Module sparse_cache 

On-disk witness cache for verified sparse-checkout deliveries.

Spec: docs/specs/SPEC-SPARSE-CHECKOUT.md §6. Cache layout:

<repo-root>/.mkit/sparse/<tree-hex>.witness

One file per (tree_hash) — the per-filter binding lives inside the file body. A cache hit means “we have some verified sparse delivery for this tree”; the caller still has to cross-check the filter hash before using the witness. The file format is defined by mkit_core::sparse::encode_sparse_cache / mkit_core::sparse::decode_sparse_cache.

This module is feature-gated by sparse-checkout because it depends on the mkit_core::sparse module which is itself feature-gated.

Enums

CacheError

Errors raised by the cache I/O helpers. Wrapping the io::Error directly keeps the call sites concise — the cache is best-effort, so callers usually log-and-continue rather than blow up.

SparseBuildError

Errors from load_or_build’s fresh-build path. A cache-read failure is never one of these — it is always treated as a miss (see load_or_build’s doc).

SparseOutcome

Outcome of load_or_build: whether the on-disk cache satisfied the request or a fresh manifest had to be built.

Functions

cache_path

Compute <common dir>/sparse/<tree-hex>.witness. The directory may not exist yet; store creates it on demand. Common-dir state: the cache is keyed by tree hash, so it is shared across worktrees.

load

Read and authenticate a bounded v2 cache witness against the requested tree and filter identities. Unsupported versions, malformed and substituted entries fail.

load_or_build

Revalidate a cache witness or build it from authenticated local metadata. Unsupported filters and oversized witnesses retain the existing full-metadata restoration path. Cache failures are disposable misses.

store

Persist a verified manifest + proof to the cache. Idempotent: re-storing the same (tree_hash, manifest, proof) triple over-writes the existing bytes byte-for-byte.