open-standards/wai/wai-quantum-service

wai-quantum-service

The WAI quantum stack as a public job service. Send an OpenQASM program; get back measurement counts, Pauli expectation values or amplitudes. Each result names the method that produced it and how accurate it is, and carries a signature you can check.

No account and no key. The public instance is at https://wai.transaction.science/quantum-jobs/v1. It keeps every job across its own restarts for a day, runs sets of programs and sweeps of one program's inputs as one job, and answers a dry run with its plan before anything runs. You can run the same service yourself: docs/self-host.md.

The service runs jobs on its own engine only. It never routes a job to anyone's quantum hardware or provider and never takes a credential: a job that names a provider is refused (400), with where such a run goes instead (the command line's run --provider, or the desktop app, which hold the person's own credentials; see wai-quantum-qpu/bring-your-own-quantum.md).

# A Bell pair, 1000 shots.
curl -s https://wai.transaction.science/quantum-jobs/v1/run \
  -H 'content-type: application/json' \
  -d '{"qasm": "OPENQASM 3.0; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; c = measure q;", "shots": 1000}'

Jobs

A job is JSON:

field	meaning
qasm	the program: OpenQASM 3, or OpenQASM 2 (required, unless source gives it)
source	the program in another format, in place of qasm: {"format": "qir", "program": "…"} (QIR as LLVM text) or {"format": "jeff", "program_base64": "…"}; read to the job's qasm before anything else reads the job, the request keeping its source, and a module that does not read refused with its code (Q700 to Q721) and place
method	auto (the default) or a method below
shots	measurement shots (default 1024 when nothing else is asked for; at most 1,000,000)
seed	the sampling seed (default 1); the same job and seed give the same counts
observables	Pauli strings such as "Z0 Z1", or {"pauli": "X3 Y4", "coeff": 0.5}
amplitudes	bit strings, one character per qubit, qubit n − 1 first
noise	{"depolarizing_1q", "depolarizing_2q", "amplitude_damping", "dephasing", "readout"}, each a probability
options	per method: threshold, max_weight and ladder (pauli), max_bond and cutoff (mps), fusion (statevector), trajectories, memory_gb
compile	{"epsilon", "level", "basis"}: compile the program first (as POST /v1/compile does) and run the compiled circuit. With basis clifford_t (the default) it runs on the bit-exact method, and the result's compiled states its distance from the program
intent	what the program must do: {"distribution": {...}}, {"equivalent": "<a reference program>"}, {"prepares": "<a reference program>"}, or a list. The result's verdict states the level the engine checked to (refused, parsed, executed, evidence, proof) and whether the intents hold, sealed by the receipt (the verdict page). A reference's check is held to the equivalence bound below
verdict	true: the verdict with no intent
repair	true or {"max_iterations", "dyadic_bits", "sizes"}: the program repaired first on the lines its diagnostics flag (as POST /v1/repair does); the result's repaired holds the program that ran
programs	in place of qasm: a set, each item a program's text or a job (below)
sweep	with qasm: a set over the program's inputs, {"theta": [0.1, 0.2], "n": [2, 3]} (below)
dry_run	true: run nothing, and answer with the plan (below)

Counts are keyed by the program's classical bits, the highest bit first. With no measurement in the program, every qubit is measured into the bit of its own index.

The program may use the standard gates, user gate definitions, and the control modifiers ctrl @, ctrl(n) @, negctrl @ and negctrl(n) @ (on x y z h s sdg t tdg p and cx cy cz ch cp ccx ccz). Measurement and reset may come anywhere, and if acts on measured bits (if (c[0]) x q[1];, if (c == 3) { … } else { … }, OpenQASM 2's if(c==1) x q;). for loops over ranges and sets, and integer consts, are unrolled on reading. A program that declares an integer input is a generator: the service reads one circuit, so send it written out (wai-quantum instance gen.qasm --input n=5). while, inv @ and pow @ are refused, each with its line and what to write instead (src/qasm.rs lists everything read).

Sets and sweeps

One request can run many programs, as one job:

• A set: "programs", a list, each item a program's text or a job ({"qasm", …}). The request's other fields (shots, observables, seed, intent, …) apply to every item that does not set them itself.
• A sweep: "qasm" with "sweep", each of the program's inputs and its values. Every combination runs, the names in sorted order and the first varying slowest. An integer input (input uint n;) takes whole numbers, and the program is written out at each. A float or angle input (input float theta;, input angle phi;) takes any number, bound to exactly the double given. Every input the program declares needs values; a list of one fixes it.

A set holds at most 100 items. They run one after another in one worker, inside one job's time limit, holding the memory of the largest item. Each item is a plain job: its request is complete in itself, and it runs, plans and verifies as it would alone. A set with an item that does not plan is refused, naming the item.

The result is a set ("format": "wai.quantum.set/1"). Each item has its own result and its own receipt. Each item's leaf is the digest its receipt signs (a failed item's: the digest of its request and its error). The head holds the Merkle root of the leaves, under the JWP Merkle domains, with the count, and the set's receipt seals the set's request and its head. Each item carries its path to the root, so one item can be shown sealed by its set without the others. POST /v1/verify checks the whole set: its receipt, every item as the request gives it, each item's receipt, the root, and each path.

curl -s https://wai.transaction.science/quantum-jobs/v1/run -H 'content-type: application/json' -d '{
  "qasm": "OPENQASM 3.0; input float theta; qubit q; rx(theta) q;",
  "sweep": {"theta": [0, 0.5, 1]}, "observables": ["Z0"] }'

Dry runs

"dry_run": true, on POST /v1/jobs or POST /v1/run, runs nothing. It answers 200 with the plan. A dry run counts as one submission, as a check does.

field	meaning
method, why, qubits	the method the job would run on, and why
memory_bytes, work	the memory it would be admitted with, and the planner's work
time	seconds with its basis: the median rate of the last jobs of the method this service timed, or, before it has timed three, the planner's nominal rate; or seconds: null with why, where the planner's work does not predict the time
energy	joules_micro_estimate, class Estimator, from the median power of the last metered jobs of the method here; or unestimated with why. Never a reading
bounds	the limits that apply: memory and time per job, jobs and memory per client, submissions per window, the queue, the most items in a set
client	where you stand: active jobs, memory held, submissions left
accepted	whether the service would take the job now, by every limit; if not, status and refusal (its message and code) say why
items	for a set: each item's plan and estimates

Methods

method	takes	answers	accuracy
exact	angles that are dyadic multiples of 2π, up to 26 qubits	counts, expectations, amplitudes, a state hash	bit-exact
statevector	any circuit, up to 32 qubits	counts, expectations, amplitudes	exact
statevector_single	any circuit with gates on at most four qubits, up to 33 qubits, where the host has a GPU	counts, expectations, amplitudes	single
stabilizer	Clifford circuits (rotations by whole quarter turns), up to 32768 qubits, optionally with depolarizing, dephasing and readout noise	counts, expectations	exact; with noise, an estimate
pauli	any circuit, up to 1024 qubits	expectations	bounded
mps	any circuit, up to 4096 qubits, at bond dimension up to 256; best when entanglement stays low	counts, expectations, amplitudes	exact when nothing is truncated, otherwise heuristic
tensor_network	any circuit	amplitudes	exact
cutrank	a Clifford circuit, then one layer of one-qubit gates at any angles, up to 4096 qubits, as wide as the state's cut-rank allows	counts, amplitudes	exact; single when only a single-precision table fits
cutrank_single	as cutrank, with the table on the host's GPU, where it has one; only when asked for	counts, amplitudes	single
stabilizer_rank	Clifford+T circuits, up to 32768 qubits, as many T gates as one job's sum of 2^t (an expectation value's 4^t) branches allows	amplitudes, expectations	exact; with terms or epsilon, an estimate with its bound and the probability it holds
density_matrix	noisy circuits, up to 16 qubits within a job's memory	counts, expectations	exact
trajectories	noisy circuits, up to 32 qubits	counts, expectations	estimate

How the methods run:

• statevector groups consecutive gates into passes over the state. Each pass applies its gates tile by tile, in a buffer that fits a core's cache. The grouping never changes a bit of the result.
• cutrank takes a Clifford circuit followed, on each qubit, by one-qubit gates at any angles (a qubit's gates from its first non-Clifford one on act on that qubit alone).
  • It writes the Clifford part's state as a graph state with local Cliffords, and sums the amplitude one qubit at a time along an order of the qubits, in a table of 2^cut entries. Here cut is the state's cut-rank, its entanglement in bits, across the cut the sum has reached.
  • The planner makes one short search for an order with narrower cuts, enough to bound the job's memory and work. The run searches longer, from several seeds on threads of their own, and keeps the cheapest order that is no wider than the planner's. The cost is set by the widest cut, max_cut in the result, not by the number of qubits.
  • Counts are exact samples, drawn qubit by qubit from the table's conditional probabilities.
  • Amplitudes carry the circuit's own global phase. A stabilizer tableau does not fix it, so one amplitude of the Clifford part is tracked exactly, gate by gate, and the summed amplitudes are scaled to agree with it, together with the phase the lowering to Clifford gates drops. A circuit with so many Hadamards that the tracking would take more than about a minute reports global_phase as not fixed instead.
  • The table is held in double precision when it fits the job's memory, and in single precision otherwise (accuracy class single).
• pauli reports each value with its truncation bound. It holds at most as many Pauli terms as the job's memory allows; a sum that would outgrow it raises its threshold until it fits (threshold_reached), and the bound covers everything that dropped. Unless ladder is false, it also reports a ladder: the value and bound at up to three thresholds a decade above the one asked for, so you can see the value settle as the threshold drops.
• stabilizer, with noise, samples by Pauli frames against one noiseless outcome of the tableau, 64 shots to a machine word. Its counts have the law of independent noisy shots. Its expectation values are estimates with standard errors, from at least 10,000 shots unless trajectories sets the number. Amplitude damping is not a Pauli channel and is refused.
• trajectories treats every shot as an independent noisy trajectory in law. Shots that took the same errors share one state, so the error-free part of a circuit, and the error-free majority of the shots, run once. histories in the result counts the distinct error histories that ran.

Programs that measure in the middle

A program that measures a qubit and then acts on it, resets a qubit after its first gate, or uses if on measured bits runs on statevector or stabilizer. auto picks the stabilizer tableau when every gate is Clifford, and the state vector otherwise.

• Counts split their shots. The shots enter together, and at each measurement or reset they divide between the outcomes as independent shots would: binomially, in the outcome's probability. Each outcome then runs on in its own copy of the state. Shots that read the same outcomes share one state, and the counts have the law of independent runs.
• Expectation values are exact: the mixture over every branch of non-zero probability, at most 4096 branches. As for any program, they describe the state before the final measurements. A measurement whose qubit nothing touches afterwards, and whose bit no later condition reads, is not made for them.
• The result's dynamic member reports what the walks did:
  • measurements_and_resets;
  • branches_run and states_at_once for the counts;
  • branches_weighed for the expectation values.

Noise in such a program, and amplitudes of one, are refused, each with its reason. The state vector holds a copy for each branch still running, so it takes one qubit fewer than for a program that measures only at the end.

# Teleportation: ⟨Z2⟩ = cos 0.7 and ⟨X2⟩ = sin 0.7, exactly.
curl -s https://wai.transaction.science/quantum-jobs/v1/run -H 'content-type: application/json' -d '{
  "qasm": "OPENQASM 3.0; qubit[3] q; bit[3] c; ry(0.7) q[0]; h q[1]; cx q[1], q[2]; cx q[0], q[1]; h q[0]; c[0] = measure q[0]; c[1] = measure q[1]; if (c[1]) x q[2]; if (c[0]) z q[2]; c[2] = measure q[2];",
  "observables": ["Z2", "X2"], "shots": 1000 }'

auto picks the first method that takes the job. With noise, it tries density_matrix, then stabilizer, then trajectories. For counts, it tries stabilizer, exact, statevector, statevector_single, cutrank, then mps. For expectations alone, it tries stabilizer, exact, statevector, statevector_single, stabilizer_rank, pauli, then mps. For amplitudes alone, it tries exact, statevector, statevector_single, cutrank, stabilizer_rank, tensor_network, then mps. The job's why names the method chosen and the ones that could not take it.

The accuracy classes:

• bit-exact: the same bits on every machine. Amplitudes are held in 30-bit fixed point, and every output is an exact function of them.
• exact: no approximation beyond double-precision rounding.
• single: no approximation beyond single-precision rounding, about 10⁻⁷ relative per gate; sums are taken in double precision.
• bounded: an approximation, with a rigorous bound on the error (bound) beside each value.
• estimate: a statistical estimate, with its standard error (stderr).
• heuristic: an approximation, reported with the standard estimate of its error but not a bound. A matrix product state that truncated reports its discarded weight and its fidelity estimate, and a warning when the estimate is below 0.9.

Counts are always seeded samples.

Endpoints

GET /v1	the service: its methods, limits, load and receipt key
POST /v1/run	submit a job and wait up to 25 s: the finished job, or 202 and the job if it is still running
POST /v1/jobs	submit a job or a set: 202 and the job, with its id, once it is in the store; with dry_run, 200 and the plan
GET /v1/jobs/{id}	the job: its status, the request as submitted, its result when it is done, and the digests it is kept under; ?wait=S (at most 25) holds the answer until its status changes
GET /v1/jobs/{id}/events	the job's status as server-sent events: a status event at each change, then one job event with the whole job when it ends
DELETE /v1/jobs/{id}	cancel a queued or running job
POST /v1/verify	{"request": ..., "result": ...}: whether the result's receipt seals that request and that result
POST /v1/critique	{"qasm"}: the program's measures (gates by kind, two-qubit gates, depth, T count, whether it is Clifford, a modelled fidelity) and its smells, each with its lines
POST /v1/equivalent	{"a", "b"}: whether two programs are the same circuit up to a global phase, and how that was decided
POST /v1/convert	{"to", "program" | "program_base64", "from"?, "profile"?, "check"?}: the program carried between OpenQASM 3, QIR and jeff (as base64), with the program as OpenQASM 3, each note with its code, what was read and written, and the check (the output read back and held to the program by the equivalence ladder); a refusal is the reader's, with its code and place (the formats page)
POST /v1/improve	{"qasm"}: the program with its smells fixed, each candidate with its measures and checked the same circuit
POST /v1/shortcuts	{"qasm"}: each exact classical route to simulating the program, priced on it, and the cheapest for each question
POST /v1/compile	{"qasm", "epsilon", "level", "basis"}: the program compiled through checked passes (to Clifford+T within epsilon, by default 1e-6), with a certificate of every pass and the distance, sealed with the service's key in a job's form so POST /v1/verify checks it (the compiler page)
GET /v1/targets	the built-in device targets (synthetic), each with its qubits, pairs, gates, errors and hash
POST /v1/estimate	{"qasm"} (or {"counts"}, {"routine"}), with budget, qubit, calibration, max_slowdown and export, each optional: what a fault-tolerant machine would need to run the program, its logical counts, the estimate and the frontier, each estimate sealed with the service's key in the resource-estimate receipt family and the answer in a job's form; POST /v1/verify checks the seals and re-runs it (the estimate page)
POST /v1/repair	{"qasm", "proposed"?, "max_iterations"?, "dyadic_bits"?, "sizes"?}: the program repaired on the lines its diagnostics flag alone, a proposed repair taken only if it changes no other line, and what needs a person
GET /.well-known/wai-quantum-receipt-keys	every key receipts are signed with, each with its validity window, a retired one's transition to its successor signed by both
POST /v1/qec/code	{"code", "certify"?, "bound"?, "certificate"?}: an error-correcting code (surface:D, toric:L, steane, color:D, bb:72 to bb:288, gross), its checks, k, layout and decoders, and its distance certificate, or a given certificate checked against it
POST /v1/qec/decode	a code's syndrome or error decoded at code capacity, or a memory experiment's, a circuit's or a model's fired detectors decoded (or its shots sampled and decoded), with decoder
POST /v1/qec/threshold	{"family", "distances", "p", "shots", "decoder"?}: logical failure rates with their standard errors, the code model fitted at circuit level, and whether each larger distance failed less
POST /v1/pulse/schedule	{"qasm", "pulse"?}: a pulse program's schedule on frames, every play, delay, phase and frequency change, capture and barrier at its sample, each waveform's samples, the gate calls, and the digests a pulse run's receipt binds
POST /v1/pulse/check	{"request", "result"}: a pulse job checked by running it again here: its receipt, its program's digest, and its result held to the run field by field
POST /mcp	the Model Context Protocol endpoint (streamable HTTP, answered as JSON, no key): the tools, resources and prompts below

The three error-correction calls answer in a job's form, sealed with the service's key, so POST /v1/verify checks them (the error-correction page). So do the two pulse calls; a pulse run itself is a job of the method pulse ("method": "pulse", its options under "pulse"), queued, run and sealed as every job is (the pulse page). A job may also give mitigate beside noise and observables ("zne", "pea", "pec", "cdr", "vd", "readout", or {"method", ...} with its options): its result then carries each value raw and mitigated with its error bar, the method and its assumptions, inside the receipt. | POST /v1/gradient | {"qasm", "params", "hamiltonian", "gradient"?}: a Hamiltonian's expectation at the program's parameters and its exact gradient by each (adjoint or parameter_shift), in f64 with each component's rounding bound | | POST /v1/optimize | {"qasm", "params", "hamiltonian", "optimizer"?, "steps"?, "step_size"?, "gradient"?, "seed"?}: the expectation minimised by gradient descent, Adam or SPSA, every step a link of a digest chain from the request | | POST /v1/vqe | {"hamiltonian", "qasm" and "params" or "ansatz": {"layers"}, …}: the variational eigensolver, beside the exact ground energy by diagonalisation | | POST /v1/qaoa | {"graph": {"nodes", "edges"}, "layers"?, …}: Max-Cut by QAOA, beside the maximum cut by brute force | | POST /v1/build | {"algorithm": "qpe" \| "amplitude_estimation" \| "adder" \| "qsvt", …}: a standard algorithm's program, how to read it, and the equivalence ladder's verdict against a reference built from its definition | | POST /mcp | the Model Context Protocol endpoint (streamable HTTP, answered as JSON, no key): the tools, resources and prompts below |

The three error-correction calls and the five of the variational and algorithm library answer in a job's form, sealed with the service's key, so POST /v1/verify checks them (the error-correction page, the variational page). A job's params binds its program's parameters (input float theta;, input angle phi;) exactly. A job may also give mitigate beside noise and observables ("zne", "pea", "pec", "cdr", "vd", "readout", or {"method", ...} with its options): its result then carries each value raw and mitigated with its error bar, the method and its assumptions, inside the receipt.

A job may give a target: a built-in target's name, or a target document (wai.quantum.target/1, its schema in GET /v1/openapi.json). The program is compiled to the target's gates, placed on the qubits and routes most likely to succeed, and simulated under the noise its calibration gives. The result's target names the layout, its expected success, the noise and the target's hash, inside the receipt. The service reads the document it is given and fetches nothing.

Every refusal says why and ends with its code, which the body also carries as code (the job layer's codes, beside the reader's): 400 for a program or job that does not read (a set that does not read: J007), 422 for one larger than a job may be (J031), 429 past the per-client limits (J030), 503 when the queue is full (J032), on a private deployment 401 without one of its API keys (J033), and an Idempotency-Key that does not read (400) or was sent before with another request (422): J034. GET /v1 states the limits.

Status and limits

A job is queued, running, done, failed, cancelled, or interrupted: the service stopped while it ran, after it had run it again once, so it has no result, and error says so. Follow a job by its event stream (GET /v1/jobs/{id}/events), or by polling GET /v1/jobs/{id}, with ?wait=S to hold each poll until the status changes.

Every answer carries the client's submission window in the rate-limit fields of the IETF HTTP API working group: RateLimit-Policy: "submissions";q=30;w=600 (at most 30 submissions in 600 s) and RateLimit: "submissions";r=12;t=34 (12 left, one more in 34 s). A refusal past the limits carries Retry-After.

Sending a job again

A connection can fail after the service took a job and before its answer came back. To send the job again safely, give POST /v1/jobs or POST /v1/run an Idempotency-Key (the same working group's field): 1 to 255 visible ASCII characters, with no quote or backslash, as a structured field's string or bare. Make it unguessable, a UUID or 128 random bits, since it is kept per client and a client is an address.

• Sent again with the same key and the same request, the job is answered with the job the key names, before any limit, and counts as no submission.
• The same key with another request is refused, 422 and J034.
• A key names its job for as long as the job is kept, whatever its status, with one exception: a job the service interrupted. That job's key runs the request again.
• The record keeps a digest of the key with the client's name, never the key.

The MCP tools that run (run_quantum_circuit, run_quantum_set, run_on_target) take the same key as idempotency_key. Without one, each call is a new job, which is why their idempotentHint is false. The command line (wai-quantum submit) and the Python client send each job under a key of their own. Where no answer comes back, they send it again under that key, twice at most, and only to a service whose GET /v1 says it keeps keys (idempotency).

Kept across restarts

Every job is in the service's store before its submission is answered, and again at each change of its status. Programs, requests, results and receipts are kept under the BLAKE3 digests of their bytes; a job's digests names them. When the service starts, it reloads the store:

• a finished job is served as it was, its receipt still verifying;
• a job that was running is run again, once, from its stored request: it is queued again in its order, and its interruptions say when the service stopped;
• a job the service stops again while it runs once more comes back interrupted, with the reason, so a job that stops the service whenever it runs does not run for ever;
• a queued one is queued again, in its order.

Finished jobs are kept for WAI_QSVC_RETAIN_SECS (a day here), then dropped. A record names its client by a keyed hash of the address, never the address. docs/self-host.md describes the store.

The six checks answer at once, in the service's own process. Each counts against the client's submissions, as a job does. At most two run at a time, and a check that waits ten seconds for its turn is refused (503). Some checks are refused (422) with the command that runs them on your own machine:

• an equivalence check that would apply more than 4·10⁹ gate amplitudes;
• an improvement whose candidates' checks would apply more than that;
• a thorough search for shortcuts;
• a compile of more than 20,000 gates, or with more than 256 rotations to approximate, or a budget that leaves a rotation less than 10⁻¹² (wai-quantum compile). A job that asks to be compiled first is held to the same bounds;
• an error-correction call past its bounds here (wai-quantum qec): a decode of more than 200,000 shots, of a memory experiment past distance 7, or of more than 2 MiB of circuit or model text; a threshold of more than 16 points or 200,000 shots in all, or at circuit level past distance 7; the distance certificate of bb:288;
• a gradient, an optimisation, a VQE or a QAOA run past its bounds here (wai-quantum gradient, optimize, vqe, qaoa): more than 16 qubits, more than 500 steps, or about 4·10⁹ gate amplitudes in all; phase estimation on more than 12 counting qubits, or amplitude estimation on more than 8 (wai-quantum build);
• an estimate of more than 200,000 gates, or with more than 256 distinct rotation angles to synthesise, or a budget that leaves a rotation less than 10⁻¹² (wai-quantum estimate). Verifying an estimate re-runs it, within the same bounds.
• a pulse check whose run takes more than 2·10¹⁰ of the simulator's multiply-adds, or a pulse call on more than 1 MiB of program (wai-quantum pulse check). A pulse job itself is held to the limits every job is.

For agents

POST /mcp serves the service to an agent as Model Context Protocol tools: run_quantum_circuit, run_quantum_set (a set or a sweep), dry_run_quantum_job (the plan, running nothing), get_quantum_job, verify_quantum_receipt, critique_qasm, check_equivalent, convert_program, improve_qasm, classical_shortcuts, compile_qasm, estimate_resources, repair_qasm, quantum_service_info, qasm_diagnostics, list_components, list_targets, show_target, run_on_target, quantum_circuit_examples, qec_code, qec_decode, qec_threshold, pulse_schedule, pulse_check, gradient_qasm, optimize_qasm, vqe_ground_state, qaoa_maxcut and build_algorithm. A run it makes asks for its verdict, so the request its receipt seals is the job's own request; every answer about a program carries its verdict, every refusal its codes, and every tool a versioned output schema. verify_quantum_receipt re-runs an estimate. It also serves the engine's resources and prompts, the same as the command line's own server (wai-quantum mcp):

• resources: the language the engine reads (wai-quantum://docs/language), its diagnostics, the methods with their accuracy classes (their reach in a job's memory here), and worked examples, each with what it must do;
• prompts: writing and verifying a circuit for an intent, explaining a result and its receipt, and repairing a program from its diagnostics. Each names this server's own tools.

A client whose initialize says its host draws interactive views (the extension io.modelcontextprotocol/ui, version 2026-01-26) gets the engine's answers as views, as from the command line's server: each tool that has one names its ui://wai-quantum/* resource, the six views are listed and read, and each answer carries what its view draws in its _meta. The service keeps no session, so the client's word is carried in the session id it is given at initialize (wq-views- and 32 random hex digits, kept nowhere), which a client sends back with every request (Mcp-Session-Id); a client that draws no views gets no session id and none of this. For a job still running when the run's wait ends, the result view follows it with poll_quantum_job, which the host keeps from the model (visibility: ["app"]); a model reads a job with get_quantum_job.

A client that speaks MCP 2025-11-25 may call the three runs as tasks (tools/call with task): initialize declares tasks (cancel, and requests.tools.call), and each run's execution.taskSupport is optional.

• The task is the job. Its taskId is the job's id. tools/call answers at once with the task, working. A program that does not read makes no task: the answer is an error (-32602) whose data is the refusal, with its codes and verdict.
• Statuses. tasks/get gives the job as a task: working while it is queued or running, completed once done, cancelled, or failed for a job that failed or that the service interrupted, with why. Its ttl is the service's retention, which a job outlasts from its creation, since it is kept that long after it ends.
• The result. tasks/result gives what get_quantum_job gives for the job that ended, naming the task in its _meta (io.modelcontextprotocol/related-task), an error (isError) where the job failed.
  • Asked while the task still works, by a client that takes text/event-stream, the answer is an event stream: kept open, and the answer its one event when the job ends.
  • Any other client is held for up to 50 s, then told to ask tasks/get.
• Cancelling. tasks/cancel cancels the job. A task that has ended is not cancelled (-32602).
• Who may read a task. There is no tasks/list, and the public service binds a task to no one: a task's id, 128 random bits, is what reads it, as a job's is. On a private deployment that takes API keys, a task is its key's alone.

server.json beside this README describes the endpoint in the MCP Registry's format; the registry lists it as science.transaction.wai/quantum-jobs. The command line's agent docs (llms.txt, AGENTS.md, the Agent Skill) list these tools from wai/wai-quantum-cli/docs/service-mcp.json, which this crate's tests hold to the live list. After changing a tool, run WAI_QUANTUM_BLESS=1 cargo test mcp:: here, then regenerate the command line's docs (its README says how).

Receipts

Every finished result carries a receipt: an Ed25519 signature, by the key GET /v1 publishes, over the BLAKE3 digest of the request as submitted and the result as returned. POST /v1/verify checks one, and so can any Ed25519 implementation:

• digest = BLAKE3(wai:quantum-service-receipt ‖ 0x02 ‖ len(R) ‖ R ‖ len(S) ‖ S), each len a big-endian u64;
• R and S are the RFC 8785 canonical texts ("canon": "rfc8785") of the request and of the result without its receipt: keys sorted, no whitespace, every number written as ECMAScript writes the double it reads.

So a result verifies after any JSON reader has carried it, a browser's included. Whole numbers in a request must be within ±(2^53 − 1), so that every reader reads them alike. Receipts issued before the canonical form carry no canon and still verify (see src/receipt.rs).

The receipt names its key, and GET /.well-known/wai-quantum-receipt-keys lists every key the service has signed with, each with its validity window. wai-quantum-service rotate-key retires the key: the old one stays listed with its window closed, and a transition statement naming both keys is signed by each (docs/self-host.md).

Each new result also carries provenance, sealed with it: the program's digest and size, the method and its accuracy, each pass a compile ran with its check's verdict and the certificate's digest, the shots, seed and plan, and the engine's and the service's versions. docs/provenance.md maps every field to the categories provenance surveys use.

Energy

Every finished result carries energy, inside the body the receipt seals: the CPU energy the job's worker process spent, from its start to its exit. The service reads it from the kernel's per-process count (proc_pid_rusage, ri_energy_nj, on macOS) after the worker exits and before it is reaped. An exited process has left every core, so its count is complete.

"energy": {
  "joules_micro": 2540113,
  "energy_provenance": "OnChipCounter",
  "energy_uncertainty": { "relative_ppm": 1, "window_us": 2603412 },
  "energy_counter_filtering": "Unknown",
  "coverage": "whole",
  "attribution": "process",
  "covers": "the CPU energy of the job's worker process, from its start to its exit, with the CPU energy system services billed to it",
  "excludes": ["memory", "the host's idle draw"],
  "cpu_ms": 31680,
  "source": "proc_pid_rusage ri_energy_nj + ri_billed_energy − ri_serviced_energy, read after the worker exited and before it was reaped"
}

The fields follow WAI's energy-measurement extension (§2):

• energy_provenance is the acquisition class. OnChipCounter means the silicon's own accounting, with no calibration behind it.
• energy_uncertainty.relative_ppm declares the part of the uncertainty that can be evaluated: here, the rounding to whole microjoules. It is not the figure's total error, because the counter's own systematic error is not evaluated.
• window_us is the worker's lifetime.
• energy_counter_filtering is Unknown, because the platform does not document whether the count is filtered.

A statevector_single or cutrank_single job runs on the GPU, which this counter does not read, so its figure is partial and says so in excludes. So is a figure that includes CPU energy system services billed to the worker, since such credits land late.

On Linux there is no per-process count. The service reads the processor packages' energy counters instead, through the kernel's power-capping interface, before the worker starts and after it exits. They count whole packages, so the figure is the packages' energy over the job's window, every process on the host included. It says so: attribution is none (the macOS figure's is process), and concurrent_jobs counts the other jobs that ran in the window. The counter is used only when every package zone reads and is live (each package advancing in 80% of fifteen 20 ms intervals at start). Its declared uncertainty covers the two whole-microjoule reads and the counter's update edges, measured then, which also bound the hardware unit the interface hides.

Where the service cannot read a count (another system, a zone its user may not read, a counter that is not live, as in most containers), energy is {"unmetered": "<why>"}. It is never a figure of zero. GET /v1 says how this host meters (energy). A set's figure covers every item together; each item's own says so. wai-quantum-service run FILE runs a job in its own process and reports no energy.

Versions

GET /v1 and quantum_service_info list the engine's components (components, wai.quantum.components/1, which list_components also gives): every method, compiler pass, noise channel and format the service runs through, each with its version and the digest of its descriptor. The service runs the built-ins alone and never loads a component from a request (the extension points).

GET /v1 names the service's version and gives versions (wai.quantum.versions/1): the engine's version, the service's, the schema of each document it writes and the MCP protocol versions it speaks. The MCP server gives the same in initialize (_meta["science.transaction.wai/versions"]) and in quantum_service_info. Every result names the engine that made it and its schema (engine, schema), inside what its receipt seals. Each MCP tool's outputSchema is its answer's schema; this server's own are in schemas/service-tools.v1.json, the job's and the engine's in wai-quantum/schemas/. What is stable and for how long: the policy; what is deprecated: the deprecations.

Running it

cargo build --locked --release
WAI_QSVC_ADDR=127.0.0.1:18241 ./target/release/wai-quantum-service serve &   # serves until stopped
bash smoke.sh http://127.0.0.1:18241

Each job runs in a child process of the same binary (worker), at a lower scheduling priority than the host's other work, and is watched for its resident memory and its time. A worker whose service has gone stops itself.

Jobs are kept in WAI_QSVC_STORE (by default ~/.local/share/wai-quantum-service/store; memory keeps them only while the process runs). docs/self-host.md covers running it yourself: the OCI image (deploy/Containerfile), the configuration, the store, the keys, API keys for a private deployment, and a reverse proxy in front. docs/scheduler.md covers handing the service to an on-premises batch scheduler's jobs.

On macOS the worker runs in a sandbox (sandbox-exec): no network, no file writes, and no program but itself. It reads its job on stdin and writes its result on stdout, so it needs none of them, and a flaw in parsing a submitted circuit then reaches neither the host's files, nor the network, nor a shell. WAI_QSVC_SANDBOX=0 turns the sandbox off, for debugging.

Limits are counted per client. A client is an IPv4 address, or the /64 an IPv6 address is in: one subscriber is usually given a /64 whole, so counting single addresses would hand out fresh limits to anyone who rotates through theirs. Behind the front proxy, the client is the first X-Forwarded-For address, which the proxy sets from the edge network's own client-address header rather than passing on what the request carried.

These variables set the limits:

variable	default	meaning
WAI_QSVC_BUDGET_GB	96	memory all running jobs share
WAI_QSVC_JOB_GB	72	memory one job may take
WAI_QSVC_WORKERS	4	jobs running at once
WAI_QSVC_MIN_FREE_PCT	15	share of the host's memory a starting job must leave free
WAI_QSVC_JOB_SECS	900	the longest a job may run
WAI_QSVC_CLIENT_ACTIVE	3	queued or running jobs one client may hold
WAI_QSVC_CLIENT_GB	the job size	memory one client's queued and running jobs may hold together
WAI_QSVC_CLIENT_BURST	30	submissions one client may make per window
WAI_QSVC_CLIENT_WINDOW_SECS	600	the window
WAI_QSVC_MAX_QUEUE	256	jobs waiting at once
WAI_QSVC_RETAIN_SECS	86400	how long finished jobs are kept, across restarts
WAI_QSVC_STORE	~/.local/share/wai-quantum-service/store	the job store's directory, or memory
WAI_QSVC_API_KEYS	unset	a file of API keys' digests: set, every request but the open ones needs a key (private deployments; the public service takes none)
WAI_QSVC_ENERGY	1	0 meters no job's energy
WAI_QSVC_TRUSTED_PROXIES	127.0.0.1,::1	peers whose X-Forwarded-For names the client
WAI_QSVC_SANDBOX	1	run each worker sandboxed (macOS); 0 runs it unsandboxed
WAI_QSVC_KEY	~/.config/wai-quantum-service/signing.key	the signing key, created on first start; its key set beside it, <key>.keys.json

wai-quantum-service run job.json runs one job or set in the current process and prints its plan and its result. wai-quantum-service rotate-key retires the receipt key and makes a new one. wai-quantum-service api-key NAME makes an API key and the line for the keys file.