@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.4

package/src/wgsl/bfs-bottom-up.wgsl.ts

@@ -0,0 +1,66 @@
+/**
+ * The `bfs-bottom-up` kernel body (design 8.4 "the bottom-up sweep"; P8-T8, the P8 plan's PD-18 / PD-21): one
+ * invocation per entry of the unvisited list (`unvisitedListLen`, word 7; the list is the first region of the
+ * read-only `sweepIn` buffer, the frontier bitset its second at `P.bitsBase`), over the REVERSE core bound in group 0
+ * (`coreOfView(residency.view(s, "reverse"))`: the forward arrays on an undirected snapshot, which P7's residency
+ * aliases at zero upload cost). A lane whose vertex is still at `INVALID_INDEX` -- the list is up to 32 levels
+ * stale, and an entry claimed since the rebuild is skipped on that test -- walks its in-neighbours until the FIRST
+ * one whose bit is set and breaks: that early exit is the whole point of the direction (a vertex with one frontier
+ * neighbour among thousands costs one read), and `arcsScanned` (word 16, one `atomicAdd` per workgroup of the lanes'
+ * reads through `wg_reduce_u32`) is the counter the sabotage row that removes the exit is pinned to, never a timing.
+ * The winners are packed into the output vertex queue by `bfs-contract`'s workgroup scan and one `atomicAdd` per
+ * workgroup on `nextFrontierCount`, and claim with a plain `atomicStore`: the list holds every vertex once and the
+ * sweep is vertex-parallel, so no two lanes claim one vertex. It adds nothing to `frontierDegreeSum` (a bottom-up
+ * level expands nothing), which is why `unvisitedDegreeSum` stops falling while bottom-up runs (the selector's
+ * JSDoc). Uniformity (spec 3.5 rule 1): the guarded walk writes locals, the scan and the reduction run
+ * unconditionally after it. 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 bfsBottomUpWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;
+var<workgroup> base: u32;
+var<workgroup> wcount: u32;                                          // the unvisited list's length on a bottom-up level, 0 on any other
+
+@compute @workgroup_size(WG)
+fn bfs_bottom_up(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let claim = atomicLoad(&counters[11]) + 1u;
+    if (lid.x == 0u) { wcount = select(0u, atomicLoad(&counters[7]), atomicLoad(&counters[24]) == 3u); }   // unvisitedListLen, on the bottom-up path only (the path word)
+    let len = workgroupUniformLoad(&wcount);                         // uniform: the block loop below holds barriers
+    for (var b0 = group_id(wid) * WG; b0 < len; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries
+        let i = b0 + lid.x;
+        var won = 0u;
+        var v = 0u;
+        var reads = 0u;
+        if (i < len) {                                                   // guarded work into locals
+            v = sweepIn[i];
+            if (atomicLoad(&depth[v]) == INVALID_INDEX) {                // a stale entry, claimed since the rebuild, is skipped
+                let end = min(rowPtr[v + 1u], P.arcEnd);
+                for (var a = max(rowPtr[v], P.arcBase); a < end; a = a + 1u) {   // in-neighbours through the reverse core
+                    reads = reads + 1u;
+                    let u = colIdx[a - P.arcBase];
+                    if (mask_bit(sweepIn[P.bitsBase + (u >> 5u)], u)) { won = 1u; break; }   // the early exit: a real break, never a flag
+                }
+            }
+        }
+        sh[lid.x] = won;
+        workgroupBarrier();
+        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of won (bfs-contract's)
+            var t = 0u;
+            if (lid.x >= s) { t = sh[lid.x - s]; }
+            workgroupBarrier();
+            sh[lid.x] = sh[lid.x] + t;
+            workgroupBarrier();
+        }
+        let inclusive = sh[lid.x];
+        let readsTotal = wg_reduce_u32(reads, lid.x, 0u);                // arcsScanned, one atomic per workgroup (the sabotage witness, Step 6)
+        if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }
+        if (lid.x == 0u) { atomicAdd(&counters[16], readsTotal); }
+        workgroupBarrier();
+        if (won == 1u) {
+            atomicStore(&depth[v], claim);                               // no claim race: the list holds v once and the sweep is vertex-parallel
+            frontierOut[base + inclusive - 1u] = v;
+        }
+        workgroupBarrier();                                              // sh and base are reused by the next block
+    }
+}
+`;

package/src/wgsl/bfs-contract.wgsl.ts

@@ -0,0 +1,54 @@
+/**
+ * The `bfs-contract` kernel body (design 8.4, 8.10 "BFS contract"; P8-T6, the P8 plan's PD-5 / PD-6 / PD-24 /
+ * DEP-P8-B): the contraction phase of the two-phase top-down level. One invocation per edge-queue entry (the target
+ * vertex `advance-expand` wrote), a direct grid-stride dispatch looping to the `edgeCount` `frontier-finalize` role 1
+ * clamped, and only when the block's `path` word says the level is two-phase. The claim is `atomicMin(&depth[v], level + 1)` and the invocation that
+ * observes `INVALID_INDEX` is the unique winner (PD-6): `atomicMin` is one read-modify-write, so only the first
+ * claimant of this level can see the sentinel; a second claimant of the same level observes `claim`, and a vertex
+ * already at a smaller depth returns that depth and keeps it. Design 8.4 says why this is not
+ * `atomicCompareExchangeWeak`: WGSL 17.8.5 lets it fail spuriously, so a compare-exchange claim needs a retry loop
+ * and a bounded loop could leave a vertex unclaimed for its level; `atomicMin` has no such failure mode. The winners
+ * are packed by a Hillis-Steele inclusive scan of the workgroup's `won` flags and ONE `atomicAdd` per workgroup on
+ * `nextFrontierCount` reserves the block's span in the output vertex queue. The edge queue holds duplicates (a vertex
+ * with three frontier neighbours appears three times); exactly one claimant wins, exactly one appends, so the next
+ * frontier is duplicate-free by construction and no ownership dedupe follows (DEP-P8-B). Nothing here writes a
+ * parent (PD-24: the post-pass does). Uniformity (spec 3.5 rule 1): the guarded work writes locals, every barrier is
+ * reached unconditionally. 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 bfsContractWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;
+var<workgroup> base: u32;
+var<workgroup> wcount: u32;                                          // the clamped edge count on a two-phase level, 0 on any other
+
+@compute @workgroup_size(WG)
+fn bfs_contract(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x == 0u) { wcount = select(0u, atomicLoad(&counters[8]), atomicLoad(&counters[24]) == 1u); }   // edgeCount, clamped by role 1; the two-phase path only (the path word)
+    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers
+    let claim = atomicLoad(&counters[11]) + 1u;                      // the depth this level assigns
+    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 won = 0u;
+        var v = 0u;
+        if (i < count) {                                                 // guarded work into locals
+            v = edgeQueue[i];
+            let old = atomicMin(&depth[v], claim);
+            won = select(0u, 1u, old == INVALID_INDEX);                  // PD-6: the unique winner
+        }
+        sh[lid.x] = won;
+        workgroupBarrier();
+        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of won
+            var t = 0u;
+            if (lid.x >= s) { t = sh[lid.x - s]; }
+            workgroupBarrier();
+            sh[lid.x] = sh[lid.x] + t;
+            workgroupBarrier();
+        }
+        let inclusive = sh[lid.x];
+        if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }   // nextFrontierCount: one reservation per workgroup
+        workgroupBarrier();
+        if (won == 1u) { frontierOut[base + inclusive - 1u] = v; }
+        workgroupBarrier();                                              // sh and base are reused by the next block
+    }
+}
+`;

package/src/wgsl/bfs-fused.wgsl.ts

@@ -0,0 +1,77 @@
+/**
+ * The `bfs-fused` kernel body (design 8.4 "the fused variant", 6 row 8 "the workgroup-per-row tier", 8.10 "BFS
+ * fused expand-contract"; P8-T7, the P8 plan's PD-23 / PD-24): the expansion and the contraction of one level in
+ * ONE dispatch, chosen by `frontier-finalize` for a frontier below `P.fusedMax` entries (`path` 2) and for the retry
+ * of a level whose edge queue overflowed (`path` 4, PD-23). One WORKGROUP per frontier entry, the workgroups striding
+ * the entries by the dispatch's group count (`P.stride`): lane 0 reads the entry's row clipped
+ * to the bound arc window, adds its degree to `frontierDegreeSum` (Beamer's m_f, so P8-T8's test sees fused levels
+ * too), and every lane strips the row `WG` arcs at a time, applying `bfs-contract`'s claim inline --
+ * `atomicMin(&depth[v], level + 1)`, the invocation that observes `INVALID_INDEX` the unique winner (PD-6) -- and
+ * packing the strip's winners into the output vertex queue by the same Hillis-Steele scan and one `atomicAdd` per
+ * strip on `nextFrontierCount`. No edge queue is written or read, which is the whole win for a tiny frontier
+ * (Merrill's fleeting iterations) and what makes the overflow retry exact: the partial edge queue is never consulted.
+ * On a retry level `advance-expand` has already added the frontier's degree to `frontierDegreeSum`, so that word
+ * holds 2 x m_f for the level and the next boundary's Beamer test and degree-sum subtraction see the doubled value;
+ * reachable only with a faked capacity or an absurd graph, accepted and said here rather than guarded. Nothing here
+ * writes a parent (PD-24: the post-pass does), which is what keeps the kernel at the eight-storage-buffer budget
+ * with the four graph slots. Uniformity (spec 3.5 rule 1): the strip loop's bound and the row start are
+ * `workgroupUniformLoad`s, so every barrier of the per-strip append is in uniform control flow; the guarded claim
+ * writes locals; a trailing barrier protects `sh` and `base` before the next strip reuses them. The claim line and
+ * the scan are `bfs-contract`'s verbatim so a reader can diff the two bodies; the scan's comment differs on purpose
+ * (the sabotage rows need distinct find strings). 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 bfsFusedWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;
+var<workgroup> wdeg: u32;
+var<workgroup> wstart: u32;
+var<workgroup> base: u32;
+var<workgroup> wcount: u32;                                          // the frontier's length on a fused or retry level, 0 on any other
+
+@compute @workgroup_size(WG)
+fn bfs_fused(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let claim = atomicLoad(&counters[11]) + 1u;
+    if (lid.x == 0u) {
+        let path = atomicLoad(&counters[24]);                        // 2 the fused level, 4 the overflow retry (PD-23)
+        wcount = select(0u, atomicLoad(&counters[0]), path == 2u || path == 4u);
+    }
+    let count = workgroupUniformLoad(&wcount);                       // uniform: the entry loop below holds barriers
+    for (var g = group_id(wid); g < count; g = g + P.stride) {       // one workgroup per frontier entry; P.stride is the dispatch's GROUP count
+        if (lid.x == 0u) {
+            let u = frontierIn[g];
+            let a0 = max(rowPtr[u], P.arcBase);
+            let a1 = min(rowPtr[u + 1u], P.arcEnd);
+            let d = select(0u, a1 - a0, a1 > a0);
+            wdeg = d;
+            wstart = a0;
+            atomicAdd(&counters[2], d);                                  // frontierDegreeSum, so Beamer's test (P8-T8) sees fused levels too
+        }
+        let deg = workgroupUniformLoad(&wdeg);                           // uniform: the loop below may hold barriers
+        let start = workgroupUniformLoad(&wstart);
+        for (var p0 = 0u; p0 < deg; p0 = p0 + WG) {                      // strip the row WG arcs at a time
+            let p = p0 + lid.x;
+            var won = 0u;
+            var v = 0u;
+            if (p < deg) {                                               // guarded claim into locals
+                v = colIdx[start + p - P.arcBase];
+                let old = atomicMin(&depth[v], claim);
+                won = select(0u, 1u, old == INVALID_INDEX);
+            }
+            sh[lid.x] = won;
+            workgroupBarrier();
+            for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan of won (bfs-contract's, verbatim)
+                var t = 0u;
+                if (lid.x >= s) { t = sh[lid.x - s]; }
+                workgroupBarrier();
+                sh[lid.x] = sh[lid.x] + t;
+                workgroupBarrier();
+            }
+            let inclusive = sh[lid.x];
+            if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }
+            workgroupBarrier();
+            if (won == 1u) { frontierOut[base + inclusive - 1u] = v; }
+            workgroupBarrier();                                          // sh and base are reused by the next strip
+        }
+    }
+}
+`;

package/src/wgsl/bfs-unvisited-flags.wgsl.ts

@@ -0,0 +1,41 @@
+/**
+ * The `bfs-unvisited-flags` kernel body (design 8.4; P8-T8, the P8 plan's PD-18): the producer of the unvisited set
+ * Beamer's test is against, run ONCE per submit before the levels. It grid-strides over the vertices
+ * (`planGridStride(n)`, `P.stride` the plan's stride) and, per lane, counts the vertices still at `INVALID_INDEX`
+ * (`unvisitedCount`, word 5), sums their OUT-degrees (`unvisitedDegreeSum`, word 6: Beamer's m_u counts the edges
+ * top-down would examine), and flags the unvisited vertices with a non-zero IN-degree (`unvisitedListLen`, word 7:
+ * what the bottom-up sweep iterates, since a vertex nobody points at can never be claimed by it); the three lane
+ * sums are reduced by the prelude's `wg_reduce_u32` (its sum code) and ONE `atomicAdd` per word per workgroup lands
+ * them in the counters block. `compact` over an iota queue then turns `flags` into the unvisited list. The list is
+ * up to `MAX_LEVELS_PER_SUBMIT` levels stale by the time the sweep reads it: it holds vertices claimed since the
+ * rebuild, which the sweep skips on the `depth == INVALID_INDEX` test it makes anyway, so staleness costs a few
+ * wasted reads and never a wrong depth. Between rebuilds `frontier-finalize` maintains words 5 and 6 by subtraction
+ * (its JSDoc states the boundary rule). Uniformity (spec 3.5 rule 1): the loop holds no barrier, and the three
+ * reductions run unconditionally after it. 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 bfsUnvisitedFlagsWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bfs_unvisited_flags(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    var cnt = 0u;
+    var degSum = 0u;
+    var len = 0u;
+    for (var v = first; v < P.n; v = v + P.stride) {                 // no barrier inside: the trip count is per lane
+        let unv = depth[v] == INVALID_INDEX;
+        let listed = unv && (inDegree[v] != 0u);
+        flags[v] = select(0u, 1u, listed);
+        cnt = cnt + select(0u, 1u, unv);
+        degSum = degSum + select(0u, outDegree[v], unv);             // the OUT-degree: Beamer's m_u counts the edges top-down would examine
+        len = len + select(0u, 1u, listed);
+    }
+    let c = wg_reduce_u32(cnt, lid.x, 0u);                           // the prelude's workgroup sum (combine_u's sum code); uniform: after the loop
+    let d = wg_reduce_u32(degSum, lid.x, 0u);
+    let l = wg_reduce_u32(len, lid.x, 0u);
+    if (lid.x == 0u) {                                               // ONE atomic per word per workgroup
+        atomicAdd(&counters[5], c);
+        atomicAdd(&counters[6], d);
+        atomicAdd(&counters[7], l);
+    }
+}
+`;

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

@@ -0,0 +1,64 @@
+/**
+ * The `closeness-reduce` kernel body (design 8.4, 9.7 "integer distances before division"; P8-T11, the P8 plan's
+ * PD-13): the one-lane bookkeeping of the bit-parallel sweep, two roles by `P.role`. Role 0 is the level boundary,
+ * recorded BEFORE the level's `compact` and sweep: `done` is whether the previous level's compacted count is 0 (so the
+ * traversal ends one level after the last claim, one empty sweep and no wrong sum), then for every source `s` the
+ * claims the level just run made (`newCount[s]`) are folded into `reached[s]` and into the 64-bit `sum[s]` at the
+ * distance `level + 1` -- the product as a 16-bit split into a low and a high word, then the add with its carry --
+ * `newCount[s]` is zeroed and `level` advances. Role 1 is the seed of a batch: for the batch's `k = min(32, n -
+ * P.source)` sources, bit `s` into `visited[source_s]` and into the frontier region level 0 reads (region 1, since
+ * 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).
+ * 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 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
+        let k = min(32u, P.n - P.source);
+        for (var s = 0u; s < k; s = s + 1u) {
+            let v = P.source + s;
+            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[3u * P.bitsBase + v] = 1u;                          // flags: level 0's compact turns them into the list
+        }
+        atomicStore(&counters[0], k);                                // not done
+        atomicStore(&counters[11], U32_MAX);                         // level: the first boundary brings it to 0
+        atomicStore(&counters[15], 0u);                              // done
+        return;
+    }
+    // role 0: the level boundary -- done from the previous level's compacted count, then the accumulation
+    let count = atomicLoad(&counters[0]);
+    atomicStore(&counters[15], select(0u, 1u, count == 0u));
+    let level = atomicLoad(&counters[11]);
+    let d = level + 1u;                                              // the distance of the claims the level just run made
+    for (var s = 0u; s < 32u; s = s + 1u) {
+        let c = atomicLoad(&perSource[s]);                           // newCount[s]
+        atomicStore(&perSource[32u + s], atomicLoad(&perSource[32u + s]) + c);   // reached[s]
+        // sum[s] += c x d in 64 bits: the 16-bit split product (pLo, pHi), then the add with its carry
+        let cLo = c & 0xFFFFu;
+        let cHi = c >> 16u;
+        let dLo = d & 0xFFFFu;
+        let dHi = d >> 16u;
+        let ll = cLo * dLo;
+        let lh = cLo * dHi;
+        let hl = cHi * dLo;
+        let mid = (ll >> 16u) + (lh & 0xFFFFu) + (hl & 0xFFFFu);
+        let pLo = (ll & 0xFFFFu) | ((mid & 0xFFFFu) << 16u);
+        let pHi = (cHi * dHi) + (lh >> 16u) + (hl >> 16u) + (mid >> 16u);
+        var lo = atomicLoad(&perSource[64u + s]);                    // sumLo[s]
+        var hi = atomicLoad(&perSource[96u + s]);                    // sumHi[s]
+        let before = lo;
+        lo = lo + pLo;
+        hi = hi + pHi + select(0u, 1u, lo < before);
+        atomicStore(&perSource[64u + s], lo);
+        atomicStore(&perSource[96u + s], hi);
+        atomicStore(&perSource[s], 0u);
+    }
+    atomicStore(&counters[11], level + 1u);
+}
+`;

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

@@ -0,0 +1,95 @@
+/**
+ * The `closeness-sweep` kernel body (design 8.4 "32 sources per u32 word"; P8-T11, the P8 plan's PD-13 / DEP-P8-E):
+ * one level of the bit-parallel multi-source breadth-first search. The batch's state is one `bits` buffer of four
+ * regions of `P.bitsBase` words each -- `visited` at 0, the two frontier regions at `P.bitsBase` and `2 x P.bitsBase`
+ * (which one is the frontier and which the next swaps by the level's parity, `P.mode`, so nothing is copied between
+ * levels), `flags` at `3 x P.bitsBase` -- with bit `s` of word `v` meaning "source `s` has reached / is at / is next
+ * at `v`". The expansion is `advance-expand`'s block-mapped strip (P8-T5): each workgroup loads up to `WG` entries of
+ * the frontier LIST (the vertices any source is at, compacted from the flags by the host's `compact`), scans their
+ * degrees with the inlined Hillis-Steele scan of `bfs-contract` (this is not a twin kernel: `needs: []`), and every
+ * invocation strips the aggregate by binary search. The claim is inline: for the arc `(u, x)` the mask is the sources
+ * at `u` that have not reached `x`; `atomicOr` on `visited[x]` returns the bits this lane won (`fresh`), which go into
+ * the next region, set `flags[x]` (the flags region is part of the one atomic binding, so a plain store is a compile
+ * 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
+ * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const closenessSweepWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;                // the block's degrees, then their inclusive scan
+var<workgroup> rowStart: array<u32, WG>;          // the first bound arc of each entry's row
+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
+
+@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)
+    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers
+    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
+        let i = b0 + lid.x;                                          // this lane's frontier entry
+        var deg = 0u;
+        var start = 0u;
+        var u = 0u;
+        if (i < count) {                                                 // guarded loads into locals (3.5 rule 1)
+            u = frontierList[i];
+            let lo = max(rowPtr[u], P.arcBase);
+            let hi = min(rowPtr[u + 1u], P.arcEnd);
+            start = lo;
+            deg = select(0u, hi - lo, hi > lo);
+        }
+        if (lid.x < 32u) { atomicStore(&local[lid.x], 0u); }            // zeroed before the strip loop (WebGPU zero-initialises workgroup memory; said anyway)
+        sh[lid.x] = deg;
+        rowStart[lid.x] = start;
+        rowOf[lid.x] = u;
+        workgroupBarrier();
+        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of the degrees (bfs-contract's, inlined)
+            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 p = lid.x; p < aggregate; p = p + WG) {                 // strip [0, aggregate): lane j takes j, j + WG, ...
+            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 arc = rowStart[k] + (p - exclusive);
+            let x = colIdx[arc - P.arcBase];
+            let mask = atomicLoad(&bits[frontierBase + rowOf[k]]) & ~atomicLoad(&bits[x]);   // the sources at u that have not reached x
+            if (mask != 0u) {
+                let old = atomicOr(&bits[x], mask);                      // visited: the claim, one read-modify-write
+                let fresh = mask & ~old;                                 // the sources whose claim this lane won
+                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)
+                    var b = fresh;
+                    loop {                                               // one tally per set bit of fresh
+                        if (b == 0u) { break; }
+                        let s = firstTrailingBit(b);
+                        atomicAdd(&local[s], 1u);
+                        b = b & (b - 1u);
+                    }
+                }
+            }
+        }
+        workgroupBarrier();                                              // uniform: the loop's bound is the uniform aggregate
+        if (lid.x < 32u) {                                               // ONE global atomic per source per workgroup
+            let c = atomicLoad(&local[lid.x]);
+            if (c != 0u) { atomicAdd(&perSource[lid.x], c); }            // newCount[s]
+        }
+        workgroupBarrier();                                              // sh, rowStart, rowOf and local are reused by the next block
+    }
+}
+`;

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

@@ -0,0 +1,16 @@
+/**
+ * The `compact-scatter` kernel body (spec 6 row 4; P8-T3): the scatter step of `compact`, after the caller's flags
+ * have been exclusive-scanned into `offsets`. Every flagged entry lands at its offset, in queue order, so the output
+ * is bitwise reproducible; lane 0 writes the total -- the last offset plus the last flag -- into `outCount[P.outIndex]`
+ * (the block is bound whole and indexed because a four-byte word is never 256-aligned). The planner never dispatches
+ * this body for count 0, so `P.count - 1u` never wraps. Body only (spec 3.5, D9); normative text.
+ */
+export const compactScatterWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn compact_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i == 0u) { outCount[P.outIndex] = offsets[P.count - 1u] + flags[P.count - 1u]; }   // the exclusive scan's total; the planner never dispatches for count 0
+    if (i >= P.count) { return; }                                                          // no barrier follows
+    if (flags[i] != 0u) { out[offsets[i]] = queue[i]; }
+}
+`;

package/src/wgsl/dedupe-claim.wgsl.ts

@@ -0,0 +1,18 @@
+/**
+ * The `dedupe-claim` kernel body (spec 6 row 4; P8-T3): the first of `dedupe`'s two dispatches. Every entry stores
+ * its own index into `owner[queue[i]]` (relaxed atomics: between two dispatches last-writer-wins is well defined, so
+ * exactly one index per distinct vertex is the owner). The entry count is `P.count`, or the device word
+ * `counters[P.countIndex]` clamped to `P.count` when `P.countIndex` is not `U32_MAX` (the SSSP piles only know their
+ * count on the device). `owner` needs no reset between calls: a stale or garbage word is only ever read by an entry
+ * whose vertex a current entry has just overwritten. Body only (spec 3.5, D9); normative text.
+ */
+export const dedupeClaimWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn dedupe_claim(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    var count = P.count;
+    if (P.countIndex != U32_MAX) { count = min(atomicLoad(&counters[P.countIndex]), P.count); }   // a device-side count, clamped to the capacity
+    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {   // grid-stride; no barrier anywhere
+        atomicStore(&owner[queue[i]], i);
+    }
+}
+`;

package/src/wgsl/dedupe-filter.wgsl.ts

@@ -0,0 +1,45 @@
+/**
+ * The `dedupe-filter` kernel body (spec 6 row 4; P8-T3): the second of `dedupe`'s two dispatches, a SEPARATE
+ * dispatch because a plain store read back in the same one is a data race (WGSL 6.5.7). An entry survives iff
+ * `owner[queue[i]]` still holds its own index; the survivors are packed by a Hillis-Steele inclusive scan of the keep
+ * bits in workgroup memory (scan-block's rounds and barrier placement, verbatim) and ONE `atomicAdd` per workgroup on
+ * `outCount[P.outIndex]` for the block's aggregate, so the output is set-deterministic: the surviving SET is fixed,
+ * the order inside `out` follows the schedule. The entry count is `P.count` or the device word
+ * `outCount[P.countIndex]` clamped to it -- the same block and the same word `dedupe-claim` read. Every lane reaches
+ * every barrier: the guarded work goes into locals (spec 3.5 rule 1). Body only (spec 3.5, D9); normative text.
+ */
+export const dedupeFilterWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;
+var<workgroup> base: u32;
+var<workgroup> wcount: u32;
+
+@compute @workgroup_size(WG)
+fn dedupe_filter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x == 0u) {
+        var count = P.count;
+        if (P.countIndex != U32_MAX) { count = min(atomicLoad(&outCount[P.countIndex]), P.count); }   // the same count source as the claim
+        wcount = count;
+    }
+    let count = workgroupUniformLoad(&wcount);                                            // uniform: the block loop below holds barriers
+    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 keep = 0u;
+        var v = 0u;
+        if (i < count) { v = queue[i]; keep = select(0u, 1u, atomicLoad(&owner[v]) == i); }   // guarded work into locals
+        sh[lid.x] = keep;
+        workgroupBarrier();                                                                   // every lane, unconditionally (3.5 rule 1)
+        for (var s = 1u; s < WG; s = s * 2u) {                                                // Hillis-Steele inclusive scan of keep
+            var t = 0u;
+            if (lid.x >= s) { t = sh[lid.x - s]; }
+            workgroupBarrier();
+            sh[lid.x] = sh[lid.x] + t;
+            workgroupBarrier();
+        }
+        let inclusive = sh[lid.x];
+        if (lid.x == WG - 1u) { base = atomicAdd(&outCount[P.outIndex], inclusive); }         // ONE atomic per workgroup: the block's aggregate
+        workgroupBarrier();
+        if (keep == 1u) { out[base + inclusive - 1u] = v; }
+        workgroupBarrier();                                                                   // sh and base are reused by the next block
+    }
+}
+`;