@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.5

package/dist/src/wgsl/frontier-finalize.wgsl.js

@@ -0,0 +1,164 @@
+/**
+ * The `frontier-finalize` kernel body (design 5.4, 6 row 7; P8-T4, the P8 plan's PD-3 / PD-23 / DEP-P8-C): the
+ * device-side selector of the frontier family. One workgroup, one lane, no barrier after the early return (spec 3.5
+ * rule 1). It is recorded TWICE per level, in two roles chosen by `P.role`, because a level's counts become known at
+ * two moments: role 0 runs at the START of a level -- rotates `nextFrontierCount` into `frontierCount`, advances
+ * `level`, decides `done` (an empty frontier, or `level >= P.maxDepth`) and chooses the path; role 1 runs once the
+ * edge queue is filled -- clamps `edgeCount` to `P.edgeCapacity`, or, when `edgeCountUnclamped` exceeds the
+ * capacity, switches the path to the fused retry over `frontierCount` (PD-23). The decision is ONE word of the
+ * counters block, `path` (word 24): 0 nothing (done, or a level past the end), 1 two-phase, 2 fused, 3 bottom-up,
+ * 4 the fused retry (role 1), 5 a near SSSP round, 6 a far one (role 2). Every level kernel is a direct grid-stride
+ * dispatch that reads that word first and runs only when it names it (decision record
+ * design/decisions/2026-09-25-frontier-kernels-dispatch-directly.md: Dawn's validation of an indirect dispatch cost
+ * about 0.4 ms of device time each, and the seven indirect slots this kernel once wrote per level were 97 % of a
+ * traversal's wall time; the slots and their args buffer are gone). Two rules: a boundary that finds `done` set
+ * moves no counter word (the host records levels past the end); role 1 counts a two-phase level only when role 0
+ * chose one, which it reads from the path word (a storage write of one dispatch is visible to the next of the same
+ * pass).
+ *
+ * Roles 2 and 3 are the SSSP round boundary of the near-far loop (P8-T9, PD-20), over the same block read in its
+ * SSSP sense (word 1 the raw near half's appends, 21 the raw far half's, 0 and 20 the deduped pile counts, 22 the
+ * threshold, 23 the delta, 4 the previous threshold, 14 the round's mode): role 2 finds a non-empty raw near half
+ * and sizes the near dedupe (count word 1, output word 0; the dedupe's count in word 8) in mode 0; finds it empty
+ * and the far half not, raises the threshold by the delta (one f32 add; an add that returns the threshold
+ * unchanged sets `done 3`, the host's E_UNSUPPORTED), remembers the previous threshold in word 4 and sizes the far
+ * dedupe (count word 21, output word 20; the dedupe's count in word 9) in mode 1; finds both empty and sets
+ * `done 1`; and finds a raw half above the capacity and sets `done 2` (the host's E_TOO_LARGE). It counts a round in
+ * `level` when it picks a mode and NOT at the done boundary, so `level` at the end is the number of relax rounds
+ * dispatched; a boundary that finds `done` set obeys rule 1. Role 3 runs once the dedupe has landed and restarts the
+ * raw half the round consumed: mode 0 restarts the raw near half (word 1 to 0), mode 1 the raw far half (word 21
+ * to 0); the relax kernels size themselves from words 0 and 20.
+ *
+ * Beamer's test (P8-T8, PD-21), evaluated at every boundary BEFORE the `done` branch (so a switch can be counted at
+ * the done boundary too, which the host model of the tests mirrors): top-down switches to bottom-up when
+ * `frontierDegreeSum > unvisitedDegreeSum / alpha` (u32 division; alpha the host's `max(1, floor(arcCount / n))`
+ * unless tuned) and the frontier is growing (`next > frontierCount`); bottom-up switches back when
+ * `next * beta < unvisitedCount` (a u32 product, wrapping only above 178M vertices, which no admitted device
+ * reaches) and the frontier is shrinking; `P.mode == 1` (the driver's `"top-down"`) pins the direction at 0. Every
+ * change is counted in `switches`, the previous direction is word 14. The two unvisited words the test reads are
+ * rebuilt exactly once per submit by `bfs-unvisited-flags` (PD-18) and maintained here by subtraction: the count is
+ * subtracted from the SECOND boundary of a submit on and the degree sum from the THIRD on, because a boundary may
+ * only subtract what the submit's rebuild counted, and the frontier whose degree sum the second boundary holds was
+ * claimed before the rebuild ran (the rebuild counts the vertices unclaimed when it runs; the frontier rotated in at
+ * boundary 0 was claimed by the previous submit's last contract, so it was never in the sum; boundary b subtracts
+ * `next = |F_b|`, inside the sum iff b >= 1, and `degSum = deg(F_{b-1})`, inside it iff b >= 2). The degree sum is
+ * the "unvisited degree estimate" of the design rather than an exact count for two reasons: it is one level stale
+ * (a frontier's degree sum is only known once it has been expanded), and a bottom-up level expands nothing, so the
+ * word stops falling while bottom-up runs and overstates the set afterwards. The bias is one-directional -- an
+ * overstated m_u makes the switch INTO bottom-up harder, never easier -- and the next submit's rebuild makes it
+ * exact again. 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 frontierFinalizeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn frontier_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x != 0u) { return; }                                       // one lane; no barrier follows (3.5 rule 1)
+    if (P.role == 0u) {                                                // the level boundary
+        if (atomicLoad(&counters[15]) != 0u) {                         // done already: a no-op level the host recorded past the end
+            atomicStore(&counters[24], 0u);                            // the path word is the only word that moves (P8-T6's levels formula reads the rest)
+            return;
+        }
+        let finished = atomicLoad(&counters[0]);
+        let next = atomicLoad(&counters[1]);
+        let degSum = atomicLoad(&counters[2]);
+        atomicStore(&counters[3], finished);                           // prevFrontierCount
+        atomicStore(&counters[4], degSum);                             // prevDegreeSum
+        atomicStore(&counters[0], next);                               // the rotation
+        atomicStore(&counters[1], 0u);
+        atomicStore(&counters[2], 0u);
+        atomicStore(&counters[8], 0u);                                 // edgeCount
+        atomicStore(&counters[9], 0u);                                 // edgeCountUnclamped
+        atomicStore(&counters[12], atomicLoad(&counters[12]) + next);  // visitedCount
+        if (P.firstOfSubmit >= 1u) {                                   // b = the boundary's index inside its submit, clamped to 2 (P8-T8, PD-18)
+            atomicStore(&counters[5], atomicLoad(&counters[5]) - next);    // unvisitedCount (exact): F_b was inside the submit's rebuilt sum iff b >= 1
+        }
+        if (P.firstOfSubmit >= 2u) {
+            atomicStore(&counters[6], atomicLoad(&counters[6]) - degSum);  // unvisitedDegreeSum (one level stale): F_{b-1} was inside it iff b >= 2
+        }
+        let level = atomicLoad(&counters[11]) + 1u;                    // the seed is U32_MAX, so the first boundary lands on 0
+        atomicStore(&counters[11], level);
+        let done = (next == 0u) || (level >= P.maxDepth);
+        atomicStore(&counters[15], select(0u, 1u, done));
+        var direction = atomicLoad(&counters[14]);
+        if (P.mode == 1u) {
+            direction = 0u;                                                 // top-down only (the test seam)
+        } else if (direction == 0u) {
+            if (degSum > atomicLoad(&counters[6]) / P.alpha && next > finished) { direction = 1u; }   // m_f > m_u / alpha and growing
+        } else {
+            if (next * P.beta < atomicLoad(&counters[5]) && next < finished) { direction = 0u; }      // next * beta < unvisited and shrinking
+        }
+        if (direction != atomicLoad(&counters[14])) { atomicStore(&counters[13], atomicLoad(&counters[13]) + 1u); }   // switches
+        var path = 0u;                                                 // word 24: what the level's kernels run (0 nothing, 1 two-phase, 2 fused, 3 bottom-up; role 1 writes 4 for the retry)
+        if (done) {
+            path = 0u;
+        } else if (direction == 1u) {                                  // the bottom-up level (P8-T8): the bits fill, the bitset build, the sweep
+            path = 3u;
+            atomicStore(&counters[19], atomicLoad(&counters[19]) + 1u);
+        } else if (next < P.fusedMax) {                                // P8-T7 makes this branch reachable (fusedMax is 0 until then)
+            path = 2u;                                                 // bfs-fused: one WORKGROUP per frontier entry
+            atomicStore(&counters[17], atomicLoad(&counters[17]) + 1u);
+        } else {
+            path = 1u;                                                 // advance-expand, then role 1 and bfs-contract
+        }
+        atomicStore(&counters[14], direction);
+        atomicStore(&counters[24], path);
+    } else if (P.role == 1u) {                                         // the edge queue is filled
+        if (atomicLoad(&counters[24]) != 1u) {                         // role 0 did not choose the two-phase path (done, fused or bottom-up): nothing to clamp, nothing to count
+            return;
+        }
+        let clamped = min(atomicLoad(&counters[8]), P.edgeCapacity);
+        atomicStore(&counters[8], clamped);
+        if (atomicLoad(&counters[9]) > P.edgeCapacity) {               // PD-23: the fused retry
+            atomicStore(&counters[24], 4u);                            // the path word: bfs-fused runs the retry over frontierCount, bfs-contract nothing
+            atomicStore(&counters[10], atomicLoad(&counters[10]) + 1u);
+            atomicStore(&counters[17], atomicLoad(&counters[17]) + 1u);
+        } else {
+            atomicStore(&counters[18], atomicLoad(&counters[18]) + 1u);   // twoPhaseLevels counts the CHOICE role 0 made, even for zero edges (P8-T7 Step 4's invariant)
+        }
+    } else if (P.role == 2u) {                                         // the SSSP round boundary (P8-T9, PD-20): which pile this round relaxes
+        atomicStore(&counters[8], 0u);                                 // the dedupe counts (words 8 and 9, the SSSP sense) and the path word: nothing unless a pile is chosen below
+        atomicStore(&counters[9], 0u);
+        atomicStore(&counters[24], 0u);
+        if (atomicLoad(&counters[15]) != 0u) {                         // done already: a no-op round the host recorded past the end (rule 1)
+            return;
+        }
+        let nearRaw = atomicLoad(&counters[1]);                        // the raw near half's appends, unclamped
+        let farRaw = atomicLoad(&counters[21]);                        // the raw far half's appends, unclamped
+        if (nearRaw > P.edgeCapacity || farRaw > P.edgeCapacity) {     // a pile overflowed its half: the host raises E_TOO_LARGE
+            atomicStore(&counters[15], 2u);
+            return;
+        }
+        if (nearRaw != 0u) {                                           // a near round: dedupe the near half into nearIn
+            atomicStore(&counters[0], 0u);                             // the deduped near count, accumulated by dedupe-filter
+            atomicStore(&counters[14], 0u);                            // mode 0
+            atomicStore(&counters[8], nearRaw);                        // the near dedupe's count word (dedupe-claim, dedupe-filter over the near half)
+            atomicStore(&counters[24], 5u);                            // the path word: sssp-relax role 0 runs, role 1 nothing
+            atomicStore(&counters[11], atomicLoad(&counters[11]) + 1u);   // rounds dispatched (the done boundary is not counted)
+        } else if (farRaw != 0u) {                                     // the near pile is empty: raise the threshold and re-bucket the far pile
+            let threshold = bitcast<f32>(atomicLoad(&counters[22]));
+            let raised = threshold + bitcast<f32>(atomicLoad(&counters[23]));   // ONE f32 add on the bit patterns (PD-9)
+            if (raised == threshold) {                                 // the delta is below the threshold's ulp: the host raises E_UNSUPPORTED
+                atomicStore(&counters[15], 3u);
+                return;
+            }
+            atomicStore(&counters[4], atomicLoad(&counters[22]));      // prevThresholdBits: what the pass-through drops below
+            atomicStore(&counters[22], bitcast<u32>(raised));
+            atomicStore(&counters[20], 0u);                            // the deduped far count, accumulated by dedupe-filter
+            atomicStore(&counters[14], 1u);                            // mode 1
+            atomicStore(&counters[9], farRaw);                         // the far dedupe's count word (dedupe-claim, dedupe-filter over the far half)
+            atomicStore(&counters[24], 6u);                            // the path word: sssp-relax role 1 runs, role 0 nothing
+            atomicStore(&counters[11], atomicLoad(&counters[11]) + 1u);
+        } else {                                                       // both piles empty: finished
+            atomicStore(&counters[15], 1u);
+        }
+    } else if (P.role == 3u) {                                         // the piles are deduped: restart the raw half the round consumed
+        if (atomicLoad(&counters[15]) != 0u) { return; }               // role 2 chose no pile this round
+        if (atomicLoad(&counters[14]) == 0u) {
+            atomicStore(&counters[1], 0u);                             // the raw near half restarts (sssp-relax role 0 sizes itself from word 0)
+        } else {
+            atomicStore(&counters[21], 0u);                            // the raw far half restarts (the pass-through re-appends what stays far; role 1 sizes itself from word 20)
+        }
+    }
+}
+`;
+//# sourceMappingURL=frontier-finalize.wgsl.js.map

package/dist/src/wgsl/frontier-finalize.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier-finalize.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/frontier-finalize.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+G9C,CAAC"}

package/dist/src/wgsl/sssp-pred.wgsl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `sssp-pred` kernel body (design 8.10 "SSSP predecessor pass"; P8-T6 and P8-T9, the P8 plan's PD-11 / PD-24 /
+ * PD-27): the ONE post-pass over the settled distances that produces `parent` for `breadthFirstSearch` and
+ * `predArc` for `sssp` and `bellmanFord`, so no claim kernel writes a predecessor and every predecessor array is a
+ * function of the settled `depth` / `dist` alone (bitwise reproducible, PD-14). `MODE` (a pipeline override) picks
+ * the distance type: 1 = u32 depths (`dist` is the BFS depth array, a tight arc is `depth[u] + 1 == depth[v]`, every
+ * tight arc is admitted, and the chain is acyclic because depth strictly decreases along it); 0 = f32 bit patterns
+ * (a tight arc is `bitcast<u32>(bitcast<f32>(dist[u]) + w) == dist[v]`, one f32 add compared as the bits PD-9
+ * stores). `P.predKind` picks what is written: 0 the arc index, 1 the source node index. The winner is the SMALLEST
+ * admitted value through `atomicMin` on `pred[v]`, which the driver fills with `INVALID_INDEX` first; the source
+ * keeps `INVALID_INDEX` whatever attains it.
+ *
+ * In `MODE 0` the body runs PD-27's three roles over a `pred` buffer of `2 x hb + 64` words, `hb = roundUp(n, 64)`:
+ * `pred[0, n)` the arcs, `pred[hb, hb + n)` the hop counts, `pred[2 hb]` the changed word, `pred[2 hb + 1]` the orphan
+ * word. Role 0 (the roots pass, `P.mode 0` only) marks every node with a tight in-arc from a strictly smaller
+ * distance as a root (`hops 0`); role 1 (a hop pass, `P.iteration` inside its batch) lowers `hops[v]` to
+ * `hops[u] + 1` along every plateau arc (`P.mode 0`: equal distance) or every tight arc (`P.mode 1`: bellmanFord's
+ * tight-subgraph rule) and records the pass index in the changed word when it lowered one, returning at its first
+ * line when the previous pass changed nothing; role 2 (the predecessor pass) admits the smallest tight arc whose
+ * source sits exactly one key step below `v` and counts a reached non-source node the key never reached as an
+ * orphan (only bellmanFord can make one). `MODE 1` reads none of `P.role`, `P.mode` and `P.iteration` and never
+ * touches `pred` beyond word `n - 1`. The body STRIDES over the rows (`planGridStride(n)`, `P.stride` the plan's
+ * stride): a per-invocation body under that plan would leave every row above the dispatch cap at `INVALID_INDEX`,
+ * silently. No barrier anywhere, so the early return is legal. 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 ssspPredWgsl = "\n@compute @workgroup_size(WG)\nfn sssp_pred(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let first = linear_id(wid, lid.x);\n    let hb = ((P.n + 63u) / 64u) * 64u;                              // MODE 0 only: hops[v] is pred[hb + v]; pred[2 hb] is the changed word, pred[2 hb + 1] the orphan word (PD-27)\n    if (P.role == 1u && P.iteration != 0u && atomicLoad(&pred[2u * hb]) < P.iteration) { return; }   // the previous hop pass changed nothing: converged (no barrier anywhere, so the early return is legal)\n    for (var u = first; u < P.n; u = u + P.stride) {                 // grid-stride over the rows (planGridStride(n)); no barrier anywhere\n        let du = dist[u];\n        var unreached = false;\n        if (MODE == 1u) { unreached = du == INVALID_INDEX; } else { unreached = du == F32_INF_BITS; }\n        if (unreached) { continue; }\n        var hu = 0u;                                                 // u's hop count (MODE 0, roles 1 and 2)\n        if (MODE == 0u && P.role != 0u) {\n            hu = atomicLoad(&pred[hb + u]);\n            if (hu == INVALID_INDEX) {                               // the key has not reached u yet\n                if (P.role == 2u && u != P.source) { atomicAdd(&pred[2u * hb + 1u], 1u); }   // an orphan: only bellmanFord can make one (P8-T10 Step 3)\n                continue;\n            }\n        }\n        let end = min(rowPtr[u + 1u], P.arcEnd);\n        for (var a = max(rowPtr[u], P.arcBase); a < end; a = a + 1u) {\n            let v = colIdx[a - P.arcBase];\n            if (v == P.source) { continue; }                         // the source keeps INVALID_INDEX whatever attains it (a zero-weight arc could)\n            let dv = dist[v];\n            var tight = false;                                       // the arc explains dist[v]\n            var below = false;                                       // and its source sits at a strictly smaller distance\n            if (MODE == 1u) {\n                tight = (du + 1u) == dv;                             // depth mode: BFS parent, one depth down\n            } else {\n                let w = select(1.0, weights[a - P.arcBase], HAS_WEIGHTS);\n                tight = (dv != F32_INF_BITS) && (bitcast<u32>(bitcast<f32>(du) + w) == dv);   // one f32 add, compared as the bit pattern PD-9 stores; never into an unreached v (an overflowed sum is +Inf too)\n                below = bitcast<f32>(du) < bitcast<f32>(dv);\n            }\n            if (!tight) { continue; }\n            var admit = false;                                       // this arc is one key step below v\n            if (MODE == 1u) {\n                admit = true;\n            } else if (P.role == 0u) {                               // the roots pass (the plateau rule only; bellmanFord seeds the source alone)\n                if (P.mode == 0u && below) { atomicMin(&pred[hb + v], 0u); }\n            } else if (P.role == 1u) {                               // a hop pass: one hop along a plateau arc (mode 0) or along any tight arc (mode 1)\n                if (P.mode == 1u || du == dv) {\n                    let old = atomicMin(&pred[hb + v], hu + 1u);\n                    if (hu + 1u < old) { atomicMax(&pred[2u * hb], P.iteration + 1u); }   // this pass changed something\n                }\n            } else {                                                 // the predecessor pass: the smallest tight arc one key step below v\n                let hv = atomicLoad(&pred[hb + v]);\n                if (P.mode == 1u) { admit = hu + 1u == hv; } else if (hv == 0u) { admit = below; } else { admit = (du == dv) && (hu + 1u == hv); }\n            }\n            if (admit) { atomicMin(&pred[v], select(a, u, P.predKind == 1u)); }\n        }\n    }\n}\n";
+//# sourceMappingURL=sssp-pred.wgsl.d.ts.map

package/dist/src/wgsl/sssp-pred.wgsl.d.ts.map

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

package/dist/src/wgsl/sssp-pred.wgsl.js

@@ -0,0 +1,80 @@
+/**
+ * The `sssp-pred` kernel body (design 8.10 "SSSP predecessor pass"; P8-T6 and P8-T9, the P8 plan's PD-11 / PD-24 /
+ * PD-27): the ONE post-pass over the settled distances that produces `parent` for `breadthFirstSearch` and
+ * `predArc` for `sssp` and `bellmanFord`, so no claim kernel writes a predecessor and every predecessor array is a
+ * function of the settled `depth` / `dist` alone (bitwise reproducible, PD-14). `MODE` (a pipeline override) picks
+ * the distance type: 1 = u32 depths (`dist` is the BFS depth array, a tight arc is `depth[u] + 1 == depth[v]`, every
+ * tight arc is admitted, and the chain is acyclic because depth strictly decreases along it); 0 = f32 bit patterns
+ * (a tight arc is `bitcast<u32>(bitcast<f32>(dist[u]) + w) == dist[v]`, one f32 add compared as the bits PD-9
+ * stores). `P.predKind` picks what is written: 0 the arc index, 1 the source node index. The winner is the SMALLEST
+ * admitted value through `atomicMin` on `pred[v]`, which the driver fills with `INVALID_INDEX` first; the source
+ * keeps `INVALID_INDEX` whatever attains it.
+ *
+ * In `MODE 0` the body runs PD-27's three roles over a `pred` buffer of `2 x hb + 64` words, `hb = roundUp(n, 64)`:
+ * `pred[0, n)` the arcs, `pred[hb, hb + n)` the hop counts, `pred[2 hb]` the changed word, `pred[2 hb + 1]` the orphan
+ * word. Role 0 (the roots pass, `P.mode 0` only) marks every node with a tight in-arc from a strictly smaller
+ * distance as a root (`hops 0`); role 1 (a hop pass, `P.iteration` inside its batch) lowers `hops[v]` to
+ * `hops[u] + 1` along every plateau arc (`P.mode 0`: equal distance) or every tight arc (`P.mode 1`: bellmanFord's
+ * tight-subgraph rule) and records the pass index in the changed word when it lowered one, returning at its first
+ * line when the previous pass changed nothing; role 2 (the predecessor pass) admits the smallest tight arc whose
+ * source sits exactly one key step below `v` and counts a reached non-source node the key never reached as an
+ * orphan (only bellmanFord can make one). `MODE 1` reads none of `P.role`, `P.mode` and `P.iteration` and never
+ * touches `pred` beyond word `n - 1`. The body STRIDES over the rows (`planGridStride(n)`, `P.stride` the plan's
+ * stride): a per-invocation body under that plan would leave every row above the dispatch cap at `INVALID_INDEX`,
+ * silently. No barrier anywhere, so the early return is legal. 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 ssspPredWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn sssp_pred(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    let hb = ((P.n + 63u) / 64u) * 64u;                              // MODE 0 only: hops[v] is pred[hb + v]; pred[2 hb] is the changed word, pred[2 hb + 1] the orphan word (PD-27)
+    if (P.role == 1u && P.iteration != 0u && atomicLoad(&pred[2u * hb]) < P.iteration) { return; }   // the previous hop pass changed nothing: converged (no barrier anywhere, so the early return is legal)
+    for (var u = first; u < P.n; u = u + P.stride) {                 // grid-stride over the rows (planGridStride(n)); no barrier anywhere
+        let du = dist[u];
+        var unreached = false;
+        if (MODE == 1u) { unreached = du == INVALID_INDEX; } else { unreached = du == F32_INF_BITS; }
+        if (unreached) { continue; }
+        var hu = 0u;                                                 // u's hop count (MODE 0, roles 1 and 2)
+        if (MODE == 0u && P.role != 0u) {
+            hu = atomicLoad(&pred[hb + u]);
+            if (hu == INVALID_INDEX) {                               // the key has not reached u yet
+                if (P.role == 2u && u != P.source) { atomicAdd(&pred[2u * hb + 1u], 1u); }   // an orphan: only bellmanFord can make one (P8-T10 Step 3)
+                continue;
+            }
+        }
+        let end = min(rowPtr[u + 1u], P.arcEnd);
+        for (var a = max(rowPtr[u], P.arcBase); a < end; a = a + 1u) {
+            let v = colIdx[a - P.arcBase];
+            if (v == P.source) { continue; }                         // the source keeps INVALID_INDEX whatever attains it (a zero-weight arc could)
+            let dv = dist[v];
+            var tight = false;                                       // the arc explains dist[v]
+            var below = false;                                       // and its source sits at a strictly smaller distance
+            if (MODE == 1u) {
+                tight = (du + 1u) == dv;                             // depth mode: BFS parent, one depth down
+            } else {
+                let w = select(1.0, weights[a - P.arcBase], HAS_WEIGHTS);
+                tight = (dv != F32_INF_BITS) && (bitcast<u32>(bitcast<f32>(du) + w) == dv);   // one f32 add, compared as the bit pattern PD-9 stores; never into an unreached v (an overflowed sum is +Inf too)
+                below = bitcast<f32>(du) < bitcast<f32>(dv);
+            }
+            if (!tight) { continue; }
+            var admit = false;                                       // this arc is one key step below v
+            if (MODE == 1u) {
+                admit = true;
+            } else if (P.role == 0u) {                               // the roots pass (the plateau rule only; bellmanFord seeds the source alone)
+                if (P.mode == 0u && below) { atomicMin(&pred[hb + v], 0u); }
+            } else if (P.role == 1u) {                               // a hop pass: one hop along a plateau arc (mode 0) or along any tight arc (mode 1)
+                if (P.mode == 1u || du == dv) {
+                    let old = atomicMin(&pred[hb + v], hu + 1u);
+                    if (hu + 1u < old) { atomicMax(&pred[2u * hb], P.iteration + 1u); }   // this pass changed something
+                }
+            } else {                                                 // the predecessor pass: the smallest tight arc one key step below v
+                let hv = atomicLoad(&pred[hb + v]);
+                if (P.mode == 1u) { admit = hu + 1u == hv; } else if (hv == 0u) { admit = below; } else { admit = (du == dv) && (hu + 1u == hv); }
+            }
+            if (admit) { atomicMin(&pred[v], select(a, u, P.predKind == 1u)); }
+        }
+    }
+}
+`;
+//# sourceMappingURL=sssp-pred.wgsl.js.map

package/dist/src/wgsl/sssp-pred.wgsl.js.map

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

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

@@ -0,0 +1,30 @@
+/**
+ * The `sssp-relax` kernel body (design 8.4 "Davidson's near-far", 8.10 "SSSP near-far relax"; P8-T9, the P8 plan's
+ * PD-9 / PD-20 / PD-22 / DEP-P8-E): one round of the near-far shortest-path loop. `dist` is `array<atomic<u32>>`
+ * holding the IEEE-754 bit patterns of the f32 distances (`F32_INF_BITS` = unreached), and `atomicMin` on the
+ * patterns IS `min` on the values, because for non-negative floats the unsigned bit order is the value order
+ * (`+0` is `0x00000000`, every sum of non-negatives under round-to-nearest is `+0` or positive, never `-0`), which
+ * the driver's host scan of the weight vector guarantees -- the whole trick, and it needs no float atomic (PD-9).
+ * Every candidate is ONE f32 add, `dist[u] + w`, so the settled value is the minimum of a fixed set of f32
+ * numbers: order-independent, bitwise reproducible, and bitwise equal to the f32 Dijkstra oracle.
+ *
+ * Two roles over one body, chosen by `P.role`. Role 0 (the near round) reads the deduped near pile `queueIn`
+ * (`counters[0]` entries, at most `P.n`), relaxes every arc of every entry's WHOLE row (never windowed, DEP-P8-E),
+ * skips a candidate above `P.cutoffBits` (the CPU port's `dv <= cutoff` guard as `nd > cutoff`), and when its
+ * `atomicMin` improved `v` -- this lane alone observed a larger old value, so this lane alone owns the append --
+ * appends `v` to the raw near half of `queueOut` (word 0, count word 1) when `nd` is below the threshold
+ * (`counters[22]`), else to the raw far half (word `P.edgeCapacity`, count word 21). Role 1 (the pass-through,
+ * PD-20) re-buckets the deduped far pile (`counters[20]` entries): an entry whose settled distance fell below the
+ * PREVIOUS threshold (`counters[4]`) was appended to near at that improvement and relaxed there, so it is dropped;
+ * the rest go back to near or far against the threshold the boundary just raised. The count words are unclamped
+ * (the write is guarded by the capacity; `frontier-finalize` role 2 detects a pile above it). The appends are per
+ * improving relaxation, one atomic each: inside a per-lane arc loop no workgroup aggregation is possible without the
+ * uniform-strip structure of `bfs-fused`, and Davidson's kernel appends per thread too. Grid-strided under a direct
+ * dispatch of `planGridStride(n)`: `P.stride` is the plan's, a deduped pile of at most `n` entries is covered in a
+ * few trips per lane and `i + stride` never wraps (`U32_MAX` would); the block's `path` word (5 a near round, 6 a
+ * far one) makes the other role's dispatch a no-op. No barrier anywhere: the loops may
+ * be per lane. 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 ssspRelaxWgsl = "\n@compute @workgroup_size(WG)\nfn sssp_relax(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let first = linear_id(wid, lid.x);\n    let mine = select(5u, 6u, P.role == 1u);                           // the path word role 2 wrote: 5 a near round, 6 a far pass-through\n    let chosen = atomicLoad(&counters[24]) == mine;                    // the other role's dispatch of the round is a no-op\n    let count = select(0u, min(atomicLoad(&counters[select(0u, 20u, P.role == 1u)]), P.n), chosen);   // the deduped near or far pile\n    let threshold = bitcast<f32>(atomicLoad(&counters[22]));\n    let cutoff = bitcast<f32>(P.cutoffBits);\n    for (var i = first; i < count; i = i + P.stride) {                // no barrier anywhere: the loops may be per lane\n        let u = queueIn[i];\n        let du = bitcast<f32>(atomicLoad(&dist[u]));\n        if (P.role == 1u) {                                            // the pass-through (PD-20): re-bucket a far entry\n            if (du < bitcast<f32>(atomicLoad(&counters[4]))) { continue; }   // below the previous threshold: relaxed in an earlier bucket\n            if (du < threshold) {\n                let q = atomicAdd(&counters[1], 1u);\n                if (q < P.edgeCapacity) { queueOut[q] = u; }\n            } else {\n                let q = atomicAdd(&counters[21], 1u);\n                if (q < P.edgeCapacity) { queueOut[P.edgeCapacity + q] = u; }\n            }\n            continue;\n        }\n        let end = rowPtr[u + 1u];\n        for (var a = rowPtr[u]; a < end; a = a + 1u) {                 // the whole row: never windowed (DEP-P8-E)\n            let v = colIdx[a];\n            let nd = du + select(1.0, weights[a], HAS_WEIGHTS);         // ONE f32 add (PD-9)\n            if (nd > cutoff) { continue; }                             // SsspOptions.cutoff: the CPU port's dv <= cutoff\n            let bits = bitcast<u32>(nd);\n            let old = atomicMin(&dist[v], bits);                       // exact on non-negative floats\n            if (bits < old) {                                          // this lane improved v, so it owns the append\n                if (nd < threshold) {\n                    let q = atomicAdd(&counters[1], 1u);\n                    if (q < P.edgeCapacity) { queueOut[q] = v; }\n                } else {\n                    let q = atomicAdd(&counters[21], 1u);\n                    if (q < P.edgeCapacity) { queueOut[P.edgeCapacity + q] = v; }\n                }\n            }\n        }\n    }\n}\n";
+//# sourceMappingURL=sssp-relax.wgsl.d.ts.map

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

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

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

@@ -0,0 +1,72 @@
+/**
+ * The `sssp-relax` kernel body (design 8.4 "Davidson's near-far", 8.10 "SSSP near-far relax"; P8-T9, the P8 plan's
+ * PD-9 / PD-20 / PD-22 / DEP-P8-E): one round of the near-far shortest-path loop. `dist` is `array<atomic<u32>>`
+ * holding the IEEE-754 bit patterns of the f32 distances (`F32_INF_BITS` = unreached), and `atomicMin` on the
+ * patterns IS `min` on the values, because for non-negative floats the unsigned bit order is the value order
+ * (`+0` is `0x00000000`, every sum of non-negatives under round-to-nearest is `+0` or positive, never `-0`), which
+ * the driver's host scan of the weight vector guarantees -- the whole trick, and it needs no float atomic (PD-9).
+ * Every candidate is ONE f32 add, `dist[u] + w`, so the settled value is the minimum of a fixed set of f32
+ * numbers: order-independent, bitwise reproducible, and bitwise equal to the f32 Dijkstra oracle.
+ *
+ * Two roles over one body, chosen by `P.role`. Role 0 (the near round) reads the deduped near pile `queueIn`
+ * (`counters[0]` entries, at most `P.n`), relaxes every arc of every entry's WHOLE row (never windowed, DEP-P8-E),
+ * skips a candidate above `P.cutoffBits` (the CPU port's `dv <= cutoff` guard as `nd > cutoff`), and when its
+ * `atomicMin` improved `v` -- this lane alone observed a larger old value, so this lane alone owns the append --
+ * appends `v` to the raw near half of `queueOut` (word 0, count word 1) when `nd` is below the threshold
+ * (`counters[22]`), else to the raw far half (word `P.edgeCapacity`, count word 21). Role 1 (the pass-through,
+ * PD-20) re-buckets the deduped far pile (`counters[20]` entries): an entry whose settled distance fell below the
+ * PREVIOUS threshold (`counters[4]`) was appended to near at that improvement and relaxed there, so it is dropped;
+ * the rest go back to near or far against the threshold the boundary just raised. The count words are unclamped
+ * (the write is guarded by the capacity; `frontier-finalize` role 2 detects a pile above it). The appends are per
+ * improving relaxation, one atomic each: inside a per-lane arc loop no workgroup aggregation is possible without the
+ * uniform-strip structure of `bfs-fused`, and Davidson's kernel appends per thread too. Grid-strided under a direct
+ * dispatch of `planGridStride(n)`: `P.stride` is the plan's, a deduped pile of at most `n` entries is covered in a
+ * few trips per lane and `i + stride` never wraps (`U32_MAX` would); the block's `path` word (5 a near round, 6 a
+ * far one) makes the other role's dispatch a no-op. No barrier anywhere: the loops may
+ * be per lane. 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 ssspRelaxWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn sssp_relax(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    let mine = select(5u, 6u, P.role == 1u);                           // the path word role 2 wrote: 5 a near round, 6 a far pass-through
+    let chosen = atomicLoad(&counters[24]) == mine;                    // the other role's dispatch of the round is a no-op
+    let count = select(0u, min(atomicLoad(&counters[select(0u, 20u, P.role == 1u)]), P.n), chosen);   // the deduped near or far pile
+    let threshold = bitcast<f32>(atomicLoad(&counters[22]));
+    let cutoff = bitcast<f32>(P.cutoffBits);
+    for (var i = first; i < count; i = i + P.stride) {                // no barrier anywhere: the loops may be per lane
+        let u = queueIn[i];
+        let du = bitcast<f32>(atomicLoad(&dist[u]));
+        if (P.role == 1u) {                                            // the pass-through (PD-20): re-bucket a far entry
+            if (du < bitcast<f32>(atomicLoad(&counters[4]))) { continue; }   // below the previous threshold: relaxed in an earlier bucket
+            if (du < threshold) {
+                let q = atomicAdd(&counters[1], 1u);
+                if (q < P.edgeCapacity) { queueOut[q] = u; }
+            } else {
+                let q = atomicAdd(&counters[21], 1u);
+                if (q < P.edgeCapacity) { queueOut[P.edgeCapacity + q] = u; }
+            }
+            continue;
+        }
+        let end = rowPtr[u + 1u];
+        for (var a = rowPtr[u]; a < end; a = a + 1u) {                 // the whole row: never windowed (DEP-P8-E)
+            let v = colIdx[a];
+            let nd = du + select(1.0, weights[a], HAS_WEIGHTS);         // ONE f32 add (PD-9)
+            if (nd > cutoff) { continue; }                             // SsspOptions.cutoff: the CPU port's dv <= cutoff
+            let bits = bitcast<u32>(nd);
+            let old = atomicMin(&dist[v], bits);                       // exact on non-negative floats
+            if (bits < old) {                                          // this lane improved v, so it owns the append
+                if (nd < threshold) {
+                    let q = atomicAdd(&counters[1], 1u);
+                    if (q < P.edgeCapacity) { queueOut[q] = v; }
+                } else {
+                    let q = atomicAdd(&counters[21], 1u);
+                    if (q < P.edgeCapacity) { queueOut[P.edgeCapacity + q] = v; }
+                }
+            }
+        }
+    }
+}
+`;
+//# sourceMappingURL=sssp-relax.wgsl.js.map

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

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