@graphty/webgpu-graph-algorithms 0.6.5 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -93,8 +93,8 @@
     "vite": "^7.0.5",
     "vitest": "^3.2.4",
     "webgpu": "0.4.0",
-    "@graphty/algorithms": "^2.0.3",
-    "@graphty/layout": "^1.9.1"
+    "@graphty/algorithms": "^2.0.4",
+    "@graphty/layout": "^1.10.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/algorithms/bfs.ts

@@ -1,7 +1,7 @@
 /**
  * Breadth-first search on the device (design 8.4, 3.3 line 807, 9.7; P8-T6 / P8-T7 / P8-T8, the P8 plan's PD-5 /
  * PD-6 / PD-7 / PD-14 / PD-18 / PD-21 / PD-23 / PD-24 / PD-26 / DEP-P8-B): the direction-optimizing traversal over
- * the `Frontier` of P8-T4, every per-level choice made ON THE DEVICE. Every level is eight recorded dispatches, all
+ * the `Frontier` of P8-T4, every per-level choice made ON THE DEVICE. Every level is nine recorded dispatches, all
  * DIRECT (2026-09-25, docs/decisions/G8.md G8-F5: Dawn validates every `dispatchWorkgroupsIndirect` with an internal
  * clamp pass costing about 0.4 ms of device time whether or not it dispatches anything, in Node and in Chromium
  * alike, and that was 97 % of a traversal's wall time) -- `frontier-finalize` role 0 (the level boundary: rotates
@@ -13,11 +13,15 @@
  * per frontier entry with the same claim inline and no edge queue; the fused level and the retry alike), then the
  * bottom-up trio: a `fill` zeroing the frontier bitset, `bfs-bitset-build` setting the frontier's bits, and
  * `bfs-bottom-up` sweeping the unvisited list over the REVERSE core (each unvisited vertex reads its in-neighbours
- * until the first one in the bitset and claims itself). Every kernel is a grid-stride dispatch of a host-planned
- * grid (`planGridStride`) that loops to its count word and reads the path word first, so exactly one path does the
- * level's work and the others cost one uniform load per workgroup. The unvisited set Beamer's test is against (PD-18) is rebuilt exactly once per submit, before
- * the levels, by `bfs-unvisited-flags` plus `compact` over an iota queue, and maintained between rebuilds by
- * subtraction inside the selector (whose JSDoc states the boundary rule). The host records `MAX_LEVELS_PER_SUBMIT`
+ * until the first one in the bitset and claims itself), and last `bfs-next-degree` (the out-degree sum of whatever
+ * the level claimed, into the block's `nextDegreeSum` word: Beamer's m_f for the NEXT boundary, measured on the
+ * frontier that boundary decides for -- issue #391, which found the previous proxy, the degree of the frontier just
+ * expanded, one level stale and missing the switch at the level holding two thirds of the 1M / 10M R-MAT's arcs).
+ * Every kernel is a grid-stride dispatch of a host-planned grid (`planGridStride`) that loops to its count word and
+ * reads the path word first, so exactly one path does the level's work and the others cost one uniform load per
+ * workgroup. The unvisited set Beamer's test is against (PD-18) is rebuilt exactly once per submit, before the
+ * levels, by `bfs-unvisited-flags` plus `compact` over an iota queue, and maintained between rebuilds by subtraction
+ * inside the selector (whose JSDoc states the boundary rule; both words are exact at every boundary). The host records `MAX_LEVELS_PER_SUBMIT`
  * levels into ONE command buffer, submits, and reads four bytes, the `done` word (PD-7): a road network has
  * thousands of levels and a per-level `mapAsync` would be slower than the CPU. A level recorded past the end is a
  * no-op (its boundary finds `done` set, writes path 0 and moves no counter), so the loop needs no diameter and
@@ -79,6 +83,9 @@ import { type AlgorithmScope, algorithmScope } from "./scope.js";
 
 const ALGORITHM = "breadthFirstSearch";
 
+/** Workgroups of the `bfs-next-degree` grid (issue #391): enough to sum n out-degrees by grid stride, few enough that a high-diameter traversal does not pay a full-width reduction per level. */
+const NEXT_DEGREE_MAX_GROUPS = 128;
+
 /**
  * Params slots of the ring, COUNTED per run (P8-T12), because `UniformRing.reserve` wraps to slot 0 when a submit's
  * records outrun the ring and silently overwrites a record the submit still reads; the ring's `overruns` counts
@@ -87,8 +94,9 @@ const ALGORITHM = "breadthFirstSearch";
  * `bfs-contract`, the bits `fill`, `bfs-bitset-build`) and four re-issued once per arc window (`advance-expand`,
  * `bfs-fused`, the fused retry, `bfs-bottom-up`). The driver as built writes fewer -- the contract and the bitset
  * build share one window-free record, a window's two fused dispatches share one, the bits fill has one record per
- * submit, and a directed snapshot's reverse view is one window whatever the forward core's count -- so at most
- * `3 + 3 x windows` per level, and the bound holds with room. The 16 covers the per-submit rebuild
+ * submit, `bfs-next-degree` has one window-free record of its own (issue #391), and a directed snapshot's reverse
+ * view is one window whatever the forward core's count -- so at most `4 + 3 x windows` per level, and the bound
+ * holds with room. The 16 covers the per-submit rebuild
  * (`bfs-unvisited-flags` and `compact`, whose scan is at most 9 dispatches for any n below 2^32, so 10, plus the
  * bits fill). The result batch flushes in its own submit, so the ring must hold IT too, and its size grows with `n`,
  * not with the cadence: the iota `fill`, the radix sort's four passes of one record plus its scan's `2 x levels - 1`
@@ -339,6 +347,7 @@ export async function bfsWithTuning(
         const bitset = await ctx.pipelines.kernel(kernelSpec("bfs-bitset-build"));
         const bottomUp = await ctx.pipelines.kernel(kernelSpec("bfs-bottom-up", graphOverrides(reverse, null)));
         const unvisited = await ctx.pipelines.kernel(kernelSpec("bfs-unvisited-flags"));
+        const nextDegree = await ctx.pipelines.kernel(kernelSpec("bfs-next-degree"));
         const pred = await ctx.pipelines.kernel(kernelSpec("sssp-pred", { ...graphOverrides(core, null), MODE: 1 }));
         const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
         const sort = await prepareRadixSort(scope);
@@ -352,6 +361,11 @@ export async function bfsWithTuning(
         // plan's GROUP count as its stride (planGridStride's cap applies to the groups)
         const levelPlan = planGridStride(Math.max(n, frontier.edgeCapacity), wg, ctx.caps);
         const sweepPlan = planGridStride(n, wg, ctx.caps);
+        // `bfs-next-degree` sums at most n words and is dispatched on EVERY level, so its fixed cost -- one
+        // workgroup reduction (six barriers) and one atomic per workgroup -- is paid 1,999 times on the
+        // 1000 x 1000 grid. A capped grid pays it 128 times a level instead of ceil(n / wg): on the card the
+        // grid row went from 436 to 356 ms and neither R-MAT row moved.
+        const degreePlan = planGridStride(n, wg, ctx.caps, NEXT_DEGREE_MAX_GROUPS);
         const fusedPlan = planGridStride(n * wg, wg, ctx.caps);
         const bitsPlan = plan1d(bitsWords, wg, ctx.caps);
         const recordFill = (pass: GPUComputePassEncoder, dst: Binding, value: number, mode: 0 | 1): void => {
@@ -415,7 +429,7 @@ export async function bfsWithTuning(
             const bitsParams = scope.params(FILL_PARAMS, { count: bitsWords, value: 0, mode: 0, pad0: 0 });
             const boundBitsFill = fill.bind({ dst: frontierBits, P: bitsParams.binding });
             for (let level = 0; level < levelsPerSubmit; level++) {
-                planner.recordFinalize(pass, 0, level, { ...fields, firstOfSubmit: Math.min(level, 2) });
+                planner.recordFinalize(pass, 0, level, { ...fields, firstOfSubmit: Math.min(level, 1) });
                 advance.record(pass, frontier);
                 planner.recordFinalize(pass, 1, level, fields);
                 // one window-free record serves the contract and the bitset build, which read no arc; the kernels that
@@ -489,6 +503,16 @@ export async function bfsWithTuning(
                     });
                     bottomUp.dispatch(pass, boundSweep, sweepPlan, [sweepParams.offset]);
                 }
+                // the next frontier's out-degree sum (issue #391): whichever path claimed, the vertices are in the output
+                // queue now, and the next boundary reads word 25 as Beamer's m_f for the frontier it is about to expand
+                const degreeParams = scope.params(FRONTIER_PARAMS, { wg, n, stride: degreePlan.stride ?? wg });
+                const boundDegree = nextDegree.bind({
+                    frontier: frontier.output,
+                    outDegree,
+                    counters,
+                    P: degreeParams.binding,
+                });
+                nextDegree.dispatch(pass, boundDegree, degreePlan, [degreeParams.offset]);
                 frontier.swap();
             }
             batch.endPass();

package/src/algorithms/pagerank.ts

@@ -34,8 +34,8 @@ import { algorithmScope } from "./scope.js";
 
 /** Iterations per submit (spec 8.2: k = 8). */
 const PR_BATCH = 8;
-/** Params slots of one batch: per iteration one PrParams (shared by pr-scale and pr-finalize) and one SpmvParams, plus the normaliser's RangeParams; a smaller ring wraps onto a slot the same batch still reads. */
-const RING_SLOTS = 2 * PR_BATCH + 1;
+/** Params slots of one batch: per iteration one PrParams (shared by pr-scale and pr-finalize) and one SpmvParams, plus the normaliser's RangeParams and the last batch's convergence check; a smaller ring wraps onto a slot the same batch still reads. */
+const RING_SLOTS = 2 * PR_BATCH + 2;
 
 /**
  * Validates `options.dest` for a score result of `n` elements.
@@ -175,6 +175,8 @@ async function run(
         const groups = groupsOf(scalePlan);
         const partialsBytes = PR_PARTIAL.byteLength * (1 + groups);
         const partials = scope.scratch(partialsBytes, "partials");
+        // the header as the last pull left it, before the convergence check of the last batch overwrites danglingMass
+        const lastHeader = scope.scratch(PR_PARTIAL.byteLength, "lastHeader");
         if (personalization !== null) {
             uploaded = ctx.residency.array(personalization, `${algorithm}/personalization`);
         }
@@ -203,17 +205,21 @@ async function run(
         const xNormBinding = bindingOf(xNorm, bytes);
         const outWeightSumBinding = bindingOf(outWeightSum, bytes);
         const partialsBinding = bindingOf(partials, partialsBytes);
+        const lastHeaderBinding = bindingOf(lastHeader, PR_PARTIAL.byteLength);
         const coefficients = { alpha, beta: 1 - alpha, uniformP: 1 / n };
         let cur = 0;
         let iterationsRun = 0;
         for (;;) {
             const k = Math.min(PR_BATCH, maxIterations - iterationsRun);
             const batch = new CommandBatch(ctx, algorithm);
-            const pass = batch.pass("iterations");
+            let pass = batch.pass("iterations");
             if (iterationsRun === 0) {
                 normaliser.record(pass, weightedCore, outWeightSumBinding);
             }
-            for (let i = 0; i < k; i++) {
+            const last = iterationsRun + k === maxIterations;
+            // the scale + finalize of iteration i measures the error of iteration i - 1 (PD-9), so the last batch
+            // runs them once more, with no pull, to measure the error of iteration maxIterations itself
+            for (let i = 0; i < k + (last ? 1 : 0); i++) {
                 const params = scope.params(PR_PARAMS, {
                     n,
                     groups,
@@ -222,6 +228,10 @@ async function run(
                     convergeThreshold: tolerance * n,
                 });
                 const other = 1 - cur;
+                if (i === k) {
+                    batch.copy(partialsBinding, lastHeaderBinding, PR_PARTIAL.byteLength);
+                    pass = batch.pass("convergence");
+                }
                 const scaleBound = scale.bind({
                     rankIn: rank[cur],
                     rankPrev: rank[other],
@@ -233,6 +243,9 @@ async function run(
                 scale.dispatch(pass, scaleBound, scalePlan, [params.offset]);
                 const finalizeBound = finalize.bind({ partials: partialsBinding, P: params.binding });
                 finalize.dispatch(pass, finalizeBound, finalizePlan, [params.offset]);
+                if (i === k) {
+                    break;
+                }
                 pull.record(
                     pass,
                     weightedRev,
@@ -248,6 +261,7 @@ async function run(
             }
             batch.endPass();
             const headerRequest = batch.readback(partials, 0, PR_PARTIAL.byteLength);
+            const lastHeaderRequest = last ? batch.readback(lastHeader, 0, PR_PARTIAL.byteLength) : headerRequest;
             const scoresRequest = batch.readback(rank[cur].buffer, 0, bytes);
             scope.flush();
             const submitted = batch.submit();
@@ -271,7 +285,7 @@ async function run(
                     scores,
                     iterations: converged ? firstConverged : iterationsRun,
                     converged,
-                    danglingMass: folded.danglingMass as number,
+                    danglingMass: PR_PARTIAL.read(new DataView(back), lastHeaderRequest.offset).danglingMass as number,
                     precision: "f32",
                 };
             }

package/src/algorithms/power-iteration.ts

@@ -33,7 +33,7 @@ import { algorithmScope } from "./scope.js";
 
 /** Iterations per submit (spec 8.2: k = 8). */
 const BATCH = 8;
-/** Params slots of one batch: four blocks per iteration times the batch, plus a margin (the plan's `4 * 8 + 8`). */
+/** Params slots of one batch: four blocks per iteration times the batch, plus a margin (the plan's `4 * 8 + 8`) that also holds the last batch's convergence check. */
 const RING_SLOTS = 4 * BATCH + 8;
 
 /**
@@ -210,7 +210,10 @@ export async function runPowerIteration(
             const k = Math.min(BATCH, config.maxIterations - iterationsRun);
             const batch = new CommandBatch(ctx, config.label);
             const pass = batch.pass("iterations");
-            for (let i = 0; i < k; i++) {
+            // the scale + finalize of iteration i measures the error of iteration i - 1 (PD-9), so the last batch
+            // runs them once more, with no apply and no pull, to measure the error of iteration maxIterations itself
+            const last = iterationsRun + k === config.maxIterations;
+            for (let i = 0; i < k + (last ? 1 : 0); i++) {
                 const iteration = iterationsRun + i + 1;
                 const params = scope.params(PR_PARAMS, {
                     n,
@@ -234,6 +237,9 @@ export async function runPowerIteration(
                 };
                 scaleNorm.dispatch(pass, scaleNorm.bind(scaleBindings), scalePlan, [params.offset]);
                 finalize.dispatch(pass, finalize.bind({ partials, P: params.binding }), finalizePlan, [params.offset]);
+                if (i === k) {
+                    break;
+                }
                 if (scaleApply !== null) {
                     scaleApply.dispatch(pass, scaleApply.bind(scaleBindings), scalePlan, [params.offset]);
                 }

package/src/constants.ts

@@ -130,6 +130,13 @@ export const FA2_DISTANCE_FLOOR = 0.01;
 export const FA2_DISTANCE_FLOOR_SQ = 0.0001;
 /** The coincident threshold `d^2 < 1e-8` of spec 7.2. */
 export const FA2_COINCIDENT_SQ = 1e-8;
+/**
+ * The most WG-node tiles one K3 (`fa2-repulsion-exact`) dispatch sums per invocation (issue #87). llvmpipe runs at
+ * most 65,535 loop iterations per shader invocation, counted over every loop together, and then quietly breaks
+ * out of each loop; one tile costs WG + 2 of them (258 at WG 256), so a single pass lost every node past
+ * j = 65,027. 128 tiles is 33,024 iterations, half the budget; a larger exact run records ceil(tiles / 128) passes.
+ */
+export const EXACT_TILES_PER_PASS = 128;
 /** Bits of Fa2Params.flags (contract 4.4). */
 export const FA2_FLAG_FIRST = 1;
 /** Fa2Params.flags bit: the Fruchterman-Reingold temperature is the adaptive one in the state block, not the uniform's (the `cooling: "adaptive"` option). */
@@ -202,6 +209,34 @@ export const SE_DEFAULTS: Readonly<{
     iterationsPerStep: 1,
     maxInFlight: 2,
 });
+/**
+ * The absolute settle floor of the shared settle rule (spec 7.17; issue #97): an iteration counts toward `settled` only
+ * when its mean displacement is at most `settleThreshold x rmsRadius` AND at most this fraction of the model's length
+ * unit -- `springLength` for spring-electrical (scaled by node count, see SETTLE_FLOOR_REFERENCE_NODES), `k` for
+ * Fruchterman-Reingold. The relative rule alone reported a spring
+ * layout settled while it still grew (6 % over 1,000 iterations at 10k nodes). ForceAtlas2 writes
+ * `SETTLE_FLOOR_UNBOUNDED` instead: it does not drift after settling, and its per-iteration jitter grows with n, so any
+ * fixed floor only delays or blocks its stop. The values are measured:
+ * design/decisions/2026-09-24-settle-rule-has-an-absolute-floor.md.
+ */
+export const SETTLE_FLOOR_FRACTION: Readonly<{ springElectrical: number; fruchtermanReingold: number }> = Object.freeze(
+    {
+        springElectrical: 3e-3,
+        fruchtermanReingold: 2e-3,
+    },
+);
+/**
+ * The node count at which the spring-electrical floor is exactly `SETTLE_FLOOR_FRACTION.springElectrical x
+ * springLength`; at `n` nodes it is that times `(SETTLE_FLOOR_REFERENCE_NODES / n)^(1/4)`. A spring layout's rms radius
+ * grows about as n^(1/4) in springLengths (3.4 at 150 nodes, 6.4 at 2,000, 10.4 at 10,000), so the relative half of the
+ * rule loosens with size while the floor tightens with it: on a small graph the floor sits above the relative threshold
+ * and the relative rule decides alone, as before issue #97; on a large one the floor binds, which is where the relative
+ * rule let an expanding layout stop. A fixed floor bound the 150-node story graph too, where the grid tier's jitter sits
+ * at the relative threshold, and nearly doubled its settle (427 -> 829 iterations on the RTX 4070 SUPER).
+ */
+export const SETTLE_FLOOR_REFERENCE_NODES = 2000;
+/** The settle floor that never binds: the largest finite f32, 0x1.fffffep+127 (ForceAtlas2's `settleFloor`, issue #97). */
+export const SETTLE_FLOOR_UNBOUNDED = 2 ** 128 - 2 ** 104;
 /** The smallest finest grid side `G` (spec 7.7 geometry table: `clamp(nextPow2(2 n^(1/dim)), 8, gridMax)`; P4 PD-9). */
 export const GRID_MIN_SIDE = 8;
 /** The coarsest pyramid level's side (spec 7.7: "levels (coarsest 4 per axis)", `levels = log2(G / 4) + 1`). */

package/src/kernel/dispatch.ts

@@ -9,11 +9,11 @@ import { MAX_WORKGROUPS_PER_DIM } from "../constants.js";
 import { WebGpuGraphError } from "../errors.js";
 import { type PlanCaps } from "../types/context.js";
 
-/** A dispatch shape (spec 5.2). `stride` is the grid-stride step (null for plain 1D / 2D plans). */
+/** A dispatch shape (spec 5.2). `stride` is the grid-stride step (null for plain 1D / 2D plans). `z` is 1 from every planner; only K3's pass split sets it (issue #87). */
 export interface DispatchPlan {
     readonly x: number;
     readonly y: number;
-    readonly z: 1;
+    readonly z: number;
     readonly items: number;
     readonly stride: number | null;
 }

package/src/kernel/kernel.ts

@@ -245,7 +245,7 @@ export class Kernel {
     }
 
     /**
-     * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, 1); a plan with x === 0 records nothing (spec 5.6).
+     * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, plan.z); a plan with x === 0 records nothing (spec 5.6).
      * PLAN DECISION: one dynamic offset per dynamic GROUP, replicated over every uniform binding of that group (every
      * P1-P3 kernel has exactly one params uniform per group); absent offsets mean 0; a BoundKernel of another kernel
      * or an offset list of the wrong length is E_INVALID_ARGUMENT.
@@ -268,7 +268,7 @@ export class Kernel {
             return;
         }
         this.setUp(pass, bound, dynamicOffsets);
-        pass.dispatchWorkgroups(plan.x, plan.y, 1);
+        pass.dispatchWorkgroups(plan.x, plan.y, plan.z);
     }
 
     /**

package/src/kernel/prelude.ts

@@ -12,6 +12,7 @@
 import { INVALID_INDEX } from "@graphty/graph-format";
 
 import {
+    EXACT_TILES_PER_PASS,
     F32_INF_BITS,
     FA2_COINCIDENT_SQ,
     FA2_DISTANCE_FLOOR,
@@ -54,6 +55,7 @@ const INVALID_INDEX: u32 = ${INVALID_INDEX}u;
 const U32_MAX: u32 = ${U32_MAX}u;
 const F32_INF_BITS: u32 = ${F32_INF_BITS}u;
 const MAX_WORKGROUPS_PER_DIM: u32 = ${MAX_WORKGROUPS_PER_DIM}u;
+const EXACT_TILES_PER_PASS: u32 = ${EXACT_TILES_PER_PASS}u;
 const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
 const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};

package/src/kernels.ts

@@ -28,6 +28,7 @@ import { bfsBitsetBuildWgsl } from "./wgsl/bfs-bitset-build.wgsl.js";
 import { bfsBottomUpWgsl } from "./wgsl/bfs-bottom-up.wgsl.js";
 import { bfsContractWgsl } from "./wgsl/bfs-contract.wgsl.js";
 import { bfsFusedWgsl } from "./wgsl/bfs-fused.wgsl.js";
+import { bfsNextDegreeWgsl } from "./wgsl/bfs-next-degree.wgsl.js";
 import { bfsUnvisitedFlagsWgsl } from "./wgsl/bfs-unvisited-flags.wgsl.js";
 import { closenessReduceWgsl } from "./wgsl/closeness-reduce.wgsl.js";
 import { closenessSweepWgsl } from "./wgsl/closeness-sweep.wgsl.js";
@@ -111,6 +112,7 @@ export type KernelId =
     | "bfs-bottom-up"
     | "bfs-bitset-build"
     | "bfs-unvisited-flags"
+    | "bfs-next-degree"
     | "sssp-relax"
     | "bf-relax"
     | "closeness-sweep"
@@ -162,7 +164,7 @@ export const FILL_PARAMS: UniformBlock = UniformBlock.define("FillParams", [
     ["pad0", "u32"],
 ]);
 
-/** `Fa2Params` (uniform, 128 B; spec 7.3): the per-iteration ForceAtlas2 parameters -- `n` @0, `dim` @4, `flags` @8 (bit 0 = FA2_FLAG_FIRST), `tierStart` @12, `tierEnd` @16, `iterationIndex` @20, `seed` @24, `nearMax` @28, `scalingRatio` @32, `gravity` @36, `jitterTolerance` @40, `scale` @44, `center` @48 (xyz, w 0), `settleThreshold` @64, `extentFactor` @68, `gridMax` @72, `levels` @76, `arcBase` @80 / `arcEnd` @84 (the bound arc window of K2, 0 and arcCount in the layout), `accumulate` @88 (1 combines into `force`: the windowed pattern), `hiEnd` @92 / `midEnd` @124 (the degreeOrder tier boundaries, PD-7; both 0 without a permutation); the P5 model fields (PD-3): `frK` @96 (the FR optimal distance), `temperature` @100 (the FR temperature of this iteration), `springLength` @104, `springCoefficient` @108, `coulomb` @112 (ngraph's `gravity`, negative repels), `dragCoefficient` @116, `timeStep` @120; 128 B. */
+/** `Fa2Params` (uniform, 144 B; spec 7.3): the per-iteration ForceAtlas2 parameters -- `n` @0, `dim` @4, `flags` @8 (bit 0 = FA2_FLAG_FIRST), `tierStart` @12, `tierEnd` @16, `iterationIndex` @20, `seed` @24, `nearMax` @28, `scalingRatio` @32, `gravity` @36, `jitterTolerance` @40, `scale` @44, `center` @48 (xyz, w 0), `settleThreshold` @64, `extentFactor` @68, `gridMax` @72, `levels` @76, `arcBase` @80 / `arcEnd` @84 (the bound arc window of K2, 0 and arcCount in the layout), `accumulate` @88 (1 combines into `force`: the windowed pattern), `hiEnd` @92 / `midEnd` @124 (the degreeOrder tier boundaries, PD-7; both 0 without a permutation); the P5 model fields (PD-3): `frK` @96 (the FR optimal distance), `temperature` @100 (the FR temperature of this iteration), `springLength` @104, `springCoefficient` @108, `coulomb` @112 (ngraph's `gravity`, negative repels), `dragCoefficient` @116, `timeStep` @120; `settleFloor` @128 (the absolute bound on the mean displacement of a settled iteration, in layout units: issue #97); 144 B. */
 export const FA2_PARAMS: UniformBlock = UniformBlock.define("Fa2Params", [
     ["n", "u32"],
     ["dim", "u32"],
@@ -193,6 +195,7 @@ export const FA2_PARAMS: UniformBlock = UniformBlock.define("Fa2Params", [
     ["dragCoefficient", "f32"],
     ["timeStep", "f32"],
     ["midEnd", "u32"],
+    ["settleFloor", "f32"],
 ]);
 
 /** `Fa2State` (storage, padded to STATE_HEADER_BYTES = 256; spec 7.3): the device-resident controller state the finalize kernels write and the host reads back for stats -- `speed` @0, `speedEfficiency` @4, `swing` @8, `traction` @12, `centroid` @16, `rmsRadius` @32, `radius` @36, `meanDisplacement` @40, `iteration` @44, `min` @48, `max` @64, `gridMin` @80 (P4), `eps` @96 (P4), `settledCount` @100, `outsideGrid` @104 (P4), `maxCellOccupancy` @108 (P4), `temperature` @112 (FR, written by K1 under STATS_MODE 1), `kineticEnergy` @116 (the preset, K1 under STATS_MODE 2), `frEnergy` @120 / `frProgress` @124 (the FR adaptive cooling), `invCellSize` @128 (P4, PD-10: `1 / cellSize`, written by K1 beside `cellSize` in `gridMin.w`; G1 multiplies by it so every key is bitwise reproducible), `reserved0` @132 (f32), `reserved1` @136 (vec2f), `reserved2` .. `reserved8` @144 .. @240. */
@@ -386,8 +389,11 @@ export const COMPACT_PARAMS: UniformBlock = UniformBlock.define("CompactParams",
  * submit), `arcsScanned` @64, `fusedLevels` @68, `twoPhaseLevels` @72, `bottomUpLevels` @76, `farCount` @80,
  * `nextFarCount` @84, `thresholdBits` @88, `deltaBits` @92 (P8-T9), `path` @96 (what the level's kernels run, written
  * by the selector: 0 nothing, 1 two-phase, 2 fused, 3 bottom-up, 4 the fused retry, 5 a near SSSP round, 6 a far
- * one; every level kernel is a direct dispatch that reads it first -- G8-F5). The words nothing writes before
- * P8-T8 / P8-T9 are declared now because the byte layout is what the single result copy decodes.
+ * one; every level kernel is a direct dispatch that reads it first -- G8-F5), `nextDegreeSum` @100 (issue #391: the
+ * out-degree sum of the vertices the level claimed, accumulated by `bfs-next-degree` at the end of every level and
+ * read, subtracted and zeroed by the next boundary -- Beamer's m_f measured on the frontier the boundary decides
+ * for, not on the one it has just expanded). The words nothing writes before P8-T8 / P8-T9 are declared now because
+ * the byte layout is what the single result copy decodes.
  */
 export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
     "FrontierCounters",
@@ -417,6 +423,7 @@ export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
         ["thresholdBits", "u32"],
         ["deltaBits", "u32"],
         ["path", "u32"],
+        ["nextDegreeSum", "u32"],
     ],
     { layout: "storage" },
 );
@@ -427,9 +434,9 @@ export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
  * `alpha` @8, `beta` @12 (Beamer's thresholds, P8-T8), `fusedMax` @16, `edgeCapacity` @20, `maxDepth` @24, `n` @28,
  * `mode` @32 (BFS: 0 auto, 1 top-down only; `sssp-pred`: the PD-27 key rule), `cutoffBits` @36, `arcBase` @40,
  * `arcEnd` @44 (the bound arc window), `predKind` @48 (0 arc, 1 node), `bitsBase` @52, `source` @56, `stride` @60
- * (a grid-stride plan's stride), `firstOfSubmit` @64 (the boundary's index inside its submit, clamped to 2: the
- * unvisited-count subtraction runs at >= 1, the degree-sum one at >= 2), `iteration` @68 (an `sssp-pred` hop pass,
- * P8-T9), `pad1` @72, `pad2` @76. The `slotBase` field that once addressed the selector's indirect slots went with
+ * (a grid-stride plan's stride), `firstOfSubmit` @64 (the boundary's index inside its submit, clamped to 1: both
+ * the unvisited-count and the unvisited-degree-sum subtraction run at >= 1, issue #391), `iteration` @68 (an
+ * `sssp-pred` hop pass, P8-T9), `pad1` @72, `pad2` @76. The `slotBase` field that once addressed the selector's indirect slots went with
  * the slots (2026-09-25); `pad2` keeps the block an explicit 80 bytes, the way every block here is padded.
  */
 export const FRONTIER_PARAMS: UniformBlock = UniformBlock.define("FrontierParams", [
@@ -939,7 +946,7 @@ const RADIX_SCATTER: KernelEntry = {
     phase: "P4",
 };
 
-/** `grid-cell-key` (G1, spec 7.7; P4-T8, PD-10): the finest cell key of every node, `floor((p - gridMin) * invCellSize)` linearised, or the outside pseudo-cell `G^dim`; `cellVal[i] = i`; 4 storage bindings (the state read-only: K1 writes it). */
+/** `grid-cell-key` (G1, spec 7.7; P4-T8, PD-10): the finest cell key of every node, `floor((p - gridMin) * invCellSize)` linearised, or the outside pseudo-cell of its orthant `G^dim + orthant` (issue #90); `cellVal[i] = i`; 4 storage bindings (the state read-only: K1 writes it). */
 const GRID_CELL_KEY: KernelEntry = {
     id: "grid-cell-key",
     body: gridCellKeyWgsl,
@@ -958,7 +965,7 @@ const GRID_CELL_KEY: KernelEntry = {
     phase: "P4",
 };
 
-/** `grid-centroid` (G4, spec 7.7; P4-T9, PD-13): thread per finest cell (the pseudo-cell included), the serial mass-weighted sum in sorted order into level 0, the occupancy max into `hubCounters[1]`, hub cells (> GRID_HUB_CELL) appended to `hubList`; 6 storage bindings. */
+/** `grid-centroid` (G4, spec 7.7; P4-T9, PD-13): thread per finest cell (the 2^dim orthant pseudo-cells included), the serial mass-weighted sum in sorted order into level 0, the occupancy max into `hubCounters[1]`, hub cells (> GRID_HUB_CELL) appended to `hubList`; 6 storage bindings. */
 const GRID_CENTROID: KernelEntry = {
     id: "grid-centroid",
     body: gridCentroidWgsl,
@@ -1013,7 +1020,7 @@ const GRID_DOWNSAMPLE: KernelEntry = {
     phase: "P4",
 };
 
-/** `grid-far-field` (G6, spec 7.7; P4-T10, PD-16, DEP-P4-G): per node in sorted order, the coarsest level minus its 3x3 (3x3x3) and, per finer level, the parent's 3x3 refined minus the level's own 3x3, plus the pseudo-cell; the loop bounds are `P.levels` / `P.gridMax`; LAW 0 FA2 / 1 FR / 2 coulomb per cell (P4-T13, PD-22); 5 storage bindings. */
+/** `grid-far-field` (G6, spec 7.7; P4-T10, PD-16, DEP-P4-G): per node in sorted order, the coarsest level minus its 3x3 (3x3x3) and, per finer level, the parent's 3x3 refined minus the level's own 3x3, plus the 2^dim orthant pseudo-cells; the FA2 term floored at 0.01 (issue #89); the loop bounds are `P.levels` / `P.gridMax`; LAW 0 FA2 / 1 FR / 2 coulomb per cell (P4-T13, PD-22); 5 storage bindings. */
 const GRID_FAR_FIELD: KernelEntry = {
     id: "grid-far-field",
     body: gridFarFieldWgsl,
@@ -1261,6 +1268,24 @@ const BFS_UNVISITED_FLAGS: KernelEntry = {
     phase: "P8",
 };
 
+/** `bfs-next-degree` (design 8.4; issue #391): Beamer's m_f measured exactly -- once per level, after the claim kernels, grid-striding over the output vertex queue and summing the `outDegree` view over the vertices the level claimed into word 25, one `atomicAdd` per workgroup; 3 storage bindings (`frontier` read-only, the `outDegree` VIEW, the counters block); `needs: ["subgroups"]` for the `wg_reduce_u32` call (a twin kernel). */
+const BFS_NEXT_DEGREE: KernelEntry = {
+    id: "bfs-next-degree",
+    body: bfsNextDegreeWgsl,
+    entryPoint: "bfs_next_degree",
+    bindings: [
+        decl(1, 0, "frontier", "storage-ro", "array<u32>"),
+        decl(1, 1, "outDegree", "storage-ro", "array<u32>"),
+        decl(1, 2, "counters", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "FrontierParams"),
+    ],
+    overrideDecls: [],
+    uniforms: [FRONTIER_PARAMS],
+    needs: ["subgroups"],
+    snippetSlots: [],
+    phase: "P8",
+};
+
 /** `sssp-relax` (design 8.4 "Davidson's near-far", 8.10 "SSSP near-far relax"; P8-T9, PD-9 / PD-20 / DEP-P8-E): one round of the near-far loop -- role 0 relaxes the deduped near pile's whole rows with `atomicMin` on the f32 bit patterns of `dist` and appends each improved vertex to the raw near or far half of `queueOut` (the two halves of ONE buffer at word 0 and word `P.edgeCapacity`), role 1 re-buckets the deduped far pile; 8 storage bindings (the four graph slots with the run's weights bound in the weights slot, `dist` and the counters block as `array<atomic<u32>>`, `queueIn` read-only, `queueOut`) -- exactly at the budget, which is why no `pred` lives here (PD-11) and why the piles' counts, the threshold and the delta are words of the block. */
 const SSSP_RELAX: KernelEntry = {
     id: "sssp-relax",
@@ -1392,6 +1417,7 @@ const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze
     "bfs-bottom-up": BFS_BOTTOM_UP,
     "bfs-bitset-build": BFS_BITSET_BUILD,
     "bfs-unvisited-flags": BFS_UNVISITED_FLAGS,
+    "bfs-next-degree": BFS_NEXT_DEGREE,
     "sssp-relax": SSSP_RELAX,
     "bf-relax": BF_RELAX,
     "closeness-sweep": CLOSENESS_SWEEP,

package/src/layouts/forceatlas2.ts

@@ -26,6 +26,7 @@ import {
     GRID_EXTENT_FLOOR,
     LAYOUT_TUNING_DEFAULTS,
     MAX_ITERATIONS_PER_STEP,
+    SETTLE_FLOOR_UNBOUNDED,
     TRACE_RECORD_BYTES,
     UNIFORM_SLOT_BYTES,
 } from "../constants.js";
@@ -590,6 +591,7 @@ export class ForceAtlas2Model implements ForceModel<ForceAtlas2Options, ForceAtl
             accumulate: 0,
             hiEnd,
             midEnd,
+            settleFloor: SETTLE_FLOOR_UNBOUNDED, // ForceAtlas2 does not drift after settling (issue #97)
         };
     }
 

package/src/layouts/fruchterman-reingold.ts

@@ -32,6 +32,7 @@ import {
     FR_REHEAT_FRACTION,
     FR_START_TEMPERATURE,
     MAX_ITERATIONS_PER_STEP,
+    SETTLE_FLOOR_FRACTION,
     TRACE_RECORD_BYTES,
     UNIFORM_SLOT_BYTES,
 } from "../constants.js";
@@ -84,6 +85,7 @@ import {
     subset,
     vector,
 } from "./model-common.js";
+import { recordExactRepulsion } from "./repulsion-exact.js";
 import { type GridStage, RepulsionGrid, type RepulsionGridOverrides } from "./repulsion-grid.js";
 
 // ============================================================ constants
@@ -587,6 +589,7 @@ export class FruchtermanReingoldModel implements ForceModel<FruchtermanReingoldO
             hiEnd,
             midEnd,
             frK: resolved.k ?? 1 / Math.sqrt(n),
+            settleFloor: SETTLE_FLOOR_FRACTION.fruchtermanReingold * (resolved.k ?? 1 / Math.sqrt(n)),
             temperature: adaptive ? FR_START_TEMPERATURE : this.temperatureAt(iteration, resolved),
         };
     }
@@ -640,7 +643,7 @@ export class FruchtermanReingoldModel implements ForceModel<FruchtermanReingoldO
         if (stop < 2) {
             return;
         }
-        k3.dispatch(pass, k3Bound, bound.plan, [offset]);
+        recordExactRepulsion(k3, pass, k3Bound, bound.plan, bound.n, offset);
         if (stop < STAGE_K5) {
             return;
         }

package/src/layouts/repulsion-exact.ts

@@ -7,6 +7,7 @@
  * override set is a distinct pipeline and the subgroup twin is selected by the device's features (spec 5.1, D16).
  */
 
+import { EXACT_TILES_PER_PASS } from "../constants.js";
 import { WebGpuGraphError } from "../errors.js";
 import { type DispatchPlan, plan1d } from "../kernel/dispatch.js";
 import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
@@ -35,6 +36,33 @@ export interface RepulsionExactOverrides {
     readonly GRAVITY_CENTER: 0 | 1;
 }
 
+/**
+ * Records K3 over `n` nodes as ceil(tiles / EXACT_TILES_PER_PASS) dispatches (issue #87: llvmpipe's per-invocation
+ * loop budget), pass p with p + 1 z slices of which only the last works (the kernel reads the pass from
+ * `num_workgroups.z`). One pass up to 32,768 nodes at WG 256. Every model's exact tier records K3 through here.
+ * ponytail: pass p also launches p idle slices, sum p over P passes; negligible against the O(n^2) pass work (31
+ * passes at 1M nodes); a per-pass uniform removes them if they ever show in a profile.
+ * @param kernel - the compiled `fa2-repulsion-exact`
+ * @param pass - the open compute pass
+ * @param bound - the kernel's bound groups
+ * @param plan - plan1d(n) of the kernel
+ * @param n - the node count
+ * @param paramsOffset - the dynamic offset of the Fa2Params slot
+ */
+export function recordExactRepulsion(
+    kernel: Kernel,
+    pass: GPUComputePassEncoder,
+    bound: BoundKernel,
+    plan: DispatchPlan,
+    n: number,
+    paramsOffset: number,
+): void {
+    const passes = Math.max(1, Math.ceil(Math.ceil(n / kernel.workgroupSize) / EXACT_TILES_PER_PASS));
+    for (let z = 1; z <= passes; z++) {
+        kernel.dispatch(pass, bound, { ...plan, z }, [paramsOffset]);
+    }
+}
+
 /** K3 (tiled all-pairs repulsion + gravity + the swing / traction epilogue) followed by K4 (the one-workgroup speed finalize) (spec 7.6, 7.10). */
 export class RepulsionExact {
     /** The overrides both kernels were compiled with (a frozen copy of the argument of create()). */
@@ -148,7 +176,7 @@ export class RepulsionExact {
     recordRepulsion(pass: GPUComputePassEncoder, n: number, paramsOffset: number): void {
         const bound = this.bound(this.boundRepulsion, "recordRepulsion");
         const plan = plan1d(n, this.repulsion.workgroupSize, this.caps);
-        this.repulsion.dispatch(pass, bound, plan, [paramsOffset]);
+        recordExactRepulsion(this.repulsion, pass, bound, plan, n, paramsOffset);
     }
 
     /**

package/src/layouts/repulsion-grid.ts

@@ -216,7 +216,7 @@ export class RepulsionGrid {
 
     /**
      * The model-owned buffers of the grid tier (spec 7.3; PD-11): `cellKey` / `cellVal` / `sortedKey` / `sortedIdx`
-     * 4n, `cellHist` / `cellStart` 4 (cells + 2) zeroed, `hubList` one word per possible hub cell, `hubArgs` one
+     * 4n, `cellHist` / `cellStart` 4 histWords (cells + 2^dim + 1) zeroed, `hubList` one word per possible hub cell, `hubArgs` one
      * indirect slot, `pyramid` 16 B per pyramid cell zeroed. `hubCounters` (16 B, zeroed) is the MODEL's on every
      * tier (PD-14: K1 binds it on the exact tier too). n = 0 reports one node's worth of bytes (spec 3.6).
      * @param n - the node count

package/src/layouts/spring-electrical.ts

@@ -25,6 +25,8 @@ import {
     MAX_ITERATIONS_PER_STEP,
     SE_DEFAULTS,
     SE_SCALE_REFERENCE_NODES,
+    SETTLE_FLOOR_FRACTION,
+    SETTLE_FLOOR_REFERENCE_NODES,
     TRACE_RECORD_BYTES,
     UNIFORM_SLOT_BYTES,
 } from "../constants.js";
@@ -77,6 +79,7 @@ import {
     subset,
     vector,
 } from "./model-common.js";
+import { recordExactRepulsion } from "./repulsion-exact.js";
 import { type GridStage, RepulsionGrid, type RepulsionGridOverrides } from "./repulsion-grid.js";
 
 // ============================================================ constants
@@ -555,6 +558,10 @@ export class SpringElectricalModel implements ForceModel<SpringElectricalOptions
             frK: 0,
             temperature: 0,
             springLength: resolved.springLength,
+            settleFloor:
+                SETTLE_FLOOR_FRACTION.springElectrical *
+                resolved.springLength *
+                (SETTLE_FLOOR_REFERENCE_NODES / Math.max(n, 1)) ** 0.25,
             springCoefficient: resolved.springCoefficient ?? SE_DEFAULTS.springCoefficient * springSizeFactor(n),
             coulomb: resolved.gravity ?? SE_DEFAULTS.gravity * springSizeFactor(n),
             dragCoefficient: resolved.dragCoefficient,
@@ -609,7 +616,7 @@ export class SpringElectricalModel implements ForceModel<SpringElectricalOptions
         if (stop < 2) {
             return;
         }
-        k3.dispatch(pass, k3Bound, bound.plan, [offset]);
+        recordExactRepulsion(k3, pass, k3Bound, bound.plan, bound.n, offset);
         if (stop < STAGE_K5) {
             return;
         }