haz_cache/

clean.rs

//! 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.

use std::path::{Path, PathBuf};

use haz_domain::settings::cache_clean::max_age::MaxAge;
use haz_domain::settings::cache_clean::max_size::MaxSize;
use haz_vfs::{EntryKind, FsError, WritableFilesystem};
use snafu::{ResultExt, Snafu};

use crate::cache::Cache;
use crate::layout;
use crate::manifest::{HashFunctionLabel, Manifest};

/// Failure modes shared by [`Cache::clear`] and [`Cache::clean`].
#[derive(Debug, Snafu)]
pub enum CleanError {
    /// Underlying filesystem error during the walk or removal.
    /// The wrapped [`FsError`] carries the specific path.
    #[snafu(display("filesystem error during cache invalidation: {source}"))]
    Io {
        /// The originating filesystem error.
        source: FsError,
    },
}

/// Composable mode flags for [`Cache::clean`] per `AUX-022`.
///
/// At least one of `soft`, `max_age`, `max_size` MUST be supplied
/// for the call to remove anything; the CLI layer enforces the
/// "must supply a mode" rule per `AUX-022`, so a [`Cache::clean`]
/// call with all-false / all-`None` mode fields is a well-defined
/// no-op (the report shows zero counts).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct CleanOptions {
    /// `CACHE-022` / `--soft`: reclaim objectively-stale state
    /// (manifest missing, unparseable, or schema-mismatched, plus
    /// orphan `.tmp-` and `.restore-` staging directories).
    pub soft: bool,
    /// `AUX-022` / `--max-age <DURATION>`: evict well-formed
    /// entries whose `created_at` is strictly older than
    /// `now_unix - max_age`. The cutoff is computed via
    /// [`u64::saturating_sub`], so a workspace clock that has not
    /// advanced past the threshold yields an empty eviction set
    /// rather than an overflow.
    pub max_age: Option<MaxAge>,
    /// `AUX-022` / `--max-size <BYTES>`: after `soft` and
    /// `max_age` have run, evict oldest-`created_at`-first
    /// well-formed survivors until the residual footprint is at
    /// or below `max_size`.
    pub max_size: Option<MaxSize>,
    /// `AUX-024` / `--dry-run`: compute the eviction set but DO
    /// NOT remove anything from disk. The returned [`CleanReport`]
    /// mirrors the non-dry-run report exactly, modulo the absence
    /// of on-disk changes.
    pub dry_run: bool,
    /// Reference "now" in Unix seconds since the epoch. Used as
    /// the right-hand side of the `AUX-023` step 4 cutoff
    /// (`now_unix - max_age`). Required to be non-zero when
    /// `max_age` is set; ignored otherwise. The injected value
    /// makes the operation deterministic under test.
    pub now_unix: u64,
}

/// Mode that accounted for evicting a given entry per `AUX-024`.
///
/// When more than one mode would match the same entry, the
/// highest-priority mode wins (in this declaration order).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EvictionMode {
    /// `CACHE-022` `--soft` pass: schema-stale or incomplete
    /// entry.
    Soft,
    /// `AUX-023` `--max-age` pass: well-formed but too old.
    MaxAge,
    /// `AUX-023` `--max-size` pass: well-formed but oldest among
    /// survivors of the previous passes when the residual
    /// footprint exceeded the bound.
    MaxSize,
}

/// Per-entry eviction detail surfaced for `AUX-024` dry-run
/// rendering.
///
/// One instance per evicted entry; the CLI displays the list
/// only under `--dry-run` per `AUX-024`, but the cache layer
/// always populates it (the cost is one `Vec` allocation of
/// modest size, and the audit-friendliness is worth it).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EvictedEntry {
    /// First eight hex characters of the entry's cache key, per
    /// `AUX-024` ("first 8 hex characters suffice for
    /// human-readable output"). Sourced from the entry
    /// directory's basename when the manifest is unparseable.
    pub key_hex_prefix: String,
    /// Manifest's `created_at_unix` field when available; zero
    /// when the manifest is missing or unparseable.
    pub created_at_unix: u64,
    /// Manifest-declared footprint of the entry (`stdout_len +
    /// stderr_len + sum(outputs[].size)`). Zero when the manifest
    /// is unavailable.
    pub footprint: u64,
    /// Priority mode that accounted for this entry's eviction.
    pub matched_mode: EvictionMode,
}

/// Outcome of [`Cache::clean`] per `AUX-024`.
///
/// All counts are zero on an absent cache root. Per-mode counts
/// follow the `AUX-024` priority rule (`soft` > `max_age` >
/// `max_size`): an entry never contributes to more than one
/// per-mode counter.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct CleanReport {
    /// `AUX-024` step 1: total number of entry directories the
    /// walk looked at (well-formed + corrupt). Excludes
    /// `.tmp-`/`.restore-` reclaimables.
    pub inspected: u64,
    /// `AUX-024` step 2: entries evicted under the `--soft` mode.
    pub evicted_by_soft: u64,
    /// `AUX-024` step 2: entries evicted under the `--max-age`
    /// mode.
    pub evicted_by_max_age: u64,
    /// `AUX-024` step 2: entries evicted under the `--max-size`
    /// mode.
    pub evicted_by_max_size: u64,
    /// `CACHE-022`: `.tmp-<key>-<random>` directories reclaimed.
    /// Always zero when `soft` is false.
    pub removed_tmp_dirs: u64,
    /// `CACHE-022`: `.restore-<key>-<random>` directories
    /// reclaimed. Always zero when `soft` is false.
    pub removed_restore_dirs: u64,
    /// `AUX-024` step 3: total bytes reclaimed (or projected
    /// under `--dry-run`). Sums each evicted entry's
    /// manifest-declared footprint; entries with no parseable
    /// manifest contribute zero. `.tmp-`/`.restore-` reclamations
    /// contribute zero.
    pub bytes_reclaimed: u64,
    /// One detail per evicted entry per `AUX-024`'s dry-run
    /// requirement (always populated regardless of `dry_run`).
    /// Sorted by `(matched_mode priority, created_at, key)` for
    /// determinism.
    pub evicted_entries: Vec<EvictedEntry>,
}

impl<Fs: WritableFilesystem> Cache<Fs> {
    /// 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 clear(&self) -> Result<(), CleanError> {
        match self.fs().remove_dir_all(self.cache_root()) {
            Ok(()) | Err(FsError::NotFound { .. }) => Ok(()),
            Err(e) => Err(CleanError::Io { source: e }),
        }
    }

    /// 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.
    pub fn clean(&self, opts: &CleanOptions) -> Result<CleanReport, CleanError> {
        let Some(enumerated) = self.enumerate_for_clean()? else {
            return Ok(CleanReport::default());
        };
        let CleanEnumeration {
            well_formed,
            corrupt,
            tmp_paths,
            restore_paths,
        } = enumerated;

        let mut report = CleanReport {
            inspected: (well_formed.len() + corrupt.len()) as u64,
            ..CleanReport::default()
        };

        let mut plan: Vec<PlannedEviction> = Vec::new();
        apply_soft_pass(opts, corrupt, &mut plan, &mut report);
        let survivors = apply_max_age_pass(opts, well_formed, &mut plan, &mut report);
        apply_max_size_pass(opts, survivors, &mut plan, &mut report);

        if !opts.dry_run {
            for planned in &plan {
                self.fs().remove_dir_all(&planned.path).context(IoSnafu)?;
            }
        }
        report.bytes_reclaimed = plan.iter().map(|p| p.detail.footprint).sum();

        if opts.soft {
            report.removed_tmp_dirs = tmp_paths.len() as u64;
            report.removed_restore_dirs = restore_paths.len() as u64;
            if !opts.dry_run {
                for p in &tmp_paths {
                    self.fs().remove_dir_all(p).context(IoSnafu)?;
                }
                for p in &restore_paths {
                    self.fs().remove_dir_all(p).context(IoSnafu)?;
                }
            }
        }

        report.evicted_entries = finalize_evicted_entries(plan);
        Ok(report)
    }

    fn enumerate_for_clean(&self) -> Result<Option<CleanEnumeration>, CleanError> {
        let cache_entries = match self.fs().read_dir(self.cache_root()) {
            Ok(es) => es,
            Err(FsError::NotFound { .. }) => return Ok(None),
            Err(e) => return Err(CleanError::Io { source: e }),
        };
        let mut e = CleanEnumeration::default();
        for cache_entry in cache_entries {
            let name = cache_entry
                .path
                .file_name()
                .map(|n| n.to_string_lossy().into_owned())
                .unwrap_or_default();

            if name.starts_with(".restore-") {
                e.restore_paths.push(cache_entry.path);
                continue;
            }
            if cache_entry.metadata.kind != EntryKind::Dir {
                continue;
            }
            self.clean_classify_shard(
                &cache_entry.path,
                &mut e.well_formed,
                &mut e.corrupt,
                &mut e.tmp_paths,
            )?;
        }
        Ok(Some(e))
    }

    fn clean_classify_shard(
        &self,
        shard_dir: &Path,
        well_formed: &mut Vec<EntryRecord>,
        corrupt: &mut Vec<EntryRecord>,
        tmp_paths: &mut Vec<PathBuf>,
    ) -> Result<(), CleanError> {
        let shard_entries = self.fs().read_dir(shard_dir).context(IoSnafu)?;
        for shard_entry in shard_entries {
            let sname = shard_entry
                .path
                .file_name()
                .map(|n| n.to_string_lossy().into_owned())
                .unwrap_or_default();

            if sname.starts_with(".tmp-") {
                tmp_paths.push(shard_entry.path);
                continue;
            }

            if shard_entry.metadata.kind != EntryKind::Dir {
                continue;
            }

            self.clean_classify_entry(&shard_entry.path, &sname, well_formed, corrupt)?;
        }
        Ok(())
    }

    fn clean_classify_entry(
        &self,
        entry_dir: &Path,
        basename: &str,
        well_formed: &mut Vec<EntryRecord>,
        corrupt: &mut Vec<EntryRecord>,
    ) -> Result<(), CleanError> {
        let key_hex_prefix: String = basename.chars().take(8).collect();
        let manifest_path = entry_dir.join(layout::MANIFEST_FILE_NAME);
        let bytes = match self.fs().read(&manifest_path) {
            Ok(b) => b,
            Err(FsError::NotFound { .. } | FsError::NotAFile { .. }) => {
                corrupt.push(EntryRecord {
                    path: entry_dir.to_path_buf(),
                    key_hex_prefix,
                    created_at_unix: 0,
                    footprint: 0,
                });
                return Ok(());
            }
            Err(e) => return Err(CleanError::Io { source: e }),
        };
        let Ok(manifest) = Manifest::from_json(&bytes) else {
            corrupt.push(EntryRecord {
                path: entry_dir.to_path_buf(),
                key_hex_prefix,
                created_at_unix: 0,
                footprint: 0,
            });
            return Ok(());
        };
        let chapter_ok = manifest.current_chapter_revision_matches();
        let hash_ok = HashFunctionLabel::from(self.hash_algo()) == manifest.hash_function;
        let footprint = manifest_footprint(&manifest);
        let record = EntryRecord {
            path: entry_dir.to_path_buf(),
            key_hex_prefix,
            created_at_unix: manifest.created_at_unix,
            footprint,
        };
        if chapter_ok && hash_ok {
            well_formed.push(record);
        } else {
            corrupt.push(record);
        }
        Ok(())
    }
}

struct EntryRecord {
    path: PathBuf,
    key_hex_prefix: String,
    created_at_unix: u64,
    footprint: u64,
}

struct PlannedEviction {
    path: PathBuf,
    detail: EvictedEntry,
}

#[derive(Default)]
struct CleanEnumeration {
    well_formed: Vec<EntryRecord>,
    corrupt: Vec<EntryRecord>,
    tmp_paths: Vec<PathBuf>,
    restore_paths: Vec<PathBuf>,
}

fn apply_soft_pass(
    opts: &CleanOptions,
    corrupt: Vec<EntryRecord>,
    plan: &mut Vec<PlannedEviction>,
    report: &mut CleanReport,
) {
    if !opts.soft {
        return;
    }
    let soft_count = corrupt.len() as u64;
    for c in corrupt {
        plan.push(PlannedEviction {
            path: c.path,
            detail: EvictedEntry {
                key_hex_prefix: c.key_hex_prefix,
                created_at_unix: c.created_at_unix,
                footprint: c.footprint,
                matched_mode: EvictionMode::Soft,
            },
        });
    }
    report.evicted_by_soft = soft_count;
}

fn apply_max_age_pass(
    opts: &CleanOptions,
    well_formed: Vec<EntryRecord>,
    plan: &mut Vec<PlannedEviction>,
    report: &mut CleanReport,
) -> Vec<EntryRecord> {
    let Some(max_age) = opts.max_age else {
        return well_formed;
    };
    let cutoff = opts
        .now_unix
        .saturating_sub(max_age.as_duration().as_secs());
    let mut survivors: Vec<EntryRecord> = Vec::with_capacity(well_formed.len());
    let mut evicted: u64 = 0;
    for wf in well_formed {
        if wf.created_at_unix < cutoff {
            plan.push(PlannedEviction {
                path: wf.path.clone(),
                detail: EvictedEntry {
                    key_hex_prefix: wf.key_hex_prefix.clone(),
                    created_at_unix: wf.created_at_unix,
                    footprint: wf.footprint,
                    matched_mode: EvictionMode::MaxAge,
                },
            });
            evicted += 1;
        } else {
            survivors.push(wf);
        }
    }
    report.evicted_by_max_age = evicted;
    survivors
}

fn apply_max_size_pass(
    opts: &CleanOptions,
    mut survivors: Vec<EntryRecord>,
    plan: &mut Vec<PlannedEviction>,
    report: &mut CleanReport,
) {
    let Some(max_size) = opts.max_size else {
        return;
    };
    let limit = max_size.as_bytes();
    let total: u64 = survivors.iter().map(|e| e.footprint).sum();
    if total <= limit {
        return;
    }
    survivors.sort_by(|a, b| {
        a.created_at_unix
            .cmp(&b.created_at_unix)
            .then_with(|| a.key_hex_prefix.cmp(&b.key_hex_prefix))
    });
    let mut remaining = total;
    let mut evicted: u64 = 0;
    for wf in &survivors {
        if remaining <= limit {
            break;
        }
        plan.push(PlannedEviction {
            path: wf.path.clone(),
            detail: EvictedEntry {
                key_hex_prefix: wf.key_hex_prefix.clone(),
                created_at_unix: wf.created_at_unix,
                footprint: wf.footprint,
                matched_mode: EvictionMode::MaxSize,
            },
        });
        remaining = remaining.saturating_sub(wf.footprint);
        evicted += 1;
    }
    report.evicted_by_max_size = evicted;
}

fn finalize_evicted_entries(plan: Vec<PlannedEviction>) -> Vec<EvictedEntry> {
    let mut details: Vec<EvictedEntry> = plan.into_iter().map(|p| p.detail).collect();
    details.sort_by(|a, b| {
        mode_rank(a.matched_mode)
            .cmp(&mode_rank(b.matched_mode))
            .then(a.created_at_unix.cmp(&b.created_at_unix))
            .then_with(|| a.key_hex_prefix.cmp(&b.key_hex_prefix))
    });
    details
}

fn manifest_footprint(m: &Manifest) -> u64 {
    let mut total = m.stdout_len.saturating_add(m.stderr_len);
    for o in &m.outputs {
        total = total.saturating_add(o.size);
    }
    total
}

const fn mode_rank(m: EvictionMode) -> u8 {
    match m {
        EvictionMode::Soft => 0,
        EvictionMode::MaxAge => 1,
        EvictionMode::MaxSize => 2,
    }
}

#[cfg(test)]
mod tests {
    use std::path::Path;

    use haz_domain::path::CanonicalPath;
    use haz_domain::settings::cache::HashAlgo;
    use haz_domain::settings::cache_clean::max_age::MaxAge;
    use haz_domain::settings::cache_clean::max_size::MaxSize;
    use haz_vfs::{Filesystem, MemFilesystem, WritableFilesystem};

    use crate::cache::Cache;
    use crate::clean::{CleanOptions, CleanReport, EvictionMode};
    use crate::key::CacheKey;
    use crate::key::prefix::CHAPTER_REVISION;
    use crate::layout;
    use crate::manifest::{HashFunctionLabel, Manifest, OutputBlob};
    use crate::store::{StoreInputs, StoredOutput};

    fn cp(s: &str) -> CanonicalPath {
        CanonicalPath::parse_workspace_absolute(s)
            .expect("test helper expects a valid workspace-absolute path")
    }

    const WORKSPACE_ROOT: &str = "/ws";

    fn make_cache(fs: MemFilesystem, algo: HashAlgo) -> Cache<MemFilesystem> {
        Cache::new(fs, Path::new(WORKSPACE_ROOT), algo)
    }

    fn key_with_first_byte(first: u8) -> CacheKey {
        let mut bytes = [0u8; 32];
        bytes[0] = first;
        CacheKey::from_bytes(bytes)
    }

    fn store_entry_at(
        cache: &Cache<MemFilesystem>,
        key: &CacheKey,
        rel: &str,
        bytes: &[u8],
        created_at_unix: u64,
    ) {
        let target = Path::new(WORKSPACE_ROOT).join(rel);
        let anchored = format!("/{rel}");
        cache.fs().create_dir_all(target.parent().unwrap()).unwrap();
        cache.fs().write_file(&target, bytes).unwrap();
        let outs = [StoredOutput {
            workspace_absolute_path: &anchored,
            on_disk_path: &target,
            mode: 0o644,
        }];
        cache
            .store(
                key,
                &StoreInputs {
                    outputs: &outs,
                    stdout: b"",
                    stderr: b"",
                    created_at_unix,
                },
            )
            .unwrap();
    }

    fn store_a_valid_entry(cache: &Cache<MemFilesystem>, key: &CacheKey, rel: &str, bytes: &[u8]) {
        store_entry_at(cache, key, rel, bytes, 0);
    }

    fn write_manifest_to_entry(cache: &Cache<MemFilesystem>, key: &CacheKey, manifest: &Manifest) {
        cache
            .fs()
            .create_dir_all(&layout::entry_dir(cache.cache_root(), key))
            .unwrap();
        cache
            .fs()
            .write_file(
                &layout::manifest_path(cache.cache_root(), key),
                &manifest.to_json_bytes(),
            )
            .unwrap();
    }

    fn soft_only() -> CleanOptions {
        CleanOptions {
            soft: true,
            ..Default::default()
        }
    }

    // ---- clear ----

    #[test]
    fn cache_021_clear_empties_a_populated_cache() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        store_a_valid_entry(&cache, &key, "proj/out", b"x");

        assert!(cache.lookup(&key).is_some(), "precondition: entry present");
        cache.clear().unwrap();
        assert!(
            cache.lookup(&key).is_none(),
            "lookup must be a miss after clear"
        );
    }

    #[test]
    fn cache_021_clear_on_fresh_cache_is_a_noop_not_an_error() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        cache.clear().unwrap();
    }

    #[test]
    fn cache_021_clear_does_not_touch_files_outside_cache_root() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        fs.add_file("/ws/unrelated.txt", b"keep me".to_vec())
            .unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        store_a_valid_entry(&cache, &key, "proj/out", b"x");

        cache.clear().unwrap();
        assert_eq!(
            cache.fs().read(Path::new("/ws/unrelated.txt")).unwrap(),
            b"keep me"
        );
    }

    // ---- clean: no-op cases ----

    #[test]
    fn cache_022_clean_soft_on_fresh_cache_is_a_noop_with_zero_counts() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report, CleanReport::default());
    }

    #[test]
    fn aux_022_clean_with_no_modes_is_a_noop_on_a_populated_cache() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        store_a_valid_entry(&cache, &key, "proj/out", b"x");

        let report = cache.clean(&CleanOptions::default()).unwrap();
        assert_eq!(report.evicted_by_soft, 0);
        assert_eq!(report.evicted_by_max_age, 0);
        assert_eq!(report.evicted_by_max_size, 0);
        assert_eq!(report.removed_tmp_dirs, 0);
        assert_eq!(report.removed_restore_dirs, 0);
        assert_eq!(report.inspected, 1);
        assert!(cache.lookup(&key).is_some());
    }

    #[test]
    fn cache_022_clean_soft_keeps_a_valid_entry_intact() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        store_a_valid_entry(&cache, &key, "proj/out", b"x");

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 0);
        assert!(cache.lookup(&key).is_some());
    }

    // ---- clean --soft: schema mismatch ----

    #[test]
    fn cache_022_clean_soft_removes_entry_with_chapter_revision_mismatch() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        let manifest = Manifest {
            chapter_revision: CHAPTER_REVISION.saturating_add(1),
            hash_function: HashFunctionLabel::Blake3,
            key,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key, &manifest);
        assert!(
            cache
                .fs()
                .metadata(&layout::entry_dir(cache.cache_root(), &key))
                .is_ok()
        );

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
        assert!(
            cache
                .fs()
                .metadata(&layout::entry_dir(cache.cache_root(), &key))
                .is_err()
        );
    }

    #[test]
    fn cache_022_clean_soft_removes_entry_with_hash_function_mismatch() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        let manifest = Manifest {
            chapter_revision: CHAPTER_REVISION,
            hash_function: HashFunctionLabel::Sha256,
            key,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key, &manifest);

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
    }

    // ---- clean --soft: incomplete entry ----

    #[test]
    fn cache_022_clean_soft_removes_entry_without_a_manifest() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        cache
            .fs()
            .create_dir_all(&layout::entry_dir(cache.cache_root(), &key))
            .unwrap();

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
    }

    #[test]
    fn cache_022_clean_soft_removes_entry_with_unparseable_manifest() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        cache
            .fs()
            .create_dir_all(&layout::entry_dir(cache.cache_root(), &key))
            .unwrap();
        cache
            .fs()
            .write_file(
                &layout::manifest_path(cache.cache_root(), &key),
                b"this is not json",
            )
            .unwrap();

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
    }

    // ---- clean --soft: tmp / restore dirs ----

    #[test]
    fn cache_022_clean_soft_removes_store_tmp_directory() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        let tmp = layout::tmp_entry_dir(cache.cache_root(), &key, "abcdef");
        cache.fs().create_dir_all(&tmp).unwrap();
        cache
            .fs()
            .write_file(&tmp.join("manifest.json"), b"partial")
            .unwrap();

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.removed_tmp_dirs, 1);
        assert!(cache.fs().metadata(&tmp).is_err());
    }

    #[test]
    fn cache_022_clean_soft_removes_restore_staging_directory() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        let staging = layout::restore_staging_dir(cache.cache_root(), &key, "feedface");
        cache.fs().create_dir_all(&staging).unwrap();
        cache
            .fs()
            .write_file(&staging.join("00000000"), b"leftover")
            .unwrap();

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.removed_restore_dirs, 1);
        assert!(cache.fs().metadata(&staging).is_err());
    }

    // ---- clean --soft: mixed state ----

    #[test]
    fn cache_022_clean_soft_is_selective_when_mixed_state_is_present() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_good = key_with_first_byte(0xAB);
        store_a_valid_entry(&cache, &key_good, "proj/out", b"x");

        let key_stale = key_with_first_byte(0xCD);
        let stale_manifest = Manifest {
            chapter_revision: CHAPTER_REVISION,
            hash_function: HashFunctionLabel::Sha256,
            key: key_stale,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key_stale, &stale_manifest);

        let key_tmp = key_with_first_byte(0xEF);
        let tmp = layout::tmp_entry_dir(cache.cache_root(), &key_tmp, "rnd1");
        cache.fs().create_dir_all(&tmp).unwrap();

        let key_restore = key_with_first_byte(0x12);
        let staging = layout::restore_staging_dir(cache.cache_root(), &key_restore, "rnd2");
        cache.fs().create_dir_all(&staging).unwrap();

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
        assert_eq!(report.removed_tmp_dirs, 1);
        assert_eq!(report.removed_restore_dirs, 1);
        assert!(cache.lookup(&key_good).is_some());
    }

    #[test]
    fn cache_022_clean_soft_does_not_touch_files_outside_cache_root() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        fs.add_file("/ws/sibling.txt", b"don't touch".to_vec())
            .unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);
        cache
            .fs()
            .create_dir_all(&layout::entry_dir(cache.cache_root(), &key))
            .unwrap();
        cache.clean(&soft_only()).unwrap();
        assert_eq!(
            cache.fs().read(Path::new("/ws/sibling.txt")).unwrap(),
            b"don't touch"
        );
    }

    #[test]
    fn cache_022_clean_soft_does_not_inspect_blob_contents() {
        // `CACHE-022` only checks `chapter_revision`/
        // `hash_function` and manifest presence/parseability. A
        // blob-content mismatch is a lookup-time concern, not a
        // clean-soft concern.
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);
        let key = key_with_first_byte(0xAB);

        let manifest = Manifest {
            chapter_revision: CHAPTER_REVISION,
            hash_function: HashFunctionLabel::Blake3,
            key,
            outputs: vec![OutputBlob {
                workspace_absolute_path: cp("/proj/out"),
                content_hash: [0xAAu8; 32],
                size: 42,
                mode: 0o644,
            }],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key, &manifest);

        let report = cache.clean(&soft_only()).unwrap();
        assert_eq!(report.evicted_by_soft, 0);
        assert!(
            cache
                .fs()
                .metadata(&layout::entry_dir(cache.cache_root(), &key))
                .is_ok()
        );
    }

    // ---- clean --max-age ----

    #[test]
    fn aux_023_clean_max_age_evicts_entries_strictly_older_than_cutoff() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_old = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key_old, "proj/old", b"x", 100);
        let key_new = key_with_first_byte(0xBB);
        store_entry_at(&cache, &key_new, "proj/new", b"y", 260);

        let opts = CleanOptions {
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_age, 1);
        assert_eq!(report.evicted_by_soft, 0);
        assert_eq!(report.evicted_by_max_size, 0);
        assert!(cache.lookup(&key_old).is_none());
        assert!(cache.lookup(&key_new).is_some());
    }

    #[test]
    fn aux_023_clean_max_age_keeps_entry_at_exactly_cutoff() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key, "proj/x", b"x", 100);

        let opts = CleanOptions {
            max_age: Some(MaxAge::parse("100s").unwrap()),
            now_unix: 200,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_age, 0);
        assert!(cache.lookup(&key).is_some());
    }

    #[test]
    fn aux_023_clean_max_age_ignores_corrupt_entries() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_corrupt = key_with_first_byte(0xCC);
        let m = Manifest {
            chapter_revision: CHAPTER_REVISION,
            hash_function: HashFunctionLabel::Sha256,
            key: key_corrupt,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key_corrupt, &m);

        let key_stale = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key_stale, "proj/x", b"x", 100);

        let opts = CleanOptions {
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_age, 1);
        assert_eq!(report.evicted_by_soft, 0);
        assert!(
            cache
                .fs()
                .metadata(&layout::entry_dir(cache.cache_root(), &key_corrupt))
                .is_ok()
        );
        assert!(cache.lookup(&key_stale).is_none());
    }

    // ---- clean --max-size ----

    #[test]
    fn aux_023_clean_max_size_is_noop_when_under_limit() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key, "proj/x", b"hello", 100);

        let opts = CleanOptions {
            max_size: Some(MaxSize::parse("1KB").unwrap()),
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_size, 0);
        assert!(cache.lookup(&key).is_some());
    }

    #[test]
    fn aux_023_clean_max_size_evicts_oldest_first_until_at_or_below_limit() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let bytes = b"0123456789"; // 10 bytes per entry footprint
        let key_old = key_with_first_byte(0x11);
        let key_mid = key_with_first_byte(0x22);
        let key_new = key_with_first_byte(0x33);
        store_entry_at(&cache, &key_old, "proj/a", bytes, 100);
        store_entry_at(&cache, &key_mid, "proj/b", bytes, 200);
        store_entry_at(&cache, &key_new, "proj/c", bytes, 300);

        // Total 30 bytes; limit 15. Evict oldest until <= 15.
        let opts = CleanOptions {
            max_size: Some(MaxSize::parse("15").unwrap()),
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_size, 2);
        assert!(cache.lookup(&key_old).is_none());
        assert!(cache.lookup(&key_mid).is_none());
        assert!(cache.lookup(&key_new).is_some());
        assert_eq!(report.bytes_reclaimed, 20);
    }

    #[test]
    fn aux_023_clean_max_size_zero_evicts_every_well_formed_entry() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key, "proj/x", b"x", 100);

        let opts = CleanOptions {
            max_size: Some(MaxSize::parse("0").unwrap()),
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_size, 1);
        assert!(cache.lookup(&key).is_none());
    }

    // ---- clean: mode composition ----

    #[test]
    fn aux_023_clean_soft_and_max_age_count_separately_per_priority() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_corrupt = key_with_first_byte(0xCC);
        let m = Manifest {
            chapter_revision: CHAPTER_REVISION.saturating_add(1),
            hash_function: HashFunctionLabel::Blake3,
            key: key_corrupt,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key_corrupt, &m);

        let key_stale = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key_stale, "proj/x", b"x", 100);

        let opts = CleanOptions {
            soft: true,
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_soft, 1);
        assert_eq!(report.evicted_by_max_age, 1);
        assert_eq!(report.inspected, 2);
    }

    #[test]
    fn aux_023_clean_evicted_entries_sorted_by_mode_then_created_at() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        // Two well-formed entries that both fall under max-age.
        let key_a = key_with_first_byte(0x11);
        let key_b = key_with_first_byte(0x22);
        store_entry_at(&cache, &key_a, "proj/a", b"x", 100);
        store_entry_at(&cache, &key_b, "proj/b", b"y", 200);

        // One corrupt entry under --soft.
        let key_corrupt = key_with_first_byte(0xCC);
        let stale = Manifest {
            chapter_revision: CHAPTER_REVISION.saturating_add(1),
            hash_function: HashFunctionLabel::Blake3,
            key: key_corrupt,
            outputs: vec![],
            stdout_len: 0,
            stderr_len: 0,
            stdout_hash: [0u8; 32],
            stderr_hash: [0u8; 32],
            exit_status: 0,
            created_at_unix: 0,
        };
        write_manifest_to_entry(&cache, &key_corrupt, &stale);

        let opts = CleanOptions {
            soft: true,
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_entries.len(), 3);
        assert_eq!(report.evicted_entries[0].matched_mode, EvictionMode::Soft);
        assert_eq!(report.evicted_entries[1].matched_mode, EvictionMode::MaxAge);
        assert_eq!(
            report.evicted_entries[1].created_at_unix, 100,
            "older max-age entry sorts before newer one"
        );
        assert_eq!(report.evicted_entries[2].matched_mode, EvictionMode::MaxAge);
        assert_eq!(report.evicted_entries[2].created_at_unix, 200);
    }

    // ---- clean: dry-run ----

    #[test]
    fn aux_023_clean_dry_run_does_not_modify_disk() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key = key_with_first_byte(0xAA);
        store_entry_at(&cache, &key, "proj/x", b"x", 100);

        let opts = CleanOptions {
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            dry_run: true,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_age, 1);
        assert_eq!(report.evicted_entries.len(), 1);
        assert_eq!(report.evicted_entries[0].matched_mode, EvictionMode::MaxAge);
        assert!(
            cache.lookup(&key).is_some(),
            "dry-run must leave the entry on disk"
        );
    }

    #[test]
    fn aux_023_clean_dry_run_under_soft_keeps_tmp_and_restore_dirs() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_tmp = key_with_first_byte(0xEF);
        let tmp = layout::tmp_entry_dir(cache.cache_root(), &key_tmp, "rnd1");
        cache.fs().create_dir_all(&tmp).unwrap();

        let key_restore = key_with_first_byte(0x12);
        let staging = layout::restore_staging_dir(cache.cache_root(), &key_restore, "rnd2");
        cache.fs().create_dir_all(&staging).unwrap();

        let opts = CleanOptions {
            soft: true,
            dry_run: true,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.removed_tmp_dirs, 1);
        assert_eq!(report.removed_restore_dirs, 1);
        assert!(cache.fs().metadata(&tmp).is_ok());
        assert!(cache.fs().metadata(&staging).is_ok());
    }

    #[test]
    fn aux_023_clean_bytes_reclaimed_sums_evicted_footprints() {
        let mut fs = MemFilesystem::new();
        fs.add_dir("/ws").unwrap();
        let cache = make_cache(fs, HashAlgo::Blake3);

        let key_a = key_with_first_byte(0x11);
        store_entry_at(&cache, &key_a, "proj/a", b"hello", 100); // 5 bytes
        let key_b = key_with_first_byte(0x22);
        store_entry_at(&cache, &key_b, "proj/b", b"world!", 200); // 6 bytes

        let opts = CleanOptions {
            max_age: Some(MaxAge::parse("50s").unwrap()),
            now_unix: 300,
            ..Default::default()
        };
        let report = cache.clean(&opts).unwrap();
        assert_eq!(report.evicted_by_max_age, 2);
        assert_eq!(report.bytes_reclaimed, 11);
    }
}