@graphty/webgpu-graph-algorithms 0.6.14 → 0.6.16

package/src/types/structure.ts

@@ -0,0 +1,28 @@
+/**
+ * The result record of triangle counting (design 3.3 line 828, 8.5; design 17 line 5067). Design 3.3 declares
+ * `{ perNode, total }`; this package also returns the clustering coefficient and the transitivity, because they are
+ * an epilogue over the counts and degrees the call already holds and nothing else in the monorepo computes them.
+ * Types only.
+ */
+
+import type { F32, U32 } from "@graphty/graph-format";
+
+/**
+ * Triangle counting over the simple undirected graph underlying the snapshot: arc directions are ignored, parallel
+ * edges count once and self-loops not at all, so a directed snapshot and its undirected twin give the same answer.
+ * @public
+ */
+export interface GpuTriangleResult {
+    /** The triangles each node lies in. */
+    readonly perNode: U32;
+    /** The triangles of the graph (each counted once). */
+    readonly total: number;
+    /**
+     * The local clustering coefficient of every node, `2 T(v) / (d(v) (d(v) - 1))` with `d` the node's number of
+     * distinct neighbours. It is 0 -- a defined value, not a missing one -- for a node with fewer than two
+     * neighbours, so a star graph returns all zeros.
+     */
+    readonly coefficient: F32;
+    /** The graph's transitivity, `3 x triangles / connected triples`; 0 when the graph has no connected triple. */
+    readonly transitivity: number;
+}

package/src/wgsl/apsp-fw.wgsl.ts

@@ -0,0 +1,112 @@
+/**
+ * The `apsp-fw` kernel body (design 8.7): one phase of one round of blocked Floyd-Warshall over `APSP_TILE x
+ * APSP_TILE` blocks of the row-major `n x n` matrix `dist`. Round `r` (`P.round`) runs three dispatches in order,
+ * the `PHASE` override choosing which:
+ *
+ * - PHASE 0, one workgroup: the pivot block `(r, r)`, staged in `tileA` and updated in place.
+ * - PHASE 1, `2 (B - 1)` workgroups (`B` = `P.blocks`): every other block of block row `r` (the first `B - 1`
+ *   workgroups) and of block column `r` (the rest). The pivot block is staged in `tileA`, the block itself in
+ *   `tileB`, updated in place.
+ * - PHASE 2, `(B - 1)^2` workgroups: every block `(i, j)` off the pivot row and column. Its two operands are the
+ *   pivot-COLUMN block `(i, r)` in `tileA` and the pivot-ROW block `(r, j)` in `tileB`; its own cells are read,
+ *   minimised over the 32 steps and written by one lane each, never shared, so they stay in registers.
+ *
+ * In-place updates are race-free because a cell is written only when the candidate is STRICTLY smaller: the cells
+ * every lane reads in step `k` (column `k` and row `k` of the tile) would be updated with `d + d[k][k]`, and the
+ * diagonal is `0` (weights are non-negative, which the driver checks) or `+Infinity` outside the matrix, so they are
+ * never written in step `k`. Every barrier is reached in uniform control flow: the early return keys on the workgroup
+ * id and uniforms only, the per-lane loops hold no barrier, and the lanes of an edge tile load `+Infinity` for a cell
+ * outside `n x n` (it offers no path; read from `P.infBits` because Tint refuses `+Infinity` as a constant) and
+ * store nothing there -- the matrix is exactly `n * n`, never padded, so the
+ * ceiling is `floor(sqrt(maxStorageBufferBindingSize / 4))`. Body only (spec 3.5, D9); the text is normative: the
+ * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const apspFwWgsl = /* wgsl */ `
+var<workgroup> tileA: array<f32, APSP_TILE * APSP_TILE>;
+var<workgroup> tileB: array<f32, APSP_TILE * APSP_TILE>;
+
+fn tile_row(block: vec2<u32>, c: u32) -> u32 { return block.x * APSP_TILE + c / APSP_TILE; }
+fn tile_col(block: vec2<u32>, c: u32) -> u32 { return block.y * APSP_TILE + c % APSP_TILE; }
+
+fn load_cell(block: vec2<u32>, c: u32) -> f32 {
+    let i = tile_row(block, c);
+    let j = tile_col(block, c);
+    if (i < P.n && j < P.n) { return dist[i * P.n + j]; }
+    return bitcast<f32>(P.infBits);                                   // outside the matrix: no path through it
+}
+
+fn store_cell(block: vec2<u32>, c: u32, v: f32) {
+    let i = tile_row(block, c);
+    let j = tile_col(block, c);
+    if (i >= P.n || j >= P.n) { return; }                            // an edge tile stores nothing outside n x n
+    dist[i * P.n + j] = v;
+}
+
+@compute @workgroup_size(WG)
+fn apsp_fw(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let g = group_id(wid);
+    let r = P.round;
+    let others = max(P.blocks, 2u) - 1u;                             // the blocks of a strip, the pivot excluded
+    let cells = APSP_TILE * APSP_TILE;
+    var count = 1u;
+    var own = vec2<u32>(r, r);                                        // the block this workgroup updates
+    var a = vec2<u32>(r, r);                                          // staged in tileA
+    var b = vec2<u32>(r, r);                                          // staged in tileB
+    if (PHASE == 1u) {
+        count = 2u * others;
+        let s = g % others;
+        let o = select(s, s + 1u, s >= r);                            // a strip skips the pivot block
+        own = select(vec2<u32>(o, r), vec2<u32>(r, o), g < others);   // block row r first, then block column r
+        b = own;
+    }
+    if (PHASE == 2u) {
+        count = others * others;
+        let i = g / others;
+        let j = g % others;
+        own = vec2<u32>(select(i, i + 1u, i >= r), select(j, j + 1u, j >= r));
+        a = vec2<u32>(own.x, r);                                      // the pivot-column block (i, r)
+        b = vec2<u32>(r, own.y);                                      // the pivot-row block (r, j)
+    }
+    if (g >= count) { return; }                                       // uniform: the workgroup id and uniforms only
+
+    for (var c = lid.x; c < cells; c = c + WG) {
+        tileA[c] = load_cell(a, c);
+        if (PHASE != 0u) { tileB[c] = load_cell(b, c); }
+    }
+    workgroupBarrier();                                               // every staged cell is visible
+
+    if (PHASE == 2u) {
+        for (var c = lid.x; c < cells; c = c + WG) {
+            let x = c / APSP_TILE;
+            let y = c % APSP_TILE;
+            var v = load_cell(own, c);
+            for (var kr = 0u; kr < APSP_TILE; kr = kr + 1u) {
+                v = min(v, tileA[x * APSP_TILE + kr] + tileB[kr * APSP_TILE + y]);
+            }
+            store_cell(own, c, v);
+        }
+        return;
+    }
+
+    let pivotRow = PHASE == 1u && own.x == r;                          // block row r reads d[x][k] from the pivot
+    for (var k = 0u; k < APSP_TILE; k = k + 1u) {
+        for (var c = lid.x; c < cells; c = c + WG) {
+            let x = c / APSP_TILE;
+            let y = c % APSP_TILE;
+            if (PHASE == 0u) {
+                let via = tileA[x * APSP_TILE + k] + tileA[k * APSP_TILE + y];
+                if (via < tileA[c]) { tileA[c] = via; }
+            } else {
+                let left = select(tileB[x * APSP_TILE + k], tileA[x * APSP_TILE + k], pivotRow);
+                let right = select(tileA[k * APSP_TILE + y], tileB[k * APSP_TILE + y], pivotRow);
+                let via = left + right;
+                if (via < tileB[c]) { tileB[c] = via; }
+            }
+        }
+        workgroupBarrier();                                           // step k is complete before step k + 1 reads
+    }
+    for (var c = lid.x; c < cells; c = c + WG) {
+        store_cell(own, c, select(tileB[c], tileA[c], PHASE == 0u));
+    }
+}
+`;

package/src/wgsl/apsp-init.wgsl.ts

@@ -0,0 +1,25 @@
+/**
+ * The `apsp-init` kernel body (design 8.7): writes the arcs into the `n x n` distance matrix after `fill` has set
+ * every entry to `+Infinity`. One lane per ROW `u`: it walks `u`'s arcs and keeps the cheapest weight per target
+ * (`min`), so parallel arcs collapse to the cheapest one, then writes the diagonal zero LAST, so a self-loop never
+ * displaces it. Every arc of row `u` lands in row `u` of the matrix and only this lane writes that row, so there is
+ * no race and no atomic. Unweighted (`HAS_WEIGHTS` false) every arc costs 1. A directed snapshot writes its one
+ * direction; an undirected one stores both arcs of every edge, so both halves are written. The driver refuses
+ * negative and non-finite weights before any dispatch. Body only (spec 3.5, D9); the text is normative: the
+ * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const apspInitWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn apsp_init(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let u = linear_id(wid, lid.x);
+    if (u >= P.n) { return; }
+    let rowBase = u * P.n;
+    let end = rowPtr[u + 1u];
+    for (var a = rowPtr[u]; a < end; a = a + 1u) {
+        let v = colIdx[a];
+        let w = select(1.0, weights[a], HAS_WEIGHTS);
+        dist[rowBase + v] = min(dist[rowBase + v], w);               // parallel arcs collapse to the cheapest
+    }
+    dist[rowBase + u] = 0.0;                                          // last: a self-loop never displaces the zero
+}
+`;

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

@@ -0,0 +1,33 @@
+/**
+ * The `bc-backward` kernel body (design 8.4 "each (w, s) PULLS over its successors", 8.10 "BC backward (successor
+ * pull)"): one level of a betweenness batch's dependency accumulation, one invocation per log entry `(w, s)` of the
+ * level's range `S[P.start .. P.start + P.count)`, which the host planned from the `ends` it read back. Each entry
+ * walks the out-arcs of `w` -- the rows the forward pass expanded -- and sums `sigma[s][w] / sigma[s][v] * (1 +
+ * delta[s][v])` over the successors `v` (`depth[s][v] == depth[s][w] + 1`), whose dependencies the previous (deeper)
+ * dispatch wrote, then writes `delta[s][w]` ONCE. No float is ever accumulated through an atomic, so the result is
+ * bitwise reproducible. The sources (depth 0) are never dispatched: their dependency stays 0, which is what keeps a
+ * source's own dependency out of its score. Grid-stride loop (`P.stride`). ponytail: one lane walks one row, so a
+ * vertex of degree above 65,535 exceeds llvmpipe's per-invocation loop cap (CLAUDE.md, Verified Platform Facts) and
+ * would need a workgroup-per-row form there; hardware adapters have no such cap. Body only; the sabotage rows of
+ * test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bcBackwardWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bc_backward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    for (var i = linear_id(wid, lid.x); i < P.count; i = i + P.stride) {
+        let t = S[P.start + i];                                      // s * n + w
+        let w = t % P.n;
+        let base = t - w;                                            // s * n
+        let succ = depthK[t] + 1u;
+        let sw = f32(sigmaK[t]);
+        var acc = 0.0;
+        for (var a = rowPtr[w]; a < rowPtr[w + 1u]; a = a + 1u) {
+            let v = base + colIdx[a];
+            if (depthK[v] == succ) {                                 // v is a successor of w for source s
+                acc = acc + (sw / f32(sigmaK[v])) * (1.0 + deltaK[v]);
+            }
+        }
+        deltaK[t] = acc;                                             // written once per (w, s)
+    }
+}
+`;

package/src/wgsl/bc-edge-gather.wgsl.ts

@@ -0,0 +1,35 @@
+/**
+ * The `bc-edge-gather` kernel body (design 8.4 "edge BC accumulates per arc from the same n x k deltas"): the per-arc
+ * twin of `bc-gather`, run once per batch after the backward sweep. One invocation per ARC (`P.count` arcs,
+ * grid-stride): it finds the row `w` that owns the arc by an upper-bound search over `rowPtr`, then adds over the
+ * batch's sources in order the term the backward pass summed -- `sigma[s][w] / sigma[s][v] * (1 + delta[s][v])`
+ * whenever `w` was reached and `depth[s][v] == depth[s][w] + 1` -- into `arcScores[arc]`. Each arc is written by one
+ * invocation: no atomic, a fixed order. Arc-parallel rather than row-parallel so a hub row is not one lane's loop
+ * (llvmpipe caps a shader loop at 65,535 iterations, and a 1,000-arc hub times 64 sources passed it). Body only;
+ * the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bcEdgeGatherWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bc_edge_gather(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    for (var a = linear_id(wid, lid.x); a < P.count; a = a + P.stride) {
+        var lo = 0u;                                                 // the row w with rowPtr[w] <= a < rowPtr[w + 1]
+        var hi = P.n;
+        loop {
+            if (lo >= hi) { break; }
+            let mid = (lo + hi) / 2u;
+            if (rowPtr[mid + 1u] <= a) { lo = mid + 1u; } else { hi = mid; }
+        }
+        let w = lo;
+        let nbr = colIdx[a];
+        var acc = arcScores[a];
+        for (var s = 0u; s < P.k; s = s + 1u) {
+            let base = s * P.n;
+            let dw = depthK[base + w];
+            if (dw != INVALID_INDEX && depthK[base + nbr] == dw + 1u) {   // (w, nbr) is on a shortest path from s
+                acc = acc + (f32(sigmaK[base + w]) / f32(sigmaK[base + nbr])) * (1.0 + deltaK[base + nbr]);
+            }
+        }
+        arcScores[a] = acc;
+    }
+}
+`;

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

@@ -0,0 +1,46 @@
+/**
+ * The `bc-finalize` kernel body (design 8.4, 5.4): the one-lane bookkeeping of a betweenness source batch, two roles
+ * by `P.role`. The batch keeps ONE append-only claim log `S` -- every `(vertex, source)` pair the forward pass
+ * claims, packed as the index `s * n + v` into the `n x k` arrays -- and `ends`, the level boundaries into it: the
+ * entries at depth `L` are `S[ends[L] .. ends[L + 1])`. That log is Brandes' stack, so the backward pass walks the
+ * same ranges from the deepest level up and nothing is ever copied between levels.
+ *
+ * Role 1 seeds the batch: the k seed entries the host wrote into `S[0 .. k)` get depth 0 and one shortest path,
+ * `ends[0] = 0`, the append cursor `stackTop` (counters word 26) starts at k, the overflow flag (word 27) is cleared,
+ * `level` (word 11) is U32_MAX so the first boundary lands on 0, and `done` (word 15) is cleared.
+ *
+ * Role 0 is the level boundary, recorded before every forward level: it advances `level`, closes the level just
+ * claimed by writing `ends[level + 1] = stackTop`, publishes the new level's size in `frontierCount` (word 0) and sets
+ * `done` when that level is empty. A boundary that finds `done` set moves nothing, so the levels the host records
+ * past the end are no-ops. The forward kernels dispatch directly and read their range from `ends` (no indirect
+ * dispatch: design/decisions/2026-09-25-frontier-kernels-dispatch-directly.md). One lane; no barrier follows the
+ * early return of the others (spec 3.5 rule 1). Body only; the sabotage rows of test/helpers/sabotage.ts are
+ * textual edits of it.
+ */
+export const bcFinalizeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bc_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x != 0u) { return; }                                     // one lane; no barrier follows (3.5 rule 1)
+    if (P.role == 1u) {                                              // the seed of a batch
+        for (var i = 0u; i < P.k; i = i + 1u) {
+            let t = S[i];
+            depthK[t] = 0u;                                          // the source is at depth 0
+            sigmaK[t] = 1u;                                          // with one shortest path, itself
+        }
+        ends[0] = 0u;
+        atomicStore(&counters[26], P.k);                             // stackTop: the seeds are the log's first k entries
+        atomicStore(&counters[27], 0u);                              // sigmaOverflow
+        atomicStore(&counters[11], U32_MAX);                         // level: the first boundary brings it to 0
+        atomicStore(&counters[15], 0u);                              // done
+        return;
+    }
+    if (atomicLoad(&counters[15]) != 0u) { return; }                 // done: a no-op level the host recorded past the end
+    let level = atomicLoad(&counters[11]) + 1u;
+    let top = atomicLoad(&counters[26]);
+    ends[level + 1u] = top;                                          // the level's entries end where the log ends now
+    let count = top - ends[level];
+    atomicStore(&counters[0], count);                                // frontierCount (the inspect seam reads it)
+    atomicStore(&counters[11], level);
+    atomicStore(&counters[15], select(0u, 1u, count == 0u));         // an empty level ends the batch
+}
+`;

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

@@ -0,0 +1,75 @@
+/**
+ * The `bc-forward-edge` kernel body (design 8.4 "the McLaughlin-Bader online switch to the edge-parallel form", 8.8
+ * row 7): one level of a betweenness batch's forward pass, edge-parallel -- every logical edge of the `edgeList` view
+ * for every source of the batch, grid-striding over the edges inside a loop over the k sources. For the edge `(u, x)`
+ * and source `s`, when `depth[s][u]` is the level the edge is relaxed toward `x` with EXACTLY the claim and the count
+ * of `bc-forward` (the pre-check, `atomicMin`, the winner appends `s * n + x` to the same claim log, every arc on a
+ * shortest path adds `sigma[s][u]`, a u32 wrap raises word 27); `UNDIRECTED` relaxes the other direction too, the
+ * edge list holding each undirected edge once. So the two forward bodies are interchangeable level by level and the
+ * backward pass cannot tell which ran. A workgroup does nothing when the level is empty (the done boundary). The
+ * winners of a strip are packed into the log with one global `atomicAdd` per strip; every barrier is in uniform
+ * control flow (the loop bounds are uniforms and the workgroup id). Body only; the sabotage rows of
+ * test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bcForwardEdgeWgsl = /* wgsl */ `
+var<workgroup> wlive: u32;                        // 1 when the level has entries
+var<workgroup> wwon: atomic<u32>;                 // the strip's winners
+var<workgroup> wbase: u32;                        // where the strip's winners go in the log
+
+fn claim(x: u32, next: u32) -> bool {
+    if (atomicLoad(&depthK[x]) != INVALID_INDEX) { return false; }   // the pre-check of design 16.1
+    return atomicMin(&depthK[x], next) == INVALID_INDEX;
+}
+
+fn count_paths(origin: u32, x: u32, next: u32) {
+    if (atomicLoad(&depthK[x]) == next) {                            // every arc on a shortest path adds
+        let add = atomicLoad(&sigmaK[origin]);
+        let old = atomicAdd(&sigmaK[x], add);
+        if (old + add < old) { atomicOr(&counters[27], 1u); }        // the u32 wrap, reported
+    }
+}
+
+@compute @workgroup_size(WG)
+fn bc_forward_edge(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let level = atomicLoad(&counters[11]);
+    if (lid.x == 0u) { wlive = select(0u, 1u, ends[level + 1u] > ends[level]); }
+    if (workgroupUniformLoad(&wlive) == 0u) { return; }              // uniform: nothing below runs on an empty level
+    let next = level + 1u;
+    for (var s = 0u; s < P.k; s = s + 1u) {
+        let base = s * P.n;
+        for (var e0 = group_id(wid) * WG; e0 < P.count; e0 = e0 + P.stride) {   // grid-stride over the edges
+            let e = e0 + lid.x;
+            var a = INVALID_INDEX;                                   // the claims this lane won
+            var b = INVALID_INDEX;
+            if (e < P.count) {
+                let u = base + edgeSrc[e];
+                let x = base + edgeDst[e];
+                if (atomicLoad(&depthK[u]) == level) {
+                    if (claim(x, next)) { a = x; }
+                    count_paths(u, x, next);
+                }
+                if (UNDIRECTED) {                                    // the other direction of an undirected edge
+                    if (atomicLoad(&depthK[x]) == level) {
+                        if (claim(u, next)) { b = u; }
+                        count_paths(x, u, next);
+                    }
+                }
+            }
+            let mine = select(0u, 1u, a != INVALID_INDEX) + select(0u, 1u, b != INVALID_INDEX);
+            var slot = 0u;
+            if (mine != 0u) { slot = atomicAdd(&wwon, mine); }
+            workgroupBarrier();
+            if (lid.x == 0u) {
+                wbase = atomicAdd(&counters[26], atomicLoad(&wwon));   // stackTop: one global atomic per strip
+                atomicStore(&wwon, 0u);
+            }
+            workgroupBarrier();
+            if (a != INVALID_INDEX) {
+                S[wbase + slot] = a;
+                slot = slot + 1u;
+            }
+            if (b != INVALID_INDEX) { S[wbase + slot] = b; }
+        }
+    }
+}
+`;

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

@@ -0,0 +1,105 @@
+/**
+ * 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
+ * in workgroup memory, and every lane strips the aggregate by an upper-bound binary search), fused with the claim, so
+ * no edge queue exists.
+ *
+ * For the arc `(u, x)` of the entry `(u, s)`, with `t = s * n + x`: the CLAIM -- a relaxed pre-check that skips the
+ * atomic when `t` is already claimed (design 16.1: a stale "unclaimed" costs one redundant atomic, a stale "claimed"
+ * cannot happen because a claim is never revoked), then `atomicMin(&depthK[t], level + 1)`, the invocation that
+ * observes INVALID_INDEX the unique winner, which appends `t` to the log; and, as a SEPARATE condition, the COUNT:
+ * every arc that reaches `t` at `level + 1` adds `sigma[s][u]` into `sigma[s][x]`, winner or not, which is what makes
+ * sigma the number of shortest paths rather than of claims. The add detects a u32 wrap from `atomicAdd`'s return
+ * value (`old + add < old`) and raises `sigmaOverflow` (counters word 27); the count is never clamped. The winners of
+ * a strip are packed into the log with one workgroup-memory counter and ONE global `atomicAdd` on `stackTop` (word
+ * 26) per strip. Uniformity (spec 3.5 rule 1): the range and the aggregate are `workgroupUniformLoad`s and the strip
+ * loop steps a uniform `p0`, so every barrier is in uniform control flow. The order of the log inside a level is
+ * not deterministic; nothing downstream depends on it (the counts are integers and every dependency is written by
+ * index). Body only; the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bcForwardWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;                // the block's degrees, then their inclusive scan
+var<workgroup> rowStart: array<u32, WG>;          // the first arc of each entry's row
+var<workgroup> entryOf: array<u32, WG>;           // each entry, s * n + u
+var<workgroup> wstart: u32;                       // the level's first log index
+var<workgroup> wcount: u32;                       // the level's entry count
+var<workgroup> wwon: atomic<u32>;                 // the strip's winners
+var<workgroup> wbase: u32;                        // where the strip's winners go in the log
+
+@compute @workgroup_size(WG)
+fn bc_forward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let level = atomicLoad(&counters[11]);
+    if (lid.x == 0u) {
+        let lo = ends[level];
+        wstart = lo;
+        wcount = ends[level + 1u] - lo;
+    }
+    let start = workgroupUniformLoad(&wstart);
+    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers
+    let next = level + 1u;
+    for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries
+        let i = b0 + lid.x;
+        var deg = 0u;
+        var first = 0u;
+        var entry = 0u;
+        if (i < count) {                                             // guarded loads into locals (3.5 rule 1)
+            entry = S[start + i];
+            let u = entry % P.n;
+            first = rowPtr[u];
+            deg = rowPtr[u + 1u] - first;
+        }
+        sh[lid.x] = deg;
+        rowStart[lid.x] = first;
+        entryOf[lid.x] = entry;
+        workgroupBarrier();
+        for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan of the degrees
+            var t = 0u;
+            if (lid.x >= s) { t = sh[lid.x - s]; }
+            workgroupBarrier();
+            sh[lid.x] = sh[lid.x] + t;
+            workgroupBarrier();
+        }
+        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);          // uniform; includes a barrier
+        for (var p0 = 0u; p0 < aggregate; p0 = p0 + WG) {            // strip [0, aggregate) WG arcs at a time
+            let p = p0 + lid.x;
+            var won = false;
+            var claimed = 0u;
+            if (p < aggregate) {
+                var lo = 0u;                                         // upper_bound: the first k with sh[k] > p owns arc p
+                var hi = WG;
+                loop {
+                    if (lo >= hi) { break; }
+                    let mid = (lo + hi) / 2u;
+                    if (sh[mid] > p) { hi = mid; } else { lo = mid + 1u; }
+                }
+                let k = lo;
+                var exclusive = 0u;
+                if (k > 0u) { exclusive = sh[k - 1u]; }
+                let origin = entryOf[k];                             // s * n + u
+                let x = (origin - (origin % P.n)) + colIdx[rowStart[k] + (p - exclusive)];   // s * n + x
+                if (atomicLoad(&depthK[x]) == INVALID_INDEX) {       // the pre-check of design 16.1
+                    won = atomicMin(&depthK[x], next) == INVALID_INDEX;   // the claim: the one winner appends
+                }
+                if (atomicLoad(&depthK[x]) == next) {                // the count: EVERY arc on a shortest path adds
+                    let add = atomicLoad(&sigmaK[origin]);
+                    let old = atomicAdd(&sigmaK[x], add);
+                    if (old + add < old) { atomicOr(&counters[27], 1u); }   // the u32 wrap, reported
+                }
+                claimed = x;
+            }
+            var slot = 0u;
+            if (won) { slot = atomicAdd(&wwon, 1u); }
+            workgroupBarrier();
+            if (lid.x == 0u) {
+                wbase = atomicAdd(&counters[26], atomicLoad(&wwon));   // stackTop: one global atomic per strip
+                atomicStore(&wwon, 0u);
+            }
+            workgroupBarrier();
+            if (won) { S[wbase + slot] = claimed; }
+        }
+        workgroupBarrier();                                          // sh, rowStart and entryOf are reused by the next block
+    }
+}
+`;

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

@@ -0,0 +1,19 @@
+/**
+ * The `bc-gather` kernel body (design 8.4 "one gather kernel after the batch's last backward level", 8.10 "BC
+ * gather"): one invocation per vertex `w`, `bc[w] += delta[0][w] + ... + delta[k - 1][w]` in source order -- k reads,
+ * one write, no atomic, a fixed summation order, so the scores are bitwise reproducible across runs and adapters.
+ * A source's own dependency is 0 (the backward pass never visits depth 0), so nothing is skipped here. Grid-stride
+ * loop (`P.stride`). Body only; the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bcGatherWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bc_gather(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    for (var w = linear_id(wid, lid.x); w < P.n; w = w + P.stride) {
+        var acc = bc[w];
+        for (var s = 0u; s < P.k; s = s + 1u) {
+            acc = acc + deltaK[s * P.n + w];
+        }
+        bc[w] = acc;
+    }
+}
+`;

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

@@ -10,6 +10,9 @@
  * level 0's parity is 0), `flags[source_s] = 1` (level 0's `compact` turns the flags into the list; a seeded list
  * would be overwritten by a compaction of all-zero flags), `counters[0] = k` (not done) and `level = U32_MAX` (so
  * level 0's boundary accumulates nothing and brings the word to 0, and level 1's counts the distance-1 claims at 1).
+ * Role 2 is role 1 for a sampled run: source `s` of the batch is word `P.source + s` of the source list the host
+ * wrote after the per-node sums (`perSource[128 + P.bitsBase + ...]`), `P.n` is the list's length, and a node listed
+ * twice in one batch carries both bits (the seed ORs, so a duplicate runs twice).
  * No barrier follows the early return of the other lanes (3.5 rule 1). Body only (spec 3.5, D9); the text is
  * normative: the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
  */
@@ -17,13 +20,14 @@ export const closenessReduceWgsl = /* wgsl */ `
 @compute @workgroup_size(WG)
 fn closeness_reduce(@builtin(local_invocation_id) lid: vec3<u32>) {
     if (lid.x != 0u) { return; }                                     // one lane; no barrier follows (3.5 rule 1)
-    if (P.role == 1u) {                                              // the seed of a batch: P.source is its first source
+    if (P.role != 0u) {                                              // the seed of a batch: P.source is its first source
         let k = min(32u, P.n - P.source);
         for (var s = 0u; s < k; s = s + 1u) {
-            let v = P.source + s;
+            var v = P.source + s;
+            if (P.role == 2u) { v = atomicLoad(&perSource[128u + P.bitsBase + P.source + s]); }   // a sampled run's list
             let bit = 1u << s;
-            bits[v] = bit;                                           // visited
-            bits[P.bitsBase + v] = bit;                              // the frontier level 0 reads (region 1: level 0's parity is 0)
+            bits[v] = bits[v] | bit;                                 // visited
+            bits[P.bitsBase + v] = bits[P.bitsBase + v] | bit;       // the frontier level 0 reads (region 1: level 0's parity is 0)
             bits[3u * P.bitsBase + v] = 1u;                          // flags: level 0's compact turns them into the list
         }
         atomicStore(&counters[0], k);                                // not done

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

@@ -13,7 +13,9 @@
  * error), and are tallied per source in WORKGROUP memory -- one global `atomicAdd` per source per workgroup after the
  * strip loop, never one per arc. Uniformity (spec 3.5 rule 1): the guarded loads write locals, the scan and the
  * `workgroupUniformLoad` sit unconditionally after the guard, the strip loop is bounded by the uniform aggregate, and
- * the flush's barrier follows it in uniform control flow. Body only (spec 3.5, D9); the text is normative: the
+ * the flush's barrier follows it in uniform control flow. A sampled run (`P.perNode == 1`) also adds each claim's
+ * distance (`level + 1`, one per won bit) into the per-node sum of `x`, `perSource[128 + x]`: the distance from each
+ * of the batch's sources TO `x`, which is what a node's sampled closeness sums on an undirected graph. Body only (spec 3.5, D9); the text is normative: the
  * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
  */
 export const closenessSweepWgsl = /* wgsl */ `
@@ -22,11 +24,16 @@ var<workgroup> rowStart: array<u32, WG>;          // the first bound arc of each
 var<workgroup> rowOf: array<u32, WG>;             // the frontier vertex of each entry (the source end of its arcs)
 var<workgroup> local: array<atomic<u32>, 32>;     // this workgroup's fresh claims per source
 var<workgroup> wcount: u32;                       // the frontier list's length
+var<workgroup> wdist: u32;                        // the distance of this level's claims
 
 @compute @workgroup_size(WG)
 fn closeness_sweep(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
-    if (lid.x == 0u) { wcount = atomicLoad(&counters[0]); }          // the frontier list's length (compact's total)
+    if (lid.x == 0u) {
+        wcount = atomicLoad(&counters[0]);                           // the frontier list's length (compact's total)
+        wdist = atomicLoad(&counters[11]) + 1u;                      // the level word: this level claims at level + 1
+    }
     let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers
+    let dist = workgroupUniformLoad(&wdist);
     let nextBase = select(2u * P.bitsBase, P.bitsBase, P.mode == 1u);   // the region that is next this level
     let frontierBase = 3u * P.bitsBase - nextBase;                   // the other one: the region that is the frontier
     for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries
@@ -74,6 +81,9 @@ fn closeness_sweep(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocat
                 if (fresh != 0u) {
                     atomicOr(&bits[nextBase + x], fresh);
                     atomicStore(&bits[3u * P.bitsBase + x], 1u);         // flags: x is in the next frontier list (compact reads it)
+                    if (P.perNode == 1u) {                               // a sampled run: x's distance to each source won
+                        atomicAdd(&perSource[128u + x], countOneBits(fresh) * dist);
+                    }
                     var b = fresh;
                     loop {                                               // one tally per set bit of fresh
                         if (b == 0u) { break; }

package/src/wgsl/coo-emit.wgsl.ts

@@ -0,0 +1,32 @@
+/**
+ * The `coo-emit` kernel body (design 6 row 10, 8.6; the first step of the simple symmetric graph build): position `i`
+ * takes arc `a` -- `i` itself, or `order[i]` under INDEXED, which is how a sorted permutation is materialised -- and
+ * writes that arc's source, target and weight. Arc `2e` is logical edge `e` as declared and arc `2e + 1` its reverse,
+ * so every edge lands in both directions and the result is symmetric whatever the snapshot's directedness. A
+ * self-loop is dropped: both of its arcs are written as `INVALID_INDEX`, which sorts after every node index and which
+ * `run-flags` never marks. Weights are 1 without WEIGHTED. Body only (spec 3.5, D9); normative text.
+ */
+export const cooEmitWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn coo_emit(@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
+    var a = i;
+    if (INDEXED) { a = order[i]; }                                 // the arc this position takes
+    let e = a / 2u;                                                // arc 2e is edge e as declared, arc 2e + 1 its reverse
+    let forward = (a % 2u) == 0u;
+    let u = edgeSrc[e];
+    let v = edgeDst[e];
+    var w = 1.0;
+    if (WEIGHTED) { w = edgeWeight[e]; }
+    if (u == v) {                                                  // a self-loop is dropped: both arcs sort last and never open a run
+        outSrc[i] = INVALID_INDEX;
+        outDst[i] = INVALID_INDEX;
+        outWeight[i] = 0.0;
+        return;
+    }
+    outSrc[i] = select(v, u, forward);
+    outDst[i] = select(u, v, forward);
+    outWeight[i] = w;
+}
+`;

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

@@ -0,0 +1,31 @@
+/**
+ * The `coo-scatter` kernel body (design 6 row 10): the last step of `cooToCsr`, after the histogram of the sources
+ * and its exclusive scan into `rowPtr`. Two modes under SORTED_INPUT.
+ *
+ * SORTED_INPUT false is the design's cursor scatter: an arc reserves its slot with `atomicAdd` on its row's cursor
+ * (`cursors`, zeroed by the caller), so slots are handed out in race order and a row is NOT sorted by target even when
+ * the input was.
+ *
+ * SORTED_INPUT true takes arcs already ordered by source: arc `i` then sits at its own index minus its row's start
+ * inside the row, no cursor and no atomic, so the write is a pure function of the input and the input order survives
+ * into every row. The precondition is checked, not trusted: an arc whose source is below its predecessor's raises
+ * `cursors[0]`, the word the driver reads back and refuses. Body only (spec 3.5, D9); normative text.
+ */
+export const cooScatterWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn coo_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 s = src[i];
+    var slot = 0u;
+    if (SORTED_INPUT) {
+        if (i > 0u && s < src[i - 1u]) { atomicStore(&cursors[0], 1u); }   // unsorted input: the flag the driver refuses
+        let within = i - rowPtr[s];                                // the arc's place in its row
+        slot = rowPtr[s] + within;
+    } else {
+        slot = rowPtr[s] + atomicAdd(&cursors[s], 1u);             // race order: the row is not sorted in this mode
+    }
+    colIdx[slot] = dst[i];
+    if (WEIGHTED) { outWeight[slot] = weight[i]; }
+}
+`;