QECTOR Decoder v3 — Certified Proof Suite

Executable proof suite certifying qector-decoder-v3==1.0.0 (Rust/PyO3) against the normative QECTOR Decoder v3 Reference Manual v1.0.0 (DOI 10.5281/zenodo.21941046).

Every test is a transcribed proof obligation from the manual. The pure-Python ground truth (the specification) is inlined in a single file; the live wheel installed from PyPI is the implementation under test. No MCP server setup, no plugin manifests, no Workbench app.

---

Quick start

Prerequisites: Python 3.9+ and internet access to pypi.org.

python test_qector_decoder_v3_proofs.py

One command performs the full certified workflow:

1. Creates a fresh, isolated .venv (with layered fallbacks: venv, venv --without-pip + ensurepip, virtualenv, system-site venv).
2. Installs from the public PyPI index only: qector-decoder-v3==1.0.0, numpy, pytest (--force-reinstall --no-cache-dir --only-binary=:all:), plus reportlab as a best-effort artifact dependency.
3. Verifies the environment before testing: the interpreter is a real venv (sys.prefix != sys.base_prefix), distribution metadata equals 1.0.0 exactly, and the imported module resolves inside that venv.
4. Re-runs this file with the venv interpreter (portable equivalent of activation — works from paths containing spaces, on any shell).
5. Executes all 83 proofs against the supplied reference manual.
6. Writes hash-anchored evidence to proof_artifacts/.

A run exits 0 only when tests pass, the live wheel verifies inside the isolated venv, and the manual is present and valid; otherwise it exits non-zero.

Repository layout

Path	Purpose
test_qector_decoder_v3_proofs.py	Single-file bootstrap + ground truth + 83-proof suite
QectorDecoder_v3_Reference_Manual_v1.0.0.pdf	Normative reference manual (SHA256-anchored into evidence)
proof_artifacts/	Certified evidence from the verified run
requirements.txt	Conventional pre-installed test dependencies
pyproject.toml	Project metadata, pytest configuration, Nox defaults
noxfile.py	Automated check sessions (checks, syntax, tests, runner)
.gitignore	Excludes local environments and caches

Proof coverage

Proof obligation	Manual section
Thm 1 — Syndrome faithfulness ⇔ residual in ker(H)	§3.1
Thm 2 — Logical-error criterion: ker \ im(Hᵀ)	§3.2
Thm 3–4 — Path-flipping faithfulness of MWPM	§3.3, §5.3
Thm 5–7 — Sparse blossom region growth / tight edges	§6.2–§6.6
Thm 8–10 — Cluster parity, peeling correctness, linear work	§7.1–§7.3
Thm 11 — OSD residual-solve faithfulness	§8.2
Thm 12 — Ambiguity-component direct sum	§9.2
Thm 13 — Space-time detector-difference telescope	§10.1–§10.2
Thm 14 — Routing structural guard (graphlike)	§11.1
Thm 15 — Two-stage CSS feed-forward	§12.1
Thm 16 — GPU/CPU bit-identity determinism lemmas	§13.2
E.1 — Steane [[7,1,3]] syndrome	Appx E.1
E.2 — Wilson score interval	Appx E.2
E.3 — DEM collapse & weight	Appx E.3
E.4 — Two-stage CSS with matrices	Appx E.4

Additional worked examples: rotated surface d=3 structure (§2.8), ring d=5 minimum-weight arc (§5.4), repetition d=5 boundary cases (§7.5), adaptive-k sparsification (§5.5), streaming truncation bound (§10.3), GPU workspace strides 6N+1+4E / 5N+E (§13.4), box-plus kernel φ involution (Table 8.1).

Live-wheel checks include: stable API surface, syndrome faithfulness of every decoder on every single-qubit error of seven graphlike families (repetition, ring, rotated/unrotated surface, toric, heavy-hex, color), weighted decoding, determinism, hypergraph rejection, and the wheel-native MCP server entry point.

CLI options

Flag	Effect
(none)	Fresh venv + live PyPI install + certified run (default)
--fresh	Force venv recreation and reinstall
--reuse-venv	Keep an existing verified .venv
--bootstrap	Bootstrap explicitly without forcing recreation
--no-bootstrap	Diagnostic mode; skips venv creation, never certifies
--allow-missing-live	Run available proofs without the wheel; not certified
--output-dir DIR	Artifact directory (default proof_artifacts)
-v	Verbose unittest output
--no-banner / --no-color	Suppress banner / ANSI colours

Pre-installed environment

python -m pip install -r requirements.txt
python -m pytest test_qector_decoder_v3_proofs.py -q

Without direct execution, live-wheel tests skip cleanly when the package is absent; pure ground-truth obligations always run (dependency-free).

Nox automation

noxfile.py provides reproducible check sessions (configured in pyproject.toml, default session checks = syntax + tests):

python -m pip install nox
nox -s checks    # syntax + pytest in isolated virtualenvs
nox -s runner    # full certified CLI workflow (fresh venv, live PyPI)

Certified evidence

proof_artifacts/ contains:

File	Description
certified_report.pdf	Human-readable certification report with coverage table
certified_report.md	Same report in Markdown
certified_proof.json	Machine-readable results, environment, digests, artifact list
certified_proof.json.sha256	SHA256 sidecar of the final JSON bytes
*.svg / *.png	Faithfulness matrix, Wilson interval, workspace strides charts

The committed evidence records: 83/83 passed, 0 failed, 0 errors, 0 skipped; live wheel qector-decoder-v3==1.0.0 installed from https://pypi.org/simple inside an isolated venv; platform and interpreter; manual SHA256 ebb77e6462b1fd8672e5f5a61cf381e184dab6073f7590b85427a1d0e3382ddc.

Verify the sidecar yourself:

sha256sum -c proof_artifacts/certified_proof.json.sha256   # Linux/macOS

Get-FileHash proof_artifacts\certified_proof.json -Algorithm SHA256   # Windows

Platform support

• Windows — fully exercised end-to-end (fresh venv, live PyPI, 83/83).
• macOS / Linux — runner is cross-platform by construction (os.name path handling, UTF-8-safe output, POSIX symlink-safe handoff); certification additionally requires a compatible qector-decoder-v3==1.0.0 binary wheel. If none exists, the runner stops rather than silently substituting packages.
• GPU-specific manual claims remain hardware-scoped; CPU-only machines still execute the complete portable suite.

Citation

@techreport{qector_decoder_v3_manual_1_0_0,
  title       = {QECTOR Decoder v3 Reference Manual},
  version     = {1.0.0},
  author      = {Lessard, Guillaume},
  institution = {iD01t Productions},
  year        = {2026},
  doi         = {10.5281/zenodo.21941046},
  url         = {https://doi.org/10.5281/zenodo.21941046}
}

Author: Guillaume Lessard — ORCID 0009-0000-3465-3753 · iD01t Productions

License

Source-available. Free for academic, personal and non-commercial research. Commercial use requires a paid licence: https://qector.store/pricing

Contact: admin@qector.store · https://www.qector.store