Add just-in-time DEM slice stitching

[qciaran]

Summary

Adds the representation, PECOS-native extraction, assembly, and first production integration layer for just-in-time detector error models:

• reusable, absolute-index-free DemSlice templates with checked temporal horizons
• a deterministic DemSliceCache whose key policy remains with the physical-template provider
• per-use detector, standard-output, tracked-Pauli, coordinate, and logical relabeling through DemSliceInstance
• a structured adapter from DetectorErrorModel that preserves independent contributions, Y decompositions, and arbitrary source-frame component lists
• location-based ownership using existing DagFaultInfluenceMap identities, with partial and unattributed ownership rejected
• DemSliceRoundSchedule derivation from detector [x, y, round] coordinates and physical DAG gate ownership annotations
• a bounded DemSliceTemplateCompiler that extracts selected owner rounds without retaining an algorithm-length model
• reusable Python DemSliceTemplate handles and DemSliceRoundSchedule.from_templates(...) composition
• checked global and per-stream detector-coordinate translation for independently placed code blocks
• automatic dem_slice_round annotation for every gate generated by the surface LogicalCircuitBuilder
• exact minimum-buffer derivation from source ownership and temporal detector support
• DemStitcher assembly for commit-plus-buffer decoding windows with explicit hard/soft forward boundaries
• production cached providers for single-patch memory, a single transversal H, and matching-shape two-patch transversal CX algorithms
• structured full-circuit construction retained as the equivalence oracle and fallback for unsupported or unbounded operation families
• fail-loud diagnostics for incomplete mappings, unresolved hard ports, undersized buffers, invalid coordinate placement, and inconsistent source decompositions

This remains a draft because repeated logical-gate composition, the correct bounded mid-cycle fold-transversal SZ/SZdg circuit, broader multi-patch families, and the anti-snake logical-subgraph window decoder remain follow-ups. Full-circuit source-tracked models remain independent equivalence oracles, not the intended online algorithm path.

Motivation and design

Windowed decoding should not need to regenerate and filter a global DEM for every window. Under a bounded detector-correlation horizon, constant-depth physical operation templates can be compiled once and instantiated using relative detector addresses.

The API separates physical cache identity from scheduling state. Absolute rounds, detector-stream routing, patch placement, and output labels live on instances, so relabel-only operations do not multiply cached templates. Non-emitting temporal ports let asymmetric boundary slices refer to detectors owned by adjacent slices.

DemSlice::from_detector_error_model consumes PECOS's existing structured model and requires explicit mappings for every D<n>, L<n>, and TP<n> identity. from_detector_error_model_for_locations selects complete physical sources using influence-map location IDs. A correlated source may not be split across slices, and source components are checked to XOR to the complete effect.

For surface circuits, DemSliceRoundSchedule::from_annotated_circuit derives mappings and ownership automatically. Detector streams are ordered from the earliest full syndrome round, preserving the physical syndrome-bit order even when initialization has only a boundary subset. Integer detector time coordinates provide rounds, and each influence-map location inherits its owner from the dem_slice_round attribute on its DAG gate. Missing, non-integral, or inconsistent metadata fails loudly.

DemSliceTemplateCompiler turns a bounded annotated physical model into independently reusable owner-round slices. A three-SEC-round surface-memory fixture supplies four distinct families: initialization, stationary bulk SEC, pre-terminal SEC, and terminal data measurement. A six-round logical-gate fixture supplies initialization, ordinary pre-gate bulk, the pre-gate boundary round, the gate plus first post-gate SEC round, ordinary post-gate bulk, pre-terminal, and terminal families.

The production providers follow PECOS's existing functools.cache style. Physical cache identity includes geometry, orientation, boundary bases, and noise parameters, while excluding requested memory lengths, patch labels, qubit offsets, and coordinate placement. Those instance-only properties are applied while composing the schedule. Requests of different lengths therefore reuse the same bounded templates, and stitched memory and H results remain byte-for-byte identical to independent full DEMs.

The transversal-CX provider extends this to two matching patch shapes. Its gate-boundary family retains native correlated two-patch sources and hyperedges. Canonical detector streams are partitioned by patch and translated independently at instantiation, so arbitrary control and target placements reuse the same physical templates. The common registered/memory/CX order is supported; mismatched shapes, shallow boundaries, and noncanonical ordering retain full-model fallback.

The current standalone SZ/SZdg emitter is deliberately not cached. Its detector span grows with the entire preceding memory segment (3, 5, and 9 rounds for pre-gate depths 3, 5, and 9), violating the bounded-correlation requirement. The documented paper protocol instead embeds a fold-transversal S operation midway through one syndrome-extraction round. Implementing that physical S-SE circuit is a prerequisite to a sound SZ/SZdg JIT provider; including memory depth in the cache key would only disguise the violation.

The window assembler assigns dense local D<n> identifiers deterministically. It accepts a bounded source halo at the hard backward boundary, distinguishes soft sliding boundaries from hard terminal boundaries, and refuses to truncate a correlation that crosses the commit region and the entire buffer. required_buffer_rounds computes the exact required look-ahead.

Python callers can compile DetectorErrorModel.round_schedule(...) once, extract opaque cached templates, compose new schedules with DemSliceRoundSchedule.from_templates(...), and reuse stitch(...) across windows. build_algorithm_descriptor, build_dem, and build_sampler_and_decoder use an eligible cached provider and fall back to the reusable structured provider otherwise. A local segment DEM may overlap the following detector round for correlation context, while its num_detectors metadata remains the non-overlapping input-syndrome partition expected by the streaming decoder.

This follows the general slicing/stitching architecture in arXiv:2608.11719. The static-Tanner/prior-only optimization discussed in arXiv:2608.25027 remains a possible fast path when topology is actually unchanged; it is not assumed by the general stitcher.

Verification

• merged current origin/dev into the branch
• cargo test -p pecos-qec (816 unit tests: 810 passed, 6 expected ignored; all integration tests; 57 doc tests)
• exact byte-for-byte bounded-template reconstruction of independently compiled repeated-measurement and surface-memory DEMs
• exact memory-provider equivalence across rectangular/square patches, bases, labels, qubit offsets, placement, depths, and noise keys
• exact transversal-H provider equivalence across depths, orientations, initial/final bases, labels, offsets, placement, and noise keys
• exact transversal-CX provider equivalence across depths, orientations, four boundary bases, independent patch placement, labels, offsets, and noise keys
• warm-cache tests proving changed algorithm lengths do not invoke full structured DEM construction
• explicit fallback coverage for shallow boundaries, unsupported SZ/SZdg, and mismatched-shape CX
• invalid and unknown per-stream coordinate-translation rejection
• partial-ownership rejection for a native correlated two-qubit source
• exact minimum-buffer and pre-window source-halo correlation tests
• logical-boundary coverage proving cross-round mechanisms are preserved while streaming detector counts remain disjoint
• cargo clippy -p pecos-qec -p pecos-rslib --all-targets -- -D warnings
• cargo fmt --all -- --check
• 211 focused surface-builder, streaming-window, logical-decoder, and structured-DEM Python tests
• repository pre-commit hooks, just docs-build, and git diff --check

Follow-ups

• implement and verify the bounded mid-cycle fold-transversal S-SE circuit before caching SZ/SZdg
• compose repeated H and CX boundaries from cached physical families
• add broader multi-patch and lattice-surgery template providers
• model one-round memory and shallow logical-gate boundary families explicitly
• support general Python detector/output identity routing beyond coordinate placement
• enable the anti-snake logical-subgraph window decoder on structured segment models
• add a topology-stable prior-update fast path where applicable
• support local cache-weight refresh for drift/leakage estimates
• feed decoder-size estimates into logical-operation scheduling