@simulatte/webgpu 0.2.1 → 0.2.4

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to `@simulatte/webgpu` are documented in this file.
+
+This changelog is package-facing and release-oriented. Early entries were
+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).
+- "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 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.
+- Fixed 4 Metal benchmark workload contracts with asymmetric repeat accounting;
+  all 31 comparable workloads now have symmetric `leftCommandRepeat` /
+  `rightCommandRepeat`.
+
+## [0.2.2] - 2026-03-10
+
+### Added
+
+- Added a Linux regression test guarding the drop-in loader against reopening
+  `libwebgpu_doe` as its own target WebGPU provider.
+
+### Changed
+
+- Fixed Linux drop-in proc resolution so workspace-local Node and Bun package
+  loads resolve Dawn/WebGPU target symbols instead of recursing through the Doe
+  drop-in library.
+- Validated the package release surface on Linux Vulkan with addon build, smoke,
+  Node tests, prebuild assembly, and Bun contract tests.
+
+## [0.2.1] - 2026-03-07
+
+### Added
+
+- Added package repository, homepage, and issue metadata.
+- Added packaged README asset generation support and shipped package assets.
+- Added additional package-surface contract documents and metadata schemas to
+  the published file set.
+
+### Changed
+
+- Refined the package surface around the canonical Doe-backed Node and Bun
+  entrypoints.
+- Expanded package publishing inputs to include scripts, prebuilds, and package
+  documentation needed for reproducible installs.
+
+## [0.2.0] - 2026-03-06
+
+### Added
+
+- Promoted the package to the public `@simulatte/webgpu` name.
+- Added Node and Bun entrypoints, benchmark CLI wrappers, and a native addon
+  bridge for headless WebGPU execution.
+- Added package install, build, test, smoke, and prebuild workflows.
+
+### Changed
+
+- Replaced the earlier placeholder package metadata with a real publishable
+  package surface for Doe-backed headless compute and benchmarking.
+- Shifted the package from scaffold-only metadata to a documented package with
+  explicit published files and package-surface contracts.
+
+## [0.0.1] - 2026-03-01
+
+### Added
+
+- Initial package scaffold for the Doe WebGPU package surface under
+  `nursery/webgpu`.

package/README.md

@@ -1,138 +1,165 @@
 # @simulatte/webgpu
 
-Canonical WebGPU package for browserless benchmarking, CI workflows, and
-headless runtime integration.
+Headless WebGPU for Node.js and Bun, powered by Doe.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/clocksmith/fawn/main/nursery/webgpu/assets/fawn-icon-main-256.png" alt="Fawn logo" width="196" />
+  <img src="assets/fawn-icon-main-256.png" alt="Fawn logo" width="196" />
 </p>
 
-It is built on Doe, Fawn's Zig WebGPU runtime and Dawn-replacement path for
-Fawn/Chromium. Doe uses Zig for explicit low-overhead systems paths, explicit
-allocator control, and keeping hot runtime paths minimal across
-Vulkan/Metal/D3D12 backends. 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.
-
-In this package, Node uses an N-API addon and Bun uses Bun FFI to load
-`libwebgpu_doe`. Current package builds still ship a Dawn sidecar where proc
-resolution requires it.
-
-This directory is the package root for `@simulatte/webgpu`. It contains the
-Node provider source, the addon build contract, the Bun FFI entrypoint, and
-the CLI helpers used by benchmark and CI workflows.
-
-## Surface maturity
-
-- Node is the primary supported package surface (N-API bridge).
-- Bun has API parity with Node via direct FFI to `libwebgpu_doe` (57/57
-  contract tests passing). Bun benchmark cube maturity remains prototype
-  until Bun cells are populated by comparable benchmark artifacts.
-- Package-surface comparisons should be read through the benchmark cube outputs
-  under `bench/out/cube/`, not as a replacement for strict backend reports.
-
-The **benchmark cube** is a cross-product matrix of surface (backend_native,
-node_package, bun_package) × provider pair (e.g. doe_vs_dawn) × workload set
-(e.g. compute_e2e, render, upload). Each intersection is a **cell** with its
-own comparability and claimability status. Cube outputs live in
-`bench/out/cube/` and include a dashboard, matrix summary, and per-row data.
+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.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/clocksmith/fawn/main/nursery/webgpu/assets/package-surface-cube-snapshot.svg" alt="Static package-surface benchmark cube snapshot" width="920" />
-</p>
-
-Static snapshot above:
-
-- source: `bench/out/cube/latest/cube.summary.json`
-- renderer: `npm run build:readme-assets`
-- scope: package surfaces only; backend-native strict claim lanes remain separate
-
-## Quickstart
+## 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
+
+### Inspect the provider
+
 ```js
-import { providerInfo, requestDevice } from "@simulatte/webgpu";
+import { providerInfo } from "@simulatte/webgpu";
 
 console.log(providerInfo());
+```
+
+### Request a full device
+
+```js
+import { requestDevice } from "@simulatte/webgpu";
 
 const device = await requestDevice();
 console.log(device.limits.maxBufferSize);
 ```
 
-Turnkey package install is the target shape. Current host/runtime caveats are
-listed below.
+### Request a compute-only device
 
-## From source
+```js
+import { requestDevice } from "@simulatte/webgpu/compute";
 
-```bash
-# From the Fawn workspace root:
-cd zig && zig build dropin   # build libwebgpu_doe + Dawn sidecar
+const device = await requestDevice();
+console.log(typeof device.createComputePipeline); // "function"
+console.log(typeof device.createRenderPipeline);  // "undefined"
+```
+
+### Run a small compute job with `doe`
 
-cd nursery/webgpu
-npm run build:addon          # compile doe_napi.node from source
-npm run smoke                # verify native loading + GPU round-trip
+```js
+import { doe, requestDevice } from "@simulatte/webgpu/compute";
+
+const gpu = doe.bind(await requestDevice());
+
+const input = gpu.createBufferFromData(new Float32Array([1, 2, 3, 4]));
+
+const output = gpu.createBuffer({
+  size: input.size,
+  usage: "storage-readwrite",
+});
+
+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>;
+
+    @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 result = await gpu.readBuffer(output, Float32Array);
+console.log(Array.from(result)); // [2, 4, 6, 8]
 ```
 
-Use this when working from the Fawn checkout or when rebuilding the addon
-against the local Doe runtime.
+`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 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
+
+- `@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>
 
-## Packaging prebuilds (CI / release)
+## Verify your install
 
 ```bash
-npm run prebuild             # assembles prebuilds/<platform>-<arch>/
+npm run smoke
+npm test
+npm run test:bun
 ```
 
-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.
-Prebuild `metadata.json` now records `doeBuild.leanVerifiedBuild` and
-`proofArtifactSha256`, and `providerInfo()` surfaces the same values when
-metadata is present.
-
-## What lives here
-
-- `src/index.js`: default Node provider entrypoint
-- `src/node-runtime.js`: compatibility alias for the Node entrypoint
-- `src/bun-ffi.js`: Bun FFI provider (full API parity with Node)
-- `src/bun.js`: Bun re-export entrypoint
-- `src/runtime_cli.js`: Doe CLI/runtime helpers
-- `native/doe_napi.c`: N-API bridge for the in-process Node provider
-- `binding.gyp`: addon build contract
-- `bin/fawn-webgpu-bench.js`: command-stream bench wrapper
-- `bin/fawn-webgpu-compare.js`: Dawn-vs-Doe compare wrapper
-
-## 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.
-- Bun has API parity with Node (57/57 contract tests). Bun benchmark lane
-  is at `bench/bun/compare.js` and compares Doe FFI against the `bun-webgpu`
-  package. Latest validated local run observed 7/11 claimable rows, but this
-  remains prototype-quality package-surface evidence rather than a
-  publication-grade performance claim. Benchmark cube policy now isolates
-  directional `compute_dispatch_simple` into a dispatch-only cell so the Bun
-  compute-e2e cube cell reflects the claimable end-to-end rows.
-  `buffer_map_write_unmap` remains slower (~19µs polling overhead). Cube
-  maturity remains prototype until cell coverage stabilizes.
-- Self-contained install ships prebuilt `doe_napi.node` + `libwebgpu_doe` +
-  Dawn sidecar per platform. Clean-machine smoke test: `npm run smoke`.
-- 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,11 +2,45 @@
 
 Contract version: `v1`
 
-Scope: browserless benchmarking and CI orchestration for Doe runtime 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.
 
-## Node runtime API
+For the current `compute` vs `full` support split, see
+[`./support-contracts.md`](./support-contracts.md).
 
-Module: `@simulatte/webgpu` (Node default export target)
+This contract covers package-surface GPU access, provider metadata, and helper
+entrypoints. It does not promise DOM/canvas ownership or browser-process
+parity.
+
+## Export surfaces
+
+### `@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?)`
 
@@ -63,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:
@@ -85,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

@@ -36,46 +36,46 @@
   </defs>
   <rect width="1200" height="640" fill="url(#bg)"/>
   <text x="72" y="72" class="title">@simulatte/webgpu package snapshot</text>
-  <text x="72" y="102" class="subtitle">Derived from bench/out/cube/latest/cube.summary.json | latest populated cell 2026-03-06T21:55:26.482Z</text>
+  <text x="72" y="102" class="subtitle">Derived from bench/out/cube/latest/cube.summary.json | latest populated cell 2026-03-10T20:24:06.544Z</text>
   <text x="72" y="128" class="subtitle">Package-surface evidence only. Backend-native strict claim lanes remain separate.</text>
 
   <rect x="72" y="176" width="488" height="318" rx="24" class="panel toneLeft"/>
   <text x="100" y="216" class="cardTitle">Node package lane</text>
   <text x="100" y="244" class="cardMeta">Primary support | mac_apple_silicon</text>
-  <text x="100" y="266" class="cardMeta">latest populated cell 2026-03-06T21:40:32.181Z</text>
+  <text x="100" y="266" class="cardMeta">latest populated cell 2026-03-10T20:24:06.544Z</text>
 
   <rect x="90" y="300" width="452" height="82" rx="16" class="metric toneLeft"/>
   <text x="114" y="331" class="metricTitle">Uploads</text>
   <rect x="386" y="315" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
   <text x="452" y="334" text-anchor="middle" class="pillText">CLAIMABLE</text>
   <text x="114" y="357" class="metricBody">5 rows | claimable</text>
-  <text x="114" y="377" class="metricBody">median p50 delta +53.9%</text>
+  <text x="114" y="377" class="metricBody">median p50 delta +37.2%</text>
 
   <rect x="90" y="396" width="452" height="82" rx="16" class="metric toneLeft"/>
   <text x="114" y="427" class="metricTitle">Compute E2E</text>
-  <rect x="386" y="411" width="132" height="28" rx="14" fill="#d97706" stroke="#fbbf24" stroke-width="1.5"/>
-  <text x="452" y="430" text-anchor="middle" class="pillText">COMPARABLE</text>
-  <text x="114" y="453" class="metricBody">3 rows | comparable</text>
-  <text x="114" y="473" class="metricBody">median p50 delta +21.2%</text>
+  <rect x="386" y="411" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
+  <text x="452" y="430" text-anchor="middle" class="pillText">CLAIMABLE</text>
+  <text x="114" y="453" class="metricBody">3 rows | claimable</text>
+  <text x="114" y="473" class="metricBody">median p50 delta +48.1%</text>
 
   <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

@@ -0,0 +1,46 @@
+# Compatibility Scope: what we actually need
+
+This note narrows compatibility work to concrete headless integration value for
+the current package surface.
+
+## Required now
+
+1. Stable headless Node/Bun provider behavior for real Doe-native execution.
+2. Stable command/trace orchestration for benchmark and CI pipelines.
+3. Reliable wrappers for:
+- Doe native bench runs
+- Dawn-vs-Doe compare runs
+4. Deterministic artifact paths and non-zero exit-code propagation.
+5. Minimal convenience entrypoints for Node consumers:
+- `create(args?)`
+- `globals`
+- `requestAdapter`/`requestDevice` convenience helpers
+- `setupGlobals` for `navigator.gpu` + enum bootstrap
+
+The point of this package is headless GPU work in Node/Bun: compute, offscreen
+execution, benchmarking, and CI. Compatibility work should serve those
+surfaces first.
+
+## Optional later (only when demanded by integrations)
+
+1. Minimal constants compatibility:
+- only constants required by real integrations, not full WebGPU enum surface.
+2. Provider-module swap support for non-default backends beyond `webgpu`.
+
+## Not planned by default
+
+1. Full `navigator.gpu` browser-parity behavior in Node.
+2. Full object lifetime/event parity (`device lost`, full error scopes, full mapping semantics).
+3. Broad drop-in support for arbitrary npm packages expecting complete `webgpu` behavior.
+
+Decision rule:
+
+- Add parity features only after a concrete headless integration is blocked by
+  a missing capability and cannot be addressed by the existing package,
+  bridge, or CLI contract.
+
+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)

package/headless-webgpu-comparison.md

@@ -7,7 +7,7 @@ This document outlines qualitative differences and target use-cases for headless
 | **Underlying Engine** | `libwebgpu_doe` (Zig + Lean pipeline) | Google Dawn (C++) | Google Dawn (C++) |
 | **Primary Focus** | Deterministic Compute, ML/AI, Verifiability | Browser Parity, Graphics | Browser Parity, Graphics |
 | **Binary Footprint** | Smaller targeted runtime expected | Varies by build/distribution | Varies by build/distribution |
-| **JS Binding Layer** | Node-API (N-API) / Bun FFI | Node-API (N-API) | Bun FFI (Fast Foreign Function) |
+| **JS Binding Layer** | Node-API (N-API); experimental Bun FFI implementation also exists | Node-API (N-API) | Bun FFI (Fast Foreign Function) |
 | **Security Model** | Explicit schema/gate discipline in Fawn pipeline | Runtime heuristics + Dawn validation | Runtime heuristics + Dawn validation |
 | **Resource Allocation** | Arena-backed, predictable memory | General WebGPU async allocations | General WebGPU async allocations |
 | **WebGPU Spec Compliance**| Compute-prioritized subset target | Broad Chromium-aligned coverage | Broad Chromium-aligned coverage |
@@ -17,7 +17,7 @@ This document outlines qualitative differences and target use-cases for headless
 ## Architectural Takeaways for Fawn
 
 1. Determinism and fail-fast contracts are the intended Doe value proposition for benchmarking workflows.
-2. Bun FFI can reduce wrapper overhead versus heavier bridge layers, but end-to-end results must be measured per workload.
+2. The package currently defaults Bun to the addon-backed runtime for correctness parity. The separate Bun FFI path may reduce wrapper overhead later, but end-to-end results must be measured per workload.
 3. Distribution size and startup claims must be backed by measured artifacts before release claims.
 
 ## Ecosystem reference: official/community competitors and stats
@@ -38,6 +38,6 @@ Notes:
 
 ## Scaffolding the Fawn NPM Package
 
-- Doe is exposed through a native C ABI and can be bridged from JS via Bun FFI now.
+- Doe is exposed through a native C ABI and also ships an experimental Bun FFI implementation, but the package-default Bun entry currently uses the addon-backed runtime for stability.
 - Node N-API support now exists in the canonical `@simulatte/webgpu` package.
 - Browser API parity is not claimed by this draft package; the current focus is headless benchmarking workflows.