@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.4

package/dist/src/wgsl/advance-expand.wgsl.js

@@ -0,0 +1,69 @@
+/**
+ * The `advance-expand` kernel body (design 6 row 8, 8.10 "BFS expand"; P8-T5, the P8 plan's PD-23): Gunrock's
+ * block-mapped expansion of a vertex frontier into the edge queue. Each workgroup loads up to `WG` frontier entries,
+ * reads their degrees clipped to the bound arc window `[P.arcBase, P.arcEnd)` (so the window-aware form of P8-T12
+ * changes nothing here), runs the prelude's INCLUSIVE workgroup scan `wg_scan_u32` over those degrees -- the subgroup
+ * form when the device has the feature, the Hillis-Steele form otherwise, which is the ONLY text that differs between
+ * the twin's two compilations -- and then every invocation strips the range `[0, aggregate)` with a binary search
+ * (`upper_bound`) over the scanned degrees to find which entry its arc belongs to. One `atomicAdd` per WORKGROUP
+ * reserves the block's span in the queue (`edgeCount`), the same aggregate lands in `edgeCountUnclamped` (the overflow
+ * detector, never clamped) and in `frontierDegreeSum` (Beamer's m_f); a lane whose queue position is at or past
+ * `P.edgeCapacity` writes nothing (the clamp). The queue holds the TARGET vertex of each arc only (PD-24: `parent`
+ * comes from the post-pass). Uniformity (spec 3.5 rule 1): the guarded loads write locals, the scan call and the
+ * `workgroupUniformLoad` sit unconditionally after the guard, and the strip loop is bounded by a uniform value.
+ * There is no `TIER` override: a hub row is balanced over all `WG` lanes inside its block, and the small-frontier
+ * workgroup-per-row structure is `bfs-fused` (P8-T7). 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 advanceExpandWgsl = /* 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> base: u32;                   // the block's reserved span in the edge queue
+var<workgroup> wcount: u32;                 // the frontier's length on a two-phase level, 0 on any other
+
+@compute @workgroup_size(WG)
+fn advance_expand(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x == 0u) { wcount = select(0u, atomicLoad(&counters[0]), atomicLoad(&counters[24]) == 1u); }   // frontierCount, on the two-phase path only (the path word)
+    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 (a direct dispatch of the plan's groups)
+        let i = b0 + lid.x;                                          // this lane's frontier entry
+        var deg = 0u;
+        var start = 0u;
+        if (i < count) {                                                 // guarded loads into locals (3.5 rule 1)
+            let v = frontierIn[i];
+            let lo = max(rowPtr[v], P.arcBase);                          // the row clipped to the bound window (P8-T12)
+            let hi = min(rowPtr[v + 1u], P.arcEnd);
+            start = lo;
+            deg = select(0u, hi - lo, hi > lo);
+        }
+        let inclusive = wg_scan_u32(deg, lid.x);                         // the prelude's inclusive scan in LANE order (P8-T1 Step 5); the twin
+        sh[lid.x] = inclusive;                                           // sh is monotone in lid.x, the index the binary search walks
+        rowStart[lid.x] = start;
+        workgroupBarrier();
+        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);              // uniform; includes a barrier
+        if (lid.x == 0u) {
+            base = atomicAdd(&counters[8], aggregate);                   // edgeCount: ONE reservation per workgroup, not one per arc
+            atomicAdd(&counters[9], aggregate);                          // edgeCountUnclamped: the overflow detector (PD-23)
+            atomicAdd(&counters[2], aggregate);                          // frontierDegreeSum: Beamer's m_f (P8-T8)
+        }
+        workgroupBarrier();
+        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 q = base + p;
+            if (q < P.edgeCapacity) { edgeQueue[q] = colIdx[arc - P.arcBase]; }   // the clamp of PD-23; the queue holds the target vertex only (PD-24)
+        }
+        workgroupBarrier();                                              // sh, rowStart and base are reused by the next block
+    }
+}
+`;
+//# sourceMappingURL=advance-expand.wgsl.js.map

package/dist/src/wgsl/advance-expand.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-expand.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/advance-expand.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkD3C,CAAC"}

package/dist/src/wgsl/bf-relax.wgsl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `bf-relax` kernel body (design 8.4 "Bellman-Ford"; P8-T10, the P8 plan's PD-12 / PD-22 / PD-27 / DEP-P8-E):
+ * one edge-parallel relaxation round over the `edgeList()` view -- every logical edge once, in declared orientation,
+ * and under `UNDIRECTED` the other direction too, because an undirected edge has ONE weight (read through its
+ * forward arc, `weights[edgeToArc[e]]`, from the run's arc-indexed vector: the snapshot's column or the uploaded
+ * override). `dist` is `array<atomic<u32>>` holding the f32 bit patterns (`F32_INF_BITS` = unreached, tested as the
+ * pattern: `bitcast<f32>(F32_INF_BITS)` is a const-expression Tint rejects). `atomicMin` on the patterns is `min` on
+ * the values for NON-NEGATIVE floats only (PD-9); with a negative distance the bit-pattern order reverses, so the
+ * claim is a compare-exchange loop on the pattern: read, compute, compare as floats, try to exchange. WGSL lets
+ * `atomicCompareExchangeWeak` fail spuriously, so the loop is BOUNDED (PD-12: `P.maxRetries`, the driver's
+ * `MAX_RETRIES`; contention is per vertex, not global) and a lane that exhausts it sets `flags[1]`
+ * (`retryExhausted`): the driver treats the round as changed and runs on, so the lost update is retried by the next
+ * round, which examines every edge anyway; a bound hit in the decision round is E_VALIDATION, never a guess. A
+ * successful exchange sets `flags[0]` (`changed`); the driver stops when a batch of rounds changed nothing, and a
+ * change in the round after `n - 1` is the negative cycle. `P.cutoffBits` is the CPU port's `dv <= cutoff` guard
+ * (`+Inf` when absent; with negative weights a negative cutoff legitimately relaxes). Grid-strided over
+ * `planGridStride(edgeCount)` with `P.stride` the plan's stride; no barrier anywhere, so the loops may be per lane.
+ * The whole arc array is bound (never windowed, DEP-P8-E). 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 bfRelaxWgsl = "\nfn relax(v: u32, nd: f32) {\n    var cur = atomicLoad(&dist[v]);\n    var tries = 0u;\n    loop {\n        if (!(nd < bitcast<f32>(cur))) { break; }                     // no improvement; +Inf is greater than every finite nd\n        let r = atomicCompareExchangeWeak(&dist[v], cur, bitcast<u32>(nd));\n        if (r.exchanged) { atomicStore(&flags[0], 1u); break; }        // changed\n        cur = r.old_value;\n        tries = tries + 1u;\n        if (tries >= P.maxRetries) { atomicStore(&flags[1], 1u); break; }   // retryExhausted (PD-12)\n    }\n}\n\n@compute @workgroup_size(WG)\nfn bf_relax(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let first = linear_id(wid, lid.x);\n    let cutoff = bitcast<f32>(P.cutoffBits);\n    for (var e = first; e < P.edgeCount; e = e + P.stride) {          // each logical edge once (edgeList)\n        let u = edgeSrc[e];\n        let v = edgeDst[e];\n        let w = weights[edgeToArc[e]];                                 // the edge's weight through its forward arc\n        let du = atomicLoad(&dist[u]);\n        if (du != F32_INF_BITS) {                                      // unreached is tested as the bit pattern, as sssp-pred does\n            let nd = bitcast<f32>(du) + w;\n            if (nd <= cutoff) { relax(v, nd); }\n        }\n        if (UNDIRECTED) {                                              // the other direction of an undirected edge\n            let dv = atomicLoad(&dist[v]);\n            if (dv != F32_INF_BITS) {\n                let nd = bitcast<f32>(dv) + w;\n                if (nd <= cutoff) { relax(u, nd); }\n            }\n        }\n    }\n}\n";
+//# sourceMappingURL=bf-relax.wgsl.d.ts.map

package/dist/src/wgsl/bf-relax.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bf-relax.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bf-relax.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,8oDAoCvB,CAAC"}

package/dist/src/wgsl/bf-relax.wgsl.js

@@ -0,0 +1,58 @@
+/**
+ * The `bf-relax` kernel body (design 8.4 "Bellman-Ford"; P8-T10, the P8 plan's PD-12 / PD-22 / PD-27 / DEP-P8-E):
+ * one edge-parallel relaxation round over the `edgeList()` view -- every logical edge once, in declared orientation,
+ * and under `UNDIRECTED` the other direction too, because an undirected edge has ONE weight (read through its
+ * forward arc, `weights[edgeToArc[e]]`, from the run's arc-indexed vector: the snapshot's column or the uploaded
+ * override). `dist` is `array<atomic<u32>>` holding the f32 bit patterns (`F32_INF_BITS` = unreached, tested as the
+ * pattern: `bitcast<f32>(F32_INF_BITS)` is a const-expression Tint rejects). `atomicMin` on the patterns is `min` on
+ * the values for NON-NEGATIVE floats only (PD-9); with a negative distance the bit-pattern order reverses, so the
+ * claim is a compare-exchange loop on the pattern: read, compute, compare as floats, try to exchange. WGSL lets
+ * `atomicCompareExchangeWeak` fail spuriously, so the loop is BOUNDED (PD-12: `P.maxRetries`, the driver's
+ * `MAX_RETRIES`; contention is per vertex, not global) and a lane that exhausts it sets `flags[1]`
+ * (`retryExhausted`): the driver treats the round as changed and runs on, so the lost update is retried by the next
+ * round, which examines every edge anyway; a bound hit in the decision round is E_VALIDATION, never a guess. A
+ * successful exchange sets `flags[0]` (`changed`); the driver stops when a batch of rounds changed nothing, and a
+ * change in the round after `n - 1` is the negative cycle. `P.cutoffBits` is the CPU port's `dv <= cutoff` guard
+ * (`+Inf` when absent; with negative weights a negative cutoff legitimately relaxes). Grid-strided over
+ * `planGridStride(edgeCount)` with `P.stride` the plan's stride; no barrier anywhere, so the loops may be per lane.
+ * The whole arc array is bound (never windowed, DEP-P8-E). 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 bfRelaxWgsl = /* wgsl */ `
+fn relax(v: u32, nd: f32) {
+    var cur = atomicLoad(&dist[v]);
+    var tries = 0u;
+    loop {
+        if (!(nd < bitcast<f32>(cur))) { break; }                     // no improvement; +Inf is greater than every finite nd
+        let r = atomicCompareExchangeWeak(&dist[v], cur, bitcast<u32>(nd));
+        if (r.exchanged) { atomicStore(&flags[0], 1u); break; }        // changed
+        cur = r.old_value;
+        tries = tries + 1u;
+        if (tries >= P.maxRetries) { atomicStore(&flags[1], 1u); break; }   // retryExhausted (PD-12)
+    }
+}
+
+@compute @workgroup_size(WG)
+fn bf_relax(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    let cutoff = bitcast<f32>(P.cutoffBits);
+    for (var e = first; e < P.edgeCount; e = e + P.stride) {          // each logical edge once (edgeList)
+        let u = edgeSrc[e];
+        let v = edgeDst[e];
+        let w = weights[edgeToArc[e]];                                 // the edge's weight through its forward arc
+        let du = atomicLoad(&dist[u]);
+        if (du != F32_INF_BITS) {                                      // unreached is tested as the bit pattern, as sssp-pred does
+            let nd = bitcast<f32>(du) + w;
+            if (nd <= cutoff) { relax(v, nd); }
+        }
+        if (UNDIRECTED) {                                              // the other direction of an undirected edge
+            let dv = atomicLoad(&dist[v]);
+            if (dv != F32_INF_BITS) {
+                let nd = bitcast<f32>(dv) + w;
+                if (nd <= cutoff) { relax(u, nd); }
+            }
+        }
+    }
+}
+`;
+//# sourceMappingURL=bf-relax.wgsl.js.map

package/dist/src/wgsl/bf-relax.wgsl.js.map

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

package/dist/src/wgsl/bfs-bitset-build.wgsl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `bfs-bitset-build` kernel body (design 8.4 "the bitset frontier"; P8-T8): the vertex-list-to-bitset hand-off
+ * of a bottom-up level. One invocation per entry of the input frontier (`frontierCount`, word 0), each `atomicOr`ing
+ * its vertex's bit into the `ceil(n / 32)`-word bitset at `P.bitsBase` inside the `sweepIn` buffer (the region a
+ * `fill` zeroed just before, on every level). The design's "bulk non-atomic path when the frontier is >= 40% of
+ * n" iterates WORDS of a frontier that is already a bitset; this frontier is a vertex list, so a word-owning store
+ * has nothing to iterate and `atomicOr` per vertex is the whole kernel. The sweep appends what it claims as a plain
+ * vertex list, exactly as the contract does, and writes no second bitset: the next level's bits come from this
+ * kernel running over that list, so one representation of a frontier (a vertex list plus a count) serves the whole
+ * phase and the hand-off in either direction is free. The early return keys on a counter and `local_invocation_id`
+ * with no barrier after it (spec 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 bfsBitsetBuildWgsl = "\n@compute @workgroup_size(WG)\nfn bfs_bitset_build(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let count = select(0u, atomicLoad(&counters[0]), atomicLoad(&counters[24]) == 3u);   // frontierCount, on the bottom-up path only (the path word)\n    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {   // grid-stride; no barrier anywhere\n        let v = frontierIn[i];\n        atomicOr(&bits[P.bitsBase + (v >> 5u)], 1u << (v & 31u));\n    }\n}\n";
+//# sourceMappingURL=bfs-bitset-build.wgsl.d.ts.map

package/dist/src/wgsl/bfs-bitset-build.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-bitset-build.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bfs-bitset-build.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,mgBAS9B,CAAC"}

package/dist/src/wgsl/bfs-bitset-build.wgsl.js

@@ -0,0 +1,24 @@
+/**
+ * The `bfs-bitset-build` kernel body (design 8.4 "the bitset frontier"; P8-T8): the vertex-list-to-bitset hand-off
+ * of a bottom-up level. One invocation per entry of the input frontier (`frontierCount`, word 0), each `atomicOr`ing
+ * its vertex's bit into the `ceil(n / 32)`-word bitset at `P.bitsBase` inside the `sweepIn` buffer (the region a
+ * `fill` zeroed just before, on every level). The design's "bulk non-atomic path when the frontier is >= 40% of
+ * n" iterates WORDS of a frontier that is already a bitset; this frontier is a vertex list, so a word-owning store
+ * has nothing to iterate and `atomicOr` per vertex is the whole kernel. The sweep appends what it claims as a plain
+ * vertex list, exactly as the contract does, and writes no second bitset: the next level's bits come from this
+ * kernel running over that list, so one representation of a frontier (a vertex list plus a count) serves the whole
+ * phase and the hand-off in either direction is free. The early return keys on a counter and `local_invocation_id`
+ * with no barrier after it (spec 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 bfsBitsetBuildWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bfs_bitset_build(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let count = select(0u, atomicLoad(&counters[0]), atomicLoad(&counters[24]) == 3u);   // frontierCount, on the bottom-up path only (the path word)
+    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {   // grid-stride; no barrier anywhere
+        let v = frontierIn[i];
+        atomicOr(&bits[P.bitsBase + (v >> 5u)], 1u << (v & 31u));
+    }
+}
+`;
+//# sourceMappingURL=bfs-bitset-build.wgsl.js.map

package/dist/src/wgsl/bfs-bitset-build.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-bitset-build.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bfs-bitset-build.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;;;;;;;;;CAS5C,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 declare const bfsBottomUpWgsl = "\nvar<workgroup> sh: array<u32, WG>;\nvar<workgroup> base: u32;\nvar<workgroup> wcount: u32;                                          // the unvisited list's length on a bottom-up level, 0 on any other\n\n@compute @workgroup_size(WG)\nfn bfs_bottom_up(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let claim = atomicLoad(&counters[11]) + 1u;\n    if (lid.x == 0u) { wcount = select(0u, atomicLoad(&counters[7]), atomicLoad(&counters[24]) == 3u); }   // unvisitedListLen, on the bottom-up path only (the path word)\n    let len = workgroupUniformLoad(&wcount);                         // uniform: the block loop below holds barriers\n    for (var b0 = group_id(wid) * WG; b0 < len; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries\n        let i = b0 + lid.x;\n        var won = 0u;\n        var v = 0u;\n        var reads = 0u;\n        if (i < len) {                                                   // guarded work into locals\n            v = sweepIn[i];\n            if (atomicLoad(&depth[v]) == INVALID_INDEX) {                // a stale entry, claimed since the rebuild, is skipped\n                let end = min(rowPtr[v + 1u], P.arcEnd);\n                for (var a = max(rowPtr[v], P.arcBase); a < end; a = a + 1u) {   // in-neighbours through the reverse core\n                    reads = reads + 1u;\n                    let u = colIdx[a - P.arcBase];\n                    if (mask_bit(sweepIn[P.bitsBase + (u >> 5u)], u)) { won = 1u; break; }   // the early exit: a real break, never a flag\n                }\n            }\n        }\n        sh[lid.x] = won;\n        workgroupBarrier();\n        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of won (bfs-contract's)\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 inclusive = sh[lid.x];\n        let readsTotal = wg_reduce_u32(reads, lid.x, 0u);                // arcsScanned, one atomic per workgroup (the sabotage witness, Step 6)\n        if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }\n        if (lid.x == 0u) { atomicAdd(&counters[16], readsTotal); }\n        workgroupBarrier();\n        if (won == 1u) {\n            atomicStore(&depth[v], claim);                               // no claim race: the list holds v once and the sweep is vertex-parallel\n            frontierOut[base + inclusive - 1u] = v;\n        }\n        workgroupBarrier();                                              // sh and base are reused by the next block\n    }\n}\n";
+//# sourceMappingURL=bfs-bottom-up.wgsl.d.ts.map

package/dist/src/wgsl/bfs-bottom-up.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-bottom-up.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bfs-bottom-up.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,8pFA+C3B,CAAC"}

package/dist/src/wgsl/bfs-bottom-up.wgsl.js

@@ -0,0 +1,67 @@
+/**
+ * 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
+    }
+}
+`;
+//# sourceMappingURL=bfs-bottom-up.wgsl.js.map

package/dist/src/wgsl/bfs-bottom-up.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-bottom-up.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bfs-bottom-up.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CzC,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 declare const bfsContractWgsl = "\nvar<workgroup> sh: array<u32, WG>;\nvar<workgroup> base: u32;\nvar<workgroup> wcount: u32;                                          // the clamped edge count on a two-phase level, 0 on any other\n\n@compute @workgroup_size(WG)\nfn bfs_contract(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    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)\n    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers\n    let claim = atomicLoad(&counters[11]) + 1u;                      // the depth this level assigns\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 won = 0u;\n        var v = 0u;\n        if (i < count) {                                                 // guarded work into locals\n            v = edgeQueue[i];\n            let old = atomicMin(&depth[v], claim);\n            won = select(0u, 1u, old == INVALID_INDEX);                  // PD-6: the unique winner\n        }\n        sh[lid.x] = won;\n        workgroupBarrier();\n        for (var s = 1u; s < WG; s = s * 2u) {                           // Hillis-Steele inclusive scan of won\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 inclusive = sh[lid.x];\n        if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }   // nextFrontierCount: one reservation per workgroup\n        workgroupBarrier();\n        if (won == 1u) { frontierOut[base + inclusive - 1u] = v; }\n        workgroupBarrier();                                              // sh and base are reused by the next block\n    }\n}\n";
+//# sourceMappingURL=bfs-contract.wgsl.d.ts.map

package/dist/src/wgsl/bfs-contract.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-contract.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bfs-contract.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,67DAmC3B,CAAC"}

package/dist/src/wgsl/bfs-contract.wgsl.js

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

package/dist/src/wgsl/bfs-contract.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-contract.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bfs-contract.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCzC,CAAC"}

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

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const bfsFusedWgsl = "\nvar<workgroup> sh: array<u32, WG>;\nvar<workgroup> wdeg: u32;\nvar<workgroup> wstart: u32;\nvar<workgroup> base: u32;\nvar<workgroup> wcount: u32;                                          // the frontier's length on a fused or retry level, 0 on any other\n\n@compute @workgroup_size(WG)\nfn bfs_fused(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let claim = atomicLoad(&counters[11]) + 1u;\n    if (lid.x == 0u) {\n        let path = atomicLoad(&counters[24]);                        // 2 the fused level, 4 the overflow retry (PD-23)\n        wcount = select(0u, atomicLoad(&counters[0]), path == 2u || path == 4u);\n    }\n    let count = workgroupUniformLoad(&wcount);                       // uniform: the entry loop below holds barriers\n    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\n        if (lid.x == 0u) {\n            let u = frontierIn[g];\n            let a0 = max(rowPtr[u], P.arcBase);\n            let a1 = min(rowPtr[u + 1u], P.arcEnd);\n            let d = select(0u, a1 - a0, a1 > a0);\n            wdeg = d;\n            wstart = a0;\n            atomicAdd(&counters[2], d);                                  // frontierDegreeSum, so Beamer's test (P8-T8) sees fused levels too\n        }\n        let deg = workgroupUniformLoad(&wdeg);                           // uniform: the loop below may hold barriers\n        let start = workgroupUniformLoad(&wstart);\n        for (var p0 = 0u; p0 < deg; p0 = p0 + WG) {                      // strip the row WG arcs at a time\n            let p = p0 + lid.x;\n            var won = 0u;\n            var v = 0u;\n            if (p < deg) {                                               // guarded claim into locals\n                v = colIdx[start + p - P.arcBase];\n                let old = atomicMin(&depth[v], claim);\n                won = select(0u, 1u, old == INVALID_INDEX);\n            }\n            sh[lid.x] = won;\n            workgroupBarrier();\n            for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan of won (bfs-contract's, verbatim)\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 inclusive = sh[lid.x];\n            if (lid.x == WG - 1u) { base = atomicAdd(&counters[1], inclusive); }\n            workgroupBarrier();\n            if (won == 1u) { frontierOut[base + inclusive - 1u] = v; }\n            workgroupBarrier();                                          // sh and base are reused by the next strip\n        }\n    }\n}\n";
+//# sourceMappingURL=bfs-fused.wgsl.d.ts.map

package/dist/src/wgsl/bfs-fused.wgsl.d.ts.map

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

package/dist/src/wgsl/bfs-fused.wgsl.js

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

package/dist/src/wgsl/bfs-fused.wgsl.js.map

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

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

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const bfsUnvisitedFlagsWgsl = "\n@compute @workgroup_size(WG)\nfn bfs_unvisited_flags(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let first = linear_id(wid, lid.x);\n    var cnt = 0u;\n    var degSum = 0u;\n    var len = 0u;\n    for (var v = first; v < P.n; v = v + P.stride) {                 // no barrier inside: the trip count is per lane\n        let unv = depth[v] == INVALID_INDEX;\n        let listed = unv && (inDegree[v] != 0u);\n        flags[v] = select(0u, 1u, listed);\n        cnt = cnt + select(0u, 1u, unv);\n        degSum = degSum + select(0u, outDegree[v], unv);             // the OUT-degree: Beamer's m_u counts the edges top-down would examine\n        len = len + select(0u, 1u, listed);\n    }\n    let c = wg_reduce_u32(cnt, lid.x, 0u);                           // the prelude's workgroup sum (combine_u's sum code); uniform: after the loop\n    let d = wg_reduce_u32(degSum, lid.x, 0u);\n    let l = wg_reduce_u32(len, lid.x, 0u);\n    if (lid.x == 0u) {                                               // ONE atomic per word per workgroup\n        atomicAdd(&counters[5], c);\n        atomicAdd(&counters[6], d);\n        atomicAdd(&counters[7], l);\n    }\n}\n";
+//# sourceMappingURL=bfs-unvisited-flags.wgsl.d.ts.map

package/dist/src/wgsl/bfs-unvisited-flags.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-unvisited-flags.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/bfs-unvisited-flags.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB,2rCAwBjC,CAAC"}

package/dist/src/wgsl/bfs-unvisited-flags.wgsl.js

@@ -0,0 +1,42 @@
+/**
+ * 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);
+    }
+}
+`;
+//# sourceMappingURL=bfs-unvisited-flags.wgsl.js.map

package/dist/src/wgsl/bfs-unvisited-flags.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bfs-unvisited-flags.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/bfs-unvisited-flags.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;CAwB/C,CAAC"}