pub fn is_cache_entry_stale_verified(
path: &str,
cached_mtime: Option<SystemTime>,
cached_hash: &str,
) -> boolExpand description
Staleness with content verification: like is_cache_entry_stale, but when
the mtime claims “unchanged”, additionally compares the md5 of the on-disk
content against the cached hash.
mtime alone cannot be trusted for correctness: same-second writes are
invisible on coarse-granularity filesystems (HFS+ 1s, FAT 2s) and mtimes can
be restored by tools. Serving an [unchanged] stub for changed content
would silently mislead the agent — the worst failure mode a context layer
can have. The extra disk read costs microseconds for typical source files;
the stub’s token savings are unaffected. Opt out: LEAN_CTX_CACHE_VERIFY=0.
Note: entries whose stored content differs from disk by design (e.g. secret redaction) hash differently and therefore never serve stubs — conservative and correct.
#1780: both filesystem calls below retry briefly before giving up, so a
transient lock is not mistaken for a content change. The mtime probe that
runs first is covered too — file_mtime retries in the same way — so all
three filesystem touches on this path share the behaviour. An unreadable
file is still declared stale — that verdict is never wrong, only wasteful
— but it no longer happens for a file that merely had a writer’s handle open
a moment ago.