Struct CacheWriter 

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

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

Wraps a CacheReader; reads against the same cache flow through Self::reader so the read-only contract of the reader’s surface is preserved.

Implementations

impl<Fs: WritableFilesystem> CacheWriter<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<CleanOutcome, CleanError>

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

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.

Best-effort per AUX-028: a shard or manifest that cannot be read during planning, and an entry that cannot be removed during eviction, are recorded in CleanOutcome::failures and skipped rather than aborting the run. The returned CleanReport counts and bytes_reclaimed reflect what actually succeeded. Idempotent on an absent cache root.

Errors

Returns CleanError::Io only when the cache root itself cannot be read, which prevents computing any eviction set. Per-item read/removal failures are NOT errors: they are collected in CleanOutcome::failures. Unparseable or missing manifests are not failures either; those entries surface as the soft-eligible “objectively stale” case.

impl<Fs: WritableFilesystem> CacheWriter<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 CacheReader::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> CacheWriter<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.

impl<Fs: WritableFilesystem> CacheWriter<Fs>

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

Construct a CacheWriter handle for the workspace rooted at workspace_root. The cache root is derived as <workspace_root>/.haz/cache via crate::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 reader(&self) -> &CacheReader<Fs>

Borrow the inner CacheReader for read-only operations (lookup, manifest introspection, info).

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 CacheWriter was constructed with.

pub fn fs(&self) -> &Fs

Borrow the underlying filesystem handle.

Trait Implementations

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

fn clone(&self) -> CacheWriter<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 CacheWriter<Fs>

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

Formats the value using the given formatter.