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
• Scan: whether project target discovery is running or complete

Use kache gc and kache clean --dry-run for clone-reclamation estimates. The live monitor stays focused on builds, store usage, and transfers.

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.