open-standards/wai/wai-quantum-cli/skills/wai-quantum/reference/loop.md

The sign-off loop: check, grade, attest

Writing a quantum program is the easy part. Saying it is right takes the engine. Three calls do that, and each answer names the layer that decided it and what that layer does not show. A classical checker decides only what it can simulate, so where no layer reaches a case, the answer is unchecked, never passed.

Step	Command line	MCP tool	Sealed
Check, until it passes	wai-quantum check FILE --intent F (or --task T)	check_quantum_program	no: this is the inner loop
Grade what passed	wai-quantum grade FILE --task T	grade_quantum_program	yes: a job anyone can run again
Attest a job another host ran	wai-quantum attest JOB --trust KEYS	attest_quantum_job	yes: a sign-off with the user's key

1. Check until it passes

check reads the program and reports its diagnostics, measures and smells. Where the reader refuses it, check lists the fixes the engine would make on the flagged lines and what needs a person. Given what the program must do, check runs each case and grades it passed, failed or unchecked, with the verdict and its layer. It also says what went wrong and where to look, in the words the course's learn why uses. next is the next thing to do.

printf '{"00": 0.5, "11": 0.5}\n' > bell-dist.json            # what bell.qasm must do: its exact distribution
wai-quantum check bell.qasm --intent bell-dist.json          # passes: exit 0
wai-quantum check bell.qasm --intent bell-dist.json --json > checked.json
wai-quantum check broken.qasm                                # exits 1
wai-quantum repair broken.qasm > fixed.qasm                  # the fixes check named
wai-quantum check fixed.qasm

Exit 0 means every case passes. Exit 1 means a case fails or the program does not read. Exit 2 means no layer decided a case. Change only what the answer points at, then check again. Never call a case passed that came back unchecked.

2. Grade what passed

A task says what the program must do, in the form the course keeps its exercises in. It gives an intent, or cases (each with name, inputs for a generator's integer inputs, and intent). It may also give a job (shots, seed, noise) and constraints (allow, counts, t_count, two_qubit, no_smells, estimate, qubits, inject). A task carries no reference, wrong or hints, because the grade's receipt seals the task whole.

cat > task.json <<'EOF'
{
  "title": "A Bell pair",
  "job": { "shots": 64, "seed": 5 },
  "cases": [
    { "name": "distribution", "intent": { "distribution": { "00": 0.5, "11": 0.5 } } },
    { "name": "samples", "intent": { "sampled": { "00": 0.5, "11": 0.5 }, "test": "chi_squared", "alpha": 0.001, "shots": 400 } }
  ],
  "constraints": { "allow": ["h", "cx"], "two_qubit": { "max": 1 } }
}
EOF
wai-quantum grade bell.qasm --task task.json --json > grade.json
wai-quantum verify grade.json                                # the grade, worked out again

grade is the same check, sealed as a job (wai.quantum.grade/1). The request holds the task and the program, so anyone can run the grade again, and with the same key they get the same bytes. verify works it out again: each case's checks are decided again, each case's grade is held to the checks it rests on, and each constraint is measured again. A grade that a host sealed but its job does not bear out fails verification, though its seal holds.

A task can also come from the course (--lesson ID, its solution left out of what is sealed) or from the model harness's task set (--set tasks.json --name NAME):

wai-quantum grade bell.qasm --set tasks.json --name bell

Quote each case's grade and layer. A case decided by samples or random_states is evidence, not proof.

3. Attest a job another host ran

A job from elsewhere, such as the job service, a person's provider or another machine, carries that host's seal. attest first verifies the job as verify does: its receipt, every rule of its form, and any verdict or compile it seals, worked out again. With --trust, it holds the job's key to a trust list, and with --at, to a time. A job that fails any of these is refused, and nothing is sealed. Then attest checks what the job's answer must do (--intent) against it, and signs it off with the user's key (wai.quantum.signoff/1). Beside the sign-off, outside its seal, attested says what the job was checked against.

Here a job sealed with the published demo key stands in for another host's. The trust list names that key, as the job service publishes its own at /.well-known/wai-quantum-receipt-keys:

wai-quantum run bell.qasm --shots 100 --demo-key --json > theirs.json
cat > keys.json <<'EOF'
{ "format": "wai.quantum.receipt-keys/1", "algorithm": "ed25519",
  "keys": [{ "key": "197f6b23e16c8532c6abc838facd5ea789be0c76b2920334039bfa8b3d368d61" }] }
EOF
printf '{"outcomes": ["00", "11"]}\n' > outcomes.json
wai-quantum attest theirs.json --trust keys.json --intent outcomes.json --json > attested.json
wai-quantum verify attested.json

Attest only what the person asked you to attest. A sign-off puts the person's key on the verdict. attested is not sealed: it says what this attester held the job to, and a reader holds the job to their own trust list when they verify it (the sign-off's request is closed, so a verifier released before a sealed list would refuse every sign-off that carried one).

4. Grade a whole task set

With a task set and a program for each task, grade grades them all at once: one sealed grade a task, and a summary (wai.quantum.grades/1). The set is the model harness's (--set tasks.json, as eval run --tasks reads it) or the course's (--course, each lesson's exercise). The programs come from --programs: a JSON object from each task's name to its program, or to a model's answer with the program in a fenced block (what eval run --scripted reads), or a directory of NAME.qasm files. A task with no program is listed as missing, not graded:

cat > answers.json <<'EOF'
{ "bell": "OPENQASM 3.0;\nqubit[2] q;\nbit[2] c;\nh q[0];\ncx q[0], q[1];\nc = measure q;\n" }
EOF
wai-quantum grade --set tasks.json --programs answers.json --json > grades.json  # exits 1: only bell has a program; the rest are missing
wai-quantum verify grades.json                               # each grade made again, the set and the summary worked out again

The batch itself is not sealed; each grade in it is. verify checks each grade's receipt and makes the grade again, holds each entry's name and grade to what its grade seals, and works the set's digest and the summary out again from the entries. The same set, programs and key give the same bytes. A task listed as missing is the grader's word: to be sure it had no program, grade it again.

Where the loop runs

The same three calls, with the same answers, run on every surface:

Surface	Check	Grade	Attest
Command line	wai-quantum check	wai-quantum grade	wai-quantum attest
Local MCP server (wai-quantum mcp)	check_quantum_program	grade_quantum_program, sealed with this user's key	attest_quantum_job, sealed with this user's key
Job service	the same tools on its MCP server, and POST /v1/check	POST /v1/grade, sealed with the service's key	POST /v1/attest, sealed with the service's key
Python (wai_quantum)	wq.check(program, intent)	wq.grade(program, task, key=...)	wq.attest(job, intent, trust=...)
npm (@transaction-science/wai-quantum)	engine.check(args)	engine.grade(request)	engine.attest(args)

The job service holds each case to its bounds before any case runs (a reference compared with a wide case of a generator, for one) and refuses one past them, naming the local command: a check that takes long belongs on this machine.