@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/src/primitives/segmented-reduce.ts

@@ -1,27 +1,29 @@
 /**
- * The segmented (per-row) reduction primitive of spec 6 row 3 in its thread-per-row tier (P2-P3): one invocation per
- * CSR row folds the caller's VALUE snippet over the row's arcs into `out[row]` (f32), a row with no arcs receiving
- * the identity element. The degree tiers of degreeOrder() (subgroup-per-row for the mid tier, workgroup-per-row for
- * the high tier) land at P4; until then `tiers !== null` is E_UNSUPPORTED and USE_PERM is always false (the perm
- * slot carries the rowPtr dummy of graphBindings). The row and arc counts come from the core's binding sizes: the
- * residency binds every array at its exact byte length (contract 3.8), so rowPtr is 4(n + 1) bytes and colIdx
- * 4 x arcCount.
+ * The segmented (per-row) reduction primitive of spec 6 row 3: the caller's VALUE snippet folded over every CSR
+ * row's arcs into `out[row]` (f32), a row with no arcs receiving the identity element. Without tiers it is ONE
+ * thread-per-row dispatch (TIER 0, USE_PERM false: the perm slot carries the rowPtr dummy of graphBindings). With
+ * the degree tiers of degreeOrder() (P4-T5, PD-6) it is up to three dispatches over the permuted rows: TIER 2, one
+ * workgroup per row of degree >= 1024 over [0, hiEnd); TIER 1, 32 lanes per row of degree 32..1023 over [hiEnd,
+ * midEnd); TIER 0, one thread per row over [midEnd, n) -- each compiled only when its range is non-empty. The row
+ * and arc counts come from the core's binding sizes: the residency binds every array at its exact byte length
+ * (contract 3.8), so rowPtr is 4(n + 1) bytes and colIdx 4 x arcCount. On a windowed core (spec 4.2, P4-T7, PD-8)
+ * the dispatches repeat per window with `arcBase = w.start`, `arcEnd = w.end` and `accumulate = 1` over an out
+ * pre-filled with the identity element (unless the caller asked to accumulate), so a row split across windows
+ * combines its partials: the untiered dispatch covers the window's rows [rowFirst, rowLast], while every tier
+ * dispatch covers its FULL tier range (permutation positions, not comparable with the window's node rows; a row
+ * whose arcs lie outside the window folds nothing and `finish` writes comb(out[i], identity) = out[i]).
  */
 
 import { WebGpuGraphError } from "../errors.js";
 import { plan1d } from "../kernel/dispatch.js";
 import { type Kernel } from "../kernel/kernel.js";
-import { graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
+import { FILL_PARAMS, graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
 import { type CoreBinding } from "../memory/residency.js";
-import { type Binding } from "../types/memory.js";
-import { assertNotWindowed, rowCountOf } from "./core-shape.js";
+import { type ArcWindow, type Binding } from "../types/memory.js";
+import { arcCountOf, type DegreeTiers, MID_TIER_LANES, rowCountOf, windowBinding } from "./core-shape.js";
 import { type ReduceOp, type ReduceScope } from "./reduce.js";
 
-/** 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];
-}
+export { type DegreeTiers } from "./core-shape.js";
 
 /** Options of segmentedReduce. `valueSnippet` is the Gunrock-style functor: WGSL statements assigning `v` from (row, arc, nbr, weight) (4.5; `nbr` because `target` is a WGSL reserved word). */
 export interface SegmentedReduceOptions {
@@ -31,10 +33,33 @@ export interface SegmentedReduceOptions {
     readonly accumulate?: boolean | undefined;
 }
 
-/** A prepared segmented reduce (P2-P3: the thread-per-row tier only; `tiers !== null` -> E_UNSUPPORTED { feature: "segmentedReduce.tiers" } until P4). */
+/** A prepared segmented reduce: one thread-per-row dispatch without tiers, up to three tier dispatches with them (times the windows of a windowed core, plus its identity fill). */
 export interface SegmentedReducePlanner {
-    /** Records one dispatch over rows [0, n) (tiers null) writing out[i] (f32) per row; a row with no arcs gets the identity element. */
+    /** Records the dispatches over rows [0, n) writing out[i] (f32) per row; a row with no arcs gets the identity element. */
     record(pass: GPUComputePassEncoder, core: CoreBinding, out: Binding): void;
+    /** Dispatches the last record() issued (0 for n = 0; 1 without tiers; 1 to 3 with them; on a windowed core the identity fill plus that many per window). */
+    readonly lastDispatches: number;
+}
+
+/** The largest finite f32, 0x1.fffffep+127 (the prelude's F32_MAX): the min identity; its negation the max identity. */
+const F32_MAX = 2 ** 128 - 2 ** 104;
+
+/**
+ * The u32 bit pattern the `fill` kernel writes so every out word holds the identity element of the operator before
+ * the windowed dispatches accumulate into it (PD-8).
+ * @param op - the operator
+ * @returns the bits of 0 (sum), F32_MAX (min) or -F32_MAX (max)
+ */
+function identityFillWord(op: ReduceOp): number {
+    let identity = 0;
+    if (op === "min") {
+        identity = F32_MAX;
+    } else if (op === "max") {
+        identity = -F32_MAX;
+    }
+    const view = new DataView(new ArrayBuffer(4));
+    view.setFloat32(0, identity, true);
+    return view.getUint32(0, true);
 }
 
 /** The identifiers a VALUE snippet may name (contract 3.11, 4.5); every other identifier is rejected textually before compose. */
@@ -141,36 +166,75 @@ function validateValueSnippet(snippet: string): void {
     }
 }
 
-/** The thread-per-row planner: ONE `segmented-reduce` dispatch with TIER 0 over every row. */
-class ThreadPerRowPlanner implements SegmentedReducePlanner {
+/** One tier's compiled pipeline and the rows [start, end) of the permutation it covers per record() (a tier whose range is empty is not compiled). */
+interface TierDispatch {
+    readonly tier: 0 | 1 | 2;
+    readonly kernel: Kernel;
+    readonly start: number;
+    readonly end: number;
+}
+
+/**
+ * The tiered planner: without tiers ONE `segmented-reduce` dispatch with TIER 0 over [0, n); with tiers TIER 2 over
+ * [0, hiEnd) (one workgroup per row), then TIER 1 over [hiEnd, midEnd) (WG / 32 rows per workgroup), then TIER 0
+ * over [midEnd, n), each with its own RangeParams record and the perm binding.
+ */
+class TieredPlanner implements SegmentedReducePlanner {
     private readonly scope: ReduceScope;
-    private readonly kernel: Kernel;
+    private readonly tiers: readonly TierDispatch[];
+    private readonly fill: Kernel;
+    private readonly perm: Binding | null;
     private readonly hasWeights: boolean;
     private readonly accumulate: boolean;
+    private readonly identityWord: number;
+    private dispatches = 0;
 
     /**
-     * Wraps a compiled thread-per-row pipeline with the pattern it was compiled for.
-     * @param scope - the scope the pipeline was prepared in
-     * @param kernel - the compiled kernel
-     * @param hasWeights - the HAS_WEIGHTS the pipeline was compiled with
+     * Wraps the compiled tier pipelines with the pattern they were compiled for.
+     * @param scope - the scope the pipelines were prepared in
+     * @param tiers - the compiled tiers in dispatch order (TIER 2, 1, 0; only the non-empty ones)
+     * @param fill - the `fill` pipeline of the identity pre-fill of a windowed core
+     * @param perm - the degreeOrder permutation binding (null: USE_PERM false, rows are node indices)
+     * @param hasWeights - the HAS_WEIGHTS the pipelines were compiled with
      * @param accumulate - whether record() combines into out instead of overwriting
+     * @param identityWord - the u32 bits of the operator's identity element (identityFillWord)
      */
-    constructor(scope: ReduceScope, kernel: Kernel, hasWeights: boolean, accumulate: boolean) {
+    constructor(
+        scope: ReduceScope,
+        tiers: readonly TierDispatch[],
+        fill: Kernel,
+        perm: Binding | null,
+        hasWeights: boolean,
+        accumulate: boolean,
+        identityWord: number,
+    ) {
         this.scope = scope;
-        this.kernel = kernel;
+        this.tiers = tiers;
+        this.fill = fill;
+        this.perm = perm;
         this.hasWeights = hasWeights;
         this.accumulate = accumulate;
+        this.identityWord = identityWord;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns 0 for n = 0, else the number of non-empty tier ranges
+     */
+    get lastDispatches(): number {
+        return this.dispatches;
     }
 
     /**
-     * Records the dispatch: rows [0, n), arcs [0, arcCount), plan1d(n); nothing for n = 0 (no zero-length binding is
-     * ever created).
+     * Records the dispatches: every tier's rows over the arcs [0, arcCount), each with its own params record;
+     * nothing for n = 0 (no zero-length binding is ever created). On a windowed core: the identity fill (unless
+     * accumulating into the caller's out), then the dispatches once per window (PD-8).
      * @param pass - the pass to record into
-     * @param core - a core with the SAME weights pattern as the one prepared (any snapshot)
+     * @param core - a core with the SAME weights pattern as the one prepared (any snapshot; with tiers, the one the
+     * tiers were built from)
      * @param out - at least 4n bytes of f32
      */
     record(pass: GPUComputePassEncoder, core: CoreBinding, out: Binding): void {
-        assertNotWindowed(core, "segmentedReduce");
         if ((core.weights !== null) !== this.hasWeights) {
             throw new WebGpuGraphError(
                 "E_INVALID_ARGUMENT",
@@ -183,10 +247,6 @@ class ThreadPerRowPlanner implements SegmentedReducePlanner {
             );
         }
         const n = rowCountOf(core, "segmentedReduce");
-        if (n === 0) {
-            return;
-        }
-        const arcCount = core.colIdx === null ? 0 : core.colIdx.size / 4;
         if (out.size < 4 * n) {
             throw new WebGpuGraphError(
                 "E_INVALID_ARGUMENT",
@@ -198,24 +258,96 @@ class ThreadPerRowPlanner implements SegmentedReducePlanner {
                 },
             );
         }
-        const params = this.scope.params(RANGE_PARAMS, {
-            start: 0,
-            end: n,
-            arcBase: 0,
-            arcEnd: arcCount,
-            accumulate: this.accumulate ? 1 : 0,
-            n,
+        this.dispatches = 0;
+        if (n === 0) {
+            return;
+        }
+        if (core.windows === null) {
+            this.recordWindow(pass, core, out, n, null, 0);
+            return;
+        }
+        if (!this.accumulate) {
+            const params = this.scope.params(FILL_PARAMS, { count: n, value: this.identityWord, mode: 0 });
+            const bound = this.fill.bind({ dst: out, P: params.binding });
+            this.fill.dispatch(pass, bound, plan1d(n, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+            this.dispatches++;
+        }
+        const { windows } = core;
+        windows.forEach((w, k) => {
+            const windowed: CoreBinding = {
+                ...core,
+                colIdx: windowBinding(core, "colIdx", w),
+                weights: core.weights === null ? null : windowBinding(core, "weights", w),
+            };
+            this.recordWindow(pass, windowed, out, n, w, k + 1 < windows.length ? windows[k + 1].start : w.end);
         });
-        const bound = this.kernel.bind({ ...graphBindings(core, null), out, P: params.binding });
-        this.kernel.dispatch(pass, bound, plan1d(n, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+    }
+
+    /**
+     * The tier dispatches over one arc window (or the whole core when `w` is null): every non-empty tier over its
+     * full range, except the untiered TIER 0 dispatch, which covers exactly the window's rows. Consecutive windows
+     * overlap by up to ARC_WINDOW_ALIGN - 1 arcs (the next window opens at the aligned-down end of this one), and a
+     * tier dispatch visits EVERY row, so the tiers fold [w.start, nextStart) and leave the overlap to the next
+     * window; the untiered dispatch keeps [w.start, w.end): its rows [rowFirst, rowLast] are exactly the rows whose
+     * arcs end inside this window, and the next window's rows start after them.
+     * @param pass - the pass to record into
+     * @param core - the core with the window's colIdx / weights bound
+     * @param out - the output binding
+     * @param n - the row count
+     * @param w - the window, or null for the single whole-core dispatch
+     * @param nextStart - the next window's first arc (w.end for the last window)
+     */
+    private recordWindow(
+        pass: GPUComputePassEncoder,
+        core: CoreBinding,
+        out: Binding,
+        n: number,
+        w: ArcWindow | null,
+        nextStart: number,
+    ): void {
+        const wg = this.scope.workgroupSize;
+        for (const { tier, kernel, start, end } of this.tiers) {
+            let first = start;
+            let last = tier === 0 ? n : end;
+            let arcEnd = w === null ? arcCountOf(core) : Math.min(w.end, nextStart);
+            if (w !== null && this.perm === null) {
+                first = w.rowFirst;
+                last = w.rowLast + 1;
+                arcEnd = w.end;
+            }
+            const rows = last - first;
+            if (rows <= 0) {
+                continue;
+            }
+            const params = this.scope.params(RANGE_PARAMS, {
+                start: first,
+                end: last,
+                arcBase: w === null ? 0 : w.start,
+                arcEnd,
+                accumulate: w !== null || this.accumulate ? 1 : 0,
+                n,
+            });
+            const bound = kernel.bind({ ...graphBindings(core, this.perm), out, P: params.binding });
+            let rowsPerGroup = wg;
+            if (tier === 2) {
+                rowsPerGroup = 1;
+            } else if (tier === 1) {
+                rowsPerGroup = wg / MID_TIER_LANES;
+            }
+            kernel.dispatch(pass, bound, plan1d(rows, rowsPerGroup, this.scope.caps), [params.offset]);
+            this.dispatches++;
+        }
     }
 }
 
 /**
- * Prepares the thread-per-row pipeline for a snapshot's dummy pattern (USE_PERM, HAS_WEIGHTS) and snippet.
+ * Prepares the tier pipelines for a snapshot's dummy pattern (USE_PERM = tiers !== null, HAS_WEIGHTS) and snippet:
+ * TIER 0 always; TIER 1 iff a row of degree 32..1023 exists (segmentOffsets[2] > segmentOffsets[1]); TIER 2 iff a
+ * row of degree >= 1024 exists (segmentOffsets[1] > 0). The mid tier folds 32 lanes per row, so a device whose
+ * workgroup size is below 32 is E_UNSUPPORTED { feature: "segmentedReduce.tiers" }.
  * @param scope - the reduce scope (pipelines, pool, params writer)
- * @param core - the core whose weights pattern selects HAS_WEIGHTS (USE_PERM is false: no tiers at P2)
- * @param options - operator, snippet, tiers (must be null), accumulate
+ * @param core - the core whose weights pattern selects HAS_WEIGHTS
+ * @param options - operator, snippet, tiers (null: the single thread-per-row dispatch), accumulate
  * @returns the planner
  */
 export async function prepareSegmentedReduce(
@@ -223,16 +355,42 @@ export async function prepareSegmentedReduce(
     core: CoreBinding,
     options: SegmentedReduceOptions,
 ): Promise<SegmentedReducePlanner> {
-    if (options.tiers !== null) {
-        throw new WebGpuGraphError("E_UNSUPPORTED", "segmentedReduce: the degree tiers land at P4; pass tiers: null", {
-            feature: "segmentedReduce.tiers",
-        });
-    }
-    assertNotWindowed(core, "segmentedReduce");
     const op = opCode(options.op);
     validateValueSnippet(options.valueSnippet);
-    const overrides = { ...graphOverrides(core, null), OP: op, TIER: 0 };
-    const spec = kernelSpec("segmented-reduce", overrides, { VALUE: options.valueSnippet });
-    const kernel = await scope.pipelines.kernel(spec);
-    return new ThreadPerRowPlanner(scope, kernel, core.weights !== null, options.accumulate === true);
+    const { tiers } = options;
+    const perm = tiers?.perm ?? null;
+    if (tiers !== null && scope.workgroupSize < MID_TIER_LANES) {
+        throw new WebGpuGraphError(
+            "E_UNSUPPORTED",
+            `segmentedReduce: the mid tier folds ${MID_TIER_LANES} lanes per row, more than the workgroup size ${scope.workgroupSize}`,
+            { feature: "segmentedReduce.tiers" },
+        );
+    }
+    const ranges: readonly { readonly tier: 0 | 1 | 2; readonly start: number; readonly end: number }[] =
+        tiers === null
+            ? [{ tier: 0, start: 0, end: rowCountOf(core, "segmentedReduce") }]
+            : [
+                  { tier: 2, start: 0, end: tiers.segmentOffsets[1] },
+                  { tier: 1, start: tiers.segmentOffsets[1], end: tiers.segmentOffsets[2] },
+                  { tier: 0, start: tiers.segmentOffsets[2], end: tiers.segmentOffsets[4] },
+              ];
+    const compiled: TierDispatch[] = [];
+    for (const range of ranges) {
+        if (range.tier !== 0 && range.end <= range.start) {
+            continue;
+        }
+        const overrides = { ...graphOverrides(core, perm), OP: op, TIER: range.tier };
+        const spec = kernelSpec("segmented-reduce", overrides, { VALUE: options.valueSnippet });
+        compiled.push({ ...range, kernel: await scope.pipelines.kernel(spec) });
+    }
+    const fill = await scope.pipelines.kernel(kernelSpec("fill"));
+    return new TieredPlanner(
+        scope,
+        compiled,
+        fill,
+        perm,
+        core.weights !== null,
+        options.accumulate === true,
+        identityFillWord(options.op),
+    );
 }

package/src/primitives/spmv.ts

@@ -1,7 +1,6 @@
 /**
- * The pull SpMV primitive of spec 6 row 9 / 8.2 in its thread-per-row tier (P7; M8b plan PD-1 / PD-2): one
- * grid-stride dispatch of the `spmv-pull` module over the rows of a REVERSE adjacency, each invocation folding
- * `weight * xNorm[nbr]` over its row's in-arcs (Kahan-compensated, f32) and writing
+ * The pull SpMV primitive of spec 6 row 9 / 8.2 (P7; M8b plan PD-1 / PD-2): the `spmv-pull` module over the rows of
+ * a REVERSE adjacency, each row folding `weight * xNorm[nbr]` over its in-arcs (a two-level f32 sum) and writing
  * `rankOut[v] = beta * pv + alpha * (sum + danglingMass * pv)`, where `pv` is `personalization[v]` under
  * HAS_PERSONALIZATION and the uniform `P.uniformP` otherwise, and `danglingMass` is `partials[0].danglingMass`
  * under USE_DANGLING. PageRank sets alpha to the damping, beta to 1 - alpha and USE_DANGLING; HITS and eigenvector
@@ -9,20 +8,21 @@
  *
  * It is its own registry entry rather than a `segmentedReduce` VALUE snippet (PD-1): the snippet vocabulary is
  * `row, arc, nbr, weight, v` and cannot read `xNorm[nbr]`, and the design's binding table gives the kernel eight
- * storage bindings of its own. The in-degree tiers of `reverseDegreeOrder()` land at P4 (PD-2): `tiers !== null` is
- * E_UNSUPPORTED and USE_PERM is always false (the perm slot carries the rowPtr dummy of graphBindings). The row and
- * arc counts come from the core's binding sizes exactly as segmentedReduce derives them.
+ * storage bindings of its own. Without tiers it is ONE grid-stride dispatch (TIER 0, USE_PERM false: the perm slot
+ * carries the rowPtr dummy of graphBindings); with the in-degree tiers of `reverseDegreeOrder()` (P4-T5, PD-6) it
+ * is up to three dispatches over the permuted rows -- TIER 2 one workgroup per row over [0, hiEnd), TIER 1 32 lanes
+ * per row over [hiEnd, midEnd), TIER 0 grid-stride over [midEnd, n) -- each compiled only when its range is
+ * non-empty. The row and arc counts come from the core's binding sizes exactly as segmentedReduce derives them.
  */
 
 import { WebGpuGraphError } from "../errors.js";
-import { planGridStride } from "../kernel/dispatch.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
 import { type Kernel } from "../kernel/kernel.js";
 import { graphBindings, graphOverrides, kernelSpec, SPMV_PARAMS } from "../kernels.js";
 import { type CoreBinding } from "../memory/residency.js";
 import { type Binding } from "../types/memory.js";
-import { arcCountOf, assertNotWindowed, rowCountOf } from "./core-shape.js";
+import { arcCountOf, assertNotWindowed, type DegreeTiers, MID_TIER_LANES, rowCountOf } from "./core-shape.js";
 import { type ReduceScope } from "./reduce.js";
-import { type DegreeTiers } from "./segmented-reduce.js";
 
 /** The group-1 bindings of one pull: the pre-scaled input, the output, the personalization (null binds xNorm as the dummy) and the PrPartial block whose header carries danglingMass. */
 export interface SpmvResources {
@@ -39,7 +39,7 @@ export interface SpmvCoefficients {
     readonly uniformP: number;
 }
 
-/** Options of prepareSpmvPull: the two variant flags, the weights binding and the tiers (must be null at P7). */
+/** Options of prepareSpmvPull: the two variant flags, the weights binding and the in-degree tiers (null: one grid-stride dispatch). */
 export interface SpmvPullOptions {
     readonly personalization: boolean;
     readonly dangling: boolean;
@@ -48,47 +48,74 @@ export interface SpmvPullOptions {
     readonly tiers: DegreeTiers | null;
 }
 
-/** A prepared pull: records ONE grid-stride dispatch over the rows of a reverse core into a pass. */
+/** A prepared pull: records one grid-stride dispatch (no tiers) or up to three tier dispatches over the rows of a reverse core into a pass. */
 export interface SpmvPullPlanner {
-    /** Records the dispatch over rows [0, n) of `rev` writing rankOut[v] (f32) per row; nothing for n = 0. */
-    record(pass: GPUComputePassEncoder, rev: CoreBinding, resources: SpmvResources, coefficients: SpmvCoefficients): void;
-    /** Dispatches the last record() issued (1, or 0 for n = 0). */
+    /** Records the dispatches over rows [0, n) of `rev` writing rankOut[v] (f32) per row; nothing for n = 0. */
+    record(
+        pass: GPUComputePassEncoder,
+        rev: CoreBinding,
+        resources: SpmvResources,
+        coefficients: SpmvCoefficients,
+    ): void;
+    /** Dispatches the last record() issued (0 for n = 0; 1 without tiers; 1 to 3 with them). */
     readonly lastDispatches: number;
 }
 
-/** The thread-per-row planner: ONE `spmv-pull` dispatch, grid-stride over every row. */
+/** One tier's compiled pipeline and the rows [start, end) of the permutation it covers per record() (a tier whose range is empty is not compiled). */
+interface TierDispatch {
+    readonly tier: 0 | 1 | 2;
+    readonly kernel: Kernel;
+    readonly start: number;
+    readonly end: number;
+}
+
+/**
+ * The tiered planner: without tiers ONE `spmv-pull` dispatch, grid-stride over every row; with tiers TIER 2 over
+ * [0, hiEnd) (one workgroup per row), then TIER 1 over [hiEnd, midEnd) (WG / 32 rows per workgroup), then TIER 0
+ * grid-stride over [midEnd, n), each with its own SpmvParams record (`n` is the range END) and the perm binding.
+ */
 class SpmvPullPlannerImpl implements SpmvPullPlanner {
     private readonly scope: ReduceScope;
-    private readonly kernel: Kernel;
+    private readonly tiers: readonly TierDispatch[];
+    private readonly perm: Binding | null;
     private readonly weights: Binding | null | undefined;
     private dispatches = 0;
 
     /**
-     * Wraps a compiled pipeline with the weights choice it was compiled for.
-     * @param scope - the scope the pipeline was prepared in
-     * @param kernel - the compiled kernel
-     * @param weights - the weights option the pipeline's HAS_WEIGHTS was derived from; record() binds the same way
+     * Wraps the compiled tier pipelines with the choices they were compiled for.
+     * @param scope - the scope the pipelines were prepared in
+     * @param tiers - the compiled tiers in dispatch order (TIER 2, 1, 0; only the non-empty ones)
+     * @param perm - the reverseDegreeOrder permutation binding (null: USE_PERM false, rows are node indices)
+     * @param weights - the weights option the pipelines' HAS_WEIGHTS was derived from; record() binds the same way
      */
-    constructor(scope: ReduceScope, kernel: Kernel, weights: Binding | null | undefined) {
+    constructor(
+        scope: ReduceScope,
+        tiers: readonly TierDispatch[],
+        perm: Binding | null,
+        weights: Binding | null | undefined,
+    ) {
         this.scope = scope;
-        this.kernel = kernel;
+        this.tiers = tiers;
+        this.perm = perm;
         this.weights = weights;
     }
 
     /**
      * Dispatches the last record() issued.
-     * @returns 1, or 0 when the last record covered no rows
+     * @returns 0 when the last record covered no rows, else the number of non-empty tier ranges
      */
     get lastDispatches(): number {
         return this.dispatches;
     }
 
     /**
-     * Records the dispatch: rows [0, n), arcs [0, arcCount), planGridStride(n); nothing for n = 0 (no zero-length
-     * binding is ever created). `personalization ?? xNorm` follows the group-0 dummy rule: both slots are
-     * storage-ro, so the aliasing check of Kernel.bind does not fire, and HAS_PERSONALIZATION false never reads it.
+     * Records the dispatches: every tier's rows over the arcs [0, arcCount), each with its own params record (TIER 0
+     * grid-stride through planGridStride, the tiers through plan1d); nothing for n = 0 (no zero-length binding is
+     * ever created). `personalization ?? xNorm` follows the group-0 dummy rule: both slots are storage-ro, so the
+     * aliasing check of Kernel.bind does not fire, and HAS_PERSONALIZATION false never reads it.
      * @param pass - the pass to record into
-     * @param rev - the reverse core (any snapshot with the weights pattern the planner was prepared for)
+     * @param rev - the reverse core (any snapshot with the weights pattern the planner was prepared for; with tiers,
+     * the one the tiers were built from)
      * @param resources - xNorm, rankOut, personalization, partials
      * @param coefficients - alpha, beta, uniformP
      */
@@ -99,39 +126,53 @@ class SpmvPullPlannerImpl implements SpmvPullPlanner {
         coefficients: SpmvCoefficients,
     ): void {
         const n = rowCountOf(rev, "spmvPull");
-        const plan = planGridStride(n, this.scope.workgroupSize, this.scope.caps);
-        if (plan.x === 0) {
-            this.dispatches = 0;
-            return;
+        const wg = this.scope.workgroupSize;
+        this.dispatches = 0;
+        for (const { tier, kernel, start, end } of this.tiers) {
+            const last = tier === 0 ? n : end;
+            const rows = last - start;
+            if (rows <= 0) {
+                continue;
+            }
+            const plan =
+                tier === 0
+                    ? planGridStride(rows, wg, this.scope.caps)
+                    : plan1d(rows, tier === 2 ? 1 : wg / MID_TIER_LANES, this.scope.caps);
+            if (plan.x === 0) {
+                continue;
+            }
+            const params = this.scope.params(SPMV_PARAMS, {
+                n: last,
+                arcBase: 0,
+                arcEnd: arcCountOf(rev),
+                stride: plan.stride ?? rows,
+                alpha: coefficients.alpha,
+                beta: coefficients.beta,
+                uniformP: coefficients.uniformP,
+                start,
+            });
+            const bound = kernel.bind({
+                ...graphBindings(rev, this.perm, this.weights),
+                xNorm: resources.xNorm,
+                rankOut: resources.rankOut,
+                personalization: resources.personalization ?? resources.xNorm,
+                partials: resources.partials,
+                P: params.binding,
+            });
+            kernel.dispatch(pass, bound, plan, [params.offset]);
+            this.dispatches++;
         }
-        const params = this.scope.params(SPMV_PARAMS, {
-            n,
-            arcBase: 0,
-            arcEnd: arcCountOf(rev),
-            stride: plan.stride ?? n,
-            alpha: coefficients.alpha,
-            beta: coefficients.beta,
-            uniformP: coefficients.uniformP,
-            pad0: 0,
-        });
-        const bound = this.kernel.bind({
-            ...graphBindings(rev, null, this.weights),
-            xNorm: resources.xNorm,
-            rankOut: resources.rankOut,
-            personalization: resources.personalization ?? resources.xNorm,
-            partials: resources.partials,
-            P: params.binding,
-        });
-        this.kernel.dispatch(pass, bound, plan, [params.offset]);
-        this.dispatches = 1;
     }
 }
 
 /**
- * Prepares the thread-per-row pull pipeline for a reverse core's weights pattern and the two variant flags.
+ * Prepares the pull pipelines for a reverse core's weights pattern and the two variant flags: TIER 0 always
+ * (USE_PERM = tiers !== null); TIER 1 iff a row of in-degree 32..1023 exists (segmentOffsets[2] >
+ * segmentOffsets[1]); TIER 2 iff a row of in-degree >= 1024 exists (segmentOffsets[1] > 0). The mid tier folds 32
+ * lanes per row, so a device whose workgroup size is below 32 is E_UNSUPPORTED { feature: "spmvPull.tiers" }.
  * @param scope - the reduce scope (pipelines, params writer)
- * @param rev - the reverse core whose weights pattern selects HAS_WEIGHTS (USE_PERM is false: no tiers at P7)
- * @param options - personalization, dangling, weights, tiers (must be null)
+ * @param rev - the reverse core whose weights pattern selects HAS_WEIGHTS
+ * @param options - personalization, dangling, weights, tiers (null: the single grid-stride dispatch)
  * @returns the planner
  */
 export async function prepareSpmvPull(
@@ -139,17 +180,36 @@ export async function prepareSpmvPull(
     rev: CoreBinding,
     options: SpmvPullOptions,
 ): Promise<SpmvPullPlanner> {
-    if (options.tiers !== null) {
-        throw new WebGpuGraphError("E_UNSUPPORTED", "spmvPull: the in-degree tiers land at P4; pass tiers: null", {
-            feature: "spmvPull.tiers",
+    assertNotWindowed(rev, "spmvPull");
+    const { tiers } = options;
+    const perm = tiers?.perm ?? null;
+    if (tiers !== null && scope.workgroupSize < MID_TIER_LANES) {
+        throw new WebGpuGraphError(
+            "E_UNSUPPORTED",
+            `spmvPull: the mid tier folds ${MID_TIER_LANES} lanes per row, more than the workgroup size ${scope.workgroupSize}`,
+            { feature: "spmvPull.tiers" },
+        );
+    }
+    const ranges: readonly { readonly tier: 0 | 1 | 2; readonly start: number; readonly end: number }[] =
+        tiers === null
+            ? [{ tier: 0, start: 0, end: rowCountOf(rev, "spmvPull") }]
+            : [
+                  { tier: 2, start: 0, end: tiers.segmentOffsets[1] },
+                  { tier: 1, start: tiers.segmentOffsets[1], end: tiers.segmentOffsets[2] },
+                  { tier: 0, start: tiers.segmentOffsets[2], end: tiers.segmentOffsets[4] },
+              ];
+    const compiled: TierDispatch[] = [];
+    for (const range of ranges) {
+        if (range.tier !== 0 && range.end <= range.start) {
+            continue;
+        }
+        const spec = kernelSpec("spmv-pull", {
+            ...graphOverrides(rev, perm, options.weights),
+            HAS_PERSONALIZATION: options.personalization,
+            USE_DANGLING: options.dangling,
+            TIER: range.tier,
         });
+        compiled.push({ ...range, kernel: await scope.pipelines.kernel(spec) });
     }
-    assertNotWindowed(rev, "spmvPull");
-    const spec = kernelSpec("spmv-pull", {
-        ...graphOverrides(rev, null, options.weights),
-        HAS_PERSONALIZATION: options.personalization,
-        USE_DANGLING: options.dangling,
-    });
-    const kernel = await scope.pipelines.kernel(spec);
-    return new SpmvPullPlannerImpl(scope, kernel, options.weights);
+    return new SpmvPullPlannerImpl(scope, compiled, perm, options.weights);
 }