Struct Cache 

pub struct Cache<Fs: WritableFilesystem> { /* private fields */ }

Handle to the cache tree rooted at <workspace_root>/.haz/cache, parameterised over a WritableFilesystem backend.

The bound is WritableFilesystem (not the read-only Filesystem) because all per-operation methods other than lookup mutate the tree. Carrying the stricter bound on the struct, rather than narrowing it per method, keeps the public signatures uniform.

Implementations

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn new(fs: Fs, workspace_root: &Path, hash_algo: HashAlgo) -> Self

Construct a Cache handle for the workspace rooted at workspace_root. The cache root is derived as <workspace_root>/.haz/cache via layout::cache_root.

hash_algo is the active hash function for this cache session and is used by lookup to reject entries that were written under a different algorithm (CACHE-016 step 3).

pub fn workspace_root(&self) -> &Path

The absolute path to the workspace root. Restoration (CACHE-019) needs this to map workspace-anchored /foo/bar paths recorded in the manifest into real filesystem paths.

pub fn cache_root(&self) -> &Path

The absolute path to the cache root, <workspace_root>/.haz/cache.

pub fn hash_algo(&self) -> HashAlgo

The hash function this Cache was constructed with.

pub fn fs(&self) -> &Fs

Borrow the underlying filesystem handle. Useful for tests and for callers that need to inspect cache-adjacent paths through the same backend.

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn clear(&self) -> Result<(), CleanError>

Remove every cache entry under <workspace_root>/.haz/cache, per CACHE-021.

Idempotent on an absent cache root: calling clear when the cache tree does not exist returns Ok(()), not an error. The implementation only touches paths under the cache root; the rest of the workspace is left alone.

Errors

Returns CleanError::Io wrapping the underlying FsError if the recursive removal fails for any reason other than “the cache root did not exist”.

pub fn clean(&self, opts: &CleanOptions) -> Result<CleanReport, CleanError>

Walk the cache root and reclaim every artefact named by the CleanOptions mode flags per AUX-022..AUX-027.

Eviction priority follows AUX-024 (soft > max_age > max_size); each entry contributes to exactly one per-mode count. Under dry_run, the eviction set is computed and reported but no file or directory is removed.

Idempotent on an absent cache root.

Errors

Returns CleanError::Io wrapping the underlying FsError if any filesystem operation along the walk fails. Unparseable manifests are NOT an error: those entries surface as the soft-eligible “objectively stale” case.

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn info(&self) -> Result<CacheInfoReport, CacheInfoError>

Walk the cache root and classify every entry per AUX-019.

Idempotent on an absent cache root: when <workspace_root>/.haz/cache does not exist, returns the default-zero report rather than an error.

Errors

Returns CacheInfoError::Io wrapping the underlying FsError when any filesystem read fails. Manifest parse failures and schema mismatches are NOT errors: those entries fold into the CacheInfoReport::corrupt_entries count.

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn lookup(&self, key: &CacheKey) -> Option<Manifest>

Look up the cache entry for key.

Returns Some(Manifest) on a hit (every consistency check from CACHE-016 passed), or None on any miss. Miss reasons enumerated by CACHE-016:

1. manifest file absent or unreadable;
2. manifest JSON malformed, contains unknown fields, or uses an unknown hash_function value;
3. manifest’s chapter_revision does not match crate::CHAPTER_REVISION;
4. manifest’s hash_function does not match the cache’s active haz_domain::settings::cache::HashAlgo;
5. any output blob the manifest references is missing, not a regular file, or has a size different from the manifest’s recorded size;
6. the captured stdout or stderr stream is missing, not a regular file, or has a size different from the manifest’s recorded stdout_len / stderr_len.

pub fn lookup_status( &self, key: &CacheKey, ) -> Result<CacheLookupStatus, CacheLookupError>

Introspecting variant of Self::lookup for AUX-015 step 11.

Performs the same per-entry checks as Self::lookup but discriminates the outcome into the four spec-named sub-states. Reuses the same blob / stream verification (CACHE-015 step 4 / 5), so a hit here is observationally equivalent to a hit from Self::lookup.

Errors

Returns CacheLookupError::Io wrapping the underlying FsError for filesystem errors that are NOT a “missing entry” shape (those collapse into the CacheLookupStatus::MissNoEntry / CacheLookupStatus::MissCorruptEntry variants).

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn restore( &self, manifest: &Manifest, ) -> Result<RestoredStreams, RestoreError>

Restore the cache entry described by manifest per CACHE-019.

Materialises every output declared in the manifest at its workspace-absolute path with the recorded mode and returns the captured stdout/stderr bytes. The caller MUST have just obtained manifest from Cache::lookup; the cache trusts the manifest content (paths, content hashes, sizes, modes) as truth and does not re-verify it.

On error, the staging directory under the cache root is removed regardless of which phase failed, so no transient scratch space leaks. If the error occurs after one or more targets have already been renamed onto, those targets remain published; the caller MUST treat the error as a miss and re-run the task fresh (CACHE-020 second paragraph).

Errors

Returns RestoreError::Io wrapping the underlying FsError if any filesystem operation along the phases fails.

impl<Fs: WritableFilesystem> Cache<Fs>

pub fn store( &self, key: &CacheKey, inputs: &StoreInputs<'_>, ) -> Result<(), StoreError>

Persist a successful run as a cache entry under key, per CACHE-017.

The caller MUST only invoke this for runs whose process exit status was 0 (CACHE-018); the method does not verify that, but always records exit_status = 0 in the manifest.

The entry is written atomically: a successful return means the final entry directory <shard>/<key>/ is visible with a complete manifest. A returned Err leaves at most a stray tmp directory on the shard, which future clean --soft invocations (CACHE-022) will reclaim.

Errors

Returns StoreError::Io wrapping the underlying FsError if any filesystem operation along the phases fails.

Trait Implementations

impl<Fs: Clone + WritableFilesystem> Clone for Cache<Fs>

fn clone(&self) -> Cache<Fs>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Fs: Debug + WritableFilesystem> Debug for Cache<Fs>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.