Highlights
SnapshotStore V2 — deterministic snapshot-assisted replay that reduces compile_cognitive_head() time by 43–95% depending on snapshot coverage. After the first snapshot, only new events are replayed, not the entire ledger.
Architecture
- ReplayEngine abstraction owns all replay strategy (full, delta, fast path)
- SnapshotManager lifecycle: load, validate, save, refresh, delete
- ReplayReport telemetry: replay mode, event counts, snapshot status
- EventCountPolicy: configurable threshold (default: 100 new events)
- ADR-026 accepted; replay subsystem contracts frozen
Performance
| Events | Snapshot % | Full (ms) | Delta (ms) | Improvement |
|---|---|---|---|---|
| 1,000 | 50% | 1.61 | 0.84 | 48.1% |
| 5,000 | 50% | 8.57 | 4.85 | 43.4% |
| 10,000 | 50% | 22.12 | 8.94 | 59.6% |
| 5,000 | 90% | 9.05 | 1.07 | 88.1% |
| 5,000 | 99% | 8.56 | 0.37 | 95.7% |
| 10,000 | 99% | 17.53 | 0.84 | 95.2% |
Verification
- 1,870 tests pass (55 snapshot + 44 replay equivalence + 1,771 existing)
- PostgreSQL CI: full test suite validates backend parity
- Replay equivalence CI: required status check on every PR
- Backend parity CI: snapshot tests on both SQLite and PostgreSQL
- Nightly benchmarks: daily performance tracking
Compatibility
- No public API breaking changes
- Existing projects require no migration beyond applying database schema version 0003
- Snapshot is purely additive — full replay remains available as fallback
Upgrade Notes
Apply migration 0003_snapshots.sql to enable snapshot storage. No code changes required — the compiler automatically uses snapshot-assisted replay when snapshots are available.