### wai-quantum: synthesis and certified compilation

Circuits synthesised and optimised by the engine, every compile carrying a sealed certificate of how close the output is to the program and how that was established (`wai-quantum/docs/compiler.md`).

- **Rotation synthesis** (`engine::synth::rz`): `Rz(θ)` as a Clifford+T word within a requested `ε`, by the Ross–Selinger method:
  - the ε-region and the unit disk as a two-dimensional grid problem over `Z[ω]`, made upright by a grid operator (rotations, shears, `K` and shifts by powers of `1 + √2`), each candidate tested in exact arithmetic;
  - the norm equation `t†t = ξ` solved prime by prime in `Z[ω]`, or shown to have no solution;
  - the operator written in its Matsumoto–Amano normal form, the fewest `T` gates of any word for it;
  - the word multiplied back exactly, and its distance to the rotation recomputed from the word in fixed point and rounded up: that is the distance reported.
  - `T` counts follow `3·log₂(1/ε)` (99 to 101 at `1e-10`). Against every Clifford+T operator with at most 11 `T` gates, 21 of 24 cases land on the optimum and the rest one above.
- **The arithmetic under it**: integers of any size (Knuth division, square roots, a primality test, Pollard–Brent factoring within a step budget), fixed point with 320 fractional bits with `π`, `√2`, sine and cosine, and the rings `Z[√2]`, `Z[ω]` and 2×2 matrices over `D[ω]`. Each held to a ground truth: 128-bit arithmetic, every `t` with small coefficients for the norm equation, brute force for the grid problems.
- **One and two qubits**: ZYZ Euler angles of any one-qubit unitary, and the KAK decomposition of any two-qubit unitary into at most three CNOTs (two or none when its canonical coordinates allow), with a deterministic Jacobi eigen-solver.
- **Phase folding** (`engine::synth::phase`): phase gates on one parity merged, checked by recomputing the phase polynomial.
- **The pass pipeline** (`engine::compile`):
  - passes `lower`, `simplify`, `phase_fold`, `resynth_1q`, `resynth_2q` and `approximate`, levels 0 to 2, bases (the gate set compiled to) `clifford_t` and `standard`;
  - each pass checked where it acts, and a pass whose check fails not applied;
  - one certificate per compile: each pass's counts before and after (gates, CNOTs, `T`, rotations), its check and verdict (`proof`, `exact` or `approximate` with its distance), the `ε` budget, its share per rotation and the bound the distances add to;
  - up to eight qubits the whole output is also measured against the whole program on dense unitaries;
  - sealed in a job's form, so the existing receipt check verifies it;
  - with `"stages": true`, the circuit after each pass as well.
- **Compiled jobs**: a job with `"compile": {"epsilon", "level", "basis"}` runs its program compiled first, bit-exact for Clifford+T, and its result's `compiled` states the distance.
- **Surfaces**:
  - the command line: `wai-quantum compile` (`--epsilon`, `--level`, `--basis`, `--json`, `--certificate`) and `run --compile ε`;
  - the service: `POST /v1/compile`, sealed with the service's key, within bounds (20 000 gates, 256 rotations, `1e-12` a rotation; past them 422 with the local command);
  - the MCP tool `compile_qasm` on both servers, and `compile` in the job schemas;
  - `QuantumEngine.compile` in a page, and the desktop app's `compile` command;
  - the Studio's compile lens: each pass with its counts and check, the certificate verified in the page, and the circuit after any pass drawn.
- **Determinism**: CI compiles one program natively and as a WASI component and compares the sealed bytes, and the browser build's tests compile one request to the native build's pinned digest. The synthesis tests also run under `wasm32-wasip2`.

