@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/src/primitives/grid.ts

@@ -0,0 +1,349 @@
+/**
+ * The grid build (spec 6 row 12, 7.7 G1-G3; P4-T8): `GridSpec` on the host (PD-9) and the planner that records, into
+ * 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
+ * pass (PD-12), never an encoder clear.
+ *
+ * The named grid buffers (`cellKey`, `cellVal`, `sortedKey`, `sortedIdx`, `cellHist`, `cellStart`) are the caller's
+ * (the model's `BufferSpec`s, so `inspect(name)` reaches them); the anonymous scratch of the sort (the digit-major
+ * table and its scan, the counting-sort cursor) is taken from the scope ONCE at bind() so the sub-kernels bind the
+ * same buffers every iteration and `Kernel.bind`'s identity cache holds (PD-11). `src/primitives/**` never imports
+ * `src/context.ts`.
+ */
+
+import { GRID_COARSEST_SIDE, GRID_MIN_SIDE, GRID_SORT_BITS } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { kernelSpec } from "../kernels.js";
+import { type ResolvedLayoutTuning } from "../types/layout.js";
+import { type Binding } from "../types/memory.js";
+import {
+    type CountingSortPlanner,
+    type HistogramPlanner,
+    prepareCountingSort,
+    prepareHistogram,
+} from "./histogram.js";
+import { prepareRadixSort, radixHistBytes, type RadixSortPlanner } from "./radix-sort.js";
+import { type ReduceScope } from "./reduce.js";
+import { prepareScan, type ScanPlanner } from "./scan.js";
+
+/** The grid's geometry (spec 7.7 geometry table; PD-9), computed on the host once per load. */
+export interface GridSpec {
+    /** 2 or 3. */
+    readonly dim: 2 | 3;
+    /** The finest side `G` per axis: a power of two in [GRID_MIN_SIDE, floorPow2(gridMax)]. */
+    readonly g: number;
+    /** `log2(G / GRID_COARSEST_SIDE) + 1`. */
+    readonly levels: number;
+    /** `G^dim` finest cells; the outside pseudo-cell is index `cells`. */
+    readonly cells: number;
+    /** `cells + 2`: 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`. */
+    readonly levelOffsets: readonly number[];
+    /** Every level's cells together: `levelOffsets[levels - 1] + GRID_COARSEST_SIDE^dim`. */
+    readonly pyramidCells: number;
+    /** Whether G2 is the stable radix sort (true) or the set-deterministic counting sort (false). */
+    readonly deterministic: boolean;
+}
+
+/**
+ * The smallest power of two >= x (by doubling; 1 for x <= 1).
+ * @param x - a non-negative number
+ * @returns the power of two
+ */
+function nextPow2(x: number): number {
+    let p = 1;
+    while (p < x) {
+        p *= 2;
+    }
+    return p;
+}
+
+/**
+ * The largest power of two <= x (by doubling; 1 for x < 2).
+ * @param x - a number >= 1
+ * @returns the power of two
+ */
+function floorPow2(x: number): number {
+    let p = 1;
+    while (p * 2 <= x) {
+        p *= 2;
+    }
+    return p;
+}
+
+/**
+ * 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).
+ * @param n - the node count (>= 0)
+ * @param dim - 2 or 3
+ * @param tuning - the resolved layout tuning (`gridMax2D`, `gridMax3D`, `deterministic`)
+ * @returns the spec
+ */
+export function gridSpecFor(
+    n: number,
+    dim: 2 | 3,
+    tuning: Pick<ResolvedLayoutTuning, "gridMax2D" | "gridMax3D" | "deterministic">,
+): GridSpec {
+    const gridMax = dim === 3 ? tuning.gridMax3D : tuning.gridMax2D;
+    const side = dim === 3 ? Math.cbrt(n) : Math.sqrt(n);
+    const cap = Math.max(GRID_MIN_SIDE, floorPow2(Math.max(1, gridMax)));
+    const g = Math.min(cap, Math.max(GRID_MIN_SIDE, nextPow2(2 * Math.ceil(side))));
+    let levels = 1;
+    for (let s = g; s > GRID_COARSEST_SIDE; s /= 2) {
+        levels++;
+    }
+    const cells = g ** 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));
+        s /= 2;
+    }
+    return {
+        dim,
+        g,
+        levels,
+        cells,
+        histWords: cells + 2,
+        levelOffsets: Object.freeze(levelOffsets),
+        pyramidCells: levelOffsets[levels - 1] + GRID_COARSEST_SIDE ** dim,
+        deterministic: tuning.deterministic,
+    };
+}
+
+/**
+ * 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.
+ * @param spec - the grid
+ * @returns the byte length
+ */
+export function gridPyramidBytes(spec: GridSpec): number {
+    return 16 * spec.pyramidCells;
+}
+
+/**
+ * The buffers the build reads and writes (the model's named buffers; `state` and `params` are the blocks G1 reads).
+ * The parameter type of GridBuildPlanner.bind (knip: exported for the signature, not imported by name).
+ * @public
+ */
+export interface GridBuildBindings {
+    /** `array<vec4f>` positions (xyz, mass). */
+    readonly pos: Binding;
+    /** The `Fa2State` block (`gridMin`, `invCellSize`), read-only here. */
+    readonly state: Binding;
+    /** The `Fa2Params` uniform ring (`n`, `dim`, `gridMax`); `record()` takes the iteration's dynamic offset. */
+    readonly params: Binding;
+    /**
+     * `n` words: G1's keys, node-indexed until G2. On the deterministic path the radix sort ping-pongs through this
+     * pair (PD-5: three passes, the even one writes the input pair), so after G2 `cellKey` / `cellVal` hold the
+     * sort's last even-pass intermediate -- a permutation of the keys, which is why the histogram recorded after it
+     * counts the same multiset; the node-indexed keys of an iteration are read through `upTo: "G1"`. The counting
+     * path never writes them.
+     */
+    readonly cellKey: Binding;
+    /** `n` words: G1's values (`i`); the sort's working pair with `cellKey`. */
+    readonly cellVal: Binding;
+    /** `n` words: the sorted keys (the radix path's result pair; unused by the counting path). */
+    readonly sortedKey: Binding;
+    /** `n` words: the sorted node indices. */
+    readonly sortedIdx: Binding;
+    /** `cells + 2` words: the per-cell counts. */
+    readonly cellHist: Binding;
+    /** `cells + 2` words: the exclusive scan of `cellHist`. */
+    readonly cellStart: Binding;
+}
+
+/** Where `record()` stops: after the keys (G1), after the sort (G2) or after the histogram and its scan (G3, the default). */
+export type GridBuildStage = "G1" | "G2" | "G3";
+
+/** A prepared grid build (spec 7.7 G1-G3): binds once per load, records the stages of one iteration into a pass. */
+export interface GridBuildPlanner {
+    /**
+     * Binds the named buffers and takes the sort's scratch from the scope, sized by `cellKey` (its word count is the
+     * node capacity; PD-11); called once per load (a second call rebinds and takes fresh scratch, so it belongs to a
+     * reload, never to an iteration).
+     * @param bindings - the buffers
+     */
+    bind(bindings: GridBuildBindings): void;
+    /**
+     * Records G1, G2 and G3 for `n` nodes at the `Fa2Params` slot `paramsOffset`; `upTo` stops after the named
+     * stage (the counting path has no separate G2 stop: its sort and histogram are one sequence, so "G2" runs it all).
+     * @param pass - the compute pass
+     * @param n - the node count (in [1, the capacity]; the caller never records a grid iteration for an empty graph)
+     * @param paramsOffset - the dynamic offset of this iteration's `Fa2Params`
+     * @param upTo - the last stage to record (default "G3")
+     */
+    record(pass: GPUComputePassEncoder, n: number, paramsOffset: number, upTo?: GridBuildStage): void;
+    /** Dispatches the last record() issued. */
+    readonly lastDispatches: number;
+}
+
+/** The G2 / G3 planners: the stable radix path (PD-5) or the set-deterministic counting path. */
+type SortPath =
+    | {
+          readonly kind: "radix";
+          readonly radix: RadixSortPlanner;
+          readonly histogram: HistogramPlanner;
+          readonly scan: ScanPlanner;
+      }
+    | { readonly kind: "counting"; readonly counting: CountingSortPlanner };
+
+/**
+ * Prepares the grid build's pipelines over a scope (G1 and the sort / histogram / scan planners it composes; 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 prepareGridBuild(scope: ReduceScope, spec: GridSpec): Promise<GridBuildPlanner> {
+    const cellKey = await scope.pipelines.kernel(kernelSpec("grid-cell-key"));
+    const path: SortPath = spec.deterministic
+        ? {
+              kind: "radix",
+              radix: await prepareRadixSort(scope),
+              histogram: await prepareHistogram(scope),
+              scan: await prepareScan(scope),
+          }
+        : { kind: "counting", counting: await prepareCountingSort(scope) };
+    return new GridBuildPlannerImpl(scope, spec, cellKey, path);
+}
+
+/** What bind() prepared: the buffers, the node capacity and the sort's scratch (the radix table and its scan, or the counting-sort cursor and an unused twin). */
+interface Bound {
+    readonly bindings: GridBuildBindings;
+    readonly capacity: number;
+    readonly scratchA: Binding;
+    readonly scratchB: Binding;
+}
+
+/** The planner: G1 and the composed sort / histogram / scan over one scope. */
+class GridBuildPlannerImpl implements GridBuildPlanner {
+    private readonly scope: ReduceScope;
+    private readonly spec: GridSpec;
+    private readonly cellKey: Kernel;
+    private readonly path: SortPath;
+    private bound: Bound | null = null;
+    private dispatches = 0;
+
+    /**
+     * Wraps the resolved kernel and planners; use prepareGridBuild().
+     * @param scope - the caller's scope
+     * @param spec - the grid
+     * @param cellKey - the `grid-cell-key` kernel
+     * @param path - the sort path
+     */
+    constructor(scope: ReduceScope, spec: GridSpec, cellKey: Kernel, path: SortPath) {
+        this.scope = scope;
+        this.spec = spec;
+        this.cellKey = cellKey;
+        this.path = path;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches(): number {
+        return this.dispatches;
+    }
+
+    /**
+     * Binds the buffers and takes the sort's scratch (see the interface).
+     * @param bindings - the buffers
+     */
+    bind(bindings: GridBuildBindings): void {
+        const capacity = Math.floor(bindings.cellKey.size / 4);
+        if (capacity < 1) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "gridBuild: cellKey must hold at least one word", {
+                argument: "cellKey",
+                value: bindings.cellKey.size,
+                expected: 4,
+            });
+        }
+        const words =
+            this.path.kind === "radix" ? radixHistBytes(capacity, this.scope.workgroupSize) / 4 : this.spec.histWords;
+        this.bound = {
+            bindings,
+            capacity,
+            scratchA: this.scratch(words, "grid/sort-scratch-a"),
+            scratchB: this.scratch(words, "grid/sort-scratch-b"),
+        };
+    }
+
+    /**
+     * Records the stages (see the interface).
+     * @param pass - the compute pass
+     * @param n - the node count
+     * @param paramsOffset - the `Fa2Params` dynamic offset
+     * @param upTo - the last stage
+     */
+    record(pass: GPUComputePassEncoder, n: number, paramsOffset: number, upTo?: GridBuildStage): void {
+        const { bound } = this;
+        if (bound === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "gridBuild: record() before bind()", { argument: "bind" });
+        }
+        if (!Number.isSafeInteger(n) || n < 1 || n > bound.capacity) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "gridBuild: n must be an integer in [1, the capacity]", {
+                argument: "n",
+                value: n,
+                expected: bound.capacity,
+            });
+        }
+        const stop = upTo ?? "G3";
+        const b = bound.bindings;
+        const keyBound = this.cellKey.bind({
+            pos: b.pos,
+            S: b.state,
+            cellKey: b.cellKey,
+            cellVal: b.cellVal,
+            P: b.params,
+        });
+        this.cellKey.dispatch(pass, keyBound, plan1d(n, this.scope.workgroupSize, this.scope.caps), [paramsOffset]);
+        this.dispatches = 1;
+        if (stop === "G1") {
+            return;
+        }
+        const { histWords: bins } = this.spec;
+        if (this.path.kind === "counting") {
+            const { counting } = this.path;
+            const scratch = { hist: b.cellHist, cursor: bound.scratchA };
+            counting.record(pass, b.cellKey, n, bins, scratch, b.sortedIdx, b.cellStart);
+            this.dispatches += counting.lastDispatches;
+            return;
+        }
+        const { radix, histogram, scan } = this.path;
+        radix.record(pass, b.cellKey, b.cellVal, n, GRID_SORT_BITS, {
+            keys: b.sortedKey,
+            vals: b.sortedIdx,
+            hist: bound.scratchA,
+            offsets: bound.scratchB,
+        });
+        this.dispatches += radix.lastDispatches;
+        if (stop === "G2") {
+            return;
+        }
+        histogram.record(pass, b.cellKey, n, bins, b.cellHist);
+        scan.record(pass, b.cellHist, bins, b.cellStart);
+        this.dispatches += histogram.lastDispatches + scan.lastDispatches;
+    }
+
+    /**
+     * A scratch of `words` u32 from the scope, bound whole.
+     * @param words - the word count (>= 1)
+     * @param label - the scratch label
+     * @returns the binding
+     */
+    private scratch(words: number, label: string): Binding {
+        const size = 4 * Math.max(1, words);
+        const buffer = this.scope.scratch(size, label);
+        return { buffer, offset: 0, size, window: null };
+    }
+}

package/src/primitives/histogram.ts

@@ -0,0 +1,273 @@
+/**
+ * The `histogram` and `countingSortByKey` primitive drivers (spec 6 row 5; P4-T3, PD-4). `histogram` zeroes `hist`
+ * with a `fill` dispatch and then adds one per key in global memory: order-independent, so bitwise deterministic on
+ * every adapter. `countingSortByKey` is the histogram, an exclusive scan of it into `outStart`, a zeroed per-bin
+ * `cursor`, and the scatter `outIndex[outStart[k] + atomicAdd(&cursor[k], 1)] = i`: the SET of indices inside a bin
+ * is fixed, their order follows the schedule (set-deterministic, design 6). Every zeroing is a dispatch inside the
+ * caller's pass (PD-12), never an encoder clear.
+ *
+ * The drivers own no device objects: the caller supplies a ReduceScope (the same record `reduce` takes) and the
+ * compute pass to record into. `src/primitives/**` never imports `src/context.ts`.
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { FILL_PARAMS, HIST_PARAMS, kernelSpec } from "../kernels.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+import { prepareScan, type ScanPlanner } from "./scan.js";
+
+/** A prepared histogram (spec 6 row 5): records the fill and the one counting dispatch into a pass. */
+export interface HistogramPlanner {
+    /**
+     * Records the histogram of `count` u32 keys of `keys` over `bins` bins into `hist` (zeroed first by a `fill`
+     * dispatch); a key >= bins is not counted. For count 0 only the fill is recorded, so `hist` is all zero.
+     * @param pass - the compute pass
+     * @param keys - the keys (at least 4 x count bytes)
+     * @param count - the key count (a non-negative integer below 2^32)
+     * @param bins - the bin count (an integer in [1, 2^32))
+     * @param hist - the counts (at least 4 x bins bytes)
+     */
+    record(pass: GPUComputePassEncoder, keys: Binding, count: number, bins: number, hist: Binding): void;
+    /** Dispatches the last record() issued: 1 (the fill) for count 0, else 2. */
+    readonly lastDispatches: number;
+}
+
+/** The two per-bin scratch arrays of a counting sort: the histogram and the scatter cursor, each at least 4 x bins bytes. */
+interface CountingSortScratch {
+    readonly hist: Binding;
+    readonly cursor: Binding;
+}
+
+/** A prepared counting sort by key (spec 6 row 5): records the histogram, the scan, the cursor fill and the scatter into a pass. */
+export interface CountingSortPlanner {
+    /**
+     * Records the counting sort of `count` keys of `keys` (every key < bins) into `outIndex` (the indices in key
+     * order; the order inside a bin follows the schedule) and `outStart` (the exclusive scan of the histogram, so bin
+     * k holds `outIndex[outStart[k] .. outStart[k + 1])` when outStart has bins + 1 words, as the grid's does).
+     * For count 0 the two fills and the scan run and `outStart` is all zero.
+     * @param pass - the compute pass
+     * @param keys - the keys (at least 4 x count bytes)
+     * @param count - the key count (a non-negative integer below 2^32)
+     * @param bins - the bin count (an integer in [1, 2^32))
+     * @param scratch - the per-bin histogram and cursor (each at least 4 x bins bytes)
+     * @param outIndex - the sorted indices (at least 4 x count bytes)
+     * @param outStart - the bin starts (at least 4 x bins bytes)
+     */
+    record(
+        pass: GPUComputePassEncoder,
+        keys: Binding,
+        count: number,
+        bins: number,
+        scratch: CountingSortScratch,
+        outIndex: Binding,
+        outStart: Binding,
+    ): void;
+    /** Dispatches the last record() issued: the histogram's + the scan's + 1 (the cursor fill) + 1 (the scatter, count > 0 only). */
+    readonly lastDispatches: number;
+}
+
+/** The largest u32: the largest value `HistParams.count` / `bins` can carry. */
+const U32_MAX = 0xffffffff;
+
+/**
+ * Prepares the histogram pipelines of a scope (compiles `histogram` and `fill` once) so record() is synchronous.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export async function prepareHistogram(scope: ReduceScope): Promise<HistogramPlanner> {
+    return prepareHistogramImpl(scope);
+}
+
+/**
+ * The concrete histogram planner (its recordZero is what the counting sort reuses for the cursor).
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+async function prepareHistogramImpl(scope: ReduceScope): Promise<HistogramPlannerImpl> {
+    const histogram = await scope.pipelines.kernel(kernelSpec("histogram"));
+    const fill = await scope.pipelines.kernel(kernelSpec("fill"));
+    return new HistogramPlannerImpl(scope, histogram, fill);
+}
+
+/**
+ * Prepares the counting-sort pipelines of a scope (the histogram's, the scan's and `counting-scatter`) so record()
+ * is synchronous. The planner lives exactly as long as the scope (the scan keeps a scratch word of it).
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+export async function prepareCountingSort(scope: ReduceScope): Promise<CountingSortPlanner> {
+    const histogram = await prepareHistogramImpl(scope);
+    const scan = await prepareScan(scope);
+    const scatter = await scope.pipelines.kernel(kernelSpec("counting-scatter"));
+    return new CountingSortPlannerImpl(scope, histogram, scan, scatter);
+}
+
+/**
+ * The E_INVALID_ARGUMENT of a binding shorter than `words` u32.
+ * @param name - the argument name
+ * @param binding - the binding
+ * @param words - the words it must hold
+ */
+function checkWords(name: string, binding: Binding, words: number): void {
+    if (binding.size < 4 * words) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `histogram: ${name} is smaller than 4 x ${words} bytes`, {
+            argument: name,
+            value: binding.size,
+            expected: 4 * words,
+        });
+    }
+}
+
+/**
+ * The argument checks shared by both record() methods (E_INVALID_ARGUMENT before anything is recorded).
+ * @param keys - the keys binding
+ * @param count - the key count
+ * @param bins - the bin count
+ * @param hist - the histogram binding
+ */
+function checkHistogramArguments(keys: Binding, count: number, bins: number, hist: Binding): void {
+    if (!Number.isSafeInteger(count) || count < 0 || count > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "histogram: count must be a non-negative integer below 2^32", {
+            argument: "count",
+            value: count,
+        });
+    }
+    if (!Number.isSafeInteger(bins) || bins < 1 || bins > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "histogram: bins must be an integer in [1, 2^32)", {
+            argument: "bins",
+            value: bins,
+        });
+    }
+    checkWords("keys", keys, count);
+    checkWords("hist", hist, bins);
+}
+
+/** The planner: the histogram and fill kernels over one scope. */
+class HistogramPlannerImpl implements HistogramPlanner {
+    private readonly scope: ReduceScope;
+    private readonly histogram: Kernel;
+    private readonly fill: Kernel;
+    private dispatches = 0;
+
+    /**
+     * Wraps the resolved kernels; use prepareHistogram().
+     * @param scope - the caller's scope
+     * @param histogram - the `histogram` kernel
+     * @param fill - the `fill` kernel
+     */
+    constructor(scope: ReduceScope, histogram: Kernel, fill: Kernel) {
+        this.scope = scope;
+        this.histogram = histogram;
+        this.fill = fill;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches(): number {
+        return this.dispatches;
+    }
+
+    /**
+     * Records the fill and the histogram (see the interface).
+     * @param pass - the compute pass
+     * @param keys - the keys
+     * @param count - the key count
+     * @param bins - the bin count
+     * @param hist - the counts
+     */
+    record(pass: GPUComputePassEncoder, keys: Binding, count: number, bins: number, hist: Binding): void {
+        checkHistogramArguments(keys, count, bins, hist);
+        this.recordZero(pass, hist, bins);
+        this.dispatches = 1;
+        if (count === 0) {
+            return;
+        }
+        const params = this.scope.params(HIST_PARAMS, { count, bins, pad0: 0, pad1: 0 });
+        const bound = this.histogram.bind({ keys, hist, P: params.binding });
+        this.histogram.dispatch(pass, bound, plan1d(count, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+        this.dispatches = 2;
+    }
+
+    /**
+     * Records a `fill` of `words` zeros into `dst` (PD-12: a dispatch inside the pass, never an encoder clear).
+     * @param pass - the compute pass
+     * @param dst - the words to zero
+     * @param words - how many (>= 1)
+     */
+    recordZero(pass: GPUComputePassEncoder, dst: Binding, words: number): void {
+        const params = this.scope.params(FILL_PARAMS, { count: words, value: 0, mode: 0, pad0: 0 });
+        const bound = this.fill.bind({ dst, P: params.binding });
+        this.fill.dispatch(pass, bound, plan1d(words, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+    }
+}
+
+/** The planner: the histogram planner, the scan planner and the scatter kernel over one scope. */
+class CountingSortPlannerImpl implements CountingSortPlanner {
+    private readonly scope: ReduceScope;
+    private readonly histogram: HistogramPlannerImpl;
+    private readonly scan: ScanPlanner;
+    private readonly scatter: Kernel;
+    private dispatches = 0;
+
+    /**
+     * Wraps the resolved planners and kernel; use prepareCountingSort().
+     * @param scope - the caller's scope
+     * @param histogram - the histogram planner (also the zeroing of the cursor)
+     * @param scan - the scan planner
+     * @param scatter - the `counting-scatter` kernel
+     */
+    constructor(scope: ReduceScope, histogram: HistogramPlannerImpl, scan: ScanPlanner, scatter: Kernel) {
+        this.scope = scope;
+        this.histogram = histogram;
+        this.scan = scan;
+        this.scatter = scatter;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches(): number {
+        return this.dispatches;
+    }
+
+    /**
+     * Records the four stages (see the interface).
+     * @param pass - the compute pass
+     * @param keys - the keys
+     * @param count - the key count
+     * @param bins - the bin count
+     * @param scratch - the histogram and cursor
+     * @param outIndex - the sorted indices
+     * @param outStart - the bin starts
+     */
+    record(
+        pass: GPUComputePassEncoder,
+        keys: Binding,
+        count: number,
+        bins: number,
+        scratch: CountingSortScratch,
+        outIndex: Binding,
+        outStart: Binding,
+    ): void {
+        checkHistogramArguments(keys, count, bins, scratch.hist);
+        checkWords("cursor", scratch.cursor, bins);
+        checkWords("outIndex", outIndex, count);
+        checkWords("outStart", outStart, bins);
+        this.histogram.record(pass, keys, count, bins, scratch.hist);
+        this.scan.record(pass, scratch.hist, bins, outStart);
+        this.histogram.recordZero(pass, scratch.cursor, bins);
+        this.dispatches = this.histogram.lastDispatches + this.scan.lastDispatches + 1;
+        if (count === 0) {
+            return;
+        }
+        const params = this.scope.params(HIST_PARAMS, { count, bins, pad0: 0, pad1: 0 });
+        const bound = this.scatter.bind({ keys, start: outStart, cursor: scratch.cursor, outIndex, P: params.binding });
+        this.scatter.dispatch(pass, bound, plan1d(count, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+        this.dispatches += 1;
+    }
+}