@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -63,7 +63,7 @@
     "@graphty/graph-format": "^1.0.2"
   },
   "peerDependencies": {
-    "@graphty/algorithms": "^1.0.0",
+    "@graphty/algorithms": "^1.0.0 || ^2.0.0",
     "@graphty/graph-format": "^1.0.0",
     "@graphty/layout": "^1.7.0",
     "webgpu": ">=0.4.0 <1.0.0"
@@ -92,8 +92,8 @@
     "vite": "^7.0.5",
     "vitest": "^3.2.4",
     "webgpu": "0.4.0",
-    "@graphty/layout": "^1.8.0",
-    "@graphty/algorithms": "^1.8.1"
+    "@graphty/algorithms": "^2.0.0",
+    "@graphty/layout": "^1.8.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -105,13 +105,14 @@
     "typecheck:strict-consumer": "tsc -p tsconfig.strict-consumer.json",
     "test": "vitest",
     "test:ui": "vitest --ui",
-    "test:run": "vitest run --project=node",
-    "test:node": "vitest run --project=node",
+    "test:run": "vitest run --project=node --project=node-device-errors",
+    "test:node": "vitest run --project=node --project=node-device-errors",
+    "test:node:ci": "node scripts/run-node-shard.js",
     "test:browser": "vitest run --project=browser",
     "test:browser:ci": "node scripts/run-browser-project.js",
     "test:limits": "vitest run --project=node-limits",
-    "coverage": "vitest run --project=node --coverage",
-    "coverage:preview": "npx serve coverage -p 9058",
+    "coverage": "vitest run --project=node --project=node-device-errors --coverage",
+    "coverage:preview": "npx serve coverage -p ${PORT:?start it through servherd, which sets PORT}",
     "bench": "tsx benchmarks/run.ts",
     "bench:compare": "node scripts/bench-compare.js",
     "benchmark": "tsx benchmarks/run.ts",

package/src/algorithms/components.ts

@@ -19,11 +19,13 @@ import { type GraphSnapshot, renumberPartition, type U32 } from "@graphty/graph-
 
 import { U32_MAX } from "../constants.js";
 import { type GpuContext } from "../context.js";
-import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { WebGpuGraphError } from "../errors.js";
 import { CommandBatch } from "../kernel/batch.js";
 import { plan1d, planGridStride } from "../kernel/dispatch.js";
 import { FILL_PARAMS, graphBindings, graphOverrides, kernelSpec, WCC_PARAMS } from "../kernels.js";
 import { type CoreBinding } from "../memory/residency.js";
+import { assertWholeCore } from "../primitives/core-shape.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { type ComponentsOptions, type GpuLabelResult } from "../types/algorithms.js";
 import { type Binding } from "../types/memory.js";
 import { type GpuRunOptions } from "../types/run.js";
@@ -66,25 +68,16 @@ function checkDest(dest: Float32Array | Uint32Array | undefined, n: number): U32
 }
 
 /**
- * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
- * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * The resident core; a windowed plan is refused with `E_TOO_LARGE { path: "windowed", algorithm }` (spec 3.8, 3.12;
+ * DEP-P4-B: only degree and segmentedReduce execute windows).
  * @param ctx - the context
  * @param s - the snapshot
  * @returns the core binding
  */
 function coreOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding {
-    try {
-        return ctx.residency.core(s);
-    } catch (error: unknown) {
-        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
-            throw new WebGpuGraphError(
-                "E_TOO_LARGE",
-                `${ALGORITHM}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`,
-                { ...error.details, algorithm: ALGORITHM },
-            );
-        }
-        throw error;
-    }
+    const core = ctx.residency.core(s);
+    assertWholeCore(core, s.arcCount, ctx.caps.limits.maxStorageBufferBindingSize, ALGORITHM);
+    return core;
 }
 
 /**
@@ -197,6 +190,7 @@ export async function connectedComponents(
     options?: ComponentsOptions & GpuRunOptions,
 ): Promise<GpuLabelResult> {
     ctx.assertReady();
+    await assertDeviceComputes(ctx);
     const n = s.nodeCount;
     const renumber = options?.renumber !== false;
     const dest = checkDest(options?.dest, n);
@@ -312,7 +306,9 @@ export async function connectedComponents(
             rounds += ROUNDS_PER_BATCH;
             ctx.assertReady();
             if (options?.signal?.aborted) {
-                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, { batchId: submitted.id });
+                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, {
+                    batchId: submitted.id,
+                });
             }
             if (new Uint32Array(back, flagRequest.offset, 1)[0] === 0) {
                 break;

package/src/algorithms/degree.ts

@@ -9,24 +9,24 @@
  *
  * Contract (3.12): `ctx.assertReady()` first; `nodeCount === 0` returns an empty `Uint32Array` (or `dest`) with no
  * GPU work (spec 5.6: there is no work, which is not a fallback); an already-aborted `signal` is `E_ABORTED` before
- * any work; `dest` must be a `Uint32Array` of length n over an `ArrayBuffer`; a windowed core is `E_TOO_LARGE
- * { path: "windowed", algorithm: "degree" }` until P4 executes windows -- `residency.core()` (3.8) throws that error
- * itself with `algorithm: null` before it would ever return a windowed `CoreBinding`, so `degree` catches it and
- * re-throws the same error with `algorithm: "degree"` (the 3.12 detail) instead of testing `core.plan`, which never
- * observes "windowed" in P1-P3; `arcCount === 0` skips the dispatch (only `rowPtr` is resident)
- * and the result is zeros; otherwise ONE dispatch over rows [0, n) with `accumulate = 0` (every row is written, so no
- * fill precedes it), a readback into the result, `onProgress(1, 1)`, and the scratch returned in a finally. Two runs
- * are bitwise identical (spec 11.9 item 4).
+ * any work; `dest` must be a `Uint32Array` of length n over an `ArrayBuffer`; `arcCount === 0` skips the dispatch
+ * (only `rowPtr` is resident) and the result is zeros; otherwise ONE dispatch over rows [0, n) with `accumulate = 0`
+ * (every row is written, so no fill precedes it) -- or, on a windowed core (spec 4.2, PD-8), a `fill` of zeros and
+ * one dispatch per window over its rows with `arcBase = w.start`, `arcEnd = w.end`, `accumulate = 1`, so a row split
+ * across windows adds its partial counts -- a readback into the result, `onProgress(1, 1)`, and the scratch returned
+ * in a finally. Two runs are bitwise identical (spec 11.9 item 4).
  */
 
 import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
 
 import { type GpuContext } from "../context.js";
 import { BufferUsage } from "../device/webgpu-constants.js";
-import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { WebGpuGraphError } from "../errors.js";
 import { plan1d } from "../kernel/dispatch.js";
-import { graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
-import { type CoreBinding } from "../memory/residency.js";
+import { type UniformBlock, type UniformValues } from "../kernel/struct-block.js";
+import { FILL_PARAMS, graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
+import { windowBinding } from "../primitives/core-shape.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { type Binding } from "../types/memory.js";
 import { type GpuRunOptions } from "../types/run.js";
 
@@ -55,26 +55,21 @@ function checkDest(dest: Float32Array | Uint32Array | undefined, n: number): U32
 }
 
 /**
- * Uploads (or finds) the core through the residency; a windowed plan, which the residency reports as `E_TOO_LARGE
- * { path: "windowed", algorithm: null }` (3.8), is re-thrown with `algorithm: "degree"` (3.12) and its other details
- * (`needed`, `limit`, `path`) kept. Every other error passes through untouched.
- * @param ctx - the context whose residency holds the core
- * @param s - the snapshot
- * @returns the resident core binding (arena or perArray)
+ * One pool-acquired uniform buffer holding one params record (a params buffer per dispatch; the caller releases
+ * `pooled` in its finally).
+ * @param ctx - the context whose pool and queue are used
+ * @param pooled - the list the buffer is appended to for release
+ * @param block - the uniform block
+ * @param values - the record's values
+ * @returns the whole-buffer binding
  */
-function coreOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding {
-    try {
-        return ctx.residency.core(s);
-    } catch (error: unknown) {
-        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
-            throw new WebGpuGraphError(
-                "E_TOO_LARGE",
-                "degree: the arc arrays need a windowed upload, which P1-P3 plan but do not execute",
-                { ...error.details, algorithm: "degree" },
-            );
-        }
-        throw error;
-    }
+function paramsBinding(ctx: GpuContext, pooled: GPUBuffer[], block: UniformBlock, values: UniformValues): Binding {
+    const buffer = ctx.pool.acquire(block.byteLength, BufferUsage.UNIFORM | BufferUsage.COPY_DST, "degree/params");
+    pooled.push(buffer);
+    const bytes = new ArrayBuffer(block.byteLength);
+    block.write(new DataView(bytes), values);
+    ctx.device.queue.writeBuffer(buffer, 0, bytes);
+    return { buffer, offset: 0, size: block.byteLength, window: null };
 }
 
 /**
@@ -89,6 +84,7 @@ function coreOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding {
  */
 export async function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRunOptions): Promise<U32> {
     ctx.assertReady();
+    await assertDeviceComputes(ctx);
     const n = s.nodeCount;
     const dest = checkDest(options?.dest, n);
     if (options?.signal?.aborted) {
@@ -98,7 +94,7 @@ export async function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRun
         options?.onProgress?.(1, 1);
         return dest ?? new Uint32Array(0);
     }
-    const core = coreOf(ctx, s);
+    const core = ctx.residency.core(s);
     if (s.arcCount === 0) {
         const zeros = dest ?? new Uint32Array(n);
         zeros.fill(0);
@@ -111,23 +107,40 @@ export async function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRun
         BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST,
         "degree/out",
     );
-    const params = ctx.pool.acquire(
-        RANGE_PARAMS.byteLength,
-        BufferUsage.UNIFORM | BufferUsage.COPY_DST,
-        "degree/params",
-    );
+    const pooled: GPUBuffer[] = [];
+    const params = (block: UniformBlock, values: UniformValues): Binding => paramsBinding(ctx, pooled, block, values);
     try {
         await ctx.allocator.check();
         const kernel = await ctx.pipelines.kernel(kernelSpec("degree", graphOverrides(core, null)));
-        const bytes = new ArrayBuffer(RANGE_PARAMS.byteLength);
-        RANGE_PARAMS.write(new DataView(bytes), { start: 0, end: n, arcBase: 0, arcEnd: s.arcCount, accumulate: 0, n });
-        ctx.device.queue.writeBuffer(params, 0, bytes);
         const outBinding: Binding = { buffer: out, offset: 0, size: byteLength, window: null };
-        const paramsBinding: Binding = { buffer: params, offset: 0, size: RANGE_PARAMS.byteLength, window: null };
-        const bound = kernel.bind({ ...graphBindings(core, null), out: outBinding, P: paramsBinding });
         const encoder = ctx.device.createCommandEncoder({ label: "degree" });
         const pass = encoder.beginComputePass({ label: "degree" });
-        kernel.dispatch(pass, bound, plan1d(n, ctx.workgroupSize, ctx.caps), [0]);
+        if (core.windows === null) {
+            const P = params(RANGE_PARAMS, { start: 0, end: n, arcBase: 0, arcEnd: s.arcCount, accumulate: 0, n });
+            const bound = kernel.bind({ ...graphBindings(core, null), out: outBinding, P });
+            kernel.dispatch(pass, bound, plan1d(n, ctx.workgroupSize, ctx.caps), [0]);
+        } else {
+            const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+            const zero = fill.bind({ dst: outBinding, P: params(FILL_PARAMS, { count: n, value: 0, mode: 0 }) });
+            fill.dispatch(pass, zero, plan1d(n, ctx.workgroupSize, ctx.caps), [0]);
+            for (const w of core.windows) {
+                const windowed = {
+                    ...core,
+                    colIdx: windowBinding(core, "colIdx", w),
+                    weights: core.weights === null ? null : windowBinding(core, "weights", w),
+                };
+                const P = params(RANGE_PARAMS, {
+                    start: w.rowFirst,
+                    end: w.rowLast + 1,
+                    arcBase: w.start,
+                    arcEnd: w.end,
+                    accumulate: 1,
+                    n,
+                });
+                const bound = kernel.bind({ ...graphBindings(windowed, null), out: outBinding, P });
+                kernel.dispatch(pass, bound, plan1d(w.rowLast - w.rowFirst + 1, ctx.workgroupSize, ctx.caps), [0]);
+            }
+        }
         pass.end();
         ctx.device.queue.submit([encoder.finish()]);
         ctx.assertReady();
@@ -136,7 +149,9 @@ export async function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRun
         options?.onProgress?.(1, 1);
         return dest ?? new Uint32Array(result);
     } finally {
-        ctx.pool.release(params);
+        for (const buffer of pooled) {
+            ctx.pool.release(buffer);
+        }
         ctx.pool.release(out);
     }
 }

package/src/algorithms/pagerank.ts

@@ -18,14 +18,15 @@ import { type F32, type GraphSnapshot } from "@graphty/graph-format";
 
 import { U32_MAX } from "../constants.js";
 import { type GpuContext } from "../context.js";
-import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { WebGpuGraphError } from "../errors.js";
 import { CommandBatch } from "../kernel/batch.js";
 import { groupsOf, plan1d } from "../kernel/dispatch.js";
 import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
 import { type ArrayBinding, type CoreBinding } from "../memory/residency.js";
-import { coreOfView } from "../primitives/core-shape.js";
+import { assertWholeCore, coreOfView } from "../primitives/core-shape.js";
 import { prepareSegmentedReduce } from "../primitives/segmented-reduce.js";
 import { prepareSpmvPull } from "../primitives/spmv.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { type GpuPageRankResult, type PageRankOptions } from "../types/algorithms.js";
 import { type Binding } from "../types/memory.js";
 import { type GpuRunOptions } from "../types/run.js";
@@ -62,26 +63,17 @@ function checkDest(dest: Float32Array | Uint32Array | undefined, n: number, algo
 }
 
 /**
- * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
- * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * The resident core; a windowed plan is refused with `E_TOO_LARGE { path: "windowed", algorithm }` (spec 3.8, 3.12;
+ * DEP-P4-B: only degree and segmentedReduce execute windows).
  * @param ctx - the context
  * @param s - the snapshot
  * @param algorithm - the caller's name
  * @returns the core binding
  */
 function coreOf(ctx: GpuContext, s: GraphSnapshot, algorithm: string): CoreBinding {
-    try {
-        return ctx.residency.core(s);
-    } catch (error: unknown) {
-        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
-            throw new WebGpuGraphError(
-                "E_TOO_LARGE",
-                `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`,
-                { ...error.details, algorithm },
-            );
-        }
-        throw error;
-    }
+    const core = ctx.residency.core(s);
+    assertWholeCore(core, s.arcCount, ctx.caps.limits.maxStorageBufferBindingSize, algorithm);
+    return core;
 }
 
 /**
@@ -126,6 +118,7 @@ async function run(
     algorithm: string,
 ): Promise<GpuPageRankResult> {
     ctx.assertReady();
+    await assertDeviceComputes(ctx);
     const n = s.nodeCount;
     const alpha = options?.dampingFactor ?? 0.85;
     const maxIterations = options?.maxIterations ?? 100;
@@ -144,7 +137,13 @@ async function run(
     }
     if (n === 0) {
         options?.onProgress?.(maxIterations, maxIterations);
-        return { scores: dest ?? new Float32Array(0), iterations: 0, converged: true, danglingMass: 0, precision: "f32" };
+        return {
+            scores: dest ?? new Float32Array(0),
+            iterations: 0,
+            converged: true,
+            danglingMass: 0,
+            precision: "f32",
+        };
     }
     const core = coreOf(ctx, s, algorithm);
     if (s.arcCount === 0) {
@@ -322,7 +321,10 @@ export async function personalizedPageRank(
             expected,
         });
     if (!(personalization instanceof Float32Array) || personalization.length !== n) {
-        throw invalid(`${personalization.constructor.name}(${personalization.length})`, `a Float32Array of length ${n}`);
+        throw invalid(
+            `${personalization.constructor.name}(${personalization.length})`,
+            `a Float32Array of length ${n}`,
+        );
     }
     let total = 0;
     for (let v = 0; v < n; v++) {

package/src/algorithms/power-iteration.ts

@@ -20,13 +20,14 @@ import { type F32, type GraphSnapshot } from "@graphty/graph-format";
 
 import { U32_MAX } from "../constants.js";
 import { type GpuContext } from "../context.js";
-import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { WebGpuGraphError } from "../errors.js";
 import { CommandBatch } from "../kernel/batch.js";
 import { groupsOf, plan1d } from "../kernel/dispatch.js";
 import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
 import { type CoreBinding } from "../memory/residency.js";
-import { coreOfView } from "../primitives/core-shape.js";
+import { assertWholeCore, coreOfView } from "../primitives/core-shape.js";
 import { prepareSpmvPull } from "../primitives/spmv.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { type Binding } from "../types/memory.js";
 import { algorithmScope } from "./scope.js";
 
@@ -103,26 +104,17 @@ export function checkDest(dest: Float32Array | Uint32Array | undefined, n: numbe
 }
 
 /**
- * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
- * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * The resident core; a windowed plan is refused with `E_TOO_LARGE { path: "windowed", algorithm }` (spec 3.8, 3.12;
+ * DEP-P4-B: only degree and segmentedReduce execute windows).
  * @param ctx - the context
  * @param s - the snapshot
  * @param algorithm - the caller's name
  * @returns the core binding
  */
 export function coreOf(ctx: GpuContext, s: GraphSnapshot, algorithm: string): CoreBinding {
-    try {
-        return ctx.residency.core(s);
-    } catch (error: unknown) {
-        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
-            throw new WebGpuGraphError(
-                "E_TOO_LARGE",
-                `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`,
-                { ...error.details, algorithm },
-            );
-        }
-        throw error;
-    }
+    const core = ctx.residency.core(s);
+    assertWholeCore(core, s.arcCount, ctx.caps.limits.maxStorageBufferBindingSize, algorithm);
+    return core;
 }
 
 /**
@@ -179,6 +171,7 @@ export async function runPowerIteration(
     n: number,
     config: PowerIterationConfig,
 ): Promise<PowerIterationRun> {
+    await assertDeviceComputes(ctx);
     const scope = algorithmScope(ctx, config.label, RING_SLOTS);
     try {
         const bytes = 4 * n;
@@ -231,7 +224,14 @@ export async function runPowerIteration(
                 const rankOut = ring[iteration % ring.length];
                 const { core, pull } = pulls[(iteration - 1) % pulls.length];
                 // outWeightSum takes rankIn as its dummy: storage-ro, read only under NORM_MODE 0, never compiled here
-                const scaleBindings = { rankIn, rankPrev: rankOut, outWeightSum: rankIn, xNorm, partials, P: params.binding };
+                const scaleBindings = {
+                    rankIn,
+                    rankPrev: rankOut,
+                    outWeightSum: rankIn,
+                    xNorm,
+                    partials,
+                    P: params.binding,
+                };
                 scaleNorm.dispatch(pass, scaleNorm.bind(scaleBindings), scalePlan, [params.offset]);
                 finalize.dispatch(pass, finalize.bind({ partials, P: params.binding }), finalizePlan, [params.offset]);
                 if (scaleApply !== null) {
@@ -265,7 +265,8 @@ export async function runPowerIteration(
                 }
                 return {
                     scores: new Float32Array(back, scoresRequest.offset, n).slice(),
-                    previous: previousRequest === null ? null : new Float32Array(back, previousRequest.offset, n).slice(),
+                    previous:
+                        previousRequest === null ? null : new Float32Array(back, previousRequest.offset, n).slice(),
                     iterations: converged ? firstConverged : iterationsRun,
                     converged,
                     iterationsRun,

package/src/constants.ts

@@ -13,6 +13,8 @@ export const MAX_WORKGROUPS_PER_DIM = 65535;
 export const MAX_1D_ITEMS = MAX_WORKGROUPS_PER_DIM * WORKGROUP_SIZE;
 /** The largest u32 (the `min` identity of the u32 reduce); interpolated into the prelude as `U32_MAX` so no body types the literal (contract 4.1). */
 export const U32_MAX = 0xffffffff;
+/** The bins of one radix-sort pass, 2^8 (spec 6 row 6; P4 PD-5: 8 bits per pass); interpolated into the prelude as `RADIX_BINS` and `RADIX_DIGIT_MASK` (= bins - 1) so no body types the literal. */
+export const RADIX_BINS = 256;
 /** Arc-window boundaries are multiples of 64 arcs = 256 bytes (design 10.6). */
 export const ARC_WINDOW_ALIGN = 64;
 /** Storage-binding offset alignment the package always honours (spec 2.6): the graph-format arena is 256-aligned. */
@@ -20,14 +22,30 @@ export const STORAGE_ALIGN = 256;
 /** Stride of one UniformRing slot: minUniformBufferOffsetAlignment is 256 on every runtime the package targets (spec 5.3). */
 export const UNIFORM_SLOT_BYTES = 256;
 /**
- * Exact-tier crossover default, re-fixed at G3 by the spec 7.8 rule (spec Q-6; docs/decisions/G3.md section 3): the
- * largest rung of the T-4 ladder (1k / 4k / 8k / 16k / 32k / 65k, E = 10n, 2D) with <= 4 ms per iteration, rounded down
- * to a power of two. Measured on the RTX 4070 SUPER under Dawn-node: benchmarks/results/nvidia-lovelace-driver580.json,
- * session 2026-09-16T02:07:45.933Z, the "ms/iteration (profiler)" rows (the GPU time of the iteration's passes at the
- * card's working clock; the step(1) wall rows beside them include the 12n readback): 2.560 ms at 32k, 8.405 ms at 65k.
- * The rule's second clause -- not slower than the grid tier at the same n -- has no grid tier to compare with in P3 and
- * is re-checked at G4 (spec 7.8). A consumer whose GPU differs (integrated, Apple, T4) passes its own value through
- * createAccelerator(ctx, { layout: { exactMaxNodes } }); P4's calibrateLayout(ctx) measures it.
+ * Exact-tier crossover default, re-fixed at G4 by the spec 7.8 rule in full (spec Q-6; docs/decisions/G3.md section 3
+ * for the budget clause, docs/decisions/G4.md section 7 for the re-check): the largest rung of the T-4 ladder (1k / 4k /
+ * 8k / 16k / 32k / 65k, E = 10n, 2D) with <= 4 ms per iteration AND not slower than the grid tier at the same n (the
+ * `layout-grid` 2D rows: the shared rungs 32k / 65k and the re-check rungs 1k / 4k / 8k / 16k the group runs so every
+ * exact rung has a grid row), rounded down to a power of two. Measured on the RTX 4070 SUPER under Dawn-node:
+ * benchmarks/results/nvidia-lovelace-driver580.json, session 2026-09-21T06:15:17.027Z, the "ms/iteration (profiler)"
+ * rows of layout-exact and the "grid ms/iteration (profiler) ... 2D" rows of layout-grid (the GPU time of the
+ * iteration's passes at the card's working clock), exact / grid ms per iteration: 1k 0.102 / 0.290, 4k 0.262 / 0.188,
+ * 8k 0.484 / 0.211, 16k 1.064 / 0.225, 32k 2.579 / 0.298, 65k 8.450 / 0.409. The grid tier's cost is a near-constant
+ * ~0.19-0.3 ms floor (its sort, scan and pyramid passes) up to 32k, so the exact tier wins only at 1k and the rule's
+ * answer is 1024 (32768 under the budget clause alone, the G3 value; 16384 was the P4-T14 draft's value, which only
+ * evaluated the grid clause at 32k / 65k and was not a measurement). calibrateLayout's finer probe on the same card
+ * (tmp/p4/t14-review/calibrate-defaults.log: exact 0.150 vs grid 0.190 ms at 2048) puts the true crossover between
+ * 2k and 4k; the ladder has no 2k rung, and the design's basis (cosmos switches at 4,096) is within 0.07 ms per
+ * iteration of the rule's value, so the choice among 1k / 2k / 4k is an accuracy preference (the exact tier is the
+ * oracle), not a speed one. OWNER DECISION G4-D1 (docs/decisions/G4.md section 7, rows G4-D1 / G4-F9): the constant
+ * KEEPS the G3 value 32768 while the accuracy work G4-F1 leaves is open -- G4-F1 (the grid tier's exact-vs-grid RMS
+ * on the clumpy and degenerate fixtures) closed on 2026-09-21 by the owner's asserted / printed split, G4-F2 (the
+ * unbiasedness item) the same day by its re-scope to the whole-field ratio, and the far field's accuracy on those
+ * fixtures is the follow-up -- because "auto" is the default every consumer sees and the exact tier is the accurate
+ * one; the rule's answer on the dev box (1024) is recorded, not shipped, until that work closes and the value is
+ * re-fixed. A
+ * consumer whose GPU differs (integrated, Apple, T4) passes its own value through
+ * createAccelerator(ctx, { layout: { exactMaxNodes } }); calibrateLayout(ctx) measures it.
  */
 export const EXACT_MAX_NODES = 32768;
 /** Default number of MAP_READ staging buffers in the Readback ring (spec 4.4). */
@@ -184,3 +202,15 @@ export const SE_DEFAULTS: Readonly<{
     iterationsPerStep: 1,
     maxInFlight: 2,
 });
+/** The smallest finest grid side `G` (spec 7.7 geometry table: `clamp(nextPow2(2 n^(1/dim)), 8, gridMax)`; P4 PD-9). */
+export const GRID_MIN_SIDE = 8;
+/** The coarsest pyramid level's side (spec 7.7: "levels (coarsest 4 per axis)", `levels = log2(G / 4) + 1`). */
+export const GRID_COARSEST_SIDE = 4;
+/** A cell with more than this many entries is summed by a workgroup (G4b) instead of the thread-per-cell loop of G4 (spec 7.7 G4: `count > 1024`). */
+export const GRID_HUB_CELL = 1024;
+/** The extent floor of spec 7.7: `cellSize = max(extent, 1e-6) / G`, so an all-coincident load never divides by zero. */
+export const GRID_EXTENT_FLOOR = 1e-6;
+/** The bbox margin of spec 7.7: `bboxExtent` is the largest axis of `state.min / max` "with a 1% margin". */
+export const GRID_BBOX_MARGIN = 1.01;
+/** The key width the grid always sorts with (P4 PD-5): three 8-bit passes cover the 19-bit 2D keys at G = 512 and the 22-bit 3D keys at G = 128, and an odd pass count leaves `sortedIdx` in the scratch pair. */
+export const GRID_SORT_BITS = 24;

package/src/errors.ts

@@ -9,7 +9,8 @@
  * `details` keys per code (contract 3.1, so tests can assert them): E_NO_WEBGPU { reason, hint };
  * E_NO_ADAPTER { reason }; E_NO_DEVICE { reason, adapter, limit?, requested?, available? } (reason "consumed" |
  * "requestDevice" | "limit" | "feature" | "maxComputeWorkgroupsPerDimension"); E_SOFTWARE_ONLY { adapter };
- * E_DEVICE_LOST { reason, message }; E_DISPOSED { label }; E_VALIDATION { label, message, batchId? };
+ * E_DEVICE_LOST { reason, message }; E_DEVICE_INCORRECT { check, where, expected, actual, poison, count, blocks,
+ * workgroupSize, adapter, hint? }; E_DISPOSED { label }; E_VALIDATION { label, message, batchId? };
  * E_SHADER_COMPILE { id, stage: "compose" | "compile", slot?, messages? }; E_OUT_OF_MEMORY { requested, resident,
  * label }; E_TOO_LARGE { needed, limit, path, algorithm }; E_UNSUPPORTED { feature? | option?, hint? } (exactly
  * one of feature / option); E_INVALID_ARGUMENT { argument, value, expected? }; E_SNAPSHOT { reason, serial };
@@ -23,6 +24,7 @@ export type WebGpuGraphErrorCode =
     | "E_NO_DEVICE"
     | "E_SOFTWARE_ONLY"
     | "E_DEVICE_LOST"
+    | "E_DEVICE_INCORRECT"
     | "E_DISPOSED"
     | "E_VALIDATION"
     | "E_SHADER_COMPILE"

package/src/index.ts

@@ -8,8 +8,8 @@
  * isSoftwareAdapter. P1 adds GpuContext and degree (values) and the context / run / profiler types. P2 adds nothing
  * (Lease, CommandBatch, UniformRing are internal). P3 adds the layout factory, the accelerator, the two default
  * tables, the seeder and the layout / accelerator types. P5 adds the two factories, the two default tables and the
- * two stats records. test/index.test.ts pins the value list and test/types/public-api.test-d.ts the type list; P4+
- * extends both. This comment must never spell the internal
+ * two stats records. P4 adds calibrateLayout and its two records. test/index.test.ts pins the value list and
+ * test/types/public-api.test-d.ts the type list. This comment must never spell the internal
  * JSDoc tag: it is the leading comment of the first export statement, and stripInternal would drop that statement
  * from the emitted declarations.
  */
@@ -41,6 +41,11 @@ export { GpuContext } from "./context.js";
 export { isSoftwareAdapter } from "./device/acquire.js";
 export type { PassTiming, Profiler } from "./kernel/profiler.js";
 
+// ==================== the device self-check: what this device computed when it was asked an answer we already
+// know. Every compute entry point awaits it and refuses a device that got it wrong (E_DEVICE_INCORRECT); a
+// caller may await it first to ask before committing.
+export { verifyDevice } from "./primitives/verify.js";
+
 // ==================== algorithms (P1: the walking-skeleton diagnostic, spec 3.3)
 export { degree } from "./algorithms/degree.js";
 
@@ -49,8 +54,9 @@ export { connectedComponents } from "./algorithms/components.js";
 export { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 export { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 
-// ==================== layouts and the accelerator (P3; the two P5 factories)
+// ==================== layouts and the accelerator (P3; the two P5 factories; P4's calibrateLayout, spec 2.2)
 export { createAccelerator } from "./accelerator.js";
+export { calibrateLayout } from "./layouts/calibrate.js";
 export { createForceAtlas2 } from "./layouts/forceatlas2.js";
 export { createFruchtermanReingold } from "./layouts/fruchterman-reingold.js";
 export { seedPositions } from "./layouts/seed.js";
@@ -97,6 +103,8 @@ export type {
 export type {
     AdapterInfoLike,
     AdapterSummary,
+    DeviceCheck,
+    DeviceCheckMismatch,
     GpuCaps,
     GpuContextOptions,
     LimitPolicy,
@@ -107,12 +115,14 @@ export type {
     RaisableLimit,
 } from "./types/context.js";
 
-// ==================== types: layouts (P3; the P5 stats and trace records)
+// ==================== types: layouts (P3; the P5 stats and trace records; the P4 calibration records)
 export type {
+    CalibrateOptions,
     ForceAtlas2Stats,
     ForceAtlas2TraceRecord,
     FruchtermanReingoldStats,
     FruchtermanReingoldTraceRecord,
+    GpuCalibration,
     GpuLayoutSimulation,
     GpuLayoutTuning,
     LayoutStatsBase,

package/src/kernel/dispatch.ts

@@ -147,16 +147,27 @@ export function planGridStride(items: number, wg: number, caps: PlanCaps, maxGro
 }
 
 /**
- * P4 (spec 5.4): the (x, y, 1) args a device-side finalize kernel writes for a count. P1-P3: throws E_UNSUPPORTED { feature: "planIndirect" } (lead f).
- * @param count - the device-side count
- * @param wg - the workgroup size
+ * P4 (spec 5.4): the (x, y, 1) args the device-side finalize kernel writes for a count -- plan1d's rule applied to a
+ * u32 count through the same grid() as plan1d and plan2d, so the host twin and the kernel cannot drift; the kernel
+ * (src/wgsl/indirect-finalize.wgsl.ts) mirrors exactly this arithmetic. `items` of the plan is the count. A count
+ * outside [0, 2^32) is E_INVALID_ARGUMENT (the device holds it as a u32); for any u32 count y <= 1,025, so
+ * E_TOO_LARGE is unreachable here.
+ * @param count - the device-side count (a u32)
+ * @param wg - the workgroup size (a power of two)
  * @param caps - the capability table
+ * @returns the plan
  */
 export function planIndirect(count: number, wg: number, caps: PlanCaps): DispatchPlan {
-    throw new WebGpuGraphError("E_UNSUPPORTED", "planIndirect lands with the indirect dispatch of P4 (spec 5.4)", {
-        feature: "planIndirect",
-        hint: `count ${count}, wg ${wg}, limit ${perDimension(caps)}`,
-    });
+    assertCount("count", count);
+    if (count > 0xffffffff) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `count must fit a u32, got ${count}`, {
+            argument: "count",
+            value: count,
+            expected: "an integer in [0, 2^32)",
+        });
+    }
+    assertWorkgroupSize(wg);
+    return grid(Math.ceil(count / wg), count, caps);
 }
 
 /**