Repository navigation
QEC v177.1 — Sparse Qutrit Construction and Opt-in Research Witnesses
Release notes · 19 October 2026
This release combines a behavior-preserving exact-qutrit constructor optimization with two opt-in research experiments: binary CSS presentation witnesses and synthetic classical syndrome-delivery replay. It preserves the existing decoder contracts and separates measured construction costs, exact algebraic checks, synthetic transport timing, and physical claims.
Release scope
These notes cover every commit after the latest published release, v177.0, through PR #609. The baseline release was published on 14 October 2026 at 14:25:42 UTC and resolves to 178077246e615bbada8589d0637ac75157cdc2f0. The proposed release target is merge commit ae85f98d877f982525a600f432bfafba71b3a5cc, merged on 19 October 2026 at 06:45:38 UTC.
The complete comparison contains seven commits, including two merge commits, across 17 changed files. The two included pull requests are #608 and #609. There are no additional intervening changes in this range.
Suggested designation: v177.1. This continues the repository's incremental milestone-style release numbering for a scoped, compatible addition following v177.0. It is a proposed label, not a published tag or a package-version change. The unchanged package metadata still reports 173.0.0; release labels, contract milestones, and package metadata must not be treated as interchangeable. No tag, release, or package update is created by these notes.
Highlights
- Faster bounded-error syndrome-table construction for exact
QutritStabilizerCodeinstances, with scalar-equivalent ordered tables and correction behavior. - Exact, bounded GF(2) witnesses for supplied binary CSS generator-basis changes and a shared qubit permutation.
- Deterministic fragmentation, integer delay/jitter, ordered syndrome reassembly, and comparison of actual correction outputs from the same decoder callback.
- Source-bound synthetic examples using a Steane CSS presentation and the unchanged reference BP decoder on all four syndromes of a three-bit repetition check.
- Stronger receipt-isolation regression tests and strict replay/input-validation boundaries without expanding decoder-promotion authority.
Exact qutrit construction optimization
PR #608 precomputes immutable one-site GF(3) syndrome contributions for each eligible decoder construction, then combines contributions only from nonzero error sites. The plan is local to that construction; there is no global or code-name-keyed cache.
The optimization preserves the existing Pauli enumeration, insertion order, first representative for each syndrome, collision row-span checks, immutable mapping, validation and max_weight behavior. Public scalar syndrome calculation and decode()/correct() semantics are unchanged. Custom code subclasses keep scalar construction so overridden syndrome behavior is respected. The identity-only case skips plan preparation.
For n sites, r generators and an error of weight w, the helper's per-candidate syndrome work is O(n + r·w), including scanning the x/z vectors. One-time preparation is O(n·r) in time and space. Candidate allocation, enumeration, table storage and collision checks remain separate costs. This is not an O(r·w)-only end-to-end constructor.
Construction benchmark
The new benchmark script includes an independent copy of the original scalar constructor as its comparison oracle. Before timing, it checks ordered table equality, table immutability, complete decode-result equality, and successful correction for 3,805 bounded errors across five workloads. The reference inherits unchanged correction and stabilizer operations; it is not a second independent implementation of the entire decoder.
The retained single-host observation used nine latency samples, three separate allocation samples, and ten correction-batch repeats. Scalar/live median constructor ratios were:
| Workload | Scalar/live median construction ratio |
|---|---|
| Cyclic five | 1.54× |
| Shor nine | 1.27× |
| Ternary Golay eleven | 2.24× |
| Small k=0 control | 1.05× |
| Zero-weight control | 0.95× |
Ratios above one mean faster live construction in that particular run. The shared host was also running regression suites, and near-one control ratios are noise-sensitive. The plan slightly increases memory use. Reused correction is unchanged. These results do not establish frame-error-rate improvements, BP convergence improvements, physical performance, steady-state throughput, or whole-application speedups. See the benchmark methodology and limits.
Binary CSS presentation witnesses
PR #609 adds qec.experiments.css_equivalence, an explicitly imported Layer-5 research module. It accepts unsigned binary X/Z check matrices, invertible row-basis transforms for each sector, a shared qubit permutation, and optional X/Z error samples.
- Computes the transformed presentations with the explicit convention
new[j] = old[permutation[j]]. - Checks CSS commutation, exact GF(2) ranks, logical-qubit count and codespace dimension, plus syndrome covariance for every supplied error sample.
- Supports empty and redundant check sectors while rejecting malformed shapes, noninvertible transforms, invalid permutations and nonbinary values. Inputs use exact Python integer bits without implicit modulo reduction or numeric coercion.
- Bounds inputs to 256 qubits, 128 checks per sector and 256 error samples.
- Emits canonical JSON-safe witnesses and verifies them by rebuilding the complete expected artifact from separately supplied trusted inputs. Rehashing changed claims cannot substitute for replay.
This validates a supplied presentation witness, not arbitrary code-equivalence search. The hash identifies the presentation and ordered samples, not an equivalence class. Signed stabilizer phases, general local-Clifford equivalence, GF(3) and ququart generalizations are outside scope. Row-basis changes can alter check weights and Tanner-graph degrees; no live graph or decoder is mutated. Code distance, decoder performance and physical behavior are not measured. Empty error samples make no sampled-syndrome claim.
Source: CSS witness implementation.
Synthetic syndrome-delivery replay
The new qec.experiments.syndrome_delivery module takes immutable syndrome traces and delivery plans. Contiguous fragment widths cover each syndrome; explicit base delays and a frame-by-fragment jitter matrix determine arrival events. Arrivals are sorted deterministically and frames are reassembled in their original order, including when later frames arrive first.
The harness invokes the same caller-supplied callback separately on baseline and replay inputs and compares its actual exact-binary correction outputs. It retains input/output mismatch indices, fragment events, timing records and modeled deadline misses. Stateful callbacks can produce mismatches, which are reported rather than suppressed. Callback exceptions propagate.
Timing uses a declared serial decoder cost and emission-relative deadlines in integer ticks. Completion exactly at the deadline is on time; late frames still decode. Tick values have no implicit physical unit. Callback execution time is not measured, and the model uses no wall clock, sleep, network or real-time guarantee. Empty traces are explicitly vacuous.
Inputs are bounded by frame, width, total-bit, partition, fragment and tick limits. Frozen inputs are reconstructed and revalidated before use; a frozen dataclass is not treated as a trust boundary. Transport inputs and modeled times are validated before callbacks execute. Receipt validation re-executes both paths against independently supplied inputs and callback settings, then compares the exact expected schema.
The callback must be deterministic and side-effect-free. The harness does not sandbox it or prove purity, decoder correctness, origin authenticity, or performance improvement.
Source: delivery implementation.
Reproducible synthetic evidence
The new fixture generator and canonical fixture record inputs, outputs, selected source hashes, versioned research references and explicit claim limits.
- The CSS example is a locally constructed Steane presentation with the zero error and all single-site X/Z errors.
- Delivery examples invoke unchanged reference BP with fixed three-bit repetition checks, LLR values of 2.0, at most 20 iterations and OSD-0 postprocessing, covering all four two-bit syndromes.
- Zero-delay and out-of-order delayed delivery preserve correction bits. In the delayed example, the declared model changes deadline misses from zero on the baseline to four on replay.
- The integration test independently checks that the correction bits reproduce all four supplied syndromes. The comparison does not establish logical-failure rates, iteration-count equivalence or a general decoder theorem.
Source hashes bind only the listed bytes. They do not establish a complete dependency closure, runtime attestation, authenticated provenance, or scientific correctness. Historical fixtures remain untouched.
Compatibility and trust-boundary changes
- No public qutrit API change or correction-semantic change is introduced. The only decoder-source change is the narrowly approved qutrit constructor optimization in #608.
- #609 does not modify protected decoder source. Importing QEC does not activate the experiments; the command registry, runtime activation, native authority and decoder-promotion rules are unchanged.
- Architecture documentation and
CLAUDE.mdrecord the #608 exception without granting future optimization or runtime-promotion authority. - Receipt-isolation tests replace a commit-adjacency assumption with direct decoder filename/byte snapshots around receipt construction and validation, including addition, deletion, mutation and rename negative controls. Static no-decoder-import checks remain.
- New research validators reject malformed or rehashed artifacts through exact reconstruction and bounded expected-schema comparison. These are validation and isolation safeguards; this release does not announce a CVE or claim to resolve a separately identified production vulnerability.
- Python remains 3.10 or later, with NumPy and SciPy as core dependencies. Package metadata, dependency declarations and entry points are unchanged.
Verification and review
PR #608 evidence
The merged PR's verification record reports:
- 31 focused tests, including all 3,723 bounded errors for cyclic five, Shor nine and Golay eleven.
- 240 held-out dense graph-state cases matching scalar ordered tables or exact failure types/messages, including 96 collision rejections.
- Final local regression: 20,803 passed / 19 skipped.
- Exact-head hosted regression: 20,804 passed / 18 skipped; Docker regression: 20,802 passed / 20 skipped; Proof HTML passed. Skip differences reflect environment capabilities.
- Independent baseline-module review found no correctness blocker; 16 receipt-boundary tests passed independent review. Final-head Codex review reported no major issues.
These are #608-stage results, not additional tests to sum into the later full-suite count.
PR #609 evidence
The merged PR's verification record reports the final source tree b038c77745a3ac572005582bf5d4ec9c842733a6, shared by reviewed head c78255e5aea288e8902439e2ca470bb9721b8c67 and the release-target merge:
- Full local Python suite: 21,136 passed / 16 skipped / 4 subtests passed, with three existing pytest deprecation warnings, in 568.72 seconds.
- Focused experiment, integration and README checks repeated three times: 277 per run, 831 passing executions total.
- Independent review: 1,458 timing-oracle combinations, plus a final 270-test focused suite; source hashes and fixture replay verified with no outstanding findings reported.
- Fixture generator
--checkandgit diff --checkpassed. - Local Rust and Docker executables were unavailable; no Rust/TUI code changed. Do not interpret local Python results as a local Rust or Docker run.
- Exact-head hosted full-repository regression: 21,074 passed / 18 skipped / 4 subtests passed, with four warnings, in 344.57 seconds. This is a separate environment-specific run, not the local 21,136-test result above.
- Exact-head switching checks: full regression and all six native CLI round trips passed.
- Codex code and security reviews both completed without findings on exact head
c78255e5aea288e8902439e2ca470bb9721b8c67. - Exact-head container regression: 21,072 passed / 20 skipped / 4 subtests passed, with four warnings, in 497.52 seconds. The full hosted/container workflow completed successfully.
- Post-merge host and container verification also completed successfully on release target
ae85f98d877f982525a600f432bfafba71b3a5cc: host 21,074 passed / 18 skipped / 4 subtests passed, with four warnings, in 441.54 seconds; container 21,072 passed / 20 skipped / 4 subtests passed, with four warnings, in 536.69 seconds. - Post-merge switching checks and Proof HTML passed. The merge tree remains identical to the tested/reviewed PR-head tree.
- Sourcery's review-budget limit prevented an additional review; its generated summary is not counted as completed independent review evidence.
Passing finite tests and reviews support the stated contracts and examples; they do not prove universal decoder correctness or physical quantum protection.
Carried baseline and scientific limits
The v177.0 acoustic syndrome transport and verified-correction system, exact qutrit/ququart foundations, historical governance receipts, six native switching architectures and cross-era replay remain the inherited baseline. None should be advertised as newly introduced by #608 or #609. Existing acoustic exporter/security fixes and the SciPy reproducibility repair in #602 belong to v177.0, not this release interval.
The new examples are locally constructed synthetic inputs, not the cited papers' experimental datasets or reproduced benchmarks. The research document cites arXiv:2610.18218v1 as motivation for distinguishing coordinate transformations from generator representations, and arXiv:2610.22112v1 as motivation for explicit comparison assumptions. This release implements neither the first paper's general equivalence-search method nor Patchwork lattice-surgery compilation or space-time partitioned decoding. Classical fragment transport does not substitute for those algorithms.
No new acoustic physical proof, hardware latency measurement, logical-error-rate advantage, quantum-state transfer, physical fault tolerance or automatic decoder promotion is established. GF(3)/ququart witness extensions and Brillouin-fibre spectral-response fixtures remain deferred; the latter require their own units, uncertainty and source-data contract. The current README keeps the QEC OS runtime/benchmark programme deferred to v193.x.
See research scope and deferred work.
Reproduce the checks
From a checkout of the release-target commit, with the declared Python dependencies installed:
python -m pip install -e '.[dev]'
python scripts/generate_qec_research_evidence.py --check
python -m pytest -q tests/test_css_equivalence.py tests/test_syndrome_delivery.py tests/test_qec_research_evidence.py
python -m pytest -q tests/test_qutrit_sparse_construction.py tests/test_decoder_fast_path_equivalence_receipts.py
python -m pytest -qFor an optional local construction measurement, save a new result separately:
python scripts/benchmark_qutrit_construction.py --samples 9 --memory-samples 3 --correction-repeats 10 > qutrit-construction-local.jsonUse the research generator without --check only when intentionally regenerating its new fixture after reviewed source changes. Preserve historical evidence and do not replace source-bound observations with machine-dependent results.
Complete commit inventory
c4b78f8— Precompute sparse bounded-error qutrit syndromes.56bfa0d— Document the approved constructor exception and enforce receipt isolation.25b18fe— Merge PR #608.01d44d4— Add bounded binary CSS presentation witnesses and metamorphic tests.0c0c20f— Add bounded synthetic syndrome-delivery replay with delay witnesses.c78255e— Bind synthetic research evidence to sources and unchanged reference BP.ae85f98— Merge PR #609.
Full changelog: v177.0 through the proposed release target.