Phase C — memory as a verifiable contract + the front door (Move #4)

[logannye]

Summary

Turns the existing memory receipt into a contract on the bounded variants --index path — declare → predict → honor-or-refuse → verify — the property no incumbent caller offers. Decomposed into three sub-stages (one design doc + three plans under docs/superpowers/), each landing green.

rosalind plan    --index g.idx --max-depth 1000 --budget-mb 2048   # predict before committing a byte
rosalind variants --index g.idx --alignments s.bam \
                 --memory-budget-mb 2048 --enforce -o s.vcf        # honor: refuse(3) / fail(4), never silent OOM
rosalind verify  --manifest s.vcf.manifest.json                    # re-check the receipt, no re-run

What changed

C1 — working-set soundness (the hard correctness core). PileupEngine::current_working_set() now counts the resident reference + each active read's seq/qual buffers (it previously counted only the projection map — a real under-count of the dominant terms). Adds a deterministic --max-depth cap; streams each call to the VCF writer (no genome-wide row buffer); decodes-then-moves each contig reference (2×→1×). Proven by a library test that the reported working set is a true upper bound and is flat as read count grows.

C2 — rosalind plan + --enforce. A pure estimator (src/call/plan.rs) sharing C1's cost constants so the prediction and the realized accountant cannot drift. plan predicts the variants peak (--index) or the build (--reference). --enforce refuses up front (exit 3) when the predicted peak won't fit and fails loud post-run (exit 4) if the realized peak does; record-only behavior is preserved without --enforce. The predicted peak = a process baseline measured at call time + the estimated working set, so it is comparable to the realized peak_rss the post-run check uses (no guessed baseline constant).

C3 — rosalind verify + self-describing receipts. Every receipt now carries contract_verdict/enforced/memory_budget_mb/max_depth/max_read_len. A small canonical-JSON hand-parser (RunManifest::from_canonical_json, round-trip property-tested, no serde_json) backs rosalind verify, which re-hashes the recorded inputs/outputs and re-checks the recorded peak vs the budget without re-running (exit 5 on mismatch). A stdout run without --manifest writes no file but prints how to persist one (avoids polluting a pipe user's cwd / racing on a fixed filename).

Test plan

• Full suite green (26 sections), cargo fmt --all -- --check clean, cargo build 0 warnings (debug and release).
• Determinism + golden-VCF snapshots preserved (the writer split + per-call streaming are byte-identical).
• New gates in tests/plan_enforce.rs: plan breakdown, --enforce refuse (exit 3), within-budget pass, stdout receipt, verify round-trip + tamper (exit 5), and the estimator-upper-bounds-realized contract gate. New provenance round-trip parser test (escapes + multibyte).

Non-goals (kept out by design)

Index-build enforcement (build is O(reference); Phase D), somatic whole-genome bounding, graceful degrade/spill (Phase D √t ladder), and thread-invariance claims (engine is single-threaded). MSRV 1.72 preserved; no new dependencies.

🤖 Generated with Claude Code

[logannye]

Folded in Move #4 — the front door (8 commits on top of Phase C), so this PR is now the complete "shipped contract + discoverable front door" story:

• Crate-root re-exports — use rosalind::{PileupEngine, PileupColumn, ReadSource, MemoryBudget, GenomeIndex, RunManifest, …} now lands on the genomics product surface; the √t theory types are regrouped under a "research layer" comment.
• lib.rs / cargo doc rewritten contract-first with a runnable doctest (was "O(√t) Space Simulation"); √t demoted to an honest "Research direction (Phase D)" footer.
• CONTRACT.md (the four verbs + the honest "never silently OOM-kills" brand) and a contract-first README (substrate-first Extend; the GenomicPlugin/Python lineage labeled legacy/non-bounded, not removed; stale "does not yet enforce" claims fixed; a runnable bundled in-house demo).
• examples/custom_pileup_analytics.rs — a non-caller PileupColumn-iterator cookbook.
• tests/frontdoor_demo.rs — smoke-tests the README's in-house demo end-to-end on the bundled fixture.

Public roadmap issue #3 reframed to match (contract-first; √t as the future Phase-D knob). Full suite green (27 sections), 0 warnings (debug + release), fmt clean.