gruel_cache/lib.rs
1//! On-disk content-addressed cache for incremental compilation (ADR-0074).
2//!
3//! This crate provides the storage and fingerprinting primitives the compiler
4//! driver uses to skip work for files (and per-function bitcode) whose inputs
5//! haven't changed since the last build. It does **not** know about Gruel
6//! source, AST, or AIR — those are serialized by their owning crates and
7//! handed to this crate as opaque byte blobs keyed by [`CacheKey`]s.
8//!
9//! Architecture:
10//!
11//! - [`CacheStore`] is a content-addressed on-disk store rooted at some cache
12//! directory (typically `target/gruel-cache/`). All writes are atomic
13//! (write to `tmp/`, then `rename`). All filenames are content-hashes
14//! (BLAKE3, hex-encoded) so concurrent invocations cannot corrupt each
15//! other.
16//! - [`Hasher`] / [`CacheKey`] wrap BLAKE3 to give the rest of the compiler
17//! a typed-key surface instead of raw byte slices.
18//! - [`compiler_fp`] hashes the running compiler binary, memoized across
19//! invocations by `(path, mtime, size)`. This is the load-bearing
20//! fingerprint that invalidates the entire cache when the compiler itself
21//! changes — including local `cargo build` cycles during compiler dev.
22//!
23//! See ADR-0074 for the full design rationale.
24
25mod compiler_fp;
26mod fingerprint;
27mod remap;
28mod signature;
29mod store;
30mod wire;
31mod wire_air;
32
33pub use compiler_fp::{compiler_fingerprint, current_binary_path};
34pub use fingerprint::{CacheKey, Hasher, blake3_bytes};
35pub use remap::RemapSpurs;
36pub use signature::{SIG_FP_VERSION, compute_sig_fp};
37pub use store::{CacheKind, CacheStats, CacheStore};
38pub use wire::{CachedParseOutput, CachedRirOutput, InternerSnapshot};
39pub use wire_air::CachedAirOutput;
40
41/// On-disk cache schema version. Bump when the layout of any cached blob
42/// changes in an incompatible way. The store wipes the cache directory on
43/// startup if the persisted version doesn't match this constant.
44///
45/// History:
46/// - 1: initial layout (parse, air, llvm-ir).
47/// - 2: ADR-0088 added `directives` + `is_unchecked` to `MethodSig` and
48/// `directives_start`/`directives_len` to `InterfaceMethodSig` RIR;
49/// `MethodSig::remap_spurs` had to learn to walk the new directive
50/// list, and signature-fp encoding now includes the unchecked flag.
51pub const CACHE_SCHEMA_VERSION: u32 = 2;