# Persistent Cache Round 10 Plan

## Summary

Round 10 should begin the path from in-process caching toward a persistent cache/index layer, but only with the smallest safe step.

The work is sequenced in this order:

1. define a persistent cache/index boundary that does not compromise freshness
2. implement the smallest disk-backed cache artifact that can be invalidated safely
3. verify correctness and fallback behavior

## Key Changes

### Persistent cache boundary

- keep append-only ledger and vault scans as sources of truth
- treat any disk-backed cache as a rebuildable derivative
- prefer read-through / invalidate-on-change behavior over background mutation

### First implementation step

- likely start with a serialized projection snapshot or equivalent lightweight artifact
- do not cache mutable UI/session state
- keep a no-cache fallback path always available

## Test Plan

- cache hit / miss tests
- invalidation tests after ledger/vault changes
- fallback tests when cache is missing or corrupted

## Assumptions

- Round 10 does not change tool names or lifecycle semantics
- Round 10 keeps correctness ahead of startup speed
- Round 10 does not introduce a daemon yet

## Completion Status

Last checked: `2026-04-12`

Completed in this round:

- added a rebuildable disk-backed lifecycle projection snapshot
- kept append-only ledger as source of truth and used the snapshot only as a derivative cache
- added invalidation on append plus corruption fallback to direct rebuild
- retained the existing in-process projection cache on top of the persistent snapshot
- verification completed with full test and check passes

Checked for omissions against this plan:

- no missed items inside the scoped implementation baseline
- external tool names and lifecycle semantics remain unchanged
- daemonization remains intentionally deferred
