@simulatte/webgpu 0.3.1 → 0.3.2

package/doe-api-design.md

@@ -0,0 +1,237 @@
+# Doe API design
+
+Status: `active`
+
+Scope:
+
+- Doe helper naming and layering above direct WebGPU
+- public JSDoc structure for package-surface helper APIs
+- future expansion direction for routine families beyond the current helper surface
+
+Use this together with:
+
+- [api-contract.md](./api-contract.md) for current implemented method signatures
+- [architecture.md](./architecture.md) for the full runtime layer stack
+- [jsdoc-style-guide.md](./jsdoc-style-guide.md) for public API documentation rules
+
+## Why this exists
+
+This document captures the naming cleanup that moved the Doe helper surface to
+a more coherent hierarchy:
+
+- `gpu.buffer.*` for resource helpers
+- `gpu.kernel.*` for explicit compute primitives
+- `gpu.compute.*` for higher-level routines
+
+The remaining job is to keep future additions aligned with that model instead
+of drifting back into mixed abstraction buckets.
+
+The design goal is:
+
+1. keep direct WebGPU separate
+2. give Doe one explicit primitive layer
+3. give Doe one routine layer
+4. avoid domain namespaces until they are clearly justified
+
+## Design principles
+
+### 1. Bind once, then stay on the bound object
+
+`doe` itself should only do two things:
+
+- `await doe.requestDevice()`
+- `doe.bind(device)`
+
+All helper methods should live on the returned `gpu` object.
+
+This keeps the public model simple:
+
+- `doe` binds
+- `gpu` does work
+
+### 2. Namespace by unit of thought, not by implementation accident
+
+Namespaces should represent stable user concepts:
+
+- `buffer`
+  resource ownership and readback
+- `kernel`
+  explicit compiled/dispatchable compute units
+- `compute`
+  higher-level workflows that allocate, dispatch, and read back for the caller
+
+Avoid namespaces that only reflect where code currently happens to live.
+
+### 3. Do not mix primitives and routines in one namespace
+
+The main current naming problem is that `compute` does two jobs:
+
+- explicit kernel operations
+- opinionated one-shot workflows
+
+Those should be separate.
+
+### 4. Delay domain packs until the domain is real
+
+Names like `linalg` or `math` should not exist just because one operation such
+as matmul exists.
+
+Introduce a domain namespace only when it has a real family of routines with a
+shared mental model and clear boundaries.
+
+Until then, keep those workflows under `gpu.compute.*`.
+
+## Current implemented surface
+
+For exact method signatures and behavior, see
+[`api-contract.md`](./api-contract.md) (section `doe`).
+
+The three namespaces are:
+
+- `gpu.buffer.*` — resource helpers (create, read)
+- `gpu.kernel.*` — explicit compute primitives (create, run, dispatch)
+- `gpu.compute(...)` — one-shot workflow helper
+
+## Proposed routine family (not yet implemented)
+
+- `gpu.compute.map(options) -> Promise<TypedArray>`
+- `gpu.compute.zip(options) -> Promise<TypedArray>`
+- `gpu.compute.reduce(options) -> Promise<number | TypedArray>`
+- `gpu.compute.scan(options) -> Promise<TypedArray>`
+- `gpu.compute.matmul(options) -> Promise<TypedArray>`
+
+Domain namespaces like `gpu.linalg` or `gpu.math` should not exist until the
+domain has a real family of routines. Keep workflow routines under
+`gpu.compute.*` until then.
+
+## Naming rules
+
+### 1. Prefer singular namespaces for domains
+
+Use:
+
+- `gpu.buffer.*`
+- `gpu.kernel.*`
+
+Do not use plural buckets like `gpu.buffers.*` unless the package already has a
+hard compatibility constraint.
+
+### 2. Keep verbs concrete
+
+Use:
+
+- `create`
+- `read`
+- `run`
+- `dispatch`
+- `map`
+- `zip`
+- `reduce`
+
+Avoid generic names like:
+
+- `execute`
+- `process`
+- `handle`
+- `apply`
+
+unless the contract is genuinely broader than the specific verbs above.
+
+### 3. Keep one namespace, one abstraction level
+
+Examples:
+
+- `gpu.buffer.*`
+  resource helpers
+- `gpu.kernel.*`
+  explicit compute primitives
+- `gpu.compute.*`
+  routines
+
+Do not mix:
+
+- reusable kernel compilation
+- buffer lifecycle
+- high-level task workflows
+
+inside one namespace.
+
+## Migration history (completed)
+
+The following renames were applied to reach the current implemented surface:
+
+- `gpu.buffers.create(...)` → `gpu.buffer.create(...)`
+- `gpu.buffers.fromData(...)` → merged into `gpu.buffer.create({ data: ... })`
+- `gpu.buffers.like(...)` → removed (use `gpu.buffer.create({ size: src.size, ... })`)
+- `gpu.buffers.read(...)` → `gpu.buffer.read({ buffer, type, ... })`
+- `gpu.compute.run(...)` → `gpu.kernel.run(...)`
+- `gpu.compute.compile(...)` → `gpu.kernel.create(...)`
+- `kernel.dispatch(...)` → stayed `kernel.dispatch(...)`
+- `gpu.compute(...)` → stayed `gpu.compute(...)`
+
+## JSDoc contract for the future helper surface
+
+Public JSDoc should document the API the user actually sees, not the private
+helper graph underneath it.
+
+For the Doe helper surface, the preferred structure is:
+
+```js
+/**
+ * Create a reusable compute kernel from WGSL and binding metadata.
+ *
+ * Surface: Doe API (`gpu.kernel.*`).
+ * Input: WGSL source, entry point, and representative bindings.
+ * Returns: A reusable kernel object with `.dispatch(...)`.
+ *
+ * This example shows the API in its basic form.
+ *
+ * ```js
+ * const kernel = gpu.kernel.create({
+ *   code,
+ *   bindings: [src, dst],
+ * });
+ * ```
+ *
+ * - Reuse this when dispatching the same WGSL shape repeatedly.
+ * - Drop to direct WebGPU if you need manual pipeline-layout ownership.
+ */
+```
+
+Required fields for future Doe helper docs:
+
+1. one-sentence summary
+2. `Surface:` line
+3. `Input:` line
+4. `Returns:` line
+5. one small example
+6. flat bullets for defaults, failure modes, and escalation path
+
+This is stricter than the current narrative style on purpose. The Doe helper
+surface benefits from explicit API contracts more than from prose-heavy
+commentary.
+
+## Decision rule for future additions
+
+When adding a new helper:
+
+1. If it is about resource ownership, put it under `gpu.buffer.*`.
+2. If it is about explicit WGSL/pipeline reuse and dispatch, put it under
+   `gpu.kernel.*`.
+3. If it is a workflow that owns temporary allocations and returns typed
+   results, put it under `gpu.compute.*`.
+4. If it requires model semantics, tensor semantics, KV cache handling,
+   attention, routing, or pipeline planning, it does not belong in Doe at all;
+   it belongs in a higher-level consumer such as Doppler.
+
+## Non-goals
+
+This design does not propose:
+
+- moving model runtime or pipeline semantics into Doe
+- replacing direct WebGPU
+- creating a broad domain-pack taxonomy today
+- documenting the proposed naming as if it were already the implemented package contract
+
+The live contract remains in [api-contract.md](./api-contract.md) until the
+implementation catches up.

package/examples/doe-api/README.md

@@ -0,0 +1,19 @@
+# Doe API examples
+
+These examples are ordered from the most explicit Doe helper path to the most
+opinionated one-shot helper.
+
+- `buffers-readback.js`
+  create a Doe-managed buffer and read it back
+- `kernel-run.js`
+  run a one-off compute kernel with explicit buffer ownership
+- `kernel-create-and-dispatch.js`
+  compile a reusable `DoeKernel` and dispatch it
+- `compute-one-shot.js`
+  use `gpu.compute(...)` with one typed-array input and inferred output size
+- `compute-one-shot-like-input.js`
+  use `gpu.compute(...)` with `likeInput` sizing and a uniform input
+- `compute-one-shot-multiple-inputs.js`
+  use `gpu.compute(...)` with multiple typed-array inputs
+- `compute-one-shot-matmul.js`
+  run a larger one-shot `gpu.compute(...)` example with explicit tensor shapes

package/examples/doe-api/buffers-readback.js

@@ -1,9 +1,10 @@
 import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
-const src = gpu.buffers.fromData(new Float32Array([1, 2, 3, 4]), {
+const src = gpu.buffer.create({
+  data: new Float32Array([1, 2, 3, 4]),
   usage: ["storageRead", "readback"],
 });
 
-const result = await gpu.buffers.read(src, Float32Array);
+const result = await gpu.buffer.read({ buffer: src, type: Float32Array });
 console.log(JSON.stringify(Array.from(result)));

package/examples/{doe-routines/compute-once-like-input.js → doe-api/compute-one-shot-like-input.js}

@@ -2,7 +2,7 @@ import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
 
-const result = await gpu.compute.once({
+const result = await gpu.compute({
   code: `
     struct Scale {
       value: f32,

package/examples/{doe-routines/compute-once-matmul.js → doe-api/compute-one-shot-matmul.js}

@@ -9,7 +9,7 @@ const lhs = Float32Array.from({ length: M * K }, (_, i) => (i % 17) / 17);
 const rhs = Float32Array.from({ length: K * N }, (_, i) => (i % 13) / 13);
 const dims = new Uint32Array([M, K, N, 0]);
 
-const result = await gpu.compute.once({
+const result = await gpu.compute({
   code: `
     struct Dims {
       m: u32,
@@ -50,4 +50,4 @@ const result = await gpu.compute.once({
   workgroups: [Math.ceil(N / 8), Math.ceil(M / 8)],
 });
 
-console.log(result.subarray(0, 8));
+console.log(JSON.stringify(Array.from(result.subarray(0, 8), (value) => Number(value.toFixed(4)))));

package/examples/{doe-routines/compute-once-multiple-inputs.js → doe-api/compute-one-shot-multiple-inputs.js}

@@ -2,7 +2,7 @@ import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
 
-const result = await gpu.compute.once({
+const result = await gpu.compute({
   code: `
     @group(0) @binding(0) var<storage, read> lhs: array<f32>;
     @group(0) @binding(1) var<storage, read> rhs: array<f32>;

package/examples/{doe-routines/compute-once.js → doe-api/compute-one-shot.js}

@@ -2,7 +2,7 @@ import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
 
-const result = await gpu.compute.once({
+const result = await gpu.compute({
   code: `
     @group(0) @binding(0) var<storage, read> src: array<f32>;
     @group(0) @binding(1) var<storage, read_write> dst: array<f32>;

package/examples/doe-api/{compile-and-dispatch.js → kernel-create-and-dispatch.js}

@@ -1,12 +1,10 @@
 import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
-const src = gpu.buffers.fromData(new Float32Array([1, 2, 3, 4]));
-const dst = gpu.buffers.like(src, {
-  usage: "storageReadWrite",
-});
+const src = gpu.buffer.create({ data: new Float32Array([1, 2, 3, 4]) });
+const dst = gpu.buffer.create({ size: src.size, usage: "storageReadWrite" });
 
-const kernel = gpu.compute.compile({
+const kernel = gpu.kernel.create({
   code: `
     @group(0) @binding(0) var<storage, read> src: array<f32>;
     @group(0) @binding(1) var<storage, read_write> dst: array<f32>;
@@ -26,5 +24,5 @@ await kernel.dispatch({
   workgroups: 1,
 });
 
-const result = await gpu.buffers.read(dst, Float32Array);
+const result = await gpu.buffer.read({ buffer: dst, type: Float32Array });
 console.log(JSON.stringify(Array.from(result)));

package/examples/doe-api/{compute-dispatch.js → kernel-run.js}

@@ -1,12 +1,10 @@
 import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
-const src = gpu.buffers.fromData(new Float32Array([1, 2, 3, 4]));
-const dst = gpu.buffers.like(src, {
-  usage: "storageReadWrite",
-});
+const src = gpu.buffer.create({ data: new Float32Array([1, 2, 3, 4]) });
+const dst = gpu.buffer.create({ size: src.size, usage: "storageReadWrite" });
 
-await gpu.compute.run({
+await gpu.kernel.run({
   code: `
     @group(0) @binding(0) var<storage, read> src: array<f32>;
     @group(0) @binding(1) var<storage, read_write> dst: array<f32>;
@@ -21,5 +19,5 @@ await gpu.compute.run({
   workgroups: 1,
 });
 
-const result = await gpu.buffers.read(dst, Float32Array);
+const result = await gpu.buffer.read({ buffer: dst, type: Float32Array });
 console.log(JSON.stringify(Array.from(result)));

package/headless-webgpu-comparison.md

@@ -38,6 +38,6 @@ Notes:
 
 ## Scaffolding the Fawn NPM Package
 
-- 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.
+- Doe is exposed through a native C ABI with parallel N-API (Node) and FFI (Bun) transports. Bun uses a platform-dependent bridge: FFI on Linux, addon-backed on macOS for correctness parity.
+- The canonical package is `@simulatte/webgpu` with full Node N-API and Bun support.
+- Browser API parity is not claimed; the current focus is headless compute and benchmarking workflows. Browser ownership lives in `nursery/fawn-browser`.