Kache saves disk in two independent places: inside the store and between the store and build trees.

Content-addressed blobs

Each output blob is named by its BLAKE3 content hash:

<cache-dir>/store/blobs/ab/abcdef...

Entries refer to blobs through metadata and the SQLite index. Identical bytes share one blob even when they came from different cache keys. Garbage collection removes a blob only after no entry needs it.

Restore methods

Kache chooses the safest available method per artifact:

1. copy-on-write clone on APFS, ReFS, btrfs, or reflink-capable XFS
2. one exclusive Unix hardlink carrier for immutable .rlib and .rmeta artifacts
3. byte copy

Executable and loadable outputs use clone or copy, never the hardlink fallback, because signing, stripping, or another consumer may modify them. Windows copies on non-CoW volumes unless the unsafe windows_hardlink option is enabled.

Reflinks have independent inodes. A later write copies changed blocks instead of modifying the store blob.

Monitor metrics

The monitor separates:

• Dedup: logical bytes avoided by content-addressed blob sharing
• Blobs: physical blob bytes in the store
• Hardlinks: Unix bytes shared through the hardlink fallback
• Scan: whether link accounting is running or complete

A zero hardlink count is normal on copy-on-write filesystems. Their sharing is reflected by filesystem allocation, not inode link count.

dup build events

A dup event is not a restore and is not the dedup metric. It means the cache key missed, the compiler ran, and all resulting blobs were already present. Repeated dups can expose noisy or over-specific key inputs.