open-standards/wai/wai-quantum/docs/verdicts.md

Verdicts: how far the engine checked

Every answer WAI Quantum gives about a program states one verification level. "Valid" is never the claim: the engine says how far it checked, and repairs only what it flagged (wai_quantum::engine::verdict, engine::repair).

The ladder

Level	Rank	The engine
refused	0	did not read the program, or refused what was asked of it; the refusal ends with its code
parsed	1	read the program and ran nothing
executed	2	ran the program by a method of a stated accuracy class, and checked no intent: none was given, or one could not be decided
evidence	3	checked every intent, at least one by a check that is evidence and not proof (random product states, a statistical test of samples)
proof	4	checked every intent by proof: a tableau, every basis state, checked rewrites, or the exact distribution

A level says how far the engine checked, not that the program is good. holds says whether the intents held: true, false, or null when one was not decided. A failure decided by proof is a verdict at proof with holds: false. With several intents, the level is the weakest check among them, and one unchecked intent leaves it at executed.

What a verdict records

A verdict ("schema": "wai.quantum.verdict/1") holds:

• parsed: whether the reader took the program, with its warnings and notes and their codes, or its refusal;
• executed: the method the run took and its accuracy class, and the distance a compile put between the program and what ran;
• intent: each intent's check, with its outcome (holds, fails, unchecked), its strength (proof, evidence, none), how it was decided and why; for a distribution, its total variation distance, the tolerance, the distribution computed (up to 64 outcomes) and, when it fails, the largest gaps;
• critique: the program's smells, each with its lines;
• repairs: each repair made before the run, with the code it answered, the rule, the lines it flagged and every line it changed, before and after;
• refusal: for a job that did not run, its message, its code and every code it gives;
• level, rank, holds, and statement, the level in one plain line.

Asking for one

A job asks for a verdict with "intent" (one intent or a list) or "verdict": true. Its result then carries verdict, which the receipt seals with the rest of the result. A job that asks for neither gives the result it gave before verdicts existed, byte for byte; a test pins it.

The intents:

• {"distribution": {"00": 0.5, "11": 0.5}, "tolerance": 1e-9}: the exact distribution of the measured bits, keyed by the classical bits with the highest bit first. The engine computes it by the state vector (up to 26 qubits), or under the job's noise by the density matrix, in double precision, within the memory the job was admitted with. The plan admits the check's memory beside the method's own.

• {"equivalent": "<the reference program>"}: the same circuit up to a global phase, by the equivalence ladder: equal tableaus for Clifford circuits at any width, every basis state up to 8 qubits, checked rewrites of one followed by the other's inverse to nothing (all proofs), then random product states up to 22 qubits (evidence).

• {"prepares": "<the reference program>"}: the same state from |0…0⟩, with the same qubits measured into the same bits.

• {"sampled": {"00": 0.5, "11": 0.5}, "test": "chi_squared", "alpha": 0.01, "shots": 4000, "seed": 7}: the program run as the job runs it (its method, noise, options and device target) for that many shots, at the intent's seed (or the job's), and the counts held to the distribution by the stated test, chi_squared (Pearson's) or g_test (the likelihood ratio), at the significance level alpha, with its statistic, degrees of freedom and p-value (engine::stats). The test, alpha and shots are required. It is evidence, never proof: one holding leaves the level at evidence, and an outcome of probability 0 that was sampled fails it outright.

Any intent may carry a note, a name, and "require": "proof", which counts evidence (random product states, a statistical test) as unchecked.

On a device target the run is the target's noisy model of the device; a distribution intent is checked on the program's own exact distribution, and a sampled intent on samples of the target's run. The intent is checked against the program the job ran (the repaired one, when it asked to be repaired), before any compile; a compiled run states the compile's distance under executed.

An intent that does not read is refused before anything runs, with the code J020.

Repairs

engine::repair reads the program, takes the reader's refusal (the reader names one at a time) and, where the fix is mechanical, makes it on the lines the diagnostic flags, reads the program again, and goes on to the next:

Code	The rule
Q004 (expected ;)	a statement that ends its line without ; gets one
Q102 (no register named …)	the register is declared before the line, with the fewest qubits (bits) its indexed uses need, or the size given (sizes)
Q320 (measure with no target)	the one bit register of the measured register's size takes it
Q310 (unbounded while)	with the bound chosen (max_iterations), @wai.max_iterations N on a line before it
Q500 (an angle the bit-exact method refuses)	with the bits chosen (dyadic_bits), each such angle written as the nearest τ·m/2^K, its rounding stated on its line

It never guesses what a program means. A code with no rule, or a case that is not the simple one, comes back as "needs a person" with the reader's advice. A repair someone else wrote (proposed) is held to the same lines: a change to a line no diagnostic flags, or a line added away from one, is rejected (J021) and nothing is changed. The engine finds the flagged lines itself, by reading the program, never from what the caller says. Every rule's own edit is held to its lines the same way.

A job may ask to be repaired first ("repair": true, or the choices); its result's repaired holds the program that ran and each repair, and its verdict lists them.

Refusals

A refusal of what is asked of a program ends with a job-layer code, beside the reader's: job-refusals.md has the table. A refused job still states its level: refused when the program does not read, parsed when it reads and the job was refused.

On every surface

• Command line: wai-quantum run FILE --intent ref.qasm (or a distribution, an intent, a list, or a project's intent.json, in JSON) prints the verdict and exits 0 when the intent holds, 1 when it fails, 2 when it is unchecked; --verdict asks for one with no intent, --repair repairs first. wai-quantum repair FILE repairs on the flagged lines and checks a proposal (--proposed FILE). wai-quantum test runs a project's program with its intents, so the verdict is sealed in the run's receipt.
• MCP servers (both): run_quantum_circuit takes intent and repair and always states its verdict (an agent's run asks for one, so the request it seals says so); repair_qasm repairs and checks proposals; every answer about a program carries its verdict (check_equivalent's own verdict came first and keeps its meaning, so its level is under verification); every refusal carries its codes as data; every tool declares a versioned output schema (wai-quantum://schemas/<tool>/1). The resource wai-quantum://docs/verdicts gives this page's contract as data.
• Job service: POST /v1/run and /v1/jobs take intent and repair, checked within the service's bounds; POST /v1/repair; every refusal's body carries its code.
• Studio and the desktop app: every run and every assistant proposal shows its level as a badge, with the engine's statement.
• Browser engine: engine_verdict(job, intent, memory_mb) and engine_repair(src, options).
• Python: wai_quantum.run(..., intent=...), job.verdict, wai_quantum.verdict(job, intent) and wai_quantum.repair(program, ...).

Conformance

quantum-conformance/intents/ holds programs, their intents and the verdict each must get, every level of the ladder covered, with distances known by hand. It runs natively, under wasm32-wasip2 and in the browser build.