Crate gruel_cache 

On-disk content-addressed cache for incremental compilation (ADR-0074).

This crate provides the storage and fingerprinting primitives the compiler driver uses to skip work for files (and per-function bitcode) whose inputs haven’t changed since the last build. It does not know about Gruel source, AST, or AIR — those are serialized by their owning crates and handed to this crate as opaque byte blobs keyed by CacheKeys.

Architecture:

• CacheStore is a content-addressed on-disk store rooted at some cache directory (typically target/gruel-cache/). All writes are atomic (write to tmp/, then rename). All filenames are content-hashes (BLAKE3, hex-encoded) so concurrent invocations cannot corrupt each other.
• Hasher / CacheKey wrap BLAKE3 to give the rest of the compiler a typed-key surface instead of raw byte slices.
• [compiler_fp] hashes the running compiler binary, memoized across invocations by (path, mtime, size). This is the load-bearing fingerprint that invalidates the entire cache when the compiler itself changes — including local cargo build cycles during compiler dev.

See ADR-0074 for the full design rationale.

Structs

CacheKey

A 32-byte BLAKE3 hash used as a cache identifier.

CacheStats

Aggregate per-kind statistics for gruel cache stats.

CacheStore

Handle to an open cache directory. Cheap to clone if needed (just holds a PathBuf); creating a new one with CacheStore::open is also cheap once the version check has run.

CachedAirOutput

Envelope around a per-file AIR + interner snapshot, ready for bincode serialization to the AIR cache.

CachedParseOutput

Envelope around a parsed file’s AST + interner snapshot, ready for bincode serialization to the parse cache.

CachedRirOutput

Envelope around a per-file RIR + interner snapshot, ready for bincode serialization to the RIR cache.

Hasher

Incremental BLAKE3 hasher.

InternerSnapshot

A per-file interner snapshot — strings[i] is the string value of the Spur whose raw key equals i. Indexed by Key::into_usize, which for lasso’s default Spur is NonZeroU32 minus one (i.e. the first interned string has key 0, the second has key 1, etc.).

Enums

CacheKind

Which subdirectory a cache entry belongs in. The variants correspond 1:1 to the pipeline stages that persist results.

Constants

CACHE_SCHEMA_VERSION

On-disk cache schema version. Bump when the layout of any cached blob changes in an incompatible way. The store wipes the cache directory on startup if the persisted version doesn’t match this constant.

SIG_FP_VERSION

Bumped any time the canonical encoding changes. Mixed into every sig_fp so old caches (which used a different encoding) are invalidated even if the file content matches.

Traits

RemapSpurs

Type capable of substituting cached Spur values via a remap table.

Functions

blake3_bytes

Compute a BLAKE3 hash of a single byte slice.

compiler_fingerprint

Compute or retrieve the cached hash of the compiler binary at binary_path. Memoization lives under memo_dir; callers typically pass ~/.cache/gruel/binary-hash.

compute_sig_fp

Compute sig_fp for a single file’s AST.

current_binary_path

Get the path to the currently-running executable, with sensible fallback. Used by callers who haven’t been handed an explicit binary path (the common case from the gruel CLI).