v163.3 — CrossBackendEquivalenceReceipt

Release Notes — v163.3
QSOLKCB/QEC v163.3 — CrossBackendEquivalenceReceipt
Release Summary

v163.3 extends the:

v163.x — Heavy Dependency Invariant Discovery

arc by adding deterministic cross-backend equivalence receipts.

This release introduces a receipt layer for comparing explicitly supplied backend observation payloads under declared equivalence policies.

It does not execute backends.

It does not import heavy dependencies.

It does not benchmark.

It does not optimize.

Core rule:

same backend invariant candidate receipt

• same canonical backend observation payloads
• same declared equivalence policy
• same deterministic comparison rules
  → same cross_backend_equivalence_receipt_hash
  New Module
  src/qec/analysis/cross_backend_equivalence_receipts.py
  New Artifacts
  BackendObservation

A deterministic artifact representing one supplied backend observation.

It records:

backend name
dependency name
observation name
observation kind
backend role
payload / payload hash
error or unavailable status
source invariant candidate hash
observation hash

Produces:

observation_hash
payload_hash
CrossBackendComparisonCase

A deterministic comparison case binding:

reference observation
candidate observations
equivalence policy
source candidate hash
case reason

Produces:

case_hash
CrossBackendComparisonResult

A deterministic comparison result for one case.

It records:

result status
policy used
reference payload hash
candidate payload hashes
mismatch reason
result hash

Produces:

result_hash
CrossBackendEquivalenceReceipt

A deterministic aggregate receipt over observations, cases, and results.

It records:

schema version
equivalence mode
invariant candidate receipt hash
observation / case / result counts
equivalent / not-equivalent / incomplete / blocked / invalid counts
first/final observation, case, and result hashes
cross_backend_equivalence_receipt_hash

Produces:

cross_backend_equivalence_receipt_hash
Declared Equivalence Policies

v163.3 implements only explicit deterministic policies:

EXACT_CANONICAL_JSON
EXACT_HASH
STRUCTURAL_SHAPE_DTYPE
ORDERED_SEQUENCE_EXACT
SET_LIKE_SORTED_EXACT
DECLARED_UNAVAILABLE_MATCH
DECLARED_ERROR_MATCH

No fuzzy matching.

No tolerance matching.

No ULP comparison.

No backend execution.

No hidden numerical assumptions.

Major Features
Deterministic Backend Observation Comparison

v163.3 compares supplied canonical payloads only.

Backends are not executed or trusted.

The comparison layer receives observations and evaluates them under declared policies.

Canonical JSON / Stable SHA-256

All new artifacts support:

canonical JSON export
canonical bytes export
stable SHA-256 hashes
self-hash exclusion
validator recomputation

Malformed hashes and well-formed-but-wrong hashes are distinguished deterministically.

Convenience Grouping Builder

Added:

build_equivalence_receipt_from_observations(...)

This groups observations deterministically and builds comparison cases when reference/candidate observations are supplied correctly.

After review fixes, grouping is scoped by:

observation_name

• source_invariant_candidate_hash

so unrelated observations with the same name are not accidentally compared.

Review / Hardening Fixes
Full Receipt Count Validation

The receipt validator now checks all aggregate counts:

observation_count
comparison_case_count
comparison_result_count
equivalent_count
not_equivalent_count
incomplete_count
blocked_by_policy_count
invalid_observation_count

This prevents a recomputed-hash receipt from carrying false totals.

Deterministic Result Re-Evaluation

The receipt validator now re-evaluates embedded results against:

embedded cases
embedded observations
declared policies

This prevents forged self-consistent result artifacts from claiming equivalence when the payloads do not actually match.

HASH_ONLY Observation Support

HASH_ONLY observations now support explicit backend-supplied payload_hash values without requiring a payload.

This allows EXACT_HASH comparisons over hash-only artifacts.

Invalid JSON Normalized to INVALID_PAYLOAD

Payload canonicalization errors are now normalized to deterministic:

INVALID_PAYLOAD

instead of leaking arbitrary JSON serialization exceptions.

Declared Error / Unavailable Policies Require Explicit Fields

DECLARED_UNAVAILABLE_MATCH now requires a non-empty unavailable reason.

DECLARED_ERROR_MATCH now requires a non-empty error code.

Two missing values no longer count as a successful declared match.

Source Candidate Binding Added

Observations and cases are now checked against the candidate hashes in the supplied BackendInvariantCandidateReceipt.

This prevents a receipt from claiming lineage to one invariant-candidate receipt while comparing observations from unrelated candidates.

Observation Role Validation Added

Comparison cases now enforce correct roles:

reference_observation_hash → REFERENCE
candidate_observation_hashes → CANDIDATE or AUXILIARY

Self-comparison is also blocked.

Case / Result Field Validation Added

Validators now check:

case index
case name
case reason
result index
mismatch reason

This closes invalid-but-self-hashed artifact paths.

Scope Boundaries Preserved

v163.3 intentionally does not implement:

optimization contracts
benchmarking
fast paths
dependency replacement
runtime imports
simulation acceleration
backend execution
fuzzy equivalence
ULP equivalence

Those belong to later phases.

v163.3 compares explicitly supplied canonical observations only.

Tests
Focused Validation
pytest -q tests/test_cross_backend_equivalence_receipts.py

Result:

22 passed
Full Local Validation
pytest -q -ra --ignore=tests/test_networkx_topology_analysis.py

Result:

17583 passed
7 skipped

Notes:

tests/test_networkx_topology_analysis.py was excluded due to a pre-existing missing networkx dependency unrelated to v163.3.

The remaining 7 skips are pre-existing optional dependency skips for qutip, mido, and matplotlib.
Files Changed
src/qec/analysis/cross_backend_equivalence_receipts.py
tests/test_cross_backend_equivalence_receipts.py
Relationship to Roadmap

v163.3 implements:

v163.3 → CrossBackendEquivalenceReceipt

from the current roadmap.

The v163 discovery arc now has:

v163.0 → HeavyDependencyDiscoveryManifest
v163.1 → DependencyImportAndHotPathReceipt
v163.2 → BackendInvariantCandidateReceipt
v163.3 → CrossBackendEquivalenceReceipt

This release converts invariant candidates into declared observation-equivalence checks, while still refusing to optimize or benchmark silently.

Final Result

After v163.3, QEC can deterministically prove:

which backend observations were supplied
which equivalence policy was declared
which comparison cases were evaluated
which observations matched
which observations failed
which receipt binds the equivalence result

The backends are now comparable.

They are still not authorities.

Gremlin Notes (Non-Canonical)

• HASH_ONLY gremlin can now present paperwork without pretending it has a payload.
• JSON gremlin no longer leaks weird serializer noises; it now says INVALID_PAYLOAD like a civilized goblin.
• Missing-error-code gremlin denied equivalence by mutual absence.
• Forged-result gremlin forced to re-sit the comparison exam.
• Observation-role goblin informed that candidates may not cosplay as references.
• Fuzzy-equivalence gremlin still banging on the window, still not invited.
• NetworkX dependency gremlin remains outside this release scope, waving an unrelated import error through the glass.

Extra Gremlin Notes:

"Why the Gremlin notes?" See: https://openai.com/index/where-the-goblins-came-from/
"It's also funny that's why!"