@simulatte/webgpu 0.2.3 → 0.2.4

package/src/doe.js

@@ -0,0 +1,275 @@
+const DOE_GPU_BUFFER_USAGE = {
+  MAP_READ: 0x0001,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+};
+
+const DOE_GPU_SHADER_STAGE = {
+  COMPUTE: 0x4,
+};
+
+const DOE_GPU_MAP_MODE = {
+  READ: 0x0001,
+};
+
+const DOE_BUFFER_META = new WeakMap();
+
+function resolve_buffer_usage_token(token) {
+  switch (token) {
+    case 'upload':
+      return DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'readback':
+      return DOE_GPU_BUFFER_USAGE.COPY_SRC | DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.MAP_READ;
+    case 'uniform':
+      return DOE_GPU_BUFFER_USAGE.UNIFORM | DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'storage-read':
+      return DOE_GPU_BUFFER_USAGE.STORAGE | DOE_GPU_BUFFER_USAGE.COPY_DST;
+    case 'storage-readwrite':
+      return DOE_GPU_BUFFER_USAGE.STORAGE | DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.COPY_SRC;
+    default:
+      throw new Error(`Unknown Doe buffer usage token: ${token}`);
+  }
+}
+
+function resolve_buffer_usage(usage) {
+  if (typeof usage === 'number') return usage;
+  if (typeof usage === 'string') return resolve_buffer_usage_token(usage);
+  if (Array.isArray(usage)) {
+    return usage.reduce((mask, token) => mask | resolve_buffer_usage_token(token), 0);
+  }
+  throw new Error('Doe buffer usage must be a number, string, or string array.');
+}
+
+function infer_binding_access_token(token) {
+  switch (token) {
+    case 'uniform':
+      return 'uniform';
+    case 'storage-read':
+      return 'storage-read';
+    case 'storage-readwrite':
+      return 'storage-readwrite';
+    default:
+      return null;
+  }
+}
+
+function infer_binding_access(usage) {
+  if (typeof usage === 'number' || usage == null) return null;
+  const tokens = typeof usage === 'string'
+    ? [usage]
+    : Array.isArray(usage)
+      ? usage
+      : null;
+  if (!tokens) {
+    throw new Error('Doe buffer usage must be a number, string, or string array.');
+  }
+  const inferred = [...new Set(tokens.map(infer_binding_access_token).filter(Boolean))];
+  if (inferred.length > 1) {
+    throw new Error(`Doe buffer usage cannot imply multiple binding access modes: ${inferred.join(', ')}`);
+  }
+  return inferred[0] ?? null;
+}
+
+function remember_buffer_usage(buffer, usage) {
+  DOE_BUFFER_META.set(buffer, {
+    binding_access: infer_binding_access(usage),
+  });
+  return buffer;
+}
+
+function inferred_binding_access_for_buffer(buffer) {
+  return DOE_BUFFER_META.get(buffer)?.binding_access ?? null;
+}
+
+function normalize_workgroups(workgroups) {
+  if (typeof workgroups === 'number') {
+    return [workgroups, 1, 1];
+  }
+  if (Array.isArray(workgroups) && workgroups.length === 3) {
+    return workgroups;
+  }
+  throw new Error('Doe workgroups must be a number or a [x, y, z] tuple.');
+}
+
+function normalize_data_view(data) {
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  throw new Error('Doe buffer data must be an ArrayBuffer or ArrayBufferView.');
+}
+
+function normalize_binding(binding, index) {
+  const entry = binding && typeof binding === 'object' && 'buffer' in binding
+    ? binding
+    : { buffer: binding };
+  const access = entry.access ?? inferred_binding_access_for_buffer(entry.buffer);
+  if (!access) {
+    throw new Error(
+      'Doe binding access is required for buffers without Doe helper usage metadata. ' +
+      'Pass { buffer, access } or create the buffer through doe.createBuffer* with a bindable usage token.'
+    );
+  }
+  return {
+    binding: index,
+    buffer: entry.buffer,
+    access,
+  };
+}
+
+function bind_group_layout_entry(binding) {
+  const buffer_type = binding.access === 'uniform'
+    ? 'uniform'
+    : binding.access === 'storage-read'
+      ? 'read-only-storage'
+      : 'storage';
+  return {
+    binding: binding.binding,
+    visibility: DOE_GPU_SHADER_STAGE.COMPUTE,
+    buffer: { type: buffer_type },
+  };
+}
+
+function bind_group_entry(binding) {
+  return {
+    binding: binding.binding,
+    resource: { buffer: binding.buffer },
+  };
+}
+
+class DoeKernel {
+  constructor(device, pipeline, layout, entry_point) {
+    this.device = device;
+    this.pipeline = pipeline;
+    this.layout = layout;
+    this.entryPoint = entry_point;
+  }
+
+  async dispatch(options) {
+    const bindings = (options.bindings ?? []).map(normalize_binding);
+    const workgroups = normalize_workgroups(options.workgroups);
+    const bind_group = this.device.createBindGroup({
+      label: options.label ?? undefined,
+      layout: this.layout,
+      entries: bindings.map(bind_group_entry),
+    });
+    const encoder = this.device.createCommandEncoder({ label: options.label ?? undefined });
+    const pass = encoder.beginComputePass({ label: options.label ?? undefined });
+    pass.setPipeline(this.pipeline);
+    if (bindings.length > 0) {
+      pass.setBindGroup(0, bind_group);
+    }
+    pass.dispatchWorkgroups(workgroups[0], workgroups[1], workgroups[2]);
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+    if (typeof this.device.queue.onSubmittedWorkDone === 'function') {
+      await this.device.queue.onSubmittedWorkDone();
+    }
+  }
+}
+
+function create_bound_doe(device) {
+  return {
+    device,
+    createBuffer(options) {
+      return doe.createBuffer(device, options);
+    },
+    createBufferFromData(data, options = {}) {
+      return doe.createBufferFromData(device, data, options);
+    },
+    readBuffer(buffer, type, options = {}) {
+      return doe.readBuffer(device, buffer, type, options);
+    },
+    runCompute(options) {
+      return doe.runCompute(device, options);
+    },
+    compileCompute(options) {
+      return doe.compileCompute(device, options);
+    },
+  };
+}
+
+function compile_compute(device, options) {
+  const bindings = (options.bindings ?? []).map(normalize_binding);
+  const shader = device.createShaderModule({ code: options.code });
+  const bind_group_layout = device.createBindGroupLayout({
+    entries: bindings.map(bind_group_layout_entry),
+  });
+  const pipeline_layout = device.createPipelineLayout({
+    bindGroupLayouts: [bind_group_layout],
+  });
+  const pipeline = device.createComputePipeline({
+    layout: pipeline_layout,
+    compute: {
+      module: shader,
+      entryPoint: options.entryPoint ?? 'main',
+    },
+  });
+  return new DoeKernel(device, pipeline, bind_group_layout, options.entryPoint ?? 'main');
+}
+
+export const doe = {
+  bind(device) {
+    return create_bound_doe(device);
+  },
+
+  createBuffer(device, options) {
+    return remember_buffer_usage(device.createBuffer({
+      label: options.label ?? undefined,
+      size: options.size,
+      usage: resolve_buffer_usage(options.usage),
+      mappedAtCreation: options.mappedAtCreation ?? false,
+    }), options.usage);
+  },
+
+  createBufferFromData(device, data, options = {}) {
+    const view = normalize_data_view(data);
+    const usage = options.usage ?? 'storage-read';
+    const buffer = remember_buffer_usage(device.createBuffer({
+      label: options.label ?? undefined,
+      size: view.byteLength,
+      usage: resolve_buffer_usage(usage),
+    }), usage);
+    device.queue.writeBuffer(buffer, 0, view);
+    return buffer;
+  },
+
+  async readBuffer(device, buffer, type, options = {}) {
+    const offset = options.offset ?? 0;
+    const size = options.size ?? Math.max(0, (buffer.size ?? 0) - offset);
+    const staging = device.createBuffer({
+      label: options.label ?? undefined,
+      size,
+      usage: DOE_GPU_BUFFER_USAGE.COPY_DST | DOE_GPU_BUFFER_USAGE.MAP_READ,
+    });
+    const encoder = device.createCommandEncoder({ label: options.label ?? undefined });
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+    device.queue.submit([encoder.finish()]);
+    await staging.mapAsync(DOE_GPU_MAP_MODE.READ);
+    const copy = staging.getMappedRange().slice(0);
+    staging.unmap();
+    if (typeof staging.destroy === 'function') {
+      staging.destroy();
+    }
+    return new type(copy);
+  },
+
+  async runCompute(device, options) {
+    const kernel = compile_compute(device, options);
+    await kernel.dispatch({
+      bindings: options.bindings ?? [],
+      workgroups: options.workgroups,
+      label: options.label,
+    });
+  },
+
+  compileCompute(device, options) {
+    return compile_compute(device, options);
+  },
+};
+
+export default doe;

package/src/full.d.ts

@@ -0,0 +1,112 @@
+import type {
+  BoundDoeNamespace,
+  DoeKernelDispatchOptions,
+  DoeNamespace,
+  DoeRunComputeOptions,
+} from "./doe.js";
+
+export interface ProviderInfo {
+  module: string;
+  loaded: boolean;
+  loadError: string;
+  defaultCreateArgs: string[];
+  doeNative: boolean;
+  libraryFlavor: string;
+  doeLibraryPath: string;
+  buildMetadataSource: string;
+  buildMetadataPath: string;
+  leanVerifiedBuild: boolean | null;
+  proofArtifactSha256: string | null;
+}
+
+export interface DoeRuntimeRunResult {
+  ok: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  signal: string | null;
+  command: string[];
+}
+
+export interface DoeRuntimeBenchResult extends DoeRuntimeRunResult {
+  traceJsonlPath: string | null;
+  traceMetaPath: string | null;
+  traceMeta: Record<string, unknown> | null;
+}
+
+export interface DoeRuntimeBenchOptions {
+  commandsPath: string;
+  quirksPath?: string;
+  vendor?: string;
+  api?: string;
+  family?: string;
+  driver?: string;
+  traceJsonlPath?: string;
+  traceMetaPath?: string;
+  uploadBufferUsage?: string;
+  uploadSubmitEvery?: number;
+  queueWaitMode?: string;
+  queueSyncMode?: string;
+  extraArgs?: string[];
+  cwd?: string;
+}
+
+export interface DoeRuntime {
+  binPath: string;
+  libPath: string | null;
+  runRaw(args: string[], spawnOptions?: Record<string, unknown>): DoeRuntimeRunResult;
+  runBench(options: DoeRuntimeBenchOptions): DoeRuntimeBenchResult;
+}
+
+export interface RequestDeviceOptions {
+  adapterOptions?: GPURequestAdapterOptions;
+  deviceDescriptor?: GPUDeviceDescriptor;
+  createArgs?: string[] | null;
+}
+
+export interface FullDoeRunComputeOptions extends DoeRunComputeOptions<GPUBuffer> {}
+
+export interface FullDoeKernelDispatchOptions extends DoeKernelDispatchOptions<GPUBuffer> {}
+
+export interface FullDoeKernel {
+  readonly device: GPUDevice;
+  readonly entryPoint: string;
+  dispatch(options: FullDoeKernelDispatchOptions): Promise<void>;
+}
+
+export interface FullBoundDoeNamespace
+  extends BoundDoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullDoeRunComputeOptions> {}
+
+export interface FullDoeNamespace
+  extends DoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullBoundDoeNamespace, FullDoeRunComputeOptions> {}
+
+export const globals: Record<string, unknown>;
+export function create(createArgs?: string[] | null): GPU;
+export function setupGlobals(target?: object, createArgs?: string[] | null): GPU;
+export function requestAdapter(
+  adapterOptions?: GPURequestAdapterOptions,
+  createArgs?: string[] | null
+): Promise<GPUAdapter | null>;
+export function requestDevice(options?: RequestDeviceOptions): Promise<GPUDevice>;
+export function providerInfo(): ProviderInfo;
+export function createDoeRuntime(options?: {
+  binPath?: string;
+  libPath?: string;
+}): DoeRuntime;
+export function runDawnVsDoeCompare(options: Record<string, unknown>): DoeRuntimeRunResult;
+
+export const doe: FullDoeNamespace;
+
+declare const _default: {
+  create: typeof create;
+  globals: typeof globals;
+  setupGlobals: typeof setupGlobals;
+  requestAdapter: typeof requestAdapter;
+  requestDevice: typeof requestDevice;
+  providerInfo: typeof providerInfo;
+  createDoeRuntime: typeof createDoeRuntime;
+  runDawnVsDoeCompare: typeof runDawnVsDoeCompare;
+  doe: FullDoeNamespace;
+};
+
+export default _default;

package/src/full.js

@@ -0,0 +1,10 @@
+import full from './index.js';
+import { doe } from './doe.js';
+
+export * from './index.js';
+export { doe };
+
+export default {
+  ...full,
+  doe,
+};

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