### wai-quantum: resource estimation from programs

What a fault-tolerant machine would need to run a program, derived from the program itself, calibrated from the crate's own decoders, and sealed (`wai-quantum/docs/estimate.md`).

- **Logical counts** (`engine::estimate::count`): the program written in Clifford gates, `T`, `z` rotations, Toffolis (one CCZ state each) and measurements:
  - a gate under several controls goes through clean ancillas, a ladder of Toffolis computed and uncomputed: `x`, `y`, `z` or `h` under `c ≥ 3` controls takes `2c − 3` Toffolis and `c − 2` ancillas, a phase under `c ≥ 2` takes `2c` and `c`;
  - each rotation synthesised at its own angle within its share of the budget's synthesis share, its `T` count the word's (`engine::synth::rz`);
  - `T` gates, Toffolis, rotations and the `T` in their words, measurements, non-Clifford, rotation and `T` depth, total depth, and logical qubits with ancillas;
  - a program that branches is counted step by step, each step once, an upper bound it says it is.
- **Ground truth**: a Bell pair, `T` chains in series and in parallel, the ripple-carry adder (`2n` Toffolis), the QFT (`3(n−1)` `T`, `3(n−1)(n−2)/2` rotations); every ladder held to the gate it replaces on dense unitaries with its ancillas at `|0⟩`; each rotation's `T` count equal to the synthesiser's.
- **The physical estimate**: the planar model (`quantum_resource`) on those counts, a rotation layer taking as many steps as its longest word has `T` gates; the headline and the frontier of estimates no other beats on both physical qubits and runtime.
- **Calibration** (`engine::estimate::calibration`): on gate-based qubits the surface code's `P(d) = a·(p/p*)^((d+1)/2)` is fitted to the memory experiment decoded by exact matching (`a = 0.0233`, `p* = 0.01004`) or by union-find (`a = 0.0214`, `p* = 0.00952`) on the same shots: `d` 3, 5, 7 by `p` 0.002 to 0.005, 100 000 shots (25 000 at `d = 7`), seed 1. The table is in the crate, a release test measures every point again, and the example `estimate_calibration` prints it. The planar model's assumed constants remain available; an extrapolation past the measured range is flagged.
- **Receipts**: every estimate a resource-estimate receipt whose job binds the program's digest, every count, the budget, the synthesis share and each rotation's (a new counted-program form; the earlier forms hash as before); the frontier's name the headline's as parent; the answer sealed in a job's form. `engine::estimate::verify` checks the seals and re-runs the request.
- **Interchange**: the logical-counts JSON (`numQubits`, `tCount`, `rotationCount`, `rotationDepth`, `cczCount`, `ccixCount`, `measurementCount`) and the routine format (`v1`: routines, ports, resources, children, connections), each read and written, the routine held to its schema, with a self-made fixture. A document's rotations cost the most `T` any of eight reference angles needs.
- **Refusals** carry codes `QE02` to `QE08`, beside the reader's own.
- **Surfaces**:
  - the command line: `wai-quantum estimate prog.qasm` (`--budget`, `--qubit NAME|all|FILE`, `--calibration`, `--max-slowdown`, `--counts`, `--routine`, `--export`, `--json`), and `verify` re-running an estimate; `lab estimate` unchanged;
  - the service: `POST /v1/estimate`, within bounds (200 000 gates, 256 distinct angles, `1e-12` a rotation), and `POST /v1/verify` re-running an estimate;
  - the MCP tool `estimate_resources` on both servers, with one description and schema, and the verify tools re-running an estimate;
  - `QuantumEngine.estimate` and `engine_estimate_verify` in a page; `estimate` in the desktop app;
  - the Studio's Estimate pane: the counts, the estimate, the frontier plotted on log scales and listed, the seals verified and the request re-run in the page;
  - Python: `wai_quantum.estimate` and `verify_estimate`.
- **Determinism**: CI compares an estimate natively and as a WASI component byte for byte, and the browser build's tests estimate one request to the native build's pinned digest. The estimate's tests run under `wasm32-wasip2`, and `wai-quantum-estimate.yml` runs them in release with the whole calibration.

