@graphty/webgpu-graph-algorithms 0.6.14 → 0.6.16

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

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const bcForwardEdgeWgsl = "\nvar<workgroup> wlive: u32;                        // 1 when the level has entries\nvar<workgroup> wwon: atomic<u32>;                 // the strip's winners\nvar<workgroup> wbase: u32;                        // where the strip's winners go in the log\n\nfn claim(x: u32, next: u32) -> bool {\n    if (atomicLoad(&depthK[x]) != INVALID_INDEX) { return false; }   // the pre-check of design 16.1\n    return atomicMin(&depthK[x], next) == INVALID_INDEX;\n}\n\nfn count_paths(origin: u32, x: u32, next: u32) {\n    if (atomicLoad(&depthK[x]) == next) {                            // every arc on a shortest path adds\n        let add = atomicLoad(&sigmaK[origin]);\n        let old = atomicAdd(&sigmaK[x], add);\n        if (old + add < old) { atomicOr(&counters[27], 1u); }        // the u32 wrap, reported\n    }\n}\n\n@compute @workgroup_size(WG)\nfn bc_forward_edge(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let level = atomicLoad(&counters[11]);\n    if (lid.x == 0u) { wlive = select(0u, 1u, ends[level + 1u] > ends[level]); }\n    if (workgroupUniformLoad(&wlive) == 0u) { return; }              // uniform: nothing below runs on an empty level\n    let next = level + 1u;\n    for (var s = 0u; s < P.k; s = s + 1u) {\n        let base = s * P.n;\n        for (var e0 = group_id(wid) * WG; e0 < P.count; e0 = e0 + P.stride) {   // grid-stride over the edges\n            let e = e0 + lid.x;\n            var a = INVALID_INDEX;                                   // the claims this lane won\n            var b = INVALID_INDEX;\n            if (e < P.count) {\n                let u = base + edgeSrc[e];\n                let x = base + edgeDst[e];\n                if (atomicLoad(&depthK[u]) == level) {\n                    if (claim(x, next)) { a = x; }\n                    count_paths(u, x, next);\n                }\n                if (UNDIRECTED) {                                    // the other direction of an undirected edge\n                    if (atomicLoad(&depthK[x]) == level) {\n                        if (claim(u, next)) { b = u; }\n                        count_paths(x, u, next);\n                    }\n                }\n            }\n            let mine = select(0u, 1u, a != INVALID_INDEX) + select(0u, 1u, b != INVALID_INDEX);\n            var slot = 0u;\n            if (mine != 0u) { slot = atomicAdd(&wwon, mine); }\n            workgroupBarrier();\n            if (lid.x == 0u) {\n                wbase = atomicAdd(&counters[26], atomicLoad(&wwon));   // stackTop: one global atomic per strip\n                atomicStore(&wwon, 0u);\n            }\n            workgroupBarrier();\n            if (a != INVALID_INDEX) {\n                S[wbase + slot] = a;\n                slot = slot + 1u;\n            }\n            if (b != INVALID_INDEX) { S[wbase + slot] = b; }\n        }\n    }\n}\n";
+//# sourceMappingURL=bc-forward-edge.wgsl.d.ts.map

package/dist/src/wgsl/bc-forward-edge.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-forward-edge.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bc-forward-edge.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,m0FA6D7B,CAAC"}

package/dist/src/wgsl/bc-forward-edge.wgsl.js

@@ -0,0 +1,76 @@
+/**
+ * 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; }
+        }
+    }
+}
+`;
+//# sourceMappingURL=bc-forward-edge.wgsl.js.map

package/dist/src/wgsl/bc-forward-edge.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-forward-edge.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bc-forward-edge.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D3C,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * 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 declare const bcForwardWgsl = "\nvar<workgroup> sh: array<u32, WG>;                // the block's degrees, then their inclusive scan\nvar<workgroup> rowStart: array<u32, WG>;          // the first arc of each entry's row\nvar<workgroup> entryOf: array<u32, WG>;           // each entry, s * n + u\nvar<workgroup> wstart: u32;                       // the level's first log index\nvar<workgroup> wcount: u32;                       // the level's entry count\nvar<workgroup> wwon: atomic<u32>;                 // the strip's winners\nvar<workgroup> wbase: u32;                        // where the strip's winners go in the log\n\n@compute @workgroup_size(WG)\nfn bc_forward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let level = atomicLoad(&counters[11]);\n    if (lid.x == 0u) {\n        let lo = ends[level];\n        wstart = lo;\n        wcount = ends[level + 1u] - lo;\n    }\n    let start = workgroupUniformLoad(&wstart);\n    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers\n    let next = level + 1u;\n    for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries\n        let i = b0 + lid.x;\n        var deg = 0u;\n        var first = 0u;\n        var entry = 0u;\n        if (i < count) {                                             // guarded loads into locals (3.5 rule 1)\n            entry = S[start + i];\n            let u = entry % P.n;\n            first = rowPtr[u];\n            deg = rowPtr[u + 1u] - first;\n        }\n        sh[lid.x] = deg;\n        rowStart[lid.x] = first;\n        entryOf[lid.x] = entry;\n        workgroupBarrier();\n        for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan of the degrees\n            var t = 0u;\n            if (lid.x >= s) { t = sh[lid.x - s]; }\n            workgroupBarrier();\n            sh[lid.x] = sh[lid.x] + t;\n            workgroupBarrier();\n        }\n        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);          // uniform; includes a barrier\n        for (var p0 = 0u; p0 < aggregate; p0 = p0 + WG) {            // strip [0, aggregate) WG arcs at a time\n            let p = p0 + lid.x;\n            var won = false;\n            var claimed = 0u;\n            if (p < aggregate) {\n                var lo = 0u;                                         // upper_bound: the first k with sh[k] > p owns arc p\n                var hi = WG;\n                loop {\n                    if (lo >= hi) { break; }\n                    let mid = (lo + hi) / 2u;\n                    if (sh[mid] > p) { hi = mid; } else { lo = mid + 1u; }\n                }\n                let k = lo;\n                var exclusive = 0u;\n                if (k > 0u) { exclusive = sh[k - 1u]; }\n                let origin = entryOf[k];                             // s * n + u\n                let x = (origin - (origin % P.n)) + colIdx[rowStart[k] + (p - exclusive)];   // s * n + x\n                if (atomicLoad(&depthK[x]) == INVALID_INDEX) {       // the pre-check of design 16.1\n                    won = atomicMin(&depthK[x], next) == INVALID_INDEX;   // the claim: the one winner appends\n                }\n                if (atomicLoad(&depthK[x]) == next) {                // the count: EVERY arc on a shortest path adds\n                    let add = atomicLoad(&sigmaK[origin]);\n                    let old = atomicAdd(&sigmaK[x], add);\n                    if (old + add < old) { atomicOr(&counters[27], 1u); }   // the u32 wrap, reported\n                }\n                claimed = x;\n            }\n            var slot = 0u;\n            if (won) { slot = atomicAdd(&wwon, 1u); }\n            workgroupBarrier();\n            if (lid.x == 0u) {\n                wbase = atomicAdd(&counters[26], atomicLoad(&wwon));   // stackTop: one global atomic per strip\n                atomicStore(&wwon, 0u);\n            }\n            workgroupBarrier();\n            if (won) { S[wbase + slot] = claimed; }\n        }\n        workgroupBarrier();                                          // sh, rowStart and entryOf are reused by the next block\n    }\n}\n";
+//# sourceMappingURL=bc-forward.wgsl.d.ts.map

package/dist/src/wgsl/bc-forward.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-forward.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bc-forward.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,+nIAmFzB,CAAC"}

package/dist/src/wgsl/bc-forward.wgsl.js

@@ -0,0 +1,106 @@
+/**
+ * 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
+    }
+}
+`;
+//# sourceMappingURL=bc-forward.wgsl.js.map

package/dist/src/wgsl/bc-forward.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-forward.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bc-forward.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFvC,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const bcGatherWgsl = "\n@compute @workgroup_size(WG)\nfn bc_gather(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    for (var w = linear_id(wid, lid.x); w < P.n; w = w + P.stride) {\n        var acc = bc[w];\n        for (var s = 0u; s < P.k; s = s + 1u) {\n            acc = acc + deltaK[s * P.n + w];\n        }\n        bc[w] = acc;\n    }\n}\n";
+//# sourceMappingURL=bc-gather.wgsl.d.ts.map

package/dist/src/wgsl/bc-gather.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-gather.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bc-gather.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,oXAWxB,CAAC"}

package/dist/src/wgsl/bc-gather.wgsl.js

@@ -0,0 +1,20 @@
+/**
+ * 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;
+    }
+}
+`;
+//# sourceMappingURL=bc-gather.wgsl.js.map

package/dist/src/wgsl/bc-gather.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc-gather.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bc-gather.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;;;;;;;;;;;CAWtC,CAAC"}

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

@@ -10,8 +10,11 @@
  * 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.
  */
-export declare const closenessReduceWgsl = "\n@compute @workgroup_size(WG)\nfn closeness_reduce(@builtin(local_invocation_id) lid: vec3<u32>) {\n    if (lid.x != 0u) { return; }                                     // one lane; no barrier follows (3.5 rule 1)\n    if (P.role == 1u) {                                              // the seed of a batch: P.source is its first source\n        let k = min(32u, P.n - P.source);\n        for (var s = 0u; s < k; s = s + 1u) {\n            let v = P.source + s;\n            let bit = 1u << s;\n            bits[v] = bit;                                           // visited\n            bits[P.bitsBase + v] = bit;                              // the frontier level 0 reads (region 1: level 0's parity is 0)\n            bits[3u * P.bitsBase + v] = 1u;                          // flags: level 0's compact turns them into the list\n        }\n        atomicStore(&counters[0], k);                                // not done\n        atomicStore(&counters[11], U32_MAX);                         // level: the first boundary brings it to 0\n        atomicStore(&counters[15], 0u);                              // done\n        return;\n    }\n    // role 0: the level boundary -- done from the previous level's compacted count, then the accumulation\n    let count = atomicLoad(&counters[0]);\n    atomicStore(&counters[15], select(0u, 1u, count == 0u));\n    let level = atomicLoad(&counters[11]);\n    let d = level + 1u;                                              // the distance of the claims the level just run made\n    for (var s = 0u; s < 32u; s = s + 1u) {\n        let c = atomicLoad(&perSource[s]);                           // newCount[s]\n        atomicStore(&perSource[32u + s], atomicLoad(&perSource[32u + s]) + c);   // reached[s]\n        // sum[s] += c x d in 64 bits: the 16-bit split product (pLo, pHi), then the add with its carry\n        let cLo = c & 0xFFFFu;\n        let cHi = c >> 16u;\n        let dLo = d & 0xFFFFu;\n        let dHi = d >> 16u;\n        let ll = cLo * dLo;\n        let lh = cLo * dHi;\n        let hl = cHi * dLo;\n        let mid = (ll >> 16u) + (lh & 0xFFFFu) + (hl & 0xFFFFu);\n        let pLo = (ll & 0xFFFFu) | ((mid & 0xFFFFu) << 16u);\n        let pHi = (cHi * dHi) + (lh >> 16u) + (hl >> 16u) + (mid >> 16u);\n        var lo = atomicLoad(&perSource[64u + s]);                    // sumLo[s]\n        var hi = atomicLoad(&perSource[96u + s]);                    // sumHi[s]\n        let before = lo;\n        lo = lo + pLo;\n        hi = hi + pHi + select(0u, 1u, lo < before);\n        atomicStore(&perSource[64u + s], lo);\n        atomicStore(&perSource[96u + s], hi);\n        atomicStore(&perSource[s], 0u);\n    }\n    atomicStore(&counters[11], level + 1u);\n}\n";
+export declare const closenessReduceWgsl = "\n@compute @workgroup_size(WG)\nfn closeness_reduce(@builtin(local_invocation_id) lid: vec3<u32>) {\n    if (lid.x != 0u) { return; }                                     // one lane; no barrier follows (3.5 rule 1)\n    if (P.role != 0u) {                                              // the seed of a batch: P.source is its first source\n        let k = min(32u, P.n - P.source);\n        for (var s = 0u; s < k; s = s + 1u) {\n            var v = P.source + s;\n            if (P.role == 2u) { v = atomicLoad(&perSource[128u + P.bitsBase + P.source + s]); }   // a sampled run's list\n            let bit = 1u << s;\n            bits[v] = bits[v] | bit;                                 // visited\n            bits[P.bitsBase + v] = bits[P.bitsBase + v] | bit;       // the frontier level 0 reads (region 1: level 0's parity is 0)\n            bits[3u * P.bitsBase + v] = 1u;                          // flags: level 0's compact turns them into the list\n        }\n        atomicStore(&counters[0], k);                                // not done\n        atomicStore(&counters[11], U32_MAX);                         // level: the first boundary brings it to 0\n        atomicStore(&counters[15], 0u);                              // done\n        return;\n    }\n    // role 0: the level boundary -- done from the previous level's compacted count, then the accumulation\n    let count = atomicLoad(&counters[0]);\n    atomicStore(&counters[15], select(0u, 1u, count == 0u));\n    let level = atomicLoad(&counters[11]);\n    let d = level + 1u;                                              // the distance of the claims the level just run made\n    for (var s = 0u; s < 32u; s = s + 1u) {\n        let c = atomicLoad(&perSource[s]);                           // newCount[s]\n        atomicStore(&perSource[32u + s], atomicLoad(&perSource[32u + s]) + c);   // reached[s]\n        // sum[s] += c x d in 64 bits: the 16-bit split product (pLo, pHi), then the add with its carry\n        let cLo = c & 0xFFFFu;\n        let cHi = c >> 16u;\n        let dLo = d & 0xFFFFu;\n        let dHi = d >> 16u;\n        let ll = cLo * dLo;\n        let lh = cLo * dHi;\n        let hl = cHi * dLo;\n        let mid = (ll >> 16u) + (lh & 0xFFFFu) + (hl & 0xFFFFu);\n        let pLo = (ll & 0xFFFFu) | ((mid & 0xFFFFu) << 16u);\n        let pHi = (cHi * dHi) + (lh >> 16u) + (hl >> 16u) + (mid >> 16u);\n        var lo = atomicLoad(&perSource[64u + s]);                    // sumLo[s]\n        var hi = atomicLoad(&perSource[96u + s]);                    // sumHi[s]\n        let before = lo;\n        lo = lo + pLo;\n        hi = hi + pHi + select(0u, 1u, lo < before);\n        atomicStore(&perSource[64u + s], lo);\n        atomicStore(&perSource[96u + s], hi);\n        atomicStore(&perSource[s], 0u);\n    }\n    atomicStore(&counters[11], level + 1u);\n}\n";
 //# sourceMappingURL=closeness-reduce.wgsl.d.ts.map

package/dist/src/wgsl/closeness-reduce.wgsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeness-reduce.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/closeness-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,0qFAgD/B,CAAC"}
+{"version":3,"file":"closeness-reduce.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/closeness-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,qyFAiD/B,CAAC"}

package/dist/src/wgsl/closeness-reduce.wgsl.js

@@ -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/dist/src/wgsl/closeness-reduce.wgsl.js.map

@@ -1 +1 @@
-{"version":3,"file":"closeness-reduce.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/closeness-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgD7C,CAAC"}
+{"version":3,"file":"closeness-reduce.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/closeness-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD7C,CAAC"}

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

@@ -13,8 +13,10 @@
  * 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 declare const closenessSweepWgsl = "\nvar<workgroup> sh: array<u32, WG>;                // the block's degrees, then their inclusive scan\nvar<workgroup> rowStart: array<u32, WG>;          // the first bound arc of each entry's row\nvar<workgroup> rowOf: array<u32, WG>;             // the frontier vertex of each entry (the source end of its arcs)\nvar<workgroup> local: array<atomic<u32>, 32>;     // this workgroup's fresh claims per source\nvar<workgroup> wcount: u32;                       // the frontier list's length\n\n@compute @workgroup_size(WG)\nfn closeness_sweep(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    if (lid.x == 0u) { wcount = atomicLoad(&counters[0]); }          // the frontier list's length (compact's total)\n    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers\n    let nextBase = select(2u * P.bitsBase, P.bitsBase, P.mode == 1u);   // the region that is next this level\n    let frontierBase = 3u * P.bitsBase - nextBase;                   // the other one: the region that is the frontier\n    for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries\n        let i = b0 + lid.x;                                          // this lane's frontier entry\n        var deg = 0u;\n        var start = 0u;\n        var u = 0u;\n        if (i < count) {                                                 // guarded loads into locals (3.5 rule 1)\n            u = frontierList[i];\n            let lo = max(rowPtr[u], P.arcBase);\n            let hi = min(rowPtr[u + 1u], P.arcEnd);\n            start = lo;\n            deg = select(0u, hi - lo, hi > lo);\n        }\n        if (lid.x < 32u) { atomicStore(&local[lid.x], 0u); }            // zeroed before the strip loop (WebGPU zero-initialises workgroup memory; said anyway)\n        sh[lid.x] = deg;\n        rowStart[lid.x] = start;\n        rowOf[lid.x] = u;\n        workgroupBarrier();\n        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of the degrees (bfs-contract's, inlined)\n            var t = 0u;\n            if (lid.x >= s) { t = sh[lid.x - s]; }\n            workgroupBarrier();\n            sh[lid.x] = sh[lid.x] + t;\n            workgroupBarrier();\n        }\n        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);              // uniform; includes a barrier\n        for (var p = lid.x; p < aggregate; p = p + WG) {                 // strip [0, aggregate): lane j takes j, j + WG, ...\n            var lo = 0u;                                                 // upper_bound: the first k with sh[k] > p owns arc p\n            var hi = WG;\n            loop {\n                if (lo >= hi) { break; }\n                let mid = (lo + hi) / 2u;\n                if (sh[mid] > p) { hi = mid; } else { lo = mid + 1u; }\n            }\n            let k = lo;\n            var exclusive = 0u;\n            if (k > 0u) { exclusive = sh[k - 1u]; }\n            let arc = rowStart[k] + (p - exclusive);\n            let x = colIdx[arc - P.arcBase];\n            let mask = atomicLoad(&bits[frontierBase + rowOf[k]]) & ~atomicLoad(&bits[x]);   // the sources at u that have not reached x\n            if (mask != 0u) {\n                let old = atomicOr(&bits[x], mask);                      // visited: the claim, one read-modify-write\n                let fresh = mask & ~old;                                 // the sources whose claim this lane won\n                if (fresh != 0u) {\n                    atomicOr(&bits[nextBase + x], fresh);\n                    atomicStore(&bits[3u * P.bitsBase + x], 1u);         // flags: x is in the next frontier list (compact reads it)\n                    var b = fresh;\n                    loop {                                               // one tally per set bit of fresh\n                        if (b == 0u) { break; }\n                        let s = firstTrailingBit(b);\n                        atomicAdd(&local[s], 1u);\n                        b = b & (b - 1u);\n                    }\n                }\n            }\n        }\n        workgroupBarrier();                                              // uniform: the loop's bound is the uniform aggregate\n        if (lid.x < 32u) {                                               // ONE global atomic per source per workgroup\n            let c = atomicLoad(&local[lid.x]);\n            if (c != 0u) { atomicAdd(&perSource[lid.x], c); }            // newCount[s]\n        }\n        workgroupBarrier();                                              // sh, rowStart, rowOf and local are reused by the next block\n    }\n}\n";
+export declare const closenessSweepWgsl = "\nvar<workgroup> sh: array<u32, WG>;                // the block's degrees, then their inclusive scan\nvar<workgroup> rowStart: array<u32, WG>;          // the first bound arc of each entry's row\nvar<workgroup> rowOf: array<u32, WG>;             // the frontier vertex of each entry (the source end of its arcs)\nvar<workgroup> local: array<atomic<u32>, 32>;     // this workgroup's fresh claims per source\nvar<workgroup> wcount: u32;                       // the frontier list's length\nvar<workgroup> wdist: u32;                        // the distance of this level's claims\n\n@compute @workgroup_size(WG)\nfn closeness_sweep(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    if (lid.x == 0u) {\n        wcount = atomicLoad(&counters[0]);                           // the frontier list's length (compact's total)\n        wdist = atomicLoad(&counters[11]) + 1u;                      // the level word: this level claims at level + 1\n    }\n    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers\n    let dist = workgroupUniformLoad(&wdist);\n    let nextBase = select(2u * P.bitsBase, P.bitsBase, P.mode == 1u);   // the region that is next this level\n    let frontierBase = 3u * P.bitsBase - nextBase;                   // the other one: the region that is the frontier\n    for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries\n        let i = b0 + lid.x;                                          // this lane's frontier entry\n        var deg = 0u;\n        var start = 0u;\n        var u = 0u;\n        if (i < count) {                                                 // guarded loads into locals (3.5 rule 1)\n            u = frontierList[i];\n            let lo = max(rowPtr[u], P.arcBase);\n            let hi = min(rowPtr[u + 1u], P.arcEnd);\n            start = lo;\n            deg = select(0u, hi - lo, hi > lo);\n        }\n        if (lid.x < 32u) { atomicStore(&local[lid.x], 0u); }            // zeroed before the strip loop (WebGPU zero-initialises workgroup memory; said anyway)\n        sh[lid.x] = deg;\n        rowStart[lid.x] = start;\n        rowOf[lid.x] = u;\n        workgroupBarrier();\n        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of the degrees (bfs-contract's, inlined)\n            var t = 0u;\n            if (lid.x >= s) { t = sh[lid.x - s]; }\n            workgroupBarrier();\n            sh[lid.x] = sh[lid.x] + t;\n            workgroupBarrier();\n        }\n        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);              // uniform; includes a barrier\n        for (var p = lid.x; p < aggregate; p = p + WG) {                 // strip [0, aggregate): lane j takes j, j + WG, ...\n            var lo = 0u;                                                 // upper_bound: the first k with sh[k] > p owns arc p\n            var hi = WG;\n            loop {\n                if (lo >= hi) { break; }\n                let mid = (lo + hi) / 2u;\n                if (sh[mid] > p) { hi = mid; } else { lo = mid + 1u; }\n            }\n            let k = lo;\n            var exclusive = 0u;\n            if (k > 0u) { exclusive = sh[k - 1u]; }\n            let arc = rowStart[k] + (p - exclusive);\n            let x = colIdx[arc - P.arcBase];\n            let mask = atomicLoad(&bits[frontierBase + rowOf[k]]) & ~atomicLoad(&bits[x]);   // the sources at u that have not reached x\n            if (mask != 0u) {\n                let old = atomicOr(&bits[x], mask);                      // visited: the claim, one read-modify-write\n                let fresh = mask & ~old;                                 // the sources whose claim this lane won\n                if (fresh != 0u) {\n                    atomicOr(&bits[nextBase + x], fresh);\n                    atomicStore(&bits[3u * P.bitsBase + x], 1u);         // flags: x is in the next frontier list (compact reads it)\n                    if (P.perNode == 1u) {                               // a sampled run: x's distance to each source won\n                        atomicAdd(&perSource[128u + x], countOneBits(fresh) * dist);\n                    }\n                    var b = fresh;\n                    loop {                                               // one tally per set bit of fresh\n                        if (b == 0u) { break; }\n                        let s = firstTrailingBit(b);\n                        atomicAdd(&local[s], 1u);\n                        b = b & (b - 1u);\n                    }\n                }\n            }\n        }\n        workgroupBarrier();                                              // uniform: the loop's bound is the uniform aggregate\n        if (lid.x < 32u) {                                               // ONE global atomic per source per workgroup\n            let c = atomicLoad(&local[lid.x]);\n            if (c != 0u) { atomicAdd(&perSource[lid.x], c); }            // newCount[s]\n        }\n        workgroupBarrier();                                              // sh, rowStart, rowOf and local are reused by the next block\n    }\n}\n";
 //# sourceMappingURL=closeness-sweep.wgsl.d.ts.map

package/dist/src/wgsl/closeness-sweep.wgsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeness-sweep.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/closeness-sweep.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,ymJA4E9B,CAAC"}
+{"version":3,"file":"closeness-sweep.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/closeness-sweep.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,inKAoF9B,CAAC"}

package/dist/src/wgsl/closeness-sweep.wgsl.js

@@ -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/dist/src/wgsl/closeness-sweep.wgsl.js.map

@@ -1 +1 @@
-{"version":3,"file":"closeness-sweep.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/closeness-sweep.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4E5C,CAAC"}
+{"version":3,"file":"closeness-sweep.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/closeness-sweep.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoF5C,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const cooEmitWgsl = "\n@compute @workgroup_size(WG)\nfn coo_emit(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let i = linear_id(wid, lid.x);\n    if (i >= P.count) { return; }                                  // no barrier follows\n    var a = i;\n    if (INDEXED) { a = order[i]; }                                 // the arc this position takes\n    let e = a / 2u;                                                // arc 2e is edge e as declared, arc 2e + 1 its reverse\n    let forward = (a % 2u) == 0u;\n    let u = edgeSrc[e];\n    let v = edgeDst[e];\n    var w = 1.0;\n    if (WEIGHTED) { w = edgeWeight[e]; }\n    if (u == v) {                                                  // a self-loop is dropped: both arcs sort last and never open a run\n        outSrc[i] = INVALID_INDEX;\n        outDst[i] = INVALID_INDEX;\n        outWeight[i] = 0.0;\n        return;\n    }\n    outSrc[i] = select(v, u, forward);\n    outDst[i] = select(u, v, forward);\n    outWeight[i] = w;\n}\n";
+//# sourceMappingURL=coo-emit.wgsl.d.ts.map

package/dist/src/wgsl/coo-emit.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coo-emit.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/coo-emit.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,s/BAuBvB,CAAC"}

package/dist/src/wgsl/coo-emit.wgsl.js

@@ -0,0 +1,33 @@
+/**
+ * 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;
+}
+`;
+//# sourceMappingURL=coo-emit.wgsl.js.map

package/dist/src/wgsl/coo-emit.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coo-emit.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/coo-emit.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;CAuBrC,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const cooScatterWgsl = "\n@compute @workgroup_size(WG)\nfn coo_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let i = linear_id(wid, lid.x);\n    if (i >= P.count) { return; }                                  // no barrier follows\n    let s = src[i];\n    var slot = 0u;\n    if (SORTED_INPUT) {\n        if (i > 0u && s < src[i - 1u]) { atomicStore(&cursors[0], 1u); }   // unsorted input: the flag the driver refuses\n        let within = i - rowPtr[s];                                // the arc's place in its row\n        slot = rowPtr[s] + within;\n    } else {\n        slot = rowPtr[s] + atomicAdd(&cursors[s], 1u);             // race order: the row is not sorted in this mode\n    }\n    colIdx[slot] = dst[i];\n    if (WEIGHTED) { outWeight[slot] = weight[i]; }\n}\n";
+//# sourceMappingURL=coo-scatter.wgsl.d.ts.map

package/dist/src/wgsl/coo-scatter.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coo-scatter.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/coo-scatter.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,2yBAiB1B,CAAC"}

package/dist/src/wgsl/coo-scatter.wgsl.js

@@ -0,0 +1,32 @@
+/**
+ * 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]; }
+}
+`;
+//# sourceMappingURL=coo-scatter.wgsl.js.map

package/dist/src/wgsl/coo-scatter.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coo-scatter.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/coo-scatter.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;CAiBxC,CAAC"}

package/dist/src/wgsl/group-by-key-row.wgsl.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `group-by-key-row` kernel body (design 8.6; the per-row group-by-key): for every listed row `v`, the arcs of
+ * the row are grouped by the key of their target (`keyIn[colIdx[a]]`), the weights are summed per key, and the key
+ * with the largest sum wins, ties going to the LOWEST key -- which makes the answer independent of the order the arcs
+ * are visited in, and so bitwise reproducible. `bestKey[v]` gets the key (`INVALID_INDEX` for an empty row) and
+ * `bestScore[v]` the summed weight.
+ *
+ * The sums are u32 fixed point, because WGSL has no float atomic: every weight is scaled by `2^s`, a power of two
+ * chosen from the exponents of the row's largest weight and of its degree alone so that `maxWeight x degree x 2^s`
+ * lies in [2^28, 2^30), and rounded to the nearest integer, halves up. No step rounds a float: the scale needs no
+ * product, scaling by a power of two is exact, and so are the integer part and the fraction of the scaled weight.
+ * That matters because WGSL lets `x + y` and `x * y` round to EITHER neighbour of an inexact result, so a rounded
+ * step could differ between devices; as written, both tiers, every device and any CPU reference compute identical
+ * integers. A weight smaller than `2^-s / 2` contributes nothing, and a negative weight counts as zero. Without
+ * WEIGHTED every weight is 1.
+ *
+ * TIER 0: one thread per row (`rows[P.rowsBase + i]`), a pairwise scan in registers -- for short rows, and at most
+ * GROUP_ROW_THREAD_LIMIT arcs, since llvmpipe stops an invocation's loops after 65,535 steps. Any other TIER: one
+ * workgroup per row (`rows[P.rowsBase + g]`) over its own open-addressing region of `GROUP_HASH_LOAD_FACTOR x degree`
+ * slot pairs (key, sum) starting at word `rows[P.basesBase + g]` of `hashRegion`, cleared by the workgroup itself;
+ * a key is claimed by a bounded compare-exchange loop with linear probing, and a lane that exhausts its bound raises
+ * `hashRegion[0]`, which the driver reads and refuses. Every barrier is reached in uniform control flow: the only
+ * early return keys on the workgroup id and a uniform. Body only (spec 3.5, D9); normative text.
+ */
+export declare const groupByKeyRowWgsl = "\nvar<workgroup> shMax: array<f32, WG>;\nvar<workgroup> shKey: array<u32, WG>;\nvar<workgroup> shSum: array<u32, WG>;\n\nfn weight_of(a: u32) -> f32 {\n    if (WEIGHTED) { return weights[a]; }\n    return 1.0;\n}\nfn scale_of(maxW: f32, d: u32) -> f32 {                            // 2^s, maxW x d x 2^s in [2^28, 2^30), from exponents alone\n    let em = i32((bitcast<u32>(maxW) >> 23u) & 255u) - 127;\n    let ed = i32(firstLeadingBit(max(d, 1u)));\n    let s = clamp(28 - em - ed, -126, 126);\n    return bitcast<f32>(u32(s + 127) << 23u);\n}\nfn inverse_of(scale: f32) -> f32 {                                 // 2^-s, exact\n    let s = i32((bitcast<u32>(scale) >> 23u) & 255u) - 127;\n    return bitcast<f32>(u32(127 - s) << 23u);\n}\nfn quantize(w: f32, scale: f32) -> u32 {                           // nearest integer, halves up; every step exact\n    let x = max(w * scale, 0.0);\n    let i = u32(x);\n    return select(i, i + 1u, x - f32(i) >= 0.5);\n}\nfn better(sum: u32, key: u32, bestSum: u32, bestKey0: u32) -> bool { return sum > bestSum || (sum == bestSum && key < bestKey0); }\n\nfn row_thread(v: u32) {\n    let lo = rowPtr[v];\n    let hi = rowPtr[v + 1u];\n    var maxW = 0.0;\n    for (var a = lo; a < hi; a = a + 1u) { maxW = max(maxW, weight_of(a)); }\n    let scale = scale_of(maxW, hi - lo);\n    var bk = INVALID_INDEX;\n    var bs = 0u;\n    for (var a = lo; a < hi; a = a + 1u) {\n        let k = keyIn[colIdx[a]];\n        var seen = false;\n        for (var b = lo; b < a; b = b + 1u) { if (keyIn[colIdx[b]] == k) { seen = true; break; } }\n        if (seen) { continue; }                                    // this key was summed at its first arc\n        var sum = 0u;\n        for (var b = a; b < hi; b = b + 1u) { if (keyIn[colIdx[b]] == k) { sum = sum + quantize(weight_of(b), scale); } }\n        if (better(sum, k, bs, bk)) { bk = k; bs = sum; }\n    }\n    bestKey[v] = bk;\n    bestScore[v] = f32(bs) * inverse_of(scale);\n}\n\nfn row_hash(g: u32, lid: u32) {\n    let v = rows[P.rowsBase + g];\n    let base = rows[P.basesBase + g];\n    let lo = rowPtr[v];\n    let hi = rowPtr[v + 1u];\n    let cap = GROUP_HASH_LOAD_FACTOR * (hi - lo);\n    var m = 0.0;\n    for (var a = lo + lid; a < hi; a = a + WG) { m = max(m, weight_of(a)); }\n    shMax[lid] = m;\n    workgroupBarrier();\n    for (var s = WG / 2u; s > 0u; s = s / 2u) {\n        if (lid < s) { shMax[lid] = max(shMax[lid], shMax[lid + s]); }\n        workgroupBarrier();\n    }\n    let scale = scale_of(shMax[0], hi - lo);\n    for (var j = lid; j < cap; j = j + WG) {                       // the region is this workgroup's alone: clear it\n        atomicStore(&hashRegion[base + 2u * j], INVALID_INDEX);\n        atomicStore(&hashRegion[base + 2u * j + 1u], 0u);\n    }\n    storageBarrier();\n    var exhausted = false;\n    for (var a = lo + lid; a < hi; a = a + WG) {\n        let k = keyIn[colIdx[a]];\n        let q = quantize(weight_of(a), scale);\n        var slot = lowbias32(k) % cap;\n        var steps = 0u;\n        loop {\n            if (steps >= cap + 64u) { exhausted = true; break; }   // bounded: a spurious compare-exchange failure is legal (WGSL 17.8.5)\n            steps = steps + 1u;\n            let r = atomicCompareExchangeWeak(&hashRegion[base + 2u * slot], INVALID_INDEX, k);\n            if (r.exchanged || r.old_value == k) { atomicAdd(&hashRegion[base + 2u * slot + 1u], q); break; }\n            if (r.old_value == INVALID_INDEX) { continue; }        // a spurious failure: the same slot again\n            slot = (slot + 1u) % cap;                              // linear probing\n        }\n    }\n    if (exhausted) { atomicStore(&hashRegion[0], 1u); }\n    storageBarrier();\n    var bk = INVALID_INDEX;\n    var bs = 0u;\n    for (var j = lid; j < cap; j = j + WG) {\n        let k = atomicLoad(&hashRegion[base + 2u * j]);\n        if (k != INVALID_INDEX) {\n            let sum = atomicLoad(&hashRegion[base + 2u * j + 1u]);\n            if (better(sum, k, bs, bk)) { bk = k; bs = sum; }\n        }\n    }\n    shKey[lid] = bk;\n    shSum[lid] = bs;\n    workgroupBarrier();\n    for (var s = WG / 2u; s > 0u; s = s / 2u) {\n        if (lid < s && better(shSum[lid + s], shKey[lid + s], shSum[lid], shKey[lid])) {\n            shKey[lid] = shKey[lid + s];\n            shSum[lid] = shSum[lid + s];\n        }\n        workgroupBarrier();\n    }\n    if (lid == 0u) {\n        bestKey[v] = shKey[0];\n        bestScore[v] = f32(shSum[0]) * inverse_of(scale);\n    }\n}\n\n@compute @workgroup_size(WG)\nfn group_by_key_row(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    if (TIER == 0u) {\n        let i = linear_id(wid, lid.x);\n        if (i < P.count) { row_thread(rows[P.rowsBase + i]); }\n        return;                                                    // TIER is an override: uniform\n    }\n    let g = group_id(wid);\n    if (g >= P.count) { return; }                                  // uniform: the workgroup id and a uniform\n    row_hash(g, lid.x);\n}\n";
+//# sourceMappingURL=group-by-key-row.wgsl.d.ts.map