Crate haz_cache 

Content-addressable cache for haz task outputs, stdout, and stderr.

Implements the model defined in chapter 9 of the specification: cache-key composition (CACHE-001..009), on-disk entry layout (CACHE-010..013), lookup (CACHE-014..016), two-phase store (CACHE-017..018), restoration (CACHE-019..020), and invalidation (CACHE-021..022).

The whole machinery is engineered to satisfy the central CACHE-023 correctness claim: a cache hit MUST be observationally equivalent to a fresh run. Every other rule in chapter 9 (canonical key derivation, atomic publish, schema- mismatch invalidation, …) exists to keep that invariant.

The cache is content-addressed: a task’s identity (project name, task name) does NOT contribute to its key. Two tasks with byte-identical inputs, identical commands, and identical environments produce equal keys and MAY share a single entry on disk.

Module map

• hasher: dispatch over the two specification-recognised hash functions (BLAKE3 by default, SHA-256 by opt-in).
• key: cache-key type, schema-version prefix, and canonical serialisation of the key’s components.
• hex: lowercase-hex encoding/decoding for 32-byte digests shared by the cache key and the manifest.
• manifest: on-disk manifest format (CACHE-011), serialised as JSON.
• layout: pure path-computation helpers for the sharded entry layout (CACHE-010).
• cache: the Cache handle bound to a haz_vfs::WritableFilesystem and a workspace root.
• lookup: Cache::lookup per CACHE-014..CACHE-016.
• store: Cache::store per CACHE-017..CACHE-018.
• restore: Cache::restore per CACHE-019..CACHE-020.
• clean: Cache::clear and Cache::clean per CACHE-021..CACHE-022 and AUX-022..AUX-027.
• info: Cache::info read-only introspection per AUX-017..AUX-021.

Re-exports

pub use cache::Cache;

pub use clean::CleanError;

pub use clean::CleanOptions;

pub use clean::CleanReport;

pub use clean::EvictedEntry;

pub use clean::EvictionMode;

pub use hasher::Hasher;

pub use hex::HexError;

pub use info::CacheInfoError;

pub use info::CacheInfoReport;

pub use info::SchemaPrefix;

pub use key::CHAPTER_REVISION;

pub use key::CacheKey;

pub use key::CacheKeyBuilder;

pub use key::CacheKeyInputs;

pub use key::EnvContribution;

pub use key::InputFile;

pub use key::PredecessorStreams;

pub use key::hash_function_id;

pub use key::schema_version_prefix;

pub use lookup::CacheLookupError;

pub use lookup::CacheLookupStatus;

pub use manifest::HashFunctionLabel;

pub use manifest::Manifest;

pub use manifest::ManifestParseError;

pub use manifest::OutputBlob;

pub use restore::RestoreError;

pub use restore::RestoredStreams;

pub use store::StoreError;

pub use store::StoreInputs;

pub use store::StoredOutput;

Modules

cache

The Cache handle: a filesystem-bound view onto the cache tree at <workspace-root>/.haz/cache per crate::layout.

clean

Cache invalidation per CACHE-021 and AUX-022..AUX-027.

hasher

Hash-function dispatch.

hex

Lowercase hexadecimal encoding for 32-byte digests.

info

Read-only cache introspection per AUX-017..AUX-021.

key

Cache-key type and builder.

layout

On-disk cache-entry layout per CACHE-010, CACHE-012, and CACHE-013.

lookup

Cache::lookup per CACHE-014..CACHE-016, plus Cache::lookup_status for AUX-015 step 11.

manifest

Manifest format per CACHE-011.

restore

Cache::restore per CACHE-019 and CACHE-020.

store

Cache::store per CACHE-017 and CACHE-018.