Module sparse_cache 

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

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

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

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 trusting the bitmap. 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>.bitmap. 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

Load a cached delivery for (tree_hash, filter_hash). Returns Ok(None) for a fresh repo / cache miss; Err(_) only for I/O or wire failures.

load_or_build

Cache-aware front end for the build_sparse → verify_sparse → store pipeline shared by mkit checkout --sparse and mkit clone --sparse (SPEC-SPARSE-CHECKOUT §8).

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.