open-standards/wai/wai-wasmq/README.md

wai-wasmq

wasmQ: a deterministic, metered, receipted WebAssembly profile for hybrid quantum-classical programs (../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;
• replays a record of calls through the modules alone (run::replay), and gives its digest (run::transcript_blake3);
• 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/.

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.