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.

```sh runnable
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.

```sh runnable
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`):

```sh runnable copy=../../../../quantum-conformance/eval/tasks.json
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`:

```sh runnable
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:

```sh runnable copy=../../../../quantum-conformance/eval/tasks.json
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.