@graphty/webgpu-graph-algorithms 0.6.26 → 0.6.28

package/src/primitives/grid-pyramid.ts

@@ -1,23 +1,26 @@
 /**
  * The grid pyramid (spec 6 row 12, 7.7 G4-G5; P4-T9): the planner that records, into the caller's pass, the finest
  * centroids (G4, `grid-centroid`: thread per cell over `cells + outsideCells`, the pseudo-cells included), the hub-cell
- * completion (G4a: the T1 `indirect-finalize` over `hubCounters[0]` into `hubArgs` with `wg = 1`, so the finalize's
- * `ceil(count / wg)` is ONE workgroup per hub cell; G4b: `grid-centroid-hub`, one workgroup per hub cell, dispatched
- * indirectly; PD-13, DEP-P4-I) and one `grid-downsample` dispatch per coarser
- * level (G5). Level 0 holds `[sum m x, sum m y, sum m z, sum m]` per cell; every parent is the sum of its 2^dim
+ * completion (G4b: `grid-centroid-hub`, one workgroup per hub cell; PD-13) and one `grid-downsample` dispatch per
+ * coarser level (G5). G4b is a DIRECT dispatch of one workgroup per word of `hubList` -- the most hub cells the graph
+ * can hold -- and the kernel's `h < hubCount[0]` guard idles the workgroups past the count. It was an indirect
+ * dispatch from a finalize-written args slot until issue #732: Dawn validates every indirect dispatch with a hidden
+ * pass that cost 0.3 to 0.9 ms of device time per iteration, several times the whole grid tier's own work at 10k
+ * nodes (the frontier kernels' lesson, docs/decisions/G8.md G8-F5). The idle workgroups cost far less: `hubList` holds
+ * `ceil(n / GRID_HUB_CELL)` words, so 977 workgroups at 1M nodes, each reading one word. Level 0 holds `[sum m x, sum m y, sum m z, sum m]` per cell; every parent is the sum of its 2^dim
  * children; the pseudo-cells (indices `cells ..` of level 0) are never children. No atomics touch the sums (design 6 row 12:
  * bitwise reproducible); the only atomics are the hub append and the occupancy max.
  *
- * The named grid buffers (`pyramid`, `hubList`, `hubCounters`, `hubArgs`) are the caller's (the model's
- * `BufferSpec`s, so `inspect(name)` reaches them); the static params of the finalize and of every level are written
+ * The named grid buffers (`pyramid`, `hubList`, `hubCounters`) are the caller's (the model's
+ * `BufferSpec`s, so `inspect(name)` reaches them); the static params of every level are written
  * ONCE at bind() through the scope's params writer (PD-11), so record() writes no uniform. `src/primitives/**` never
  * imports `src/context.ts`.
  */
 
 import { WebGpuGraphError } from "../errors.js";
-import { type DispatchPlan, plan1d } from "../kernel/dispatch.js";
+import { plan1d, plan2d } from "../kernel/dispatch.js";
 import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
-import { GRID_LEVEL_PARAMS, INDIRECT_PARAMS, kernelSpec } from "../kernels.js";
+import { GRID_LEVEL_PARAMS, kernelSpec } from "../kernels.js";
 import { type Binding } from "../types/memory.js";
 import { type GridSpec } from "./grid.js";
 import { type ReduceScope } from "./reduce.js";
@@ -38,39 +41,37 @@ export interface GridPyramidBindings {
     readonly cellStart: Binding;
     /** `pyramidCells` vec4f: every level, level 0 first with the 2^dim orthant pseudo-cells from index `cells`. */
     readonly pyramid: Binding;
-    /** The hub cells' indices, appended by G4 (at least one word; at most `floor(n / (GRID_HUB_CELL + 1))` are ever written, so `ceil(n / GRID_HUB_CELL)` words always suffice). */
+    /** The hub cells' indices, appended by G4 (at least one word; at most `floor(n / (GRID_HUB_CELL + 1))` are ever written, so `ceil(n / GRID_HUB_CELL)` words always suffice). Its word count is G4b's workgroup count. */
     readonly hubList: Binding;
     /** Two u32 (bound whole, at least 8 bytes): `[0]` the hub count, `[1]` the largest cell occupancy; the caller zeroes both before every build (K1, T10). */
     readonly hubCounters: Binding;
-    /** One 16-byte indirect args slot with the INDIRECT usage: G4a writes it, G4b dispatches from it. */
-    readonly hubArgs: Binding;
 }
 
-/** Where `record()` stops: after level 0 is whole (G4, G4a and G4b) or after every coarser level (G5, the default). */
+/** Where `record()` stops: after level 0 is whole (G4 and G4b) or after every coarser level (G5, the default). */
 export type GridPyramidStage = "G4" | "G5";
 
 /** A prepared pyramid build (spec 7.7 G4-G5): binds once per load, records the stages of one iteration into a pass. */
 export interface GridPyramidPlanner {
     /**
-     * Binds the named buffers and writes the static params of the finalize and of every level (PD-11); called once
+     * Binds the named buffers and writes the static params of every level (PD-11); called once
      * per load (a second call rebinds and writes fresh params, so it belongs to a reload, never to an iteration).
      * @param bindings - the buffers
      */
     bind(bindings: GridPyramidBindings): void;
     /**
-     * Records G4, G4a, G4b and then G5 for every coarser level at the `Fa2Params` slot `paramsOffset`; `upTo: "G4"`
-     * stops after G4b (level 0 is whole: G4a and G4b are G4's completion).
+     * Records G4, G4b and then G5 for every coarser level at the `Fa2Params` slot `paramsOffset`; `upTo: "G4"`
+     * stops after G4b (level 0 is whole: G4b is G4's completion).
      * @param pass - the compute pass
      * @param paramsOffset - the dynamic offset of this iteration's `Fa2Params`
      * @param upTo - the last stage to record (default "G5")
      */
     record(pass: GPUComputePassEncoder, paramsOffset: number, upTo?: GridPyramidStage): void;
-    /** Dispatches the last record() issued: 3 after `upTo: "G4"`, `3 + (levels - 1)` for a full record. */
+    /** Dispatches the last record() issued: 2 after `upTo: "G4"`, `2 + (levels - 1)` for a full record. */
     readonly lastDispatches: number;
 }
 
 /**
- * Prepares the pyramid's pipelines over a scope (G4, the finalize, G4b and G5; compiles once) so bind() and record()
+ * Prepares the pyramid's pipelines over a scope (G4, G4b and G5; compiles once) so bind() and record()
  * are synchronous. The planner lives exactly as long as the scope.
  * @param scope - the caller's scope (device, caps, cache, scratch, params)
  * @param spec - the grid
@@ -78,31 +79,28 @@ export interface GridPyramidPlanner {
  */
 export async function preparePyramid(scope: ReduceScope, spec: GridSpec): Promise<GridPyramidPlanner> {
     const centroid = await scope.pipelines.kernel(kernelSpec("grid-centroid"));
-    const finalize = await scope.pipelines.kernel(kernelSpec("indirect-finalize"));
     const hub = await scope.pipelines.kernel(kernelSpec("grid-centroid-hub"));
     const downsample = await scope.pipelines.kernel(kernelSpec("grid-downsample"));
-    return new GridPyramidPlannerImpl(scope, spec, { centroid, finalize, hub, downsample });
+    return new GridPyramidPlannerImpl(scope, spec, { centroid, hub, downsample });
 }
 
-/** The four kernels of the build. */
+/** The three kernels of the build. */
 interface Kernels {
     readonly centroid: Kernel;
-    readonly finalize: Kernel;
     readonly hub: Kernel;
     readonly downsample: Kernel;
 }
 
 /** What bind() prepared: the bound groups and, per coarser level, its bound group with its params offset. */
 interface Bound {
-    readonly hubArgs: Binding;
     readonly centroid: BoundKernel;
-    readonly finalize: BoundKernel;
-    readonly finalizeOffset: number;
     readonly hub: BoundKernel;
+    /** G4b's workgroups: one per word of `hubList`. */
+    readonly hubSlots: number;
     readonly levels: readonly { readonly bound: BoundKernel; readonly offset: number; readonly parentCells: number }[];
 }
 
-/** The planner: G4, G4a, G4b and G5 over one scope. */
+/** The planner: G4, G4b and G5 over one scope. */
 class GridPyramidPlannerImpl implements GridPyramidPlanner {
     private readonly scope: ReduceScope;
     private readonly spec: GridSpec;
@@ -114,7 +112,7 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
      * Wraps the resolved kernels; use preparePyramid().
      * @param scope - the caller's scope
      * @param spec - the grid
-     * @param kernels - the four kernels
+     * @param kernels - the three kernels
      */
     constructor(scope: ReduceScope, spec: GridSpec, kernels: Kernels) {
         this.scope = scope;
@@ -135,15 +133,9 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
      * @param bindings - the buffers
      */
     bind(bindings: GridPyramidBindings): void {
-        const { centroid, finalize, hub, downsample } = this.kernels;
+        const { centroid, hub, downsample } = this.kernels;
         const { spec, scope } = this;
         const b = bindings;
-        const finalizeParams = scope.params(INDIRECT_PARAMS, {
-            countIndex: 0,
-            wg: 1, // the finalize plans ceil(count / wg) workgroups over ITEMS; G4b's item is a hub cell, one workgroup each
-            slot: 0,
-            pad0: 0,
-        });
         const levels: { readonly bound: BoundKernel; readonly offset: number; readonly parentCells: number }[] = [];
         let parentSide = spec.g;
         for (let level = 0; level + 1 < spec.levels; level++) {
@@ -166,7 +158,6 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
             });
         }
         this.bound = {
-            hubArgs: b.hubArgs,
             centroid: centroid.bind({
                 sortedIdx: b.sortedIdx,
                 cellStart: b.cellStart,
@@ -176,8 +167,6 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
                 hubCounters: b.hubCounters,
                 P: b.params,
             }),
-            finalize: finalize.bind({ counters: b.hubCounters, args: b.hubArgs, P: finalizeParams.binding }),
-            finalizeOffset: finalizeParams.offset,
             hub: hub.bind({
                 sortedIdx: b.sortedIdx,
                 cellStart: b.cellStart,
@@ -187,6 +176,7 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
                 hubCount: b.hubCounters,
                 P: b.params,
             }),
+            hubSlots: Math.floor(b.hubList.size / 4),
             levels,
         };
     }
@@ -202,13 +192,11 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
         if (bound === null) {
             throw new WebGpuGraphError("E_NOT_LOADED", "gridPyramid: record() before bind()", { argument: "bind" });
         }
-        const { centroid, finalize, hub, downsample } = this.kernels;
-        const one: DispatchPlan = { x: 1, y: 1, z: 1, items: 1, stride: null };
+        const { centroid, hub, downsample } = this.kernels;
         const level0 = spec.cells + spec.outsideCells;
         centroid.dispatch(pass, bound.centroid, plan1d(level0, scope.workgroupSize, scope.caps), [paramsOffset]);
-        finalize.dispatch(pass, bound.finalize, one, [bound.finalizeOffset]);
-        hub.dispatchIndirect(pass, bound.hub, bound.hubArgs, 0, [paramsOffset]);
-        this.dispatches = 3;
+        hub.dispatch(pass, bound.hub, plan2d(bound.hubSlots, scope.caps), [paramsOffset]);
+        this.dispatches = 2;
         if ((upTo ?? "G5") === "G4") {
             return;
         }

package/src/types/accelerator.ts

@@ -130,6 +130,8 @@ export interface AcceleratorOptions {
  */
 export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator {
     readonly kind: "webgpu";
+    /** `closenessCentrality` honours `harmonic` on an exact run, so the CPU dispatcher sends harmonic closeness here. */
+    readonly harmonicCloseness: true;
     readonly ctx: GpuContext;
     readonly options: Readonly<AcceleratorOptions>;
     forceAtlas2(options?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats>;

package/src/types/managed.ts

@@ -0,0 +1,86 @@
+/**
+ * The types of `acquireAccelerator` (the `./acquire` subpath, and the same function on `./browser` and `./node`):
+ * one call that finds a device, checks that it computes correctly and hands back an accelerator, or says why it
+ * did not. Types only.
+ */
+
+import type { AcceleratorOptions, GpuAccelerator } from "./accelerator.js";
+import type { AdapterSummary, DeviceCheck } from "./context.js";
+
+/**
+ * Options of `acquireAccelerator`.
+ * @public
+ */
+export interface AcquireAcceleratorOptions {
+    /**
+     * Accept a software adapter (llvmpipe, SwiftShader, WARP). Default false: a software adapter is usually slower
+     * than a CPU implementation, so it is declined with `E_SOFTWARE_ONLY`.
+     */
+    readonly acceptSoftware?: boolean | undefined;
+    /** The adapter power preference; default "high-performance". */
+    readonly powerPreference?: GPUPowerPreference | undefined;
+    /** Passed to `createAccelerator` (layout tuning, betweenness defaults). */
+    readonly accelerator?: AcceleratorOptions | undefined;
+    /** Warn once when more than this many snapshots stay resident on the device (the context's default when absent). */
+    readonly warnUnreleasedSnapshots?: number | undefined;
+    /** Node only: a substring of the Dawn adapter name to pick (`"llvmpipe"`, `"4070"`). Ignored in a browser. */
+    readonly adapter?: string | undefined;
+}
+
+/**
+ * A verified accelerator.
+ * @public
+ */
+export interface AcceleratorReady {
+    readonly ok: true;
+    readonly code: "OK";
+    /** The accelerator. Its `ctx.lost` resolves when the device is lost; the handle then acquires a new one. */
+    readonly accelerator: GpuAccelerator;
+}
+
+/**
+ * Why no accelerator was handed over. Every code here is decided before any work runs, so a caller that has a CPU
+ * implementation runs it and reports the reason; that is detection, not a fallback.
+ * @public
+ */
+export interface AcceleratorDeclined {
+    readonly ok: false;
+    /**
+     * E_NO_WEBGPU: this runtime has no WebGPU (in Node: the optional `webgpu` package is missing);
+     * E_NO_ADAPTER: WebGPU exists but no adapter answered; E_SOFTWARE_ONLY: the adapter is a software renderer and
+     * `acceptSoftware` was not set; E_DEVICE_INCORRECT: the device got a known answer wrong in the self-check.
+     */
+    readonly code: "E_NO_WEBGPU" | "E_NO_ADAPTER" | "E_SOFTWARE_ONLY" | "E_DEVICE_INCORRECT";
+    /** The reason in words. */
+    readonly reason: string;
+    /** What the user can change to get the GPU, or null when nothing they can do would help. */
+    readonly fix: string | null;
+    /** The adapter that was found and declined, when one was. */
+    readonly adapter: AdapterSummary | null;
+    /** The self-check record of an E_DEVICE_INCORRECT decline (what disagreed); null otherwise. */
+    readonly check: DeviceCheck | null;
+}
+
+/**
+ * What `ManagedAccelerator.current()` resolves to.
+ * @public
+ */
+export type AcquireResult = AcceleratorReady | AcceleratorDeclined;
+
+/**
+ * The handle `acquireAccelerator` returns. It owns the device: probing, the device self-check, re-acquiring after
+ * device loss, and disposal.
+ * @public
+ */
+export interface ManagedAccelerator {
+    /**
+     * The accelerator, or why there is none. The first call acquires (probe, context, self-check); later calls
+     * return the same answer until the device is lost or the accelerator is disposed, after which the next call
+     * acquires a new device. Concurrent calls share one acquisition. A decline is remembered for the life of the
+     * handle. Rejects only for a failure that is not a decline (a device request that failed, a check that could not
+     * run), and with E_DISPOSED after `dispose()`.
+     */
+    current(): Promise<AcquireResult>;
+    /** Disposes the current accelerator and its device; idempotent. */
+    dispose(): void;
+}

package/src/wgsl/bc-forward.wgsl.ts

@@ -2,7 +2,7 @@
  * The `bc-forward` kernel body (design 8.4 "forward pass = BFS with sigma as array<atomic<u32>>", 8.10 "BC forward
  * (tagged)", 16.1): one level of the tagged multi-source breadth-first search of a betweenness batch. The level's
  * frontier is the range `S[ends[level] .. ends[level + 1])` of the claim log, every entry a packed `s * n + u`; the
- * expansion is `closeness-sweep`'s block-mapped strip (each workgroup loads up to `WG` entries, scans their degrees
+ * expansion is `advance-expand`'s block-mapped strip (each workgroup loads up to `WG` entries, scans their degrees
  * in workgroup memory, and every lane strips the aggregate by an upper-bound binary search), fused with the claim, so
  * no edge queue exists.
  *

package/src/wgsl/closeness-level.wgsl.ts

@@ -0,0 +1,203 @@
+/**
+ * The `closeness-level` kernel body: one level of the bit-parallel multi-source breadth-first search of closeness, in
+ * ONE dispatch, plus the two seed roles of a batch. A batch runs `32 x P.words` sources at once: bit `b` of word `j`
+ * of node `v` is source lane `32 j + b`. The `bits` buffer holds five regions of `P.base` words, `P.words` words per
+ * node: `visited` at 0, three frontier regions at `P.base`, `2 P.base` and `3 P.base` that rotate by the level
+ * (level `L` reads region `1 + L % 3`, writes region `1 + (L + 1) % 3` and zeroes region `1 + (L + 2) % 3`, the
+ * frontier of level `L - 1` that nothing reads any more, so no fill runs between levels; a stale bit could never
+ * claim anything, since its node's neighbours were claimed the level after, so the clear only keeps a later frontier
+ * from re-walking old nodes), then a sampled run's
+ * per-node distance sums at `4 P.base`. The `table` buffer holds the per-level claim counts of the submit (row `P.row`
+ * at `P.row x 32 P.words`, one word per source lane), then a ring of three control slots of four words at `P.ctrl`
+ * (`any` @0: the level claimed something; `arcs` @1: the out-degree of every (node, word) that joined the next
+ * frontier; `pull` @2: `arcs` passed `P.pullAt`), then a sampled run's source list at `P.sourcesAt`.
+ *
+ * Role 0 (one invocation per node and per arc, `max(n, arcs)` in all): a level whose predecessor claimed nothing
+ * returns at once (one uniform load per workgroup), so the host can record more levels than the batch needs.
+ * Otherwise the level chooses its step from the slot its predecessor filled, the same way for every invocation:
+ *   - PUSH (the frontier is cheap to expand): one invocation per out-arc `(u, x)` -- `u` found by a binary search of
+ *     `rowPtr` -- claims the sources at `u` that `x` has not seen with `atomicOr` on `x`'s visited word; the bits it
+ *     won (`fresh`) join the next frontier;
+ *   - PULL (the frontier's arcs pass `P.pullAt`, and `P.pullOk`): one invocation per node not yet reached by every
+ *     source walks its IN-arcs, ORs the neighbours' frontier words, and keeps the bits it had not seen; it stops at
+ *     the first in-arc after which every source has reached it (the early exit). Only the owner writes a node's
+ *     words. The host allows the pull only when no node has more than a few thousand in-arcs, so no
+ *     invocation of either step loops more than a few tens of thousands of times (llvmpipe silently ends every loop
+ *     of an invocation past 65,535 iterations).
+ * Every claimed bit is tallied per source lane in workgroup memory and flushed with one global `atomicAdd` per lane
+ * per workgroup into the level's row; the host turns the counts into exact sums (`count x (L + 1)`) and harmonic
+ * sums (`count / (L + 1)`). Role 1 (one invocation per word): zeroes the regions, sets every dead lane of a partial
+ * batch as already visited (so the early exit and the "reached by every source" test see a full word), and zeroes the
+ * control ring. Role 2 (one invocation per lane): seeds lane `b`'s source -- `P.source + b`, or word `P.source + b` of
+ * the source list -- into `visited` and level 0's frontier with `atomicOr` (a node listed twice carries both bits),
+ * and fills the control slot level 0 reads. Body only; the text is normative: the sabotage rows of
+ * test/helpers/sabotage.ts are textual edits of it.
+ */
+export const closenessLevelWgsl = /* wgsl */ `
+const max_words: u32 = 8u;
+var<workgroup> tally: array<atomic<u32>, 32u * max_words>;   // 32 x max_words: this workgroup's claims per source lane
+var<workgroup> wlive: u32;
+var<workgroup> wpull: u32;
+var<workgroup> wany: atomic<u32>;
+var<workgroup> warcs: atomic<u32>;
+var<workgroup> wover: atomic<u32>;
+
+fn dead_lanes(j: u32) -> u32 {                        // the lanes of word j at or past the batch's source count
+    let first = 32u * j;
+    if (P.count >= first + 32u) { return 0u; }
+    if (P.count <= first) { return U32_MAX; }
+    return ~((1u << (P.count - first)) - 1u);
+}
+
+fn add_arcs(slot: u32, value: u32) {                  // the arcs total of a control slot; pull once it passes P.pullAt
+    if (value == 0u) { return; }
+    let before = atomicAdd(&table[slot + 1u], value);
+    if (value > P.pullAt || before + value > P.pullAt || before + value < before) {
+        atomicStore(&table[slot + 2u], 1u);
+    }
+}
+
+fn record(j: u32, node: u32, fresh: u32, dist: u32) {   // the claims of one word: tallied per lane, a sampled run's sums
+    if (P.perNode == 1u) { atomicAdd(&bits[4u * P.base + node], countOneBits(fresh) * dist); }
+    var b = fresh;
+    loop {
+        if (b == 0u) { break; }
+        atomicAdd(&tally[32u * j + firstTrailingBit(b)], 1u);
+        b = b & (b - 1u);
+    }
+}
+
+@compute @workgroup_size(WG)
+fn closeness_level(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    let W = P.words;
+    if (P.role == 1u) {                                              // seed, part 1: one invocation per word
+        if (i == 0u) {
+            for (var k = 0u; k < 12u; k = k + 1u) { atomicStore(&table[P.ctrl + k], 0u); }
+        }
+        if (i < P.total) { atomicStore(&bits[i], select(0u, dead_lanes(i % W), i < P.base)); }
+        return;                                                      // uniform: P.role is
+    }
+    if (P.role == 2u) {                                              // seed, part 2: one invocation per source lane
+        if (i < P.count) {
+            var v = P.source + i;
+            if (P.sourcesAt != 0u) { v = atomicLoad(&table[P.sourcesAt + P.source + i]); }
+            let w = v * W + i / 32u;
+            let bit = 1u << (i % 32u);
+            atomicOr(&bits[w], bit);                                 // visited
+            let before = atomicOr(&bits[P.base + w], bit);           // level 0's frontier (region 1)
+            let slot = P.ctrl + 8u;                                  // the slot of "level -1", which level 0 reads
+            atomicStore(&table[slot], 1u);
+            if (before == 0u) { add_arcs(slot, rowPtr[v + 1u] - rowPtr[v]); }
+        }
+        return;
+    }
+
+    // role 0: one level
+    let L = P.level;
+    let prev = P.ctrl + 4u * ((L + 2u) % 3u);
+    let cur = P.ctrl + 4u * (L % 3u);
+    if (lid.x == 0u) {
+        wlive = atomicLoad(&table[prev]);
+        wpull = select(0u, atomicLoad(&table[prev + 2u]), P.pullOk == 1u);
+        atomicStore(&wany, 0u);
+        atomicStore(&warcs, 0u);
+        atomicStore(&wover, 0u);
+    }
+    for (var k = lid.x; k < 32u * W; k = k + WG) { atomicStore(&tally[k], 0u); }
+    let live = workgroupUniformLoad(&wlive);                         // uniform; includes a barrier
+    if (live == 0u) { return; }                                      // the previous level claimed nothing
+    let pull = workgroupUniformLoad(&wpull) == 1u;
+    if (i == 0u) {                                                   // the slot of level L + 1 held level L - 2's
+        let nxt = P.ctrl + 4u * ((L + 1u) % 3u);
+        atomicStore(&table[nxt], 0u);
+        atomicStore(&table[nxt + 1u], 0u);
+        atomicStore(&table[nxt + 2u], 0u);
+    }
+    let frontierBase = P.base * (1u + L % 3u);
+    let nextBase = P.base * (1u + (L + 1u) % 3u);
+    let staleBase = P.base * (1u + (L + 2u) % 3u);
+    let dist = L + 1u;
+    var arcs = 0u;
+    if (i < P.n) {
+        for (var j = 0u; j < W; j = j + 1u) { atomicStore(&bits[staleBase + i * W + j], 0u); }
+    }
+    if (pull) {
+        if (i < P.n) {                                               // one invocation per node: its in-arcs
+            var vis: array<u32, max_words>;
+            var unseen = 0u;
+            for (var j = 0u; j < W; j = j + 1u) {
+                vis[j] = atomicLoad(&bits[i * W + j]);
+                unseen = unseen | ~vis[j];
+            }
+            if (unseen != 0u) {                                      // some source has not reached this node yet
+                var acc: array<u32, max_words>;
+                let end = inRowPtr[i + 1u];
+                for (var a = inRowPtr[i]; a < end; a = a + 1u) {
+                    let u = inColIdx[a];
+                    var missing = 0u;
+                    for (var j = 0u; j < W; j = j + 1u) {
+                        acc[j] = acc[j] | atomicLoad(&bits[frontierBase + u * W + j]);
+                        missing = missing | ~(acc[j] | vis[j]);
+                    }
+                    if (missing == 0u) { break; }                    // every source has reached it: the early exit
+                }
+                let degree = rowPtr[i + 1u] - rowPtr[i];
+                for (var j = 0u; j < W; j = j + 1u) {
+                    let fresh = acc[j] & ~vis[j];
+                    if (fresh != 0u) {
+                        atomicStore(&bits[i * W + j], vis[j] | fresh);
+                        atomicStore(&bits[nextBase + i * W + j], fresh);
+                        arcs = arcs + degree;
+                        record(j, i, fresh, dist);
+                    }
+                }
+            }
+        }
+    } else if (i < P.arcCount) {                                     // one invocation per arc: no row is walked whole
+        var lo = 0u;                                                 // the arc's source: the last row starting at or before it
+        var hi = P.n - 1u;
+        loop {
+            if (lo >= hi) { break; }
+            let mid = (lo + hi + 1u) / 2u;
+            if (rowPtr[mid] <= i) { lo = mid; } else { hi = mid - 1u; }
+        }
+        let u = lo;
+        let x = colIdx[i];
+        for (var j = 0u; j < W; j = j + 1u) {
+            let mask = atomicLoad(&bits[frontierBase + u * W + j]) & ~atomicLoad(&bits[x * W + j]);   // at u, not yet at x
+            if (mask == 0u) { continue; }
+            let fresh = mask & ~atomicOr(&bits[x * W + j], mask);    // the claims this invocation won
+            if (fresh == 0u) { continue; }
+            if (atomicOr(&bits[nextBase + x * W + j], fresh) == 0u) {
+                arcs = arcs + (rowPtr[x + 1u] - rowPtr[x]);
+            }
+            record(j, x, fresh, dist);
+        }
+    }
+    if (arcs > P.pullAt) {
+        atomicStore(&wover, 1u);
+    } else if (arcs != 0u) {
+        let before = atomicAdd(&warcs, arcs);
+        if (before + arcs > P.pullAt || before + arcs < before) { atomicStore(&wover, 1u); }
+    }
+    workgroupBarrier();
+    let row = P.row * 32u * W;
+    for (var k = lid.x; k < 32u * W; k = k + WG) {                   // ONE global atomic per source lane per workgroup
+        let c = atomicLoad(&tally[k]);
+        if (c != 0u) {
+            atomicAdd(&table[row + k], c);
+            atomicStore(&wany, 1u);
+        }
+    }
+    workgroupBarrier();
+    if (lid.x == 0u) {
+        if (atomicLoad(&wany) != 0u) { atomicStore(&table[cur], 1u); }
+        if (atomicLoad(&wover) != 0u) {
+            atomicStore(&table[cur + 2u], 1u);
+        } else {
+            add_arcs(cur, atomicLoad(&warcs));
+        }
+    }
+}
+`;

package/src/wgsl/closeness-rowsum.wgsl.ts

@@ -0,0 +1,41 @@
+/**
+ * The `closeness-rowsum` kernel body: closeness from a finished all-pairs distance matrix, one workgroup per row.
+ * Every lane walks its strided columns of row `r` (the distances FROM `r`), skips the diagonal and every unreachable
+ * entry (`+Infinity`, compared by its bit pattern because WGSL lets a compiler assume no infinities), and adds, by
+ * `P.role`: 0 the hop count as an integer (exact: a row of at most 23,170 hops below 23,170 sums below 2^32), 1 the
+ * f32 distance, 2 its reciprocal (harmonic closeness; a zero distance adds nothing, as in the CPU port). A tree reduction in workgroup memory folds the lanes and lane
+ * 0 writes `out[r]` -- the integer, or the f32 bit pattern. The host turns the row into the score. Body only; the text
+ * is normative: the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const closenessRowsumWgsl = /* wgsl */ `
+var<workgroup> partial: array<u32, WG>;
+
+@compute @workgroup_size(WG)
+fn closeness_rowsum(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let row = group_id(wid);                                         // uniform: one workgroup per row
+    if (row >= P.n) { return; }
+    var whole = 0u;
+    var real = 0.0;
+    for (var c = lid.x; c < P.n; c = c + WG) {
+        let d = dist[row * P.n + c];
+        if (c == row || bitcast<u32>(d) == F32_INF_BITS) { continue; }
+        if (P.role == 0u) {
+            whole = whole + u32(d);
+        } else if (P.role == 1u) {
+            real = real + d;
+        } else if (d > 0.0) {
+            real = real + 1.0 / d;                                    // a zero distance adds nothing, as on the CPU
+        }
+    }
+    partial[lid.x] = select(whole, bitcast<u32>(real), P.role != 0u);
+    for (var s = WG / 2u; s > 0u; s = s / 2u) {
+        workgroupBarrier();
+        if (lid.x < s) {
+            let a = partial[lid.x];
+            let b = partial[lid.x + s];
+            partial[lid.x] = select(a + b, bitcast<u32>(bitcast<f32>(a) + bitcast<f32>(b)), P.role != 0u);
+        }
+    }
+    if (lid.x == 0u) { out[row] = partial[0]; }
+}
+`;

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

@@ -1,6 +1,6 @@
 /**
- * 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
+ * G4b, the `grid-centroid-hub` kernel body (spec 7.7; P4-T9): one workgroup per word of hubList, dispatched
+ * directly (issue #732), so the workgroups past hubCounters[0] idle; 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.
  */