wai-quantum 0.4.1: the fabric's WebGPU member — one WGSL kernel, certified bit-exact on every adapter #218

Merged

dcharlot merged 11 commits from wai-quantum-webgpu into main 2026-10-11 22:28:10 -04:00

Conversation 0 Commits 11 Files changed 26 +6410 -101

dcharlot commented 2026-10-11 05:08:53 -04:00

Owner

Copy link

Why

The fabric contract (0.3.41) defines members, parity against the CPU reference, certificates and placement. So far its only members are CPUs. This adds the first accelerator member: one WGSL kernel that runs the circuit core's gates on Metal, Vulkan and DX12 natively, and on a browser's WebGPU. It is certified bit-exact against the CPU reference on each adapter it finds.

Integer-first numerics are what make that provable. The kernel is a line-for-line transcription of the fabric's 32-bit-lane gate kernel (lanes), which already reproduces the i64 fixed-point core bit for bit natively and under wasm32. WGSL has no i64 and no f64, so the kernel uses only u32 values holding i32 bit patterns.

What

Stage 0: CPU groundwork (no new dependency)

• Certification (an incremental certificate builder) and Corpus.
• The fabric-v1 corpus: the random-v1 circuits plus wider ones, so every dispatch shape is exercised. Its digests are pinned.
• lanes::{GateWords, apply_words, simulate_checked, horizon}.
• A member-neutral plan module with a CPU executor.

Stage 1: the kernel and its checker

• src/quantum_fabric/lanes32.wgsl uses:
  • u32 values only;
  • shifts by literal amounts only;
  • no division, conversion, bitcast, workgroup memory or barrier.
• It carries every result as an exact 64-bit value too. It reports exactly when the reference leaves i32, with the first op index, so the member returns the reference's bits or a typed refusal, never other bits.
• lanes::horizon proves how many gates a valid circuit can run before a refusal is possible: tens of thousands at 26 qubits, far more at fewer.
• quantum_fabric::wgsl provides:
  • the implementation id (a digest of the shader and host layout);
  • gate records and dispatch grids;
  • member ids;
  • seven shader mutants, each with a named detector and a CPU-proven witness.
• wai/tools/quantum-wgsl-check (unpublished) checks the shader. It walks naga's IR for the rules above and translates the shader to MSL, SPIR-V and HLSL; the SPIR-V must pass spirv-val.

Stage 2: the native member (feature quantum_fabric_webgpu, opt-in, not in full, absent on wasm32-wasip2)

• Discovery and an Unsuitable listing.
• A device request at the downlevel limits.
• One in-place dispatch per gate, chunked submissions and readback.
• Async without an executor: native futures resolve in one poll.
• Certification, placement and receipts.
• Device tests G0–G11. Each runner must declare the adapters it has; none is a declaration too, so an adapter-less run fails instead of passing.

Stage 3: CI and release

• scripts/wai-quantum-webgpu-member.sh fails unless all of these hold:
  • every test ran;
  • the adapters found are exactly the declared ones;
  • each declared adapter earned one bit-exact certificate per pinned digest;
  • each declared adapter killed every mutant.
• .github/workflows/wai-quantum-webgpu.yml has four jobs:
  • shader checks, browser build, wasip2 inertness and MSRV;
  • software Vulkan;
  • Metal;
  • the discrete GPU on the hardware runner.
• wai_quantum_vectors verify --webgpu runs the whole conformance corpus through the member.
• wai-quantum 0.4.1, additive: default features, full and every existing pin are unchanged.

Review

An independent review of stages 0–3 found no input on which the member returns different bits from the reference. It modelled the kernel's arithmetic exactly and ran the full wide suite, up to 26 qubits, on Metal. It upheld seven smaller findings, now fixed:

• Coverage: certification and G0–G11 now run through a tiny gate ring and tiny readback pieces, so every adapter exercises the paths that only the widest circuits reached. G6 adds long small-register circuits, including an out-of-range flag across a submission boundary.
• Device loss: a failed native wait panicked inside the GPU interface. It is now caught and returned as a typed device error, and recorded so that every later call reports it.
• Timeout: the wait timeout now bounds each submission chunk, not the whole run.
• CI:
  • the hardware job fetches the exact commit it must test;
  • the path filters cover the wai-rs inputs the GPU jobs build;
  • the public-names check reads the shipped shader;
  • the checks job runs the member's device-free unit tests.
• Lockfile: wai-quantum's lockfile labels its existing hashbrown with a version, because a second version now coexists. No version moved.

Checked locally

On the Metal adapter:

• G0–G11 pass, and both gatesets reproduce the pinned random-v1 and fabric-v1 digests, including under forced dispatch geometries.
• Every conformance vector matches, and wide circuits match native.
• All seven mutants are killed, with the device's differing-pair counts equal to the CPU-proven ones.
• verify --webgpu passes the vector, reject and accept trees.

The CI script fails as intended:

• with a wrong adapter declaration;
• with the feature dropped;
• with a mutant shader;
• with one digest pin changed.

The checker fails as intended on a planted signed local, a planted variable shift and planted workgroup memory.

Both wai-quantum gates pass, natively and under wasm32-wasip2. The publish dry-run passes, and the package carries the shader.

First CI run

Some facts can only be confirmed by the first run. Each fails loudly rather than passing:

• the software Vulkan driver's adapter key in the linux container;
• the hardware runner's adapter set and Vulkan loader;
• whether the macOS runner's service context sees the Metal device.

🤖 Generated with Claude Code

## Why The fabric contract (0.3.41) defines members, parity against the CPU reference, certificates and placement. So far its only members are CPUs. This adds the first accelerator member: one WGSL kernel that runs the circuit core's gates on Metal, Vulkan and DX12 natively, and on a browser's WebGPU. It is certified **bit-exact** against the CPU reference on each adapter it finds. Integer-first numerics are what make that provable. The kernel is a line-for-line transcription of the fabric's 32-bit-lane gate kernel (`lanes`), which already reproduces the i64 fixed-point core bit for bit natively and under wasm32. WGSL has no i64 and no f64, so the kernel uses only u32 values holding i32 bit patterns. ## What **Stage 0: CPU groundwork (no new dependency)** - `Certification` (an incremental certificate builder) and `Corpus`. - The **fabric-v1** corpus: the random-v1 circuits plus wider ones, so every dispatch shape is exercised. Its digests are pinned. - `lanes::{GateWords, apply_words, simulate_checked, horizon}`. - A member-neutral `plan` module with a CPU executor. **Stage 1: the kernel and its checker** - `src/quantum_fabric/lanes32.wgsl` uses: - u32 values only; - shifts by literal amounts only; - no division, conversion, bitcast, workgroup memory or barrier. - It carries every result as an exact 64-bit value too. It reports exactly when the reference leaves i32, with the first op index, so the member returns the reference's bits or a typed refusal, never other bits. - `lanes::horizon` proves how many gates a valid circuit can run before a refusal is possible: tens of thousands at 26 qubits, far more at fewer. - `quantum_fabric::wgsl` provides: - the implementation id (a digest of the shader and host layout); - gate records and dispatch grids; - member ids; - seven shader mutants, each with a named detector and a CPU-proven witness. - `wai/tools/quantum-wgsl-check` (unpublished) checks the shader. It walks naga's IR for the rules above and translates the shader to MSL, SPIR-V and HLSL; the SPIR-V must pass `spirv-val`. **Stage 2: the native member** (feature `quantum_fabric_webgpu`, opt-in, not in `full`, absent on wasm32-wasip2) - Discovery and an `Unsuitable` listing. - A device request at the downlevel limits. - One in-place dispatch per gate, chunked submissions and readback. - Async without an executor: native futures resolve in one poll. - Certification, placement and receipts. - Device tests G0–G11. Each runner must declare the adapters it has; `none` is a declaration too, so an adapter-less run fails instead of passing. **Stage 3: CI and release** - `scripts/wai-quantum-webgpu-member.sh` fails unless all of these hold: - every test ran; - the adapters found are exactly the declared ones; - each declared adapter earned one bit-exact certificate per pinned digest; - each declared adapter killed every mutant. - `.github/workflows/wai-quantum-webgpu.yml` has four jobs: - shader checks, browser build, wasip2 inertness and MSRV; - software Vulkan; - Metal; - the discrete GPU on the hardware runner. - `wai_quantum_vectors verify --webgpu` runs the whole conformance corpus through the member. - wai-quantum 0.4.1, additive: default features, `full` and every existing pin are unchanged. ## Review An independent review of stages 0–3 found no input on which the member returns different bits from the reference. It modelled the kernel's arithmetic exactly and ran the full wide suite, up to 26 qubits, on Metal. It upheld seven smaller findings, now fixed: - **Coverage:** certification and G0–G11 now run through a tiny gate ring and tiny readback pieces, so every adapter exercises the paths that only the widest circuits reached. G6 adds long small-register circuits, including an out-of-range flag across a submission boundary. - **Device loss:** a failed native wait panicked inside the GPU interface. It is now caught and returned as a typed device error, and recorded so that every later call reports it. - **Timeout:** the wait timeout now bounds each submission chunk, not the whole run. - **CI:** - the hardware job fetches the exact commit it must test; - the path filters cover the wai-rs inputs the GPU jobs build; - the public-names check reads the shipped shader; - the checks job runs the member's device-free unit tests. - **Lockfile:** wai-quantum's lockfile labels its existing `hashbrown` with a version, because a second version now coexists. No version moved. ## Checked locally On the Metal adapter: - G0–G11 pass, and both gatesets reproduce the pinned random-v1 and fabric-v1 digests, including under forced dispatch geometries. - Every conformance vector matches, and wide circuits match native. - All seven mutants are killed, with the device's differing-pair counts equal to the CPU-proven ones. - `verify --webgpu` passes the vector, reject and accept trees. The CI script fails as intended: - with a wrong adapter declaration; - with the feature dropped; - with a mutant shader; - with one digest pin changed. The checker fails as intended on a planted signed local, a planted variable shift and planted workgroup memory. Both wai-quantum gates pass, natively and under wasm32-wasip2. The publish dry-run passes, and the package carries the shader. ## First CI run Some facts can only be confirmed by the first run. Each fails loudly rather than passing: - the software Vulkan driver's adapter key in the linux container; - the hardware runner's adapter set and Vulkan loader; - whether the macOS runner's service context sees the Metal device. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 8 commits 2026-10-11 05:08:53 -04:00

wai-quantum fabric: CPU groundwork for accelerator members ... 059e2ca06f

Everything a 32-bit-lane member needs except the device, under the existing
quantum_fabric feature and with no new dependency, so it builds and is tested
on every target including wasm32-wasip2.

- Certification: certify one case at a time, for members whose outputs arrive
  asynchronously; certify is now a loop over it (the lanes32 pins guard it).
- Corpus and fabric-v1: random-v1's circuits, then wide circuits of 11 to 17
  qubits continuing the same stream (lanes::random_wide_circuit), so every
  dispatch shape is exercised. FABRIC_DEFAULT = seed 7, 200 + 24 circuits.
  certify_lanes is certify_corpus on Corpus::Random, with the same generator
  string; random_circuit keeps its draw order.
- lanes: GateWords and gate_words, fxmul_wide, PROBE_EDGES, apply_words (the
  general 2x2 path from exact 64-bit values, flagging a gate exactly when the
  reference's result leaves 32 bits; malformed words refused), run_words,
  simulate_checked, output, reference_output, certify_corpus, and horizon: the
  gate count below which a valid circuit provably cannot leave 32 bits,
  computed in integers from the gateset's table.
- quantum_fabric::plan: the program a member runs for a circuit (one gate step
  per op, the start reduced modulo 2^n) and its CPU executor.
- Docs: the module and fxmul no longer claim that every result of a valid
  circuit fits in 32 bits; it holds within lanes::horizon.

fabric-v1 corpus digests, computed by the pin test's first run and pinned:
  circuit  41c726a0ac80f7defef92e15ecf893bdb7a3076b5e7f670fa0b7142e5c033df7
  circuit2 9a84b55af68f1a8b07390b234cf562dd8d85cef3185a697ab85690c8790a7809
The random-v1 lanes32 pins are unchanged and their test unedited.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum fabric: the WGSL gate kernel, its host layout, and a checker ... 1f7fa8666a

The kernel a WebGPU member runs, and everything such a member needs that is
not the device, under the existing quantum_fabric feature with no new
dependency; it builds and is tested on every target including wasm32-wasip2.

- lanes32.wgsl: quantum_fabric::lanes transcribed line for line into WGSL,
  every value a u32 holding a 32-bit pattern, with an exact 64-bit copy of
  every result so that the kernel reports, exactly, any result that leaves
  32 bits. No signed type, float, division, conversion, workgroup memory or
  barrier; every shift amount a literal. Entry points apply (one gate, one
  invocation per amplitude pair, in place) and probe (the wide multiply and
  the exact fx on listed operands).
- quantum_fabric::wgsl: SHADER, the implementation id (BLAKE3 over the shader
  text and HOST_LAYOUT), the 64-byte gate record, the dispatch grid
  (X_GROUPS_MAX = 64, so 2-D grids occur from 14 qubits, inside fabric-v1),
  AdapterIdentity with its member id (local/gpu-... or local/swgpu-..., both
  sorting after every local/cpu-<arch>) and CI key, and the seven textual
  mutants with their detectors. The module docs carry the argument that the
  kernel is bit-exact (same function, exact fx64, no dynamic error, order
  independence).
- .gitattributes: the shader is checked out with LF, since its bytes are hashed.
- wai/tools/quantum-wgsl-check (unpublished, own lockfile; the only place naga
  is a dependency): parses and validates SHADER under naga 30.0.1, walks the
  IR (entry points, bindings, no workgroup variable, bool/u32 scalars only, no
  conversion/division/math, literal shifts in 1..=31, atomicOr/atomicMin
  only, no barrier), translates to MSL 2.4, SPIR-V and HLSL 5.1, writes
  lanes32.spv for spirv-val, and checks every mutant validates. --shader
  <file> checks another text, to show a planted violation failing.

Pinned: implementation wgsl-lanes32/dc8e19f61e0e87ab; member ids of the two
test identities local/gpu-metal-a47619e299a8 and
local/swgpu-vulkan-917c9bb1d948 (each cross-checked by an independent BLAKE3
computation). The probe mutants' witness counts over the probe edges equal
the ones computed when the mutants were chosen.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum fabric: the WebGPU member on a native GPU ... 0ba66b2026

Adds the opt-in feature `quantum_fabric_webgpu` (not in `full`): the
32-bit-lane gate kernel of `quantum_fabric::wgsl` run through the
platform's GPU interface natively (Metal, Vulkan, DX12) and through a
browser's WebGPU on wasm32-unknown-unknown. wgpu 30.0.1 enters only those
two target tables, default features off; on every other target, wasm32-
wasip2 included, it is absent and the module is compiled out.

`quantum_fabric_webgpu`:
- discovery opens each adapter at the WebGPU downlevel limits with only
  the two buffer limits raised, lists an unsuitable one with its reason,
  pins the DX12 compiler (translator "naga+dxbc" in the member id), and
  probes the device's arithmetic against lanes before it is a member;
- a run is one dispatch per gate, in place, with gate records in a
  uniform ring at dynamic offsets, x = min(groups, 64), submissions
  bounded by a work budget, and readback in 64 MiB pieces; every step
  runs inside error scopes and uncaptured errors and device loss are
  recorded, never left to the default handler;
- every entry point is async with no executor; natively `blocking`
  resolves each call with one poll on a no-op waker, and a future still
  pending is an error;
- certification folds the member's own run of a corpus into a
  Certification, so a bit-exact member reproduces the pinned random-v1
  and fabric-v1 digests; `member` certifies both gatesets, and placement
  and receipts go through the fabric unchanged.

tests/webgpu_member.rs (required-features): G0-G11 against a declared
adapter set (WAI_QUANTUM_WEBGPU_EXPECT), with liveness lines appended to
WAI_QUANTUM_WEBGPU_REPORT. On Metal: 12 of 12 pass; both gatesets
certify bit-exact with the pinned digests, forced geometries give the
same digests, and every mutant is killed.

Docs: the package description, crate doc and README say the default
features reach no system library and this feature reaches the GPU
interface; the fabric's honest boundaries say the WebGPU member is
detected per process and runs lanes on real hardware.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum 0.4.1: CI for the WebGPU member, verify --webgpu, lockfiles ... 38c50c61ed

The member's tests run in CI on every adapter a runner declares, the
quantum corpus runs through each member, and wai-quantum is 0.4.1.

- scripts/wai-quantum-webgpu-member.sh: runs tests/webgpu_member.rs and
  fails unless all 12 tests ran and passed, the adapters found are exactly
  WAI_QUANTUM_WEBGPU_EXPECT, each declared adapter earned one bit-exact
  certificate per pinned digest (random-v1 and fabric-v1, both gatesets),
  and each killed 7 of 7 shader mutants; with WAI_QUANTUM_WEBGPU_WIDE=1 a
  GPU adapter must also have matched native at its full width.
- .github/workflows/wai-quantum-webgpu.yml (per-ref concurrency group):
  checks (linux): the shader under naga 30.0.1 and a SPIR-V validator, the
  browser build, no wgpu in the wasm32-wasip2 tree, the shader in the
  package, MSRV 1.97.0. member-software (linux, swgpu-vulkan-10005),
  member-metal (macos, gpu-metal-0), member-hw (linux-hw, gpu-vulkan-10de,
  wide sizes). The two GPU jobs then run verify --webgpu. No linux-arm64
  job; no windows job while that runner is offline.
- wai-conformance.yml: the wasm32-wasip2 job requires each new fabric unit
  test by name.
- wai-rs: feature quantum_fabric_webgpu forwards to wai-quantum's and
  re-exports the module; the requirement on wai-quantum is 0.4.1.
  wai_quantum_vectors verify <dir> --webgpu runs the whole check once per
  member, each state computed by the member, and holds each accept file to
  the native simulator's result (the 255-qubit files are refused as
  too-many-qubits by both). No member: exit 2; without the feature, the
  flag is an error.
- wai-quantum 0.4.1 with a CHANGELOG entry for the API of the last three
  commits. Lockfiles: the version line in all six that resolve
  wai-quantum (quantum-wgsl-check included); wai-rs also gains the wgpu
  tree through its new feature, at the versions wai-quantum's lock holds.

Local: on Metal the script passes; it fails with a wrong EXPECT, with the
feature dropped from its cargo test, with M1 as the shader, and with one
pin changed. verify --webgpu passes on Metal. cargo publish --dry-run and
cargo package --list pass. The runs on linux, macos and linux-hw are
pending CI.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum WebGPU member: CI review fixes ... 5fb5070f89

- The hardware job fetches the commit it must test by its full SHA, not the
  ref: a later commit on main that this workflow's paths do not match would
  otherwise be fetched instead, failing the job with nothing to retest it.
- The path filters add wai-rs's Cargo.toml, Cargo.lock and lib.rs and the
  toolchain pin: the GPU jobs build wai-rs with the forwarded feature, --locked,
  and no other workflow does.
- The public-names check reads .wgsl files: the crate ships its shader.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum WebGPU member: chunked work under test, a failed wait is typed ... 2cd6ab4672

Review findings on the member, none of which changed a result:

- Ring rewrites and multi-piece readback were never exercised below the
  wide sizes: every corpus circuit fit one submission and one readback
  piece. Hidden knobs `with_ring_records` and `with_readback_chunk` (like
  `with_max_x`) let G4 certify random-v1 through a ring of three records
  with state planes read back twelve bytes at a time, and fabric-v1
  through a ring of two with pieces of 12 KiB and four bytes; both give
  the pinned digests. G6 adds long four-qubit circuits in each gateset,
  more gates than one submission holds, at the default ring and a ring of
  three, against native; and a run whose first out-of-range op sits in a
  later submission than the first, with a later one after it, reported
  at its op-log index.
- wgpu's native device poll reports a failed wait other than a timeout,
  such as device loss, by panicking. The poll now runs under
  catch_unwind: the panic becomes WebGpuError::Device and the device is
  treated as lost from then on. Documented, including that a
  panic = "abort" build still aborts. A unit test holds the mapping.
- POLL_TIMEOUT bounded the whole run's GPU time, since the first wait was
  on the readback queued behind every gate submission. Natively each
  submission, a chunk of gates sized by the work budget, the probe's
  dispatch or a readback copy, is now waited on before the next, so the
  timeout bounds one chunk. The documentation and changelog say so.

Still 12 device tests; the member script's checks are unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum WebGPU member: the checks job runs the member's unit tests ... 0c02f30c28

The guard that types a failed native wait is tested without a device, by a
unit test that only the feature build compiles; no job ran it. The checks job
now runs the member's unit tests and fails unless that test ran and passed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Merge remote-tracking branch 'origin/main' into wai-quantum-webgpu ... bb9b276002

# Conflicts:
#	wai/CHANGELOG.md
#	wai/wai-rs/Cargo.lock

dcharlot added 1 commit 2026-10-11 05:52:22 -04:00

wai-quantum WebGPU member: jetson-hub declares both of its adapters ... 03e09d47b2

The first run found the discrete GPU and a software Vulkan driver on that host
(gpu-vulkan-10de and swgpu-vulkan-10005), and G0 refused the run as declared.
Both are declared now; the wide sizes run on the GPU only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot added 1 commit 2026-10-11 16:59:18 -04:00

Merge remote-tracking branch 'origin/main' into wai-quantum-webgpu ... d602453977

# Conflicts:
#	wai/CHANGELOG.md

dcharlot added 1 commit 2026-10-11 22:27:43 -04:00

Merge remote-tracking branch 'origin/main' into wai-quantum-webgpu ... 6218369c32

# Conflicts:
#	wai/CHANGELOG.md

dcharlot merged commit 1946c7502f into main 2026-10-11 22:28:10 -04:00

dcharlot referenced this pull request from a commit 2026-10-11 22:28:12 -04:00

Merge pull request 'wai-quantum 0.4.1: the fabric's WebGPU member — one WGSL kernel, certified bit-exact on every adapter' (#218) from wai-quantum-webgpu into main

dcharlot referenced this pull request 2026-10-11 22:59:51 -04:00

wai-vector: the default stroke set and the test repertoire, as WSF1 sources expanded by Annex A, and the text vectors (D7-5) #224

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!218

No description provided.