vinilana Govern Cache Retention
Require every cache and persistent index to declare how it stops growing and becomes fresh again.
Workflow
- Inventory keys, values, entry count, estimated bytes, and ownership lifetime.
- Define maximum entries, maximum estimated bytes, TTL, and single-entry behavior.
- Choose a freshness signal tied to the source, not only elapsed time.
- Use LRU within TTL and evict proactively on set and lifecycle cleanup.
- Make timers unref, bounded, and disposable.
- Clear process-local caches on server stop.
- Add lazy, dual-read migration for persistent shape changes.
- Protect active sessions and preserve rollback readability.
Required cache contract
Document:
- normalized key;
- entry and byte limits;
- TTL;
- freshness signal;
- eviction order;
- sweep trigger;
- dispose behavior;
- metrics;
- behavior when one entry exceeds budget.
Reject a cache implementation that omits any item.
Persistent indexes
Avoid one ever-growing JSON document on a hot path. Partition bindings or records when lookup and rewrite cost scale with total history. Keep summaries in session.json and move growing checkpoint payloads to append-only or individual records.
Required invariants
- Never expire only when the exact stale key is read again.
- Never leave a referenced interval after stop.
- Never retain stale semantic context after source identity changes.
- Never ignore cacheEnabled.
- Never prune active workflow state.
- Never require destructive migration to roll back.
- Clamp unsafe configuration values.
Dotcontext routing
- Put generic LRU/retention rules in harness domain/application.
- Keep MCP and integration caches owned and disposed by their surfaces.
- Coordinate repository pruning with runtime history.
- Follow F-07.
Review gate
Test entry eviction, byte eviction, TTL sweep, freshness invalidation, stop cleanup, stale binding removal, checkpoint migration, unsafe config clamps, and legacy reads.