v2.2.1

Source commit: 7330222ed68fbc577e950f3b99d7c4d3b15fcde6

Required CI: https://github.com/timfromhcs/CQ-HECS/actions/runs/40290751381

CQ-HECS Release Notes

Version: 2.2.1
Release date: 2026-10-26
License: Apache 2.0
Repository: https://github.com/timfromhcs/CQ-HECS

The release workflow copies this file to
dist/RELEASE_NOTES_v2.2.1.md, prepends the exact source commit and required
CI run, and appends the SHA256 values of the final assets. The content
describes the code in this tree.

---

1. What this release is

v2.2.1 is a patch release on top of v2.2.0. It fixes correctness and
refusal defects in the Python QASM reader, capability routing, Qiskit
measurement handling, Path D observable parsing and Path C resource accounting.
It adds no new simulator, no new exactness claim and no GPU acceleration.

The four CPU paths keep their scope:

Path	Method	Correctness class	Supported width & output
A	Stabilizer tableau (Gottesman–Knill)	Exact GF(2) symplectic arithmetic	300+ qubits for Clifford circuits; full-register counts
B	Stabilizer-rank decomposition	Algebraically exact decomposition, float64 arithmetic	Up to 22 qubits (implementation limit); scales with T-count
C	MPS without deliberate truncation	No bond cut-off; float64 noise floor; no certified roundoff bound	500-qubit routing/sampling ceiling; RAM budget enforced
D	Sparse-Pauli dynamics	Certified bound on requested expectation values	200+ qubits; selective observables; no certified joint distribution

---

2. Fixed in 2.2.1

One strict QASM contract for Python and native

• The Python reader is no longer a permissive Qiskit-based loader. It is a
  strict, line-oriented OpenQASM subset parser with the same structured
  {line, category, message} errors as src/qasm_parser.cpp.
• Unknown gates, missing semicolons, undeclared registers, duplicate registers,
  out-of-range indices, bad arity and non-finite angles are rejected before any
  execution. No statement is silently skipped.
• Multiple registers receive global qubit offsets in declaration order:
  qreg a[2]; qreg b[3]; maps b[0] to qubit 2 and the circuit width is 5.
• Whole-register operands expand in arity-sized chunks, matching native
  semantics; a flattened width that is not a multiple of the arity is
  operand_count_mismatch.
• Angles are evaluated by a bounded recursive-descent grammar, never by
  Python eval(). nan, inf, division by zero, **, unbalanced
  parentheses and trailing tokens are rejected.
• Classical-bit remapping is refused explicitly instead of dropping the target.
  Terminal measurements are sorted by qubit; mid-circuit measurements stay at
  their source position and are refused before execution.

Capability-first routing

• Added cqhecs/gate_manifest.py as the single source of truth for gate arity,
  parameters, per-path support and Clifford status. The analyzer, router,
  Qiskit Target and every backend derive their capabilities from it.
• Parameterised gates are classified per angle, not by name or first parameter.
  cp(π/2) is no longer treated as a Path A Clifford gate; it is routed to
  Path C or refused before execution. The same applies to crz, crx, cry,
  cu1, rz, p and u1.
• Removed the false Path A reset capability. reset, mid-circuit
  measurement and classically controlled gates are refused before execution.
• CQHecsBackend.run() requires counts, so a counts request cannot silently
  degrade to Path D expectation values.

Qiskit measurement semantics

• normalize_measurements no longer moves a mid-circuit measurement to the end.
  Such circuits are rejected before simulation.
• Repeated measurements of one qubit into distinct classical bits are
  preserved; non-contiguous classical indices are kept.
• measure_all() and terminal measurements are tested differentially where
  Aer is available.
• The Qiskit Target now lists every implemented path gate (cp, cu1,
  crx, cry, crz, cz, swap, ...) on a conservative linear coupling
  map. Gates without any path remain absent, so transpile(qc, backend=backend)
  cannot emit them.

Path D observables and certification

• Observable strings are parsed as a strict grammar; trailing characters after
  valid tokens are rejected instead of being ignored.
• bool masks, negative masks and masks wider than the system are rejected.
• Duplicate Pauli factors simplify algebraically (Z[i] Z[i] = I).
• Per-observable bounds are reported; aggregate bounds are not invented.
• Marginal samples remain explicitly labelled as not a joint distribution.

Path C resources and numerics

• ram_budget_mb is enforced fail-closed before a state update; a refusal
  preserves the last valid state and reports an atomic diagnostic.
• Process RSS and peak RSS are reported separately from internal NumPy tensor
  bytes (process_rss_mb, process_peak_rss_mb,
  rss_measurement_available). Tensor bytes are never presented as RSS.
• numerical_error_bound remains None. Numerical rank reduction at the
  1e-13 relative threshold is documented separately from a deliberate bond
  cut-off; exact=True means "no deliberate truncation", not symbolic
  exactness.

Tooling and gates

• Added tests/test_hardening_v221.py with focused regressions for every
  contract above, including Python/native differential categories and Qiskit
  transpilation of Path C gates.
• The T-count mutation anchor follows the shared _t_resource classifier.
• The release workflow now refuses to publish unless ci.yml succeeded for the
  exact tagged commit, and it appends the final SHA256 values to the release
  body.

---

3. Compatibility notes

• Python API additions are backwards compatible: cqhecs.gate_manifest is new,
  UnsupportedCircuitInput remains available as an alias of
  UnsupportedCircuitInputError, and existing result fields are unchanged.
• Behaviour that was previously wrong is now refused: cp/crz-style gates
  are no longer offered to Path A; reset, mid-circuit measurement and
  classical conditions raise UnsupportedCircuitError instead of producing a
  plausible but wrong result.
• cq-hecs run accepts the same strict QASM subset as the native qasm
  command. Callers that relied on unknown QASM statements being skipped must
  fix their input.
• The native executor still implements only its documented legacy gate table.
  p, u1, cu1, crx, cry and crz are Python/Path-C only; the
  divergence is an acceptance ceiling, documented in docs/QASM_CONTRACT.md
  §6, not a semantic difference.
• Supported Python remains 3.11–3.14.

---

4. Verification

Local evidence for the release candidate (Windows, MSVC 19.44, CPython 3.14.6,
Qiskit 2.5.1, Aer 0.17.2, Stim 1.16.0):

Gate	Command	Result
Python suite + native	CQ_HECS_REQUIRE_NATIVE=1 python -m pytest tests/ -q	309 passed
Native CTest	ctest --test-dir build -C Release --output-on-failure	14/14 passed
Branch coverage	coverage run --branch --source=cqhecs -m pytest tests/; coverage report --fail-under=70	81 % (gate 70 %)
Mutation harness	python scripts/run_mutation_tests.py	11/11 killed, baseline clean
Fatal-error lint	flake8 ... --select=E9,F63,F7,F82	pass
Version consistency	python scripts/check_version.py	pass
Silent-truncation audit	python scripts/verify_no_silent_truncation.py	pass
Shader verification	python scripts/verify_vulkan_shaders.py	12/12 SPIR-V shaders
Wheel/sdist build	python -m build, twine check dist/*.whl dist/*.tar.gz	pass
Clean-install smoke	fresh venv, cq-hecs version/doctor/run name:bell	pass

GitHub Actions runs the required suite on the exact tagged commit; the release
job waits for that run and links it in the published body. A green run on an
earlier commit is not accepted.

---

5. Artifacts and supply chain

• cqhecs-2.2.1-py3-none-any.whl — pure-Python package (no native extension).
• cqhecs-2.2.1.tar.gz — source distribution.
• cqhecs-sbom.spdx.json — SPDX SBOM generated from the final artifacts.
• sha256sums.txt — SHA256 for every published asset; appended verbatim to the
  release body by the release workflow.

The Python wheel does not contain the native libcq_hecs / cq_hecs.exe
artifacts. Native builds are platform-specific and are not claimed as part of
the wheel. No signed provenance or attestation is claimed unless a workflow run
actually produced and verified one.

---

6. Cloud Build

Status: NOT VERIFIED. cloudbuild.yaml was reviewed, but no Google Cloud
project or credentials were available in the audit environment, so no real
Cloud Build run was started. This is not a passing result. Local tests and
GitHub Actions do not substitute for it.

---

7. Known limitations

1. No physical GPU compute has been verified. The Vulkan loader enumerates a
   device and shaders compile, but no compute dispatch on a physical GPU was
   demonstrated. All verified execution is CPU. Loader availability is not
   PHYSICAL_GPU_COMPUTE_VERIFIED.
2. Path C reports no certified roundoff bound. numerical_error_bound is
   None; discarded singular-value mass is a diagnostic, not a state-error
   bound.
3. exact=True is not symbolic exactness. Numerical rank reduction at
   1e-13 and float64 rounding remain.
4. 500 MPS qubits are a routing ceiling, not an exactness guarantee.
   Entanglement, bond dimension and available memory decide what is feasible.
5. Path B exactness is algebraic, not symbolic. Coefficients are evaluated
   in float64.
6. Path D cannot produce a certified joint distribution. The bound applies
   to the requested observables; joint counts are opt-in and labell...

v2.2.0

CQ-HECS Release Notes

Version: 2.2.0
License: Apache 2.0
Repository: https://github.com/timfromhcs/CQ-HECS

The release workflow copies this file to
dist/RELEASE_NOTES_v<version>.md. The content describes the current code,
not a historical target. No release tag is created by the hardening work
itself; publication requires explicit authorization.

---

1. What this release is

v2.2.0 is a hardening release. It adds structured diagnostics and an
explicit engine classification, and it replaces fail-open code paths and
false-green tests with fail-closed contracts. It adds no new simulator, no
GPU acceleration, and no new exactness claim.

The four CPU simulation paths are unchanged in scope:

Path	Method	Correctness class	Supported width & output
A	Stabilizer tableau (Gottesman-Knill)	Exact (GF(2) symplectic arithmetic)	300+ qubits; full-register counts (Clifford)
B	Stabilizer-rank decomposition	Exact algebra, float64 arithmetic	Up to 22 qubits (implementation limit); scales with T-count
C	MPS, unbounded bond dimension	Exact algebra; no deliberate cutoff; float64 noise floor	300+ qubits (low entanglement); sequential conditional sampling without a dense statevector
D	Sparse-Pauli dynamics	Certified bound on expectation values	200+ qubits; selective observables API

---

2. Fixed in 2.2.0

Native QASM parsing and execution

• The native parser no longer repairs invalid input. Missing semicolons,
  unknown gates, malformed or non-finite angle expressions, out-of-range
  register references and block comments are rejected with a structured
  {line, category, message} error. Previously several of these were accepted
  and a partially interpreted circuit was executed.
• cq_hecs qasm returns exit code 2 for invalid circuit input and emits a
  JSON error document on stdout in --json mode. Diagnostics remain on stderr.
• cq_execute_qasm in the C ABI returns -3 on parse errors and zeroes the
  result structure. cq_get_version() reports the canonical version.
• The native engine is labelled engine_class = legacy_z8_phase_ledger with
  statevector_simulation = false. The version banner derives from
  CQ_HECS_VERSION; the stale hardcoded v4.5.0 output is gone.
• --qubits is enforced as a hard cap.
• test_qasm_contract covers strict parsing and bounded randomized
  robustness; the C-ABI test suite covers invalid-circuit rejection.

Scheduler and resource accounting

• VulkanComputeScheduler.submit_workload() no longer reports
  completed=True for metadata-only submissions. It reports
  planner_only=True; completion requires record_completion(submission, backend). Negative dispatch counts are rejected.
• Timing-jitter harvesting is documented as a deterministic diagnostic, not as
  proof of hardware entropy.
• TieredMemoryGovernor.allocate() raises MemoryError when a page cannot fit,
  instead of silently exceeding the budget.
• JSpaceDelta.reinflate_matrix() validates matrix shapes and labels its
  residual as a diagnostic rather than a certified bound.

Tests that could pass without evidence

• QASM fuzz tests assert the strict parser contract and fail, rather than skip,
  when CQ_HECS_REQUIRE_NATIVE=1 is set.
• Stress, concurrency and SVD tests separate internal accounting from RSS, use
  explicit availability skips, verify independent-instance behaviour, and
  require real truncation measurements.
• The source-level mutation harness applies exact patches to production files,
  runs independent subprocess checks, restores source byte-for-byte, and exits
  non-zero on a broken baseline or a surviving mutant. The maintained set is
  11 mutants; this is a scoped regression gate, not a proof of correctness.

CI and packaging

• CI is split into static/package smoke, pinned Linux native, pinned Windows
  native, Python 3.12–3.14 compatibility, and an ASan/UBSan native job.
• Branch coverage is enforced at a 70 % floor against a measured local
  baseline of 76 %.
• Workflow permissions are least-privilege; test evidence and package artifacts
  are uploaded.
• Supported Python is declared as 3.11–3.14. Python 3.9/3.10 are no longer
  claimed after reaching end of life.
• pyproject.toml uses SPDX license metadata and the canonical version
  surfaces agree across Python, CMake, C ABI, citation and changelog.

---

3. Verification

Local evidence for this tree (Windows, MSVC 19.51, CPython 3.14.6):

• Python: 254 passed with CQ_HECS_REQUIRE_NATIVE=1.
• Python 3.11 pinned lane: 251 passed, 3 explicit skips (native-only tests,
  which CI's native jobs require instead of skipping).
• Native CTest: 14/14 passed.
• Mutation harness: baseline clean, 11/11 killed, exit code 0.
• Branch coverage: 76 % local; CI gate is 70 %.
• Version consistency, silent-truncation audit and SPIR-V verification: pass
  (12/12 shaders).

GitHub Actions for the pushed hardening commit runs the Linux/Windows native
jobs, the ASan/UBSan job, the Python 3.12–3.14 matrix and the package smoke
job. The run link is recorded in research/v2_2/TEST_MATRIX.md after the push.
A green run on an earlier SHA is not evidence for a later commit.

---

4. Known limitations

These are deliberate and documented, not defects to be discovered later.

1. No physical GPU execution has been verified. The Vulkan loader
   enumerates a device and shaders compile, but no compute dispatch on a
   physical GPU was demonstrated. All verified execution is CPU. See
   README.md §9.
2. Cloud Build was not observed. gcloud is not installed in the audit
   environment. Status: BLOCKED, not passed.
3. Path C reports no certified roundoff bound. The discarded singular-value
   mass is exposed as discarded_spectral_mass_diagnostic, but per-rewrite
   masses do not compose into a state-norm bound without propagation analysis
   that is not implemented.
4. Path B exactness is algebraic, not symbolic. The decomposition drops no
   terms, but coefficients are evaluated in float64.
5. Path D cannot produce a certified joint distribution. Its bound applies
   to the requested observables. Joint counts are opt-in and labelled as
   uncertified.
6. The native QASM path is a legacy engine. It is not a general statevector
   simulator and is not a replacement for the four Python paths.

---

5. Upgrading

• cq_hecs qasm now exits 2 on invalid circuit input instead of executing a
  partially parsed circuit. Callers that treated non-zero as a generic failure
  should distinguish parse/usage errors from unresolved simulations.
• The native version banner no longer prints v4.5.0; it reports 2.2.0 from
  the canonical CMake version.
• Scheduler users must call record_completion(); submit_workload() no longer
  claims execution.
• TieredMemoryGovernor.allocate() raises MemoryError instead of overcommitting.
• Python 3.9/3.10 are unsupported; use Python 3.11 or newer.
• The legacy python_bridge/ and python/ packages remain available for
  reference but are not the supported entry point. Use cq-hecs.

v2.1.0

CQ-HECS Release Notes

Current version: see scripts/version.py (single source of truth).
License: Apache 2.0
Repository: https://github.com/timfromhcs/CQ-HECS

The release workflow copies this file to
dist/RELEASE_NOTES_v<version>.md. The content below describes the current
state of the code, not a historical target.

---

1. What this release is

A major capability and correctness release (v2.1.0). This release extends CQ-HECS
to reliably simulate and sample at least 200 qubits for explicitly documented
circuit classes and output types, introduces an MPS-native sequential conditional
sampler avoiding dense $2^n$ statevector allocation, adds a selective observables API
for Path D, accelerates stabilizer symplectic phase accumulation by 10x, and completes
a formal audit of the 372 manuscript families in the OpenAI Math corpus.

Four classical simulation paths, all CPU-based:

Path	Method	Correctness class	Supported Width & Output
A	Stabilizer tableau (Gottesman-Knill)	Exact (GF(2) symplectic arithmetic)	300+ qubits; full-register counts (Clifford)
B	Stabilizer rank decomposition	Exact algebra, float64 arithmetic	Up to 22 qubits (implementation limit); scales with T-count
C	MPS, unbounded bond dimension	Exact algebra; no deliberate cutoff; float64 noise floor	300+ qubits (low entanglement); full-register counts via sequential conditional sampler
D	Sparse-Pauli dynamics	Certified bound on expectation values	200+ qubits; selective observables API

---

2. Correctness work

Fabricated results removed

• Path B substituted a uniform distribution when its rank decomposition
  failed to normalize, and returned {'0'*n: shots} for circuits wider than the
  statevector limit — both reported as exact=True, error_bound=0.0. Both now
  raise.
• Path C returned an all-zeros placeholder beyond its sampling limit. It now
  reports no counts.
• Path A inflated 100 real samples up to the requested shot count for wide
  circuits. It now reports the number of shots actually drawn.
• The legacy python/cq_hecs Qiskit provider returned a fabricated 50/50 counts
  dict when the native engine was absent, with success=True. It now raises.

Correlation loss fixed

Path D sampled each qubit independently from its own <Z_q> marginal and
returned the result as a joint measurement distribution. A Bell state came out
uniform. Path D now reports certified expectation_values — single-qubit Z and
parity Z_q Z_r, which are what actually carry correlation structure. Joint
counts are opt-in and labelled counts_are_joint_distribution=False.

Silently ignored gates fixed

• Path C skipped any gate outside its dispatch chain and discarded singular
  values below an absolute 1e-14 cutoff while still claiming exactness.
• Path B ignored unknown gates, hiding two real bugs: Clifford-angle RZ and
  all RX/RY gates were never applied. RX/RY also used a hardcoded Z
  as their Clifford generator.
• Path D treated unrecognised gates as the identity. CZ, SWAP, RX and RY
  all took that path and returned wrong answers.
• Path A never called its own apply_cz, and dropped Clifford-angle rotations.

Latest hardening round

• The CZ rule in Path D was algebraically wrong. CZ†(X_a X_b)CZ picks up
  a relative minus sign that naive single-Pauli composition misses; every
  CZ-containing circuit was silently corrupted. The rules are now verified
  against explicit U† P U matrices over all two-qubit Paulis.
• Path B's two-qubit gates are vectorised. The per-amplitude loop that
  forced a 16-qubit ceiling is gone; the ceiling is now 22 qubits (documented
  implementation limit), and a vectorisation aliasing bug caught by
  differential testing was fixed.
• Path D evaluates observables in one backward pass with per-observable
  truncation and terminates early with unresolved=True once the bound can
  no longer be certified; deep hopeless circuits no longer run for minutes.

Bitstring ordering corrected

Paths A and C did not use the Qiskit convention (qubit 0 rightmost): X on
qubit 0 of a 3-qubit circuit returned '100' instead of '001'. The native
C++ engine renders qubit 0 leftmost, the opposite of every Python path; its
output is normalised, and the native engine is used only when it can faithfully
run the circuit.

The Qiskit BackendV2 integration also mis-mapped classical bits:
measure_all() maps qubit q to clbit q+n, so the outcome belongs in the high
columns. X on qubit 2 of 3 qubits returned 000100 where Aer returns
100 000.

Fail-closed routing

The analyzer defaulted any unrecognised circuit input to Path A. A
user-forced path could silently reroute. The router caught bare Exception,
turning a programming error into "try the next path". All three now fail closed
with typed errors naming the offending gate.

---

3. Numerical guarantees

SimulationResult separates three error sources instead of conflating them:

Field	Meaning
error_bound	Deliberate approximation. 0.0 means nothing was deliberately approximated.
numerical_error_bound	Measured float roundoff, where derivable.
sampling_error_bound	Finite-shot confidence bound.

total_error_bound composes them only when they share a metric; it is
None for observable-only results, because a bound on expectation values does
not bound a bitstring distribution.

The finite-shot bound was wrong and is now correct

The previous expression sqrt(ln(2/δ)/(2n)) was documented as a total-variation
bound. It bounds a single categorical outcome; total variation sums over all K
outcomes, so the 2^K − 2 concentration prefactor cannot be dropped.

Measured violation rate at n=1000, δ=0.05: 73% at K=16 and 100% at K=64,
while claiming to hold with probability 95%.

Replaced with the Weissman et al. (2003) result (via Mardia et al. 2019,
Lemma 1), distribution-independent using φ ≥ 2:

TV <= sqrt( ln((2^K − 2)/δ) / (2n) )

It reduces exactly to the classic value at K=2, holds within δ for K = 2…64,
is computed in log space (no overflow at 1000 qubits), and is clamped to 1.0.

---

4. Known limitations

These are deliberate and documented, not defects to be discovered later.

1. Path C reports no certified roundoff bound. The discarded
   singular-value mass is exposed as discarded_spectral_mass_diagnostic, but
   per-rewrite masses do not compose into a state-norm bound without a
   propagation analysis that is not implemented. Reporting it as a bound would
   overstate what is known.
2. Path B exactness is algebraic, not symbolic. The decomposition drops no
   terms, but coefficients are evaluated in float64.
3. Path C counts stop at 20 qubits. Wider circuits are executed and
   reported, but produce no counts rather than a placeholder.
4. No physical GPU execution has been verified. The Vulkan loader
   enumerates a device; no compute dispatch on a physical GPU was demonstrated.
   All verified execution is CPU. See README.md §8.
5. Path D cannot produce a joint distribution. By design; see §2.

---

5. Engineering

• cq-hecs CLI (version, doctor, backend list, analyze, run,
  verify, benchmark smoke) with a strict JSON contract: --format json
  emits exactly one document on stdout, diagnostics go to stderr, exit codes
  are stable (0 ok, 1 unexpected, 2 usage, 3 unresolved, 4 environment).
• One version source (scripts/version.py) with a CI-enforced consistency
  checker. Previously SECURITY.md, the docs, the SBOM generator and the release
  workflow carried four different versions.
• CMake: artifacts under ${CMAKE_BINARY_DIR}, core compiled once instead of
  ~14 times, AVX2 scoped to one target, Vulkan requirement stated explicitly.
• Native engine auto-discovery in the build output.

---

6. Verification

• Python: 209 passed, 0 failed with the native engine built (2 Qiskit
  deprecation warnings inside a test helper).
• Native ctest: 13/13 (MSVC 19.44).
• Mutation harness: baseline gate passes, 7/7 killed, exit code 0.
• Clean install: wheel built from a clean dist/, installed into an empty
  venv; cq-hecs --help, version (2.0.0), doctor and a JSON run
  smoke test all pass from the installed package.
• CI runs Ubuntu and Windows on every push; the release tag runs the release
  pipeline with the asset existence checks shown in .github/workflows/release.yml.

---

7. Upgrading

• error_bound no longer conflates approximation, roundoff and sampling. Code
  reading total_error_bound must handle None.
• Path D no longer returns counts by default. Use allow_uncertified_joint_counts=True
  and treat the result as a marginal sample, not a joint distribution.
• HOEFFDING-style guarantees from prior releases are withdrawn; the sampling
  bound is now support-size dependent.
• The cq_hecs legacy CLI is not the supported entry point. Use cq-hecs.

v2.0.0

CQ-HECS Release Notes

Current version: see scripts/version.py (single source of truth).
License: Apache 2.0
Repository: https://github.com/timfromhcs/CQ-HECS

The release workflow copies this file to
dist/RELEASE_NOTES_v<version>.md. The content below describes the current
state of the code, not a historical target.

---

1. What this release is

A correctness release. Its purpose is that every reported number can be
justified and every failure mode is explicit rather than silent.

Four classical simulation paths, all CPU-based:

Path	Method	Correctness class
A	Stabilizer tableau	Exact (GF(2) symplectic arithmetic)
B	Stabilizer rank decomposition	Exact algebra, float64 arithmetic, finite-shot counts
C	MPS, unbounded bond dimension	No truncation; no certified roundoff bound (see §4)
D	Sparse-Pauli dynamics	Certified bound on expectation values

---

2. Correctness work

Fabricated results removed

• Path B substituted a uniform distribution when its rank decomposition
  failed to normalize, and returned {'0'*n: shots} for circuits wider than the
  statevector limit — both reported as exact=True, error_bound=0.0. Both now
  raise.
• Path C returned an all-zeros placeholder beyond its sampling limit. It now
  reports no counts.
• Path A inflated 100 real samples up to the requested shot count for wide
  circuits. It now reports the number of shots actually drawn.
• The legacy python/cq_hecs Qiskit provider returned a fabricated 50/50 counts
  dict when the native engine was absent, with success=True. It now raises.

Correlation loss fixed

Path D sampled each qubit independently from its own <Z_q> marginal and
returned the result as a joint measurement distribution. A Bell state came out
uniform. Path D now reports certified expectation_values — single-qubit Z and
parity Z_q Z_r, which are what actually carry correlation structure. Joint
counts are opt-in and labelled counts_are_joint_distribution=False.

Silently ignored gates fixed

• Path C skipped any gate outside its dispatch chain and discarded singular
  values below an absolute 1e-14 cutoff while still claiming exactness.
• Path B ignored unknown gates, hiding two real bugs: Clifford-angle RZ and
  all RX/RY gates were never applied. RX/RY also used a hardcoded Z
  as their Clifford generator.
• Path D treated unrecognised gates as the identity. CZ, SWAP, RX and RY
  all took that path and returned wrong answers.
• Path A never called its own apply_cz, and dropped Clifford-angle rotations.

Latest hardening round

• The CZ rule in Path D was algebraically wrong. CZ†(X_a X_b)CZ picks up
  a relative minus sign that naive single-Pauli composition misses; every
  CZ-containing circuit was silently corrupted. The rules are now verified
  against explicit U† P U matrices over all two-qubit Paulis.
• Path B's two-qubit gates are vectorised. The per-amplitude loop that
  forced a 16-qubit ceiling is gone; the ceiling is now 22 qubits (documented
  implementation limit), and a vectorisation aliasing bug caught by
  differential testing was fixed.
• Path D evaluates observables in one backward pass with per-observable
  truncation and terminates early with unresolved=True once the bound can
  no longer be certified; deep hopeless circuits no longer run for minutes.

Bitstring ordering corrected

Paths A and C did not use the Qiskit convention (qubit 0 rightmost): X on
qubit 0 of a 3-qubit circuit returned '100' instead of '001'. The native
C++ engine renders qubit 0 leftmost, the opposite of every Python path; its
output is normalised, and the native engine is used only when it can faithfully
run the circuit.

The Qiskit BackendV2 integration also mis-mapped classical bits:
measure_all() maps qubit q to clbit q+n, so the outcome belongs in the high
columns. X on qubit 2 of 3 qubits returned 000100 where Aer returns
100 000.

Fail-closed routing

The analyzer defaulted any unrecognised circuit input to Path A. A
user-forced path could silently reroute. The router caught bare Exception,
turning a programming error into "try the next path". All three now fail closed
with typed errors naming the offending gate.

---

3. Numerical guarantees

SimulationResult separates three error sources instead of conflating them:

Field	Meaning
error_bound	Deliberate approximation. 0.0 means nothing was deliberately approximated.
numerical_error_bound	Measured float roundoff, where derivable.
sampling_error_bound	Finite-shot confidence bound.

total_error_bound composes them only when they share a metric; it is
None for observable-only results, because a bound on expectation values does
not bound a bitstring distribution.

The finite-shot bound was wrong and is now correct

The previous expression sqrt(ln(2/δ)/(2n)) was documented as a total-variation
bound. It bounds a single categorical outcome; total variation sums over all K
outcomes, so the 2^K − 2 concentration prefactor cannot be dropped.

Measured violation rate at n=1000, δ=0.05: 73% at K=16 and 100% at K=64,
while claiming to hold with probability 95%.

Replaced with the Weissman et al. (2003) result (via Mardia et al. 2019,
Lemma 1), distribution-independent using φ ≥ 2:

TV <= sqrt( ln((2^K − 2)/δ) / (2n) )

It reduces exactly to the classic value at K=2, holds within δ for K = 2…64,
is computed in log space (no overflow at 1000 qubits), and is clamped to 1.0.

---

4. Known limitations

These are deliberate and documented, not defects to be discovered later.

1. Path C reports no certified roundoff bound. The discarded
   singular-value mass is exposed as discarded_spectral_mass_diagnostic, but
   per-rewrite masses do not compose into a state-norm bound without a
   propagation analysis that is not implemented. Reporting it as a bound would
   overstate what is known.
2. Path B exactness is algebraic, not symbolic. The decomposition drops no
   terms, but coefficients are evaluated in float64.
3. Path C counts stop at 20 qubits. Wider circuits are executed and
   reported, but produce no counts rather than a placeholder.
4. No physical GPU execution has been verified. The Vulkan loader
   enumerates a device; no compute dispatch on a physical GPU was demonstrated.
   All verified execution is CPU. See README.md §8.
5. Path D cannot produce a joint distribution. By design; see §2.

---

5. Engineering

• cq-hecs CLI (version, doctor, backend list, analyze, run,
  verify, benchmark smoke) with a strict JSON contract: --format json
  emits exactly one document on stdout, diagnostics go to stderr, exit codes
  are stable (0 ok, 1 unexpected, 2 usage, 3 unresolved, 4 environment).
• One version source (scripts/version.py) with a CI-enforced consistency
  checker. Previously SECURITY.md, the docs, the SBOM generator and the release
  workflow carried four different versions.
• CMake: artifacts under ${CMAKE_BINARY_DIR}, core compiled once instead of
  ~14 times, AVX2 scoped to one target, Vulkan requirement stated explicitly.
• Native engine auto-discovery in the build output.

---

6. Verification

• Python: 209 passed, 0 failed with the native engine built (2 Qiskit
  deprecation warnings inside a test helper).
• Native ctest: 13/13 (MSVC 19.44).
• Mutation harness: baseline gate passes, 7/7 killed, exit code 0.
• Clean install: wheel built from a clean dist/, installed into an empty
  venv; cq-hecs --help, version (2.0.0), doctor and a JSON run
  smoke test all pass from the installed package.
• CI runs Ubuntu and Windows on every push; the release tag runs the release
  pipeline with the asset existence checks shown in .github/workflows/release.yml.

---

7. Upgrading

• error_bound no longer conflates approximation, roundoff and sampling. Code
  reading total_error_bound must handle None.
• Path D no longer returns counts by default. Use allow_uncertified_joint_counts=True
  and treat the result as a marginal sample, not a joint distribution.
• HOEFFDING-style guarantees from prior releases are withdrawn; the sampling
  bound is now support-size dependent.
• The cq_hecs legacy CLI is not the supported entry point. Use cq-hecs.

v0.2.0: Vulkan 1.3 Compute Hardening & Classical Four-Path Architecture

CQ-HECS v0.2.0: Vulkan 1.3 Compute Hardening & Classical Four-Path Architecture

Executive Summary

CQ-HECS v0.2.0 hardens the core technology with a native Vulkan 1.3 / SPIR-V compute backend, delivering vendor-independent acceleration across AMD, Intel, NVIDIA, and Apple Silicon (via MoltenVK) with zero proprietary CUDA lock-in.

---

Key Highlights & Architectural Additions

1. Automated Vulkan 1.3 SPIR-V Compute Pipeline:
   • Automated compilation and verification of all 12 compute shaders via glslangValidator --target-env vulkan1.3 -V.
   • Integrated into CMake (vulkan_shaders target) and GitHub Actions CI.
   • Cross-vendor tensor contraction and bit-exact ring arithmetic without CUDA dependence.
2. Exact Giles-Selinger Ring Arithmetic $\mathbb{Z}[1/\sqrt{2}, i]$:
   • Bit-exact cyclotomic ring synthesis for Clifford+T circuits, eliminating floating-point rounding drift.
3. Scientific Entanglement Honesty:
   • Area-Law States (e.g. GHZ with $\chi=2$): memory scales flatly with $< 5$ MB resident VRAM up to 300 qubits.
   • Volume-Law States (e.g. Random Circuit Sampling): linear entropy growth ($S \sim L/2$) and exponential bond dimension explosion ($\chi \sim 2^{L/2}$) are honestly acknowledged. Execution escalates to Path D (Sparse-Pauli with certified error bound $\Delta \le \sum |c_P|$) or reports unresolved=True. Zero silent truncation.
4. Zero-Buzzwords Architecture:
   • Complete elimination of all legacy GWT / consciousness vocabulary in favor of functional, deterministic components:
     • VulkanComputeScheduler (cqhecs/scheduler.py)
     • EntanglementAdaptiveRouter (cqhecs/router.py)
5. Standardized Cryptographic Testbench:
   • Aligned with real specifications (ChaCha20: 20 rounds, SHA-256: 64 steps, BLAKE2b: 12 rounds) as an algebraic SAT verification testbench with zero preimage extraction claims.
6. Single License Unification:
   • Standardized exclusively under the Apache License 2.0 repository-wide.

---

Remote CI Verification (Ubuntu Linux & Windows MSVC 100% Green)

• CI Run 1: Run 33562814848 (Commit 88dc726, 2m55s, Ubuntu)
• CI Run 2: Run 33563158293 (Commit 9c98d9d, 3m03s, Ubuntu)
• CI Run 3 (Dual-OS Matrix): Run 33564612795 (Commit 62d3149, Ubuntu 24.04 in 2m04s & Windows Server 2025 in 5m06s)
• Quality Gates: 12/12 Vulkan Shaders Verified on Linux & Windows, 89/89 Pytest Passed, 13/13 CTest Passed, 100% Mutation Killed (5/5), 0 Silent Truncation Violations.

---

Release Artifacts & Checksums

• cqhecs-0.2.0-py3-none-any.whl (Python Wheel)
• cqhecs-0.2.0.tar.gz (Source Tarball)
• cqhecs-0.2.0-windows-x64.zip (Native Windows x64 binaries: cq_hecs.exe, cq_hecs.dll, cq_hecs_core.dll, cq_hecs_api.h)
• cqhecs-sbom.spdx.json (SPDX 2.3 SBOM)
• sha256sums.txt (SHA256 Checksums)
• vulkan_mps_benchmark_results.json (Raw Benchmark Telemetry)
• VULKAN_MPS_EVALUATION.md (Comparative Benchmark Report)