fix: import must not depend on the native core's exact symbol set

The v0.6.9 tag build failed its pre-publish smoke test:

  AttributeError: module 'qector_decoder_v3.qector_decoder_v3'
  has no attribute 'py_generate_parity_check_matrix'

Nothing reached PyPI -- the smoke gate added in 0.6.8 caught it, which is
exactly what it exists for.

Cause: release wheels compile the Rust core from the RUST_SRC_B64_* secrets
bundle, which can lag this repo's Python layer. `py_generate_parity_check_matrix`
is registered in the repo's lib.rs but absent from the bundle's older core. Six
utility lookups in __init__ were unguarded, so a symbol-set mismatch killed
`import qector_decoder_v3` outright -- the same failure mode that made every
v0.6.7 wheel unimportable.

Unlike the class guards (which stub and raise on use), these six have exact
pure-Python equivalents, so a wheel built against an older core keeps FULL
functionality rather than degrading. Each fallback mirrors src/utils.rs
one-to-one including the edge cases: out-of-range qubits dropped rather than
raising, n_qubits inferred as max+1, surface distance >= 2 rejected, repetition
distance 0 -> empty.

python/tests/test_native_fallbacks.py locks both directions: every fallback is
byte-identical to its native counterpart on this build (31 tests over surface /
ring / toy / repetition / edges / parity-matrix incl. edge cases), and
`_native_or` returns the fallback when the symbol is missing while preferring
the compiled one when present.

Verified against a simulated older core -- the native module with those six
symbols stripped -- which reproduces the CI traceback exactly and now imports
clean with all six resolved via fallback.

Gates: ruff check + format clean; 139 passed across the fallback, release-import,
comprehensive and new-modules suites.

Author: qectorlab

python/qector_decoder_v3/__init__.py

@@ -56,12 +56,106 @@ def __repr__(self):
 _RustSparseBlossomDecoder = _guard("SparseBlossomDecoder")
 _RustHybridDecoder = _guard("HybridDecoder")
 _RustHybridCascadeDecoder = _guard("HybridCascadeDecoder")
-py_check_to_edges = _native_module.py_check_to_edges
-py_generate_surface_code_checks = _native_module.py_generate_surface_code_checks
-py_generate_toy_code_checks = _native_module.py_generate_toy_code_checks
-py_generate_ring_code_checks = _native_module.py_generate_ring_code_checks
-py_generate_repetition_code_checks = _native_module.py_generate_repetition_code_checks
-py_generate_parity_check_matrix = _native_module.py_generate_parity_check_matrix
+# ---------------------------------------------------------------------------
+# Utility functions: native when available, exact pure-Python fallback when not.
+#
+# Release wheels compile the Rust core from the RUST_SRC_B64_* secrets bundle,
+# which can lag the Python layer in this repo. v0.6.9's first tag build died at
+# import because `py_generate_parity_check_matrix` was registered in the repo's
+# lib.rs but absent from the bundle's older core -- the same failure mode that
+# made every v0.6.7 wheel unimportable. Import must never depend on the native
+# module's exact symbol set.
+#
+# Unlike the class guards above (which stub and raise on use), these six have
+# exact pure-Python equivalents, so a wheel with an older core keeps FULL
+# functionality. Each fallback mirrors src/utils.rs one-to-one, including edge
+# cases (out-of-range qubits dropped, n_qubits inferred as max+1, surface
+# distance >= 2, repetition distance == 0 -> empty). Equivalence against the
+# native implementations is locked by python/tests/test_native_fallbacks.py.
+# ---------------------------------------------------------------------------
+
+
+def _py_check_to_edges(check_to_qubits):
+    edges = []
+    for qubits in check_to_qubits:
+        if len(qubits) < 2:
+            continue
+        for i in range(len(qubits) - 1):
+            edges.append((int(qubits[i]), int(qubits[i + 1])))
+    return edges
+
+
+def _py_generate_ring_code_checks(distance):
+    n_qubits = distance * distance
+    return [[i, (i + 1) % n_qubits] for i in range(n_qubits)], n_qubits
+
+
+def _py_generate_surface_code_checks(distance):
+    if distance < 2:
+        raise ValueError("distance must be >= 2")
+    d = distance
+
+    def q(row, col):
+        return (row % d) * d + (col % d)
+
+    checks = []
+    for row in range(d):
+        for col in range(d):
+            checks.append([q(row, col), q(row, col + 1), q(row + 1, col), q(row + 1, col + 1)])
+    for row in range(d):
+        for col in range(d):
+            checks.append([q(row, col), q(row, col + d - 1), q(row + d - 1, col), q(row + d - 1, col + d - 1)])
+    return checks, d * d
+
+
+def _py_generate_toy_code_checks(distance):
+    n = distance
+    checks = []
+    for _ in range(2):
+        for row in range(n):
+            for col in range(n):
+                q0 = row * n + col
+                q1 = row * n + ((col + 1) % n)
+                q2 = ((row + 1) % n) * n + col
+                q3 = ((row + 1) % n) * n + ((col + 1) % n)
+                checks.append([q0, q1, q2, q3])
+    return checks, n * n
+
+
+def _py_generate_repetition_code_checks(distance):
+    if distance == 0:
+        return [], 0
+    return [[i, i + 1] for i in range(distance - 1)], distance
+
+
+def _py_generate_parity_check_matrix(check_to_qubits, n_qubits=None):
+    import numpy as np
+
+    n_checks = len(check_to_qubits)
+    max_q = max((int(q) for qs in check_to_qubits for q in qs), default=0)
+    if n_qubits is None:
+        n_qubits = max_q + 1
+    h = np.zeros((n_checks, n_qubits), dtype=np.uint8)
+    for ci, qs in enumerate(check_to_qubits):
+        for q in qs:
+            if int(q) < n_qubits:
+                h[ci, int(q)] = 1
+    return h
+
+
+def _native_or(name, fallback):
+    """Prefer the compiled implementation; fall back without losing function."""
+    return getattr(_native_module, name, fallback)
+
+
+py_check_to_edges = _native_or("py_check_to_edges", _py_check_to_edges)
+py_generate_surface_code_checks = _native_or("py_generate_surface_code_checks", _py_generate_surface_code_checks)
+py_generate_toy_code_checks = _native_or("py_generate_toy_code_checks", _py_generate_toy_code_checks)
+py_generate_ring_code_checks = _native_or("py_generate_ring_code_checks", _py_generate_ring_code_checks)
+py_generate_repetition_code_checks = _native_or(
+    "py_generate_repetition_code_checks", _py_generate_repetition_code_checks
+)
+py_generate_parity_check_matrix = _native_or("py_generate_parity_check_matrix", _py_generate_parity_check_matrix)
 try:
     run_mcp_server = _native_module.run_mcp_server
 except AttributeError:

python/tests/test_native_fallbacks.py

@@ -0,0 +1,165 @@
+"""Pure-Python fallbacks must be byte-exact equivalents of the native utils.
+
+Release wheels compile the Rust core from the RUST_SRC_B64_* secrets bundle,
+which can lag the repo's Python layer. The v0.6.9 tag build died at import
+because `py_generate_parity_check_matrix` existed in the repo's lib.rs but not
+in the bundle's older core -- the same class of failure that made every v0.6.7
+wheel unimportable. `__init__` now resolves these six utilities via
+`_native_or(name, fallback)`.
+
+Two contracts locked here:
+
+1. On a build where the native implementations exist (this machine), each
+   fallback produces *identical* output -- so a wheel that falls back loses
+   nothing.
+2. `_native_or` actually returns the fallback when the symbol is absent, so
+   import survives an older core.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+import qector_decoder_v3 as qd
+
+_HAS_NATIVE = all(
+    hasattr(qd._native_module, n)
+    for n in (
+        "py_check_to_edges",
+        "py_generate_surface_code_checks",
+        "py_generate_toy_code_checks",
+        "py_generate_ring_code_checks",
+        "py_generate_repetition_code_checks",
+        "py_generate_parity_check_matrix",
+    )
+)
+
+needs_native = pytest.mark.skipif(
+    not _HAS_NATIVE, reason="native utils absent in this build; equivalence needs both sides"
+)
+
+
+def _norm_checks(pair):
+    """Normalise (checks, n_qubits) across native (tuples/uints) and Python (lists/ints)."""
+    checks, nq = pair
+    return [[int(q) for q in c] for c in checks], int(nq)
+
+
+@needs_native
+@pytest.mark.parametrize("d", [2, 3, 5, 7])
+def test_surface_checks_equivalent(d):
+    assert _norm_checks(qd._py_generate_surface_code_checks(d)) == _norm_checks(
+        qd._native_module.py_generate_surface_code_checks(d)
+    )
+
+
+@needs_native
+def test_surface_rejects_distance_below_two():
+    with pytest.raises(ValueError):
+        qd._py_generate_surface_code_checks(1)
+    with pytest.raises(ValueError):
+        qd._native_module.py_generate_surface_code_checks(1)
+
+
+@needs_native
+@pytest.mark.parametrize("d", [1, 2, 3, 5, 8])
+def test_ring_checks_equivalent(d):
+    assert _norm_checks(qd._py_generate_ring_code_checks(d)) == _norm_checks(
+        qd._native_module.py_generate_ring_code_checks(d)
+    )
+
+
+@needs_native
+@pytest.mark.parametrize("d", [1, 2, 3, 5])
+def test_toy_checks_equivalent(d):
+    assert _norm_checks(qd._py_generate_toy_code_checks(d)) == _norm_checks(
+        qd._native_module.py_generate_toy_code_checks(d)
+    )
+
+
+@needs_native
+@pytest.mark.parametrize("d", [0, 1, 2, 5, 9])
+def test_repetition_checks_equivalent(d):
+    assert _norm_checks(qd._py_generate_repetition_code_checks(d)) == _norm_checks(
+        qd._native_module.py_generate_repetition_code_checks(d)
+    )
+
+
+EDGE_CASES = [
+    [[0, 1], [1, 2], [2, 3]],
+    [[0, 1, 3, 4], [1, 2, 4, 5]],  # weight-4 checks -> consecutive pairs
+    [[7]],  # single-qubit check contributes no edges
+    [[0, 5]],  # sparse indices
+]
+
+
+@needs_native
+@pytest.mark.parametrize("c2q", EDGE_CASES)
+def test_check_to_edges_equivalent(c2q):
+    py = [(int(a), int(b)) for a, b in qd._py_check_to_edges(c2q)]
+    native = [(int(a), int(b)) for a, b in qd._native_module.py_check_to_edges(c2q)]
+    assert py == native
+
+
+PARITY_CASES = [
+    ([[0, 1], [1, 2]], 3),
+    ([[0, 1], [1, 2]], None),  # n_qubits inferred as max+1
+    ([[0, 3]], None),
+    ([[0, 5]], 3),  # out-of-range qubit dropped, not an error
+    ([[0, 1, 3, 4], [1, 2, 4, 5]], 9),
+]
+
+
+@needs_native
+@pytest.mark.parametrize(("c2q", "nq"), PARITY_CASES)
+def test_parity_check_matrix_equivalent(c2q, nq):
+    py = qd._py_generate_parity_check_matrix(c2q, nq)
+    native = np.asarray(qd._native_module.py_generate_parity_check_matrix(c2q, nq))
+    assert py.dtype == np.uint8
+    assert py.shape == native.shape
+    assert np.array_equal(py, native)
+
+
+def test_native_or_falls_back_when_symbol_missing(monkeypatch):
+    """The exact CI-wheel condition, exercised through the real resolver.
+
+    `_native_or` reads from the module-level `_native_module`, so swap that for
+    a core with no utils registered and confirm the fallback is what comes back.
+    """
+
+    class _OlderCore:
+        pass  # the bundle's core: none of the six utils exist
+
+    monkeypatch.setattr(qd, "_native_module", _OlderCore())
+
+    sentinel = object()
+
+    def fallback():
+        return sentinel
+
+    resolved = qd._native_or("py_generate_parity_check_matrix", fallback)
+    assert resolved is fallback, "_native_or must return the fallback for a missing symbol"
+    assert resolved() is sentinel
+
+
+@needs_native
+def test_native_or_prefers_the_compiled_symbol():
+    """When the core does provide it, the native implementation must win."""
+
+    def fallback():  # pragma: no cover - must never be selected here
+        raise AssertionError("fallback selected despite a native symbol being present")
+
+    resolved = qd._native_or("py_generate_parity_check_matrix", fallback)
+    assert resolved is qd._native_module.py_generate_parity_check_matrix
+
+
+def test_fallbacks_faithful_against_decoder():
+    """A fallback-generated code must decode correctly end to end."""
+    checks, nq = qd._py_generate_ring_code_checks(3)
+    dec = qd.UnionFindDecoder(checks, n_qubits=nq)
+    h = qd._py_generate_parity_check_matrix(checks, nq)
+    syndrome = np.zeros(len(checks), dtype=np.uint8)
+    syndrome[0] = 1
+    syndrome[1] = 1
+    corr = dec.decode(syndrome)
+    assert np.array_equal((h @ corr) & 1, syndrome)