@graphty/webgpu-graph-algorithms 0.6.4 → 0.6.6

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;
         }

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/advance.ts

@@ -34,7 +34,8 @@ import { type Kernel } from "../kernel/kernel.js";
 import { FRONTIER_PARAMS, graphBindings, graphOverrides, kernelSpec } from "../kernels.js";
 import { type CoreBinding } from "../memory/residency.js";
 import { type CoreWindow, coreWindows, rowCountOf } from "./core-shape.js";
-import { type Frontier, type FrontierScope } from "./frontier.js";
+import { type Frontier } from "./frontier.js";
+import { type ReduceScope } from "./reduce.js";
 
 /** A prepared advance (design 6 row 8): records one expansion of a frontier per level. */
 export interface AdvancePlanner {
@@ -64,7 +65,7 @@ export interface AdvancePlanner {
  * @param core - the resident core arrays of the snapshot the frontier walks (windowed or not)
  * @returns the planner
  */
-export async function prepareAdvance(scope: FrontierScope, core: CoreBinding): Promise<AdvancePlanner> {
+export async function prepareAdvance(scope: ReduceScope, core: CoreBinding): Promise<AdvancePlanner> {
     const kernel = await scope.pipelines.kernel(kernelSpec("advance-expand", graphOverrides(core, null)));
     return new AdvancePlannerImpl(scope, core, kernel);
 }
@@ -73,7 +74,7 @@ export async function prepareAdvance(scope: FrontierScope, core: CoreBinding): P
 class AdvancePlannerImpl implements AdvancePlanner {
     readonly kernel: Kernel;
     readonly windows: readonly CoreWindow[];
-    private readonly scope: FrontierScope;
+    private readonly scope: ReduceScope;
     private readonly n: number;
 
     /**
@@ -82,7 +83,7 @@ class AdvancePlannerImpl implements AdvancePlanner {
      * @param core - the core the kernel was compiled for
      * @param kernel - the `advance-expand` kernel
      */
-    constructor(scope: FrontierScope, core: CoreBinding, kernel: Kernel) {
+    constructor(scope: ReduceScope, core: CoreBinding, kernel: Kernel) {
         this.scope = scope;
         this.kernel = kernel;
         this.windows = coreWindows(core);

package/src/primitives/frontier.ts

@@ -1,46 +1,48 @@
 /**
  * The `Frontier` of design 6 row 7 and the device-side dispatch selector of design 5.4 (P8-T4; the P8 plan's PD-1,
- * PD-3, PD-8, PD-23, DEP-P8-A, DEP-P8-C). A traversal's per-level state is two n-slot vertex queues, ONE 24-word
+ * PD-3, PD-8, PD-23, DEP-P8-A, DEP-P8-C). A traversal's per-level state is two n-slot vertex queues, ONE 25-word
  * counters block (every counter of the phase is a word of it: a four-byte word is never a legal storage-binding
- * offset, and the selector must reach every count it acts on through one binding), the indirect args buffer of
- * `MAX_LEVELS_PER_SUBMIT x FRONTIER_CANDIDATES` 16-byte slots, and the edge queue. The host never reads a counter
- * inside a submit: `frontier-finalize`, one lane, runs at the START of every level (role 0: rotates
- * `nextFrontierCount` into `frontierCount`, advances `level`, decides `done`, writes this level's slots) and again once
- * the edge queue is filled (role 1: clamps `edgeCount`, sizes the contract slot, or on an overflow --
- * `edgeCountUnclamped > edgeCapacity` -- sizes the fused-retry slot instead, PD-23), and the kernels that follow
- * dispatch indirectly from those slots. The host records up to `MAX_LEVELS_PER_SUBMIT` levels per submit and reads
- * `done` (four bytes) once per submit; a boundary that finds `done` set zeroes its slots and moves no counter, so the
- * recorded levels past the end are no-ops and the counters freeze at the finishing boundary's values.
+ * offset, and the selector must reach every count it acts on through one binding) and the edge queue. The host
+ * never reads a counter inside a submit: `frontier-finalize`, one lane, runs at the START of every level (role 0:
+ * rotates `nextFrontierCount` into `frontierCount`, advances `level`, decides `done`, chooses the level's path) and
+ * again once the edge queue is filled (role 1: clamps `edgeCount`, or on an overflow -- `edgeCountUnclamped >
+ * edgeCapacity` -- switches the path to the fused retry, PD-23). The choice is the block's `path` word (`W.path`,
+ * word 24); every level kernel is a direct grid-stride dispatch that reads it first and does nothing unless the
+ * word names it (design/decisions/2026-09-25-frontier-kernels-dispatch-directly.md: the seven indirect slots the
+ * selector once wrote per level cost about 0.4 ms of Dawn validation each and were 97 % of a traversal's wall
+ * time; they and their args buffer are gone). The host records up to `MAX_LEVELS_PER_SUBMIT` levels per submit and
+ * reads `done` (four bytes) once per submit; a boundary that finds `done` set writes path 0 and moves no counter,
+ * so the recorded levels past the end are no-ops and the counters freeze at the finishing boundary's values.
  *
  * The seed: `frontierCount` is NEVER seeded, because the first boundary rotates it out unread. A BFS driver calls
  * `reset(queue, source, { nextFrontierCount: 1, level: U32_MAX })`: the first boundary rotates the 1 in, adds it into
  * `visitedCount`, and wraps `level` to 0, so the level-0 expansion claims the source's neighbours at `level + 1 == 1`.
  * `reset` is a queue write, ordered before the submit that follows, and it puts the source on side 0.
  *
- * Every buffer comes from the caller's ONE lease (`scope.scratch`, `scope.indirect`) so the algorithm's dispose()
+ * Every buffer comes from the caller's ONE lease (`scope.scratch`) so the algorithm's dispose()
  * releases them together (design 4.4). The two vertex queues are two BUFFERS, never two ranges of one: `Kernel.bind`
  * rejects one buffer bound read-only and read-write in one dispatch even for disjoint ranges. `src/primitives/**`
  * never imports `src/context.ts`.
  */
 
-import { FRONTIER_CANDIDATES, MAX_LEVELS_PER_SUBMIT, U32_MAX } from "../constants.js";
+import { MAX_LEVELS_PER_SUBMIT, U32_MAX } from "../constants.js";
 import { WebGpuGraphError } from "../errors.js";
 import { plan1d } from "../kernel/dispatch.js";
-import { INDIRECT_ARGS_STRIDE, type Kernel } from "../kernel/kernel.js";
+import { type Kernel } from "../kernel/kernel.js";
 import { FRONTIER_COUNTERS, FRONTIER_PARAMS, kernelSpec } from "../kernels.js";
 import { type Binding } from "../types/memory.js";
 import { type ReduceScope } from "./reduce.js";
 
-/** The seven indirect slots of one level (`FRONTIER_CANDIDATES`), by the kernel that dispatches from each. */
-export const SLOT: Readonly<{
-    expand: 0;
-    contract: 1;
+/** The values of the `path` word (`W.path`): what a level's kernels run; every level kernel reads it first. */
+export const PATH: Readonly<{
+    none: 0;
+    twoPhase: 1;
     fused: 2;
-    fillBits: 3;
-    bitset: 4;
-    bottomUp: 5;
-    fusedRetry: 6;
-}> = Object.freeze({ expand: 0, contract: 1, fused: 2, fillBits: 3, bitset: 4, bottomUp: 5, fusedRetry: 6 });
+    bottomUp: 3;
+    fusedRetry: 4;
+    near: 5;
+    far: 6;
+}> = Object.freeze({ none: 0, twoPhase: 1, fused: 2, bottomUp: 3, fusedRetry: 4, near: 5, far: 6 });
 
 /** The words of the counters block (`FRONTIER_COUNTERS`), by index: byte offset 4 x word; no driver types a number. */
 export const W: Readonly<{
@@ -69,6 +71,7 @@ export const W: Readonly<{
     thresholdBits: 22;
     deltaBits: 23;
     path: 24;
+    nextDegreeSum: 25;
 }> = Object.freeze({
     frontierCount: 0,
     nextFrontierCount: 1,
@@ -95,18 +98,13 @@ export const W: Readonly<{
     thresholdBits: 22,
     deltaBits: 23,
     path: 24,
+    nextDegreeSum: 25,
 });
 
 /** The words a `reset` seeds (every other word is zeroed). */
 export type FrontierSeed = Readonly<Partial<Record<keyof typeof W, number>>>;
 
-/** A ReduceScope that can also lease an INDIRECT buffer (the args of the frontier); `algorithmScope` is one. */
-export interface FrontierScope extends ReduceScope {
-    /** A STORAGE | INDIRECT | COPY_DST | COPY_SRC buffer of the scope's lease. */
-    indirect(byteLength: number, label: string): GPUBuffer;
-}
-
-/** The `FrontierParams` fields a caller passes to `recordFinalize`; the planner fills `role`, `slotBase`, `wg`, `edgeCapacity` and `n` itself. A missing field is written as 0. */
+/** The `FrontierParams` fields a caller passes to `recordFinalize`; the planner fills `role`, `wg`, `edgeCapacity` and `n` itself. A missing field is written as 0. */
 export type FrontierFinalizeFields = Readonly<
     Partial<
         Record<
@@ -163,14 +161,12 @@ function assertCount(argument: string, value: number): void {
     }
 }
 
-/** The frontier queue of design 6 row 7: two vertex queues, the counters block, the args buffer and the edge queue, all leased by the caller's scope. */
+/** The frontier queue of design 6 row 7: two vertex queues, the counters block and the edge queue, all leased by the caller's scope. */
 export class Frontier {
     /** The two n-slot u32 vertex queues (`vertices[side]` is the input of the current level). */
     readonly vertices: readonly [Binding, Binding];
-    /** The `FrontierCounters` block, 96 B, bound by every kernel as `array<atomic<u32>>`. */
+    /** The `FrontierCounters` block, 112 B, bound by every kernel as `array<atomic<u32>>`. */
     readonly counters: Binding;
-    /** The indirect args, `MAX_LEVELS_PER_SUBMIT x FRONTIER_CANDIDATES` 16-byte slots (usage INDIRECT | STORAGE | COPY_DST | COPY_SRC). */
-    readonly args: Binding;
     /** The edge queue: `edgeCapacity` entries of u32 (the target vertex of an arc). */
     readonly edgeQueue: Binding;
     /** How many entries the edge queue holds; role 1 clamps `edgeCount` to it and detects an overflow above it. */
@@ -183,7 +179,6 @@ export class Frontier {
      * Wraps the leased buffers; use prepareFrontier().
      * @param vertices - the two vertex queues
      * @param counters - the counters block
-     * @param args - the args buffer
      * @param edgeQueue - the edge queue
      * @param edgeCapacity - the edge queue's entry count
      * @param n - the vertex count
@@ -191,14 +186,12 @@ export class Frontier {
     constructor(
         vertices: readonly [Binding, Binding],
         counters: Binding,
-        args: Binding,
         edgeQueue: Binding,
         edgeCapacity: number,
         n: number,
     ) {
         this.vertices = vertices;
         this.counters = counters;
-        this.args = args;
         this.edgeQueue = edgeQueue;
         this.edgeCapacity = edgeCapacity;
         this.n = n;
@@ -234,7 +227,7 @@ export class Frontier {
     }
 
     /**
-     * Seeds a traversal: one `queue.writeBuffer` of the whole 96-byte block (zero except the caller's words) and one of
+     * Seeds a traversal: one `queue.writeBuffer` of the whole 112-byte block (zero except the caller's words) and one of
      * `vertices[0][0] = source`, both ordered before the submit that follows; the source is on side 0 afterwards.
      * `frontierCount` is not a word to seed: the first boundary rotates word 1 into it (the BFS seed is
      * `{ nextFrontierCount: 1, level: U32_MAX }`). A source outside `[0, n)`, an unknown word or a value that is not a
@@ -261,13 +254,14 @@ export class Frontier {
 
 /** A prepared frontier (design 6 row 7): the leased queue and the recorded selector dispatches. */
 export interface FrontierPlanner {
-    /** The queue the planner sizes the slots of. */
+    /** The queue the planner's selector rotates and chooses the path of. */
     readonly frontier: Frontier;
     /**
      * Records one `frontier-finalize` dispatch (one workgroup) in `role` for `level` of the current submit: one
-     * `FrontierParams` record with `slotBase = level x FRONTIER_CANDIDATES`, `wg`, `edgeCapacity` and `n` filled by the
-     * planner and every other field from `fields`. A level outside `[0, MAX_LEVELS_PER_SUBMIT)` or a role outside
-     * `[0, 3]` is E_INVALID_ARGUMENT before anything is recorded.
+     * `FrontierParams` record with `wg`, `edgeCapacity` and `n` filled by the planner and every other field from
+     * `fields`. A level outside `[0, MAX_LEVELS_PER_SUBMIT)` (the selector addresses nothing by level any more, but
+     * the host's submit cadence still is the bound) or a role outside `[0, 3]` is E_INVALID_ARGUMENT before
+     * anything is recorded.
      * @param pass - the compute pass
      * @param role - 0 the level boundary, 1 the edge-queue role (2 and 3 are P8-T9's)
      * @param level - the level inside the submit
@@ -281,14 +275,14 @@ export interface FrontierPlanner {
  * edge capacity defaults to `max(1, min(arcCount, floor(maxStorageBufferBindingSize / 4)))` (never a zero-length
  * buffer: the one-node graph has no arcs); a test passes a small one to force the overflow path. The planner lives
  * exactly as long as the scope: never use it after the scope's dispose().
- * @param scope - the caller's scope (device, caps, cache, scratch, indirect, params)
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
  * @param n - the vertex count
  * @param arcCount - the arc count (the natural edge-queue size)
  * @param edgeCapacity - the edge queue's entry count, when the caller chooses it (an integer >= 1)
  * @returns the planner
  */
 export async function prepareFrontier(
-    scope: FrontierScope,
+    scope: ReduceScope,
     n: number,
     arcCount: number,
     edgeCapacity?: number,
@@ -306,7 +300,6 @@ export async function prepareFrontier(
     }
     const kernel = await scope.pipelines.kernel(kernelSpec("frontier-finalize"));
     const queueBytes = 4 * Math.max(1, n);
-    const argsBytes = MAX_LEVELS_PER_SUBMIT * FRONTIER_CANDIDATES * INDIRECT_ARGS_STRIDE;
     const vertices: readonly [Binding, Binding] = [
         { buffer: scope.scratch(queueBytes, "frontier/vertices-0"), offset: 0, size: queueBytes, window: null },
         { buffer: scope.scratch(queueBytes, "frontier/vertices-1"), offset: 0, size: queueBytes, window: null },
@@ -317,26 +310,20 @@ export async function prepareFrontier(
         size: FRONTIER_COUNTERS.byteLength,
         window: null,
     };
-    const args: Binding = {
-        buffer: scope.indirect(argsBytes, "frontier/args"),
-        offset: 0,
-        size: argsBytes,
-        window: null,
-    };
     const edgeQueue: Binding = {
         buffer: scope.scratch(4 * capacity, "frontier/edge-queue"),
         offset: 0,
         size: 4 * capacity,
         window: null,
     };
-    const frontier = new Frontier(vertices, counters, args, edgeQueue, capacity, n);
+    const frontier = new Frontier(vertices, counters, edgeQueue, capacity, n);
     return new FrontierPlannerImpl(scope, kernel, frontier);
 }
 
-/** The planner: the selector kernel bound once to the frontier's block and args. */
+/** The planner: the selector kernel bound once to the frontier's block. */
 class FrontierPlannerImpl implements FrontierPlanner {
     readonly frontier: Frontier;
-    private readonly scope: FrontierScope;
+    private readonly scope: ReduceScope;
     private readonly kernel: Kernel;
 
     /**
@@ -345,7 +332,7 @@ class FrontierPlannerImpl implements FrontierPlanner {
      * @param kernel - the `frontier-finalize` kernel
      * @param frontier - the leased queue
      */
-    constructor(scope: FrontierScope, kernel: Kernel, frontier: Frontier) {
+    constructor(scope: ReduceScope, kernel: Kernel, frontier: Frontier) {
         this.scope = scope;
         this.kernel = kernel;
         this.frontier = frontier;
@@ -377,12 +364,11 @@ class FrontierPlannerImpl implements FrontierPlanner {
         const params = scope.params(FRONTIER_PARAMS, {
             ...definedWords(fields),
             role,
-            slotBase: level * FRONTIER_CANDIDATES,
             wg: scope.workgroupSize,
             edgeCapacity: frontier.edgeCapacity,
             n: frontier.n,
         });
-        const bound = this.kernel.bind({ counters: frontier.counters, args: frontier.args, P: params.binding });
+        const bound = this.kernel.bind({ counters: frontier.counters, P: params.binding });
         this.kernel.dispatch(pass, bound, plan1d(1, scope.workgroupSize, scope.caps), [params.offset]);
     }
 }

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);