# WAI Extension: Quantum-Circuit Simulation > Status: Draft. A quantum computation shipped as **instructions**, not > outcomes: the wire carries a compact gate op-log (a `WQC` container), > the sink **classically simulates** it in a fixed-point complex floor, > and the reconstructed statevector hashes identically on every machine. > Conformance is **statevector-equivalence** (and, for measured circuits, > **shot-histogram-equivalence**). Reference impl: the `quantum` feature of > `wai-rs` (`crate::quantum`); corpus: `quantum-conformance/`; capability > `wai.quantum.circuit`. Keywords **MUST**, **MUST NOT**, **SHOULD**, **MAY** are RFC 2119/8174. ## 1. Scope and model A `wai.quantum.circuit` object is a **quantum circuit**: a qubit count and an ordered list of gates. The sink reconstructs the resulting quantum state by simulating the circuit from `|0…0⟩` in the `wai.det.fixed64` floor — every amplitude is a complex fixed-point number (`re, im` as `i64` at scale `2^FRAC`), every gate an integer matrix–vector update with a pinned rounding rule. It is lever 3 (instructions-at-the-sink) applied to computation: the wire carries the *circuit*, the sink reconstructs the *state*. The design rule that governs the whole extension: **WAI's value is determinism** — byte-identical reconstruction, "conformance is a hash." Real quantum **hardware** is the enemy of that: NISQ noise and stochastic measurement are not reproducible across devices. So this extension does **not** use, require, or emulate a QPU, and delivers **no** quantum speedup. It makes a quantum *computation* a transportable, deterministic, receiptable object — nothing more, and it says so plainly. In scope: the container, the gate IR, the deterministic reconstruct contract, the **statevector-equivalence** and **shot-histogram-equivalence** conformance criteria, the quantum-information-theoretic fidelity metric, and the receipt profile. Out of scope: quantum hardware or any device backend; a compression codec for arbitrary media (this is not one); variational-quantum-circuit / "quantum AI" **priors** whose measurement is stochastic — those are at best a float/behavioral capability that can never back `intent=replicate`, so they do not belong in this exact-reconstruction extension (§7). Relationship to the core spec: mirrors worlds / score / film. The reconstruct runs in the deterministic floor; `media` takes the informational value `"quantum"`; `wai.quantum.circuit` is authoritative. Its replicate class is `StandardDefined` (WAI's own deterministic floor), its fidelity tier `Lossless` (the simulation analog — the reconstruction is byte-exact). ## 2. Container (`WQC`) ``` "WQC1" | u16 n_sections | section table (u8 kind, u32 off, u32 len) | sections ``` `off` is relative to the start of the sections blob (immediately after the table). Unknown section kinds MUST be ignored (forward-compatible). | kind | section | required | |---|---|---| | `0x01` | contract (canonical JSON) | REQUIRED | | `0x02` | gate op-log | REQUIRED | | `0x03` | measurement (canonical JSON) | OPTIONAL | ### 2.1 Contract ```json { "ext": "wai.quantum.circuit/1", "n_qubits": 3, "numeric": "wai.det.fixed64", "frac": 30, "gateset": "cliffordT+dyadicP" } ``` `frac` is the amplitude fixed-point scale (`FRAC`, 30 in v1). `gateset` names the reconstruction's gate algebra (§3). ### 2.2 Gate op-log `n_ops u32`, then per op: ``` u8 opcode | u8 n_ctrl | u8 target | u16 param | n_ctrl × u8 control ``` The op is a **controlled-1-qubit gate**: the base gate `opcode` is applied to `target` iff every qubit in `control` is set. `param` carries the dyadic index `k` for `P(k)` (0 otherwise). Opcodes: | opcode | gate | | opcode | gate | |---|---|---|---|---| | 0 | `I` | | 5 | `S` | | 1 | `X` | | 6 | `S†` | | 2 | `Y` | | 7 | `T` | | 3 | `Z` | | 8 | `T†` | | 4 | `H` | | 9 | `P(k) = diag(1, e^{2πi/2^k})` | `CX`/`CZ`/`CP(k)` are these with `n_ctrl = 1`; `CCX` (Toffoli) with `n_ctrl = 2`; `SWAP` is three `CX`. A target MUST be `< n_qubits`; a control MUST be `< n_qubits` and `≠ target`; `P(k)` MUST have `1 ≤ k ≤ 32`. ### 2.3 Measurement (optional) ```json { "seed": 13034510, "shots": 100000, "basis": "computational" } ``` Pins a computational-basis sampling for shot-histogram-equivalence (§4). ## 3. Reconstruct contract The state is `2^n` amplitudes, `amps[|0…0⟩] = 1`, all others `0` at start. Each op applies its base gate's 2×2 fixed-point matrix `M` to the amplitude pair `(i, i∨2^target)` for every `i` with the target bit clear **and** all control bits set: ``` a0' = M00·a0 + M01·a1 a1' = M10·a0 + M11·a1 ``` Complex products use a pinned round-half-up fixed-point multiply (`(a·b + 2^(FRAC−1)) >> FRAC`, `i128` intermediate). The one irrational the Clifford+T set needs — `1/√2` — and the dyadic phases `e^{2πi/2^k}` are built by an **integer half-angle recurrence** seeded at `(cos π/2, sin π/2) = (0, 1)` (`cos(θ/2)=√((1+cosθ)/2)`, integer `isqrt`), so **no float ever runs**. `gateset = "cliffordT+dyadicP"` is universal (Clifford+T is dense in `SU(2^n)`); the dyadic phase ladder gives the **QFT** ("quantum FFT"), which is transported as a circuit (`H` + controlled-`P(k)` + swaps) and reconstructs byte-exact. The canonical reconstructed quantity is the amplitude vector serialized as `re_le(i64) ‖ im_le(i64)` per amplitude, in index order. ## 4. Conformance ### 4.1 statevector-equivalence > Given the same `wai.quantum.circuit`, a conforming sink MUST reconstruct the > identical fixed-point statevector, hence the identical BLAKE3 — on every > machine, no tolerance parameter. ``` statevector_hash = BLAKE3("wai:quantum-statevector\x01" || n_qubits || frac_le || canonical amps) circuit_hash = BLAKE3("wai:quantum-circuit\x01" || contract_bytes || oplog_bytes) ``` `circuit_hash` is the frame-independent identity of the circuit; each sink's `statevector_hash` is the verifiable result. ### 4.2 shot-histogram-equivalence (measured circuits) For a circuit with a §2.3 measurement, a conforming sink MUST sample the computational-basis outcome with the pinned `splitmix64` PRNG seeded by `seed` (walking the un-normalized `|amp|²` prefix sums — no divide), producing an identical per-basis-state count vector, hence: ``` histogram_hash = BLAKE3("wai:quantum-histogram\x01" || n_qubits || seed_le || shots_le || counts_le) ``` ## 5. Fidelity and size (honest) Two honesties the format states rather than implies: 1. **The reconstruction is exact; the model it reconstructs is an approximation.** The statevector is byte-identical across sinks (statevector-equivalence), but it is a *fixed-point* approximation of the ideal complex-amplitude unitary evolution — each gate carries a bounded rounding error (`≈ 2^−FRAC` per op, accumulating roughly linearly). This is the same call as `wai.video.int_motion`: byte-exact reconstruction of a defined-lossy quantity. The tier is therefore `Lossless` in the *simulation* sense (like world replay), and the per-gate error bound is the contract, not a hidden claim. 2. **The state is exponential; the circuit is not.** A statevector is `2^n` amplitudes × 16 bytes — the reconstruction is heavy and grows exponentially. The *transportable* object is the circuit op-log, which is linear in gate count (the reference corpus's QFT-5 circuit is 261 bytes and reconstructs a 32-amplitude state; a 26-qubit circuit is still a few kilobytes and reconstructs ~1 GiB). The win is exactly WAI's thesis — the wire carries instructions, the sink reconstructs — and it is *why* the receipt matters: because reconstruction cost is exponential, an energy-metered, byte-exact, signed record of the computation is a genuinely novel artifact. This extension is a way to make a quantum computation portable and verifiable. It is not a media codec and it is not a route to quantum advantage. ## 6. Receipt (JWP profile) The receipt (`quantum_receipt.rs`, feature `quantum_receipt = ["quantum", "world"]`) is the artifact this whole extension exists to make possible. Its design principle: **separate the two halves of the reconstruction's cost so each is trusted the way it honestly can be.** | field | what it is | how it is trusted | |---|---|---| | `circuit_hash` | identity — the `WQC` circuit's hash | re-checkable | | `statevector_hash` | the byte-exact reconstruction result | **re-checkable** (re-simulate) | | `measurement` | optional `{seed, shots, histogram_hash}` | re-checkable | | `work_amp_updates` | `n_ops · 2^n` — the exponential reconstruction cost | **verified by recomputation** | | `joules_micro` | measured marginal CPU energy the sink spent; `0` is the unmetered marker | **attested by signature** | | `energy_provenance` and its evidence (optional; [energy-measurement](energy-measurement.md) §2.8) | how `joules_micro` was acquired | **attested by signature**, not re-measurable | `work_amp_updates` is *portable-exact*: anyone recomputes it from `(n_ops, n_qubits)` and it grows exponentially in qubits, so a sink cannot inflate or deflate the stated cost. `joules_micro` is *measured-attested*: only the signer can vouch for what its own silicon drew, and the same holds for the class that labels it and for the values of any report about it (energy-measurement §6). One Ed25519 signature, verified as SPEC §7 *Signatures* requires, covers all of it over a Merkle root of the leaf hashes (`circuit`, `statevector`, `[histogram]`) — the worlds / provenance / film receipt shape reused, `parent_receipt_hash` chaining a derivation exactly as they do. Two verification depths: - `verify()` — Merkle root recomputes, `work == n_ops · 2^n`, signature valid. - `verify_reconstruction(circuit)` — the strong, portable check: **independently re-simulate the circuit** and confirm it reproduces the receipt's `circuit_hash`, `statevector_hash`, shape, and histogram, *then* that the receipt verifies. A receipt claiming a statevector the circuit does not reconstruct to is rejected on any machine. (The measured `joules_micro` stays attested-only — re-simulation checks the *result and cost*, never the signer's energy draw.) `to_json()` / `from_json()` give the portable, sorted-key JSON an out-of-band verifier reads. `wai_quantum_meter [receipt.json]` fills the energy honestly: on a host that exposes its SoC's power interface to unprivileged readers it samples CPU power through the open-source `macmon` reader (no elevated privileges), brackets a reconstruction burst against an idle baseline, and writes the **measured** marginal microjoules — never a fabricated number; where no meter is present, or the reader's rail is not live in both brackets ([energy-measurement](energy-measurement.md) §3.1), or the §4 ratio or the §2.3 uncertainty cannot support a figure, it emits an UNMETERED receipt, whose `joules_micro` carries the unmetered marker `0` ([energy-measurement](energy-measurement.md) §2), never a figure of zero joules, with the exact work intact; a reader presents it as unmetered, and `POST /verify` renders it as `"joules_micro": null`. Beside a measured figure the meter writes a measurement report (energy-measurement §6). A measured figure is sealed with its acquisition class as a `quantum_energy::Labelled` receipt ([energy-measurement](energy-measurement.md) §2.8): `OnChipCounter` with its declared uncertainty, inside the signature, verified with `Labelled::verify` / `Labelled::verify_reconstruction`. The `wai-quantum verify` CLI and the HTTP handler's `POST /verify` accept a receipt in either form (`quantum_energy::MaybeLabelled`) and restate its class. A receipt sealed without a label keeps its legacy bytes and its figure is unlabelled. A representative run on the reference QFT-5 vector: **≈43 µJ measured per reconstruction, `work_amp_updates = 672`** (21 ops × 2⁵), sealed and self-verified. Because a quantum computation carries no speedup here, this is exactly the value the standard adds: an energy-accounted, byte-exact, signed record whose *result* and *cost* anyone can re-check, and whose *energy* the signer attests. ## 7. Quantum information theory as the conformance metric The exact path above conforms by **byte identity**, so state fidelity is `1` by construction — but the reference exposes the quantum-information-theoretic metric explicitly, `fidelity_fx(a, b) = |⟨a|b⟩|²` in the fixed-point floor (`0` for orthogonal states, `≈ ONE` for equal). It serves two roles: a **diagnostic** here (how close an *approximate* or float simulation lands to the byte-exact reference), and the **conformance metric** for the future path this extension deliberately excludes — a variational-quantum-circuit / "quantum AI" prior whose measurement is stochastic. Such a prior is `NeuralFloat`/`Behavioral`: it MUST NOT back `intent=replicate`, and would conform by a declared fidelity floor, exactly as `wai.semantic.*` conforms by a CLIP-similarity threshold. Naming the metric now fixes the axis before that capability is ever registered. ## Appendix statevector-equivalence is replay-equivalence with the world state replaced by a quantum amplitude vector, and the deterministic floor extended from real fixed-point (`Fx`) to complex fixed-point (`Amp`). The same discipline that makes a world replay, a mix sum, an actuator buzz, a film frame and a Gaussian cloud reconstruct now makes a quantum state reconstruct — one floor, one more cargo class, one verification. The state is heavy and the model approximate; the *reconstruction* of it is exact and auditable, and that — not a quantum speedup WAI does not claim — is the honest thing the standard adds.