@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/src/primitives/verify.ts

@@ -0,0 +1,249 @@
+/**
+ * The device self-check: one real exclusive scan of known numbers, run once per device before this package
+ * computes anything on it, so a device that returns wrong numbers is refused instead of believed.
+ *
+ * WHY IT EXISTS. On the Windows host lane -- Dawn's D3D12 backend over the Microsoft Basic Render Driver, the
+ * software renderer built into Windows -- every exclusive scan of more than one workgroup came back wrong: a
+ * block total of 1 where 256 belonged, or a second block nothing wrote at all, differing between two runs of
+ * identical code in one job. Everything built on the scan was wrong with it (the histogram, the radix sort, the
+ * grid build and every layout above them, eighteen test files), while every single-block scan and every earlier
+ * primitive stayed right. Three shader repairs failed; copying Microsoft's current redistributable renderer
+ * beside the runner's Node executable made all of it pass untouched. The defect is the driver's, and the danger
+ * to a caller is not a crash but silence: a graph laid out from wrong numbers with no error anywhere.
+ *
+ * WHY IT SCANS RATHER THAN PROBING A CONSTRUCT. An earlier hand-written probe matrix of workgroup constructs
+ * (test/primitives/workgroup-id-probe.test.ts) was measured PASSING on that renderer in the same job in which the
+ * real scan returned the wrong answer, so a copy of the shader's shape is not evidence about the shader. This
+ * check therefore drives the shipped `prepareScan` through the shipped composer and pipeline cache: it tests the
+ * code that runs, and it cannot drift away from it. One scan covers both recorded failures -- a value crossing
+ * `workgroupBarrier` inside a block, and a block total crossing from one dispatch of a compute pass to the next
+ * dispatch that reads it, which is the shape of every driver in this package.
+ *
+ * WHY IT REFUSES RATHER THAN ROUTING AROUND THE DEFECT. See docs/decisions/device-self-check.md: a barrier-free second
+ * implementation was designed and costed, and rejected because it would ship unverified on the only platform it
+ * exists for.
+ *
+ * WHERE IT RUNS. Lazily, at the first compute entry point a caller reaches, memoised per GPUDevice: the
+ * algorithms (degree, connectedComponents, the power-iteration family) and calibrateLayout await it on entry, and
+ * a layout simulation awaits it in the compile-and-bind promise `load()` starts -- the promise every batch and
+ * every debug run already awaits before it may submit. So a caller is covered whether the context was created,
+ * adopted through `create({ device })` or adopted through `GpuContext.from`, and a simulation refuses before its
+ * first iteration without the check sitting on the per-batch path, where an extra await would move the moment a
+ * submission becomes visible to a step() issued in the same tick and so change how the frame loop coalesces.
+ * It deliberately does NOT run in GpuContext.create:
+ * a context that only compiles -- Dawn's null backend, which computes nothing by design -- must stay usable, and
+ * `src/context.ts` may not import a primitive (the layer rule of spec 3.2).
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { UniformRing } from "../kernel/uniform-ring.js";
+import { type CheckedContext, type DeviceCheck, type DeviceCheckMismatch } from "../types/context.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+import { prepareScan } from "./scan.js";
+
+/**
+ * The word written into every output slot before the dispatch, so a word NOTHING wrote is distinguishable from
+ * a word written wrongly. The Windows lane returned this value from the second block, which is how the failure
+ * was read as "the block was never written" rather than "the block was miscomputed".
+ */
+const POISON = 0xdeadbeef;
+
+/** Full workgroups the check scans; one partial workgroup of a single word follows them. */
+const CHECK_BLOCKS = 32;
+
+/** Params slots the scan's levels need (two levels of block scan plus one add-back, with room to spare). */
+const RING_SLOTS = 8;
+
+/** The settled check per device: the one work a second caller never repeats. A rejection is dropped, so a check that failed to RUN is retried. */
+const checked = new WeakMap<GPUDevice, Promise<DeviceCheck>>();
+
+/**
+ * The input word at `i`: 1, 2, 3, ... so no two workgroups have the same block total (all-ones would give every
+ * block the same one, and a block total stored at the wrong index would still read correct -- which is exactly
+ * the Windows symptom) and every output word is a different number.
+ * @param i - the word index
+ * @returns the input value
+ */
+function inputAt(i: number): number {
+    return i + 1;
+}
+
+/**
+ * The verdict: the first output word or total that disagrees with the arithmetic answer, or null when nothing
+ * does. Pure, so test/primitives/verify.test.ts can drive it past a fabricated wrong result and exercise the
+ * refusal without a broken device.
+ * @param words - the `count` output words read back from the device
+ * @param total - the total word read back from the device
+ * @param count - the words scanned
+ * @returns the first disagreement, or null
+ * @internal
+ */
+export function checkScanWords(words: Uint32Array, total: number, count: number): DeviceCheckMismatch | null {
+    let running = 0;
+    for (let i = 0; i < count; i++) {
+        const got = words[i];
+        if (got !== running) {
+            return { where: `out[${String(i)}]`, expected: running, actual: got, poison: got === POISON };
+        }
+        // u32 addition wraps in WGSL, so the host oracle wraps too: at WORKGROUP_SIZE 256 the total cannot
+        // reach 2^32, but a false refusal would deny every device on earth, so it is not left to that constant
+        running = (running + inputAt(i)) >>> 0;
+    }
+    if (total !== running) {
+        return { where: "total", expected: running, actual: total, poison: total === POISON };
+    }
+    return null;
+}
+
+/**
+ * Binds a whole scratch buffer.
+ * @param buffer - the buffer
+ * @param size - the bytes bound
+ * @returns the binding
+ */
+function whole(buffer: GPUBuffer, size: number): Binding {
+    return { buffer, offset: 0, size, window: null };
+}
+
+/**
+ * Runs the check once: one scan of `CHECK_BLOCKS * workgroupSize + 1` words recorded into one compute pass, one
+ * submit, the output and the total read back and verified on the host.
+ *
+ * It never throws for a wrong ANSWER -- that is the returned record's job. A failure of the machinery (a lost
+ * device, a validation error, out of memory) propagates with its own code, so "the driver computes incorrectly"
+ * is never said about a device that merely died.
+ * @param ctx - the context to check
+ * @returns what the check found
+ */
+async function runCheck(ctx: CheckedContext): Promise<DeviceCheck> {
+    const started = performance.now();
+    const wg = ctx.workgroupSize;
+    const count = CHECK_BLOCKS * wg + 1;
+    const bytes = 4 * count;
+    const lease = ctx.pool.lease();
+    const ring = new UniformRing(ctx.device, ctx.allocator, RING_SLOTS, "device-check/ring");
+    try {
+        const scope: ReduceScope = {
+            device: ctx.device,
+            caps: ctx.caps,
+            pipelines: ctx.pipelines,
+            pool: ctx.pool,
+            workgroupSize: wg,
+            scratch: (byteLength, label) => lease.storage(byteLength, `device-check/${label}`),
+            params(block, values) {
+                const slot = ring.reserve(1);
+                ring.write(slot, block, values);
+                return { binding: ring.binding(block), offset: ring.offsetOf(slot) };
+            },
+        };
+        const planner = await prepareScan(scope);
+        const src = lease.storage(bytes, "device-check/src");
+        const out = lease.storage(bytes, "device-check/out");
+        const input = new Uint32Array(count);
+        for (let i = 0; i < count; i++) {
+            input[i] = inputAt(i);
+        }
+        ctx.device.queue.writeBuffer(src, 0, input);
+        ctx.device.queue.writeBuffer(out, 0, new Uint32Array(count).fill(POISON));
+        const encoder = ctx.device.createCommandEncoder({ label: "device-check" });
+        const pass = encoder.beginComputePass({ label: "device-check" });
+        const total = planner.record(pass, whole(src, bytes), count, whole(out, bytes));
+        pass.end();
+        ring.flush();
+        ctx.device.queue.submit([encoder.finish()]);
+        const words = new Uint32Array(await ctx.readback.read(out, bytes));
+        const totalWord = new Uint32Array(
+            await ctx.readback.read(total.binding.buffer, 4, undefined, total.binding.offset + 4 * total.index),
+        );
+        const mismatch = checkScanWords(words, totalWord[0], count);
+        return {
+            check: "exclusive-scan",
+            ok: mismatch === null,
+            workgroupSize: wg,
+            count,
+            blocks: CHECK_BLOCKS,
+            ms: performance.now() - started,
+            vendor: ctx.caps.vendor,
+            architecture: ctx.caps.architecture,
+            description: ctx.caps.description,
+            mismatch,
+        };
+    } finally {
+        ring.destroy();
+        lease.release();
+    }
+}
+
+/**
+ * What this device computed when it was asked for an answer this package already knows, run once per device and
+ * remembered. A caller may await it before committing work to a context; every compute entry point of the
+ * package awaits it too, so the cost is paid once whoever asks first.
+ *
+ * It reports rather than throws, so a caller can ask a device a question without having to catch the answer. The
+ * entry points use `assertDeviceComputes`, which turns a failing report into E_DEVICE_INCORRECT.
+ * @param ctx - the context whose device is checked
+ * @returns the capability record; `ok` false means this device returns wrong numbers
+ */
+export function verifyDevice(ctx: CheckedContext): Promise<DeviceCheck> {
+    const cached = checked.get(ctx.device);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const running = runCheck(ctx).catch((err: unknown) => {
+        // only a settled verdict is worth keeping: a check that could not RUN (a lost device, a transient
+        // out-of-memory) must not answer for the device forever
+        checked.delete(ctx.device);
+        throw err;
+    });
+    checked.set(ctx.device, running);
+    return running;
+}
+
+/**
+ * The guard every compute entry point awaits: resolves on a device that computed the check correctly, throws
+ * E_DEVICE_INCORRECT on one that did not, carrying the first wrong word, what was required there, and the
+ * adapter strings that separate a broken driver from a fixed one.
+ * @param ctx - the context about to be computed on
+ * @internal
+ */
+export async function assertDeviceComputes(ctx: CheckedContext): Promise<void> {
+    const check = await verifyDevice(ctx);
+    const { mismatch } = check;
+    if (mismatch === null) {
+        return;
+    }
+    const adapter = {
+        vendor: check.vendor,
+        architecture: check.architecture,
+        device: ctx.caps.device,
+        description: check.description,
+    };
+    const hint =
+        check.architecture === "warp"
+            ? "this is the Microsoft Basic Render Driver; the Microsoft.Direct3D.WARP redistributable (1.0.21 or newer) beside the host executable computes it correctly"
+            : undefined;
+    const observed = mismatch.poison
+        ? `${mismatch.where} was never written (the ${String(POISON)} the check wrote beforehand survived the dispatch)`
+        : `${mismatch.where} came back as ${String(mismatch.actual)} where ${String(mismatch.expected)} was required`;
+    const message =
+        `this device computes multi-workgroup shaders incorrectly: an exclusive scan of ${String(check.count)} ` +
+        `known numbers is wrong -- ${observed}. Refusing to run: every number this package computed here would ` +
+        `be unreliable. adapter: ${adapter.vendor}/${adapter.architecture} "${adapter.description}"`;
+    throw new WebGpuGraphError(
+        "E_DEVICE_INCORRECT",
+        hint === undefined ? message : `${message}. ${hint}`,
+        {
+            check: check.check,
+            where: mismatch.where,
+            expected: mismatch.expected,
+            actual: mismatch.actual,
+            poison: mismatch.poison,
+            count: check.count,
+            blocks: check.blocks,
+            workgroupSize: check.workgroupSize,
+            adapter,
+            ...(hint === undefined ? {} : { hint }),
+        },
+    );
+}

package/src/types/context.ts

@@ -4,6 +4,7 @@
  * package eslint config). P0-T3 wrote AdapterInfoLike and AdapterSummary; P1-T1 completes the file.
  */
 
+import type { GpuContext } from "../context.js";
 import type { WebGpuGraphError } from "../errors.js";
 
 /** The limits `"raise"` takes from the adapter (spec 2.2); maxComputeWorkgroupsPerDimension is deliberately absent. */
@@ -133,3 +134,58 @@ export interface PlanCaps {
 export interface GpuDebugFlags {
     inspect: boolean;
 }
+
+/**
+ * The context the device self-check runs on. `src/primitives/**` may not name GpuContext (the layer rule of
+ * spec 3.2), and this file may, so the alias is how src/primitives/verify.ts types its argument. It is
+ * GpuContext and nothing else: pass the context you were going to compute on.
+ */
+export type CheckedContext = GpuContext;
+
+/**
+ * The first word a device got wrong in the self-check. `poison` is true when the word still held the
+ * 0xdeadbeef the check wrote before the dispatch, which means NOTHING wrote it -- a different failure from a
+ * word written with the wrong value, and the distinction that made the Windows diagnosis possible.
+ */
+export interface DeviceCheckMismatch {
+    /** Where it was found: `out[<index>]`, or `total`. */
+    readonly where: string;
+    /** The value arithmetic requires there. */
+    readonly expected: number;
+    /** The value the device returned. */
+    readonly actual: number;
+    /** True when `actual` is the poison word the check wrote beforehand: nothing wrote this word. */
+    readonly poison: boolean;
+}
+
+/**
+ * What one device self-check found (spec 3.3): the capability record a caller may read BEFORE it commits work
+ * to a device, through `verifyDevice`. `mismatch === null` (equivalently `ok`) means every one of `count`
+ * output words and the total matched the arithmetic answer; a non-null `mismatch` is the device returning
+ * wrong numbers, which every compute entry point of this package turns into E_DEVICE_INCORRECT.
+ *
+ * It reports one property -- that values crossing a workgroup barrier and block totals crossing dispatches of
+ * one compute pass survive -- and is therefore a refusal mechanism, not a certificate of correctness.
+ */
+export interface DeviceCheck {
+    /** The check that ran; one today, named so a second can be added without changing the shape. */
+    readonly check: "exclusive-scan";
+    /** True when nothing disagreed. */
+    readonly ok: boolean;
+    /** The device's workgroup size (spec 5.1). */
+    readonly workgroupSize: number;
+    /** The words scanned: `blocks * workgroupSize + 1`, so the last workgroup is a partial one. */
+    readonly count: number;
+    /** The full workgroups of the scan (one partial one follows). */
+    readonly blocks: number;
+    /** Wall time of this check in milliseconds, pipeline compile included on the first call. */
+    readonly ms: number;
+    /** caps.vendor of the device that ran it. */
+    readonly vendor: string;
+    /** caps.architecture of the device that ran it. */
+    readonly architecture: string;
+    /** caps.description: the string that separates a broken driver from a fixed one. */
+    readonly description: string;
+    /** The first disagreement, or null when there was none. */
+    readonly mismatch: DeviceCheckMismatch | null;
+}

package/src/types/layout.ts

@@ -137,3 +137,25 @@ export interface ResolvedLayoutTuning {
     readonly extentFactor: number;
     readonly compat: "paper" | "networkx";
 }
+
+/** Spec 2.2 CalibrateOptions, verbatim: the probe sizes of calibrateLayout (default 8k / 16k / 32k / 65k). */
+export interface CalibrateOptions {
+    readonly sizes?: readonly number[] | undefined;
+}
+
+/**
+ * Spec 2.2 GpuCalibration, verbatim: the per-size ms per iteration of both repulsion tiers on the actual device,
+ * `pairsPerSecond` of the exact tier at the largest probed size, `suggestedExactMaxNodes` by the spec 7.8 rule
+ * (the largest probed n with exactMs(n) <= min(4 ms, gridMs(n)), rounded down to a power of two; when NO probed size
+ * qualifies -- the grid tier faster at every probe, or every probe over the budget -- the largest power of two strictly
+ * below the smallest probe, so the exact tier runs at no probed size and a value below floorPow2(min(sizes)) tells the
+ * caller the rule found nothing in the range: src/layouts/calibrate.ts) and the wall time of the whole call (pipeline
+ * compilation included on the first call).
+ */
+export interface GpuCalibration {
+    readonly pairsPerSecond: number;
+    readonly exactMsPerIter: Readonly<Record<number, number>>;
+    readonly gridMsPerIter: Readonly<Record<number, number>>;
+    readonly suggestedExactMaxNodes: number;
+    readonly firstCallMs: number;
+}

package/src/wgsl/counting-scatter.wgsl.ts

@@ -0,0 +1,16 @@
+/**
+ * The `counting-scatter` kernel body (spec 6 row 5; P4-T3): the scatter of a counting sort. `start[k]` is the
+ * exclusive scan of the histogram, `cursor[k]` a zeroed per-bin atomic; an element takes the slot `start[k] +
+ * atomicAdd(&cursor[k], 1u)`. The order inside a bin depends on the schedule (set-deterministic, design 6). Body
+ * only; normative text.
+ */
+export const countingScatterWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn counting_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.count) { return; }                                  // no barrier follows
+    let k = keys[i];
+    let slot = atomicAdd(&cursor[k], 1u);                          // the per-bin cursor (6 row 5)
+    outIndex[start[k] + slot] = i;
+}
+`;

package/src/wgsl/fa2-attraction.wgsl.ts

@@ -1,35 +1,46 @@
 /**
- * K2 of the ForceAtlas2 iteration, `fa2-attraction` (spec 7.5; contract 4.5): the thread-per-row gather of the
- * attraction force over the undirected CSR rows (both arcs present, so the sum is symmetric with no atomics), the
- * linear or linlog law, the optional weights, the distributed-action division by the mass in `pos.w`, written as
- * the FIRST writer of `force` each iteration. P3 ships the thread-per-row tier over `[tierStart, tierEnd)` = `[0, n)`
- * with `USE_PERM = false`; the subgroup / workgroup tiers arrive with P4 (`TIER`). `LAW` (P5, spec 7.20) picks the
- * pair law: 0 = the FA2 text, 1 = Fruchterman-Reingold `d^2 / k` (unfloored), 2 = ngraph's Hooke spring
- * `k_s (d - L)`; under 1 / 2 the models compile `LINLOG = false` and `HAS_WEIGHTS = false`, and the law overwrites
- * `w` so weights are ignored either way.
+ * K2 of the ForceAtlas2 iteration, `fa2-attraction` (spec 7.5; contract 4.5): the gather of the attraction force
+ * over the undirected CSR rows (both arcs present, so the sum is symmetric with no atomics), the linear or linlog
+ * law, the optional weights, the distributed-action division by the mass in `pos.w`, written as the FIRST writer of
+ * `force` each iteration (or combined into it under `P.accumulate`, the windowed pattern of 4.2). The arcs are read
+ * inside the bound window [P.arcBase, P.arcEnd). P4-T5 (PD-6, PD-7) gives it the three degree tiers: TIER 0 is one
+ * row per thread over `[P.tierStart, P.tierEnd)`; TIER 1 is 32 lanes per row over `[P.hiEnd, P.midEnd)` with a
+ * five-step tree in workgroup memory; TIER 2 is one workgroup per row over `[0, P.hiEnd)` through `wg_reduce_vec4`
+ * (hence `needs: ["subgroups"]`); the row is `perm[row]` under USE_PERM. `LAW` (P5, spec 7.20) picks the pair law:
+ * 0 = the FA2 text, 1 = Fruchterman-Reingold `d^2 / k` (unfloored), 2 = ngraph's Hooke spring `k_s (d - L)`; under
+ * 1 / 2 the models compile `LINLOG = false` and `HAS_WEIGHTS = false`, and the law overwrites `w` so weights are
+ * ignored either way.
  *
- * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5) are textual edits of it.
+ * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5, P5-T7, P4-T5 / T6) are
+ * textual edits of it.
+ *
+ * TIER 0 folds its row through `row_force_dense`, a stride-one copy of `row_force`, because the shader compiler
+ * emits `row_force(i, 0u, 1u)` as a call and leaves the stride in a parameter: the loop then walks the row with a
+ * runtime step, which costs the strength-reduced addressing into colIdx / weights and the unrolling that keeps
+ * several loads in flight per thread. TIER 0 runs on every load -- alone when no row reaches degree 32, and over
+ * the low-degree rows, which are most of them, when the tiers are bound. The two folds spell their locals apart
+ * (`arc` / `nbr` / `weight` / `total` against `a` / `j` / `w` / `f`) so that each sabotage row names exactly one
+ * of them.
  */
 
-/** The K2 body: entry point `attraction`; an early return is legal here because no barrier follows (spec 3.5 rule 1). */
+/** The K2 body: entry point `attraction`; the tier bodies are functions called under the uniform `TIER` override, so the barriers of `tiered` are reached in uniform control flow and `tier0`'s early return is legal (spec 3.5 rule 1). */
 export const fa2AttractionWgsl = /* wgsl */ `fn store_force(i: u32, f: vec3f) {
     force[3u * i] = f.x;
     force[3u * i + 1u] = f.y;
     force[3u * i + 2u] = f.z;
 }
-
-@compute @workgroup_size(WG)
-fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
-    let row = linear_id(wid, lid.x) + P.tierStart;
-    if (row >= P.tierEnd) { return; }                          // no barrier follows in this tier (3.5 rule 1)
-    let i = select(row, perm[row], USE_PERM);
+fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn row_node(row: u32) -> u32 { return select(row, perm[row], USE_PERM); }
+fn row_force(i: u32, lane: u32, step: u32) -> vec3f {           // the arcs of row i this lane walks inside the bound window [P.arcBase, P.arcEnd) (4.2)
     let pi = pos[i];                                           // xyz + mass in one load (D23)
+    let a0 = max(rowPtr[i], P.arcBase);
+    let a1 = min(rowPtr[i + 1u], P.arcEnd);
     var f = vec3f(0.0);
-    for (var a = rowPtr[i]; a < rowPtr[i + 1u]; a = a + 1u) {
-        let j = colIdx[a];
+    for (var a = a0 + lane; a < a1; a = a + step) {
+        let j = colIdx[a - P.arcBase];
         if (j == i) { continue; }                              // a self-loop exerts no force
         var w = 1.0;
-        if (HAS_WEIGHTS) { w = weights[a]; }
+        if (HAS_WEIGHTS) { w = weights[a - P.arcBase]; }
         let d = pos[j].xyz - pi.xyz;                           // toward j
         let len = max(length(d), FA2_DIST_FLOOR);
         if (LAW == 1u) { w = length(d) / P.frK; }              // LAW 1 (FR, 7.20): |F| = d^2 / k along d / d, unfloored; the linear select below applies w as is
@@ -37,6 +48,73 @@ fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_i
         let mag = select(w, w * log(1.0 + len) / len, LINLOG); // linear: |F| = w len; linlog: |F| = w log(1 + len)
         f = f + d * mag;
     }
-    if (DISTRIBUTED) { f = f / pi.w; }
+    return f;
+}
+fn row_force_dense(i: u32) -> vec3f {                          // TIER 0's stride-one twin of row_force (see the header)
+    let pi = pos[i];
+    let lo = max(rowPtr[i], P.arcBase);
+    let hi = min(rowPtr[i + 1u], P.arcEnd);
+    var total = vec3f(0.0);
+    for (var arc = lo; arc < hi; arc = arc + 1u) {
+        let k = arc - P.arcBase;                               // the window-local index; this walk is contiguous
+        let nbr = colIdx[k];
+        if (nbr == i) { continue; }                            // a self-loop exerts no force
+        var weight = 1.0;
+        if (HAS_WEIGHTS) { weight = weights[k]; }
+        let d = pos[nbr].xyz - pi.xyz;                         // toward the neighbour
+        let len = max(length(d), FA2_DIST_FLOOR);
+        if (LAW == 1u) { weight = length(d) / P.frK; }         // LAW 1 (FR, 7.20), as in row_force
+        if (LAW == 2u) { weight = P.springCoefficient * (len - P.springLength) / len; }   // LAW 2 (spring), as in row_force
+        let mag = select(weight, weight * log(1.0 + len) / len, LINLOG);
+        total = total + d * mag;
+    }
+    return total;
+}
+fn finish(i: u32, f0: vec3f) {
+    var f = f0;
+    if (DISTRIBUTED) { f = f / pos[i].w; }
+    if (P.accumulate == 1u) { f = f + load_force(i); }         // the windowed loop of 4.2 (arcBase != 0 dispatches after the first)
     store_force(i, f);                                         // overwrites: attraction is the first writer of force each iteration
+}
+fn tier0(wid: vec3<u32>, lane: u32) {                          // TIER 0: one row per thread over [tierStart, tierEnd); no barrier, so the early return is legal (3.5 rule 1)
+    let row = linear_id(wid, lane) + P.tierStart;
+    if (row >= P.tierEnd) { return; }
+    let i = row_node(row);
+    finish(i, row_force_dense(i));
+}
+
+var<workgroup> sh: array<vec3f, WG>;
+
+fn tiered(wid: vec3<u32>, lid: u32) {                          // TIER 1: 32 lanes per row over [hiEnd, midEnd); TIER 2: WG lanes per row over [0, hiEnd) (PD-6, PD-7)
+    let g = group_id(wid);
+    var row = g;
+    var end = P.hiEnd;
+    var lane = lid;
+    var step = WG;
+    if (TIER == 1u) { row = P.hiEnd + g * (WG / 32u) + lid / 32u; end = P.midEnd; lane = lid % 32u; step = 32u; }
+    let valid = row < end;
+    var i = 0u;
+    var f = vec3f(0.0);
+    if (valid) { i = row_node(row); f = row_force(i, lane, step); }
+    if (TIER == 1u) {
+        sh[lid] = f;
+        workgroupBarrier();
+        for (var s = 16u; s >= 1u; s = s / 2u) {                 // the five-step tree over each 32-lane group; every lane runs every step
+            var t = vec3f(0.0);
+            if (lane < s) { t = sh[lid + s]; }
+            workgroupBarrier();
+            sh[lid] = sh[lid] + t;
+            workgroupBarrier();
+        }
+        if (valid && lane == 0u) { finish(i, sh[lid]); }
+    }
+    if (TIER == 2u) {
+        let t = wg_reduce_vec4(vec4f(f, 0.0), lid, 0u);
+        if (valid && lid == 0u) { finish(i, t.xyz); }
+    }
+}
+
+@compute @workgroup_size(WG)
+fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (TIER == 0u) { tier0(wid, lid.x); } else { tiered(wid, lid.x); }
 }`;

package/src/wgsl/fa2-stats-finalize.wgsl.ts

@@ -10,7 +10,11 @@
  * free nodes into `partials.swingTraction.x`) against `S.frEnergy` grows the temperature by 1 / FR_COOLING_STEP after
  * FR_COOLING_PATIENCE consecutive falls and shrinks it by FR_COOLING_STEP on a rise (Yifan Hu 2005, section 3.2);
  * 2 = the spring-electrical kinetic energy K5 folded into `partials.swingTraction.x` (PD-4) into `S.kineticEnergy`
- * and the trace.
+ * and the trace. On the grid tier (`P.gridMax > 0`, P4-T10, PD-14) it also derives the grid frame of the next build
+ * from the fold (`extent = max(min(bboxExtent * GRID_BBOX_MARGIN, extentFactor * rmsRadius), GRID_EXTENT_FLOOR)`,
+ * `cellSize = extent / G`, `gridMin = centroid - extent / 2` with `cellSize` in `.w`, `invCellSize`, `eps = 0.25
+ * cellSize`), copies the previous iteration's pseudo-cell count and occupancy max into the state, and resets the
+ * hub counters; the exact tier writes `gridMax: 0` and binds two dummies, so the block is dead there.
  *
  * This file holds the kernel BODY only (spec 3.5, D9): no bind-group lines and no `override` lines -- the composer
  * emits them from the registry entry in src/kernels.ts (contract 3.10.1). The text is normative (contract 4.5) and
@@ -63,6 +67,23 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
         T[P.iterationIndex].meanDisplacement = S.meanDisplacement;
         T[P.iterationIndex].settledCount = S.settledCount;
         T[P.iterationIndex].iteration = S.iteration;
+        if (P.gridMax > 0u) {                                      // the grid tier (7.7): the robust extent, the cell size, eps, last iteration's counts, the hub counter reset (PD-14)
+            let cells = P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u);
+            if (fold) {
+                let box = (S.max.xyz - S.min.xyz) * GRID_BBOX_MARGIN;
+                var bboxExtent = max(box.x, box.y);
+                if (P.dim == 3u) { bboxExtent = max(bboxExtent, box.z); }
+                let extent = max(min(bboxExtent, P.extentFactor * S.rmsRadius), GRID_EXTENT_FLOOR);   // min(bbox, extentFactor x rms), floored (7.7)
+                let cellSize = extent / f32(P.gridMax);
+                S.gridMin = vec4f(S.centroid.xyz - vec3f(0.5 * extent), cellSize);   // gridMin.w carries cellSize
+                S.invCellSize = 1.0 / cellSize;
+                S.eps = 0.25 * cellSize;
+            }
+            S.outsideGrid = cellHist[cells];                         // the previous iteration's pseudo-cell count (0 after load)
+            S.maxCellOccupancy = atomicLoad(&hubCounters[1]);
+            atomicStore(&hubCounters[0], 0u);
+            atomicStore(&hubCounters[1], 0u);
+        }
         if (STATS_MODE == 1u) {                                    // FR: this iteration's temperature (7.20) into the state and the trace
             if ((P.flags & FA2_FLAG_ADAPTIVE) != 0u) {                // adaptive cooling (Yifan Hu 2005 3.2): tKe is the previous iteration's sum |F|^2 over free nodes
                 if (fold) {

package/src/wgsl/grid-cell-key.wgsl.ts

@@ -0,0 +1,29 @@
+/**
+ * G1, the `grid-cell-key` kernel body (spec 7.7; P4-T8): the finest cell of every node from the state's robust extent,
+ * `floor((p - gridMin) * invCellSize)` (a multiply, correctly rounded everywhere: PD-10), linearised when every axis
+ * is in [0, G) and the outside pseudo-cell `cells` otherwise; `cellVal[i] = i`. The clamp before the floor keeps a
+ * far-away or NaN coordinate out of an out-of-range float-to-int conversion. Body only; normative text.
+ */
+export const gridCellKeyWgsl = /* wgsl */ `
+fn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u); }
+
+@compute @workgroup_size(WG)
+fn grid_cell_key(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.n) { return; }                                      // no barrier follows
+    let cells = grid_cells();
+    let gf = f32(P.gridMax);
+    let q = (pos[i].xyz - S.gridMin.xyz) * S.invCellSize;          // PD-10: never a division
+    let c = vec3<i32>(floor(clamp(q, vec3f(-1.0), vec3f(gf + 1.0))));
+    let g = i32(P.gridMax);
+    var inside = c.x >= 0 && c.x < g && c.y >= 0 && c.y < g;
+    if (P.dim == 3u) { inside = inside && c.z >= 0 && c.z < g; }
+    var key = cells;                                               // the outside pseudo-cell (7.7)
+    if (inside) {
+        key = u32(c.x) + P.gridMax * u32(c.y);
+        if (P.dim == 3u) { key = key + P.gridMax * P.gridMax * u32(c.z); }
+    }
+    cellKey[i] = key;
+    cellVal[i] = i;
+}
+`;

package/src/wgsl/grid-centroid-hub.wgsl.ts

@@ -0,0 +1,28 @@
+/**
+ * G4b, the `grid-centroid-hub` kernel body (spec 7.7; P4-T9): one workgroup per hub cell of hubList, dispatched
+ * indirectly from hubArgs (the T1 finalize over hubCounters[0]); a WG-strided mass-weighted sum reduced by the
+ * prelude's tree. The work is guarded by `valid`, never an early return, so the reduction is uniform (PD-13). Body
+ * only; normative text.
+ */
+export const gridCentroidHubWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn grid_centroid_hub(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let h = group_id(wid);
+    let valid = h < hubCount[0];                                   // a workgroup past the count sums nothing
+    var c = 0u;
+    var start = 0u;
+    var count = 0u;
+    if (valid) {
+        c = hubList[h];
+        start = cellStart[c];
+        count = cellStart[c + 1u] - start;
+    }
+    var acc = vec4f(0.0);
+    for (var k = start + lid.x; k < start + count; k = k + WG) {   // strided over the cell's sorted range
+        let p = pos[sortedIdx[k]];
+        acc = acc + vec4f(p.xyz * p.w, p.w);
+    }
+    let t = wg_reduce_vec4(acc, lid.x, 0u);                        // uniform control flow: 256 -> 1
+    if (valid && lid.x == 0u) { pyramid[c] = t; }
+}
+`;

package/src/wgsl/grid-centroid.wgsl.ts

@@ -0,0 +1,28 @@
+/**
+ * G4, the `grid-centroid` kernel body (spec 7.7; P4-T9): thread per finest cell, the pseudo-cell included; the
+ * mass-weighted position sum of a cell's sorted range in index order (no atomics: deterministic), the largest
+ * occupancy into hubCounters[1], and cells above GRID_HUB_CELL entries appended to hubList for G4b (PD-13). Body
+ * only; normative text.
+ */
+export const gridCentroidWgsl = /* wgsl */ `
+fn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u); }
+
+@compute @workgroup_size(WG)
+fn grid_centroid(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let c = linear_id(wid, lid.x);
+    if (c > grid_cells()) { return; }                              // cells [0, cells]: the pseudo-cell is index cells; no barrier follows
+    let start = cellStart[c];
+    let count = cellStart[c + 1u] - start;
+    atomicMax(&hubCounters[1], count);                             // maxCellOccupancy, read by K1 next iteration
+    if (count > GRID_HUB_CELL) {                                   // a hub cell: G4b sums it (PD-13)
+        hubList[atomicAdd(&hubCounters[0], 1u)] = c;
+        return;
+    }
+    var acc = vec4f(0.0);
+    for (var k = start; k < start + count; k = k + 1u) {           // sorted order: deterministic
+        let p = pos[sortedIdx[k]];
+        acc = acc + vec4f(p.xyz * p.w, p.w);                       // (sum m x, sum m y, sum m z, sum m)
+    }
+    pyramid[c] = acc;
+}
+`;

package/src/wgsl/grid-downsample.wgsl.ts

@@ -0,0 +1,27 @@
+/**
+ * G5, the `grid-downsample` kernel body (spec 7.7; P4-T9): one dispatch per coarser level; every parent cell is the
+ * sum of its 4 (2D) or 8 (3D) children at the level below, read at P.childBase and written at P.parentBase (the
+ * pseudo-cell, index cells of level 0, is never a child). No atomics. Body only; normative text.
+ */
+export const gridDownsampleWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn grid_downsample(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let pc = linear_id(wid, lid.x);                                // the parent cell inside its level
+    if (pc >= P.parentCells) { return; }                           // no barrier follows
+    let side = P.parentSide;
+    let cs = 2u * side;                                            // the child level's side
+    let px = pc % side;
+    let py = (pc / side) % side;
+    let pz = pc / (side * side);
+    var acc = vec4f(0.0);
+    for (var dz = 0u; dz < P.depth; dz = dz + 1u) {
+        for (var dy = 0u; dy < 2u; dy = dy + 1u) {
+            for (var dx = 0u; dx < 2u; dx = dx + 1u) {
+                let child = (2u * px + dx) + cs * ((2u * py + dy) + cs * (2u * pz + dz));
+                acc = acc + pyramid[P.childBase + child];
+            }
+        }
+    }
+    pyramid[P.parentBase + pc] = acc;
+}
+`;