# wai-wasmq

wasmQ: a deterministic, metered, receipted WebAssembly profile for hybrid quantum-classical
programs ([`../extensions/quantum-wasmq.md`](../extensions/quantum-wasmq.md)).

An OpenQASM 3 program declares the classical functions it calls between gates with
`extern`. A wasmQ envelope carries the program, the WebAssembly modules that define those
functions and their priors, pinned by BLAKE3. This crate:

- holds a module to the profile (`profile`): Lime1, nothing imported, memory, size and
  stack bounded, each rule a refusal code; and reads a program within bounds it is held to
  as it is read, so that no short program makes a host hold or do more than it has;
- prepares it (`meter`) so that it meters its own fuel, weighs its own stack and returns
  only canonical NaNs, for an engine that does not hold those rules itself;
- runs it on two engines (`engine`): the pinned wasmtime release, and an interpreter of its
  own (`interp`) that also runs on wasm32;
- packs and opens envelopes (`envelope`), bounding from the bundle alone what a run asks of
  its host that fuel does not count, runs a bundle of Clifford gates shot by shot on
  a stabilizer tableau with each callout metered (`run`), in whole numbers throughout, and
  seals the job receipt every verifier of a job checks: the engine holds a wasmQ job to its
  form (`wai-quantum`, `engine::wasmq`), and this crate takes the profile's constants from
  there, so a run writes what a verifier holds it to;
- under the profile's second version (`wai.quantum.wasmq/2`, §11 of the text), also runs
  `t`, Toffoli and gates at dyadic angles on the engine's whole-number state vector
  (`exact`), the same bits on every host, passes angles to callouts as their numerators,
  and seals the run's energy: a reading where the host meters it (`wai-quantum run` reads
  the run in a process of its own), the unmetered form with its reason where it does not,
  and each callout's unmetered form, since no meter resolves one call;
- replays a record of calls through the modules alone (`run::replay`), and gives its digest
  (`run::transcript_blake3`);
- carries a few of the profile's own envelopes to start from (`examples`, the conformance
  set's bytes), says what a run asks of a host from the bundle alone, its work and an upper
  estimate of its memory, for a host that admits runs by them (`asks`, the job service's),
  and gives the MCP tool both servers serve, `run_wasmq`, in one wording (`tool`);
- builds the reference programs (`reference`) and checks the conformance vectors
  (`vectors`, and the `wasmq_vectors` binary).

The reference modules, the engine's qLDPC decoder and atom rearrangement planner built as
wasmQ modules, are in `modules/`; their modules of record are in
`../quantum-conformance/wasmq/modules/`.

```sh
wai-quantum pack-wasmq memory.qasm --callout decode64=qldpc_decoder.wasm \
  --prior qldpc_decoder.wasm=checks.bin --shots 1000 -o memory.wai
wai-quantum run memory.wai --json > job.json
wai-quantum verify job.json --bundle memory.wai
cargo run --release --bin wasmq_vectors -- verify ../quantum-conformance/wasmq
```

`mutations.py` removes each of the crate's checks in turn, and says which test then fails:
a check whose tests all still pass is one no test is of. It builds the crate once for each,
so it runs on a build host, not in CI.