@graphty/webgpu-graph-algorithms 0.6.5 → 0.6.6

package/src/memory/residency.ts

@@ -579,7 +579,9 @@ export class GraphResidency {
     }
 
     /**
-     * One resident per array (spec 4.3: views upload in perArray mode, never into the arena).
+     * One resident per array (spec 4.3: views upload in perArray mode, never into the arena). An empty array (the
+     * colIdx of an edgeless directed reverse view, the src / dst of an edgeless edgeList) is skipped: spec 5.6 never
+     * uploads a zero-length array, and Kernel.bind rejects a zero-size binding, so it is absent as in core().
      * @param record - the owning record
      * @param arrays - the named arrays
      * @param label - the buffer label prefix
@@ -592,6 +594,9 @@ export class GraphResidency {
     ): Readonly<Record<string, Binding>> {
         const bindings: Record<string, Binding> = {};
         for (const [name, array] of arrays) {
+            if (array.byteLength === 0) {
+                continue;
+            }
             const resident = this.upload(record, array, array, `${label}:${name}`);
             bindings[name] = { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
         }
@@ -606,19 +611,24 @@ export class GraphResidency {
      * lengths, so keying the packed buffer on `rev.rowPtr` would make the packed and the unpacked view of one
      * snapshot collide -- whichever was built second would get the other's buffer. The record still owns the
      * resident, so release(s) destroys it with the rest. Offsets are STORAGE_ALIGN-aligned because Kernel.bind
-     * rejects any other offset synchronously (E_INVALID_ARGUMENT { argument: "offset" }).
+     * rejects any other offset synchronously (E_INVALID_ARGUMENT { argument: "offset" }). Empty arrays are left
+     * out as in separateArrays; when nothing is left, nothing is uploaded.
      * @param record - the owning record
-     * @param arrays - the named arrays, in buffer order
+     * @param all - the named arrays, in buffer order
      * @param key - the marker object the resident is keyed on
      * @param label - the buffer label
      * @returns the bindings by name, all into the one buffer
      */
     private packArrays(
         record: ResidencyRecord,
-        arrays: readonly (readonly [string, TypedArrayData])[],
+        all: readonly (readonly [string, TypedArrayData])[],
         key: object,
         label: string,
     ): Readonly<Record<string, Binding>> {
+        const arrays = all.filter(([, array]) => array.byteLength > 0);
+        if (arrays.length === 0) {
+            return Object.freeze({});
+        }
         const offsets: number[] = [];
         let total = 0;
         for (const [, array] of arrays) {

package/src/primitives/frontier.ts

@@ -71,6 +71,7 @@ export const W: Readonly<{
     thresholdBits: 22;
     deltaBits: 23;
     path: 24;
+    nextDegreeSum: 25;
 }> = Object.freeze({
     frontierCount: 0,
     nextFrontierCount: 1,
@@ -97,6 +98,7 @@ export const W: Readonly<{
     thresholdBits: 22,
     deltaBits: 23,
     path: 24,
+    nextDegreeSum: 25,
 });
 
 /** The words a `reset` seeds (every other word is zeroed). */

package/src/primitives/grid-pyramid.ts

@@ -1,11 +1,11 @@
 /**
  * The grid pyramid (spec 6 row 12, 7.7 G4-G5; P4-T9): the planner that records, into the caller's pass, the finest
- * centroids (G4, `grid-centroid`: thread per cell over `cells + 1`, the pseudo-cell included), the hub-cell
+ * centroids (G4, `grid-centroid`: thread per cell over `cells + outsideCells`, the pseudo-cells included), the hub-cell
  * completion (G4a: the T1 `indirect-finalize` over `hubCounters[0]` into `hubArgs` with `wg = 1`, so the finalize's
  * `ceil(count / wg)` is ONE workgroup per hub cell; G4b: `grid-centroid-hub`, one workgroup per hub cell, dispatched
  * indirectly; PD-13, DEP-P4-I) and one `grid-downsample` dispatch per coarser
  * level (G5). Level 0 holds `[sum m x, sum m y, sum m z, sum m]` per cell; every parent is the sum of its 2^dim
- * children; the pseudo-cell (index `cells` of level 0) is never a child. No atomics touch the sums (design 6 row 12:
+ * children; the pseudo-cells (indices `cells ..` of level 0) are never children. No atomics touch the sums (design 6 row 12:
  * bitwise reproducible); the only atomics are the hub append and the occupancy max.
  *
  * The named grid buffers (`pyramid`, `hubList`, `hubCounters`, `hubArgs`) are the caller's (the model's
@@ -34,9 +34,9 @@ export interface GridPyramidBindings {
     readonly params: Binding;
     /** `n` words: the sorted node indices (the T8 build). */
     readonly sortedIdx: Binding;
-    /** `cells + 2` words: the exclusive scan of the cell histogram (the T8 build). */
+    /** `histWords` (`cells + 2^dim + 1`) words: the exclusive scan of the cell histogram (the T8 build). */
     readonly cellStart: Binding;
-    /** `pyramidCells` vec4f: every level, level 0 first with the pseudo-cell at index `cells`. */
+    /** `pyramidCells` vec4f: every level, level 0 first with the 2^dim orthant pseudo-cells from index `cells`. */
     readonly pyramid: Binding;
     /** The hub cells' indices, appended by G4 (at least one word; at most `floor(n / (GRID_HUB_CELL + 1))` are ever written, so `ceil(n / GRID_HUB_CELL)` words always suffice). */
     readonly hubList: Binding;
@@ -204,7 +204,8 @@ class GridPyramidPlannerImpl implements GridPyramidPlanner {
         }
         const { centroid, finalize, hub, downsample } = this.kernels;
         const one: DispatchPlan = { x: 1, y: 1, z: 1, items: 1, stride: null };
-        centroid.dispatch(pass, bound.centroid, plan1d(spec.cells + 1, scope.workgroupSize, scope.caps), [paramsOffset]);
+        const level0 = spec.cells + spec.outsideCells;
+        centroid.dispatch(pass, bound.centroid, plan1d(level0, scope.workgroupSize, scope.caps), [paramsOffset]);
         finalize.dispatch(pass, bound.finalize, one, [bound.finalizeOffset]);
         hub.dispatchIndirect(pass, bound.hub, bound.hubArgs, 0, [paramsOffset]);
         this.dispatches = 3;

package/src/primitives/grid.ts

@@ -3,8 +3,9 @@
  * the caller's pass, the cell keys (G1, `grid-cell-key`), the stable sort by key (G2: `radixSort` at GRID_SORT_BITS,
  * or `countingSortByKey` when the caller asks for the set-deterministic path) and the per-cell histogram with its
  * exclusive scan (G3: the `histogram` kernel over `cellKey` and the `scan` of it; DEP-P4-I names no grid-specific
- * id). `cellHist` and `cellStart` hold `cells + 2` words: every real cell, the outside pseudo-cell at index `cells`
- * and one more so `cellStart[cells + 1] === n` closes the last range. Every zeroing is a `fill` dispatch inside the
+ * id). `cellHist` and `cellStart` hold `histWords = cells + 2^dim + 1` words: every real cell, the 2^dim outside
+ * pseudo-cells (one per orthant about the grid centre, issue #90) from index `cells`, and one more so
+ * `cellStart[histWords - 1] === n` closes the last range. Every zeroing is a `fill` dispatch inside the
  * pass (PD-12), never an encoder clear.
  *
  * The named grid buffers (`cellKey`, `cellVal`, `sortedKey`, `sortedIdx`, `cellHist`, `cellStart`) are the caller's
@@ -39,11 +40,13 @@ export interface GridSpec {
     readonly g: number;
     /** `log2(G / GRID_COARSEST_SIDE) + 1`. */
     readonly levels: number;
-    /** `G^dim` finest cells; the outside pseudo-cell is index `cells`. */
+    /** `G^dim` finest cells; the outside pseudo-cells are indices `cells .. cells + outsideCells - 1`. */
     readonly cells: number;
-    /** `cells + 2`: the length of `cellHist` / `cellStart`. */
+    /** `2^dim`: one outside pseudo-cell per orthant about the grid centre (issue #90). */
+    readonly outsideCells: number;
+    /** `cells + outsideCells + 1`: the length of `cellHist` / `cellStart`. */
     readonly histWords: number;
-    /** The first cell of every level inside the pyramid: `levelOffsets[0] = 0`, level 0 holds `cells + 1` (the pseudo-cell), level L `(G / 2^L)^dim`. */
+    /** The first cell of every level inside the pyramid: `levelOffsets[0] = 0`, level 0 holds `cells + outsideCells` (the pseudo-cells last), level L `(G / 2^L)^dim`. */
     readonly levelOffsets: readonly number[];
     /** Every level's cells together: `levelOffsets[levels - 1] + GRID_COARSEST_SIDE^dim`. */
     readonly pyramidCells: number;
@@ -81,8 +84,8 @@ function floorPow2(x: number): number {
  * The grid of `n` nodes in `dim` dimensions under the tuning (spec 7.7 geometry table; PD-9): `G = clamp(nextPow2(2 *
  * ceil(n^(1 / dim))), GRID_MIN_SIDE, floorPow2(gridMax))` where `gridMax` is `gridMax2D` or `gridMax3D`, rounded DOWN
  * to a power of two so every level's side is an integer (512 and 128 stay; 100 becomes 64); `levels = log2(G /
- * GRID_COARSEST_SIDE) + 1`. At the caps: 349,521 pyramid cells in 2D, 2,396,737 in 3D (the design's counts plus the
- * pseudo-cell).
+ * GRID_COARSEST_SIDE) + 1`. At the caps: 349,524 pyramid cells in 2D, 2,396,744 in 3D (the design's counts plus the
+ * 2^dim pseudo-cells).
  * @param n - the node count (>= 0)
  * @param dim - 2 or 3
  * @param tuning - the resolved layout tuning (`gridMax2D`, `gridMax3D`, `deterministic`)
@@ -102,10 +105,11 @@ export function gridSpecFor(
         levels++;
     }
     const cells = g ** dim;
+    const outsideCells = 2 ** dim;
     const levelOffsets: number[] = [0];
     let s = g;
     for (let level = 0; level + 1 < levels; level++) {
-        levelOffsets.push(levelOffsets[level] + s ** dim + (level === 0 ? 1 : 0));
+        levelOffsets.push(levelOffsets[level] + s ** dim + (level === 0 ? outsideCells : 0));
         s /= 2;
     }
     return {
@@ -113,7 +117,8 @@ export function gridSpecFor(
         g,
         levels,
         cells,
-        histWords: cells + 2,
+        outsideCells,
+        histWords: cells + outsideCells + 1,
         levelOffsets: Object.freeze(levelOffsets),
         pyramidCells: levelOffsets[levels - 1] + GRID_COARSEST_SIDE ** dim,
         deterministic: tuning.deterministic,
@@ -121,7 +126,7 @@ export function gridSpecFor(
 }
 
 /**
- * The bytes of the pyramid (spec 7.7: 16 B per cell, every level, the pseudo-cell included): 38,347,792 at the 3D cap.
+ * The bytes of the pyramid (spec 7.7: 16 B per cell, every level, the pseudo-cells included): 38,347,904 at the 3D cap.
  * @param spec - the grid
  * @returns the byte length
  */
@@ -155,9 +160,9 @@ export interface GridBuildBindings {
     readonly sortedKey: Binding;
     /** `n` words: the sorted node indices. */
     readonly sortedIdx: Binding;
-    /** `cells + 2` words: the per-cell counts. */
+    /** `histWords` (`cells + 2^dim + 1`) words: the per-cell counts. */
     readonly cellHist: Binding;
-    /** `cells + 2` words: the exclusive scan of `cellHist`. */
+    /** `histWords` (`cells + 2^dim + 1`) words: the exclusive scan of `cellHist`. */
     readonly cellStart: Binding;
 }
 

package/src/wgsl/advance-expand.wgsl.ts

@@ -7,8 +7,9 @@
  * 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`
+ * detector, never clamped) and in `frontierDegreeSum` (the inspect seam's per-level expansion count, rotated into
+ * `prevDegreeSum` by the boundary; Beamer's m_f is `nextDegreeSum`, measured by `bfs-next-degree` -- issue #391);
+ * 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
@@ -44,7 +45,7 @@ fn advance_expand(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocati
         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)
+            atomicAdd(&counters[2], aggregate);                          // frontierDegreeSum: what this level expanded (the inspect seam)
         }
         workgroupBarrier();
         for (var p = lid.x; p < aggregate; p = p + WG) {                 // strip [0, aggregate): lane j takes j, j + WG, ...

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

@@ -11,9 +11,10 @@
  * 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
+ * level expands nothing), which is why that word is not Beamer's m_f: `bfs-next-degree` sums the degree of what
+ * this sweep CLAIMS into `nextDegreeSum`, so the boundary's test and its `unvisitedDegreeSum` subtraction are exact
+ * on a bottom-up level like any other (issue #391; 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 */ `

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

@@ -4,15 +4,15 @@
  * 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
+ * to the bound arc window, adds its degree to `frontierDegreeSum` (so the inspect seam's per-level expansion count
+ * covers 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
+ * holds twice the level's expanded degree; since issue #391 no decision reads it (Beamer's m_f is `nextDegreeSum`
+ * and the boundary subtracts that), so the doubling only reaches the inspect seam's `prevDegreeSum`. 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
@@ -44,7 +44,7 @@ fn bfs_fused(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
             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
+            atomicAdd(&counters[2], d);                                  // frontierDegreeSum, so the inspect seam sees fused levels too
         }
         let deg = workgroupUniformLoad(&wdeg);                           // uniform: the loop below may hold barriers
         let start = workgroupUniformLoad(&wstart);

package/src/wgsl/bfs-next-degree.wgsl.ts

@@ -0,0 +1,33 @@
+/**
+ * The `bfs-next-degree` kernel body (design 8.4; issue #391, the amendment to P8-T8's PD-21): Beamer's m_f measured
+ * EXACTLY, at the end of every level, as the out-degree sum of the vertices the level just claimed -- the next
+ * frontier, which is what the next boundary decides the direction FOR. It grid-strides over the output vertex
+ * queue (`nextFrontierCount`, word 1, the claim kernels' append span; `P.stride` the plan's stride), reads each
+ * entry's out-degree from the `outDegree` view, reduces the lane sums with the prelude's `wg_reduce_u32` and lands
+ * ONE `atomicAdd` per workgroup in `nextDegreeSum` (word 25), which `frontier-finalize` role 0 reads for the
+ * switch-into-bottom-up test, subtracts from `unvisitedDegreeSum` and zeroes for the next level. It runs on every
+ * path that claims (the path word 24 non-zero: two-phase, fused, bottom-up, the retry) and does nothing on a level
+ * past the end.
+ *
+ * Why a kernel of its own: before it, the test used `frontierDegreeSum` (word 2), which the EXPANSION of the
+ * previous frontier accumulates, so the boundary compared the degree of the frontier it had just finished with the
+ * unvisited set, one level stale, and a bottom-up level (which expands nothing) left it at 0. On the 1M / 10M R-MAT
+ * that misses the switch at the level that matters: the frontier of 46,524 hubs at level 1 has 13.6M out-arcs, the
+ * unvisited set 7.3M, and the boundary saw the source's 86,405 instead -- top-down wrote 13.6M edge-queue entries
+ * where the bottom-up sweep reads 0.6M. Measuring the next frontier's degree at claim time is Beamer's own m_f, and
+ * the same word makes `unvisitedDegreeSum` exact after a bottom-up level too. Uniformity (spec 3.5 rule 1): the
+ * loop holds no barrier (its trip count is per lane), and the reduction runs 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 bfsNextDegreeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bfs_next_degree(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let count = select(0u, atomicLoad(&counters[1]), atomicLoad(&counters[24]) != 0u);   // nextFrontierCount, on a level that claimed (the path word)
+    var sum = 0u;
+    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {   // no barrier inside: the trip count is per lane
+        sum = sum + outDegree[frontier[i]];
+    }
+    let total = wg_reduce_u32(sum, lid.x, 0u);                       // the prelude's workgroup sum; uniform: after the loop
+    if (lid.x == 0u) { atomicAdd(&counters[25], total); }            // nextDegreeSum: ONE atomic per workgroup
+}
+`;

package/src/wgsl/fa2-repulsion-exact.wgsl.ts

@@ -9,6 +9,9 @@
  * `partials[group].swingTraction`. `pos` is `array<vec4f>` with the mass in `.w`; `force` / `oldForce` are stride-3
  * `array<f32>` read through the per-body helpers (4.4 rule 6). Normative text, copied verbatim: the P1-T5 sabotage
  * rows (gravity sign, `k / d2`, the `jj != i` guard, the `.w` mass lane) are textual edits of this string.
+ * The j range is split into passes of at most EXACT_TILES_PER_PASS tiles (issue #87: llvmpipe's per-invocation loop
+ * budget); an earlier pass adds its partial sum into `force`, the last one runs gravity and the epilogue. A graph of
+ * at most 32,768 nodes is one pass, bitwise the single-pass kernel. Record it through recordExactRepulsion.
  */
 export const fa2RepulsionExactWgsl = /* wgsl */ `
 var<workgroup> tile: array<vec4f, WG>;                         // xyz + mass, 4 KiB at WG = 256
@@ -35,14 +38,23 @@ fn gravity_force(pi: vec4f) -> vec3f {                         // spec 7.9: cent
 }
 
 @compute @workgroup_size(WG)
-fn repulsion(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+fn repulsion(
+    @builtin(workgroup_id) wid: vec3<u32>,
+    @builtin(local_invocation_id) lid: vec3<u32>,
+    @builtin(num_workgroups) nwg: vec3<u32>,
+) {
+    // issue #87: pass p of the tile range is dispatched with p + 1 z slices; only the last slice works, so the pass
+    // index needs no uniform. Uniform: keyed on workgroup_id and num_workgroups only.
+    if (wid.z + 1u < nwg.z) { return; }
     let i = linear_id(wid, lid.x);
     let valid = i < P.n;
     var pi = vec4f(0.0);
     if (valid) { pi = pos[i]; }
     var f = vec3f(0.0);
     let tiles = (P.n + WG - 1u) / WG;
-    for (var t = 0u; t < tiles; t = t + 1u) {
+    let tileBegin = (nwg.z - 1u) * EXACT_TILES_PER_PASS;
+    let tileEnd = min(tiles, tileBegin + EXACT_TILES_PER_PASS);
+    for (var t = tileBegin; t < tileEnd; t = t + 1u) {
         let j = t * WG + lid.x;
         if (j < P.n) { tile[lid.x] = pos[j]; } else { tile[lid.x] = vec4f(0.0); }   // guarded fill; mass 0 marks the pad
         workgroupBarrier();                                                       // uniform: every invocation reaches it
@@ -65,6 +77,10 @@ fn repulsion(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
         }
         workgroupBarrier();
     }
+    if (tileEnd < tiles) {                                                        // an earlier pass: its partial sum only (uniform: P.n, nwg)
+        if (valid) { store_force(i, load_force(i) + f); }
+        return;
+    }
     // epilogue (7.9, 7.10): gravity and force += under the guard, the swing / traction reduction outside it
     var sw = 0.0;
     var tr = 0.0;

package/src/wgsl/fa2-stats-finalize.wgsl.ts

@@ -61,7 +61,7 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
             S.radius = sqrt(max(tHi.w, 0.0));                          // max |p - centroid| about the same previous centroid as rmsRadius (K5 puts |q|^2 in max.w)
             let meanDisp = select(tDisp / f32(tFree), 0.0, tFree == 0u);  // all-fixed: 0, never NaN (7.4)
             S.meanDisplacement = meanDisp;
-            S.settledCount = select(0u, S.settledCount + 1u, meanDisp <= P.settleThreshold * S.rmsRadius);
+            S.settledCount = select(0u, S.settledCount + 1u, meanDisp <= min(P.settleThreshold * S.rmsRadius, P.settleFloor));   // relative AND absolute (issue #97)
         }
         S.iteration = S.iteration + 1u;
         T[P.iterationIndex].meanDisplacement = S.meanDisplacement;
@@ -79,7 +79,9 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
                 S.invCellSize = 1.0 / cellSize;
                 S.eps = 0.25 * cellSize;
             }
-            S.outsideGrid = cellHist[cells];                         // the previous iteration's pseudo-cell count (0 after load)
+            var outside = 0u;                                        // the previous iteration's pseudo-cell counts, one per orthant (issue #90; 0 after load)
+            for (var o = 0u; o < select(4u, 8u, P.dim == 3u); o = o + 1u) { outside = outside + cellHist[cells + o]; }
+            S.outsideGrid = outside;
             S.maxCellOccupancy = atomicLoad(&hubCounters[1]);
             atomicStore(&hubCounters[0], 0u);
             atomicStore(&hubCounters[1], 0u);

package/src/wgsl/frontier-finalize.wgsl.ts

@@ -29,25 +29,26 @@
  * 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.
+ * Beamer's test (P8-T8, PD-21; amended for issue #391), 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 `nextDegreeSum > 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. `nextDegreeSum` (word
+ * 25) is Beamer's m_f measured EXACTLY: `bfs-next-degree` sums the out-degrees of the vertices a level claims at
+ * the end of that level, so the boundary that rotates them in as `next` compares the degree of the frontier it is
+ * about to expand -- not, as before the amendment, `frontierDegreeSum` (word 2), the degree of the frontier the
+ * previous level EXPANDED, one level stale and 0 after a bottom-up level, which on the 1M / 10M R-MAT missed the
+ * switch at the level holding 13.6M of the 21M arcs. Word 2 is still accumulated by the expansion and rotated into
+ * word 4 for the inspect seam. The two unvisited words are rebuilt exactly once per submit by `bfs-unvisited-flags`
+ * (PD-18) and maintained here by subtraction from the SECOND boundary of a submit on, because a boundary may only
+ * subtract what the submit's rebuild counted: the rebuild counts the vertices unclaimed when it runs, the frontier
+ * rotated in at boundary 0 was claimed by the previous submit's last level, so it was never in the sums, and
+ * boundary b subtracts `next = |F_b|` and `nextDegreeSum = deg(F_b)`, both inside the sums iff b >= 1. Both words
+ * are therefore exact at every boundary, bottom-up levels included (the sweep's claims are summed like any other).
+ * 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)
@@ -61,19 +62,19 @@ fn frontier_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
         let finished = atomicLoad(&counters[0]);
         let next = atomicLoad(&counters[1]);
         let degSum = atomicLoad(&counters[2]);
+        let nextDeg = atomicLoad(&counters[25]);                       // deg(F_b), summed by bfs-next-degree when F_b was claimed (issue #391)
         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[25], 0u);                                // the next level's claims sum from 0
         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
+        if (P.firstOfSubmit >= 1u) {                                   // b = the boundary's index inside its submit, clamped (P8-T8, PD-18): F_b was inside the submit's rebuilt sums iff b >= 1
+            atomicStore(&counters[5], atomicLoad(&counters[5]) - next);       // unvisitedCount, exact
+            atomicStore(&counters[6], atomicLoad(&counters[6]) - nextDeg);    // unvisitedDegreeSum, exact (issue #391: no longer one level stale)
         }
         let level = atomicLoad(&counters[11]) + 1u;                    // the seed is U32_MAX, so the first boundary lands on 0
         atomicStore(&counters[11], level);
@@ -83,7 +84,7 @@ fn frontier_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
         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
+            if (nextDeg > atomicLoad(&counters[6]) / P.alpha && next > finished) { direction = 1u; }   // m_f > m_u / alpha and growing, m_f the degree of the frontier about to be expanded
         } else {
             if (next * P.beta < atomicLoad(&counters[5]) && next < finished) { direction = 0u; }      // next * beta < unvisited and shrinking
         }

package/src/wgsl/grid-cell-key.wgsl.ts

@@ -1,7 +1,8 @@
 /**
  * G1, the `grid-cell-key` kernel body (spec 7.7; P4-T8): the finest cell of every node from the state's robust extent,
  * `floor((p - gridMin) * invCellSize)` (a multiply, correctly rounded everywhere: PD-10), linearised when every axis
- * is in [0, G) and the outside pseudo-cell `cells` otherwise; `cellVal[i] = i`. The clamp before the floor keeps a
+ * is in [0, G), and otherwise one of the 2^dim outside pseudo-cells `cells + orthant`, the orthant of the cell about the
+ * grid centre (bit a set when `c[a] >= G / 2`; issue #90); `cellVal[i] = i`. The clamp before the floor keeps a
  * far-away or NaN coordinate out of an out-of-range float-to-int conversion. Body only; normative text.
  */
 export const gridCellKeyWgsl = /* wgsl */ `
@@ -18,7 +19,8 @@ fn grid_cell_key(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocatio
     let g = i32(P.gridMax);
     var inside = c.x >= 0 && c.x < g && c.y >= 0 && c.y < g;
     if (P.dim == 3u) { inside = inside && c.z >= 0 && c.z < g; }
-    var key = cells;                                               // the outside pseudo-cell (7.7)
+    var key = cells + select(0u, 1u, c.x >= g / 2) + select(0u, 2u, c.y >= g / 2);   // an outside pseudo-cell: its orthant (issue #90)
+    if (P.dim == 3u) { key = key + select(0u, 4u, c.z >= g / 2); }
     if (inside) {
         key = u32(c.x) + P.gridMax * u32(c.y);
         if (P.dim == 3u) { key = key + P.gridMax * P.gridMax * u32(c.z); }

package/src/wgsl/grid-centroid.wgsl.ts

@@ -1,5 +1,6 @@
 /**
- * G4, the `grid-centroid` kernel body (spec 7.7; P4-T9): thread per finest cell, the pseudo-cell included; the
+ * G4, the `grid-centroid` kernel body (spec 7.7; P4-T9): thread per finest cell, the 2^dim outside pseudo-cells
+ * included (issue #90); the
  * mass-weighted position sum of a cell's sorted range in index order (no atomics: deterministic), the largest
  * occupancy into hubCounters[1], and cells above GRID_HUB_CELL entries appended to hubList for G4b (PD-13). Body
  * only; normative text.
@@ -10,7 +11,7 @@ fn grid_cells() -> u32 { return P.gridMax * P.gridMax * select(1u, P.gridMax, P.
 @compute @workgroup_size(WG)
 fn grid_centroid(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
     let c = linear_id(wid, lid.x);
-    if (c > grid_cells()) { return; }                              // cells [0, cells]: the pseudo-cell is index cells; no barrier follows
+    if (c >= grid_cells() + select(4u, 8u, P.dim == 3u)) { return; }   // cells [0, cells + 2^dim): the pseudo-cells follow the real ones; no barrier follows
     let start = cellStart[c];
     let count = cellStart[c + 1u] - start;
     atomicMax(&hubCounters[1], count);                             // maxCellOccupancy, read by K1 next iteration

package/src/wgsl/grid-downsample.wgsl.ts

@@ -1,7 +1,7 @@
 /**
  * G5, the `grid-downsample` kernel body (spec 7.7; P4-T9): one dispatch per coarser level; every parent cell is the
  * sum of its 4 (2D) or 8 (3D) children at the level below, read at P.childBase and written at P.parentBase (the
- * pseudo-cell, index cells of level 0, is never a child). No atomics. Body only; normative text.
+ * pseudo-cells, indices cells .. of level 0, are never children). No atomics. Body only; normative text.
  */
 export const gridDownsampleWgsl = /* wgsl */ `
 @compute @workgroup_size(WG)

package/src/wgsl/grid-far-field.wgsl.ts

@@ -2,9 +2,11 @@
  * 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)
+ * level's own 3x3 -- space tiled exactly once, no theta -- plus the centroid of each of the 2^dim outside
+ * pseudo-cells, one per orthant about the grid centre (issue #90); 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)` with `|d|^2` first
+ * floored at 0.01^2 like K3's pair law (issue #89), `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.
@@ -18,11 +20,12 @@ fn store_force(i: u32, f: vec3f) {
 }
 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)
+fn outside_cells() -> u32 { return select(4u, 8u, P.dim == 3u); }   // one pseudo-cell per orthant (issue #90)
+fn level_base(level: u32) -> u32 {                             // the pyramid index of level L's cell 0 (level 0 carries the pseudo-cells at 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);
+        base = base + s * s * select(1u, s, P.dim == 3u) + select(0u, outside_cells(), l == 0u);
     }
     return base;
 }
@@ -33,7 +36,9 @@ fn cell_at(level: u32, cx: i32, cy: i32, cz: i32) -> u32 {
 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;
+    var d2 = dot(d, d);
+    if (LAW == 0u) { d2 = max(d2, FA2_DIST_FLOOR_SQ); }        // FA2 alone floors d >= 0.01, as K3 and G7 do (issue #89); FR and coulomb are unfloored (7.20)
+    d2 = d2 + 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
@@ -82,9 +87,11 @@ fn grid_far_field(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocati
                 }
             }
         }
-        f = f + cell_force(pi, pyramid[grid_cells()]);             // the outside pseudo-cell as one far-field term
+        for (var o = 0u; o < outside_cells(); o = o + 1u) {        // every outside pseudo-cell: one far-field term per orthant
+            f = f + cell_force(pi, pyramid[grid_cells() + o]);
+        }
     } 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 cz = 0; cz <= zTop; cz = cz + 1) {                // an outside node: the coarsest level in full, no pseudo-cell (G7 sums them pair by pair)
             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)]);

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

@@ -3,7 +3,7 @@
  * 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
+ * cells around its own, or over the 2^dim outside pseudo-cells (one per orthant, issue #90) 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
@@ -103,7 +103,11 @@ fn grid_near_field(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocat
                 }
             }
         } else {
-            f = cell_sum(i, pi, grid_cells(), true);               // an outside node: the pseudo-cell alone
+            var own = grid_cells() + select(0u, 1u, c0.x >= g / 2) + select(0u, 2u, c0.y >= g / 2);   // G1's orthant key
+            if (P.dim == 3u) { own = own + select(0u, 4u, c0.z >= g / 2); }
+            for (var o = grid_cells(); o < grid_cells() + select(4u, 8u, P.dim == 3u); o = o + 1u) {   // an outside node: every outside pseudo-cell
+                f = f + cell_sum(i, pi, o, o == own);
+            }
         }
     }
     // epilogue (7.9, 7.10): gravity and force += under the guard, the swing / traction reduction outside it (K3's text)

package/src/wgsl/histogram.wgsl.ts

@@ -1,7 +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.
+ * caller's contract; the grid's keys are always < cells + 2^dim). Body only; normative text.
  */
 export const histogramWgsl = /* wgsl */ `
 @compute @workgroup_size(WG)