@simulatte/webgpu 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -7,19 +7,41 @@ retrofitted from package version history and package-surface commits so the npm
 package has a conventional release history alongside the broader Fawn status
 and process documents.
 
+## [0.2.4] - 2026-03-11
+
+### Changed
+
+- `doe.runCompute()` now infers binding access from Doe helper-created buffer
+  usage and fails fast when a bare binding lacks Doe usage metadata or uses a
+  non-bindable/ambiguous usage shape.
+- Simplified the compute-surface README example to use inferred binding access
+  (`bindings: [input, output]`) and the device-bound `doe.bind(await
+  requestDevice())` flow directly.
+- Clarified the install contract for non-prebuilt platforms: the `node-gyp`
+  fallback only builds the native addon and does not bundle `libwebgpu_doe`
+  plus the required Dawn sidecar.
+- Aligned the published package docs and API contract with the current
+  `@simulatte/webgpu`, `@simulatte/webgpu/compute`, and `@simulatte/webgpu/full`
+  export surface.
+
 ## [0.2.3] - 2026-03-10
 
 ### Added
 
 - macOS arm64 (Metal) prebuilds shipped alongside existing Linux x64 (Vulkan).
-- Monte Carlo pi estimation example in the README, replacing the trivial
-  buffer-readback snippet with a real GPU compute demonstration.
 - "Verify your install" section with `npm run smoke` and `npm test` guidance.
+- Added explicit package export surfaces for `@simulatte/webgpu` (default
+  full) and `@simulatte/webgpu/compute`, plus the first `doe` ergonomic
+  namespace for buffer/readback/compute helpers.
+- Added `doe.bind(device)` so the ergonomic helper surface supports device-bound
+  workflows in addition to static helper calls.
 
 ### Changed
 
-- Restructured package README for consumers: examples, quickstart, and
-  verification first; building from source and Fawn developer context at the end.
+- Restructured the package README around the default full surface,
+  `@simulatte/webgpu/compute`, and the `doe` helper surface.
+- `doe.runCompute()` now infers binding access from Doe helper-created buffer
+  usage and fails fast for bare bindings that do not carry Doe usage metadata.
 - Fixed broken README image links to use bundled asset paths instead of dead
   raw GitHub URLs.
 - Root Fawn README now directs package users to the package README.

package/README.md

@@ -1,16 +1,38 @@
 # @simulatte/webgpu
 
-Headless WebGPU for Node.js and Bun, powered by Doe, Fawn's Zig WebGPU
-runtime.
+Headless WebGPU for Node.js and Bun, powered by Doe.
 
 <p align="center">
   <img src="assets/fawn-icon-main-256.png" alt="Fawn logo" width="196" />
 </p>
 
-Use this package for headless compute, CI, benchmarking, and offscreen GPU
-execution. It is built for explicit runtime behavior, deterministic
-traceability, and artifact-backed performance work. It is not a DOM/canvas
-package and it should not be read as a promise of full browser-surface parity.
+Use this package for compute, CI, benchmarking, and offscreen GPU execution.
+It is not a DOM/canvas package and it does not target browser-surface parity.
+
+## Install
+
+```bash
+npm install @simulatte/webgpu
+```
+
+The install ships platform-specific prebuilds for macOS arm64 (Metal) and
+Linux x64 (Vulkan). If no prebuild matches your platform, the installer falls
+back to building the native addon with `node-gyp` only; it does not build or
+bundle `libwebgpu_doe` and the required Dawn sidecar for you. On unsupported
+platforms, use a local Fawn workspace build for those runtime libraries.
+
+## Choose a surface
+
+| Import | Surface | Includes |
+| --- | --- | --- |
+| `@simulatte/webgpu` | Default full surface | Buffers, compute, textures, samplers, render, Doe helpers |
+| `@simulatte/webgpu/compute` | Compute-first surface | Buffers, compute, copy/upload/readback, Doe helpers |
+| `@simulatte/webgpu/full` | Explicit full surface | Same contract as the default package surface |
+
+Use `@simulatte/webgpu/compute` when you want the constrained package contract
+for AI workloads and other buffer/dispatch-heavy headless execution. The
+compute surface intentionally omits render and sampler methods from the JS
+facade.
 
 ## Quick examples
 
@@ -22,7 +44,7 @@ import { providerInfo } from "@simulatte/webgpu";
 console.log(providerInfo());
 ```
 
-### Request a device
+### Request a full device
 
 ```js
 import { requestDevice } from "@simulatte/webgpu";
@@ -31,289 +53,113 @@ const device = await requestDevice();
 console.log(device.limits.maxBufferSize);
 ```
 
-### Estimate pi on the GPU
-
-65,536 threads each test 1,024 points inside the unit square. Each thread
-hashes its index to produce sample coordinates, counts how many land inside
-the unit circle, and writes its count to a results array. The CPU sums the
-counts and computes pi ≈ 4 × hits / total.
+### Request a compute-only device
 
 ```js
-import { globals, requestDevice } from "@simulatte/webgpu";
+import { requestDevice } from "@simulatte/webgpu/compute";
 
-const { GPUBufferUsage, GPUMapMode, GPUShaderStage } = globals;
 const device = await requestDevice();
+console.log(typeof device.createComputePipeline); // "function"
+console.log(typeof device.createRenderPipeline);  // "undefined"
+```
 
-const THREADS = 65536;
-const WORKGROUP_SIZE = 256;
-const SAMPLES_PER_THREAD = 1024;
-
-if (THREADS % WORKGROUP_SIZE !== 0) {
-  throw new Error("THREADS must be a multiple of WORKGROUP_SIZE");
-}
+### Run a small compute job with `doe`
 
-const shader = device.createShaderModule({
-  code: `
-    @group(0) @binding(0) var<storage, read_write> counts: array<u32>;
-
-    fn hash(n: u32) -> u32 {
-      var x = n;
-      x ^= x >> 16u;
-      x *= 0x45d9f3bu;
-      x ^= x >> 16u;
-      x *= 0x45d9f3bu;
-      x ^= x >> 16u;
-      return x;
-    }
+```js
+import { doe, requestDevice } from "@simulatte/webgpu/compute";
 
-    @compute @workgroup_size(${WORKGROUP_SIZE})
-    fn main(@builtin(global_invocation_id) gid: vec3u) {
-      var count = 0u;
-      for (var i = 0u; i < ${SAMPLES_PER_THREAD}u; i += 1u) {
-        let idx = gid.x * ${SAMPLES_PER_THREAD}u + i;
-        let x = f32(hash(idx * 2u)) / 4294967295.0;
-        let y = f32(hash(idx * 2u + 1u)) / 4294967295.0;
-        if x * x + y * y <= 1.0 {
-          count += 1u;
-        }
-      }
-      counts[gid.x] = count;
-    }
-  `,
-});
+const gpu = doe.bind(await requestDevice());
 
-const bindGroupLayout = device.createBindGroupLayout({
-  entries: [{
-    binding: 0,
-    visibility: GPUShaderStage.COMPUTE,
-    buffer: { type: "storage" },
-  }],
-});
+const input = gpu.createBufferFromData(new Float32Array([1, 2, 3, 4]));
 
-const pipeline = device.createComputePipeline({
-  layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
-  compute: { module: shader, entryPoint: "main" },
+const output = gpu.createBuffer({
+  size: input.size,
+  usage: "storage-readwrite",
 });
 
-const countsBuffer = device.createBuffer({
-  size: THREADS * 4,
-  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-});
-const readback = device.createBuffer({
-  size: THREADS * 4,
-  usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-});
+await gpu.runCompute({
+  code: `
+    @group(0) @binding(0) var<storage, read> src: array<f32>;
+    @group(0) @binding(1) var<storage, read_write> dst: array<f32>;
 
-const bindGroup = device.createBindGroup({
-  layout: bindGroupLayout,
-  entries: [{ binding: 0, resource: { buffer: countsBuffer } }],
+    @compute @workgroup_size(4)
+    fn main(@builtin(global_invocation_id) gid: vec3u) {
+      let i = gid.x;
+      dst[i] = src[i] * 2.0;
+    }
+  `,
+  bindings: [input, output],
+  workgroups: 1,
 });
 
-const encoder = device.createCommandEncoder();
-const pass = encoder.beginComputePass();
-pass.setPipeline(pipeline);
-pass.setBindGroup(0, bindGroup);
-pass.dispatchWorkgroups(THREADS / WORKGROUP_SIZE);
-pass.end();
-encoder.copyBufferToBuffer(countsBuffer, 0, readback, 0, THREADS * 4);
-device.queue.submit([encoder.finish()]);
-
-await readback.mapAsync(GPUMapMode.READ);
-const counts = new Uint32Array(readback.getMappedRange());
-const hits = counts.reduce((a, b) => a + b, 0);
-readback.unmap();
-
-const total = THREADS * SAMPLES_PER_THREAD;
-const pi = 4 * hits / total;
-console.log(`${total.toLocaleString()} samples → pi ≈ ${pi.toFixed(6)}`);
+const result = await gpu.readBuffer(output, Float32Array);
+console.log(Array.from(result)); // [2, 4, 6, 8]
 ```
 
-Expected output will vary slightly, but it should look like:
-
-```
-67,108,864 samples → pi ≈ 3.14...
-```
-
-Increase `SAMPLES_PER_THREAD` for more precision.
+`doe` is available from both `@simulatte/webgpu` and
+`@simulatte/webgpu/compute`. It provides a small ergonomic layer for common
+headless tasks: `doe.bind(device)` for device-bound workflows, plus static
+buffer creation, readback, one-shot compute dispatch, and
+reusable compiled compute kernels.
+Binding access is inferred from Doe helper-created buffer usage when possible.
+For raw WebGPU buffers or non-bindable/ambiguous usage, pass
+`{ buffer, access }` explicitly.
 
 ## What this package is
 
 `@simulatte/webgpu` is the canonical package surface for Doe. Node uses an
 N-API addon and Bun currently routes through the same addon-backed runtime
-entry to load `libwebgpu_doe`. Current package builds still ship a Dawn sidecar
-where proc resolution requires it. The experimental raw Bun FFI path remains in
-`src/bun-ffi.js`, but it is not the default package entry.
-
-Doe is a Zig-first WebGPU runtime with explicit allocator control, startup-time
-profile and quirk binding, a native WGSL pipeline (`lexer -> parser ->
-semantic analysis -> IR -> backend emitters`), and explicit
-Vulkan/Metal/D3D12 execution paths in one system. Optional
-`-Dlean-verified=true` builds use Lean 4 where proved invariants can be
-hoisted out of runtime branches instead of being re-checked on every command;
-package consumers should not assume that path by default.
-
-Doe also keeps adapter and driver quirks explicit. Profile selection happens at
-startup, quirk data is schema-backed, and the runtime binds the selected
-profile instead of relying on hidden per-command fallback logic.
+entry to load `libwebgpu_doe`. Current builds still ship a Dawn sidecar where
+proc resolution requires it.
+
+Doe is a Zig-first WebGPU runtime with explicit profile and quirk binding, a
+native WGSL pipeline (`lexer -> parser -> semantic analysis -> IR -> backend
+emitters`), and explicit Vulkan/Metal/D3D12 execution paths in one system.
+Optional `-Dlean-verified=true` builds use Lean 4 where proved invariants can
+be hoisted out of runtime branches instead of being re-checked on every
+command; package consumers should not assume that path by default.
 
 ## Current scope
 
-- Node is the primary supported package surface (N-API bridge).
-- Bun has API parity with Node through the package's addon-backed runtime entry
-  (61/61 contract tests passing). Bun benchmark cube maturity remains
-  prototype until the comparable macOS cells stabilize across repeated
-  governed runs.
-- Package-surface comparisons should be read through the benchmark cube outputs
-  under `bench/out/cube/`, not as a replacement for strict backend reports.
+- `@simulatte/webgpu` is the default full headless package surface.
+- `@simulatte/webgpu/compute` is the compute-first subset for AI workloads.
+- Node is the primary supported package surface.
+- Bun currently shares the addon-backed runtime entry with Node.
+- Package-surface comparisons should be read through the published repository
+  benchmark artifacts, not as a replacement for strict backend reports.
 
 <p align="center">
   <img src="assets/package-surface-cube-snapshot.svg" alt="Static package-surface benchmark cube snapshot" width="920" />
 </p>
 
-Package-surface benchmark evidence lives under `bench/out/cube/latest/`. Read
-those rows as package-surface positioning data, not as substitutes for strict
-backend-native claim lanes.
-
-## Quick start
-
-```bash
-npm install @simulatte/webgpu
-```
-
-```js
-import { providerInfo, requestDevice } from "@simulatte/webgpu";
-
-console.log(providerInfo());
-
-const device = await requestDevice();
-console.log(device.limits.maxBufferSize);
-```
-
-The install ships platform-specific prebuilds for macOS arm64 (Metal) and
-Linux x64 (Vulkan). The commands are the same on both platforms; the correct
-backend is selected automatically. The only external prerequisite is GPU
-drivers on the host. If no prebuild matches your platform, install falls back
-to building from source via node-gyp.
-
 ## Verify your install
 
-After installing, run the smoke test to confirm native library loading and a
-GPU round-trip:
-
 ```bash
 npm run smoke
-```
-
-To run the full contract test suite (adapter, device, buffers, compute
-dispatch with readback, textures, samplers):
-
-```bash
-npm test                     # Node
-npm run test:bun             # Bun
-```
-
-If `npm run smoke` fails, check that GPU drivers are installed and that your
-platform is supported (macOS arm64 or Linux x64).
-
-## Building from source
-
-Use this when working from the Fawn repo checkout or rebuilding the addon
-against a local Doe runtime build.
-
-```bash
-# From the Fawn workspace root:
-cd zig && zig build dropin   # build libwebgpu_doe + Dawn sidecar
-
-cd nursery/webgpu
-npm run build:addon          # compile doe_napi.node from source
-npm run smoke                # verify native loading + GPU round-trip
-npm test                     # Node contract tests
-npm run test:bun             # Bun contract tests
-```
-
-Current macOS arm64 validation for `0.2.3` was rerun on March 10, 2026 with:
-
-```bash
-cd zig && zig build dropin
-
-cd nursery/webgpu
-npm run build:addon
-npm run smoke
 npm test
 npm run test:bun
-npm run prebuild -- --skip-addon-build
-npm pack --dry-run
-```
-
-That path is green on the Apple Metal host. `npm run test:bun` also passed on
-this host (`61 passed, 0 failed`) once Bun was added to `PATH`.
-
-For Fawn development setup, build toolchain requirements, and benchmark
-harness usage, see the [Fawn project README](../../README.md).
-
-## Packaging prebuilds (CI / release)
-
-```bash
-npm run prebuild             # assembles prebuilds/<platform>-<arch>/
 ```
 
-Supported prebuild targets: macOS arm64 (Metal), Linux x64 (Vulkan),
-Windows x64 (D3D12). Host GPU drivers are the only external prerequisite.
-Install uses prebuilds when available, falls back to node-gyp from source.
-Tracked `prebuilds/<platform>-<arch>/` directories are the source of truth for
-reproducible package publishes. If a prebuild exists only on one local machine
-and is not committed, `npm pack` output will differ by environment.
-Generated `.tgz` package archives are release outputs and should not be
-committed to the repo.
-Prebuild `metadata.json` now records `doeBuild.leanVerifiedBuild` and
-`proofArtifactSha256`, and `providerInfo()` surfaces the same values when
-metadata is present.
-
-Package publication still depends on the governed Linux Vulkan release lane in
-[`process.md`](../../process.md). A green macOS package rerun is necessary, but
-not sufficient, for a release publish.
-
-## Current caveats
-
-- This package is for headless benchmarking and CI workflows, not full browser
-  parity.
-- Node provider comparisons are host-local package/runtime evidence measured
-  with package-level timers. They are useful surface-positioning data, not
-  backend claim substantiation or a broad "the package is faster" claim.
-- `@simulatte/webgpu` does not yet have a single broad cross-surface speed
-  claim. Current performance evidence is split across Node package-surface
-  runs, prototype Bun package-surface runs, and workload-specific strict
-  backend reports.
-- Linux Node Doe-native path is now wired end-to-end (Linux guard removed).
-  No `DOE_WEBGPU_LIB` env var needed when prebuilds or workspace artifacts
-  are present.
-- Fresh macOS package evidence from March 10, 2026 is reflected in
-  `bench/out/cube/latest/` (generated `2026-03-10T20:31:02.431911Z`):
-  Bun `uploads`, `compute_e2e`, and `full_comparable` are `claimable`;
-  Node `uploads`, `compute_e2e`, and `full_comparable` are also `claimable`.
-- Separate Apple Metal extended-comparable backend evidence from March 10, 2026
-  (`bench/out/apple-metal/extended-comparable/20260310T121546Z/`) is
-  `31/31` comparable and `31/31` claimable. Read that lane as stricter
-  backend evidence, not as a replacement for the package-surface cube rows.
-- Bun has API parity with Node (61/61 contract tests). The package-default Bun
-  entry currently routes through the addon-backed runtime, while
-  `src/bun-ffi.js` remains experimental. Bun benchmark lane is at
-  `bench/bun/compare.js`; benchmark interpretations should note which runtime
-  entry was exercised. Latest fresh macOS run
-  (`bench/out/bun-doe-vs-webgpu/doe-vs-bun-webgpu-2026-03-10T195022524Z.json`)
-  executes all `12` current workloads and has `9` comparable rows, all `9`
-  claimable. `compute_e2e_{256,4096,65536}` and
-  `copy_buffer_to_buffer_4kb` are claimable in the full macOS package lane.
-  The remaining three rows are intentional directional-only workloads
-  (`submit_empty`, `pipeline_create`, `compute_dispatch_simple`).
-- Latest fresh macOS Node package run
-  (`bench/out/node-doe-vs-dawn-claim-full/doe-vs-dawn-node-2026-03-10T202406545Z.json`)
-  has `12` total rows, `9` comparable rows, and all `9` comparable rows are
-  claimable. `compute_e2e_{256,4096,65536}`, `copy_buffer_to_buffer_4kb`,
-  and the current upload set are claimable in the full package lane. The
-  remaining three rows are intentional directional-only workloads
-  (`submit_empty`, `pipeline_create`, `compute_dispatch_simple`).
-- Self-contained install ships prebuilt `doe_napi.node` + `libwebgpu_doe` +
-  Dawn sidecar per platform. See **Verify your install** above.
-- API details live in `API_CONTRACT.md`.
-- Compatibility scope is documented in `COMPAT_SCOPE.md`.
+`npm run smoke` checks native library loading and a GPU round-trip. `npm test`
+covers the Node package contract and a packed-tarball export/import check.
+
+## Caveats
+
+- This is a headless package, not a browser DOM/canvas package.
+- `@simulatte/webgpu/compute` is intentionally narrower than the default full
+  surface.
+- Bun currently shares the addon-backed runtime entry with Node. Package-surface
+  contract tests are green, and current comparable macOS package cells are
+  claimable. Any FFI-specific claims remain scoped to the experimental Bun FFI
+  path until separately revalidated.
+- Package-surface benchmark rows are positioning data; backend-native claim
+  lanes remain the source of truth for strict Doe-vs-Dawn claims.
+
+## Further reading
+
+- [API contract](./api-contract.md)
+- [Support contracts](./support-contracts.md)
+- [Compatibility scope](./compat-scope.md)
+- [Layering plan](./layering-plan.md)
+- [Headless WebGPU comparison](./headless-webgpu-comparison.md)
+- [Zig source inventory](./zig-source-inventory.md)

package/{API_CONTRACT.md → api-contract.md}

@@ -2,21 +2,45 @@
 
 Contract version: `v1`
 
-Scope: current single-surface headless WebGPU package contract for Node.js and
-Bun, plus Doe runtime helpers used by benchmarking, CI, and artifact-backed
-comparison workflows.
+Scope: current headless WebGPU package contract for Node.js and Bun, with a
+default `full` surface, an explicit `compute` subpath, and Doe runtime helpers
+used by benchmarking, CI, and artifact-backed comparison workflows.
 
-This is the current single-surface package contract.
-For the proposed future layered `core` vs `full` support split, see
-`SUPPORT_CONTRACTS.md`.
+For the current `compute` vs `full` support split, see
+[`./support-contracts.md`](./support-contracts.md).
 
 This contract covers package-surface GPU access, provider metadata, and helper
 entrypoints. It does not promise DOM/canvas ownership or browser-process
 parity.
 
-## Node runtime API
+## Export surfaces
 
-Module: `@simulatte/webgpu` (Node default export target)
+### `@simulatte/webgpu`
+
+Default package surface.
+
+Contract:
+
+- headless `full` surface
+- includes compute plus render/sampler/surface APIs already exposed by the package runtime
+- also exports the `doe` ergonomic namespace
+
+### `@simulatte/webgpu/compute`
+
+Compute-first package surface.
+
+Contract:
+
+- sized for AI workloads and other buffer/dispatch-heavy headless execution
+- excludes render/sampler/surface methods from the public JS facade
+- also exports the same `doe` ergonomic namespace
+
+## Shared runtime API
+
+Modules:
+
+- `@simulatte/webgpu`
+- `@simulatte/webgpu/compute`
 
 ### `create(createArgs?)`
 
@@ -73,6 +97,11 @@ Output:
 
 - `Promise<GPUDevice>`
 
+On `@simulatte/webgpu/compute`, the returned device is a compute-only facade:
+
+- buffer / bind group / compute pipeline / command encoder / queue methods are available
+- render / sampler / surface methods are intentionally absent from the facade
+
 ### `providerInfo()`
 
 Output object:
@@ -95,6 +124,27 @@ Behavior:
   metadata is available
 - does not guess: if metadata is unavailable, `leanVerifiedBuild` is `null`
 
+### `doe`
+
+Output object:
+
+- `bind(device)`
+- `createBuffer(device, options)`
+- `createBufferFromData(device, data, options?)`
+- `readBuffer(device, buffer, TypedArray, options?)`
+- `runCompute(device, options)`
+- `compileCompute(device, options)`
+
+Behavior:
+
+- provides an ergonomic JS surface for common headless compute tasks
+- supports both static helper calls and `doe.bind(device)` for device-bound workflows
+- infers `runCompute(...).bindings` access from Doe helper-created buffer usage when that
+  usage maps to one bindable access mode (`uniform`, `storage-read`, `storage-readwrite`)
+- fails fast for bare bindings that do not carry Doe helper usage metadata or whose
+  usage is non-bindable/ambiguous; callers must pass `{ buffer, access }` explicitly
+- additive only; it does not replace the raw WebGPU-facing package API
+
 ### `createDoeRuntime(options?)`
 
 Input:

package/assets/package-surface-cube-snapshot.svg

@@ -60,22 +60,22 @@
 
   <rect x="640" y="176" width="488" height="318" rx="24" class="panel toneRight"/>
   <text x="668" y="216" class="cardTitle">Bun package lane</text>
-  <text x="668" y="244" class="cardMeta">Prototype support | linux_x64</text>
-  <text x="668" y="266" class="cardMeta">latest populated cell 2026-03-06T21:55:26.482Z</text>
+  <text x="668" y="244" class="cardMeta">Validated support | mac_apple_silicon</text>
+  <text x="668" y="266" class="cardMeta">latest populated cell 2026-03-10T19:50:22.523Z</text>
 
   <rect x="658" y="300" width="452" height="82" rx="16" class="metric toneRight"/>
   <text x="682" y="331" class="metricTitle">Compute E2E</text>
   <rect x="954" y="315" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
   <text x="1020" y="334" text-anchor="middle" class="pillText">CLAIMABLE</text>
   <text x="682" y="357" class="metricBody">3 rows | claimable</text>
-  <text x="682" y="377" class="metricBody">median p50 delta +77.2%</text>
+  <text x="682" y="377" class="metricBody">median p50 delta +53.1%</text>
 
   <rect x="658" y="396" width="452" height="82" rx="16" class="metric toneRight"/>
   <text x="682" y="427" class="metricTitle">Uploads</text>
-  <rect x="954" y="411" width="132" height="28" rx="14" fill="#d97706" stroke="#fbbf24" stroke-width="1.5"/>
-  <text x="1020" y="430" text-anchor="middle" class="pillText">COMPARABLE</text>
-  <text x="682" y="453" class="metricBody">5 rows | comparable</text>
-  <text x="682" y="473" class="metricBody">median p50 delta +8.6%</text>
+  <rect x="954" y="411" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
+  <text x="1020" y="430" text-anchor="middle" class="pillText">CLAIMABLE</text>
+  <text x="682" y="453" class="metricBody">5 rows | claimable</text>
+  <text x="682" y="473" class="metricBody">median p50 delta +67.8%</text>
   <text x="72" y="590" class="foot">Generated by nursery/webgpu/scripts/generate-readme-assets.js.</text>
   <text x="72" y="612" class="foot">Static claim and comparability card from the package-surface cube. It is not a substitute for strict backend reports.</text>
 </svg>

package/{COMPAT_SCOPE.md → compat-scope.md}

@@ -43,4 +43,4 @@ Layering note:
 
 - this file describes the current package surface and its present non-goals
 - proposed future `core` vs `full` support contracts are defined separately in
-  `SUPPORT_CONTRACTS.md`
+  [`./support-contracts.md`](./support-contracts.md)

package/{LAYERING_PLAN.md → layering-plan.md}

@@ -20,10 +20,10 @@ It answers four questions:
 
 Use this together with:
 
-- `SUPPORT_CONTRACTS.md` for product/support scope
-- `API_CONTRACT.md` for the current single-surface package contract
-- `COMPAT_SCOPE.md` for current package non-goals
-- `ZIG_SOURCE_INVENTORY.md` for the current `zig/src` file map
+- `support-contracts.md` for product/support scope
+- `api-contract.md` for the current package contract (`full` default, `compute` subpath)
+- `compat-scope.md` for current package non-goals
+- `zig-source-inventory.md` for the current `zig/src` file map
 
 ## Current state
 
@@ -37,7 +37,7 @@ Current reality:
 4. Canonical texture command handling now lives in `zig/src/core/resource/wgpu_texture_commands.zig`; canonical sampler and surface command handling now lives in `zig/src/full/render/wgpu_sampler_commands.zig` and `zig/src/full/surface/wgpu_surface_commands.zig`.
 5. `zig/src/wgpu_commands.zig`, `zig/src/wgpu_resources.zig`, and `zig/src/wgpu_extended_commands.zig` are now compatibility façades over the canonical subtrees, while `zig/src/webgpu_ffi.zig` remains the public façade and owner of `WebGPUBackend`.
 6. Dedicated Zig test lanes now exist as `zig build test-core` and `zig build test-full`, but split coverage remains thin and capability tracking is still represented by one shared coverage ledger.
-7. The JS package still exposes a single surface today.
+7. The JS package now exposes a default `full` surface plus an explicit `compute` subpath, while the underlying JS implementation is still shared.
 
 That means this plan is now materially physicalized in the tree, and the remaining semantic split is concentrated in the public façade files and backend roots.
 
@@ -195,12 +195,14 @@ lean/Fawn/Core/
 lean/Fawn/Full/
 ```
 
-Matching package layout can be one of:
+Matching package layout is currently:
 
 1. one package with scoped exports
-2. separate packages with separate contracts
+   - `@simulatte/webgpu` => `full`
+   - `@simulatte/webgpu/compute` => compute-first subset
 
-Packaging choice is secondary. The source boundary must come first.
+Separate packages remain optional later, but they are not the current shape.
+The source boundary still comes first.
 
 ## Refactor order