@graphty/webgpu-graph-algorithms 0.2.1 → 0.3.0

package/src/algorithms/pagerank.ts

@@ -0,0 +1,343 @@
+/**
+ * PageRank and personalized PageRank on the device (spec 8.2, 3.3): a pull over the reverse adjacency with the
+ * out-weight normaliser folded into `xNorm` by `pr-scale`, the dangling mass and the L1 delta folded by
+ * `pr-finalize` into the header at `partials[0]`, and `spmv-pull` writing the next iterate. Iterations run in
+ * batches of PR_BATCH per submit, ONE readback per batch (the header and the iterate together), and the device
+ * records `firstConverged` the first time the delta falls below `tolerance * n`, so the reported `iterations` is the
+ * first converged iteration and not the batch boundary (spec 9.7).
+ *
+ * PLAN DECISION PD-7: the ping-pong is TWO buffers (`rankA`, `rankB`) alternated through two cached bind groups;
+ * one buffer of two aliased halves would bind (each kernel sees the halves in one access mode) but saves nothing.
+ * PLAN DECISION PD-8: `outWeightSum` is call scratch from the Lease, one `segmentedReduce` pass per call.
+ * PLAN DECISION PD-9: `pr-scale` at iteration i reads x(i-1) and x(i-2), so its delta is the error of iteration
+ * i - 1 and `pr-finalize` records `P.iteration - 1`; the ping-pong supplies `rankPrev` for free because it is the
+ * buffer this iteration overwrites, and `pr-scale` runs before `spmv-pull` in the same pass.
+ */
+
+import { type F32, type GraphSnapshot } from "@graphty/graph-format";
+
+import { U32_MAX } from "../constants.js";
+import { type GpuContext } from "../context.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { groupsOf, plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
+import { type ArrayBinding, type CoreBinding } from "../memory/residency.js";
+import { coreOfView } from "../primitives/core-shape.js";
+import { prepareSegmentedReduce } from "../primitives/segmented-reduce.js";
+import { prepareSpmvPull } from "../primitives/spmv.js";
+import { type GpuPageRankResult, type PageRankOptions } from "../types/algorithms.js";
+import { type Binding } from "../types/memory.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { algorithmScope } from "./scope.js";
+
+/** Iterations per submit (spec 8.2: k = 8). */
+const PR_BATCH = 8;
+/** Params slots of one batch: per iteration one PrParams (shared by pr-scale and pr-finalize) and one SpmvParams, plus the normaliser's RangeParams; a smaller ring wraps onto a slot the same batch still reads. */
+const RING_SLOTS = 2 * PR_BATCH + 1;
+
+/**
+ * Validates `options.dest` for a score result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @param algorithm - the caller's name, for the message
+ * @returns the destination as an F32, or null when none was given
+ */
+function checkDest(dest: Float32Array | Uint32Array | undefined, n: number, algorithm: string): F32 | null {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Float32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest as F32;
+    }
+    throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `${algorithm}: dest must be a Float32Array of length ${n} over an ArrayBuffer`,
+        {
+            argument: "dest",
+            value: `${dest.constructor.name}(${dest.length})`,
+            expected: `Float32Array(${n}) over an ArrayBuffer`,
+        },
+    );
+}
+
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param algorithm - the caller's name
+ * @returns the core binding
+ */
+function coreOf(ctx: GpuContext, s: GraphSnapshot, algorithm: string): CoreBinding {
+    try {
+        return ctx.residency.core(s);
+    } catch (error: unknown) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError(
+                "E_TOO_LARGE",
+                `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`,
+                { ...error.details, algorithm },
+            );
+        }
+        throw error;
+    }
+}
+
+/**
+ * Whole-buffer binding of a scratch buffer over its first `size` bytes.
+ * @param buffer - the buffer
+ * @param size - the bound byte length
+ * @returns the binding
+ */
+function bindingOf(buffer: GPUBuffer, size: number): Binding {
+    return { buffer, offset: 0, size, window: null };
+}
+
+/**
+ * The E_ABORTED error of a signal.
+ * @param algorithm - the caller's name
+ * @param batchId - the last submitted batch, when one exists
+ * @returns the error
+ */
+function aborted(algorithm: string, batchId?: number): WebGpuGraphError {
+    return new WebGpuGraphError(
+        "E_ABORTED",
+        `${algorithm}: the signal was aborted`,
+        batchId === undefined ? {} : { batchId },
+    );
+}
+
+/**
+ * The shared driver: `personalization` is the normalised vector of personalizedPageRank or null for the uniform
+ * 1 / n of pageRank.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param personalization - the normalised personalization (sum 1), or null
+ * @param options - the PageRank and run options
+ * @param algorithm - the public name, for messages and labels
+ * @returns the result
+ */
+async function run(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    personalization: F32 | null,
+    options: (PageRankOptions & GpuRunOptions) | undefined,
+    algorithm: string,
+): Promise<GpuPageRankResult> {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const alpha = options?.dampingFactor ?? 0.85;
+    const maxIterations = options?.maxIterations ?? 100;
+    const tolerance = options?.tolerance ?? 1e-6;
+    const useWeights = options?.weighted !== false;
+    if (!Number.isInteger(maxIterations) || maxIterations < 1) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${algorithm}: maxIterations must be a positive integer`, {
+            argument: "maxIterations",
+            value: maxIterations,
+            expected: "a positive integer",
+        });
+    }
+    const dest = checkDest(options?.dest, n, algorithm);
+    if (options?.signal?.aborted) {
+        throw aborted(algorithm);
+    }
+    if (n === 0) {
+        options?.onProgress?.(maxIterations, maxIterations);
+        return { scores: dest ?? new Float32Array(0), iterations: 0, converged: true, danglingMass: 0, precision: "f32" };
+    }
+    const core = coreOf(ctx, s, algorithm);
+    if (s.arcCount === 0) {
+        // every node is dangling: the whole mass is redistributed by pv each iteration, so pv is the fixed point
+        const scores = dest ?? new Float32Array(n);
+        if (personalization === null) {
+            scores.fill(1 / n);
+        } else {
+            scores.set(personalization);
+        }
+        options?.onProgress?.(maxIterations, maxIterations);
+        return { scores, iterations: 0, converged: true, danglingMass: 1, precision: "f32" };
+    }
+    const view = ctx.residency.view(s, "reverse");
+    const rev = coreOfView(view, view.scalars.arcCount[0]);
+    // weighted: false runs the unweighted algorithm on BOTH sides: the normaliser sums 1 per arc and the pull folds 1
+    const weights: Binding | null | undefined = useWeights ? undefined : null;
+    const weightedCore: CoreBinding = useWeights ? core : { ...core, weights: null, hasWeights: false };
+    const weightedRev: CoreBinding = useWeights ? rev : { ...rev, weights: null, hasWeights: false };
+    const scope = algorithmScope(ctx, algorithm, RING_SLOTS);
+    let uploaded: ArrayBinding | null = null;
+    try {
+        const bytes = 4 * n;
+        const rankA = scope.scratch(bytes, "rankA");
+        const rankB = scope.scratch(bytes, "rankB");
+        const xNorm = scope.scratch(bytes, "xNorm");
+        const outWeightSum = scope.scratch(bytes, "outWeightSum");
+        const scalePlan = plan1d(n, ctx.workgroupSize, ctx.caps);
+        const groups = groupsOf(scalePlan);
+        const partialsBytes = PR_PARTIAL.byteLength * (1 + groups);
+        const partials = scope.scratch(partialsBytes, "partials");
+        if (personalization !== null) {
+            uploaded = ctx.residency.array(personalization, `${algorithm}/personalization`);
+        }
+        await ctx.allocator.check();
+        const normaliser = await prepareSegmentedReduce(scope, weightedCore, {
+            op: "sum",
+            valueSnippet: "v = weight;",
+            tiers: null,
+        });
+        const pull = await prepareSpmvPull(scope, weightedRev, {
+            personalization: personalization !== null,
+            dangling: true,
+            weights,
+            tiers: null,
+        });
+        const scale = await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: 0 }));
+        const finalize = await ctx.pipelines.kernel(kernelSpec("pr-finalize", { NORM_MODE: 0 }));
+        const finalizePlan = plan1d(1, ctx.workgroupSize, ctx.caps);
+        const { queue } = ctx.device;
+        queue.writeBuffer(rankA, 0, new Float32Array(n).fill(1 / n));
+        queue.writeBuffer(rankB, 0, new Float32Array(n));
+        const header = new ArrayBuffer(PR_PARTIAL.byteLength);
+        PR_PARTIAL.write(new DataView(header), { firstConverged: U32_MAX, iteration: 0 });
+        queue.writeBuffer(partials, 0, header);
+        const rank = [bindingOf(rankA, bytes), bindingOf(rankB, bytes)];
+        const xNormBinding = bindingOf(xNorm, bytes);
+        const outWeightSumBinding = bindingOf(outWeightSum, bytes);
+        const partialsBinding = bindingOf(partials, partialsBytes);
+        const coefficients = { alpha, beta: 1 - alpha, uniformP: 1 / n };
+        let cur = 0;
+        let iterationsRun = 0;
+        for (;;) {
+            const k = Math.min(PR_BATCH, maxIterations - iterationsRun);
+            const batch = new CommandBatch(ctx, algorithm);
+            const pass = batch.pass("iterations");
+            if (iterationsRun === 0) {
+                normaliser.record(pass, weightedCore, outWeightSumBinding);
+            }
+            for (let i = 0; i < k; i++) {
+                const params = scope.params(PR_PARAMS, {
+                    n,
+                    groups,
+                    iteration: iterationsRun + i + 1,
+                    trackConvergence: 1,
+                    convergeThreshold: tolerance * n,
+                });
+                const other = 1 - cur;
+                const scaleBound = scale.bind({
+                    rankIn: rank[cur],
+                    rankPrev: rank[other],
+                    outWeightSum: outWeightSumBinding,
+                    xNorm: xNormBinding,
+                    partials: partialsBinding,
+                    P: params.binding,
+                });
+                scale.dispatch(pass, scaleBound, scalePlan, [params.offset]);
+                const finalizeBound = finalize.bind({ partials: partialsBinding, P: params.binding });
+                finalize.dispatch(pass, finalizeBound, finalizePlan, [params.offset]);
+                pull.record(
+                    pass,
+                    weightedRev,
+                    {
+                        xNorm: xNormBinding,
+                        rankOut: rank[other],
+                        personalization: uploaded?.binding ?? null,
+                        partials: partialsBinding,
+                    },
+                    coefficients,
+                );
+                cur = other;
+            }
+            batch.endPass();
+            const headerRequest = batch.readback(partials, 0, PR_PARTIAL.byteLength);
+            const scoresRequest = batch.readback(rank[cur].buffer, 0, bytes);
+            scope.flush();
+            const submitted = batch.submit();
+            const back = await submitted.readback;
+            iterationsRun += k;
+            ctx.assertReady();
+            if (options?.signal?.aborted) {
+                throw aborted(algorithm, submitted.id);
+            }
+            options?.onProgress?.(iterationsRun, maxIterations);
+            const folded = PR_PARTIAL.read(new DataView(back), headerRequest.offset);
+            const firstConverged = folded.firstConverged as number;
+            const converged = firstConverged !== U32_MAX;
+            if (converged || iterationsRun >= maxIterations) {
+                const scores = dest ?? new Float32Array(n);
+                scores.set(new Float32Array(back, scoresRequest.offset, n));
+                if (converged && iterationsRun < maxIterations) {
+                    options?.onProgress?.(maxIterations, maxIterations);
+                }
+                return {
+                    scores,
+                    iterations: converged ? firstConverged : iterationsRun,
+                    converged,
+                    danglingMass: folded.danglingMass as number,
+                    precision: "f32",
+                };
+            }
+        }
+    } finally {
+        uploaded?.destroy();
+        scope.dispose();
+    }
+}
+
+/**
+ * PageRank on the device (spec 3.3, 8.2): NetworkX semantics, f32 scores, `iterations` the first converged
+ * iteration (spec 9.7).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export function pageRank(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: PageRankOptions & GpuRunOptions,
+): Promise<GpuPageRankResult> {
+    return run(ctx, s, null, options, "pageRank");
+}
+
+/**
+ * Personalized PageRank on the device (spec 3.3, 8.2): the personalization vector replaces the uniform 1 / n in
+ * the teleport and the dangling redistribution; it is normalised to sum 1 on the host.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param personalization - one finite non-negative mass per node, not all zero
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export async function personalizedPageRank(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    personalization: F32,
+    options?: PageRankOptions & GpuRunOptions,
+): Promise<GpuPageRankResult> {
+    const n = s.nodeCount;
+    const invalid = (value: unknown, expected: string): WebGpuGraphError =>
+        new WebGpuGraphError("E_INVALID_ARGUMENT", `personalizedPageRank: personalization must be ${expected}`, {
+            argument: "personalization",
+            value,
+            expected,
+        });
+    if (!(personalization instanceof Float32Array) || personalization.length !== n) {
+        throw invalid(`${personalization.constructor.name}(${personalization.length})`, `a Float32Array of length ${n}`);
+    }
+    let total = 0;
+    for (let v = 0; v < n; v++) {
+        const mass = personalization[v];
+        if (!Number.isFinite(mass) || mass < 0) {
+            throw invalid(mass, "finite and non-negative in every entry");
+        }
+        total += mass;
+    }
+    if (n > 0 && !(total > 0)) {
+        throw invalid(total, "a vector whose entries sum to a positive number");
+    }
+    const normalised = new Float32Array(n);
+    for (let v = 0; v < n; v++) {
+        normalised[v] = personalization[v] / total;
+    }
+    return run(ctx, s, normalised, options, "personalizedPageRank");
+}

package/src/algorithms/power-iteration.ts

@@ -0,0 +1,278 @@
+/**
+ * The power-iteration driver HITS, eigenvector centrality and Katz centrality share (spec 8.2 lines 2603-2605; M8b
+ * plan PD-10): per iteration `pr-scale` at NORM_MODE 1 | 2 | 4 folds the norm term (and the L1 delta) into the
+ * per-workgroup partials, `pr-finalize` folds them into the header at `partials[0]` (the square root for L2) and
+ * records `firstConverged`, `pr-scale` at NORM_MODE 3 writes `xNorm[u] = x[u] / partials[0].norm` (skipped at
+ * mode 4, the identity, where the first scale pass already wrote `xNorm[u] = x[u]`), and `spmv-pull` writes the
+ * next iterate. Four dispatches (three for Katz), all on the device, NO readback inside the batch: the scalar
+ * normaliser the host cannot supply without a readback is exactly what stays on the device, so these three batch
+ * eight iterations per submit like PageRank does.
+ *
+ * The ping-pong is TWO buffers alternated through two cached bind groups (PD-7 / DEP-M8B-G), and `rankPrev` is the
+ * buffer this iteration overwrites: it still holds x(i-2) when `pr-scale` reads it, because the scale runs before
+ * the pull in the same pass (PD-9). With an `alternate` adjacency (HITS, spec 8.2: "alternates two pulls") the
+ * iterations pull over `adjacency` and `alternate` in turn, and the ring is THREE buffers so the buffer being
+ * overwritten holds x(i-3) -- the previous iterate of the same kind -- and the delta stays meaningful. The batch
+ * loop duplicates src/algorithms/pagerank.ts, which its own task owns.
+ */
+
+import { type F32, type GraphSnapshot } from "@graphty/graph-format";
+
+import { U32_MAX } from "../constants.js";
+import { type GpuContext } from "../context.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { groupsOf, plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
+import { type CoreBinding } from "../memory/residency.js";
+import { coreOfView } from "../primitives/core-shape.js";
+import { prepareSpmvPull } from "../primitives/spmv.js";
+import { type Binding } from "../types/memory.js";
+import { algorithmScope } from "./scope.js";
+
+/** Iterations per submit (spec 8.2: k = 8). */
+const BATCH = 8;
+/** Params slots of one batch: four blocks per iteration times the batch, plus a margin (the plan's `4 * 8 + 8`). */
+const RING_SLOTS = 4 * BATCH + 8;
+
+/**
+ * What one power iteration run needs. `adjacency` is the CoreBinding the pull walks -- the forward core for hubs
+ * and eigenvector, coreOfView(view(s, "reverse")) for authorities and Katz (spec 8.2 lines 2603-2606). Exported
+ * for runPowerIteration's signature, not imported by name.
+ * @public
+ */
+export interface PowerIterationConfig {
+    /**
+     * 1 = L1 (sum) normalise, 2 = L2 normalise, 4 = identity (Katz: no normaliser). Never 0 or 3 here: 0 is
+     * PageRank's per-node divisor and 3 is the internal scale pass this driver issues itself.
+     */
+    readonly normMode: 1 | 2 | 4;
+    readonly adjacency: CoreBinding;
+    /**
+     * Null: every iteration pulls over `adjacency`. Non-null: the odd iterations (1, 3, ...) pull over `adjacency`
+     * and the even ones over `alternate`, so x(i) = A_alt * norm(A * norm(x(i-2))) -- one interleaved chain of HITS,
+     * whose hubs and authorities are the last iterates of the two chains (forward-first and reverse-first). The
+     * ring then has three buffers and `weights` must be null or undefined (each core's own weights).
+     */
+    readonly alternate: CoreBinding | null;
+    readonly alpha: number;
+    readonly beta: number;
+    readonly uniformP: number;
+    readonly maxIterations: number;
+    readonly tolerance: number;
+    /** undefined takes the adjacency's weights, null runs UNWEIGHTED on a weighted snapshot (T4 Step 4). */
+    readonly weights: Binding | null | undefined;
+    readonly label: string;
+    readonly signal: AbortSignal | undefined;
+    readonly onProgress: ((done: number, total: number) => void) | undefined;
+}
+
+/** The iterate, the device-recorded first converged iteration, and the number of iterations actually run. */
+export interface PowerIterationRun {
+    readonly scores: F32;
+    /** x(m - 1) on an alternating run: the chain's last iterate of the OTHER kind (hub or authority); null otherwise. */
+    readonly previous: F32 | null;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly iterationsRun: number;
+}
+
+/**
+ * Validates `options.dest` for a score result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @param algorithm - the caller's name, for the message
+ * @returns the destination as an F32, or null when none was given
+ */
+export function checkDest(dest: Float32Array | Uint32Array | undefined, n: number, algorithm: string): F32 | null {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Float32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest as F32;
+    }
+    throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `${algorithm}: dest must be a Float32Array of length ${n} over an ArrayBuffer`,
+        {
+            argument: "dest",
+            value: `${dest.constructor.name}(${dest.length})`,
+            expected: `Float32Array(${n}) over an ArrayBuffer`,
+        },
+    );
+}
+
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param algorithm - the caller's name
+ * @returns the core binding
+ */
+export function coreOf(ctx: GpuContext, s: GraphSnapshot, algorithm: string): CoreBinding {
+    try {
+        return ctx.residency.core(s);
+    } catch (error: unknown) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError(
+                "E_TOO_LARGE",
+                `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`,
+                { ...error.details, algorithm },
+            );
+        }
+        throw error;
+    }
+}
+
+/**
+ * The reverse adjacency as the CoreBinding the pull walks (the forward buffers on an undirected snapshot, PD-13).
+ * @param ctx - the context
+ * @param s - the snapshot (n > 0)
+ * @returns the reverse core
+ */
+export function reverseOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding {
+    const view = ctx.residency.view(s, "reverse");
+    return coreOfView(view, view.scalars.arcCount[0]);
+}
+
+/**
+ * The E_ABORTED error of a signal.
+ * @param algorithm - the caller's name
+ * @param batchId - the last submitted batch, when one exists
+ * @returns the error
+ */
+export function aborted(algorithm: string, batchId?: number): WebGpuGraphError {
+    return new WebGpuGraphError(
+        "E_ABORTED",
+        `${algorithm}: the signal was aborted`,
+        batchId === undefined ? {} : { batchId },
+    );
+}
+
+/**
+ * Whole-buffer binding of a scratch buffer over its first `size` bytes.
+ * @param buffer - the buffer
+ * @param size - the bound byte length
+ * @returns the binding
+ */
+function whole(buffer: GPUBuffer, size: number): Binding {
+    return { buffer, offset: 0, size, window: null };
+}
+
+/**
+ * Runs the power iteration of `config` over `n` nodes from x(0) = 1 / n, in batches of eight iterations with ONE
+ * readback per batch (the header and the iterate together), stopping at the first batch whose header records a
+ * converged iteration or at `maxIterations`. The returned iterate is RAW: the last `spmv-pull` output, which the
+ * caller normalises once on the host. The iterate travels with the header in EVERY batch, not once after the loop:
+ * whether a batch terminates the run is known only from its header, and a second readback for the iterate would
+ * be a second mapAsync (the plan's case 8 counts exactly one). The cost is 4n bytes (8n on an alternating run) of
+ * staging per batch of 8 that the loop then discards when it continues -- 40 MB per 8 iterations at 10M nodes;
+ * pagerank.ts pays the same.
+ * @param ctx - the context
+ * @param n - the node count (> 0)
+ * @param config - the recurrence, the adjacency and the run options
+ * @returns the raw iterate, the first converged iteration, whether it converged and the iterations actually run
+ */
+export async function runPowerIteration(
+    ctx: GpuContext,
+    n: number,
+    config: PowerIterationConfig,
+): Promise<PowerIterationRun> {
+    const scope = algorithmScope(ctx, config.label, RING_SLOTS);
+    try {
+        const bytes = 4 * n;
+        // x(i) lives in ring[i % ring.length]: two buffers for one pull per iteration, three for the alternating pair
+        const ring = (config.alternate === null ? ["rankA", "rankB"] : ["rankA", "rankB", "rankC"]).map((label) =>
+            whole(scope.scratch(bytes, label), bytes),
+        );
+        const xNorm = whole(scope.scratch(bytes, "xNorm"), bytes);
+        const scalePlan = plan1d(n, ctx.workgroupSize, ctx.caps);
+        const groups = groupsOf(scalePlan);
+        const partialsBytes = PR_PARTIAL.byteLength * (1 + groups);
+        const partialsBuffer = scope.scratch(partialsBytes, "partials");
+        const partials = whole(partialsBuffer, partialsBytes);
+        await ctx.allocator.check();
+        const pullOptions = { personalization: false, dangling: false, weights: config.weights, tiers: null };
+        const pulls = [{ core: config.adjacency, pull: await prepareSpmvPull(scope, config.adjacency, pullOptions) }];
+        if (config.alternate !== null) {
+            pulls.push({ core: config.alternate, pull: await prepareSpmvPull(scope, config.alternate, pullOptions) });
+        }
+        const scaleNorm = await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: config.normMode }));
+        const scaleApply =
+            config.normMode === 4 ? null : await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: 3 }));
+        const finalize = await ctx.pipelines.kernel(kernelSpec("pr-finalize", { NORM_MODE: config.normMode }));
+        const finalizePlan = plan1d(1, ctx.workgroupSize, ctx.caps);
+        const { queue } = ctx.device;
+        queue.writeBuffer(ring[0].buffer, 0, new Float32Array(n).fill(1 / n));
+        for (const slot of ring.slice(1)) {
+            queue.writeBuffer(slot.buffer, 0, new Float32Array(n));
+        }
+        const header = new ArrayBuffer(PR_PARTIAL.byteLength);
+        PR_PARTIAL.write(new DataView(header), { firstConverged: U32_MAX, iteration: 0 });
+        queue.writeBuffer(partialsBuffer, 0, header);
+        const coefficients = { alpha: config.alpha, beta: config.beta, uniformP: config.uniformP };
+        let iterationsRun = 0;
+        for (;;) {
+            const k = Math.min(BATCH, config.maxIterations - iterationsRun);
+            const batch = new CommandBatch(ctx, config.label);
+            const pass = batch.pass("iterations");
+            for (let i = 0; i < k; i++) {
+                const iteration = iterationsRun + i + 1;
+                const params = scope.params(PR_PARAMS, {
+                    n,
+                    groups,
+                    iteration,
+                    trackConvergence: 1,
+                    convergeThreshold: config.tolerance * n,
+                });
+                const rankIn = ring[(iteration - 1) % ring.length];
+                // the slot the pull overwrites still holds x(iteration - ring.length): that is rankPrev (PD-9)
+                const rankOut = ring[iteration % ring.length];
+                const { core, pull } = pulls[(iteration - 1) % pulls.length];
+                // outWeightSum takes rankIn as its dummy: storage-ro, read only under NORM_MODE 0, never compiled here
+                const scaleBindings = { rankIn, rankPrev: rankOut, outWeightSum: rankIn, xNorm, partials, P: params.binding };
+                scaleNorm.dispatch(pass, scaleNorm.bind(scaleBindings), scalePlan, [params.offset]);
+                finalize.dispatch(pass, finalize.bind({ partials, P: params.binding }), finalizePlan, [params.offset]);
+                if (scaleApply !== null) {
+                    scaleApply.dispatch(pass, scaleApply.bind(scaleBindings), scalePlan, [params.offset]);
+                }
+                pull.record(pass, core, { xNorm, rankOut, personalization: null, partials }, coefficients);
+            }
+            batch.endPass();
+            const headerRequest = batch.readback(partialsBuffer, 0, PR_PARTIAL.byteLength);
+            const scoresRequest = batch.readback(ring[(iterationsRun + k) % ring.length].buffer, 0, bytes);
+            // x(m - 1) on an alternating run: the other kind, still intact in the third ring slot
+            const previousRequest =
+                config.alternate === null
+                    ? null
+                    : batch.readback(ring[(iterationsRun + k - 1) % ring.length].buffer, 0, bytes);
+            scope.flush();
+            const submitted = batch.submit();
+            const back = await submitted.readback; // the ONE mapAsync of the batch (G7 item 5)
+            iterationsRun += k;
+            ctx.assertReady();
+            if (config.signal?.aborted === true) {
+                throw aborted(config.label, submitted.id);
+            }
+            config.onProgress?.(iterationsRun, config.maxIterations);
+            const folded = PR_PARTIAL.read(new DataView(back), headerRequest.offset);
+            const firstConverged = folded.firstConverged as number;
+            const converged = firstConverged !== U32_MAX;
+            if (converged || iterationsRun >= config.maxIterations) {
+                if (converged && iterationsRun < config.maxIterations) {
+                    config.onProgress?.(config.maxIterations, config.maxIterations);
+                }
+                return {
+                    scores: new Float32Array(back, scoresRequest.offset, n).slice(),
+                    previous: previousRequest === null ? null : new Float32Array(back, previousRequest.offset, n).slice(),
+                    iterations: converged ? firstConverged : iterationsRun,
+                    converged,
+                    iterationsRun,
+                };
+            }
+        }
+    } finally {
+        scope.dispose();
+    }
+}

package/src/algorithms/scope.ts

@@ -0,0 +1,52 @@
+/**
+ * The ReduceScope an algorithm driver hands the primitives (contract 3.11), built over a GpuContext: `scratch` comes
+ * from ONE Lease (released by `dispose()` in the algorithm's `finally`, spec 4.4) and `params` from a UniformRing
+ * slot, so a batch of k iterations writes k parameter blocks into one buffer and dispatches with dynamic offsets
+ * instead of allocating a uniform buffer per dispatch (spec 5.3). The src/ twin of the tests' testReduceScope
+ * (test/helpers/segmented-reduce.ts). `slots` sizes the ring for the LARGEST batch the caller records: reserve()
+ * wraps, so a ring too small silently reuses a slot another dispatch of the same batch still reads.
+ */
+
+import { type GpuContext } from "../context.js";
+import { UniformRing } from "../kernel/uniform-ring.js";
+import { type ReduceScope } from "../primitives/reduce.js";
+
+/** A ReduceScope over a context plus the two lifecycle calls an algorithm makes: flush() before submit, dispose() in its finally. */
+export interface AlgorithmScope extends ReduceScope {
+    /** queue.writeBuffer of the params slots written since the last flush (called before the batch is submitted). */
+    flush(): void;
+    /** Destroys the ring and releases every scratch buffer of the lease; idempotent. */
+    dispose(): void;
+}
+
+/**
+ * The scope of one algorithm call.
+ * @param ctx - the context
+ * @param label - the label prefix of the ring and every scratch buffer
+ * @param slots - the params slots of the ring: at least the parameter blocks of the largest batch recorded
+ * @returns the scope
+ */
+export function algorithmScope(ctx: GpuContext, label: string, slots: number): AlgorithmScope {
+    const lease = ctx.pool.lease();
+    const ring = new UniformRing(ctx.device, ctx.allocator, slots, `${label}/ring`);
+    return {
+        device: ctx.device,
+        caps: ctx.caps,
+        pipelines: ctx.pipelines,
+        pool: ctx.pool,
+        workgroupSize: ctx.workgroupSize,
+        scratch: (byteLength, scratchLabel) => lease.storage(byteLength, `${label}/${scratchLabel}`),
+        params(block, values) {
+            const slot = ring.reserve(1);
+            ring.write(slot, block, values);
+            return { binding: ring.binding(block), offset: ring.offsetOf(slot) };
+        },
+        flush: () => {
+            ring.flush();
+        },
+        dispose(): void {
+            ring.destroy();
+            lease.release();
+        },
+    };
+}