Give the DEM-consuming Python decoders a uniform call and result protocol

[ciaranra]

Problem

The Python decoder objects that all consume a DEM expose three different call
and result shapes, so user code cannot iterate over decoders uniformly:

Decoder	Methods	Per-shot result
PyMatchingDecoder	decode, decode_batch	.correction (per-observable vector)
TesseractDecoder	decode, decode_batch, decode_syndrome	.observables_mask (bitmask)
DemAwareDecoder	decode_syndrome	.observables_mask (bitmask)

Writing an explicit comparison therefore needs a different expression per
decoder:

pymatching_errors += pymatching.decode(syndrome).correction[0] != actual
tesseract_errors += (tesseract.decode_syndrome(syndrome).observables_mask & 1) != actual
bp_osd_errors += (bp_osd.decode_syndrome(syndrome).observables_mask & 1) != actual

(from docs/workflows/guppy-dem-decoding.md, which shows this honestly rather
than hiding it behind the stringly-typed SampleBatch.decode_count(text, name)
shortcut).

Proposal

Give the DEM-consuming decoders one shared Python protocol: a single per-shot
method name and a single result shape (mask and per-observable vector both
available on the result, rather than one or the other depending on the class),
plus a batch variant with the same contract. Keep the existing methods as
deprecated aliases during a ramp, as in #424.

The Rust side already has this notion: ObservableDecoder::decode_obs is the
wide primitive the registry dispatches through
(python/pecos-rslib/src/fault_tolerance_bindings.rs,
create_observable_decoder). The Python surface should expose the same
uniformity instead of the stringly-typed registry being the only uniform path.

Related

Consistency series: #422, #423, #424, #425, #428. The stringly-typed
decode_count(text, "name") registry is fine as a fast-path convenience, but it
should not be the only way to treat decoders uniformly.

[ciaranra]

Design review panel (2026-08-03, two blind arms) revised this issue. Design record: pecos-docs/design/construction-and-decoding-api-shape.md.

Resolved open questions:

• Protocol, not a shared result type. MwpmResult carries .weight, TesseractResult carries .cost/.low_confidence, DemAwareResult carries .converged/.iterations, and BpResult.decoding is per-mechanism — a different vector space with no observable mapping. One carrier for all of that is a union of mostly-None fields, worse than today.
• Vector-primary, not mask-primary. The premise in the design was inverted: Rust ObservableDecoder::decode_obs already returns a wide ObsMask; it is the Python results that are u64 at the pyo3 getter. Tesseract and Fusion Blossom genuinely cap at 64; PyMatching is wide. So MwpmResult.correction is the model and the two mask classes must change — this is a breaking change, not an additive one.

Corrections to the premise:

• None of the three pyclasses route through ObservableDecoder — they call their inherent Rust decoder directly. There is no existing seam to surface; this is new plumbing.
• decode_obs is uniform because it returns nothing but an ObsMask — exactly the diagnostics a unified result wants to keep.
• SampleBatch.decode_each(dem, decoder_type) already exists and is the genuinely uniform per-shot path: arbitrary-precision Python ints (no 64-observable truncation), and it propagates decode errors instead of masking them. decode_count counts a decode failure as a logical error. Both should be documented; they already cover ~34 decoder configurations, versus the three classes.
• Unifying three classes does not retire the string registry: most registry configurations have no Python class, and bp_osd/bp_lsd/union_find/relay_bp/min_sum_bp are registry-constructible while their classes are not DEM-constructible.
• Standardizing on the name decode collides with MWPM2D/DummyDecoder in the same namespace, which use it for a measurements→recovery-circuit protocol.

Do the concrete defects first — #430 (critical width bug) and #431 (same-named decode() with different encodings, missing re-export, stale stub, drifted registry). They need no design decision and remove most of the observable pain that motivated this issue.