open-standards/wai/extensions/quantum-sim.md

# 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 | **attested by signature** |

`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. One Ed25519 signature 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 <circuit.wqc> [receipt.json]` fills the
energy honestly: on Apple Silicon it samples CPU power via `macmon` (IOReport, no
sudo), brackets a reconstruction burst against an idle baseline, and writes the
**measured** marginal microjoules — never a fabricated number; where no meter is
present it emits an UNMETERED receipt (`joules_micro = 0`) with the exact work
intact. 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.