open-standards/wai/wai-quantum-service/README.md

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.

A service started with a model also writes programs: send it a task, what a program must do, and its own model writes an OpenQASM program for it, the engine checking each attempt (below).

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), controls (statevector and exact: "standard" or "whole", a gate under many controls in standard gates or as one), 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's result is kept as text as it ends, so the results of earlier items take no more than they will as served. 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.

A job's result, or a set's with every item's request and result in it, may take at most WAI_QSVC_RESULT_MIB (64 MiB) as served. That is checked before anything runs, from a bound of the result read from the request: each item's counts list at most its shots (a trajectories run's, its trajectories), the outcomes its measured bits can give (a noiseless stabilizer run's, two to the power of the gates that branch, h, sx and sxdg: a GHZ state's two, however wide) and 65,536 outcomes, each its bit string, quotes, a colon, a comma and its count's digits; a verdict counts the critique's remarks the program can draw (one for each gate that does nothing and each pair that cancels or merges, not one for every gate), each intent's check with the 64 outcomes it lists at a time, and the reader's notes again; each other part is counted by what it may hold or at its length as RFC 8785 writes it, every number in its own form (1e20 is 21 characters). A request whose bound passes the cap is refused at once, 422 and J031, with the bound, its largest part (the counts, the verdict, the reader's notes, the items' requests or the rest) and what makes that part smaller in the reason, and a dry run gives the bound as result_bytes. The cap is less than a set at its most can give: at about 22 bytes a 16-bit outcome, 100 points of 65,536 outcomes each are about 150 MB, and are refused; 100 points of 16 measured bits are taken, and run to the end, up to about 30,000 shots a point (30,878 without a verdict; 30,003 over MCP, whose runs ask for one). Send fewer points or shots, split the set, or run it on your own machine (wai-quantum run), where no cap applies. A pulse run is bounded the same way, from its schedule as read: its populations and its distribution by the qubits it simulates and the captures it reads, each keyed as wide as the program's bits, its counts by its shots, and each capture with its frame's and bit's names. The check as a result ends stays only as a backstop, for a job kept across a restart that lowered the cap.

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, the most a result may take (result_bytes), the most intents, the steps a request's programs may take to read, the largest body
result_bytes	the most its result takes as served, bounded before it runs; past bounds.result_bytes it is refused, 422 and J031
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

Writing a program for a task

A service started with a model (WAI_QSVC_MODEL, the model's directory) also writes programs. POST /v1/write takes a task, and the service's own model writes an OpenQASM 3 program for it. The engine checks each attempt against the task exactly as it checks a lesson's answer in the course. What went wrong goes back to the model, in the engine's words, for the next attempt, until a program passes or the rounds run out. The model is North Mini Code 1.0 (Apache-2.0), on WAI's own pure-Rust inference runtime (wai-quantum-writer).

{ "task": { "title": "A Bell pair", "task": "Entangle two qubits so that their measured bits always agree.", "intent": { "distribution": { "00": 0.5, "11": 0.5 } } }, "rounds": 4, "max_new": 3000 }

field	meaning
task	an exercise in the course's form (wai.quantum.exercise/1): title and task in words (strings, or one per locale), an optional starter program, and what the program must do, as an intent (a job's intent) or as cases that each have one (a case without one takes the task's); optionally constraints (allow, counts, t_count, two_qubit, no_smells, estimate) and the job the check runs it as (shots, seed, noise)
rounds	repairs after the first attempt: 0 to 4 (default 4)
max_new	the most tokens one reply may take, its thinking included: 1 to 4000 (default 3000)

• The answer is 202 and the job, at once, since a write takes minutes. Its result is the transcript (wai.quantum.write/1). It names the task and its digest; the model by its name, licence and the digest of its files, how far its files were checked ("checked": "blake3": the writer reads every byte against the model's manifest when it starts, and loads exactly the files the manifest lists), and the arithmetic it ran in (architecture, operating system, maths library, matmul kernel); the prompt by its version and digests; the decoding (greedy, with its thinking cap), the memory each check's run was planned in (check_memory_bytes) and the engine's version. It holds each attempt with its program, the program's digest and the engine's check, and says whether one passed and at what level.
• Sealed as every result is. The service's receipt seals the transcript with the job's request, the writer's energy inside it, so POST /v1/verify checks it. How long each reply and each check took is the job's timing, beside the result and outside the signed body.
• Each attempt as it lands is an attempt event ({"id", "attempt", "timing"}) on GET /v1/jobs/{id}/events. A running write's job also gives progress: how many attempts the engine has checked, and the latest.
• The same task gives the same transcript, in the same arithmetic. Decoding is greedy, and the task reaches the model in its canonical form (the form its digest is taken over), so the same model files, task, options and engine give the same bytes on a host whose arithmetic is the same: the transcript's model names it. On another architecture or maths library the logits can differ in their low bits, and a near tie can go the other way. A write that was running when the service stopped is run again, once, as a job is, and gives the same transcript.
• One write at a time. The model runs in one writer process (the binary's writer mode), started with the service and kept for every write, so the model loads once. Writes wait in the queue in their order, beside the circuit jobs, and neither waits for the other: each kind fills the queue up to WAI_QSVC_MAX_QUEUE alone. A client holds one queued or running write, however many it sends at once: a second is refused (429, J030).
• Its limits. A write may run for WAI_QSVC_WRITE_SECS (an hour by default). The writer's resident memory, its model's mapped pages among it, is held to WAI_QSVC_WRITER_GB (96 GiB). The engine's checks inside it plan within one job's memory (WAI_QSVC_JOB_GB), so the check refuses a program larger than a job may be, as a job's plan does. A writer that passes its memory or its time, or whose write is cancelled, is stopped: the write fails saying which, and the next write starts the writer again. A write cancelled while the writer starts is never sent to it.
• What a task may hold. A task is held to the course's form before it is queued: every bound whole numbers, every constraint one the course names, a job of shots, seed and noise alone, at most 16 cases and 8 intents in one place. Its canonical form is at most 64 KiB, what the model is first told of it at most 8 KiB, and a program an intent compares with is held to the equivalence bounds a job's intent is (422, J031). What costs nothing to read (the shape, the options, the sizes, the number of cases and intents) is refused first, and so is what refuses whatever is sent (a write the client already holds, its results not yet read, a full queue of writes, a spent window), uncounted; then the write waits for a turn to be read, as a job does, and counts against its client's window, whatever comes of it; only then are its programs read, each once and all within one budget of 1 000 000 statements, in a reading child whose memory and time are capped (WAI_QSVC_READ_GB, WAI_QSVC_READ_SECS), as a job's are. Every case gives the same inputs, or none does.
• Refusals. A service with no model answers 503 (J080). GET /v1 says under write whether this one has a model, and names it (name, licence, digest) once it is loaded. A task without an intent, or with a case that has none and no task's intent to take, or not in the course's form or past its sizes, is 400 (J081). Options out of range, or a member a write does not take, are 400 (J082). An Idempotency-Key works as it does for a job.

The MCP tool write_circuit takes the same and runs as a task (For agents). WAI_QSVC_WRITER_SCRIPT names a script the writer runs in the model's place: a JSON list of replies, each a string, or null for a reply that never left its thinking. The service's tests write with one. smoke.sh writes a Bell pair's program when SMOKE_WRITE=1, against a service with a model.

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. Named, a job past one job's work at the bond it asks for runs under a meter of the bonds it reaches (metered in its plan, whose work is then what the meter allows) and stops with J011 if it passes it	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.

Under a contract

A job may carry a contract: the class wanted, a deadline, a cost ceiling, an energy ceiling, and whether a provider may be used (section 8.7 of the provider protocol). The service prices each method here for it, rejects those that cannot meet it, runs the cheapest of the rest and seals its reasoning in the receipt. A job no method here meets is refused at once, and in a dry run, with every method's reason (J071). The service reaches no provider: none is among its routes, whatever the contract allows, and a contract that wants a device's counts is refused. A dry run's energy is an estimate from what it has metered, and it promises nothing. A max_joules is held by a live reading of the worker while it runs, about every ten milliseconds as the host schedules the service: at the ceiling the worker is killed, read whole before it is reaped where the host allows, and a receipt is sealed that says so, with no answer in it, the worker's whole figure and the longest time between two reads. A Mac whose counter reads nothing for a process (an Intel one) reads no worker, so its routes are refused under a ceiling. A route on a host or a device nothing here reads is refused under a ceiling (energy_unwatched), and an estimate clearly past the ceiling refuses a job before it runs (energy). A run past its contract's deadline is stopped (J074), and nothing is sealed. A queued job keeps the reasoning it was admitted with across a restart. A contract is one job's: a set refuses one (J073).

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, as RFC 8785 text, the same on every route and after a restart: its status, the request as sealed (the canonical form of the one 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, for a write an attempt event for each attempt as it lands, 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 and every rule of the provider protocol's section 8.4 holds, read from the body's own text: valid, reasons, key, form, and what a provider's result says of itself. A body that does not read as a job's, is no job, has no receipt, or is longer than the 4 MiB and 2^19 values it reads (too_large, stating both) gets that reason as its verdict; past them, wai-quantum verify reads further. It is counted against the client's window for checks before it is read, and read in a reading child on one of the client's check turns (a body past 1 MiB on one of four large bodies read at once, one a client); an estimate or an algorithm's answer whose request runs again nowhere is not valid, and says why (rerun_error). An estimate or an algorithm's answer whose receipt holds is also run again, counted and read as a check is
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, clock 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
GET /metrics	the service's counters in the text exposition format (wai-metrics), for the operator at the service's own address: wai_quantum_requests_total{route,method,code} (the route a path matched, never the path), wai_quantum_jobs{status} (the jobs held now, every status from the start), wai_quantum_memory_held_bytes, wai_quantum_restored_jobs{outcome} (what the store held at the start) and wai_quantum_energy_unmetered (1 where no meter backs the jobs' energy). It is answered before the API key and the client's limits; HEAD as GET without the text, another method 405, and a request carrying a field a front sets (Forwarded, Via, X-Forwarded-*, X-Real-IP and the like) 404, as a path the service does not have. No job, client, key or address is a label. It is outside the OpenAPI document and the MCP endpoint
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 /v1/write | {"task", "rounds"?, "max_new"?}: a program written for the task by the service's model, each attempt checked by the engine; 202 and the job, its result the signed transcript (above) | | 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 or no turn to read it came (J032), on a private deployment 401 without one of its API keys (J033), an Idempotency-Key that does not read (400) or was sent before with another request (422): J034; and for a write, 503 on a service with no model (J080), 400 for a task that does not read (J081) or options out of range (J082). 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. A client holds at most WAI_QSVC_CLIENT_STREAMS (4) long polls and event streams at once: a long poll past them is not held, and says so, 429 (503 past everyone's), J032, with Retry-After: 2 and the job's status; wait that long before polling again, or poll without ?wait.

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.

A submission is admitted in the order of what each step costs:

1. A job sent again under its Idempotency-Key is answered with the key's job, before any limit: it reads nothing, takes no turn and counts as nothing. A job given in another format ("source") is matched as it was received, so it too comes back past the window. Sent again in some other form, it is read and counted to tell whether it is the same request.
2. What reads nothing and refuses whatever is sent: your jobs at once (429), the memory they hold (429), a full queue (503), a spent window (429). None of these is counted, so waiting as told spends nothing.
3. It waits for a turn to be read. If none comes, it is refused (503, J032): nothing was read and nothing is counted.
4. With its turn the submission is counted against your window. Every refusal after this counts.
5. What reads nothing: every whole number exact, at most 16 intents (each of a set's items too), at most 100 items in a set.
6. Its programs are read: the job's own, a set's items and a sweep's points, and every intent's reference, each once however often admission reads it, and all of them within one budget of 22,000,000 steps (statements the reader runs, gates it writes, a generator's loop passes and what it writes out, and every 128 bytes of a value it makes or copies). That is as many as one program may take, its statements and its gates each to the reader's bound, so a job whose own program reads within the reader's bounds reads here. A request whose programs take more is refused, 422 and J031, with the command that runs it on your machine.
7. The job is kept and queued, within your and the queue's limits, and within the most a result may take: one whose result's bound passes WAI_QSVC_RESULT_MIB is refused, 422 and J031, before it runs.

Retry-After is the pace at which a refusal that counts would not spend your window (the window over its submissions, at least 5 s), or, past the window, when the next submission opens. A 503 carries it too.

Reading happens outside the service's own process, as each job's run does: each request is read by a child, this binary run as wai-quantum-service read, sandboxed as a worker is.

• Turns. Four requests are read at a time (jobs, dry runs and the MCP tools' verdicts), and four checks beside them. A client has its share of each: WAI_QSVC_CLIENT_READS (2) of the first and WAI_QSVC_CLIENT_CHECKS (1) of the checks, so no client holds a whole pool. Past its share, one more turn is lent to a client while the pool keeps two free for others, so its quick calls (a critique, a lint, an estimate) pass its own slow one: of the checks, at their share of one; the reading pool's four turns, at its share of two, leave none to lend. A call on a lent turn moves onto the client's own turn as soon as one comes free, and then has the whole of its time and gives the lent turn back, so the client's quick calls pass it on that one; until then it runs past five seconds only while no other client's request waits for a turn and none of its own client's has waited seven seconds, and once one has it is refused, 503 and J032, to send again: two long calls of one client never hold its quick ones past their wait. Its other requests wait behind its own turns, in order, so an agent's burst of parallel calls is answered one after another: up to eight of them may wait (so its eleventh request at once, of readings or of checks, is refused), at most 32 requests wait in all, each for ten seconds, and past any of these a request is refused, 503 and J032, having read and spent nothing, saying whether its own requests or the pool held it up. A client is its address, so people behind one address (an office, a carrier's NAT, a class) share one client's turns and its window: raise the shares, or give such a group an API key of its own on a private deployment.
• Memory. A child's memory is polled every 50 ms from a thread of its own, and the child is killed once it holds more than WAI_QSVC_READ_GB (4); the request is refused, 422 and J031. The kill is a signal the service sends itself (SIGKILL, to the child's process group, and again every 100 ms until it has ended), so it needs no new process. On macOS the poll reads the child's physical footprint, which counts its compressed and swapped pages; on Linux its resident and swapped pages. A poll is not a kernel limit: a child can pass the cap by what it touches in one interval before it is killed. On Linux the child also holds its own address space to twice the cap and a gigabyte, so an allocation past that fails at once (422, J031), and the kernel ends a reader or a worker before the service when the host runs short. macOS gives an unprivileged process neither, and has no limit that counts compressed memory.
• Time. A child that reads for longer than WAI_QSVC_READ_SECS (45) is killed and the request refused, 422 and J031. Every request is answered within WAI_QSVC_ANSWER_SECS (55) of its arrival, under the 60 s a proxy in front commonly waits for an answer: its waits for a turn and its readings end by then, POST /v1/run and the MCP run tools wait for their job only for what is left and then answer with the job, still running, to poll, and an MCP answer's verdict is read again only if time is left (its verdict says so where it was not). An error-correction call's shots are measured as they run: each point is set up and sampled, and a pilot of its own shots decoded, before the rest of any; it is refused at once when what is measured says it would take more than WAI_QSVC_QEC_SECS (25), and stopped if it runs a fifth past that.
• Its answer. What a reading gives back comes into the service's memory, which every job shares: one that would take more than WAI_QSVC_READ_ANSWER_MIB (128) once read, about 80 bytes a value, is refused in the child before it is written (422, J031), and the service reads it off its request threads. A dry run gets back the plans and points alone. A check's answer can be that large: a critique of a program of 200,000 gates that each draw a remark (qubit q; for int i in [1:200000] { x q; }) is refused so; one of 150,000 is answered.
• What ended jobs keep. A job keeps its request as the canonical text the store keeps, and a set lets go of its items once it ends. What ended jobs keep in memory, their requests' text and their results as RFC 8785 text, is counted in two parts. Results that have been read (or ended more than WAI_QSVC_KEPT_MIN_SECS, 600 s, ago) are held to WAI_QSVC_CLIENT_KEPT_MIB (128) a client, its oldest dropped first, and WAI_QSVC_KEPT_MIB (4096) in all, those of the client keeping the most dropped first (between two keeping as much, the newer); only these are ever dropped before WAI_QSVC_RETAIN_SECS. Results not yet read are dropped by neither cap: a client's next job is refused, 429, while its unread results, with each job it has running at its result's bound and the new one at WAI_QSVC_RESULT_MIB (64), would pass WAI_QSVC_CLIENT_UNREAD_MIB (256), and every next job is refused, 503, while all unread results, with every job queued or running at its result's bound and the new one, would pass WAI_QSVC_UNREAD_MIB (8192). A job whose result's bound passes WAI_QSVC_RESULT_MIB is refused before it runs (see Sets and sweeps). The bounds that remain: memory for ended jobs stays under the two caps, 12 GiB at the defaults, the results of jobs still queued or running counted within the unread cap at their bounds; reaching the unread cap takes 32 clients each holding its whole allowance unread, and holds every next job for at most 600 s; a client is its address, so people behind one address share its allowances, and one of them who leaves 256 MiB unread holds the others' next jobs until it is read or 600 s pass; and an honest client's read result is dropped early only where it, of all clients, keeps the most. A request's body is parsed only once its client's window has room (or, for a resend under a key the client holds a job under, first, as it is answered before any limit). A receipt check has a window of its own, WAI_QSVC_CLIENT_VERIFIES (120), asked before its body is read. An MCP message over 64 KiB from a client past its window is read only for its id, method, tool and key, and answered under its own id with a tool result that says why; a resend under a key the client holds, and a receipt check, are read whole. A job's report is one RFC 8785 text on every route (a poll, its events, a cancel, and in the MCP job tools' answers, written with RFC 8785's numbers, the job's own bytes, with each JSON-RPC id echoed as the text it was sent as: 1.0, 1e3 and an integer past 64 bits as written) and after a restart: its request and its result are written in as the text each is kept as, never parsed again, and the memory a large request or answer was parsed into is given back to the system once it is answered. On macOS the service starts itself with the allocator's large-block cache off (MallocLargeCache=0): that cache kept every large block a parsed request had freed, dirty and charged to the service (on arm64, 30 requests of a megabyte kept 1 GiB; with it off, 2 MiB).
• Ending. A child that panics, overflows its stack or aborts is answered 500, and the service runs on. A client that hangs up ends its child.
• Connections. A request whose header section takes longer than WAI_QSVC_HEADER_SECS (150) to arrive is closed; the same limit closes a connection left idle between requests, so it is set above a proxy's own idle limit (two minutes, commonly), and the proxy, not the service, closes its idle connections. A body that takes longer than WAI_QSVC_BODY_SECS (30) is refused, 408. A client may have WAI_QSVC_CLIENT_REQUESTS (32) requests open at once; past it a request is refused, 503, before its body is read (a health check is answered whatever that is). Long polls and event streams are held to WAI_QSVC_CLIENT_STREAMS (4) a client and WAI_QSVC_STREAMS (512, at most a quarter of the connections) in all: past them a long poll is answered at once, 429 (its client's) or 503 (everyone's), J032, with Retry-After: 2 and the job's status, and an event stream is refused, 503. Four connections past the connection cap are held for health checks alone, one request each, for 2 s. The service raises its open-file limit to its hard limit as it starts (on macOS no further than kern.maxfilesperproc and 10240), says so in its log, and holds at most WAI_QSVC_CONNECTIONS (4096) connections, fewer where that limit leaves less room: past them the connection idle longest (or the one whose body has been arriving longest) is closed for the new one, so a health check is always answered, and with none to close a new connection is answered 503 at once.
• Updating. Readers and workers start from the service's own binary as it was started: on Linux its running image, elsewhere a copy it keeps beside its signing key, named by its digest. So the binary can be replaced before the restart (by a copy over it, or, on Linux, where a running binary cannot be written, by a rename), and the running service goes on with its own until it is restarted.

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, POST /v1/run or POST /v1/write 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. A send that overtakes its first, both still being read, is read and counts, and gets the one job.
• 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, write_circuit) 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.

A restart reads no program: a job keeps the plan it was admitted with, and a set its items, so what is queued delays no restart. One too large for the service's limits as they now stand fails, saying why.

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, each read and answered in a reading child as a job's admission is. Each counts against the client's submissions, as a job does, once it has its turn and before it reads anything (a check that waits ten seconds and finds no turn is refused, 503, having read and spent nothing). At most four run at a time, one of them a client's (and one more lent for a quick call), its others waiting behind it. Its bounds and its answer then read its programs within one budget, each read once: a check that runs the budget out is refused, 422 and J031, whatever it had made of it, so a repair of many fixes to a slow program ends at the budget. 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 more than 1,024 fired detectors, of a memory experiment past distance 7 or 21 rounds, 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 or 21 rounds; a decode or a threshold whose shots, measured as they run, would take more than WAI_QSVC_QEC_SECS (25 s); 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, build_algorithm and write_circuit (a program written for a task, on a service with a model). 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.

Every answer about a program states a verdict. Reading the program again for it costs what reading it cost, so it is read, in a reading child, only for a call that was counted. A poll (get_quantum_job) states what its job holds: the result's verdict where the job asked for one (verdict or intent); otherwise, and for a job not yet ended, that it reads, with empty diagnostics and critique, and a view on a poll draws nothing. A tool that says nothing about a program takes no turn. A call refused before it was counted, told to try again, or that finds no turn for its verdict states a verdict that gives the reason and nothing of the program.

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 and write_circuit as tasks (tools/call with task): initialize declares tasks (cancel, and requests.tools.call), and each one's execution.taskSupport is optional. A write's task says, while it works, how many attempts the engine has checked, and its result states the verdict of the last program it wrote.

• 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 (of the program where the request was counted, as above).
• 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. The provider protocol's §8 states the seal in full: the canonical text, the first form, how a job is read, the strict signature, and the reasons a verifier gives; quantum-conformance/receipts/ holds receipts and a second verifier written from that text.

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.

A write's figure is the writer process's. The writer runs on between writes, so the service reads its count before the write is sent and again after its last line comes back, over the write's window. The second read trails by the time the writer's threads are still on a core, which the kernel adds only when they leave it, so the figure is a lower bound by that much: its coverage is partial, and excludes says why. On Linux a write's figure is the packages' over its window, as a job's is.

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. The writer runs in the same sandbox, its model's directory read. 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_READ_GB	4	the memory one request's reading may hold, in its child
WAI_QSVC_READ_SECS	45	the time one request's reading may take
WAI_QSVC_READ_ANSWER_MIB	128	the most one request's reading may give back to the service, once read
WAI_QSVC_QEC_SECS	25	the time an error-correction call's shots may take, measured as they run
WAI_QSVC_ANSWER_SECS	55	the longest any answer takes, its waits and readings included
WAI_QSVC_CLIENT_KEPT_MIB	128	what one client's ended jobs may keep in memory
WAI_QSVC_KEPT_MIB	4096	what all ended jobs whose results have been read may keep in memory
WAI_QSVC_CLIENT_UNREAD_MIB	256	what one client's results not yet read may hold, each of its running jobs counted at its result's bound and the next at WAI_QSVC_RESULT_MIB; past it, its next job is refused (429)
WAI_QSVC_UNREAD_MIB	8192	what all results not yet read may hold; past it, every next job is refused (503)
WAI_QSVC_RESULT_MIB	64	the most one job's or set's result may take, as served: a request whose result's bound passes it is refused before it runs (422, J031)
WAI_QSVC_CLIENT_STREAMS	4	long polls (?wait=) and event streams one client may hold at once
WAI_QSVC_STREAMS	512	those of all clients, at most a quarter of the connections held
WAI_QSVC_KEPT_MIN_SECS	600	how long an ended job not yet read is kept whatever the two caps above say
WAI_QSVC_CLIENT_VERIFIES	120	receipts one client may have checked in its window (POST /v1/verify, verify_quantum_receipt)
WAI_QSVC_CLIENT_REQUESTS	32	requests one client may have open at once; past it, 503 before the body is read
WAI_QSVC_CONNECTIONS	4096	connections held at once, at most; lowered to what the open-file limit leaves room for
WAI_QSVC_CLIENT_READS	2	how many of one client's jobs, dry runs and verdicts are read at once (more wait)
WAI_QSVC_CLIENT_CHECKS	1	how many of one client's checks run at once (more wait)
WAI_QSVC_HEADER_SECS	150	how long a client may take to send a request's header section, and how long an idle connection stays open
WAI_QSVC_BODY_SECS	30	how long a client may take to send a request's body
WAI_QSVC_MAX_QUEUE	256	circuit jobs waiting at once, and writes waiting at once, each counted alone
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, and the writer, sandboxed (macOS); 0 runs them unsandboxed
WAI_QSVC_MODEL	unset	the model's directory (its files and wai-model.json): set, the service writes programs for tasks (POST /v1/write); unset, it refuses them (J080)
WAI_QSVC_WRITER_GB	96	the memory the writer process may hold, its model's mapped pages among it
WAI_QSVC_WRITE_SECS	3600	the longest a write may run
WAI_QSVC_WRITER_SCRIPT	unset	a script the writer runs in the model's place (tests)
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.