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).
• reader: the CacheReader handle bound to a haz_vfs::Filesystem and a workspace root; read-only surface of the cache.
• writer: the CacheWriter handle bound to a haz_vfs::WritableFilesystem and a workspace root; write- side surface, composing a CacheReader for reads.
• lookup: CacheReader::lookup per CACHE-014..CACHE-016.
• store: CacheWriter::store per CACHE-017..CACHE-018.
• restore: CacheWriter::restore per CACHE-019..CACHE-020.
• clean: CacheWriter::clear and CacheWriter::clean per CACHE-021..CACHE-022 and AUX-022..AUX-027.
• info: CacheReader::info read-only introspection per AUX-017..AUX-021.

Re-exports

pub use clean::CleanError;

pub use clean::CleanFailure;

pub use clean::CleanOptions;

pub use clean::CleanOutcome;

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 reader::CacheReader;

pub use restore::RestoreError;

pub use restore::RestoredStreams;

pub use store::StoreError;

pub use store::StoreInputs;

pub use store::StoredOutput;

pub use writer::CacheWriter;

Modules

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

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

manifest

Manifest format per CACHE-011.

reader

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

restore

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

store

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

writer

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