Storage Engine v4 — Stack 5: equivalence runner + microtests + bench CLIs

[c1-squire-dev]

Summary

Stack 5 of RFC 0004 — closes the v4 PR stack with the validation infrastructure (RFC §6). Stacks on Stack 4.

Equivalence harness at pkg/dotc1z/engine/equivalence/:

• Reference interface — minimal store contract that both the Pebble engine and the in-memory reference satisfy. Pluggable: future stacks can register the SQLite engine as a second Reference once the v2↔v3 translation layer is implemented (deferred — see tracker.md).
• MemoryRef — deterministic in-memory implementation; source-of-truth in property tests.
• RunWorkload(ctx, ref, w) → Result; Compare(ctx, refA, refB, w) error.
• Workload + Op types support Put + Delete sequences.
• 4/4 tests pass: TestPebbleMatchesMemoryRef (200 puts + 25 deletes, 5 entitlements, 50 principals), TestEmptyWorkload, TestSingleGrant, TestPutOverwrite (proves index cleanup matches reference).

Microtests at pkg/dotc1z/engine/pebble/microtests/:

• tuple_test.go — exercises the production codec.AppendTupleBytes / codec.AppendTupleSeparator for the prefix-free property over hand-picked + 200 random cases (40,000+ pairwise comparisons).
• codec_perf_test.go — codegen vs cached-reflection codec benchmark. On Linux/arm64: 96.92 ns/op direct vs 188.0 ns/op reflect (~1.94× delta — justifies the hybrid registry: direct codegen for the canonical record types, reflection fallback for ad-hoc types via the codec.Lookup path).
• doc.go indexes the 5 risk-validation tests. The remaining 3 (compress, checkpoint, ingest_excise) are already covered by Stack 3 / Stack 4 tests against the production engine — they don't need a separate microtest copy.

Benchmark CLI at cmd/baton-storage-bench/:

• G2 random Get by primary key, G3 list by entitlement, G4 list by principal, G5 full-sync scan.
• Read-only against an existing Pebble dir; reports ops/sec + ns/op.
• G1 (bulk write) lives in cmd/baton-fixture-gen. G6-G10 land as follow-ups.

Fixture-gen CLI at cmd/baton-fixture-gen/:

• Generates synthetic GrantRecord rows at scale: -grants flag for total count, -entitlements / -principals for cardinality, -seed for deterministic generation. Output is a Pebble directory ready to bench.
• Smoke: 1000 grants in 51ms (~19.6k r/s single-threaded). At 1M grants this projects to ~50s.

End-to-end smoke

baton-fixture-gen → baton-storage-bench: G3 ListByEntitlement returns
732k rows in 1s of benching (7.3k ops/s with the small fixture).

Test plan

• make lint clean (no findings across the whole v4 stack)
• 4/4 equivalence tests + 1 tuple property test + 4 codec benchmarks
• End-to-end fixture-gen → storage-bench smoke
• CI green

🤖 Generated with Claude Code

[c1-squire-dev]

Rebased onto updated Parent (PR #867) after review fixes from btipling + pr-review bot. See #867 for the specific fixes, or PR #874 for the combined squash view.