@simulatte/webgpu 0.2.3 → 0.3.0

package/src/node-runtime.js

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export { default } from "./index.js";
+export * from "./full.js";
+export { default } from "./full.js";

package/src/node.js

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export { default } from "./index.js";
+export * from "./full.js";
+export { default } from "./full.js";

package/{SUPPORT_CONTRACTS.md → support-contracts.md}

@@ -12,8 +12,8 @@ Scope:
 
 This document defines three explicit layers:
 
-1. `core`
-   - compute-first headless WebGPU
+1. `compute` (`core` runtime boundary)
+   - compute-first headless WebGPU for AI workloads and other buffer/dispatch-heavy tasks
    - minimal releaseable package/runtime surface
    - explicit unsupported for sampled/render/browser gaps
 2. `full`
@@ -30,7 +30,7 @@ depends on the full runtime artifact plus browser-specific gates; it must not
 depend on npm packaging shape.
 
 Boundary-enforcement and refactor-order details are defined in
-`LAYERING_PLAN.md`.
+[`./layering-plan.md`](./layering-plan.md).
 
 ## Dependency contract
 
@@ -62,7 +62,7 @@ Implementation intent:
 
 Three surfaces are implied by this split:
 
-1. `core`
+1. `compute`
    - headless compute-first package/runtime
 2. `full`
    - headless full WebGPU package/runtime
@@ -100,11 +100,11 @@ Browser-owned semantics remain outside both `core` and `full`.
 | Fallback policy / denylist / kill switch | `out_of_scope` | `out_of_scope` | `required` |
 | Chromium process behavior | `out_of_scope` | `out_of_scope` | `required` |
 
-## Core support contract
+## Compute support contract (`core` runtime, `@simulatte/webgpu/compute` export)
 
 ### Target user
 
-- ML inference
+- AI workloads
 - simulation
 - data processing
 - CI and benchmark orchestration
@@ -112,59 +112,44 @@ Browser-owned semantics remain outside both `core` and `full`.
 
 ### Promise
 
-`core` promises a stable compute-first headless WebGPU surface with explicit
+`compute` promises a stable compute-first headless WebGPU surface sized for AI
+workloads and other buffer/dispatch-heavy headless execution, with explicit
 unsupported behavior for sampled-texture, render, and browser-owned semantics.
 
 ### Included object model
 
-`core` includes:
+`compute` includes:
 
 - `GPU`, `GPUAdapter`, `GPUDevice`, `GPUQueue`
 - `GPUBuffer`
 - `GPUShaderModule` for compute WGSL
 - `GPUBindGroupLayout`, `GPUBindGroup`, `GPUPipelineLayout`
 - `GPUComputePipeline`
+- `createComputePipelineAsync`
 - `GPUCommandEncoder` for copy, upload, clear, barrier, and compute encoding
 - `GPUComputePassEncoder`
 - `dispatchWorkgroups`
 - `dispatchWorkgroupsIndirect`
-
-### Texture contract
-
-`core` gets samplerless compute textures only.
-
-Included usage classes:
-
-- `COPY_SRC`
-- `COPY_DST`
-- `TEXTURE_BINDING`
-- `STORAGE_BINDING`
-
-Excluded from `core`:
-
-- `GPUSampler`
-- sampled-texture semantics
-- render-attachment semantics
-- browser presentation semantics
-
-Best rule:
-
-- `core` gets samplerless compute textures only
-- `full` gets sampled textures and render semantics
+- queue `writeBuffer`
+- buffer readback via `MAP_READ` + `copyBufferToBuffer`
+- Node/Bun bootstrap globals required for headless execution:
+  - `navigator.gpu`
+  - `GPUBufferUsage`
+  - `GPUShaderStage`
+  - `GPUMapMode`
+  - `GPUTextureUsage`
 
 ### WGSL contract
 
-WGSL required in `core`:
+WGSL required in `compute`:
 
 - storage buffers
 - uniform buffers
 - workgroup buffers
 - atomics
 - barriers
-- `textureLoad`
-- `textureStore`
 
-WGSL out of scope for `core`:
+WGSL out of scope for `compute`:
 
 - sampler declarations and binding semantics
 - `textureSample*`
@@ -174,9 +159,10 @@ WGSL out of scope for `core`:
 
 ### Explicit exclusions
 
-`core` does not own:
+`compute` does not own:
 
 - `GPUSampler`
+- sampled textures
 - `GPURenderPipeline`
 - `GPURenderPassEncoder`
 - `GPURenderBundleEncoder`
@@ -191,7 +177,7 @@ WGSL out of scope for `core`:
 
 ### Release gates for `core`
 
-`core` acceptance requires:
+`compute` acceptance requires:
 
 1. schema, correctness, and trace gates green
 2. package contract tests green for Node and declared Bun surface
@@ -199,9 +185,9 @@ WGSL out of scope for `core`:
    - adapter/device acquisition
    - buffers
    - copy/upload
+   - readback
    - compute pipeline
    - compute dispatch
-   - compute-visible texture load/store paths
 4. benchmark cube evidence limited to:
    - upload
    - compute e2e
@@ -209,7 +195,7 @@ WGSL out of scope for `core`:
 5. explicit unsupported taxonomy for any sampler, sampled-texture, render,
    surface, or browser API request outside the `core` contract
 
-### Non-goals for `core`
+### Non-goals for `compute`
 
 1. full WebGPU JS object-model parity
 2. sampled-texture semantics
@@ -229,8 +215,8 @@ WGSL out of scope for `core`:
 ### Promise
 
 `full` promises a full headless WebGPU surface. It is a strict superset of
-`core`, but it still does not claim browser-process ownership, DOM integration,
-or Chromium wire/drop-in readiness by itself.
+`compute`, but it still does not claim browser-process ownership, DOM
+integration, or Chromium wire/drop-in readiness by itself.
 
 ### Added object model
 

package/{ZIG_SOURCE_INVENTORY.md → zig-source-inventory.md}

@@ -22,8 +22,8 @@ This document maps the current `zig/src` tree into four buckets:
 
 Use this with:
 
-- `SUPPORT_CONTRACTS.md`
-- `LAYERING_PLAN.md`
+- `support-contracts.md`
+- `layering-plan.md`
 
 ## Reading rule
 

package/API_CONTRACT.md

@@ -1,182 +0,0 @@
-# @simulatte/webgpu API Contract
-
-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.
-
-This is the current single-surface package contract.
-For the proposed future layered `core` vs `full` support split, see
-`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
-
-Module: `@simulatte/webgpu` (Node default export target)
-
-### `create(createArgs?)`
-
-Input:
-
-- `createArgs?: string[]` (currently ignored by the default Doe-native provider)
-
-Behavior:
-
-- loads the Doe-native N-API addon and `libwebgpu_doe`
-- returns a GPU object backed by the in-tree Doe provider
-
-Output:
-
-- `GPU` object with `requestAdapter(...)`
-
-### `globals`
-
-Output:
-
-- provider globals object suitable for `Object.assign(globalThis, globals)`
-
-### `setupGlobals(target?, createArgs?)`
-
-Input:
-
-- `target?: object` (default: `globalThis`)
-- `createArgs?: string[]`
-
-Behavior:
-
-- installs provider globals if missing
-- installs `navigator.gpu` if missing
-
-Output:
-
-- `GPU` object
-
-### `requestAdapter(adapterOptions?, createArgs?)`
-
-Output:
-
-- `Promise<GPUAdapter | null>`
-
-### `requestDevice(options?)`
-
-Input:
-
-- `options.adapterOptions?: object`
-- `options.deviceDescriptor?: object`
-- `options.createArgs?: string[]`
-
-Output:
-
-- `Promise<GPUDevice>`
-
-### `providerInfo()`
-
-Output object:
-
-- `module: string`
-- `loaded: boolean`
-- `loadError: string`
-- `defaultCreateArgs: string[]`
-- `doeNative: boolean`
-- `libraryFlavor: string`
-- `doeLibraryPath: string`
-- `buildMetadataSource: string`
-- `buildMetadataPath: string`
-- `leanVerifiedBuild: boolean | null`
-- `proofArtifactSha256: string | null`
-
-Behavior:
-
-- reports package-surface library provenance when prebuild metadata or Zig build
-  metadata is available
-- does not guess: if metadata is unavailable, `leanVerifiedBuild` is `null`
-
-### `createDoeRuntime(options?)`
-
-Input:
-
-- `options.binPath?: string`
-- `options.libPath?: string`
-
-Output object:
-
-- `binPath: string`
-- `libPath: string | null`
-- `runRaw(args: string[], spawnOptions?): RunResult`
-- `runBench(options: BenchOptions): BenchResult`
-
-`BenchOptions`:
-
-- `commandsPath: string` (required)
-- `quirksPath?: string`
-- `vendor?: string`
-- `api?: string`
-- `family?: string`
-- `driver?: string`
-- `traceJsonlPath?: string`
-- `traceMetaPath?: string`
-- `uploadBufferUsage?: string`
-- `uploadSubmitEvery?: number`
-- `queueWaitMode?: string`
-- `queueSyncMode?: string`
-- `extraArgs?: string[]`
-
-`RunResult`:
-
-- `ok: boolean`
-- `exitCode: number`
-- `stdout: string`
-- `stderr: string`
-- `signal: string | null`
-- `command: string[]`
-
-`BenchResult` extends `RunResult` with:
-
-- `traceJsonlPath: string | null`
-- `traceMetaPath: string | null`
-- `traceMeta: object | null`
-
-### `runDawnVsDoeCompare(options)`
-
-Input:
-
-- `repoRoot?: string`
-- `compareScriptPath?: string`
-- `pythonBin?: string`
-- `configPath?: string`
-- `outPath?: string`
-- `extraArgs?: string[]`
-- `env?: Record<string, string>`
-
-Behavior:
-
-- wraps `bench/compare_dawn_vs_doe.py`
-- requires either `configPath` or `--config` in `extraArgs`
-
-Output:
-
-- `RunResult`
-
-## CLI contract
-
-### `fawn-webgpu-bench`
-
-Purpose:
-
-- execute Doe command-stream benchmark runs and emit trace artifacts.
-
-### `fawn-webgpu-compare`
-
-Purpose:
-
-- one-command Dawn-vs-Doe compare wrapper from Node tooling.
-
-## Non-goals in v1
-
-1. Full browser-parity WebGPU JS object model emulation.
-2. Browser presentation parity.
-3. npm `webgpu` drop-in compatibility guarantee.