Decoding With Ldpc

Do not describe this lane as "the decoder abstraction" for the whole repo. It is the first executable decoder slice, not the universal decoder interface.

Required Artifacts And Assumptions

Expected inputs:

• a DetectorModelBundle,
• a matching TrajectoryBundle,
• an explicit decoder configuration or an explicit decision to use defaults.

Expected outputs:

• DecoderResult.

Assumptions to make explicit:

• whether the detector model is expected to be graphlike,
• whether the detector and trajectory artifacts come from the same parent circuit,
• whether the result is being used as a baseline measurement or only as a smoke-check.

Standard Workflow Checklist

1. Read research-state.yaml and confirm the current decoder-lane assumptions.
2. Check servers/contracts/qec_decoders_mcp.yaml for the intended tool surface.
3. Confirm the detector-model and trajectory artifacts come from the same circuit source.
4. Keep the decoder output in DecoderResult artifacts instead of returning shot-level payloads inline.
5. Record whether the run is only a baseline BPOSD result or part of a broader benchmark story.

Validation Loop

Before closing work:

1. confirm the detector-model and trajectory bundles are compatible,
2. confirm the decoder configuration is recorded,
3. confirm the reported logical error metric is tied to actual sampled observables,
4. confirm the result is described as an ldpc baseline lane, not a repo-wide decoder truth.

Common Issues And Fixes

Artifact mismatch

Problem: the detector-model and trajectory bundles do not share the same source circuit.

Fix: stop and rebuild one of the inputs instead of decoding across incompatible artifacts.

Hidden graphlike assumption

Problem: the decode path silently assumes graphlike detector-model structure.

Fix: record whether undecomposed hyperedges are allowed and keep the default strict unless the task explicitly needs otherwise.

Benchmark overclaim

Problem: one successful BPOSD run gets described like a full decoder evaluation pipeline.

Fix: keep the summary narrow and record what still needs a benchmark lane, transport binding, or multi-decoder comparison.

References

• references/api.md
• references/examples.md
• docs/ARTIFACT_MODEL.md
• docs/TOOLKIT_REGISTRY.md
• servers/contracts/qec_decoders_mcp.yaml