@graphty/webgpu-graph-algorithms 0.2.1 → 0.4.0

package/src/memory/residency.ts

@@ -20,6 +20,7 @@ import {
     type TypedArrayData,
 } from "@graphty/graph-format";
 
+import { STORAGE_ALIGN } from "../constants.js";
 import { type AllocationTracker } from "../device/error-scope.js";
 import { BufferUsage } from "../device/webgpu-constants.js";
 import { WebGpuGraphError } from "../errors.js";
@@ -140,6 +141,16 @@ interface ResidencyRecord {
         readonly segments: Readonly<Record<CoreArrayName, ArenaSegmentBinding | null>>;
     } | null;
     readonly bindings: Map<CoreArrayName, Binding>;
+    /** Memo of the P7 views by `name` or `name + ":packed"`, so a second view() call uploads nothing (spec 4.3). */
+    readonly views: Map<string, ViewBinding>;
+    /**
+     * One fresh marker object per PACKED view, keyed the same way as `views`. It is the `key` argument of
+     * upload(): a packed view must never be keyed on one of the snapshot's own arrays, because upload()
+     * memoises on the key object and does NOT compare byte lengths, and `s.reverse()` is cached
+     * (graph-format `graph-snapshot.ts:600-601`) so the packed and the unpacked builder see the same
+     * `rev.rowPtr` object.
+     */
+    readonly packKeys: Map<string, object>;
     released: boolean;
 }
 
@@ -345,13 +356,15 @@ export class GraphResidency {
     }
 
     /**
-     * Uploads (or finds) a view; P1-P3 support outDegree / inDegree / degreeOrder / reverseDegreeOrder; the others
-     * -> E_UNSUPPORTED until P7. packViews is accepted and ignored until P7 (a `true` request is E_UNSUPPORTED
-     * { option: "packViews" }, PLAN DECISION 9).
+     * Uploads (or finds) a view: outDegree / inDegree / degreeOrder / reverseDegreeOrder upload one array each;
+     * reverse and edgeList (P7) upload their arrays perArray, never into the arena, and are memoised per record so
+     * a second call uploads nothing (spec 4.3). coo and mate -> E_UNSUPPORTED until P11. packViews concatenates a
+     * reverse or edgeList view into ONE buffer at STORAGE_ALIGN offsets; on any other view `true` is E_UNSUPPORTED
+     * { option: "packViews" }.
      * @param s - the snapshot
      * @param name - the view
      * @param options - view options
-     * @param options.packViews - P7's packed reverse upload; `true` is E_UNSUPPORTED until then
+     * @param options.packViews - pack the reverse / edgeList arrays into one buffer (a no-op on an undirected reverse)
      * @returns the view binding
      */
     view(
@@ -361,10 +374,25 @@ export class GraphResidency {
     ): ViewBinding {
         this.assertLive();
         assertAttached(s);
-        if (options?.packViews === true) {
-            throw new WebGpuGraphError("E_UNSUPPORTED", "packViews is not supported before the P7 view uploads", {
+        const packed = options?.packViews === true;
+        if (name === "reverse" || name === "edgeList") {
+            this.assertNotReleased(s);
+            this.assertNonEmpty(s);
+            const memoKey = packed ? `${name}:packed` : name;
+            const record = this.ensureRecord(s);
+            const memo = record.views.get(memoKey);
+            if (memo !== undefined) {
+                return memo;
+            }
+            const built =
+                name === "reverse" ? this.buildReverse(s, record, packed) : this.buildEdgeList(s, record, packed);
+            record.views.set(memoKey, built);
+            return built;
+        }
+        if (packed) {
+            throw new WebGpuGraphError("E_UNSUPPORTED", "packViews applies to the reverse and edgeList views only", {
                 option: "packViews",
-                hint: "omit packViews; the four reverse arrays are uploaded separately",
+                hint: `the ${name} view uploads one array`,
             });
         }
         let array: TypedArrayData;
@@ -401,13 +429,11 @@ export class GraphResidency {
                 scalars = { segmentOffsets: Array.from(order.segmentOffsets) };
                 break;
             }
-            case "reverse":
             case "coo":
-            case "edgeList":
             case "mate":
-                throw new WebGpuGraphError("E_UNSUPPORTED", `the ${name} view is not uploaded before P7`, {
+                throw new WebGpuGraphError("E_UNSUPPORTED", `the ${name} view is not uploaded before P11`, {
                     feature: `view:${name}`,
-                    hint: "P1-P3 upload outDegree, inDegree, degreeOrder and reverseDegreeOrder",
+                    hint: "outDegree, inDegree, degreeOrder, reverseDegreeOrder, reverse and edgeList are uploaded",
                 });
             default:
                 throw invalid("name", name, "a view name");
@@ -422,6 +448,165 @@ 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
+     * core() rather than re-uploading the arrays is what makes that true on the arena plan as well, where the
+     * per-array WeakMap key resolves to the whole-arena resident (spec 4.3 lines 1182-1186). `fwdArc` is never
+     * uploaded (spec 13 row P7). `packed` is ignored when undirected: there is nothing to pack.
+     * @param s - the snapshot
+     * @param record - its residency record
+     * @param packed - concatenate the arrays into one buffer (directed only)
+     * @returns the view binding
+     */
+    private buildReverse(s: GraphSnapshot, record: ResidencyRecord, packed: boolean): ViewBinding {
+        const rev = s.reverse();
+        if (!s.directed) {
+            const core = this.core(s, ["rowPtr", "colIdx", "weights"]);
+            const bindings: Record<string, Binding> = { rowPtr: core.rowPtr };
+            if (core.colIdx !== null) {
+                bindings.colIdx = core.colIdx;
+            }
+            if (core.weights !== null) {
+                bindings.weights = core.weights;
+            }
+            return Object.freeze({
+                view: "reverse",
+                bindings: Object.freeze(bindings),
+                scalars: Object.freeze({ arcCount: [rev.arcCount], directed: [0] }),
+            });
+        }
+        const arrays: [string, TypedArrayData][] = [
+            ["rowPtr", rev.rowPtr],
+            ["colIdx", rev.colIdx],
+        ];
+        if (rev.weights !== null) {
+            arrays.push(["weights", rev.weights]);
+        }
+        const bindings = packed
+            ? this.packArrays(
+                  record,
+                  arrays,
+                  this.packKey(record, "reverse:packed"),
+                  `residency:view:${record.serial}:reverse:packed`,
+              )
+            : this.separateArrays(record, arrays, `residency:view:${record.serial}:reverse`);
+        return Object.freeze({
+            view: "reverse",
+            bindings,
+            scalars: Object.freeze({ arcCount: [rev.arcCount], directed: [1] }),
+        });
+    }
+
+    /**
+     * The each-edge-once binding an edge-parallel kernel uses on directed and undirected snapshots alike (spec 8.1
+     * row 2); `arc` is not uploaded (no kernel of P7 reads it).
+     * @param s - the snapshot
+     * @param record - its residency record
+     * @param packed - concatenate into one buffer
+     * @returns the view binding
+     */
+    private buildEdgeList(s: GraphSnapshot, record: ResidencyRecord, packed: boolean): ViewBinding {
+        const list = s.edgeList();
+        const arrays: [string, TypedArrayData][] = [
+            ["src", list.src],
+            ["dst", list.dst],
+        ];
+        if (list.weights !== null) {
+            arrays.push(["weights", list.weights]);
+        }
+        const bindings = packed
+            ? this.packArrays(
+                  record,
+                  arrays,
+                  this.packKey(record, "edgeList:packed"),
+                  `residency:view:${record.serial}:edgeList:packed`,
+              )
+            : this.separateArrays(record, arrays, `residency:view:${record.serial}:edgeList`);
+        return Object.freeze({
+            view: "edgeList",
+            bindings,
+            scalars: Object.freeze({ edgeCount: [s.edgeCount] }),
+        });
+    }
+
+    /**
+     * One resident per array (spec 4.3: views upload in perArray mode, never into the arena).
+     * @param record - the owning record
+     * @param arrays - the named arrays
+     * @param label - the buffer label prefix
+     * @returns the bindings by name
+     */
+    private separateArrays(
+        record: ResidencyRecord,
+        arrays: readonly (readonly [string, TypedArrayData])[],
+        label: string,
+    ): Readonly<Record<string, Binding>> {
+        const bindings: Record<string, Binding> = {};
+        for (const [name, array] of arrays) {
+            const resident = this.upload(record, array, array, `${label}:${name}`);
+            bindings[name] = { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
+        }
+        return Object.freeze(bindings);
+    }
+
+    /**
+     * The arrays concatenated into ONE buffer at STORAGE_ALIGN-aligned offsets (spec 4.3 packViews): one
+     * createBuffer and one writeBuffer instead of three of each, which is what the option buys. The resident is
+     * keyed on `key`, a marker object owned by the record (packKey), NOT on one of the snapshot's arrays: upload()
+     * returns an existing resident whenever the key matches and the serial matches, without comparing byte
+     * 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" }).
+     * @param record - the owning record
+     * @param arrays - 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])[],
+        key: object,
+        label: string,
+    ): Readonly<Record<string, Binding>> {
+        const offsets: number[] = [];
+        let total = 0;
+        for (const [, array] of arrays) {
+            offsets.push(total);
+            total += Math.ceil(array.byteLength / STORAGE_ALIGN) * STORAGE_ALIGN;
+        }
+        const staging = new Uint8Array(total);
+        arrays.forEach(([, array], i) => {
+            staging.set(new Uint8Array(array.buffer, array.byteOffset, array.byteLength), offsets[i]);
+        });
+        const resident = this.upload(record, key, staging, label);
+        const bindings: Record<string, Binding> = {};
+        arrays.forEach(([name, array], i) => {
+            bindings[name] = { buffer: resident.buffer, offset: offsets[i], size: array.byteLength, window: null };
+        });
+        return Object.freeze(bindings);
+    }
+
+    /**
+     * The upload key of a packed view: a marker object allocated once per record and memo name, never one of the
+     * snapshot's arrays.
+     * @param record - the owning record
+     * @param memoKey - the `views` memo key of this packed view
+     * @returns the stable marker object
+     */
+    private packKey(record: ResidencyRecord, memoKey: string): object {
+        const existing = record.packKeys.get(memoKey);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = {};
+        record.packKeys.set(memoKey, created);
+        return created;
+    }
+
     /**
      * gpuView(name) + column.version; re-uploads in place when the version changed and the byte length did not
      * (spec 4.3). CONTRACT DECISION: `owner` is required so release(owner) can find the buffer (a table has no
@@ -679,6 +864,8 @@ export class GraphResidency {
     private forget(record: ResidencyRecord): void {
         record.released = true;
         record.bindings.clear();
+        record.views.clear();
+        record.packKeys.clear();
         record.arena = null;
         record.plan = null;
         this.bySerial.delete(record.serial);
@@ -705,6 +892,8 @@ export class GraphResidency {
                 plan: null,
                 arena: null,
                 bindings: new Map<CoreArrayName, Binding>(),
+                views: new Map<string, ViewBinding>(),
+                packKeys: new Map<string, object>(),
                 released: false,
             };
             this.bySerial.set(s.serial, record);

package/src/primitives/core-shape.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ * 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";
+
+/**
+ * The row count of a core from its rowPtr binding (4(n + 1) bytes).
+ * @param core - the core
+ * @param primitive - the caller's name, used in the message and the detail
+ * @returns n
+ */
+export function rowCountOf(core: CoreBinding, primitive: string): number {
+    const bytes = core.rowPtr.size;
+    if (bytes < 4 || bytes % 4 !== 0) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `${primitive}: a rowPtr binding of ${bytes} bytes is not 4(n + 1)`,
+            {
+                argument: "core.rowPtr",
+                value: bytes,
+                expected: "a positive multiple of 4",
+            },
+        );
+    }
+    return bytes / 4 - 1;
+}
+
+/**
+ * The arc count a core implies: the colIdx binding is 4 bytes per arc, and a null colIdx is an arc-less snapshot.
+ * @param core - the core
+ * @returns the arc count
+ */
+export function arcCountOf(core: CoreBinding): number {
+    return core.colIdx === null ? 0 : core.colIdx.size / 4;
+}
+
+/**
+ * Rejects a windowed core (executed at P4).
+ * @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`, {
+            feature: `${primitive}.windowed`,
+        });
+    }
+}
+
+/**
+ * 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
+ * top-level fields (src/kernels.ts graphBindings / graphOverrides). This is the only adapter between the two in the
+ * package. `plan` is "perArray" because views always upload per array (spec 4.3 lines 1182-1186) and `windows` is
+ * null because a view is never windowed, which is what makes assertNotWindowed pass for a view. `serial` is -1: a
+ * view is not a core and no caller of this function reads serial (nothing in src/primitives or src/algorithms
+ * reads CoreBinding.serial).
+ * @param v - the view binding, from residency.view(s, "reverse") or view(s, "edgeList")
+ * @param arcCount - the arc count of the view, from v.scalars.arcCount[0]; it must agree with the colIdx binding,
+ * which is what record() derives the arc window from (E_INVALID_ARGUMENT { argument: "arcCount" } otherwise)
+ * @returns the equivalent CoreBinding
+ */
+export function coreOfView(v: ViewBinding, arcCount: number): CoreBinding {
+    const { rowPtr }: { readonly rowPtr?: Binding | undefined } = v.bindings;
+    if (rowPtr === undefined) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `the ${v.view} view has no rowPtr binding`, {
+            argument: "view",
+            value: v.view,
+            expected: "a view with a rowPtr binding (reverse)",
+        });
+    }
+    const colIdx = v.bindings.colIdx ?? null;
+    const weights = v.bindings.weights ?? null;
+    const bound = colIdx === null ? 0 : colIdx.size / 4;
+    if (bound !== arcCount) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `the ${v.view} view binds ${bound} arcs but its arcCount scalar says ${arcCount}`,
+            {
+                argument: "arcCount",
+                value: arcCount,
+                expected: bound,
+            },
+        );
+    }
+    return Object.freeze({
+        serial: -1,
+        plan: "perArray" as const,
+        rowPtr,
+        colIdx,
+        weights,
+        arcToEdge: null,
+        edgeToArc: null,
+        windows: null,
+        hasWeights: weights !== null,
+    });
+}

package/src/primitives/segmented-reduce.ts

@@ -14,6 +14,7 @@ import { type Kernel } from "../kernel/kernel.js";
 import { 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 ReduceOp, type ReduceScope } from "./reduce.js";
 
 /** The degree tiers of degreeOrder(): the permutation binding and the CPU-side segmentOffsets [0, hiEnd, midEnd, lowEnd, n]. */
@@ -140,39 +141,6 @@ function validateValueSnippet(snippet: string): void {
     }
 }
 
-/**
- * The row count of a core from its rowPtr binding (4(n + 1) bytes).
- * @param core - the core
- * @returns n
- */
-function rowCountOf(core: CoreBinding): number {
-    const bytes = core.rowPtr.size;
-    if (bytes < 4 || bytes % 4 !== 0) {
-        throw new WebGpuGraphError(
-            "E_INVALID_ARGUMENT",
-            `segmentedReduce: a rowPtr binding of ${bytes} bytes is not 4(n + 1)`,
-            {
-                argument: "core.rowPtr",
-                value: bytes,
-                expected: "a positive multiple of 4",
-            },
-        );
-    }
-    return bytes / 4 - 1;
-}
-
-/**
- * Rejects a windowed core (executed at P4).
- * @param core - the core
- */
-function assertNotWindowed(core: CoreBinding): void {
-    if (core.plan === "windowed" || core.windows !== null) {
-        throw new WebGpuGraphError("E_UNSUPPORTED", "segmentedReduce: windowed cores are executed at P4", {
-            feature: "segmentedReduce.windowed",
-        });
-    }
-}
-
 /** The thread-per-row planner: ONE `segmented-reduce` dispatch with TIER 0 over every row. */
 class ThreadPerRowPlanner implements SegmentedReducePlanner {
     private readonly scope: ReduceScope;
@@ -202,7 +170,7 @@ class ThreadPerRowPlanner implements SegmentedReducePlanner {
      * @param out - at least 4n bytes of f32
      */
     record(pass: GPUComputePassEncoder, core: CoreBinding, out: Binding): void {
-        assertNotWindowed(core);
+        assertNotWindowed(core, "segmentedReduce");
         if ((core.weights !== null) !== this.hasWeights) {
             throw new WebGpuGraphError(
                 "E_INVALID_ARGUMENT",
@@ -214,7 +182,7 @@ class ThreadPerRowPlanner implements SegmentedReducePlanner {
                 },
             );
         }
-        const n = rowCountOf(core);
+        const n = rowCountOf(core, "segmentedReduce");
         if (n === 0) {
             return;
         }
@@ -260,7 +228,7 @@ export async function prepareSegmentedReduce(
             feature: "segmentedReduce.tiers",
         });
     }
-    assertNotWindowed(core);
+    assertNotWindowed(core, "segmentedReduce");
     const op = opCode(options.op);
     validateValueSnippet(options.valueSnippet);
     const overrides = { ...graphOverrides(core, null), OP: op, TIER: 0 };

package/src/primitives/spmv.ts

@@ -0,0 +1,155 @@
+/**
+ * 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
+ * `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
+ * set alpha 1, beta 0, uniformP 0; Katz sets alpha to the attenuation, beta to its constant and uniformP 1.
+ *
+ * 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.
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { 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 { 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 {
+    readonly xNorm: Binding;
+    readonly rankOut: Binding;
+    readonly personalization: Binding | null;
+    readonly partials: Binding;
+}
+
+/** The scalar coefficients of one pull (SpmvParams alpha / beta / uniformP). */
+export interface SpmvCoefficients {
+    readonly alpha: number;
+    readonly beta: number;
+    readonly uniformP: number;
+}
+
+/** Options of prepareSpmvPull: the two variant flags, the weights binding and the tiers (must be null at P7). */
+export interface SpmvPullOptions {
+    readonly personalization: boolean;
+    readonly dangling: boolean;
+    /** The weights binding to fold with: `undefined` takes the core's, `null` runs UNWEIGHTED on a weighted core. */
+    readonly weights?: Binding | null | undefined;
+    readonly tiers: DegreeTiers | null;
+}
+
+/** A prepared pull: records ONE grid-stride dispatch 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). */
+    readonly lastDispatches: number;
+}
+
+/** The thread-per-row planner: ONE `spmv-pull` dispatch, grid-stride over every row. */
+class SpmvPullPlannerImpl implements SpmvPullPlanner {
+    private readonly scope: ReduceScope;
+    private readonly kernel: Kernel;
+    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
+     */
+    constructor(scope: ReduceScope, kernel: Kernel, weights: Binding | null | undefined) {
+        this.scope = scope;
+        this.kernel = kernel;
+        this.weights = weights;
+    }
+
+    /**
+     * Dispatches the last record() issued.
+     * @returns 1, or 0 when the last record covered no rows
+     */
+    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.
+     * @param pass - the pass to record into
+     * @param rev - the reverse core (any snapshot with the weights pattern the planner was prepared for)
+     * @param resources - xNorm, rankOut, personalization, partials
+     * @param coefficients - alpha, beta, uniformP
+     */
+    record(
+        pass: GPUComputePassEncoder,
+        rev: CoreBinding,
+        resources: SpmvResources,
+        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 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.
+ * @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)
+ * @returns the planner
+ */
+export async function prepareSpmvPull(
+    scope: ReduceScope,
+    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 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);
+}