aft/
cache_freshness.rs

1use rayon::prelude::*;
2#[cfg(debug_assertions)]
3use std::cell::Cell;
4use std::collections::BTreeMap;
5use std::fs;
6use std::path::{Path, PathBuf};
7#[cfg(debug_assertions)]
8use std::sync::atomic::{AtomicUsize, Ordering};
9use std::sync::{Mutex, OnceLock};
10use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
11
12pub const CONTENT_HASH_SIZE_CAP: u64 = 4 * 1024 * 1024;
13
14#[cfg(debug_assertions)]
15static STRICT_VERIFY_FILE_CALLS: AtomicUsize = AtomicUsize::new(0);
16#[cfg(debug_assertions)]
17thread_local! {
18    static HASH_FILE_IF_SMALL_CALLS: Cell<usize> = const { Cell::new(0) };
19}
20#[cfg(any(debug_assertions, test))]
21static WATCHED_HASH_FILE: OnceLock<Mutex<Option<(PathBuf, usize)>>> = OnceLock::new();
22
23const VERIFY_MEMO_TTL: Duration = Duration::from_secs(10 * 60);
24static VERIFY_MEMO: OnceLock<Mutex<VerifyMemo>> = OnceLock::new();
25
26#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
27pub(crate) enum VerifyArtifact {
28    Search,
29    Semantic,
30}
31
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub(crate) enum WarmVerifyPlan {
34    Skip,
35    StatFirst,
36    Strict,
37}
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub(crate) enum VerifyStrategy {
41    StatFirst,
42    Strict,
43}
44
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub(crate) struct ArtifactGeneration {
47    size: u64,
48    modified_nanos: Option<u128>,
49}
50
51#[derive(Debug, Clone)]
52struct VerifyMemoEntry {
53    verify_completed_at: Instant,
54    generation: ArtifactGeneration,
55    invalidated: bool,
56}
57
58#[derive(Default)]
59struct VerifyMemo {
60    entries: BTreeMap<(PathBuf, VerifyArtifact), VerifyMemoEntry>,
61    invalidation_tickets: BTreeMap<PathBuf, u64>,
62}
63
64#[derive(Debug, Clone, Copy, PartialEq, Eq)]
65pub struct FileFreshness {
66    pub mtime: SystemTime,
67    pub size: u64,
68    pub content_hash: blake3::Hash,
69}
70
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72pub enum FreshnessVerdict {
73    HotFresh,
74    ContentFresh {
75        new_mtime: SystemTime,
76        new_size: u64,
77    },
78    Stale,
79    Deleted,
80}
81
82pub fn hash_bytes(bytes: &[u8]) -> blake3::Hash {
83    blake3::hash(bytes)
84}
85
86pub fn hash_file_if_small(path: &Path, size: u64) -> std::io::Result<Option<blake3::Hash>> {
87    if size > CONTENT_HASH_SIZE_CAP {
88        return Ok(None);
89    }
90    #[cfg(debug_assertions)]
91    HASH_FILE_IF_SMALL_CALLS.with(|calls| calls.set(calls.get() + 1));
92    #[cfg(any(debug_assertions, test))]
93    {
94        let mut watched = WATCHED_HASH_FILE
95            .get_or_init(|| Mutex::new(None))
96            .lock()
97            .unwrap_or_else(std::sync::PoisonError::into_inner);
98        if let Some((watched_path, count)) = watched.as_mut() {
99            if watched_path == path {
100                *count += 1;
101            }
102        }
103    }
104    fs::read(path).map(|bytes| Some(hash_bytes(&bytes)))
105}
106
107pub fn metadata_matches(path: &Path, cached: &FileFreshness) -> std::io::Result<bool> {
108    let metadata = fs::metadata(path)?;
109    let new_size = metadata.len();
110    let new_mtime = metadata.modified().unwrap_or(UNIX_EPOCH);
111    Ok(new_size == cached.size && new_mtime == cached.mtime)
112}
113
114pub fn zero_hash() -> blake3::Hash {
115    blake3::Hash::from_bytes([0u8; 32])
116}
117
118pub(crate) fn artifact_generation(path: &Path) -> Option<ArtifactGeneration> {
119    let metadata = fs::metadata(path).ok()?;
120    let modified_nanos = metadata
121        .modified()
122        .ok()
123        .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok())
124        .map(|duration| duration.as_nanos());
125    Some(ArtifactGeneration {
126        size: metadata.len(),
127        modified_nanos,
128    })
129}
130
131fn verify_memo() -> &'static Mutex<VerifyMemo> {
132    VERIFY_MEMO.get_or_init(|| Mutex::new(VerifyMemo::default()))
133}
134
135pub(crate) fn warm_verify_plan(
136    root: &Path,
137    artifact: VerifyArtifact,
138    generation: Option<ArtifactGeneration>,
139) -> WarmVerifyPlan {
140    let Some(generation) = generation else {
141        return WarmVerifyPlan::Strict;
142    };
143    let memo = verify_memo()
144        .lock()
145        .unwrap_or_else(std::sync::PoisonError::into_inner);
146    let Some(entry) = memo.entries.get(&(root.to_path_buf(), artifact)) else {
147        return WarmVerifyPlan::Strict;
148    };
149    if entry.generation != generation {
150        return WarmVerifyPlan::Strict;
151    }
152    if entry.invalidated || entry.verify_completed_at.elapsed() >= VERIFY_MEMO_TTL {
153        WarmVerifyPlan::StatFirst
154    } else {
155        WarmVerifyPlan::Skip
156    }
157}
158
159pub(crate) fn capture_verify_ticket(root: &Path) -> u64 {
160    verify_memo()
161        .lock()
162        .unwrap_or_else(std::sync::PoisonError::into_inner)
163        .invalidation_tickets
164        .get(root)
165        .copied()
166        .unwrap_or(0)
167}
168
169pub(crate) fn record_verify_completed_if_unchanged(
170    root: &Path,
171    artifact: VerifyArtifact,
172    generation: Option<ArtifactGeneration>,
173    ticket: u64,
174) -> bool {
175    let Some(generation) = generation else {
176        return false;
177    };
178    let mut memo = verify_memo()
179        .lock()
180        .unwrap_or_else(std::sync::PoisonError::into_inner);
181    let current_ticket = memo.invalidation_tickets.get(root).copied().unwrap_or(0);
182    if current_ticket != ticket {
183        return false;
184    }
185    memo.entries.insert(
186        (root.to_path_buf(), artifact),
187        VerifyMemoEntry {
188            verify_completed_at: Instant::now(),
189            generation,
190            invalidated: false,
191        },
192    );
193    true
194}
195
196#[cfg(test)]
197pub(crate) fn record_verify_completed(
198    root: &Path,
199    artifact: VerifyArtifact,
200    generation: Option<ArtifactGeneration>,
201) {
202    let ticket = capture_verify_ticket(root);
203    let _ = record_verify_completed_if_unchanged(root, artifact, generation, ticket);
204}
205
206pub(crate) fn invalidate_verify_memo(root: &Path) {
207    let mut memo = verify_memo()
208        .lock()
209        .unwrap_or_else(std::sync::PoisonError::into_inner);
210    let ticket = memo
211        .invalidation_tickets
212        .entry(root.to_path_buf())
213        .or_insert(0);
214    *ticket = ticket.wrapping_add(1);
215    for ((memo_root, _), entry) in &mut memo.entries {
216        if memo_root == root {
217            entry.invalidated = true;
218        }
219    }
220}
221
222/// Forget all completed verification for a root after an interval in which its
223/// filesystem watcher was stopped. A normal watcher invalidation can use
224/// stat-first verification, but an unobserved interval must hash content because
225/// size and mtime may both have been preserved by an external writer.
226pub(crate) fn invalidate_verify_memo_strict(root: &Path) {
227    let mut memo = verify_memo()
228        .lock()
229        .unwrap_or_else(std::sync::PoisonError::into_inner);
230    let ticket = memo
231        .invalidation_tickets
232        .entry(root.to_path_buf())
233        .or_insert(0);
234    *ticket = ticket.wrapping_add(1);
235    memo.entries.retain(|(memo_root, _), _| memo_root != root);
236}
237
238pub fn collect(path: &Path) -> std::io::Result<FileFreshness> {
239    let metadata = fs::metadata(path)?;
240    let mtime = metadata.modified().unwrap_or(UNIX_EPOCH);
241    let size = metadata.len();
242    let content_hash = hash_file_if_small(path, size)?.unwrap_or_else(zero_hash);
243    Ok(FileFreshness {
244        mtime,
245        size,
246        content_hash,
247    })
248}
249
250pub fn verify_file(path: &Path, cached: &FileFreshness) -> FreshnessVerdict {
251    verify_file_inner(path, cached, false)
252}
253
254pub fn verify_file_strict(path: &Path, cached: &FileFreshness) -> FreshnessVerdict {
255    #[cfg(debug_assertions)]
256    {
257        STRICT_VERIFY_FILE_CALLS.fetch_add(1, Ordering::Relaxed);
258        strict_verify_paths_for_debug()
259            .lock()
260            .unwrap_or_else(std::sync::PoisonError::into_inner)
261            .push(path.to_path_buf());
262    }
263    verify_file_inner(path, cached, true)
264}
265
266/// Verify semantic cache file freshness in a private bounded Rayon pool.
267///
268/// Do not use the global pool here: load-time strict verification can hash every
269/// indexed file, and the semantic load/build already runs beside the bridge's
270/// single dispatch thread. Match the half-cores/cap-8 policy used by the search
271/// and callgraph cold-build pools.
272pub(crate) fn verify_files_strict_bounded<K: Send>(
273    files: Vec<(K, PathBuf, FileFreshness)>,
274) -> Vec<(K, PathBuf, FreshnessVerdict)> {
275    verify_files_bounded(files, VerifyStrategy::Strict)
276}
277
278pub(crate) fn verify_files_bounded<K: Send>(
279    files: Vec<(K, PathBuf, FileFreshness)>,
280    strategy: VerifyStrategy,
281) -> Vec<(K, PathBuf, FreshnessVerdict)> {
282    fn verify_one<K>(
283        (key, path, cached): (K, PathBuf, FileFreshness),
284        strategy: VerifyStrategy,
285    ) -> (K, PathBuf, FreshnessVerdict) {
286        let verdict = match strategy {
287            VerifyStrategy::StatFirst => verify_file(&path, &cached),
288            VerifyStrategy::Strict => verify_file_strict(&path, &cached),
289        };
290        (key, path, verdict)
291    }
292
293    if files.len() <= 1 {
294        return files
295            .into_iter()
296            .map(|file| verify_one(file, strategy))
297            .collect();
298    }
299
300    match rayon::ThreadPoolBuilder::new()
301        .num_threads(strict_verify_pool_size())
302        .thread_name(|index| format!("aft-semantic-verify-{index}"))
303        .build()
304    {
305        Ok(pool) => pool.install(|| {
306            files
307                .into_par_iter()
308                .map(|file| verify_one(file, strategy))
309                .collect()
310        }),
311        Err(_) => files
312            .into_iter()
313            .map(|file| verify_one(file, strategy))
314            .collect(),
315    }
316}
317
318fn strict_verify_pool_size() -> usize {
319    std::thread::available_parallelism()
320        .map(|parallelism| parallelism.get())
321        .unwrap_or(1)
322        .div_ceil(2)
323        .clamp(1, 8)
324}
325
326#[cfg(debug_assertions)]
327fn strict_verify_paths_for_debug() -> &'static std::sync::Mutex<Vec<PathBuf>> {
328    static STRICT_VERIFY_FILE_PATHS: OnceLock<std::sync::Mutex<Vec<PathBuf>>> = OnceLock::new();
329    STRICT_VERIFY_FILE_PATHS.get_or_init(|| std::sync::Mutex::new(Vec::new()))
330}
331
332#[cfg(debug_assertions)]
333#[doc(hidden)]
334pub fn reset_verify_file_strict_count_for_debug() {
335    STRICT_VERIFY_FILE_CALLS.store(0, Ordering::Relaxed);
336    strict_verify_paths_for_debug()
337        .lock()
338        .unwrap_or_else(std::sync::PoisonError::into_inner)
339        .clear();
340}
341
342#[cfg(debug_assertions)]
343#[doc(hidden)]
344pub fn verify_file_strict_count_for_debug() -> usize {
345    STRICT_VERIFY_FILE_CALLS.load(Ordering::Relaxed)
346}
347
348/// Strict-verification count attributed to one root. The bare process-global
349/// count is meaningless under parallel tests (any concurrent semantic or
350/// search load increments it); tests asserting "MY operation ran no strict
351/// verification" must count only paths under their own fixture root.
352#[cfg(debug_assertions)]
353#[doc(hidden)]
354pub fn verify_file_strict_count_under_for_debug(root: &Path) -> usize {
355    strict_verify_paths_for_debug()
356        .lock()
357        .unwrap_or_else(std::sync::PoisonError::into_inner)
358        .iter()
359        .filter(|path| path.starts_with(root))
360        .count()
361}
362
363#[cfg(debug_assertions)]
364#[doc(hidden)]
365pub fn reset_hash_file_if_small_count_for_debug() {
366    HASH_FILE_IF_SMALL_CALLS.with(|calls| calls.set(0));
367}
368
369#[cfg(debug_assertions)]
370#[doc(hidden)]
371pub fn hash_file_if_small_count_for_debug() -> usize {
372    HASH_FILE_IF_SMALL_CALLS.with(Cell::get)
373}
374
375#[cfg(any(debug_assertions, test))]
376#[doc(hidden)]
377pub fn watch_hash_file_for_debug(path: &Path) {
378    *WATCHED_HASH_FILE
379        .get_or_init(|| Mutex::new(None))
380        .lock()
381        .unwrap_or_else(std::sync::PoisonError::into_inner) = Some((path.to_path_buf(), 0));
382}
383
384#[cfg(any(debug_assertions, test))]
385#[doc(hidden)]
386pub fn watched_hash_file_count_for_debug() -> usize {
387    WATCHED_HASH_FILE
388        .get_or_init(|| Mutex::new(None))
389        .lock()
390        .unwrap_or_else(std::sync::PoisonError::into_inner)
391        .as_ref()
392        .map_or(0, |(_, count)| *count)
393}
394
395fn verify_file_inner(
396    path: &Path,
397    cached: &FileFreshness,
398    hash_matching_metadata: bool,
399) -> FreshnessVerdict {
400    let Ok(metadata) = fs::metadata(path) else {
401        return FreshnessVerdict::Deleted;
402    };
403    let new_size = metadata.len();
404    let new_mtime = metadata.modified().unwrap_or(UNIX_EPOCH);
405    if new_size == cached.size && new_mtime == cached.mtime {
406        if hash_matching_metadata {
407            if new_size > CONTENT_HASH_SIZE_CAP || cached.content_hash == zero_hash() {
408                return FreshnessVerdict::Stale;
409            }
410            return match hash_file_if_small(path, new_size) {
411                Ok(Some(hash)) if hash == cached.content_hash => FreshnessVerdict::HotFresh,
412                _ => FreshnessVerdict::Stale,
413            };
414        }
415        return FreshnessVerdict::HotFresh;
416    }
417    if new_size != cached.size || new_size > CONTENT_HASH_SIZE_CAP {
418        return FreshnessVerdict::Stale;
419    }
420    match hash_file_if_small(path, new_size) {
421        Ok(Some(hash)) if hash == cached.content_hash => FreshnessVerdict::ContentFresh {
422            new_mtime,
423            new_size,
424        },
425        _ => FreshnessVerdict::Stale,
426    }
427}
428
429#[cfg(test)]
430mod tests {
431    use super::*;
432    use std::io::Write;
433
434    fn write(path: &Path, bytes: &[u8]) {
435        fs::write(path, bytes).unwrap();
436    }
437
438    /// Phase-3 gating benchmark: stat-all (non-strict verify_file) vs hash-all
439    /// (strict verify_file_strict) cost across a real repo's file set, with NO
440    /// file changed (the steady-state warm freshness pass). Decides Option B:
441    /// if stat-all is cheap even at large file counts, replace the per-edit
442    /// hash-all with stat-diff-first.
443    ///
444    ///   AFT_BENCH_REPO=/path/to/repo cargo test -p agent-file-tools --lib \
445    ///     --release -- --ignored --nocapture --test-threads=1 \
446    ///     freshness_stat_vs_hash_benchmark
447    #[test]
448    #[ignore = "manual benchmark; needs AFT_BENCH_REPO"]
449    fn freshness_stat_vs_hash_benchmark() {
450        use std::time::Instant;
451        let Ok(repo) = std::env::var("AFT_BENCH_REPO") else {
452            eprintln!("AFT_BENCH_REPO unset; skipping");
453            return;
454        };
455        let root = std::path::PathBuf::from(&repo);
456        let files: Vec<std::path::PathBuf> = crate::callgraph::walk_project_files(&root).collect();
457
458        // Cold pass: collect freshness records (this is the cold-build cost, not
459        // what we're optimizing — just needed to seed the warm comparison).
460        let records: Vec<(std::path::PathBuf, FileFreshness)> = files
461            .iter()
462            .filter_map(|p| collect(p).ok().map(|f| (p.clone(), f)))
463            .collect();
464
465        eprintln!(
466            "\n=== freshness stat-vs-hash benchmark ===\nrepo: {}\nfiles walked: {}  freshness records: {}",
467            root.display(),
468            files.len(),
469            records.len()
470        );
471
472        // 3 iterations each, report medians. Interleave to share cache effects.
473        let mut stat_ms = Vec::new();
474        let mut hash_ms = Vec::new();
475        for _ in 0..3 {
476            let t = Instant::now();
477            let mut stat_hot = 0usize;
478            for (path, cached) in &records {
479                // Non-strict: stat only; hashes ONLY if (mtime,size) differ.
480                // With no file changed, this is pure stat — the Option B cost.
481                if matches!(verify_file(path, cached), FreshnessVerdict::HotFresh) {
482                    stat_hot += 1;
483                }
484            }
485            stat_ms.push(t.elapsed().as_micros());
486
487            let t = Instant::now();
488            let mut hash_hot = 0usize;
489            for (path, cached) in &records {
490                // Strict: stat + content-hash every file (today's per-edit cost).
491                if matches!(verify_file_strict(path, cached), FreshnessVerdict::HotFresh) {
492                    hash_hot += 1;
493                }
494            }
495            hash_ms.push(t.elapsed().as_micros());
496
497            eprintln!("  iter: stat_hot={stat_hot} hash_hot={hash_hot}");
498        }
499        stat_ms.sort_unstable();
500        hash_ms.sort_unstable();
501        let stat_med = stat_ms[1] as f64 / 1000.0;
502        let hash_med = hash_ms[1] as f64 / 1000.0;
503        eprintln!(
504            "SUMMARY  files={}  stat_all_median={:.2}ms  hash_all_median={:.2}ms  speedup={:.1}x",
505            records.len(),
506            stat_med,
507            hash_med,
508            hash_med / stat_med.max(0.001)
509        );
510    }
511
512    #[test]
513    fn hot_fresh_when_mtime_size_match() {
514        let dir = tempfile::tempdir().unwrap();
515        let path = dir.path().join("a.txt");
516        write(&path, b"same");
517        let fresh = collect(&path).unwrap();
518        assert_eq!(verify_file(&path, &fresh), FreshnessVerdict::HotFresh);
519    }
520
521    #[test]
522    fn strict_hashes_small_file_when_metadata_matches() {
523        let dir = tempfile::tempdir().unwrap();
524        let path = dir.path().join("a.txt");
525        let original_mtime = filetime::FileTime::from_unix_time(1_700_000_000, 0);
526        write(&path, b"alpha");
527        filetime::set_file_mtime(&path, original_mtime).unwrap();
528        let fresh = collect(&path).unwrap();
529
530        assert_eq!(
531            verify_file_strict(&path, &fresh),
532            FreshnessVerdict::HotFresh
533        );
534
535        write(&path, b"bravo");
536        filetime::set_file_mtime(&path, original_mtime).unwrap();
537
538        // Stat-diff freshness intentionally treats same-size, same-mtime edits as
539        // fresh; Tier-2's staleness ceiling heals this accepted residual with a
540        // periodic strict pass instead of hashing every file on each edit.
541        assert_eq!(verify_file(&path, &fresh), FreshnessVerdict::HotFresh);
542        assert_eq!(verify_file_strict(&path, &fresh), FreshnessVerdict::Stale);
543    }
544
545    #[test]
546    fn strict_stale_when_large_file_hash_was_not_cached() {
547        let dir = tempfile::tempdir().unwrap();
548        let path = dir.path().join("big.bin");
549        let original_mtime = filetime::FileTime::from_unix_time(1_700_000_000, 0);
550        let file = fs::File::create(&path).unwrap();
551        file.set_len(CONTENT_HASH_SIZE_CAP + 1).unwrap();
552        filetime::set_file_mtime(&path, original_mtime).unwrap();
553        let fresh = collect(&path).unwrap();
554
555        assert_eq!(fresh.size, CONTENT_HASH_SIZE_CAP + 1);
556        assert_eq!(fresh.content_hash, zero_hash());
557        // Non-strict stat-diff trusts unchanged metadata for over-cap files and
558        // avoids strict's needless rescan of large unchanged files.
559        assert_eq!(verify_file(&path, &fresh), FreshnessVerdict::HotFresh);
560        assert_eq!(verify_file_strict(&path, &fresh), FreshnessVerdict::Stale);
561    }
562
563    #[test]
564    fn content_fresh_when_only_mtime_changes() {
565        let dir = tempfile::tempdir().unwrap();
566        let path = dir.path().join("a.txt");
567        write(&path, b"same");
568        let fresh = collect(&path).unwrap();
569        let mut file = fs::OpenOptions::new().append(true).open(&path).unwrap();
570        file.write_all(b"").unwrap();
571        file.sync_all().unwrap();
572        filetime::set_file_mtime(&path, filetime::FileTime::from_unix_time(1, 0)).unwrap();
573        assert!(matches!(
574            verify_file(&path, &fresh),
575            FreshnessVerdict::ContentFresh { .. }
576        ));
577    }
578
579    #[test]
580    fn stale_when_size_changes() {
581        let dir = tempfile::tempdir().unwrap();
582        let path = dir.path().join("a.txt");
583        write(&path, b"same");
584        let fresh = collect(&path).unwrap();
585        write(&path, b"different");
586        assert_eq!(verify_file(&path, &fresh), FreshnessVerdict::Stale);
587    }
588
589    #[test]
590    fn deleted_when_missing() {
591        let dir = tempfile::tempdir().unwrap();
592        let path = dir.path().join("a.txt");
593        write(&path, b"same");
594        let fresh = collect(&path).unwrap();
595        fs::remove_file(&path).unwrap();
596        assert_eq!(verify_file(&path, &fresh), FreshnessVerdict::Deleted);
597    }
598
599    #[test]
600    fn over_cap_hash_is_not_computed() {
601        let dir = tempfile::tempdir().unwrap();
602        let path = dir.path().join("big.bin");
603        fs::write(&path, vec![0u8; CONTENT_HASH_SIZE_CAP as usize + 1]).unwrap();
604        assert!(hash_file_if_small(&path, CONTENT_HASH_SIZE_CAP + 1)
605            .unwrap()
606            .is_none());
607    }
608}
609
610#[cfg(test)]
611mod warm_reload_tests {
612    use super::*;
613
614    #[test]
615    fn stat_first_hashes_only_files_with_changed_metadata_while_cold_verify_is_strict() {
616        let dir = tempfile::tempdir().unwrap();
617        let path = dir.path().join("warm.rs");
618        fs::write(&path, b"fn warm() {}\n").unwrap();
619        let original_mtime = filetime::FileTime::from_unix_time(1_700_000_000, 0);
620        filetime::set_file_mtime(&path, original_mtime).unwrap();
621        let freshness = collect(&path).unwrap();
622
623        watch_hash_file_for_debug(&path);
624        let unchanged = verify_files_bounded(
625            vec![((), path.clone(), freshness)],
626            VerifyStrategy::StatFirst,
627        );
628        assert_eq!(unchanged[0].2, FreshnessVerdict::HotFresh);
629        assert_eq!(watched_hash_file_count_for_debug(), 0);
630
631        watch_hash_file_for_debug(&path);
632        let cold = verify_files_strict_bounded(vec![((), path.clone(), freshness)]);
633        assert_eq!(cold[0].2, FreshnessVerdict::HotFresh);
634        assert_eq!(watched_hash_file_count_for_debug(), 1);
635
636        filetime::set_file_mtime(&path, filetime::FileTime::from_unix_time(1, 0)).unwrap();
637        watch_hash_file_for_debug(&path);
638        let changed_stat = verify_files_bounded(
639            vec![((), path.clone(), freshness)],
640            VerifyStrategy::StatFirst,
641        );
642        assert!(matches!(
643            changed_stat[0].2,
644            FreshnessVerdict::ContentFresh { .. }
645        ));
646        assert_eq!(watched_hash_file_count_for_debug(), 1);
647    }
648
649    #[test]
650    fn verify_memo_skips_hits_and_invalidates_on_watcher_or_generation_change() {
651        let dir = tempfile::tempdir().unwrap();
652        let root = dir.path().join("root");
653        let artifact = dir.path().join("cache.bin");
654        fs::create_dir(&root).unwrap();
655        fs::write(&artifact, b"generation-one").unwrap();
656        let generation_one = artifact_generation(&artifact).unwrap();
657
658        assert_eq!(
659            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation_one)),
660            WarmVerifyPlan::Strict
661        );
662        record_verify_completed(&root, VerifyArtifact::Search, Some(generation_one));
663        assert_eq!(
664            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation_one)),
665            WarmVerifyPlan::Skip
666        );
667
668        invalidate_verify_memo(&root);
669        assert_eq!(
670            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation_one)),
671            WarmVerifyPlan::StatFirst
672        );
673
674        fs::write(&artifact, b"generation-two-is-different").unwrap();
675        let generation_two = artifact_generation(&artifact).unwrap();
676        assert_ne!(generation_one, generation_two);
677        assert_eq!(
678            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation_two)),
679            WarmVerifyPlan::Strict
680        );
681    }
682
683    #[test]
684    fn invalidation_between_verify_and_record_prevents_false_fresh_memo() {
685        let dir = tempfile::tempdir().unwrap();
686        let root = dir.path().join("root");
687        let artifact = dir.path().join("cache.bin");
688        fs::create_dir(&root).unwrap();
689        fs::write(&artifact, b"stable-generation").unwrap();
690        let generation = artifact_generation(&artifact).unwrap();
691
692        let stale_ticket = capture_verify_ticket(&root);
693        invalidate_verify_memo(&root);
694        assert!(!record_verify_completed_if_unchanged(
695            &root,
696            VerifyArtifact::Search,
697            Some(generation),
698            stale_ticket,
699        ));
700        assert_eq!(
701            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation)),
702            WarmVerifyPlan::Strict
703        );
704
705        let current_ticket = capture_verify_ticket(&root);
706        assert!(record_verify_completed_if_unchanged(
707            &root,
708            VerifyArtifact::Search,
709            Some(generation),
710            current_ticket,
711        ));
712        assert_eq!(
713            warm_verify_plan(&root, VerifyArtifact::Search, Some(generation)),
714            WarmVerifyPlan::Skip
715        );
716    }
717
718    #[cfg(unix)]
719    fn process_cpu_time() -> Duration {
720        let mut usage = std::mem::MaybeUninit::<libc::rusage>::uninit();
721        let result = unsafe { libc::getrusage(libc::RUSAGE_SELF, usage.as_mut_ptr()) };
722        assert_eq!(result, 0, "getrusage should report process CPU time");
723        let usage = unsafe { usage.assume_init() };
724        let seconds = (usage.ru_utime.tv_sec + usage.ru_stime.tv_sec) as u64;
725        let micros = (usage.ru_utime.tv_usec + usage.ru_stime.tv_usec) as u64;
726        Duration::from_secs(seconds) + Duration::from_micros(micros)
727    }
728
729    /// Measures the configure -> eviction -> rebind freshness component against
730    /// a real repository. The first pass models a cold strict verification; the
731    /// second models the unchanged-generation memo hit after in-process eviction.
732    #[cfg(unix)]
733    #[test]
734    #[ignore = "manual CPU measurement; needs AFT_BENCH_REPO"]
735    fn configure_eviction_rebind_cpu_measurement() {
736        let root = PathBuf::from(
737            std::env::var("AFT_BENCH_REPO").expect("AFT_BENCH_REPO must name a repository"),
738        );
739        let records = crate::callgraph::walk_project_files(&root)
740            .filter_map(|path| collect(&path).ok().map(|freshness| (path, freshness)))
741            .collect::<Vec<_>>();
742        let artifact_dir = tempfile::tempdir().unwrap();
743        let artifact = artifact_dir.path().join("cache.bin");
744        fs::write(&artifact, b"stable-generation").unwrap();
745        let generation = artifact_generation(&artifact).unwrap();
746
747        let strict_inputs = records
748            .iter()
749            .enumerate()
750            .map(|(index, (path, freshness))| (index, path.clone(), *freshness))
751            .collect();
752        let before = process_cpu_time();
753        let _ = verify_files_strict_bounded(strict_inputs);
754        let strict_cpu = process_cpu_time().saturating_sub(before);
755        record_verify_completed(&root, VerifyArtifact::Search, Some(generation));
756
757        let before = process_cpu_time();
758        if warm_verify_plan(&root, VerifyArtifact::Search, Some(generation)) != WarmVerifyPlan::Skip
759        {
760            panic!("unchanged artifact generation should skip rebind verification");
761        }
762        let memo_hit_cpu = process_cpu_time().saturating_sub(before);
763
764        invalidate_verify_memo(&root);
765        let stat_inputs = records
766            .iter()
767            .enumerate()
768            .map(|(index, (path, freshness))| (index, path.clone(), *freshness))
769            .collect();
770        let before = process_cpu_time();
771        let _ = verify_files_bounded(stat_inputs, VerifyStrategy::StatFirst);
772        let stat_first_cpu = process_cpu_time().saturating_sub(before);
773
774        eprintln!(
775            "configure-eviction-rebind CPU: files={} cold_strict={:?} memo_rebind={:?} invalidated_stat_first={:?}",
776            records.len(), strict_cpu, memo_hit_cpu, stat_first_cpu
777        );
778    }
779}
aft/cache_freshness.rs

aft/
cache_freshness.rs
