Module router_cache 

In-memory cache for the source router per ADR-021 §7.

Source latencies vary across orders of magnitude (microseconds for a keychain read; hundreds of milliseconds for op read plus a possible biometric prompt; seconds for a misconfigured Vault). Without caching, an agent that resolves a dozen secrets per minute is unusable. This module is the cache the router (P5.5+, P6) wraps every get() with.

Adaptive TTL

Per ADR-021 §7:

• The base TTL is per-source (cache_ttl_seconds in sources.toml); the default lives in P6 source impls and is typically 900 seconds.
• If SecretSource::get returns a lease_duration, the effective TTL becomes min(base_ttl, lease_duration). Vault dynamic-secret leases keep the cache from outliving the lease.
• lease_duration = Some(0) disables caching for that read entirely — the value is returned to the caller but never cached.
• The global index may further lower the TTL through cache_ttl_seconds_max (per-secret cap). The cap can only lower the TTL; it cannot raise it above the source default.

Eviction

Entries leave the cache when:

1. Their effective TTL elapses (lazy — checked on the next get).
2. The user invokes devboy secrets refresh <path> / --all (AdaptiveCache::invalidate / AdaptiveCache::invalidate_all).
3. A source declares out-of-band invalidation (Vault lease revoked, 1Password session timed out). The router calls AdaptiveCache::invalidate in response.
4. The process exits — every SecretString in the map zeroizes on drop. The cache itself is Drop-safe; we do not keep any extra plaintext copy.

Persistence

Never. Per ADR-021 §7: “the cache is never persisted. Process exit drops every entry.” The same posture as secrecy::SecretString’s zeroize-on-drop, extended one level up.

Testability

CacheClock is the abstract time source. Production callers pass SystemClock; tests pass ManualClock so the TTL can be raced past without std::thread::sleep.

Structs

AdaptiveCache

Path-keyed in-memory cache with adaptive TTL.

ManualClock

Test clock whose now() value is controlled by ManualClock::advance.

SystemClock

Production clock backed by Instant::now.

Constants

DEFAULT_BASE_TTL

Default base TTL when neither the source nor the per-secret cap override it. Matches the ADR-021 §7 fallback (15 minutes).

Traits

CacheClock

Wall-clock abstraction so tests can race past the cache TTL without sleeping.