docs: annbatch contrast + read-once/sample-once shuffle contract

[emfdavid]

What

Documents where insitubatch sits relative to annbatch (scverse, Ilan Gold et al., arXiv:2604.01949), and pins down the shuffle/gather contract that comparison turns on.

DESIGN.md — the evolution ledger (why / alternatives)

• New annbatch row in What it is, by contrast: same premise, opposite bet — annbatch pre-shuffles to disk and dissolves chunks into rows; insitubatch keeps chunks whole and resident and pays with an approximate shuffle. Both carry one bounded-randomness knob (their buffer m ≈ our block_chunks); the difference is the currency — a one-time rewrite vs. read locality.
• Shuffle section trimmed to the thesis (why approximate at all) + the contrast; mechanism deferred to architecture.
• Ragged-batch flagged as a possible wart in Known limitations, with options, pending user feedback.

docs/architecture.md — the live contract (how it works)

• New Read-once and sample-once section: the two orthogonal invariants (read-once = read plan + ChunkPool; sample-once = the order ledger, fancy index recomputed at gather, never stored).
• An archive → batch figure (mermaid) staged like annbatch's Fig 1C — colour tracks the bytes (a chunk keeps its colour archive→pool), the read plan is metadata (dashed), and each batch is colour-coded slices drawn across resident chunks that stay whole.
• The ragged per-block tail as a user caveat: batches don't span shuffle blocks, so a short final batch appears per block (steps-per-epoch = Σ ⌈block/bs⌉, not ⌈N/bs⌉); no drop_last today.

Why

DESIGN.md's own header already declares the division (evolution ledger vs. live contract in architecture.md). This enforces it: contract + diagram live in architecture, why/alternatives in DESIGN, cross-linked both ways. Net −9 lines — less sprawl, one home per topic.

Notes for review

• The mermaid figure renders on GitHub and in the mkdocs site; worth an eyeball on the nested batch subgraphs and the #known-limitations--defects / #read-once-and-sample-once cross-link anchors.
• No code touched; contract claims are backed by existing tests (test_order_covers_every_sample_exactly_once, test_order_handles_partial_final_chunk, the decode-once suite).

🤖 Generated with Claude Code