Add detector-error-model fault distance

[ciaranra]

Independent of #415 and #439; branches from dev.

Why

Code distance is not circuit distance. A distance-5 code with a syndrome-extraction circuit that spreads a single fault across multiple data qubits can have fault distance 3, so code distance alone can overstate the protection an implementation actually provides. Nothing in PECOS computed the circuit-level number: check_undetectable_logical_errors enumerates failing fault configurations but never reports a minimum.

This adds the detector-error-model level: the minimum NUMBER OF FAULT MECHANISMS whose XOR-combined effect flips no detector but flips at least one observable. Equivalently, with H the detector-by-mechanism matrix and L the observable-by-mechanism matrix, the minimum |e| with H*e = 0 and L*e != 0 — structurally the same problem as stabilizer-code distance, which is why this lands beside the existing fault-tolerance checkers rather than in a separate silo.

Two methods, explicitly chosen

graphlike_fault_distance is exact when every mechanism flips at most two detectors. It searches the parity-doubled graph, treating every detector and the boundary as a BFS root, taking the minimum over roots and observables. Rooting only at the boundary is NOT exact: a DEM whose minimum cycle avoids the boundary entirely (for example D0 D1 L0 / D1 D2 / D0 D2, distance 3, no boundary edges) leaves the boundary node isolated and the search finds nothing. That case is now a regression test.

exhaustive_fault_distance(max_weight) is correct for any DEM including hyperedges. max_weight is required rather than defaulted, because the cost is combinatorial in the mechanism count and the caller should own that budget.

Mechanisms with hyperedges cause graphlike_fault_distance to fail fast with the hyperedge count rather than silently ignoring them. This is deliberate: DemMatchingGraph silently skips hyperedges, so building on it would have returned quietly wrong distances. The implementation reads to_mechanisms() directly and reuses FaultMechanism::{xor, is_graphlike, is_hyperedge}.

Both methods return the witnessing mechanism set, not just the number, mirroring DistanceResult::min_weight_operator — knowing which faults conspire is the point of the diagnostic.

Tests

Eight Rust tests plus two Python binding tests. Beyond the hand-verifiable cases (distance-1 detector-free mechanism, repetition-code triad, budget below distance, no-logical-error), three are deliberately adversarial:

• the boundary-free cycle above, which the boundary-only formulation gets wrong
• a hyperedge DEM whose only witness REQUIRES the hyperedge, proving hyperedges are not dropped
• a multi-observable DEM where L0 has no witness and L1 does, which a search hardcoded to L0 would miss

The strongest guard is a seeded property test: 512 randomly generated small graphlike DEMs, asserting the two methods agree on both the distance and whether a solution exists. Fixture-based tests alone shared a blind spot with the original design (every one happened to contain a boundary edge); cross-validating an exact special case against a general reference catches that class of error rather than one instance of it.

Verified by mutation: restricting the BFS roots back to boundary-only fails both the boundary-free regression test and the property test.

Verification

• cargo test -p pecos-qec: no failures
• uv run --frozen pytest .../test_fault_distance.py: 2 passed
• just build-debug, just lint (new files staged first so pre-commit sees them): clean

[ciaranra]

Folded into #415 — the commit is now on code-distance-rust and verified there alongside the rest of the distance work. Closing to keep review in one place.