Phase 3: fused DemSampler.decode() with a frozen reproducibility ABI

[ciaranra]

Summary

Phase 3 of the unified batch-decode API, stacked on #530 (phases 1-2 merge first).

• sampler.decode(dem, num_shots, decoder=..., *, seed=None, workers=None, predictions=False, timing=False) — the fused sample-and-decode entry point returning the shared DecodeResult, with sampling_seed_used populated (entropy draws are returned so any run can be replayed).
• Sampling ABI v1 (frozen): shots partition into canonical 1024-shot chunks; chunk k samples from PecosRng seeded with the k-th SplitMix64 output of seed XOR 0x5045434F5344454D ("PECOSDEM"), one single-shot DemSampler::sample call per shot. The hard guarantee: a fixed (seed, num_shots) yields an identical shot and prediction stream for every worker count, sequential and native execution included. Golden pin tests freeze the derivation (owner-computed literals, independently re-derived three times) and an end-to-end fused stream spanning both chunk boundaries; a consequence pinned by test: the stream for N shots is a prefix of the stream for M > N.
• One seeding seam (sampling_chunk_rng) feeds all three execution paths so the ABI's load-bearing lines cannot drift apart.
• Execution reuses the phase-2 planner unchanged: history-dependent decoders run one engine continuously across chunk boundaries (never reset — pinned by a cross-boundary test); wall-clock-bounded decoders parallelize only by explicit opt-in with a recorded warning; PyMatching gets the native chunk-batch path.
• Raw-measurement samplers are rejected before decoder parsing, mirroring SampleBatch's guard; unconditional decoder build + dimension preflight happens before dispatch, including at zero shots.
• Predictions and truth are restricted to the sampler's observable DEM outputs, matching sample_decode_count (documented, including the deliberate asymmetry with SampleBatch.decode).
• Legacy sample_decode_count / sample_batch streams are byte-untouched, pinned by per-shot row regression literals, and remain until the migration phase.

Verification

• cargo clippy --locked --workspace --all-targets --all-features -- -D warnings; test suites for pecos-random (ABI pins), pecos-decoders, pecos-decoder-core, pecos-pymatching; cargo fmt --check; just lint.
• Python: rslib tree 2176 passed on an mwpf-enabled build.
• Independent cross-checks beyond the test suite: the frozen golden stream re-derived on two independent execution paths (native and sequential agree shot-for-shot); prefix property across 1025/1500/2065 shots and mixed worker counts; entropy-seed replay exact.
• Independent adversarial full-diff review returned SHIP with no blockers; its two pre-merge recommendations (single seeding seam, native-timing invariant assert) are included, and all seven ABI pins were re-derived a third time by the reviewer.