@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/dist/src/wgsl/grid-far-field.wgsl.js

@@ -0,0 +1,98 @@
+/**
+ * G6, the `grid-far-field` kernel body (spec 7.7; P4-T10; D24): per node `i = sortedIdx[t]`, its finest cell
+ * recomputed from `pos[i]` and the state (PD-10); for an inside node the coarsest level minus the 3x3 (3x3x3)
+ * around its coarsest cell, then at every finer level the 6x6 (6x6x6) block that is the parent's 3x3 minus this
+ * level's own 3x3 -- space tiled exactly once, no theta -- plus the outside pseudo-cell's centroid; for an outside
+ * node the coarsest level in full and no pseudo-cell. Every cell term is the per-cell law on the mass-weighted
+ * centroid (Gephi Region semantics), softened by `eps^2`: `LAW` 0 (FA2) `d * (k m_i M / d2)`, `LAW` 1 (FR, 7.20)
+ * `d * (k^2 M / d2)` (mass 1 per node, so `M` is the cell's count), `LAW` 2 (coulomb) `d * (-g m_i M / d2^1.5)`
+ * (P4-T13, PD-22). `force += f` (K2 wrote it). The loop bounds are `P.levels` and `P.gridMax` from the uniform,
+ * not a `LEVELS` override (PD-16, DEP-P4-G). Body only; normative text.
+ */
+export const gridFarFieldWgsl = /* wgsl */ `
+fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn store_force(i: u32, f: vec3f) {
+    force[3u * i] = f.x;
+    force[3u * i + 1u] = f.y;
+    force[3u * i + 2u] = f.z;
+}
+fn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u); }
+fn grid_side(level: u32) -> u32 { return P.gridMax >> level; }
+fn level_base(level: u32) -> u32 {                             // the pyramid index of level L's cell 0 (level 0 carries the pseudo-cell at index cells)
+    var base = 0u;
+    for (var l = 0u; l < level; l = l + 1u) {
+        let s = grid_side(l);
+        base = base + s * s * select(1u, s, P.dim == 3u) + select(0u, 1u, l == 0u);
+    }
+    return base;
+}
+fn cell_at(level: u32, cx: i32, cy: i32, cz: i32) -> u32 {
+    let s = grid_side(level);
+    return level_base(level) + u32(cx) + s * (u32(cy) + select(0u, s * u32(cz), P.dim == 3u));
+}
+fn cell_force(pi: vec4f, q: vec4f) -> vec3f {                  // one far-field term, softened by state.eps (7.7)
+    if (q.w <= 0.0) { return vec3f(0.0); }                     // an empty cell
+    let d = pi.xyz - q.xyz / q.w;                              // to the mass-weighted centroid
+    let d2 = dot(d, d) + S.eps * S.eps;
+    if (LAW == 1u) { return d * (P.frK * P.frK * q.w / d2); }                       // LAW 1 (FR, 7.20): k^2 / d per node, q.w nodes at the centroid
+    if (LAW == 2u) { return d * (-P.coulomb * pi.w * q.w / (d2 * sqrt(d2))); }     // LAW 2 (coulomb): -g m_i M_cell / d^2
+    return d * (P.scalingRatio * pi.w * q.w / d2);             // LAW 0 (FA2): |F| = k m_i M_cell / d
+}
+
+@compute @workgroup_size(WG)
+fn grid_far_field(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let t = linear_id(wid, lid.x);
+    if (t >= P.n) { return; }                                      // no barrier follows
+    let i = sortedIdx[t];                                          // sorted order (D24)
+    let pi = pos[i];
+    let gf = f32(P.gridMax);
+    let q = (pi.xyz - S.gridMin.xyz) * S.invCellSize;              // PD-10
+    var c0 = vec3<i32>(floor(clamp(q, vec3f(-1.0), vec3f(gf + 1.0))));
+    if (P.dim == 2u) { c0.z = 0; }                                 // 2D: one z plane; the loops below visit cz = 0 only, so the 3x3 test must see cz - 0
+    let g = i32(P.gridMax);
+    var inside = c0.x >= 0 && c0.x < g && c0.y >= 0 && c0.y < g;
+    if (P.dim == 3u) { inside = inside && c0.z >= 0 && c0.z < g; }
+    let top = P.levels - 1u;
+    let ts = i32(grid_side(top));                                  // the coarsest side (4)
+    let zTop = select(0, ts - 1, P.dim == 3u);                     // z ranges: one plane in 2D
+    var f = vec3f(0.0);
+    if (inside) {
+        let ct = c0 / i32(1u << top);                              // the node's coarsest cell
+        for (var cz = 0; cz <= zTop; cz = cz + 1) {
+            for (var cy = 0; cy < ts; cy = cy + 1) {
+                for (var cx = 0; cx < ts; cx = cx + 1) {
+                    if (abs(cx - ct.x) <= 1 && abs(cy - ct.y) <= 1 && abs(cz - ct.z) <= 1) { continue; }   // the 3x3(x3) is finer levels' work
+                    f = f + cell_force(pi, pyramid[cell_at(top, cx, cy, cz)]);
+                }
+            }
+        }
+        for (var l = top; l > 0u; l = l - 1u) {                    // level l - 1: the parent's 3x3 at level l, refined, minus this level's own 3x3
+            let level = l - 1u;
+            let cl = c0 / i32(1u << level);
+            let cp = cl / 2;
+            let side = i32(grid_side(level));
+            let zLo = select(0, max(0, 2 * (cp.z - 1)), P.dim == 3u);
+            let zHi = select(0, min(side - 1, 2 * (cp.z + 1) + 1), P.dim == 3u);
+            for (var cz = zLo; cz <= zHi; cz = cz + 1) {
+                for (var cy = max(0, 2 * (cp.y - 1)); cy <= min(side - 1, 2 * (cp.y + 1) + 1); cy = cy + 1) {
+                    for (var cx = max(0, 2 * (cp.x - 1)); cx <= min(side - 1, 2 * (cp.x + 1) + 1); cx = cx + 1) {
+                        if (abs(cx - cl.x) <= 1 && abs(cy - cl.y) <= 1 && abs(cz - cl.z) <= 1) { continue; }
+                        f = f + cell_force(pi, pyramid[cell_at(level, cx, cy, cz)]);
+                    }
+                }
+            }
+        }
+        f = f + cell_force(pi, pyramid[grid_cells()]);             // the outside pseudo-cell as one far-field term
+    } else {
+        for (var cz = 0; cz <= zTop; cz = cz + 1) {                // an outside node: the coarsest level in full, no pseudo-cell (it would include itself)
+            for (var cy = 0; cy < ts; cy = cy + 1) {
+                for (var cx = 0; cx < ts; cx = cx + 1) {
+                    f = f + cell_force(pi, pyramid[cell_at(top, cx, cy, cz)]);
+                }
+            }
+        }
+    }
+    store_force(i, load_force(i) + f);
+}
+`;
+//# sourceMappingURL=grid-far-field.wgsl.js.map

package/dist/src/wgsl/grid-far-field.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-far-field.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/grid-far-field.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqF1C,CAAC"}

package/dist/src/wgsl/grid-near-field.wgsl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * G7, the `grid-near-field` kernel body (spec 7.7, 7.6, 7.20; P4-T10, P4-T13; D24): per node `i = sortedIdx[t]`, the
+ * exact pair law of K3 (`LAW` 0: `|F| = k m_i m_j / d` with the 0.01 floor; `LAW` 1: FR's unfloored `k^2 / d`;
+ * `LAW` 2: the unfloored coulomb `-g m_i m_j / d^2`; the antisymmetric coincident kick at the law's magnitude at
+ * d = 0.01, PD-22) over the 9 (27) finest
+ * cells around its own, or over the outside pseudo-cell alone for an outside node; a cell above `nearMax` entries
+ * is sampled by `nearMax` INDEPENDENT draws with replacement, draw `k` reading the slot
+ * `lowbias32(((c ^ (iteration * 0x9E3779B9)) ^ seed) ^ (k * 0x85EBCA6B)) % count` (every slot's inclusion
+ * probability is `nearMax / count` whatever its position in the sorted order, so a duplicated draw is counted twice
+ * and the node itself, when drawn, is skipped and not replaced), and scaled by `others / sampled` where `sampled` is
+ * the realised number of draws that were not the node (the Horvitz-Thompson form of PD-15 / DEP-P4-K: given
+ * `sampled = s`, those `s` draws are i.i.d. uniform over the `others` slots, so the expectation of the scaled sum is
+ * the exact cell sum whenever `s >= 1`; the G4 record's G4-F2 row carries the measurement); then
+ * the fused epilogue of K3 (gravity, `force +=`, the swing / traction workgroup reduction in uniform control flow).
+ * The helpers `load_force`, `store_force`, `load_old`, `kick_magnitude`, `gravity_force` and the epilogue are K3's
+ * text. Body only; normative text.
+ */
+export declare const gridNearFieldWgsl = "\nfn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }\nfn store_force(i: u32, f: vec3f) {\n    force[3u * i] = f.x;\n    force[3u * i + 1u] = f.y;\n    force[3u * i + 2u] = f.z;\n}\nfn load_old(i: u32) -> vec3f { return vec3f(oldForce[3u * i], oldForce[3u * i + 1u], oldForce[3u * i + 2u]); }\nfn gravity_force(pi: vec4f) -> vec3f {                         // spec 7.9: centroid (GRAVITY_CENTER 0) or origin (1); regular or strong\n    var q = pi.xyz;\n    if (GRAVITY_CENTER == 0u) { q = pi.xyz - S.centroid.xyz; }\n    if (STRONG_GRAVITY) { return -P.gravity * pi.w * q; }\n    let d = length(q);\n    if (d > FA2_DIST_FLOOR) { return -P.gravity * pi.w * q / d; }\n    return vec3f(0.0);\n}\nfn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u); }\nfn kick_magnitude(mi: f32, mj: f32) -> f32 {                   // the law's magnitude at d = FA2_DIST_FLOOR (the P5 plan's PD-10)\n    if (LAW == 1u) { return P.frK * P.frK / FA2_DIST_FLOOR; }\n    if (LAW == 2u) { return -P.coulomb * mi * mj / FA2_DIST_FLOOR_SQ; }\n    return P.scalingRatio * mi * mj / FA2_DIST_FLOOR;\n}\nfn pair_force(i: u32, pi: vec4f, jj: u32, o: vec4f) -> vec3f {  // the exact pair law of K3 (7.6, 7.20): the floor (FA2 only), the coincident kick\n    let d = pi.xyz - o.xyz;\n    var d2 = dot(d, d);\n    if (d2 < FA2_COINCIDENT_SQ) { return kick_dir(i, jj, P.dim) * kick_magnitude(pi.w, o.w); }\n    if (LAW == 0u) { d2 = max(d2, FA2_DIST_FLOOR_SQ); }\n    let k = P.scalingRatio * pi.w * o.w;\n    if (LAW == 1u) { return d * (P.frK * P.frK / d2); }\n    if (LAW == 2u) { return d * (-P.coulomb * pi.w * o.w / (d2 * sqrt(d2))); }\n    return d * (k / d2);\n}\nfn cell_sum(i: u32, pi: vec4f, c: u32, own: bool) -> vec3f {     // one finest cell: exact below nearMax entries, Horvitz-Thompson above (PD-15)\n    let start = cellStart[c];\n    let count = cellStart[c + 1u] - start;\n    var f = vec3f(0.0);\n    if (count <= P.nearMax) {\n        for (var k = start; k < start + count; k = k + 1u) {\n            let jj = sortedIdx[k];\n            if (jj != i) { f = f + pair_force(i, pi, jj, pos[jj]); }\n        }\n        return f;\n    }\n    let base = (c ^ (P.iterationIndex * 0x9E3779B9u)) ^ P.seed;                  // the per-iteration draw seed (7.16)\n    var sampled = 0u;\n    for (var k = 0u; k < P.nearMax; k = k + 1u) {\n        let jj = sortedIdx[start + (lowbias32(base ^ (k * 0x85EBCA6Bu)) % count)];   // draw k: independent inclusion, with replacement (PD-15)\n        if (jj == i) { continue; }\n        f = f + pair_force(i, pi, jj, pos[jj]);\n        sampled = sampled + 1u;\n    }\n    if (sampled == 0u) { return vec3f(0.0); }\n    let others = select(count, count - 1u, own);\n    return f * (f32(others) / f32(sampled));                     // others / sampled over the realised sample (DEP-P4-K)\n}\n\n@compute @workgroup_size(WG)\nfn grid_near_field(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let t = linear_id(wid, lid.x);\n    let valid = t < P.n;\n    var i = 0u;\n    var pi = vec4f(0.0);\n    var f = vec3f(0.0);\n    if (valid) {\n        i = sortedIdx[t];                                          // sorted order (D24)\n        pi = pos[i];\n        let gf = f32(P.gridMax);\n        let q = (pi.xyz - S.gridMin.xyz) * S.invCellSize;\n        var c0 = vec3<i32>(floor(clamp(q, vec3f(-1.0), vec3f(gf + 1.0))));\n        if (P.dim == 2u) { c0.z = 0; }                             // 2D: the one z plane\n        let g = i32(P.gridMax);\n        var inside = c0.x >= 0 && c0.x < g && c0.y >= 0 && c0.y < g;\n        if (P.dim == 3u) { inside = inside && c0.z >= 0 && c0.z < g; }\n        if (inside) {\n            let zr = select(0, 1, P.dim == 3u);\n            for (var dz = -zr; dz <= zr; dz = dz + 1) {\n                for (var dy = -1; dy <= 1; dy = dy + 1) {\n                    for (var dx = -1; dx <= 1; dx = dx + 1) {\n                        let cx = c0.x + dx;\n                        let cy = c0.y + dy;\n                        let cz = c0.z + dz;\n                        if (cx < 0 || cx >= g || cy < 0 || cy >= g || cz < 0 || cz >= g) { continue; }\n                        let c = u32(cx) + P.gridMax * (u32(cy) + select(0u, P.gridMax * u32(cz), P.dim == 3u));\n                        f = f + cell_sum(i, pi, c, dx == 0 && dy == 0 && dz == 0);\n                    }\n                }\n            }\n        } else {\n            f = cell_sum(i, pi, grid_cells(), true);               // an outside node: the pseudo-cell alone\n        }\n    }\n    // epilogue (7.9, 7.10): gravity and force += under the guard, the swing / traction reduction outside it (K3's text)\n    var sw = 0.0;\n    var tr = 0.0;\n    if (valid) {\n        f = f + gravity_force(pi);\n        let fnew = load_force(i) + f;\n        store_force(i, fnew);\n        if (SWING_MODE == 1u) {                                    // NetworkX: positions and forces mixed, every node (7.2)\n            sw = pi.w * length(pi.xyz - fnew);\n            tr = 0.5 * pi.w * length(pi.xyz + fnew);\n        } else if (!mask_bit(fixedMask[i >> 5u], i)) {             // paper: free nodes only\n            let fold = load_old(i);\n            sw = pi.w * length(fnew - fold);\n            tr = 0.5 * pi.w * length(fnew + fold);\n        }\n    }\n    let tt = wg_reduce_vec4(vec4f(sw, tr, 0.0, 0.0), lid.x, 0u);   // uniform control flow: 256 -> 1\n    if (lid.x == 0u) { partials[group_id(wid)].swingTraction = tt.xy; }\n}\n";
+//# sourceMappingURL=grid-near-field.wgsl.d.ts.map

package/dist/src/wgsl/grid-near-field.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-near-field.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/grid-near-field.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,27KA8G7B,CAAC"}

package/dist/src/wgsl/grid-near-field.wgsl.js

@@ -0,0 +1,129 @@
+/**
+ * G7, the `grid-near-field` kernel body (spec 7.7, 7.6, 7.20; P4-T10, P4-T13; D24): per node `i = sortedIdx[t]`, the
+ * exact pair law of K3 (`LAW` 0: `|F| = k m_i m_j / d` with the 0.01 floor; `LAW` 1: FR's unfloored `k^2 / d`;
+ * `LAW` 2: the unfloored coulomb `-g m_i m_j / d^2`; the antisymmetric coincident kick at the law's magnitude at
+ * d = 0.01, PD-22) over the 9 (27) finest
+ * cells around its own, or over the outside pseudo-cell alone for an outside node; a cell above `nearMax` entries
+ * is sampled by `nearMax` INDEPENDENT draws with replacement, draw `k` reading the slot
+ * `lowbias32(((c ^ (iteration * 0x9E3779B9)) ^ seed) ^ (k * 0x85EBCA6B)) % count` (every slot's inclusion
+ * probability is `nearMax / count` whatever its position in the sorted order, so a duplicated draw is counted twice
+ * and the node itself, when drawn, is skipped and not replaced), and scaled by `others / sampled` where `sampled` is
+ * the realised number of draws that were not the node (the Horvitz-Thompson form of PD-15 / DEP-P4-K: given
+ * `sampled = s`, those `s` draws are i.i.d. uniform over the `others` slots, so the expectation of the scaled sum is
+ * the exact cell sum whenever `s >= 1`; the G4 record's G4-F2 row carries the measurement); then
+ * the fused epilogue of K3 (gravity, `force +=`, the swing / traction workgroup reduction in uniform control flow).
+ * The helpers `load_force`, `store_force`, `load_old`, `kick_magnitude`, `gravity_force` and the epilogue are K3's
+ * text. Body only; normative text.
+ */
+export const gridNearFieldWgsl = /* wgsl */ `
+fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn store_force(i: u32, f: vec3f) {
+    force[3u * i] = f.x;
+    force[3u * i + 1u] = f.y;
+    force[3u * i + 2u] = f.z;
+}
+fn load_old(i: u32) -> vec3f { return vec3f(oldForce[3u * i], oldForce[3u * i + 1u], oldForce[3u * i + 2u]); }
+fn gravity_force(pi: vec4f) -> vec3f {                         // spec 7.9: centroid (GRAVITY_CENTER 0) or origin (1); regular or strong
+    var q = pi.xyz;
+    if (GRAVITY_CENTER == 0u) { q = pi.xyz - S.centroid.xyz; }
+    if (STRONG_GRAVITY) { return -P.gravity * pi.w * q; }
+    let d = length(q);
+    if (d > FA2_DIST_FLOOR) { return -P.gravity * pi.w * q / d; }
+    return vec3f(0.0);
+}
+fn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.dim == 3u); }
+fn kick_magnitude(mi: f32, mj: f32) -> f32 {                   // the law's magnitude at d = FA2_DIST_FLOOR (the P5 plan's PD-10)
+    if (LAW == 1u) { return P.frK * P.frK / FA2_DIST_FLOOR; }
+    if (LAW == 2u) { return -P.coulomb * mi * mj / FA2_DIST_FLOOR_SQ; }
+    return P.scalingRatio * mi * mj / FA2_DIST_FLOOR;
+}
+fn pair_force(i: u32, pi: vec4f, jj: u32, o: vec4f) -> vec3f {  // the exact pair law of K3 (7.6, 7.20): the floor (FA2 only), the coincident kick
+    let d = pi.xyz - o.xyz;
+    var d2 = dot(d, d);
+    if (d2 < FA2_COINCIDENT_SQ) { return kick_dir(i, jj, P.dim) * kick_magnitude(pi.w, o.w); }
+    if (LAW == 0u) { d2 = max(d2, FA2_DIST_FLOOR_SQ); }
+    let k = P.scalingRatio * pi.w * o.w;
+    if (LAW == 1u) { return d * (P.frK * P.frK / d2); }
+    if (LAW == 2u) { return d * (-P.coulomb * pi.w * o.w / (d2 * sqrt(d2))); }
+    return d * (k / d2);
+}
+fn cell_sum(i: u32, pi: vec4f, c: u32, own: bool) -> vec3f {     // one finest cell: exact below nearMax entries, Horvitz-Thompson above (PD-15)
+    let start = cellStart[c];
+    let count = cellStart[c + 1u] - start;
+    var f = vec3f(0.0);
+    if (count <= P.nearMax) {
+        for (var k = start; k < start + count; k = k + 1u) {
+            let jj = sortedIdx[k];
+            if (jj != i) { f = f + pair_force(i, pi, jj, pos[jj]); }
+        }
+        return f;
+    }
+    let base = (c ^ (P.iterationIndex * 0x9E3779B9u)) ^ P.seed;                  // the per-iteration draw seed (7.16)
+    var sampled = 0u;
+    for (var k = 0u; k < P.nearMax; k = k + 1u) {
+        let jj = sortedIdx[start + (lowbias32(base ^ (k * 0x85EBCA6Bu)) % count)];   // draw k: independent inclusion, with replacement (PD-15)
+        if (jj == i) { continue; }
+        f = f + pair_force(i, pi, jj, pos[jj]);
+        sampled = sampled + 1u;
+    }
+    if (sampled == 0u) { return vec3f(0.0); }
+    let others = select(count, count - 1u, own);
+    return f * (f32(others) / f32(sampled));                     // others / sampled over the realised sample (DEP-P4-K)
+}
+
+@compute @workgroup_size(WG)
+fn grid_near_field(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let t = linear_id(wid, lid.x);
+    let valid = t < P.n;
+    var i = 0u;
+    var pi = vec4f(0.0);
+    var f = vec3f(0.0);
+    if (valid) {
+        i = sortedIdx[t];                                          // sorted order (D24)
+        pi = pos[i];
+        let gf = f32(P.gridMax);
+        let q = (pi.xyz - S.gridMin.xyz) * S.invCellSize;
+        var c0 = vec3<i32>(floor(clamp(q, vec3f(-1.0), vec3f(gf + 1.0))));
+        if (P.dim == 2u) { c0.z = 0; }                             // 2D: the one z plane
+        let g = i32(P.gridMax);
+        var inside = c0.x >= 0 && c0.x < g && c0.y >= 0 && c0.y < g;
+        if (P.dim == 3u) { inside = inside && c0.z >= 0 && c0.z < g; }
+        if (inside) {
+            let zr = select(0, 1, P.dim == 3u);
+            for (var dz = -zr; dz <= zr; dz = dz + 1) {
+                for (var dy = -1; dy <= 1; dy = dy + 1) {
+                    for (var dx = -1; dx <= 1; dx = dx + 1) {
+                        let cx = c0.x + dx;
+                        let cy = c0.y + dy;
+                        let cz = c0.z + dz;
+                        if (cx < 0 || cx >= g || cy < 0 || cy >= g || cz < 0 || cz >= g) { continue; }
+                        let c = u32(cx) + P.gridMax * (u32(cy) + select(0u, P.gridMax * u32(cz), P.dim == 3u));
+                        f = f + cell_sum(i, pi, c, dx == 0 && dy == 0 && dz == 0);
+                    }
+                }
+            }
+        } else {
+            f = cell_sum(i, pi, grid_cells(), true);               // an outside node: the pseudo-cell alone
+        }
+    }
+    // epilogue (7.9, 7.10): gravity and force += under the guard, the swing / traction reduction outside it (K3's text)
+    var sw = 0.0;
+    var tr = 0.0;
+    if (valid) {
+        f = f + gravity_force(pi);
+        let fnew = load_force(i) + f;
+        store_force(i, fnew);
+        if (SWING_MODE == 1u) {                                    // NetworkX: positions and forces mixed, every node (7.2)
+            sw = pi.w * length(pi.xyz - fnew);
+            tr = 0.5 * pi.w * length(pi.xyz + fnew);
+        } else if (!mask_bit(fixedMask[i >> 5u], i)) {             // paper: free nodes only
+            let fold = load_old(i);
+            sw = pi.w * length(fnew - fold);
+            tr = 0.5 * pi.w * length(fnew + fold);
+        }
+    }
+    let tt = wg_reduce_vec4(vec4f(sw, tr, 0.0, 0.0), lid.x, 0u);   // uniform control flow: 256 -> 1
+    if (lid.x == 0u) { partials[group_id(wid)].swingTraction = tt.xy; }
+}
+`;
+//# sourceMappingURL=grid-near-field.wgsl.js.map

package/dist/src/wgsl/grid-near-field.wgsl.js.map

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

package/dist/src/wgsl/histogram.wgsl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `histogram` kernel body (spec 6 row 5; P4-T3): one atomicAdd per key into the global `hist` (zeroed by a fill
+ * dispatch earlier in the pass, PD-4). Order-independent, hence deterministic. A key >= P.bins is not counted (the
+ * caller's contract; the grid's keys are always < cells + 1). Body only; normative text.
+ */
+export declare const histogramWgsl = "\n@compute @workgroup_size(WG)\nfn histogram(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let i = linear_id(wid, lid.x);\n    if (i >= P.count) { return; }                                  // no barrier follows\n    let k = keys[i];\n    if (k < P.bins) { atomicAdd(&hist[k], 1u); }                   // order-independent: the count is the same whatever the schedule\n}\n";
+//# sourceMappingURL=histogram.wgsl.d.ts.map

package/dist/src/wgsl/histogram.wgsl.d.ts.map

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

package/dist/src/wgsl/histogram.wgsl.js

@@ -0,0 +1,15 @@
+/**
+ * The `histogram` kernel body (spec 6 row 5; P4-T3): one atomicAdd per key into the global `hist` (zeroed by a fill
+ * dispatch earlier in the pass, PD-4). Order-independent, hence deterministic. A key >= P.bins is not counted (the
+ * caller's contract; the grid's keys are always < cells + 1). Body only; normative text.
+ */
+export const histogramWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn histogram(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.count) { return; }                                  // no barrier follows
+    let k = keys[i];
+    if (k < P.bins) { atomicAdd(&hist[k], 1u); }                   // order-independent: the count is the same whatever the schedule
+}
+`;
+//# sourceMappingURL=histogram.wgsl.js.map

package/dist/src/wgsl/histogram.wgsl.js.map

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

package/dist/src/wgsl/indirect-finalize.wgsl.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `indirect-finalize` kernel body (spec 5.4; P4-T1): one lane turns the device-side count `counters[P.countIndex]`
+ * into the `(x, y, 1)` of an indirect dispatch by plan1d's rule (spec 5.2) and writes it with the count into the
+ * 16-byte slot `P.slot` of `args` (PD-2). No barrier follows the early return of the other lanes. Body only (spec 3.5,
+ * D9); the text is normative: the P4 sabotage rows are textual edits of it.
+ */
+export declare const indirectFinalizeWgsl = "\n@compute @workgroup_size(WG)\nfn indirect_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {\n    if (lid.x != 0u) { return; }                                   // one lane; no barrier follows (3.5 rule 1)\n    let count = counters[P.countIndex];\n    let groups = count / P.wg + select(0u, 1u, count % P.wg != 0u);   // ceil(count / wg) without the u32 wrap of (count + wg - 1) above 2^32 - wg: plan1d's rule (5.2) for ANY u32 count\n    var x = groups;\n    var y = 1u;\n    if (groups > MAX_WORKGROUPS_PER_DIM) {                         // the 2D split; y <= 1,025 for any u32 count\n        x = MAX_WORKGROUPS_PER_DIM;\n        y = (groups + MAX_WORKGROUPS_PER_DIM - 1u) / MAX_WORKGROUPS_PER_DIM;\n    }\n    let base = 4u * P.slot;                                        // 16-byte slots: (x, y, 1, count) (PD-2)\n    args[base] = x;\n    args[base + 1u] = y;\n    args[base + 2u] = 1u;\n    args[base + 3u] = count;\n}\n";
+//# sourceMappingURL=indirect-finalize.wgsl.d.ts.map

package/dist/src/wgsl/indirect-finalize.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indirect-finalize.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/indirect-finalize.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,26BAkBhC,CAAC"}

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

@@ -0,0 +1,26 @@
+/**
+ * The `indirect-finalize` kernel body (spec 5.4; P4-T1): one lane turns the device-side count `counters[P.countIndex]`
+ * into the `(x, y, 1)` of an indirect dispatch by plan1d's rule (spec 5.2) and writes it with the count into the
+ * 16-byte slot `P.slot` of `args` (PD-2). No barrier follows the early return of the other lanes. Body only (spec 3.5,
+ * D9); the text is normative: the P4 sabotage rows are textual edits of it.
+ */
+export const indirectFinalizeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn indirect_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x != 0u) { return; }                                   // one lane; no barrier follows (3.5 rule 1)
+    let count = counters[P.countIndex];
+    let groups = count / P.wg + select(0u, 1u, count % P.wg != 0u);   // ceil(count / wg) without the u32 wrap of (count + wg - 1) above 2^32 - wg: plan1d's rule (5.2) for ANY u32 count
+    var x = groups;
+    var y = 1u;
+    if (groups > MAX_WORKGROUPS_PER_DIM) {                         // the 2D split; y <= 1,025 for any u32 count
+        x = MAX_WORKGROUPS_PER_DIM;
+        y = (groups + MAX_WORKGROUPS_PER_DIM - 1u) / MAX_WORKGROUPS_PER_DIM;
+    }
+    let base = 4u * P.slot;                                        // 16-byte slots: (x, y, 1, count) (PD-2)
+    args[base] = x;
+    args[base + 1u] = y;
+    args[base + 2u] = 1u;
+    args[base + 3u] = count;
+}
+`;
+//# sourceMappingURL=indirect-finalize.wgsl.js.map

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

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

package/dist/src/wgsl/radix-hist.wgsl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `radix-hist` kernel body (spec 6 row 6; P4-T4): the RADIX_BINS-bin (2^8) digit histogram of one WG-wide block
+ * of keys, privatised in workgroup memory (atomics on workgroup memory are order-independent) and written
+ * DIGIT-MAJOR, `hist[digit * P.groups + group]`, so one exclusiveScan over the table yields, per digit, the offsets
+ * of the workgroups in workgroup order -- what a stable LSD scatter needs. The bitwise operators act on a KEY and a
+ * DIGIT, never on an arc index (house rule). Body only; normative text.
+ */
+export declare const radixHistWgsl = "\nvar<workgroup> local: array<atomic<u32>, RADIX_BINS>;\n\n@compute @workgroup_size(WG)\nfn radix_hist(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    for (var b = lid.x; b < RADIX_BINS; b = b + WG) { atomicStore(&local[b], 0u); }\n    workgroupBarrier();\n    let g = group_id(wid);\n    let i = g * WG + lid.x;\n    if (i < P.count) {\n        let d = (keys[i] >> P.shift) & RADIX_DIGIT_MASK;                 // the pass's digit\n        atomicAdd(&local[d], 1u);\n    }\n    workgroupBarrier();\n    // Above MAX_1D_ITEMS plan1d pads the 2D grid to x * y >= P.groups workgroups; a padding workgroup (g >= P.groups)\n    // holds an all-zero table and its digit-major slot b * P.groups + g is digit b + 1's slot of a REAL group, so it\n    // must not store. Uniform per workgroup, no barrier inside. Every test size fits 1D (the ladder tops at 2^22); no\n    // case reaches this branch, so the guard is proved by reading, not by a run.\n    if (g < P.groups) {\n        for (var b = lid.x; b < RADIX_BINS; b = b + WG) { hist[b * P.groups + g] = atomicLoad(&local[b]); }   // digit-major\n    }\n}\n";
+//# sourceMappingURL=radix-hist.wgsl.d.ts.map

package/dist/src/wgsl/radix-hist.wgsl.d.ts.map

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

package/dist/src/wgsl/radix-hist.wgsl.js

@@ -0,0 +1,31 @@
+/**
+ * The `radix-hist` kernel body (spec 6 row 6; P4-T4): the RADIX_BINS-bin (2^8) digit histogram of one WG-wide block
+ * of keys, privatised in workgroup memory (atomics on workgroup memory are order-independent) and written
+ * DIGIT-MAJOR, `hist[digit * P.groups + group]`, so one exclusiveScan over the table yields, per digit, the offsets
+ * of the workgroups in workgroup order -- what a stable LSD scatter needs. The bitwise operators act on a KEY and a
+ * DIGIT, never on an arc index (house rule). Body only; normative text.
+ */
+export const radixHistWgsl = /* wgsl */ `
+var<workgroup> local: array<atomic<u32>, RADIX_BINS>;
+
+@compute @workgroup_size(WG)
+fn radix_hist(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    for (var b = lid.x; b < RADIX_BINS; b = b + WG) { atomicStore(&local[b], 0u); }
+    workgroupBarrier();
+    let g = group_id(wid);
+    let i = g * WG + lid.x;
+    if (i < P.count) {
+        let d = (keys[i] >> P.shift) & RADIX_DIGIT_MASK;                 // the pass's digit
+        atomicAdd(&local[d], 1u);
+    }
+    workgroupBarrier();
+    // Above MAX_1D_ITEMS plan1d pads the 2D grid to x * y >= P.groups workgroups; a padding workgroup (g >= P.groups)
+    // holds an all-zero table and its digit-major slot b * P.groups + g is digit b + 1's slot of a REAL group, so it
+    // must not store. Uniform per workgroup, no barrier inside. Every test size fits 1D (the ladder tops at 2^22); no
+    // case reaches this branch, so the guard is proved by reading, not by a run.
+    if (g < P.groups) {
+        for (var b = lid.x; b < RADIX_BINS; b = b + WG) { hist[b * P.groups + g] = atomicLoad(&local[b]); }   // digit-major
+    }
+}
+`;
+//# sourceMappingURL=radix-hist.wgsl.js.map

package/dist/src/wgsl/radix-hist.wgsl.js.map

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

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

@@ -0,0 +1,9 @@
+/**
+ * The `radix-scatter` kernel body (spec 6 row 6; P4-T4): the stable scatter of one LSD pass. Lane 0 ranks the block's
+ * keys serially in index order with a RADIX_BINS-entry counter table (PD-5: deterministic and stable, WG steps per
+ * workgroup; ponytail: the 8-way split ranking of GraphWaGu is the upgrade if T-6 shows the sort on the critical
+ * path), then every lane writes its key and value at `offsets[digit * P.groups + group] + rank`. Body only;
+ * normative text.
+ */
+export declare const radixScatterWgsl = "\nvar<workgroup> rank: array<u32, WG>;\nvar<workgroup> cnt: array<u32, RADIX_BINS>;\n\n@compute @workgroup_size(WG)\nfn radix_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    for (var b = lid.x; b < RADIX_BINS; b = b + WG) { cnt[b] = 0u; }\n    let g = group_id(wid);\n    let i = g * WG + lid.x;\n    var key = 0u;\n    var d = 0u;\n    if (i < P.count) {\n        key = keys[i];\n        d = (key >> P.shift) & RADIX_DIGIT_MASK;\n    }\n    workgroupBarrier();\n    if (lid.x == 0u) {                                             // serial stable ranking (PD-5)\n        let last = min(WG, P.count - g * WG);\n        for (var s = 0u; s < last; s = s + 1u) {\n            let ds = (keys[g * WG + s] >> P.shift) & RADIX_DIGIT_MASK;\n            rank[s] = cnt[ds];\n            cnt[ds] = cnt[ds] + 1u;\n        }\n    }\n    workgroupBarrier();\n    if (i < P.count) {\n        let dst = offsets[d * P.groups + g] + rank[lid.x];\n        keysOut[dst] = key;\n        valsOut[dst] = vals[i];\n    }\n}\n";
+//# sourceMappingURL=radix-scatter.wgsl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"radix-scatter.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/radix-scatter.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,iiCA+B5B,CAAC"}

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

@@ -0,0 +1,40 @@
+/**
+ * The `radix-scatter` kernel body (spec 6 row 6; P4-T4): the stable scatter of one LSD pass. Lane 0 ranks the block's
+ * keys serially in index order with a RADIX_BINS-entry counter table (PD-5: deterministic and stable, WG steps per
+ * workgroup; ponytail: the 8-way split ranking of GraphWaGu is the upgrade if T-6 shows the sort on the critical
+ * path), then every lane writes its key and value at `offsets[digit * P.groups + group] + rank`. Body only;
+ * normative text.
+ */
+export const radixScatterWgsl = /* wgsl */ `
+var<workgroup> rank: array<u32, WG>;
+var<workgroup> cnt: array<u32, RADIX_BINS>;
+
+@compute @workgroup_size(WG)
+fn radix_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    for (var b = lid.x; b < RADIX_BINS; b = b + WG) { cnt[b] = 0u; }
+    let g = group_id(wid);
+    let i = g * WG + lid.x;
+    var key = 0u;
+    var d = 0u;
+    if (i < P.count) {
+        key = keys[i];
+        d = (key >> P.shift) & RADIX_DIGIT_MASK;
+    }
+    workgroupBarrier();
+    if (lid.x == 0u) {                                             // serial stable ranking (PD-5)
+        let last = min(WG, P.count - g * WG);
+        for (var s = 0u; s < last; s = s + 1u) {
+            let ds = (keys[g * WG + s] >> P.shift) & RADIX_DIGIT_MASK;
+            rank[s] = cnt[ds];
+            cnt[ds] = cnt[ds] + 1u;
+        }
+    }
+    workgroupBarrier();
+    if (i < P.count) {
+        let dst = offsets[d * P.groups + g] + rank[lid.x];
+        keysOut[dst] = key;
+        valsOut[dst] = vals[i];
+    }
+}
+`;
+//# sourceMappingURL=radix-scatter.wgsl.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"radix-scatter.wgsl.js","sourceRoot":"","sources":["../../../src/wgsl/radix-scatter.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B1C,CAAC"}

package/dist/src/wgsl/scan-add.wgsl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The `scan-add` kernel body (spec 6 row 2 step (c); P4-T2): adds the exclusive prefix of its block's sum,
+ * `blockOffsets[group]`, to every element of the block. Body only; normative text.
+ */
+export declare const scanAddWgsl = "\n@compute @workgroup_size(WG)\nfn scan_add(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let g = group_id(wid);\n    let i = g * WG + lid.x;\n    if (i >= P.count) { return; }                                  // no barrier follows\n    out[i] = out[i] + blockOffsets[g];\n}\n";
+//# sourceMappingURL=scan-add.wgsl.d.ts.map

package/dist/src/wgsl/scan-add.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-add.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/scan-add.wgsl.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,uUAQvB,CAAC"}

package/dist/src/wgsl/scan-add.wgsl.js

@@ -0,0 +1,14 @@
+/**
+ * The `scan-add` kernel body (spec 6 row 2 step (c); P4-T2): adds the exclusive prefix of its block's sum,
+ * `blockOffsets[group]`, to every element of the block. Body only; normative text.
+ */
+export const scanAddWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn scan_add(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let g = group_id(wid);
+    let i = g * WG + lid.x;
+    if (i >= P.count) { return; }                                  // no barrier follows
+    out[i] = out[i] + blockOffsets[g];
+}
+`;
+//# sourceMappingURL=scan-add.wgsl.js.map

package/dist/src/wgsl/scan-add.wgsl.js.map

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

package/dist/src/wgsl/scan-block.wgsl.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `scan-block` kernel body (spec 6 row 2; P4-T2): an exclusive prefix sum of one WG-wide block of `src` in
+ * workgroup memory (Hillis-Steele, log2(WG) rounds of two barriers each, every lane in uniform control flow) into
+ * `out`, and the block's inclusive total into `blockSums[group]`. u32 addition is exact in any order, so the
+ * output is bitwise the same on every adapter (PD-3). Body only (spec 3.5, D9); normative text.
+ */
+export declare const scanBlockWgsl = "\nvar<workgroup> sh: array<u32, WG>;\n\n@compute @workgroup_size(WG)\nfn scan_block(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let g = group_id(wid);\n    let i = g * WG + lid.x;\n    var v = 0u;\n    if (i < P.count) { v = src[i]; }\n    sh[lid.x] = v;\n    workgroupBarrier();\n    for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan; uniform: every lane runs every round\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 (i < P.count) { out[i] = inclusive - v; }                  // exclusive = inclusive - own value\n    if (lid.x == WG - 1u) { blockSums[g] = inclusive; }           // the block total (the last lane's inclusive sum)\n}\n";
+//# sourceMappingURL=scan-block.wgsl.d.ts.map

package/dist/src/wgsl/scan-block.wgsl.d.ts.map

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

package/dist/src/wgsl/scan-block.wgsl.js

@@ -0,0 +1,30 @@
+/**
+ * The `scan-block` kernel body (spec 6 row 2; P4-T2): an exclusive prefix sum of one WG-wide block of `src` in
+ * workgroup memory (Hillis-Steele, log2(WG) rounds of two barriers each, every lane in uniform control flow) into
+ * `out`, and the block's inclusive total into `blockSums[group]`. u32 addition is exact in any order, so the
+ * output is bitwise the same on every adapter (PD-3). Body only (spec 3.5, D9); normative text.
+ */
+export const scanBlockWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;
+
+@compute @workgroup_size(WG)
+fn scan_block(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let g = group_id(wid);
+    let i = g * WG + lid.x;
+    var v = 0u;
+    if (i < P.count) { v = src[i]; }
+    sh[lid.x] = v;
+    workgroupBarrier();
+    for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan; uniform: every lane runs every round
+        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 (i < P.count) { out[i] = inclusive - v; }                  // exclusive = inclusive - own value
+    if (lid.x == WG - 1u) { blockSums[g] = inclusive; }           // the block total (the last lane's inclusive sum)
+}
+`;
+//# sourceMappingURL=scan-block.wgsl.js.map

package/dist/src/wgsl/scan-block.wgsl.js.map

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

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

@@ -1,13 +1,27 @@
 /**
- * The `segmented-reduce` kernel body (spec 6 row 3; contract 4.5), TIER 0 = thread-per-row: one invocation per row
- * of [P.start, P.end) folds the VALUE snippet over the row's arcs inside the bound window [P.arcBase, P.arcEnd) and
- * writes out[i] as f32; a row with no arcs gets the identity element (0 for sum, F32_MAX for min, -F32_MAX for
- * max). The mid / high degree tiers (TIER 1 / 2 over degreeOrder()) land at P4. The body is normative: a sabotage
- * mutation (test/helpers/sabotage.ts) is a textual edit of it, so it is not restyled.
+ * The `segmented-reduce` kernel body (spec 6 row 3; contract 4.5) in its three degree tiers (P4-T5, PD-6). Every
+ * tier folds the VALUE snippet over a row's arcs inside the bound window [P.arcBase, P.arcEnd) and writes out[i]
+ * as f32 (a row with no arcs gets the identity element: 0 for sum, F32_MAX for min, -F32_MAX for max); the row is
+ * `perm[row]` under USE_PERM and `row` otherwise, over the rows [P.start, P.end) of the dispatch. TIER 0 is one row
+ * per thread (no barrier, so its early return is legal); TIER 1 is 32 lanes per row and WG / 32 rows per workgroup,
+ * reduced by a five-step tree in workgroup memory (bitwise the same on every subgroup size); TIER 2 is one row per
+ * workgroup through `wg_reduce_f32` of the prelude (the subgroup variant when the feature exists, the workgroup twin
+ * otherwise -- hence `needs: ["subgroups"]`). The tier bodies are functions called under `if (TIER == 0u)`, an
+ * override, so every barrier is reached in uniform control flow. The body is normative: a sabotage mutation
+ * (test/helpers/sabotage.ts) is a textual edit of it, so it is not restyled.
+ *
+ * TIER 0 folds its row through `row_fold_dense`, a stride-one copy of `row_fold`, because the shader compiler emits
+ * `row_fold(i, 0u, 1u)` as a call and leaves the stride in a parameter: the loop then walks the row with a runtime
+ * step, which costs the strength-reduced addressing into colIdx / weights and the unrolling that keeps several loads
+ * in flight per thread. PageRank's out-weight pass, the only caller that passes no tiers today, runs TIER 0 alone,
+ * and under the tiers TIER 0 still folds the low-degree rows, which are most of them. The two folds spell their
+ * locals apart (`lo` / `hi` / `k` against `a0` / `a1`) so that each sabotage row names exactly one of them; the
+ * VALUE snippet sees the same `row`, `arc`, `nbr` and `weight` in both.
  */
 /**
- * Entry point `segmented_reduce`; overrides OP (0 sum, 1 min, 2 max) and TIER (0); snippet slot VALUE: statements
- * assigning `v` from `row`, `arc`, `nbr`, `weight` (`target` is a WGSL reserved word, hence `nbr`).
+ * Entry point `segmented_reduce`; overrides OP (0 sum, 1 min, 2 max) and TIER (0 thread-per-row, 1 32-lanes-per-row,
+ * 2 workgroup-per-row); snippet slot VALUE: statements assigning `v` from `row`, `arc`, `nbr`, `weight` (`target`
+ * is a WGSL reserved word, hence `nbr`).
  */
-export declare const segmentedReduceWgsl = "\nfn identity() -> f32 { if (OP == 1u) { return F32_MAX; } if (OP == 2u) { return -F32_MAX; } return 0.0; }\nfn comb(a: f32, b: f32) -> f32 { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }\n\n@compute @workgroup_size(WG)\nfn segmented_reduce(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    let row = linear_id(wid, lid.x) + P.start;\n    if (row >= P.end) { return; }\n    let i = select(row, perm[row], USE_PERM);\n    let a0 = max(rowPtr[i], P.arcBase);\n    let a1 = min(rowPtr[i + 1u], P.arcEnd);\n    var acc = identity();\n    for (var arc = a0; arc < a1; arc = arc + 1u) {\n        let nbr = colIdx[arc - P.arcBase];               // the neighbour index (`target` is a WGSL reserved word)\n        var weight = 1.0;\n        if (HAS_WEIGHTS) { weight = weights[arc - P.arcBase]; }\n        var v = 0.0;\n        //@@VALUE@@\n        acc = comb(acc, v);\n    }\n    out[i] = select(acc, comb(out[i], acc), P.accumulate == 1u);\n}\n";
+export declare const segmentedReduceWgsl = "\nfn identity() -> f32 { if (OP == 1u) { return F32_MAX; } if (OP == 2u) { return -F32_MAX; } return 0.0; }\nfn comb(a: f32, b: f32) -> f32 { if (OP == 1u) { return min(a, b); } if (OP == 2u) { return max(a, b); } return a + b; }\nfn row_node(row: u32) -> u32 { return select(row, perm[row], USE_PERM); }\nfn row_fold(i: u32, lane: u32, step: u32) -> f32 {              // the arcs of row i this lane walks inside the bound window [P.arcBase, P.arcEnd)\n    let row = i;                                                 // the CSR row the VALUE snippet may name (the node index, under USE_PERM too)\n    let a0 = max(rowPtr[i], P.arcBase);\n    let a1 = min(rowPtr[i + 1u], P.arcEnd);\n    var acc = identity();\n    for (var arc = a0 + lane; arc < a1; arc = arc + step) {\n        let nbr = colIdx[arc - P.arcBase];               // the neighbour index (`target` is a WGSL reserved word)\n        var weight = 1.0;\n        if (HAS_WEIGHTS) { weight = weights[arc - P.arcBase]; }\n        var v = 0.0;\n        //@@VALUE@@\n        acc = comb(acc, v);\n    }\n    return acc;\n}\nfn row_fold_dense(i: u32) -> f32 {                              // TIER 0's stride-one twin of row_fold (see the header)\n    let row = i;                                                 // the CSR row the VALUE snippet may name (as in row_fold)\n    let lo = max(rowPtr[i], P.arcBase);\n    let hi = min(rowPtr[i + 1u], P.arcEnd);\n    var acc = identity();\n    for (var arc = lo; arc < hi; arc = arc + 1u) {\n        let k = arc - P.arcBase;                         // the window-local index; this walk is contiguous\n        let nbr = colIdx[k];\n        var weight = 1.0;\n        if (HAS_WEIGHTS) { weight = weights[k]; }\n        var v = 0.0;\n        //@@VALUE@@\n        acc = comb(acc, v);\n    }\n    return acc;\n}\nfn finish(i: u32, acc: f32) { out[i] = select(acc, comb(out[i], acc), P.accumulate == 1u); }\nfn tier0(wid: vec3<u32>, lane: u32) {                            // TIER 0: one row per thread over [P.start, P.end); no barrier, so the early return is legal (3.5 rule 1)\n    let row = linear_id(wid, lane) + P.start;\n    if (row >= P.end) { return; }\n    let i = row_node(row);\n    finish(i, row_fold_dense(i));\n}\n\nvar<workgroup> sh: array<f32, WG>;\n\nfn tiered(wid: vec3<u32>, lid: u32) {                            // TIER 1: 32 lanes per row, WG / 32 rows per workgroup; TIER 2: WG lanes per row (PD-6)\n    let g = group_id(wid);\n    var row = P.start + g;\n    var lane = lid;\n    var step = WG;\n    if (TIER == 1u) { row = P.start + g * (WG / 32u) + lid / 32u; lane = lid % 32u; step = 32u; }\n    let valid = row < P.end;\n    var i = 0u;\n    var acc = identity();\n    if (valid) { i = row_node(row); acc = row_fold(i, lane, step); }\n    if (TIER == 1u) {\n        sh[lid] = acc;\n        workgroupBarrier();\n        for (var s = 16u; s >= 1u; s = s / 2u) {                 // the five-step tree over each 32-lane group; every lane runs every step\n            var t = identity();\n            if (lane < s) { t = sh[lid + s]; }\n            workgroupBarrier();\n            sh[lid] = comb(sh[lid], t);\n            workgroupBarrier();\n        }\n        if (valid && lane == 0u) { finish(i, sh[lid]); }\n    }\n    if (TIER == 2u) {\n        let t = wg_reduce_f32(acc, lid, OP);                     // the workgroup tree of the prelude (subgroup variant when available)\n        if (valid && lid == 0u) { finish(i, t); }\n    }\n}\n\n@compute @workgroup_size(WG)\nfn segmented_reduce(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {\n    if (TIER == 0u) { tier0(wid, lid.x); } else { tiered(wid, lid.x); }\n}\n";
 //# sourceMappingURL=segmented-reduce.wgsl.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"segmented-reduce.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/segmented-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,mgCAsB/B,CAAC"}
+{"version":3,"file":"segmented-reduce.wgsl.d.ts","sourceRoot":"","sources":["../../../src/wgsl/segmented-reduce.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gmHA6E/B,CAAC"}