Module clean 

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

Two entry points:

• Cache::clear is the unconditional reset behind haz cache clear: it removes the entire cache root in a single recursive call. Subsequent lookups against the same workspace are misses until new entries are stored.
• Cache::clean is the composable selective reclamation behind haz cache clean. It accepts a CleanOptions mode set and applies the modes in spec-mandated priority order:
  1. soft (CACHE-022): reclaim every objectively stale artefact, entry directories with a missing, unparseable, or schema-mismatched manifest plus .tmp-<key>-<random> store-time directories and .restore-<key>-<random> restore-time staging directories.
  2. max_age (AUX-023 step 4): evict every remaining well-formed entry whose created_at is strictly older than now_unix - max_age.
  3. max_size (AUX-023 step 5): if the well-formed survivors’ footprint exceeds max_size, evict oldest-created_at-first until the residual footprint is at or below max_size.
  4. dry_run (AUX-024): compute the eviction set but make no on-disk changes.

Per AUX-024, when more than one mode would name the same entry, the entry counts in the highest-priority mode (soft > max_age > max_size). CleanReport::evicted_entries carries one EvictedEntry per evicted entry, labelled with its priority mode.

Both methods are idempotent on an absent cache root: calling them when <workspace>/.haz/cache does not exist is a no-op, not an error.

Structs

CleanOptions

Composable mode flags for Cache::clean per AUX-022.

CleanReport

Outcome of Cache::clean per AUX-024.

EvictedEntry

Per-entry eviction detail surfaced for AUX-024 dry-run rendering.

Enums

CleanError

Failure modes shared by Cache::clear and Cache::clean.

EvictionMode

Mode that accounted for evicting a given entry per AUX-024.