@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/src/memory/residency.ts

@@ -5,8 +5,10 @@
  * withColumns() siblings, and tombstoned so a live user learns of the release through `isReleased` (spec 4.5).
  * Uploads follow the pure planner of ./upload-plan.ts: the arena path writes ONE buffer with ONE writeBuffer of the
  * hot prefix (or the full arena when a cold segment is needed and fits) and binds segments at
- * `segment.byteOffset - arena.byteOffset`; the perArray path writes one buffer per array; a windowed plan is
- * E_TOO_LARGE until P4 executes windows (PLAN DECISION 2). Identity permutations are never materialised: presence is
+ * `segment.byteOffset - arena.byteOffset`; the perArray path writes one buffer per array; the windowed path (P4-T7,
+ * PD-8) writes one buffer per PlannedArray range of every arc-indexed array and binds window 0 as the default
+ * colIdx / weights, the whole window list and the per-array buffers riding on the CoreBinding for the row-walking
+ * primitives to bind per window. Identity permutations are never materialised: presence is
  * decided from counts and flags, and the arcToEdge / edgeToArc getters are read only when a segment exists. Nothing
  * is freed by garbage collection; the once-only warning above warnUnreleasedSnapshots names the missing release.
  */
@@ -34,6 +36,9 @@ const DEFAULT_NEED: readonly CoreArrayName[] = Object.freeze(["rowPtr", "colIdx"
 /** The five core arrays in arena (hot-to-cold) order. */
 const CORE_ORDER: readonly CoreArrayName[] = Object.freeze(["rowPtr", "colIdx", "weights", "arcToEdge", "edgeToArc"]);
 
+/** The arc-indexed core arrays: the ones a windowed plan splits into window buffers (upload-plan.ts ARC_INDEXED). */
+const ARC_INDEXED: readonly ("colIdx" | "weights" | "arcToEdge")[] = Object.freeze(["colIdx", "weights", "arcToEdge"]);
+
 /** Every resident buffer is bound by kernels, filled by writeBuffer and readable back (tests, readbacks of state). */
 const RESIDENT_USAGE = BufferUsage.STORAGE | BufferUsage.COPY_DST | BufferUsage.COPY_SRC;
 
@@ -53,6 +58,8 @@ export interface CoreBinding {
     readonly arcToEdge: Binding | null;
     readonly edgeToArc: Binding | null;
     readonly windows: readonly ArcWindow[] | null;
+    /** The buffers each arc-indexed array was split into by the windowed plan (indexed by ArcWindow.bufferIndex; an absent array has none); non-null iff `plan === "windowed"`. */
+    readonly arcBuffers: Readonly<Record<"colIdx" | "weights" | "arcToEdge", readonly GPUBuffer[]>> | null;
     readonly hasWeights: boolean;
 }
 
@@ -63,7 +70,14 @@ export interface CoreBinding {
  */
 export interface ViewBinding {
     readonly view:
-        "reverse" | "coo" | "edgeList" | "outDegree" | "inDegree" | "degreeOrder" | "reverseDegreeOrder" | "mate";
+        | "reverse"
+        | "coo"
+        | "edgeList"
+        | "outDegree"
+        | "inDegree"
+        | "degreeOrder"
+        | "reverseDegreeOrder"
+        | "mate";
     readonly bindings: Readonly<Record<string, Binding>>;
     readonly scalars: Readonly<Record<string, readonly number[]>>;
 }
@@ -151,9 +165,24 @@ interface ResidencyRecord {
      * `rev.rowPtr` object.
      */
     readonly packKeys: Map<string, object>;
+    /** One marker object per window buffer, keyed `<name>:<bufferIndex>` (the packKey pattern: never one of the snapshot's own arrays). */
+    readonly windowKeys: Map<string, object>;
+    /** The windowed plan's windows, or null on the arena / perArray plans. */
+    windows: readonly ArcWindow[] | null;
+    /** The window buffers of every arc-indexed array uploaded so far (windowed plan only). */
+    readonly arcBuffers: Map<CoreArrayName, GPUBuffer[]>;
     released: boolean;
 }
 
+/**
+ * Whether a core array is arc-indexed (split into window buffers by a windowed plan).
+ * @param name - the core array
+ * @returns true for colIdx, weights and arcToEdge
+ */
+function isArcIndexed(name: CoreArrayName): name is "colIdx" | "weights" | "arcToEdge" {
+    return (ARC_INDEXED as readonly CoreArrayName[]).includes(name);
+}
+
 /**
  * Whether an ArrayBuffer-like is a SharedArrayBuffer (checked by tag so the global need not exist).
  * @param buffer - the buffer to test
@@ -294,8 +323,9 @@ export class GraphResidency {
 
     /**
      * Uploads (or finds) the core; `need` defaults to ["rowPtr", "colIdx", "weights"]; cold segments on demand
-     * (spec 4.2). Never materialises an identity permutation. A windowed plan throws E_TOO_LARGE { path: "windowed" }
-     * until P4 (PLAN DECISION 2); a tombstoned serial is lifted and re-uploaded (PLAN DECISION 7).
+     * (spec 4.2). Never materialises an identity permutation. A windowed plan (spec 4.2, PD-8) uploads every
+     * arc-indexed array as the plan's buffer ranges and binds window 0 as its default binding; rowPtr and edgeToArc
+     * stay whole. A tombstoned serial is lifted and re-uploaded (PLAN DECISION 7).
      * @param s - the snapshot
      * @param need - the core arrays to bind (rowPtr is always included; absent arrays are ignored)
      * @returns the core binding (a frozen object; grows as cold segments are added)
@@ -306,18 +336,6 @@ export class GraphResidency {
         const wanted = need ?? DEFAULT_NEED;
         const names = CORE_ORDER.filter((name) => (name === "rowPtr" || wanted.includes(name)) && isPresent(s, name));
         const plan = planUpload(s, this.caps, names);
-        if (plan.kind === "windowed") {
-            throw new WebGpuGraphError(
-                "E_TOO_LARGE",
-                `snapshot ${s.serial}: an arc array of ${4 * s.arcCount} bytes needs arc windows (${plan.windows.length}), which P1-P3 plan but do not execute`,
-                {
-                    needed: 4 * s.arcCount,
-                    limit: this.caps.limits.maxStorageBufferBindingSize,
-                    path: "windowed",
-                    algorithm: null,
-                },
-            );
-        }
         const record = this.ensureRecord(s);
         if (record.plan === null) {
             record.plan = plan.kind;
@@ -331,10 +349,19 @@ export class GraphResidency {
                 );
                 record.arena = { buffer: resident.buffer, segments: plan.segments };
             }
+            if (plan.kind === "windowed") {
+                record.windows = plan.windows;
+            }
         }
         for (const name of names) {
             if (!record.bindings.has(name)) {
-                record.bindings.set(name, this.bindCore(record, s, name));
+                const planned = plan.kind === "windowed" ? plan.arrays.find((a) => a.name === name) : undefined;
+                record.bindings.set(
+                    name,
+                    planned !== undefined && planned.buffers.length > 0 && record.windows !== null && isArcIndexed(name)
+                        ? this.bindWindowed(record, s, name, planned.buffers, record.windows[0])
+                        : this.bindCore(record, s, name),
+                );
             }
         }
         const rowPtr = record.bindings.get("rowPtr");
@@ -350,7 +377,15 @@ export class GraphResidency {
             weights,
             arcToEdge: record.bindings.get("arcToEdge") ?? null,
             edgeToArc: record.bindings.get("edgeToArc") ?? null,
-            windows: null,
+            windows: record.windows,
+            arcBuffers:
+                record.windows === null
+                    ? null
+                    : Object.freeze({
+                          colIdx: Object.freeze([...(record.arcBuffers.get("colIdx") ?? [])]),
+                          weights: Object.freeze([...(record.arcBuffers.get("weights") ?? [])]),
+                          arcToEdge: Object.freeze([...(record.arcBuffers.get("arcToEdge") ?? [])]),
+                      }),
             hasWeights: weights !== null,
         });
     }
@@ -448,7 +483,6 @@ export class GraphResidency {
         });
     }
 
-
     /**
      * The reverse adjacency's bindings. On an UNDIRECTED snapshot graph-format invariant I7 makes reverse() return
      * the FORWARD arrays, so the core bindings ARE the reverse bindings and nothing is uploaded -- delegating to
@@ -464,6 +498,19 @@ export class GraphResidency {
         const rev = s.reverse();
         if (!s.directed) {
             const core = this.core(s, ["rowPtr", "colIdx", "weights"]);
+            if (core.plan === "windowed") {
+                // a view is never windowed (spec 4.3): window 0's colIdx must not pose as the whole reverse adjacency
+                throw new WebGpuGraphError(
+                    "E_TOO_LARGE",
+                    `snapshot ${s.serial}: the undirected reverse view is the core, which needs arc windows (${core.windows?.length ?? 0}) that no view executes`,
+                    {
+                        needed: 4 * s.arcCount,
+                        limit: this.caps.limits.maxStorageBufferBindingSize,
+                        path: "windowed",
+                        algorithm: null,
+                    },
+                );
+            }
             const bindings: Record<string, Binding> = { rowPtr: core.rowPtr };
             if (core.colIdx !== null) {
                 bindings.colIdx = core.colIdx;
@@ -796,6 +843,59 @@ export class GraphResidency {
         return { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
     }
 
+    /**
+     * Uploads one arc-indexed array as the windowed plan's buffer ranges (spec 4.2: an array above maxBufferSize is
+     * split across buffers at window boundaries), each keyed on a marker object of the record (windowKey), and
+     * returns window 0's binding so a caller that ignores windows still binds something valid (PD-8).
+     * @param record - the snapshot's record
+     * @param s - the snapshot
+     * @param name - a PRESENT arc-indexed core array
+     * @param ranges - the plan's buffer ranges of the array
+     * @param first - window 0
+     * @returns the binding of window 0
+     */
+    private bindWindowed(
+        record: ResidencyRecord,
+        s: GraphSnapshot,
+        name: "colIdx" | "weights" | "arcToEdge",
+        ranges: readonly { readonly byteOffset: number; readonly byteLength: number }[],
+        first: ArcWindow,
+    ): Binding {
+        const array = coreArray(s, name);
+        const buffers = ranges.map(
+            (range, index) =>
+                this.upload(
+                    record,
+                    this.windowKey(record, `${name}:${index}`),
+                    new Uint8Array(array.buffer, array.byteOffset + range.byteOffset, range.byteLength),
+                    `residency:core:${record.serial}:${name}:w${index}`,
+                ).buffer,
+        );
+        record.arcBuffers.set(name, buffers);
+        return {
+            buffer: buffers[first.bufferIndex],
+            offset: first.offset,
+            size: 4 * (first.end - first.start),
+            window: first,
+        };
+    }
+
+    /**
+     * The upload key of one window buffer: a marker object allocated once per record and `<name>:<bufferIndex>`.
+     * @param record - the owning record
+     * @param memoKey - `<name>:<bufferIndex>`
+     * @returns the stable marker object
+     */
+    private windowKey(record: ResidencyRecord, memoKey: string): object {
+        const existing = record.windowKeys.get(memoKey);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = {};
+        record.windowKeys.set(memoKey, created);
+        return created;
+    }
+
     /**
      * Uploads `data` into a new buffer keyed on `key`, or returns the resident already uploaded for that key by
      * the same owner (PLAN DECISION 11: a resident belongs to one record).
@@ -866,6 +966,9 @@ export class GraphResidency {
         record.bindings.clear();
         record.views.clear();
         record.packKeys.clear();
+        record.windowKeys.clear();
+        record.arcBuffers.clear();
+        record.windows = null;
         record.arena = null;
         record.plan = null;
         this.bySerial.delete(record.serial);
@@ -894,6 +997,9 @@ export class GraphResidency {
                 bindings: new Map<CoreArrayName, Binding>(),
                 views: new Map<string, ViewBinding>(),
                 packKeys: new Map<string, object>(),
+                windowKeys: new Map<string, object>(),
+                windows: null,
+                arcBuffers: new Map<CoreArrayName, GPUBuffer[]>(),
                 released: false,
             };
             this.bySerial.set(s.serial, record);

package/src/primitives/core-shape.ts

@@ -1,13 +1,60 @@
 /**
  * The shape helpers every core-walking primitive shares (spec 4.1): the row count and the arc count a CoreBinding
- * implies, the windowed rejection of P4, and the ViewBinding -> CoreBinding adapter the P7 pull kernels need.
+ * implies, the per-window binding of a windowed core (P4-T7, PD-8), the windowed rejections the pull and the
+ * whole-core drivers keep (DEP-P4-B), and the ViewBinding -> CoreBinding adapter the P7 pull kernels need.
  * Moved out of segmented-reduce.ts by M8b-T4 so spmv.ts can use them without duplicating them; the `primitive`
  * argument keeps each caller's error details byte-identical to what they were when the helpers were private.
  */
 
 import { WebGpuGraphError } from "../errors.js";
 import { type CoreBinding, type ViewBinding } from "../memory/residency.js";
-import { type Binding } from "../types/memory.js";
+import { type ArcWindow, type Binding } from "../types/memory.js";
+
+/** The lanes one TIER 1 (mid-degree) row is folded by, in segmentedReduce and spmvPull alike (PD-6: bitwise the same on every subgroup size). */
+export const MID_TIER_LANES = 32;
+
+/** The degree tiers of degreeOrder(): the permutation binding and the CPU-side segmentOffsets [0, hiEnd, midEnd, lowEnd, n]. */
+export interface DegreeTiers {
+    readonly perm: Binding;
+    readonly segmentOffsets: readonly [number, number, number, number, number];
+}
+
+/**
+ * The DegreeTiers of a degreeOrder / reverseDegreeOrder view (the perm binding and the five segment offsets
+ * [0, hiEnd, midEnd, lowEnd, n] of graph-format's cuGraph thresholds 1024 / 32 / 1).
+ * @param view - residency.view(s, "degreeOrder") or view(s, "reverseDegreeOrder")
+ * @returns the tiers; E_INVALID_ARGUMENT when the view has no perm binding or its segmentOffsets are not five
+ * ascending numbers ending at the row count (4 bytes per row of the perm binding)
+ */
+export function degreeTiersOf(view: ViewBinding): DegreeTiers {
+    const { perm }: { readonly perm?: Binding | undefined } = view.bindings;
+    if (perm === undefined) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `the ${view.view} view has no perm binding`, {
+            argument: "view",
+            value: view.view,
+            expected: "a view with a perm binding (degreeOrder, reverseDegreeOrder)",
+        });
+    }
+    const so: readonly number[] | undefined = view.scalars.segmentOffsets;
+    const ascending =
+        so !== undefined &&
+        so.length === 5 &&
+        so[0] === 0 &&
+        so.every((value, k) => Number.isInteger(value) && (k === 0 || value >= so[k - 1]));
+    if (!ascending || so[4] !== perm.size / 4) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `the ${view.view} view's segmentOffsets are not five ascending numbers ending at the row count`,
+            {
+                argument: "view",
+                value: so === undefined ? null : Array.from(so),
+                expected: `[0, hiEnd, midEnd, lowEnd, ${perm.size / 4}] ascending`,
+            },
+        );
+    }
+    const segmentOffsets: readonly [number, number, number, number, number] = [so[0], so[1], so[2], so[3], so[4]];
+    return Object.freeze({ perm, segmentOffsets });
+}
 
 /**
  * The row count of a core from its rowPtr binding (4(n + 1) bytes).
@@ -41,18 +88,57 @@ export function arcCountOf(core: CoreBinding): number {
 }
 
 /**
- * Rejects a windowed core (executed at P4).
+ * The binding of one arc window of a windowed core's arc-indexed array (spec 4.2): the buffer the window was placed
+ * in, at the window's offset, over its arcs; the kernel reads `array[arc - P.arcBase]` with `arcBase = w.start`.
+ * @param core - a windowed core (arcBuffers non-null)
+ * @param name - the arc-indexed array
+ * @param w - one of core.windows
+ * @returns the binding; E_INVALID_ARGUMENT when the core is not windowed or the array is absent
+ */
+export function windowBinding(core: CoreBinding, name: "colIdx" | "weights" | "arcToEdge", w: ArcWindow): Binding {
+    const buffer = core.arcBuffers?.[name][w.bufferIndex];
+    if (buffer === undefined) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `windowBinding: the core has no window buffers of ${name}`, {
+            argument: "core",
+            value: name,
+            expected: "a windowed core whose plan uploaded the array",
+        });
+    }
+    return { buffer, offset: w.offset, size: 4 * (w.end - w.start), window: w };
+}
+
+/**
+ * Rejects a windowed core: the pull cannot accumulate its affine epilogue across windows (DEP-P4-B).
  * @param core - the core
  * @param primitive - the caller's name, used in the message and the feature detail
  */
 export function assertNotWindowed(core: CoreBinding, primitive: string): void {
     if (core.plan === "windowed" || core.windows !== null) {
-        throw new WebGpuGraphError("E_UNSUPPORTED", `${primitive}: windowed cores are executed at P4`, {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `${primitive}: windowed cores are not executed by the pull`, {
             feature: `${primitive}.windowed`,
         });
     }
 }
 
+/**
+ * Rejects a windowed core for a driver that walks the whole core (DEP-P4-B: pageRank, the power iterations and
+ * connectedComponents): `E_TOO_LARGE { needed, limit, path: "windowed", algorithm }` (spec 3.8 / 3.12), the refusal
+ * GraphResidency.core() itself issued before P4-T7 executed windows for degree and segmentedReduce.
+ * @param core - the core
+ * @param arcCount - the snapshot's arc count (4 bytes per arc of each arc-indexed array)
+ * @param limit - the device's maxStorageBufferBindingSize
+ * @param algorithm - the driver's name
+ */
+export function assertWholeCore(core: CoreBinding, arcCount: number, limit: number, algorithm: string): void {
+    if (core.plan === "windowed") {
+        throw new WebGpuGraphError(
+            "E_TOO_LARGE",
+            `${algorithm}: the arc arrays need a windowed upload (${core.windows?.length ?? 0} windows), which ${algorithm} does not execute (DEP-P4-B)`,
+            { needed: 4 * arcCount, limit, path: "windowed", algorithm },
+        );
+    }
+}
+
 /**
  * The CoreBinding shape of a residency VIEW (spec 4.3). residency.view() returns a ViewBinding -- a name -> Binding
  * record -- while graphBindings / graphOverrides and every core-walking primitive read rowPtr / colIdx / weights as
@@ -98,6 +184,7 @@ export function coreOfView(v: ViewBinding, arcCount: number): CoreBinding {
         arcToEdge: null,
         edgeToArc: null,
         windows: null,
+        arcBuffers: null,
         hasWeights: weights !== null,
     });
 }

package/src/primitives/grid-pyramid.ts

@@ -0,0 +1,221 @@
+/**
+ * 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
+ * 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:
+ * 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
+ * `BufferSpec`s, so `inspect(name)` reaches them); the static params of the finalize and of every level are written
+ * ONCE at bind() through the scope's params writer (PD-11), so record() writes no uniform. `src/primitives/**` never
+ * imports `src/context.ts`.
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { type DispatchPlan, plan1d } from "../kernel/dispatch.js";
+import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
+import { GRID_LEVEL_PARAMS, INDIRECT_PARAMS, kernelSpec } from "../kernels.js";
+import { type Binding } from "../types/memory.js";
+import { type GridSpec } from "./grid.js";
+import { type ReduceScope } from "./reduce.js";
+
+/**
+ * The buffers the pyramid build reads and writes (the model's named buffers). The parameter type of
+ * GridPyramidPlanner.bind (knip: exported for the signature, not imported by name).
+ * @public
+ */
+export interface GridPyramidBindings {
+    /** `array<vec4f>` positions (xyz, mass). */
+    readonly pos: Binding;
+    /** The `Fa2Params` uniform ring (`dim`, `gridMax`); `record()` takes the iteration's dynamic offset. */
+    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). */
+    readonly cellStart: Binding;
+    /** `pyramidCells` vec4f: every level, level 0 first with the pseudo-cell at 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;
+    /** Two u32 (bound whole, at least 8 bytes): `[0]` the hub count, `[1]` the largest cell occupancy; the caller zeroes both before every build (K1, T10). */
+    readonly hubCounters: Binding;
+    /** One 16-byte indirect args slot with the INDIRECT usage: G4a writes it, G4b dispatches from it. */
+    readonly hubArgs: Binding;
+}
+
+/** Where `record()` stops: after level 0 is whole (G4, G4a and G4b) or after every coarser level (G5, the default). */
+export type GridPyramidStage = "G4" | "G5";
+
+/** A prepared pyramid build (spec 7.7 G4-G5): binds once per load, records the stages of one iteration into a pass. */
+export interface GridPyramidPlanner {
+    /**
+     * Binds the named buffers and writes the static params of the finalize and of every level (PD-11); called once
+     * per load (a second call rebinds and writes fresh params, so it belongs to a reload, never to an iteration).
+     * @param bindings - the buffers
+     */
+    bind(bindings: GridPyramidBindings): void;
+    /**
+     * Records G4, G4a, G4b and then G5 for every coarser level at the `Fa2Params` slot `paramsOffset`; `upTo: "G4"`
+     * stops after G4b (level 0 is whole: G4a and G4b are G4's completion).
+     * @param pass - the compute pass
+     * @param paramsOffset - the dynamic offset of this iteration's `Fa2Params`
+     * @param upTo - the last stage to record (default "G5")
+     */
+    record(pass: GPUComputePassEncoder, paramsOffset: number, upTo?: GridPyramidStage): void;
+    /** Dispatches the last record() issued: 3 after `upTo: "G4"`, `3 + (levels - 1)` for a full record. */
+    readonly lastDispatches: number;
+}
+
+/**
+ * Prepares the pyramid's pipelines over a scope (G4, the finalize, G4b and G5; compiles once) so bind() and record()
+ * are synchronous. The planner lives exactly as long as the scope.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @param spec - the grid
+ * @returns the planner
+ */
+export async function preparePyramid(scope: ReduceScope, spec: GridSpec): Promise<GridPyramidPlanner> {
+    const centroid = await scope.pipelines.kernel(kernelSpec("grid-centroid"));
+    const finalize = await scope.pipelines.kernel(kernelSpec("indirect-finalize"));
+    const hub = await scope.pipelines.kernel(kernelSpec("grid-centroid-hub"));
+    const downsample = await scope.pipelines.kernel(kernelSpec("grid-downsample"));
+    return new GridPyramidPlannerImpl(scope, spec, { centroid, finalize, hub, downsample });
+}
+
+/** The four kernels of the build. */
+interface Kernels {
+    readonly centroid: Kernel;
+    readonly finalize: Kernel;
+    readonly hub: Kernel;
+    readonly downsample: Kernel;
+}
+
+/** What bind() prepared: the bound groups and, per coarser level, its bound group with its params offset. */
+interface Bound {
+    readonly hubArgs: Binding;
+    readonly centroid: BoundKernel;
+    readonly finalize: BoundKernel;
+    readonly finalizeOffset: number;
+    readonly hub: BoundKernel;
+    readonly levels: readonly { readonly bound: BoundKernel; readonly offset: number; readonly parentCells: number }[];
+}
+
+/** The planner: G4, G4a, G4b and G5 over one scope. */
+class GridPyramidPlannerImpl implements GridPyramidPlanner {
+    private readonly scope: ReduceScope;
+    private readonly spec: GridSpec;
+    private readonly kernels: Kernels;
+    private bound: Bound | null = null;
+    private dispatches = 0;
+
+    /**
+     * Wraps the resolved kernels; use preparePyramid().
+     * @param scope - the caller's scope
+     * @param spec - the grid
+     * @param kernels - the four kernels
+     */
+    constructor(scope: ReduceScope, spec: GridSpec, kernels: Kernels) {
+        this.scope = scope;
+        this.spec = spec;
+        this.kernels = kernels;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches(): number {
+        return this.dispatches;
+    }
+
+    /**
+     * Binds the buffers and writes the static params (see the interface).
+     * @param bindings - the buffers
+     */
+    bind(bindings: GridPyramidBindings): void {
+        const { centroid, finalize, hub, downsample } = this.kernels;
+        const { spec, scope } = this;
+        const b = bindings;
+        const finalizeParams = scope.params(INDIRECT_PARAMS, {
+            countIndex: 0,
+            wg: 1, // the finalize plans ceil(count / wg) workgroups over ITEMS; G4b's item is a hub cell, one workgroup each
+            slot: 0,
+            pad0: 0,
+        });
+        const levels: { readonly bound: BoundKernel; readonly offset: number; readonly parentCells: number }[] = [];
+        let parentSide = spec.g;
+        for (let level = 0; level + 1 < spec.levels; level++) {
+            parentSide /= 2;
+            const parentCells = parentSide ** spec.dim;
+            const params = scope.params(GRID_LEVEL_PARAMS, {
+                childBase: spec.levelOffsets[level],
+                parentBase: spec.levelOffsets[level + 1],
+                parentSide,
+                parentCells,
+                depth: spec.dim === 3 ? 2 : 1,
+                pad0: 0,
+                pad1: 0,
+                pad2: 0,
+            });
+            levels.push({
+                bound: downsample.bind({ pyramid: b.pyramid, P: params.binding }),
+                offset: params.offset,
+                parentCells,
+            });
+        }
+        this.bound = {
+            hubArgs: b.hubArgs,
+            centroid: centroid.bind({
+                sortedIdx: b.sortedIdx,
+                cellStart: b.cellStart,
+                pos: b.pos,
+                pyramid: b.pyramid,
+                hubList: b.hubList,
+                hubCounters: b.hubCounters,
+                P: b.params,
+            }),
+            finalize: finalize.bind({ counters: b.hubCounters, args: b.hubArgs, P: finalizeParams.binding }),
+            finalizeOffset: finalizeParams.offset,
+            hub: hub.bind({
+                sortedIdx: b.sortedIdx,
+                cellStart: b.cellStart,
+                pos: b.pos,
+                pyramid: b.pyramid,
+                hubList: b.hubList,
+                hubCount: b.hubCounters,
+                P: b.params,
+            }),
+            levels,
+        };
+    }
+
+    /**
+     * Records the stages (see the interface).
+     * @param pass - the compute pass
+     * @param paramsOffset - the `Fa2Params` dynamic offset
+     * @param upTo - the last stage
+     */
+    record(pass: GPUComputePassEncoder, paramsOffset: number, upTo?: GridPyramidStage): void {
+        const { bound, scope, spec } = this;
+        if (bound === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "gridPyramid: record() before bind()", { argument: "bind" });
+        }
+        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]);
+        finalize.dispatch(pass, bound.finalize, one, [bound.finalizeOffset]);
+        hub.dispatchIndirect(pass, bound.hub, bound.hubArgs, 0, [paramsOffset]);
+        this.dispatches = 3;
+        if ((upTo ?? "G5") === "G4") {
+            return;
+        }
+        for (const level of bound.levels) {
+            downsample.dispatch(pass, level.bound, plan1d(level.parentCells, scope.workgroupSize, scope.caps), [
+                level.offset,
+            ]);
+            this.dispatches += 1;
+        }
+    }
+}