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

# WAI Extension: Quantum-Operations Attestation (`wai.quantum.calibration` · `wai.quantum.job`)

Status: **Draft.** Engine: `wai-rs/src/quantum_ops.rs` (feature `quantum_ops`).
The **verify-half** of WAI (`wai.asset.provenance`'s lineage, specialized) applied
to the quantum processing industry.

## 0. What this extension adds

A calibration run or a QPU job leaves a dataset (commonly HDF5), a state snapshot
and a log. This extension adds a receipt over each operation with two properties:

1. **cryptographic signature + portability** — a record a *third party* verifies
   from the bytes alone;
2. **measured joules** — the energy of the operation, carried with its
   acquisition class, on hardware whose dilution refrigerator and control racks
   draw kilowatts.

Related reproducibility work exists (version capture of the software that ran, QBOM
bills of materials, hash-chained audit traces such as QCIVET's); the receipt here
is signed, content-addressed and joule-metered. It is not a control system and **runs no
hardware**: the calibration/job is performed by the sink's control stack, exactly
as WAI dispatches a decode to a sink's codec. WAI owns the **receipt**.

## 1. Two receipts, cross-linked

### `wai.quantum.calibration` — `CalibrationReceipt`

A signed record of one bring-up / tune-up run:

- `device_id`, `target` (`"q3"`, `"cz(q3,q4)"`, `"readout:q3"`)
- `config_hash` — content hash of the applied pulse/gate config
- `evidence[]` — each an `{kind, blob_hash, summary}`: a benchmark outcome
  (RB / T1·T2 / Rabi / readout-GMM) **content-addressed to its raw dataset bytes**,
  so a fidelity *claim* binds to the exact bytes that produced it
  (`evidence_matches()`) — checkable, not asserted
- `joules_micro` — measured energy of the run (attested), with its acquisition
  class as an optional signed label: `quantum_energy::Labelled` wraps any
  receipt here and re-signs it with the class inside the signature, and
  `LabelledQbom` labels a bill of materials per entry
  ([energy-measurement](energy-measurement.md) §2.8). An unlabelled receipt
  keeps its legacy bytes.
- `grant` — the authorization (below)
- `parent_receipt_hash` — the prior device state this supersedes: a signed
  lineage of device states

`merkle_root` covers `[config_hash] ++ evidence leaves`; one Ed25519 signature
covers the whole payload. Every receipt here is verified as SPEC §7 *Signatures*
requires.

### `wai.quantum.job` — `JobReceipt`

A signed record of one dispatched circuit:

- `backend_id` — which QPU/sim actually ran it (`"example:qpu-a"`, `"wai.quantum.circuit"`)
- `circuit_hash`, `result_hash` (counts histogram / statevector), `shots`
- **`calibration_ref`** — the `CalibrationReceipt::receipt_hash` of the device
  state the job ran under. `verify_against_calibration(cal)` confirms the job
  names *that* calibration and both verify — the QCIVET **"the claimed calibration
  was actually in effect"** property, signed. `None` for a simulator.
- `joules_micro`, `grant`, `parent_receipt_hash`

## 2. The grant — gate ⊗ meter ⊗ receipt in one object

`GrantRef` = **capability ⊗ joule-ceiling** (⊗ optional funds-ceiling, JCP §4.8
dual ceiling). The full grant lives in the JCP layer; the receipt binds its content
hash plus the ceilings it enforces.

The enforcement is the sharp part: **the joule ceiling is checked inside
`verify()`.** A receipt whose measured `joules_micro` exceeds its grant ceiling is
**not valid** — an operation that blew its energy grant *cannot produce a passing
receipt*. This is the whole portfolio thesis (gate, meter, receipt) collapsed into
a single verifiable object. `honors_budget()` exposes the check on its own; a
grant with `joule_ceiling_micro = u64::MAX` opts out (still signs everything else).

## 3. Conformance

- A **conforming producer** (a control stack, or an adapter over one — see §5)
  MUST seal a `CalibrationReceipt` per calibration run and a `JobReceipt` per
  dispatched job, with `joules_micro` a **measured** figure (never fabricated;
  `0`/unbounded if genuinely unmetered) and every hash the real content hash.
- A **conforming verifier** MUST accept a receipt iff `verify()` passes — Merkle
  root recomputes, joules within the grant ceiling, signature valid — and, for a
  job that claims a calibration state, `verify_against_calibration()` passes.
- Receipts are **portable**: JSON with hex hashes (`to_json`/`from_json`),
  verifiable with only the public key. No vendor cloud required.

## 4. What this is NOT

- **Not a control system, not a simulator, not a calibration ML.** It attests
  operations others perform. The physical control electronics and the ML tuning
  models are the dispatched **backend** — WAI's founding "don't reinvent, dispatch"
  philosophy (SPEC Appendix B), applied to quantum control.
- **Not a reconstruction.** `joules_micro` and the result are *attested* (only the
  signer can vouch for their own silicon's energy draw); the hashes, Merkle root,
  grant ceiling, and cross-link are *verifiable* by anyone. The receipt states
  plainly which half is which.

## 5. Integration (where it attaches)

The natural attach point is the **control-system → cloud boundary**: the moment a
calibration node or a job completes, the control system already holds everything a
receipt needs (config, evidence datasets, result, timing, backend identity), and
the power rails are already instrumented — so adding a signature + a joule figure
is *incremental*. Open-source insertion points:

1. **Quantify** (`quantify-core`) — one HDF5-write point covers every node.
2. A lab-OS task-management and database layer, as a control plane; in
   production chip testing a signed pass/fail is the record a test produces.
3. **QUAlibrate/QUAM** — the per-node boundary, and its existing record of
   package versions, map onto a signed, metered receipt.
4. **Qubex/qube-calib** — a `CalibrationNote` artifact per node.

## 6. The metric

This extension carries joules per verified calibration and joules per QPU job as
signed, portable, content-addressed, grant-bounded records.