Decoder surface defects: same-named decode() with different encodings, missing re-export, stale stub, drifted registry

[ciaranra]

Problem

Two public decoder classes expose a method with the same name, decode, that
takes different input encodings, and both accept list[int] from Python, so
mixing them up is silent rather than an error.

• PyMatchingDecoder.decode(syndrome) takes a dense per-detector vector
  (python/pecos-rslib/src/decoder_bindings.rs:524).
• TesseractDecoder.decode(detections) takes sparse detector indices
  (python/pecos-rslib/src/decoder_bindings.rs:1586, documented at :1573);
  TesseractDecoder.decode_syndrome is the dense one and densifies before
  delegating (:1608-1616).

Verified on one DEM with the same Python literal [1, 0]:

Tesseract decode([1, 0])           -> observables_mask = 0
Tesseract decode_syndrome([1, 0])  -> observables_mask = 1

A user who reaches for decode on both classes gets a wrong answer from one of
them with no exception raised.

decode_batch is likewise not uniform: PyMatchingDecoder.decode_batch(events, num_shots) returns raw list[list[int]] and requires an explicit shot count,
while TesseractDecoder.decode_batch(syndromes, num_workers=None) returns
result objects (:558-562, :1633-1637).

Separately, MWPM2D and DummyDecoder in the same pecos.decoders namespace
also define decode, with a third protocol entirely (measurement output to
recovery circuit).

Related defects found alongside

• DemAwareResult is registered in pecos_rslib.decoders but not re-exported
  from pecos.decoders (python/quantum-pecos/src/pecos/decoders/__init__.py),
  so users receive an object they cannot import by name.
• FusionBlossomDecoder has a Rust from_dem that is not exposed on the
  pyclass (python/pecos-rslib/src/decoder_bindings.rs:666-763), so it is
  reachable only through the string registry.
• The type stub python/pecos-rslib/pecos_rslib.pyi is stale for this family:
  it declares PyMatchingDecoder.__init__(check_matrix, weights) (real:
  new(num_nodes, num_observables=64)), TesseractResult.correction/.weight
  (real getters: observables_mask, cost, low_confidence),
  TesseractDecoder.__init__(dem_string) (real: from_dem staticmethod), and
  omits DemAwareDecoder/DemAwareResult entirely.
• A second decoder string registry, decoder_dem_requirement
  (python/pecos-rslib/src/fault_tolerance_bindings.rs:6902-6925), has drifted
  out of sync with create_observable_decoder: belief_matching,
  belief_matching_correlated, belief_find, beamsearch, and perturbed
  raise "Unknown decoder type", while chromobius is listed but is not
  constructible.

Notes

These are the concrete, fixable defects behind #429. Several can be fixed
without any API-shape change, which is worth doing first: re-export
DemAwareResult, expose FusionBlossomDecoder.from_dem, refresh the stub, and
reconcile the two registries.

Found by an adversarial design-review panel on
pecos-docs/design/construction-and-decoding-api-shape.md and verified by
execution against the installed extension.

[ciaranra]

Fixed in PR #420 (commit 13eb92c68), except the API-shape item.

Closed here:

• FusionBlossomDecoder.from_dem(dem, correlated=False) exposed on the pyclass. The Rust from_dem/from_dem_correlated already existed but were unreachable from Python, so the decoder was registry-only.
• DemAwareResult re-exported from pecos.decoders — decoding returns it, so users must be able to name it.
• Registry drift reconciled. belief_find -> "any" (it is built in the same check-matrix arm as bp_osd); belief_matching, belief_matching_correlated, belief_matching_mgbp, belief_matching_hybrid, and beamsearch -> "graphlike" (all matching-graph based). Each classification was read off the arm that constructs the decoder, not guessed.
• perturbed now delegates to its inner decoder instead of being classified as one thing. perturbed:K=15,inner=TYPE wraps an arbitrary decoder, so a fixed answer would be wrong for half its uses. Verified: perturbed:inner=tesseract -> "any", perturbed:inner=pymatching -> "graphlike", bare perturbed -> "graphlike" (default inner is pymatching).
• Type stub refreshed: PyMatchingDecoder's real constructor plus its from_dem/from_dem_with_correlations/from_check_matrix statics and decode_batch; TesseractResult's actual getters (observables_mask, cost, low_confidence, observable_bits); TesseractDecoder.from_dem with both the sparse decode and dense decode_syndrome; and DemAwareDecoder/DemAwareResult, which were absent entirely.

Tests: python/quantum-pecos/tests/qec/test_decoder_surface_defects.py — 26 cases covering the re-export, the DEM constructor, a name-by-name registry table, and the perturbed delegation matrix.

Left open (needs the design decision in #429): the same-named decode() with different input encodings — PyMatchingDecoder.decode dense versus TesseractDecoder.decode sparse. Making that uniform is either a breaking rename or an added alias, and it should land with the protocol decision rather than piecemeal. chromobius also remains classified but not constructible; it exists in pecos-decoders and is simply not registry-wired, so the classification documents intent rather than drift.

Note: decoder_dem_requirement and create_observable_decoder are still two hand-maintained lists that must be updated together — the new test table makes a future drift fail loudly, but the structural fix belongs with #429.

[ciaranra]

Another instance of the missing- defect, found while reviewing the workflow example in PR #420.

has no constructor from a DEM at all:

decoder	on the Python surface
TesseractDecoder	yes
PyMatchingDecoder	yes, plus from_dem_with_correlations
DemAwareDecoder	yes
FusionBlossomDecoder	missing (already noted in this issue)
BpOsdDecoder	missing

The consequence is visible in docs/workflows/guppy-dem-decoding.md, where Tesseract and PyMatching are constructed as named types while BP+OSD has to go through a stringly-typed wrapper:

bp_osd = DemAwareDecoder.from_dem(raw_text, decoder_type="bp_osd")

And "bp_osd" is the only value decoder_type accepts (python/pecos-rslib/src/decoder_bindings.rs). So the parameter is a one-element enum that exists solely to reach the one decoder that lacks a from_dem — it is a symptom of this issue rather than an API choice.

Suggested addition to this issue's scope: expose BpOsdDecoder.from_dem(...) alongside the FusionBlossomDecoder.from_dem re-export already listed. Once both exist, DemAwareDecoder's decoder_type has no remaining purpose and can go, and the workflow doc can use named decoder types uniformly.

[ciaranra]

Another instance of the missing-from_dem defect, found while reviewing the workflow example in PR #420.

BpOsdDecoder has no constructor from a DEM at all:

decoder	from_dem on the Python surface
TesseractDecoder	yes
PyMatchingDecoder	yes, plus from_dem_with_correlations
DemAwareDecoder	yes
FusionBlossomDecoder	missing (already noted in this issue)
BpOsdDecoder	missing

The consequence is visible in docs/workflows/guppy-dem-decoding.md, where Tesseract and PyMatching are constructed as named types while BP+OSD must go through a stringly-typed wrapper:

bp_osd = DemAwareDecoder.from_dem(raw_text, decoder_type="bp_osd")

And "bp_osd" is the only value decoder_type accepts (python/pecos-rslib/src/decoder_bindings.rs). So the parameter is a one-element enum existing solely to reach the one decoder that lacks a from_dem — a symptom of this issue rather than an API choice.

Suggested addition to this issue's scope: expose BpOsdDecoder.from_dem(...) alongside the FusionBlossomDecoder.from_dem re-export already listed. Once both exist, DemAwareDecoder's decoder_type has no remaining purpose and can be removed, and the workflow doc can use named decoder types uniformly.

(Superseding my previous comment on this issue, which shell-mangled its backticks.)

[ciaranra]

Status re-check against the current guppy-dem-idle-docs branch, verified by execution. Most of the mechanical tier is already fixed — recording that so nobody re-does it.

defect	status
DemAwareResult not re-exported from pecos.decoders	fixed — present
FusionBlossomDecoder.from_dem not exposed	fixed — present
Registry drift in decoder_dem_requirement	fixed — belief_matching, belief_matching_correlated, belief_find, beamsearch, perturbed, chromobius all resolve; none raise
Stale type stub	fixed — PyMatchingDecoder.__init__(num_nodes, num_observables), TesseractResult.observables_mask, TesseractDecoder.from_dem staticmethod, and DemAwareDecoder/DemAwareResult all present
decode name collision	live — see below
BpOsdDecoder.from_dem missing	live
decode_batch / result-protocol non-uniformity	live, but belongs to #429

The collision reproduces, with a minimal DEM

The original reproduction used a DEM that does not discriminate — on many DEMs both readings coincide, which makes this easy to miss. This one forces them apart: D0 alone flips nothing, D1 alone flips the observable.

dem = (
    "detector D0\n"
    "detector D1\n"
    "logical_observable L0\n"
    "error(0.1) D0\n"
    "error(0.1) D1 L0\n"
)
t = TesseractDecoder.from_dem(dem)
t.decode([1, 0]).observables_mask           # -> 1   sparse: detectors 1 and 0 fired
t.decode_syndrome([1, 0]).observables_mask  # -> 0   dense: only D0 fired

Same class, same argument type, same literal, opposite answers, no exception. PyMatchingDecoder.decode takes the dense form, so moving between the two classes silently changes the meaning of the input and produces wrong logical error rates.

Worth keeping in mind for whoever fixes it: the two encodings are not distinguishable at runtime in general. A list of length num_detectors containing only 0/1 is a valid dense vector and a valid sparse index list, so a heuristic guard cannot close this — it needs a naming or signature change, which is why it is coupled to #429.

Remaining scope

1. Rename or re-sign the colliding decode so the encoding is unambiguous (coupled to Give the DEM-consuming Python decoders a uniform call and result protocol #429's protocol decision).
2. Expose BpOsdDecoder.from_dem(...), which also retires DemAwareDecoder's single-valued decoder_type parameter.

[ciaranra]

Correction to my earlier comments. I claimed "bp_osd" was the only value decoder_type accepts, and that it therefore existed solely to reach the one decoder lacking a from_dem. That is wrong — it came from a careless grep of the bindings rather than from execution.

Verified by running against the installed extension:

decoder_type	result
bp_osd	works
bp_lsd	works
union_find	works
relay_bp	works
min_sum_bp	works
pymatching, fusion_blossom, tesseract, beamsearch, chromobius	ValueError: Unknown decoder type

So decoder_type is a real five-way selector for the LDPC/BP family, not a one-element enum. Removing it would delete four working construction paths. My proposal to retire it was based on a false premise and should be disregarded.

What still stands:

• BpOsdDecoder.from_dem is genuinely missing, as are the equivalents for bp_lsd, union_find, relay_bp and min_sum_bp. The named types exist (BpOsdDecoder, BpLsdDecoder, UnionFindDecoder, RelayBpDecoder, MinSumBpDecoder) but none can be built from a DEM directly, which is why DemAwareDecoder is the only route for that whole family. That is a wider gap than I first described, and it explains the selector's existence rather than condemning it.
• The decode encoding collision is unaffected by any of this and remains the live headline defect.

If the family gained per-type from_dem constructors, decoder_type could then be reconsidered — but that is a five-decoder change, not the trivial cleanup I implied.