@graphty/webgpu-graph-algorithms 0.6.4 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.4",
+  "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,14 +13,18 @@
  * 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, zeroes its slots and moves no counter), so the loop needs no diameter and
+ * no-op (its boundary finds `done` set, writes path 0 and moves no counter), so the loop needs no diameter and
  * ends on `done`; a traversal has at most `n` levels, so more submits than that is E_VALIDATION, never a hang. The
  * thresholds are uniform fields (`FUSED_FRONTIER_MAX`; alpha derived as `max(1, floor(arcCount / n))`, PD-21;
  * `BEAMER_BETA`; `mode 1` pinning top-down -- each unless the tuning says otherwise), so a test forces any path
@@ -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/algorithms/scope.ts

@@ -8,12 +8,11 @@
  */
 
 import { type GpuContext } from "../context.js";
-import { BufferUsage } from "../device/webgpu-constants.js";
 import { UniformRing } from "../kernel/uniform-ring.js";
-import { type FrontierScope } from "../primitives/frontier.js";
+import { type ReduceScope } from "../primitives/reduce.js";
 
-/** A FrontierScope (a ReduceScope plus `indirect()`, P8-T4) over a context plus the two lifecycle calls an algorithm makes: flush() before submit, dispose() in its finally. */
-export interface AlgorithmScope extends FrontierScope {
+/** A ReduceScope over a context plus the two lifecycle calls an algorithm makes: flush() before submit, dispose() in its finally. (The `indirect()` lease it once added for the frontier's args buffer went with that buffer, 2026-09-25.) */
+export interface AlgorithmScope extends ReduceScope {
     /** queue.writeBuffer of the params slots written since the last flush (called before the batch is submitted). */
     flush(): void;
     /** Destroys the ring and releases every scratch buffer of the lease; idempotent. */
@@ -39,12 +38,6 @@ export function algorithmScope(ctx: GpuContext, label: string, slots: number): A
         pool: ctx.pool,
         workgroupSize: ctx.workgroupSize,
         scratch: (byteLength, scratchLabel) => lease.storage(byteLength, `${label}/${scratchLabel}`),
-        indirect: (byteLength, indirectLabel) =>
-            lease.acquire(
-                byteLength,
-                BufferUsage.STORAGE | BufferUsage.INDIRECT | BufferUsage.COPY_DST | BufferUsage.COPY_SRC,
-                `${label}/${indirectLabel}`,
-            ),
         params(block, values) {
             const slot = ring.reserve(1);
             ring.write(slot, block, values);

package/src/algorithms/sssp.ts

@@ -11,9 +11,10 @@
  * delta and dedupes the far half into `farIn` for a pass-through; both empty is `done`), `dedupe-claim` and
  * `dedupe-filter` over each half (direct grid-stride dispatches; role 2 writes the chosen half's raw count into that
  * dedupe's count word -- `edgeCount` for the near half, `edgeCountUnclamped` for the far one, two words SSSP borrows
- * -- and 0 into the other's, so the half not chosen is a no-op), role 3 (restarts the raw half), and `sssp-relax`
- * twice (role 0 over `nearIn`, role 1 over `farIn`; the block's `path` word, 5 a near round and 6 a far one, makes
- * the other role's dispatch a no-op). The far pile is re-bucketed by the
+ * -- and 0 into the other's, so the half not chosen is a no-op), role 3 (restarts the raw half the round consumed),
+ * and `sssp-relax` twice (role 0 over `nearIn` sized by `frontierCount`, role 1 over `farIn` sized by `farCount`;
+ * the block's `path` word, 5 a near round and 6 a far one, makes the other role's dispatch a no-op). Nothing in a
+ * round is an indirect dispatch (2026-09-25). The far pile is re-bucketed by the
  * relax kernel's pass-through, not by `compact` (PD-20): a far entry whose settled distance fell below the previous
  * threshold was relaxed in the near band already and is dropped, the rest go back to near or far against the raised
  * threshold. The near pile is ONE pile (no sub-partitions). The host records `MAX_LEVELS_PER_SUBMIT` rounds per

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`). */
@@ -218,8 +253,6 @@ export const GRID_SORT_BITS = 24;
 export const MAX_LEVELS_PER_SUBMIT = 32;
 /** Design 8.4 and 6 row 8 (P8): a frontier at most this long runs the fused expand-contract kernel (Merrill's "fleeting iterations"); the default of the `fusedMax` uniform, which a test may set to 0 or `U32_MAX`. */
 export const FUSED_FRONTIER_MAX = 4096;
-/** P8-T4: the indirect dispatch slots `frontier-finalize` writes per level (expand, contract, fused, fill-bits, bitset-build, bottom-up, fused-retry); the args buffer is `MAX_LEVELS_PER_SUBMIT x FRONTIER_CANDIDATES x 16` bytes. */
-export const FRONTIER_CANDIDATES = 7;
 /** Design 8.4 (P8 PD-21): Beamer's beta -- switch back to top-down when `frontierCount * BEAMER_BETA < unvisitedCount` and the frontier is shrinking; alpha is derived from the graph, so it has no constant. */
 export const BEAMER_BETA = 24;
 /** Design 8.4 (P8 PD-22): the near-far split `delta = SSSP_DELTA_FACTOR * avgWeight / avgDegree`, computed on the host from the weight vector the run uses. */

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,23 +423,24 @@ export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
         ["thresholdBits", "u32"],
         ["deltaBits", "u32"],
         ["path", "u32"],
+        ["nextDegreeSum", "u32"],
     ],
     { layout: "storage" },
 );
 
 /**
  * `FrontierParams` (uniform, 80 B; P8-T4): the params block every P8 kernel except the three compact / dedupe
- * primitives and `bf-relax` binds -- `role` @0 (the finalize role), `slotBase` @4 (`level x FRONTIER_CANDIDATES`),
- * `wg` @8 (the consumers' workgroup size), `alpha` @12, `beta` @16 (Beamer's thresholds, P8-T8), `fusedMax` @20,
- * `edgeCapacity` @24, `maxDepth` @28, `n` @32, `mode` @36 (BFS: 0 auto, 1 top-down only; `sssp-pred`: the PD-27 key
- * rule), `cutoffBits` @40, `arcBase` @44, `arcEnd` @48 (the bound arc window), `predKind` @52 (0 arc, 1 node),
- * `bitsBase` @56, `source` @60, `stride` @64 (a grid-stride plan's stride), `firstOfSubmit` @68 (the boundary's index
- * inside its submit, clamped to 2: the unvisited-count subtraction runs at >= 1, the degree-sum one at >= 2),
- * `iteration` @72 (an `sssp-pred` hop pass, P8-T9), `pad1` @76.
+ * primitives and `bf-relax` binds -- `role` @0 (the finalize role), `wg` @4 (the consumers' workgroup size),
+ * `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 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", [
     ["role", "u32"],
-    ["slotBase", "u32"],
     ["wg", "u32"],
     ["alpha", "u32"],
     ["beta", "u32"],
@@ -452,6 +459,7 @@ export const FRONTIER_PARAMS: UniformBlock = UniformBlock.define("FrontierParams
     ["firstOfSubmit", "u32"],
     ["iteration", "u32"],
     ["pad1", "u32"],
+    ["pad2", "u32"],
 ]);
 
 /** `BfParams` (uniform, 16 B; P8-T10): `edgeCount` @0 (the logical edges of the `edgeList` view), `stride` @4 (the grid-stride plan's stride), `maxRetries` @8 (PD-12's compare-exchange bound), `cutoffBits` @12 (the f32 bit pattern of the CPU port's `cutoff`, `+Inf` when absent). */
@@ -938,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,
@@ -957,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,
@@ -1012,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,
@@ -1117,16 +1125,12 @@ const DEDUPE_FILTER: KernelEntry = {
     phase: "P8",
 };
 
-/** `frontier-finalize` (design 5.4, 8.10 "BFS finalizeArgs"; P8-T4, PD-3): the one-lane level-boundary selector that rotates the counters block and writes the level's seven indirect slots (role 0), then clamps the edge count and sizes the contract or the fused-retry slot (role 1); 2 storage bindings (the block as `array<atomic<u32>>`, the args). */
+/** `frontier-finalize` (design 5.4, 8.10 "BFS finalizeArgs"; P8-T4, PD-3): the one-lane level-boundary selector that rotates the counters block and writes the level's `path` word (role 0), then clamps the edge count or switches the path to the fused retry (role 1); 1 storage binding (the block as `array<atomic<u32>>`). Since 2026-09-25 it writes no indirect slots: every level kernel is a direct dispatch gated by the path word. */
 const FRONTIER_FINALIZE: KernelEntry = {
     id: "frontier-finalize",
     body: frontierFinalizeWgsl,
     entryPoint: "frontier_finalize",
-    bindings: [
-        decl(1, 0, "counters", "storage", "array<atomic<u32>>"),
-        decl(1, 1, "args", "storage", "array<u32>"),
-        decl(2, 0, "P", "uniform", "FrontierParams"),
-    ],
+    bindings: [decl(1, 0, "counters", "storage", "array<atomic<u32>>"), decl(2, 0, "P", "uniform", "FrontierParams")],
     overrideDecls: [],
     uniforms: [FRONTIER_PARAMS],
     needs: [],
@@ -1188,7 +1192,7 @@ const SSSP_PRED: KernelEntry = {
     phase: "P8",
 };
 
-/** `bfs-fused` (design 8.4 "the fused variant", 6 row 8 "the workgroup-per-row tier", 8.10 "BFS fused expand-contract"; P8-T7, PD-23): one level's expansion and contraction in one dispatch, one WORKGROUP per frontier entry, every lane stripping the entry's row with `bfs-contract`'s claim inline and no edge queue traffic; dispatched from `SLOT.fused` (a frontier below `P.fusedMax`) and from `SLOT.fusedRetry` (an overflowed level); 8 storage bindings (the four graph slots, `frontierIn`, the counters block as `array<atomic<u32>>`, `depth` as `array<atomic<u32>>`, `frontierOut`) -- exactly at the budget, which is why no `parent` lives here (PD-24). */
+/** `bfs-fused` (design 8.4 "the fused variant", 6 row 8 "the workgroup-per-row tier", 8.10 "BFS fused expand-contract"; P8-T7, PD-23): one level's expansion and contraction in one dispatch, one WORKGROUP per frontier entry, every lane stripping the entry's row with `bfs-contract`'s claim inline and no edge queue traffic; a direct grid-stride dispatch that runs when the path word is 2 (a frontier below `P.fusedMax`) or 4 (the overflow retry, role 1's), sized from `frontierCount`; 8 storage bindings (the four graph slots, `frontierIn`, the counters block as `array<atomic<u32>>`, `depth` as `array<atomic<u32>>`, `frontierOut`) -- exactly at the budget, which is why no `parent` lives here (PD-24). */
 const BFS_FUSED: KernelEntry = {
     id: "bfs-fused",
     body: bfsFusedWgsl,
@@ -1264,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",
@@ -1395,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;
         }