Phase 5: copy-on-write snapshots (Pillar A) + overlay reuse

[KaiCode2]

Implements Pillar A of the roadmap: replace the O(total-state) deep-clone create_snapshot with a copy-on-write snapshot, and add overlay buffer/instance reuse. Stacked on phase-3-state-updates (which now carries the merged Phase 4 work, #3).

Design (locked decisions D1–D5, see docs/phase-5-spec.md)

A two-tier snapshot: the cold layer-2 BlockchainDb index is flattened once into an immutable Arc<BaseState> (per-account storage shared by Arc), memoized across snapshots and rebuilt copy-on-write only for changed addresses; each snapshot folds just the hot layer-1 CacheDB delta over a cheap Arc::clone.

• D1 — Arc-shared maps, not a persistent/HAMT crate: reads stay O(1) and lock-free, no per-SLOAD regression, no new dependency.
• D2 — base memoized immutable; every controlled layer-2 write marks it dirty (over-invalidation is safe, silent staleness is not). Uncontrolled append-only lazy-fetch growth is caught by an O(accounts) length-scan.
• D3 — create_snapshot_deep_clone() retained as the A/B baseline and the differential read-equivalence reference.
• D4 — EvmOverlay::reset() recycles an overlay across sims; the 64 KB shared-memory buffer is reused via a Send-preserving take/reclaim (plain Vec field + method-local Rc).
• D5 — create_snapshot is now &mut self (it memoizes the base). All call sites updated.

EvmSnapshot stays Send + Sync, EvmOverlay stays Send; read semantics (StorageCleared/NotExisting/two-layer precedence) are bit-for-bit identical to the legacy flatten.

Benchmarks (benches/simulation.rs, measured)

create_snapshot COW vs the legacy deep clone, cold index in layer 2:

cold index	COW	deep clone	speedup
100 × 8	1.8 µs	49.9 µs	~28×
1 000 × 8	17 µs	530 µs	~31×
2 000 × 16	34 µs	2.55 ms	~76×
5 000 × 16	101 µs	6.54 ms	~65×
10 000 × 16	193 µs	12.79 ms	~66×

The deep clone scales with total slots; COW eliminates the per-slot copy and tracks accounts + changed. overlay_fanout reset-recycled is a modest win that grows with fan-out width.

Tests

tests/cow_snapshot.rs — a differential-equivalence gate: create_snapshot is asserted read-identical to create_snapshot_deep_clone after 12 mutation kinds (layer-2-only write-through, same-length inject overwrite, simulated uncontrolled backend growth, purge, set_block, NotExisting, …), plus COW non-aliasing, overlay reset()/buffer-reuse, and an escape-hatch guard. 328 passed (default) / 275 (--no-default-features); existing snapshot/overlay/freshness contracts pass unchanged. fmt + clippy (both configs) + doc + bench --no-run clean.

Review

Line-by-line overseer review + a 3-way adversarial panel (staleness / read-equivalence / concurrency) confirmed the core model sound (read-equivalence bit-for-bit; the COW rebuild never mutates a shared Arc; the count-based growth scan is sufficient because the lazy fetch is append-only — validated against foundry-fork-db's source). Remediation applied:

1. The one layer-2 write site not following the uniform rule (override_account_code…) now dirties the base.
2. The one residual edge — an out-of-band same-length overwrite through the public blockchain_db()/backend() handles (a contract boundary, not reachable internally) — now has a public invalidate_snapshot_base() re-honest hook, rustdoc warnings on both accessors, a load-bearing-invariant note in refresh_base, a guard test, and a KNOWN_ISSUES.md entry.

Docs

CHANGELOG (### Added COW + reset(); ### Changed create_snapshot/inject_storage_batch → &mut self), ROADMAP (Phase 5 → Done), KNOWN_ISSUES (limitation resolved + the boundary documented).

🤖 Generated with Claude Code