@graphty/webgpu-graph-algorithms 0.5.0 → 0.6.0

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). */
@@ -114,3 +132,85 @@ export const FA2_DISTANCE_FLOOR_SQ = 0.0001;
 export const FA2_COINCIDENT_SQ = 1e-8;
 /** Bits of Fa2Params.flags (contract 4.4). */
 export const FA2_FLAG_FIRST = 1;
+/** Fa2Params.flags bit: the Fruchterman-Reingold temperature is the adaptive one in the state block, not the uniform's (the `cooling: "adaptive"` option). */
+export const FA2_FLAG_ADAPTIVE = 2;
+/** The Fruchterman-Reingold loop's starting temperature (spec 7.20; `layout/src/simulation/fruchterman-reingold.ts:30`). */
+export const FR_START_TEMPERATURE = 0.1;
+/** The reheat point of spec 7.20: the temperature index a reheat restarts at, as a fraction of `iterations`. */
+export const FR_REHEAT_FRACTION = 0.7;
+/** Adaptive cooling (Yifan Hu 2005, section 3.2): the temperature is multiplied by this when the force energy rose, divided by it after FR_COOLING_PATIENCE consecutive falls. */
+export const FR_COOLING_STEP = 0.9;
+/** Adaptive cooling: consecutive iterations of falling energy before the temperature grows. */
+export const FR_COOLING_PATIENCE = 5;
+/** Adaptive cooling: the iteration budget when `iterations` is not given (the schedule no longer needs one; this is the cap on a run that never settles). */
+export const FR_ADAPTIVE_MAX_ITERATIONS = 10_000;
+/** Fruchterman-Reingold defaults (spec 7.20, 9.3; the CPU simulation's, `layout/src/simulation/fruchterman-reingold.ts:32`): `k` null = `1 / sqrt(n)`. */
+export const FR_DEFAULTS: Readonly<{
+    k: null;
+    iterations: 50;
+    fixed: null;
+    dim: 2;
+    scale: 1;
+    settleThreshold: 0.001;
+    settleWindow: 10;
+    iterationsPerStep: 1;
+    maxInFlight: 2;
+    cooling: "linear";
+}> = Object.freeze({
+    k: null,
+    iterations: 50,
+    fixed: null,
+    dim: 2,
+    scale: 1,
+    settleThreshold: 0.001,
+    settleWindow: 10,
+    iterationsPerStep: 1,
+    maxInFlight: 2,
+    cooling: "linear",
+});
+/**
+ * Spring-electrical size scaling: when `gravity` or `springCoefficient` is left to its default, ngraph's constant is
+ * multiplied by min(1, SE_SCALE_REFERENCE_NODES / n). ngraph's values were tuned for graphs of a few hundred nodes;
+ * on tens of thousands the per-node forces are so large that every node moves at the unit speed clamp and the layout
+ * never comes to rest (measured on the 58k-node Brightkite graph: 3,350 iterations to the settle rule with the
+ * kinetic energy still at the clamp; a uniform 1/1000 factor settled in 1,000 with the energy decayed 25x).
+ */
+export const SE_SCALE_REFERENCE_NODES = 300;
+/** Spring-electrical defaults: ngraph.forcelayout 3.3.1's (`lib/createPhysicsSimulator.js:29,34,40,54,59`; spec 7.20), plus the shared simulation defaults. `gravity` is ngraph's Coulomb constant: negative repels. */
+export const SE_DEFAULTS: Readonly<{
+    springLength: 10;
+    springCoefficient: 0.8;
+    gravity: -12;
+    dragCoefficient: 0.9;
+    timeStep: 0.5;
+    dim: 2;
+    scale: 1;
+    settleThreshold: 0.001;
+    settleWindow: 10;
+    iterationsPerStep: 1;
+    maxInFlight: 2;
+}> = Object.freeze({
+    springLength: 10,
+    springCoefficient: 0.8,
+    gravity: -12,
+    dragCoefficient: 0.9,
+    timeStep: 0.5,
+    dim: 2,
+    scale: 1,
+    settleThreshold: 0.001,
+    settleWindow: 10,
+    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

@@ -7,20 +7,24 @@
  * ForceSimulation, ForceAtlas2Model: tests import them from their files). P0: the error class, the constants and
  * 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. 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
+ * tables, the seeder and the layout / accelerator types. P5 adds the two factories, the two default tables and the
+ * 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.
  */
 
-// ==================== constants and errors (P0; FA2_DEFAULTS / LAYOUT_TUNING_DEFAULTS public from P3)
+// ==================== constants and errors (P0; FA2_DEFAULTS / LAYOUT_TUNING_DEFAULTS public from P3, FR_DEFAULTS /
+// SE_DEFAULTS from P5)
 export {
     ARC_WINDOW_ALIGN,
     EXACT_MAX_NODES,
     FA2_DEFAULTS,
+    FR_DEFAULTS,
     LAYOUT_TUNING_DEFAULTS,
     MAX_1D_ITEMS,
     MAX_WORKGROUPS_PER_DIM,
+    SE_DEFAULTS,
     STORAGE_ALIGN,
     WORKGROUP_SIZE,
 } from "./constants.js";
@@ -37,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";
 
@@ -45,10 +54,13 @@ 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)
+// ==================== 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";
+export { createSpringElectrical } from "./layouts/spring-electrical.js";
 
 // ==================== types: the accelerator surface and the re-exported declarations of @graphty/layout (spec 9.3)
 // and @graphty/algorithms (spec 9.2), both `import type` since W1b (D27)
@@ -91,6 +103,8 @@ export type {
 export type {
     AdapterInfoLike,
     AdapterSummary,
+    DeviceCheck,
+    DeviceCheckMismatch,
     GpuCaps,
     GpuContextOptions,
     LimitPolicy,
@@ -101,14 +115,20 @@ export type {
     RaisableLimit,
 } from "./types/context.js";
 
-// ==================== types: layouts (P3)
+// ==================== types: layouts (P3; the P5 stats and trace records; the P4 calibration records)
 export type {
+    CalibrateOptions,
     ForceAtlas2Stats,
     ForceAtlas2TraceRecord,
+    FruchtermanReingoldStats,
+    FruchtermanReingoldTraceRecord,
+    GpuCalibration,
     GpuLayoutSimulation,
     GpuLayoutTuning,
     LayoutStatsBase,
     RunOptions,
+    SpringElectricalStats,
+    SpringElectricalTraceRecord,
 } from "./types/layout.js";
 export type {
     CommonLayoutOptions,

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);
 }
 
 /**

package/src/kernel/kernel.ts

@@ -2,7 +2,8 @@
  * Kernel (spec 5.1; contract 3.9): a compiled pipeline bound to the binding list of its spec. `bind()` creates the
  * bind groups from a `Record<name, Binding>` keyed by the declared names and caches them by the identity of the
  * buffers, offsets and sizes (a layout's bind groups are created once per load(), not per iteration); `dispatch()`
- * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6).
+ * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6); `dispatchIndirect()`
+ * (P4, spec 5.4) records the same prefix and a dispatchWorkgroupsIndirect over one 16-byte slot of an args buffer.
  */
 
 import { STORAGE_ALIGN } from "../constants.js";
@@ -21,6 +22,9 @@ export interface BoundKernel {
     readonly dynamicGroups: readonly number[];
 }
 
+/** Bytes of one indirect args slot: (x, y, 1, count) as four u32 (spec 5.4; P4 PD-2). */
+export const INDIRECT_ARGS_STRIDE = 16;
+
 /** Buffer identities for the bind-group cache key: every GPUBuffer seen by any Kernel gets one number, once. */
 const bufferIds = new WeakMap<GPUBuffer, number>();
 let nextBufferId = 1;
@@ -259,6 +263,50 @@ export class Kernel {
         plan: DispatchPlan,
         dynamicOffsets?: readonly number[],
     ): void {
+        this.check(bound, dynamicOffsets);
+        if (plan.x === 0) {
+            return;
+        }
+        this.setUp(pass, bound, dynamicOffsets);
+        pass.dispatchWorkgroups(plan.x, plan.y, 1);
+    }
+
+    /**
+     * setPipeline + the bind groups exactly as dispatch(), then dispatchWorkgroupsIndirect(args.buffer, args.offset +
+     * INDIRECT_ARGS_STRIDE * slot) (spec 5.4): the (x, y, 1) of the slot were written by the indirect-finalize kernel
+     * earlier in the same pass. A slot beyond the binding is E_INVALID_ARGUMENT.
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of THIS kernel
+     * @param args - the args buffer range (usage INDIRECT | STORAGE)
+     * @param slot - the 16-byte slot index inside the range
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
+     */
+    dispatchIndirect(
+        pass: GPUComputePassEncoder,
+        bound: BoundKernel,
+        args: Binding,
+        slot: number,
+        dynamicOffsets?: readonly number[],
+    ): void {
+        this.check(bound, dynamicOffsets);
+        if (!Number.isInteger(slot) || slot < 0 || (slot + 1) * INDIRECT_ARGS_STRIDE > args.size) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${this.spec.id}: args slot ${slot} is outside the binding`, {
+                argument: "slot",
+                value: slot,
+                expected: `0 <= slot < ${Math.floor(args.size / INDIRECT_ARGS_STRIDE)}`,
+            });
+        }
+        this.setUp(pass, bound, dynamicOffsets);
+        pass.dispatchWorkgroupsIndirect(args.buffer, args.offset + INDIRECT_ARGS_STRIDE * slot);
+    }
+
+    /**
+     * The argument checks dispatch() and dispatchIndirect() share: a BoundKernel of another kernel or an offset list
+     * of the wrong length is E_INVALID_ARGUMENT.
+     * @param bound - the bound kernel
+     * @param dynamicOffsets - the offsets, if any
+     */
+    private check(bound: BoundKernel, dynamicOffsets: readonly number[] | undefined): void {
         const { id } = this.spec;
         if (bound.kernel !== this) {
             throw new WebGpuGraphError(
@@ -282,9 +330,16 @@ export class Kernel {
                 },
             );
         }
-        if (plan.x === 0) {
-            return;
-        }
+    }
+
+    /**
+     * setPipeline + setBindGroup for every group (the dynamic offsets replicated over the uniform bindings of each
+     * dynamic group), the prefix dispatch() and dispatchIndirect() share.
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of this kernel
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups (absent = 0)
+     */
+    private setUp(pass: GPUComputePassEncoder, bound: BoundKernel, dynamicOffsets: readonly number[] | undefined): void {
         pass.setPipeline(this.pipeline);
         let next = 0;
         bound.bindGroups.forEach((bindGroup, group) => {
@@ -301,7 +356,6 @@ export class Kernel {
                 pass.setBindGroup(group, bindGroup);
             }
         });
-        pass.dispatchWorkgroups(plan.x, plan.y, 1);
     }
 
     /** Drops cached bind groups (a layout's buffers changed). */

package/src/kernel/prelude.ts

@@ -15,8 +15,15 @@ import {
     FA2_COINCIDENT_SQ,
     FA2_DISTANCE_FLOOR,
     FA2_DISTANCE_FLOOR_SQ,
+    FA2_FLAG_ADAPTIVE,
     FA2_FLAG_FIRST,
+    FR_COOLING_PATIENCE,
+    FR_COOLING_STEP,
+    GRID_BBOX_MARGIN,
+    GRID_EXTENT_FLOOR,
+    GRID_HUB_CELL,
     MAX_WORKGROUPS_PER_DIM,
+    RADIX_BINS,
     U32_MAX,
     WORKGROUP_SIZE,
 } from "../constants.js";
@@ -49,6 +56,14 @@ const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
 const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};
 const FA2_FLAG_FIRST: u32 = ${FA2_FLAG_FIRST}u;
+const FA2_FLAG_ADAPTIVE: u32 = ${FA2_FLAG_ADAPTIVE}u;
+const FR_COOLING_STEP: f32 = ${wgslF32Literal(FR_COOLING_STEP)};
+const FR_COOLING_PATIENCE: u32 = ${FR_COOLING_PATIENCE}u;
+const GRID_HUB_CELL: u32 = ${GRID_HUB_CELL}u;
+const GRID_EXTENT_FLOOR: f32 = ${wgslF32Literal(GRID_EXTENT_FLOOR)};
+const GRID_BBOX_MARGIN: f32 = ${wgslF32Literal(GRID_BBOX_MARGIN)};
+const RADIX_BINS: u32 = ${RADIX_BINS}u;
+const RADIX_DIGIT_MASK: u32 = ${RADIX_BINS - 1}u;
 const F32_MAX: f32 = 0x1.fffffep+127;
 override WG: u32 = ${WORKGROUP_SIZE}u;
 override USE_PERM: bool = false;

package/src/kernel/profiler.ts

@@ -4,8 +4,10 @@
  * every CommandBatch pass; `resolveInto(batch)` records the resolve plus a copy into the batch's
  * staging slot and `timings(bytes, request)` decodes `{ label, ns }` per pass from the batch's
  * readback bytes. Chromium quantises timestamps to 100 us (`quantised: true`); Dawn-node reports
- * 1,024 ns ticks (spec 2.6). The profiler never throws: a full query set drops timings and a device
- * without the feature disables it. Slot pairs are handed out in order and the cursor restarts at 0
+ * 1,024 ns ticks (spec 2.6). The profiler never throws: a full query set drops the timings of the
+ * passes past the budget and marks the batch's request `partial(request)` so a caller summing the
+ * rows into a duration falls back to wall time; a device without the feature disables it. Slot
+ * pairs are handed out in order and the cursor restarts at 0
  * after every resolve: queue order guarantees the resolve of batch A reads its slots before batch B
  * overwrites them, and one resolve buffer suffices for the same reason.
  */
@@ -36,8 +38,10 @@ export class Profiler {
     private readonly querySet: GPUQuerySet | null;
     private readonly resolveBuffer: GPUBuffer | null;
     private readonly labels = new WeakMap<ReadbackRequest, readonly string[]>();
+    private readonly partialRequests = new WeakSet<ReadbackRequest>();
     private pending: PendingPass[] = [];
     private cursor = 0;
+    private refused = 0;
     private destroyed = false;
 
     /**
@@ -69,12 +73,17 @@ export class Profiler {
     }
 
     /**
-     * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots.
+     * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots. A pass refused for
+     * want of slots is counted, and the next `resolveInto()` marks its request partial.
      * @param label - the pass name reported by `timings()`
      * @returns the descriptor a CommandBatch puts on beginComputePass, or undefined
      */
     beginPass(label: string): GPUComputePassTimestampWrites | undefined {
-        if (this.querySet === null || this.destroyed || this.cursor + 2 > this.slots) {
+        if (this.querySet === null || this.destroyed) {
+            return undefined;
+        }
+        if (this.cursor + 2 > this.slots) {
+            this.refused++;
             return undefined;
         }
         const begin = this.cursor;
@@ -100,11 +109,25 @@ export class Profiler {
             request,
             this.pending.map((pass) => pass.label),
         );
+        if (this.refused > 0) {
+            this.partialRequests.add(request);
+        }
         this.pending = [];
         this.cursor = 0;
+        this.refused = 0;
         return request;
     }
 
+    /**
+     * Whether a pass of the batch was refused a slot pair, so `timings()` covers only its first slots / 2 passes
+     * and their sum is not the batch's duration.
+     * @param request - the request `resolveInto()` returned
+     * @returns true when at least one pass of that batch went untimed
+     */
+    partial(request: ReadbackRequest): boolean {
+        return this.partialRequests.has(request);
+    }
+
     /**
      * Decodes the timings of a batch from its readback bytes.
      * @param bytes - the resolved readback of the batch
@@ -138,6 +161,7 @@ export class Profiler {
         this.destroyed = true;
         this.pending = [];
         this.cursor = 0;
+        this.refused = 0;
         if (this.querySet !== null) {
             this.querySet.destroy();
         }