@graphty/webgpu-graph-algorithms 0.6.13 → 0.6.15

package/src/types/accelerator.ts

@@ -12,6 +12,8 @@ import type {
     BetweennessAcceleratorOptions,
     BfsOptions,
     BfsResultLike,
+    ClosenessAcceleratorOptions,
+    ClosenessResultLike,
     CommunityResultLike,
     CorenessResultLike,
     EdgeScoresResultLike,
@@ -31,6 +33,7 @@ import type { GpuContext } from "../context.js";
 import type {
     ComponentsOptions,
     EigenvectorOptions,
+    GpuClosenessResult,
     GpuHitsResult,
     GpuLabelResult,
     GpuPageRankResult,
@@ -39,6 +42,7 @@ import type {
     KatzOptions,
     PageRankOptions,
 } from "./algorithms.js";
+import type { GpuBetweennessResult, GpuEdgeScoresResult } from "./betweenness.js";
 import type {
     ForceAtlas2Stats,
     FruchtermanReingoldStats,
@@ -66,6 +70,8 @@ export type {
     BetweennessAcceleratorOptions,
     BfsOptions,
     BfsResultLike,
+    ClosenessAcceleratorOptions,
+    ClosenessResultLike,
     CommunityResultLike,
     CorenessResultLike,
     EdgeScoresResultLike,
@@ -91,7 +97,8 @@ export interface AcceleratorOptions {
     readonly algorithms?:
         | {
               readonly betweenness?:
-                  { readonly k?: number | undefined; readonly sources?: readonly number[] | undefined } | undefined;
+                  | { readonly k?: number | undefined; readonly sources?: readonly number[] | undefined }
+                  | undefined;
           }
         | undefined;
 }
@@ -106,9 +113,10 @@ export interface AcceleratorOptions {
  * semantics on directed input) under both names the mirror declares; their options parameter stays OPTIONAL, because
  * the mirror declares none and an extra REQUIRED parameter would stop the member satisfying it. The four traversals
  * take the seam's OWN option types (PD-19: `BfsOptions`, `SsspOptions` for both `sssp` and `bellmanFord`,
- * `HitsOptionsLike` for `closenessCentrality`), so a key the CPU dispatcher forwards is exactly a key the GPU reads;
- * `test/types/conformance.test-d.ts` holds each parameter EQUAL to the seam's, not merely assignable. Later phases add
- * one member per shipped algorithm.
+ * `ClosenessAcceleratorOptions` for `closenessCentrality`), so a key the CPU dispatcher forwards is exactly a key the GPU reads;
+ * `test/types/conformance.test-d.ts` holds each parameter EQUAL to the seam's, not merely assignable. The two
+ * betweenness members take the seam's `BetweennessAcceleratorOptions`. Later phases add one member per shipped
+ * algorithm.
  * Exported: implemented by src/accelerator.ts (P3-T3); re-exported from src/index.ts at P3-T3.
  * @public
  */
@@ -120,7 +128,9 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     fruchtermanReingold(
         options?: FruchtermanReingoldOptions,
     ): GpuLayoutSimulation<FruchtermanReingoldOptions, FruchtermanReingoldStats>;
-    springElectrical(options?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats>;
+    springElectrical(
+        options?: SpringElectricalOptions,
+    ): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats>;
     pageRank(s: GraphSnapshot, options?: PageRankOptions): Promise<GpuPageRankResult>;
     personalizedPageRank(
         s: GraphSnapshot,
@@ -135,7 +145,9 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     breadthFirstSearch(s: GraphSnapshot, source: number, options?: BfsOptions): Promise<GpuBfsResult>;
     sssp(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<GpuSsspResult>;
     bellmanFord(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<GpuBellmanFordResult>;
-    closenessCentrality(s: GraphSnapshot, options?: HitsOptionsLike): Promise<GpuScoresResult>;
+    closenessCentrality(s: GraphSnapshot, options?: ClosenessAcceleratorOptions): Promise<GpuClosenessResult>;
+    betweennessCentrality(s: GraphSnapshot, options?: BetweennessAcceleratorOptions): Promise<GpuBetweennessResult>;
+    edgeBetweennessCentrality(s: GraphSnapshot, options?: BetweennessAcceleratorOptions): Promise<GpuEdgeScoresResult>;
     release(s: GraphSnapshot): void;
     dispose(): void;
 }

package/src/types/algorithms.ts

@@ -25,6 +25,11 @@ export interface GpuScoresResult {
     readonly precision: "f32";
 }
 
+/** Closeness scores with the number of sources run: `n` for the exact score, the sample's length for a sampled one. */
+export interface GpuClosenessResult extends GpuScoresResult {
+    readonly sourcesUsed: number;
+}
+
 /** Spec 3.3 line 816: `iterations` is the first iteration whose L1 delta fell below the tolerance (8.2), not the batch boundary. */
 export interface GpuPageRankResult extends GpuScoresResult {
     readonly danglingMass: number;

package/src/types/betweenness.ts

@@ -0,0 +1,38 @@
+/**
+ * The betweenness result records (spec 3.3 lines 833-834). Types only: this file imports nothing at runtime. The
+ * options are the CPU seam's own `BetweennessAcceleratorOptions` (`normalized`, `endpoints`, `sources`, `k`), as the
+ * traversals take the seam's option types.
+ */
+
+import type { F32 } from "@graphty/graph-format";
+
+import type { GpuScoresResult } from "./algorithms.js";
+
+/**
+ * Vertex betweenness (spec 3.3 line 833). A SAMPLED run (`sources` or `k`) returns the UNSCALED sum over the sources
+ * actually run -- never extrapolated by `n / k` -- and `sourcesUsed` says how many that was; a caller who wants the
+ * estimator of the full sum multiplies by `n / sourcesUsed`.
+ * @public
+ */
+export interface GpuBetweennessResult extends GpuScoresResult {
+    /** How many sources the scores sum over: `n` for an exact run, the sample size for a sampled one. */
+    readonly sourcesUsed: number;
+    /**
+     * True when some pair of vertices is joined by more than 2^32 shortest paths: the u32 path counts wrapped and the
+     * scores are WRONG, not approximate. Never clamped, never silent.
+     */
+    readonly sigmaOverflow: boolean;
+}
+
+/**
+ * Edge betweenness (spec 3.3 line 834): one score per logical edge (`edgeCount`), the per-arc scores folded with
+ * `foldArcs(s, perArc, "sum")` and halved on an undirected snapshot (the two arcs carry the pairs crossing the edge
+ * in each direction). `sourcesUsed` and `sigmaOverflow` mean what they mean on `GpuBetweennessResult`.
+ * @public
+ */
+export interface GpuEdgeScoresResult {
+    readonly scores: F32;
+    readonly precision: "f32";
+    readonly sourcesUsed: number;
+    readonly sigmaOverflow: boolean;
+}

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; }