@graphty/webgpu-graph-algorithms 0.6.14 → 0.6.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -61,10 +61,10 @@
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/webgpu-graph-algorithms#readme",
   "dependencies": {
     "@webgpu/types": "^0.1.72",
-    "@graphty/graph-format": "^1.2.1"
+    "@graphty/graph-format": "^1.2.2"
   },
   "peerDependencies": {
-    "@graphty/algorithms": "^1.0.0 || ^2.0.0",
+    "@graphty/algorithms": "^1.0.0 || ^2.0.0 || ^3.0.0",
     "@graphty/graph-format": "^1.0.0",
     "@graphty/layout": "^1.7.0 || ^2.0.0",
     "webgpu": ">=0.4.0 <1.0.0"
@@ -95,8 +95,8 @@
     "vite": "^7.0.5",
     "vitest": "4.1.11",
     "webgpu": "0.4.0",
-    "@graphty/layout": "^2.0.1",
-    "@graphty/algorithms": "^2.2.1"
+    "@graphty/layout": "^2.0.2",
+    "@graphty/algorithms": "^3.1.0"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",

package/src/accelerator.ts

@@ -7,7 +7,8 @@
  * P5's `fruchtermanReingold` and `springElectrical` (the two other layout members of spec 9.3, landed together once
  * both models were green, P5 PD-19), P7's seven algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and P8's four
  * traversal members (spec 8.4; P8-T13 PD-16, PD-19: `breadthFirstSearch`, `sssp`, `bellmanFord`,
- * `closenessCentrality`, each taking the seam's own option type) and nothing else: the CPU-side dispatchers
+ * `closenessCentrality`, each taking the seam's own option type), `allPairsShortestPath` (design 8.7), P11's
+ * `triangleCount` and `labelPropagation`, and nothing else: the CPU-side dispatchers
  * (`accelerated()`, `createSimulation()`) test `acc.betweennessCentrality !== undefined` /
  * `acc.fruchtermanReingold !== undefined` and route to the CPU when the member is absent (spec 2.4 row "method
  * missing"), so a method the GPU does not implement must not exist here -- never a throwing stub. The remaining
@@ -16,20 +17,27 @@
 
 import { type F32, type F64, type GraphSnapshot } from "@graphty/graph-format";
 
+import { allPairsShortestPath } from "./algorithms/all-pairs.js";
 import { bellmanFord } from "./algorithms/bellman-ford.js";
+import { betweennessCentrality, edgeBetweennessCentrality } from "./algorithms/betweenness.js";
 import { breadthFirstSearch } from "./algorithms/bfs.js";
 import { closenessCentrality } from "./algorithms/closeness.js";
 import { connectedComponents } from "./algorithms/components.js";
+import { labelPropagation } from "./algorithms/label-propagation.js";
 import { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 import { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 import { sssp } from "./algorithms/sssp.js";
+import { triangleCount } from "./algorithms/triangles.js";
 import { type GpuContext } from "./context.js";
+import { WebGpuGraphError } from "./errors.js";
 import { createForceAtlas2 } from "./layouts/forceatlas2.js";
 import { createFruchtermanReingold } from "./layouts/fruchterman-reingold.js";
 import { createSpringElectrical } from "./layouts/spring-electrical.js";
 import {
     type AcceleratorOptions,
+    type BetweennessAcceleratorOptions,
     type BfsOptions,
+    type ClosenessAcceleratorOptions,
     type GpuAccelerator,
     type HitsOptionsLike,
     type SsspOptions,
@@ -37,6 +45,7 @@ import {
 import {
     type ComponentsOptions,
     type EigenvectorOptions,
+    type GpuClosenessResult,
     type GpuHitsResult,
     type GpuLabelResult,
     type GpuPageRankResult,
@@ -45,6 +54,8 @@ import {
     type KatzOptions,
     type PageRankOptions,
 } from "./types/algorithms.js";
+import { type GpuApspResult } from "./types/all-pairs.js";
+import { type GpuBetweennessResult, type GpuEdgeScoresResult } from "./types/betweenness.js";
 import {
     type ForceAtlas2Stats,
     type FruchtermanReingoldStats,
@@ -57,6 +68,7 @@ import {
     type FruchtermanReingoldOptions,
     type SpringElectricalOptions,
 } from "./types/options.js";
+import { type GpuTriangleResult } from "./types/structure.js";
 import { type GpuBellmanFordResult, type GpuBfsResult, type GpuSsspResult } from "./types/traversal.js";
 
 /** The `algorithms` record of AcceleratorOptions (spec 3.3), named for the copy helpers. */
@@ -79,6 +91,30 @@ function copyBetweenness(defaults: BetweennessDefaults): BetweennessDefaults {
     return Object.freeze(copy);
 }
 
+/**
+ * A betweenness call's options with the accelerator's `algorithms.betweenness` defaults applied: the defaults supply
+ * `sources` / `k` only when the call names neither, so a call's own sampling always wins whole. The defaults serve
+ * graphs of every size, so they are fitted to this one: a default `sources` list keeps only the indices below
+ * `nodeCount` (and then wins over a default `k`), and a default `k` of `nodeCount` or more runs every vertex.
+ * @param defaults - the frozen defaults, if any
+ * @param options - the call's options
+ * @param nodeCount - the snapshot's vertex count
+ * @returns the options the driver runs with
+ */
+function withBetweennessDefaults(
+    defaults: BetweennessDefaults | undefined,
+    options: BetweennessAcceleratorOptions | undefined,
+    nodeCount: number,
+): BetweennessAcceleratorOptions | undefined {
+    if (defaults === undefined || options?.sources !== undefined || options?.k !== undefined) {
+        return options;
+    }
+    if (defaults.sources !== undefined) {
+        return { ...options, sources: defaults.sources.filter((v) => v < nodeCount) };
+    }
+    return { ...options, k: defaults.k !== undefined && defaults.k < nodeCount ? defaults.k : undefined };
+}
+
 /**
  * Frozen copy of the algorithms record, one level deeper for `betweenness`.
  * @param algorithms - the caller's record
@@ -118,8 +154,9 @@ function freezeOptions(options: AcceleratorOptions | undefined): Readonly<Accele
  * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
  * structurally; P3's forceAtlas2, release and dispose, P5's fruchtermanReingold and springElectrical (the same
  * `{ ...o, ...options.layout }` shape as forceAtlas2) plus P7's seven algorithm members and P8's four traversal
- * members, each a delegation to its algorithm with `ctx.assertReady()` first. The accelerator's algorithm defaults are not consulted by any of
- * them: only `betweenness` has any, and it belongs to P9. One per call (the app creates one and injects
+ * members and the two betweenness members, each a delegation to its algorithm with `ctx.assertReady()` first. Only
+ * the betweenness members consult the accelerator's algorithm defaults (`algorithms.betweenness` supplies `sources` /
+ * `k` when a call names neither). One per call (the app creates one and injects
  * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
  * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
  * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
@@ -163,7 +200,9 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
          * @param o - the CPU option type (spec 9.3 SpringElectricalOptions, ngraph's names)
          * @returns a fresh simulation in state "created"
          */
-        springElectrical(o?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats> {
+        springElectrical(
+            o?: SpringElectricalOptions,
+        ): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats> {
             ctx.assertReady();
             return createSpringElectrical(ctx, { ...o, ...frozen.layout });
         },
@@ -278,17 +317,101 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
             ctx.assertReady();
             return await bellmanFord(ctx, gs, source, o);
         },
+        /**
+         * Betweenness centrality on the device (spec 8.4): exact, or sampled through `sources` / `k` (the call's own,
+         * else the accelerator's `algorithms.betweenness` defaults), the unscaled sum over the sources run.
+         * `endpoints: true` is refused.
+         * @param gs - the snapshot
+         * @param o - the seam's `BetweennessAcceleratorOptions`
+         * @returns the f32 scores with `sourcesUsed` and `sigmaOverflow`
+         */
+        async betweennessCentrality(
+            gs: GraphSnapshot,
+            o?: BetweennessAcceleratorOptions,
+        ): Promise<GpuBetweennessResult> {
+            ctx.assertReady();
+            return await betweennessCentrality(
+                ctx,
+                gs,
+                withBetweennessDefaults(frozen.algorithms?.betweenness, o, gs.nodeCount),
+            );
+        },
+        /**
+         * Edge betweenness on the device (spec 8.4): one score per edge, arcs summed and halved when undirected; sampling
+         * and defaults as `betweennessCentrality`.
+         * @param gs - the snapshot
+         * @param o - the seam's `BetweennessAcceleratorOptions`
+         * @returns the f32 per-edge scores with `sourcesUsed` and `sigmaOverflow`
+         */
+        async edgeBetweennessCentrality(
+            gs: GraphSnapshot,
+            o?: BetweennessAcceleratorOptions,
+        ): Promise<GpuEdgeScoresResult> {
+            ctx.assertReady();
+            return await edgeBetweennessCentrality(
+                ctx,
+                gs,
+                withBetweennessDefaults(frozen.algorithms?.betweenness, o, gs.nodeCount),
+            );
+        },
         /**
          * Closeness centrality on the device (spec 8.4; P8-T13): the bit-parallel multi-source sweep, or one `sssp`
          * per source when `weighted`. `maxIterations` / `tolerance` are refused when defined (P8 PD-25).
          * @param gs - the snapshot
-         * @param o - the seam's placeholder `HitsOptionsLike` (`weighted`)
-         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         * @param o - `weighted`, and a sampled run's `sources` (undirected snapshots only)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7) and `sourcesUsed`
          */
-        async closenessCentrality(gs: GraphSnapshot, o?: HitsOptionsLike): Promise<GpuScoresResult> {
+        async closenessCentrality(gs: GraphSnapshot, o?: ClosenessAcceleratorOptions): Promise<GpuClosenessResult> {
             ctx.assertReady();
             return await closenessCentrality(ctx, gs, o);
         },
+        /**
+         * All-pairs shortest paths on the device (design 8.7): blocked Floyd-Warshall, `E_TOO_LARGE` above the device's
+         * storage-binding ceiling. The seam passes `SsspOptions`; neither of its keys has an all-pairs meaning, so a
+         * defined `cutoff` (it would change what `+Infinity` means) or `weights` (a per-arc override is a different
+         * matrix from the snapshot's resident column) is `E_UNSUPPORTED { option }`, never silently dropped.
+         * @param gs - the snapshot
+         * @param o - the seam's `SsspOptions`; both keys refused when defined
+         * @returns the row-major `n x n` distances and `n` (spec 3.3 line 835)
+         */
+        async allPairsShortestPath(gs: GraphSnapshot, o?: SsspOptions): Promise<GpuApspResult> {
+            ctx.assertReady();
+            for (const key of ["cutoff", "weights"] as const) {
+                if (o?.[key] !== undefined) {
+                    throw new WebGpuGraphError("E_UNSUPPORTED", `allPairsShortestPath: ${key} is not supported`, {
+                        option: key,
+                        hint: "all-pairs shortest paths runs over the snapshot's own weights with no cutoff",
+                    });
+                }
+            }
+            return await allPairsShortestPath(ctx, gs);
+        },
+        /**
+         * Triangle counting with the clustering coefficient and the transitivity (design 8.5; P11).
+         * @param gs - the snapshot
+         * @returns perNode, total, coefficient and transitivity
+         */
+        async triangleCount(gs: GraphSnapshot): Promise<GpuTriangleResult> {
+            ctx.assertReady();
+            return await triangleCount(ctx, gs);
+        },
+        /**
+         * Label propagation (design 8.6; P11): `maxIterations` and `weighted` are honoured, `tolerance` is refused when
+         * defined (a label propagation stops at a fixed point, not below a tolerance).
+         * @param gs - the snapshot
+         * @param o - the seam's placeholder `HitsOptionsLike`
+         * @returns the labels dense in first-seen order, the community count and groups()
+         */
+        async labelPropagation(gs: GraphSnapshot, o?: HitsOptionsLike): Promise<GpuLabelResult> {
+            ctx.assertReady();
+            if (o?.tolerance !== undefined) {
+                throw new WebGpuGraphError("E_UNSUPPORTED", "labelPropagation: tolerance has no meaning here", {
+                    option: "tolerance",
+                    hint: "label propagation stops at a fixed point or after maxIterations passes",
+                });
+            }
+            return await labelPropagation(ctx, gs, { maxIterations: o?.maxIterations, weighted: o?.weighted });
+        },
         /**
          * Destroys every device buffer recorded for the snapshot (spec 4.5); delegates to ctx.release.
          * @param s - the snapshot the app is done with

package/src/algorithms/all-pairs.ts

@@ -0,0 +1,228 @@
+/**
+ * All-pairs shortest paths on the device (design 8.7, 3.3 lines 813 and 835, 9.7): blocked Floyd-Warshall over
+ * `APSP_TILE x APSP_TILE` tiles of ONE `n x n` f32 matrix. `fill` sets the matrix to `+Infinity`, `apsp-init` writes
+ * the arcs (the cheapest of parallel arcs) and the diagonal zero, then `B = ceil(n / APSP_TILE)` rounds each run the
+ * three `apsp-fw` phases in order: the pivot block, the pivot row and column, everything else. The whole sweep --
+ * `3 B` dispatches -- is recorded into ONE compute pass: WebGPU runs the dispatches of a pass in order and makes each
+ * one's writes visible to the next, so nothing is read back until the matrix is done. Above
+ * `APSP_MAX_DISPATCHES_PER_SUBMIT` dispatches the sweep is split into further submits and `signal` is checked
+ * between them -- but no binding WebGPU devices offer today reaches that (a 4 GiB binding is 32,767 nodes, 3,072
+ * dispatches), so in practice the sweep is one submit: `signal` is checked before it and after it, never during,
+ * and `onProgress` fires once. The result is bitwise reproducible (no atomics, and a cell is only ever written by one
+ * lane per dispatch), exact for hop counts, and the minimum of f32 path sums for weights.
+ *
+ * The ceiling: the matrix is exactly `n * n` (never padded to the tile) and is bound as ONE storage binding, so
+ * `n <= floor(sqrt(limit / 4))` with `limit` the smaller of the device's `maxStorageBufferBindingSize` and
+ * `maxBufferSize`. A context's default `limits: "raise"` takes the adapter's own limits: 23,170 nodes on a hardware
+ * adapter under Dawn (a 2 GiB binding), 5,792 on lavapipe or under `limits: "default"` (the 128 MiB spec default).
+ * Above it the call throws `E_TOO_LARGE` naming the node count, the ceiling, the limit it read and
+ * `GpuContextOptions.limits` as the way to raise it; the rows are never windowed. Refused before any device work: a negative weight (`E_UNSUPPORTED
+ * allPairs.negativeWeights` -- Floyd-Warshall's in-place tile update is race-free only while the diagonal stays 0)
+ * and a NaN or infinite one (`allPairs.nonFiniteWeights`). `weighted` defaults to "the snapshot has weights";
+ * `weighted: false` on a weighted snapshot computes hop counts. The empty graph returns an empty matrix without a
+ * dispatch. `allPairsWithTuning` is what the tests drive; nothing public exposes it.
+ */
+
+import { type GraphSnapshot } from "@graphty/graph-format";
+
+import { APSP_MAX_DISPATCHES_PER_SUBMIT, APSP_TILE, F32_INF_BITS } from "../constants.js";
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d, plan2d } from "../kernel/dispatch.js";
+import { APSP_PARAMS, FILL_PARAMS, graphBindings, graphOverrides, kernelSpec } from "../kernels.js";
+import { assertWholeCore } from "../primitives/core-shape.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { type ApspOptions, type GpuApspResult } from "../types/all-pairs.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { algorithmScope } from "./scope.js";
+import { aborted, bindingOf, checkDest } from "./sssp.js";
+
+const ALGORITHM = "allPairsShortestPath";
+
+/** The rounds one submit holds by default: three dispatches per round. */
+const DEFAULT_ROUNDS_PER_SUBMIT = Math.floor(APSP_MAX_DISPATCHES_PER_SUBMIT / 3);
+
+/**
+ * The knobs the tests need and nothing public offers.
+ * @internal
+ */
+export interface AllPairsTuning {
+    /** Rounds recorded per submit (default `floor(APSP_MAX_DISPATCHES_PER_SUBMIT / 3)`); 1 submits every round alone. */
+    readonly roundsPerSubmit?: number | undefined;
+}
+
+/**
+ * The largest node count whose `n x n` f32 matrix fits the device (design 8.7): `floor(sqrt(limit / 4))` over the
+ * smaller of `maxStorageBufferBindingSize` and `maxBufferSize`, corrected so the float square root can never
+ * overshoot by one.
+ * @internal
+ * @param limits - the device limits
+ * @returns the ceiling and the limit that set it
+ */
+export function allPairsCeiling(limits: Pick<GPUSupportedLimits, "maxStorageBufferBindingSize" | "maxBufferSize">): {
+    readonly maxNodes: number;
+    readonly limit: number;
+    readonly limitName: "maxStorageBufferBindingSize" | "maxBufferSize";
+} {
+    const binding = limits.maxStorageBufferBindingSize;
+    const bufferSize = limits.maxBufferSize;
+    const limitName = bufferSize < binding ? "maxBufferSize" : "maxStorageBufferBindingSize";
+    const limit = Math.min(binding, bufferSize);
+    let maxNodes = Math.floor(Math.sqrt(limit / 4));
+    while (4 * maxNodes * maxNodes > limit) {
+        maxNodes -= 1;
+    }
+    while (4 * (maxNodes + 1) * (maxNodes + 1) <= limit) {
+        maxNodes += 1;
+    }
+    return { maxNodes, limit, limitName };
+}
+
+/**
+ * All-pairs shortest paths with the test knobs; `allPairsShortestPath` is this with an empty tuning.
+ * @internal
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - `weighted`, plus dest (a Float32Array of length n * n) / signal / onProgress (rounds done of `ceil(n / 32)`)
+ * @param tuning - the knobs
+ * @returns the row-major `n x n` distances and `n`
+ */
+export async function allPairsWithTuning(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options: (ApspOptions & GpuRunOptions) | undefined,
+    tuning: AllPairsTuning,
+): Promise<GpuApspResult> {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const roundsPerSubmit = tuning.roundsPerSubmit ?? DEFAULT_ROUNDS_PER_SUBMIT;
+    if (!Number.isInteger(roundsPerSubmit) || roundsPerSubmit < 1 || roundsPerSubmit > DEFAULT_ROUNDS_PER_SUBMIT) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `${ALGORITHM}: roundsPerSubmit must be an integer in [1, ${DEFAULT_ROUNDS_PER_SUBMIT}]`,
+            {
+                argument: "roundsPerSubmit",
+                value: roundsPerSubmit,
+                expected: `an integer in [1, ${DEFAULT_ROUNDS_PER_SUBMIT}]`,
+            },
+        );
+    }
+    const { maxNodes, limit, limitName } = allPairsCeiling(ctx.caps.limits);
+    if (n > maxNodes) {
+        throw new WebGpuGraphError(
+            "E_TOO_LARGE",
+            `${ALGORITHM}: ${n} nodes need a ${4 * n * n}-byte distance matrix in one storage binding; this device's ${limitName} of ${limit} bytes holds at most ${maxNodes} nodes -- raise it through GpuContextOptions.limits`,
+            {
+                needed: 4 * n * n,
+                limit,
+                path: "allPairs.matrix",
+                algorithm: ALGORITHM,
+                nodes: n,
+                maxNodes,
+                limitName,
+                hint: `raise ${limitName} through GpuContextOptions.limits`,
+            },
+        );
+    }
+    const dist = checkDest(ALGORITHM, options?.dest, n * n) ?? new Float32Array(n * n);
+    const weighted = (options?.weighted ?? s.weights !== null) && s.weights !== null && !s.flags.allWeightsOne;
+    if (weighted && !s.flags.nonNegativeWeights) {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: a negative weight is not supported`, {
+            feature: "allPairs.negativeWeights",
+            hint: "the blocked Floyd-Warshall sweep needs non-negative weights; pass weighted: false for hop counts",
+        });
+    }
+    if (weighted && !s.flags.finiteWeights) {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: a NaN or infinite weight has no shortest path`, {
+            feature: "allPairs.nonFiniteWeights",
+        });
+    }
+    if (options?.signal?.aborted) {
+        throw aborted(ALGORITHM);
+    }
+    if (n === 0) {
+        return { dist, n };
+    }
+    await assertDeviceComputes(ctx);
+    const core = ctx.residency.core(s);
+    assertWholeCore(core, s.arcCount, ctx.caps.limits.maxStorageBufferBindingSize, ALGORITHM);
+    const blocks = Math.ceil(n / APSP_TILE);
+    const scope = algorithmScope(ctx, ALGORITHM, Math.min(roundsPerSubmit, blocks) + 2);
+    try {
+        const wg = ctx.workgroupSize;
+        const bytes = 4 * n * n;
+        const matrix = bindingOf(scope.scratch(bytes, "dist"), bytes);
+        await ctx.allocator.check();
+        const weightsBinding = weighted ? undefined : null;
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+        const init = await ctx.pipelines.kernel(kernelSpec("apsp-init", graphOverrides(core, null, weightsBinding)));
+        const phases = await Promise.all(
+            [0, 1, 2].map((phase) => ctx.pipelines.kernel(kernelSpec("apsp-fw", { PHASE: phase }))),
+        );
+        const graph = graphBindings(core, null, weightsBinding);
+        const others = blocks - 1;
+        const phasePlans = [plan2d(1, ctx.caps), plan2d(2 * others, ctx.caps), plan2d(others * others, ctx.caps)];
+
+        for (let first = 0; first < blocks; first += roundsPerSubmit) {
+            const batch = new CommandBatch(ctx, `${ALGORITHM}/sweep`);
+            const pass = batch.pass("apsp");
+            if (first === 0) {
+                const fillParams = scope.params(FILL_PARAMS, { count: n * n, value: F32_INF_BITS, mode: 0, pad0: 0 });
+                fill.dispatch(pass, fill.bind({ dst: matrix, P: fillParams.binding }), plan1d(n * n, wg, ctx.caps), [
+                    fillParams.offset,
+                ]);
+                const initParams = scope.params(APSP_PARAMS, { n, round: 0, blocks, infBits: F32_INF_BITS });
+                init.dispatch(
+                    pass,
+                    init.bind({ ...graph, dist: matrix, P: initParams.binding }),
+                    plan1d(n, wg, ctx.caps),
+                    [initParams.offset],
+                );
+            }
+            const last = Math.min(first + roundsPerSubmit, blocks);
+            for (let round = first; round < last; round++) {
+                const params = scope.params(APSP_PARAMS, { n, round, blocks, infBits: F32_INF_BITS });
+                for (let phase = 0; phase < 3; phase++) {
+                    const kernel = phases[phase];
+                    kernel.dispatch(pass, kernel.bind({ dist: matrix, P: params.binding }), phasePlans[phase], [
+                        params.offset,
+                    ]);
+                }
+            }
+            batch.endPass();
+            scope.flush();
+            const submitted = batch.submit();
+            await submitted.readback;
+            ctx.assertReady();
+            options?.onProgress?.(last, blocks);
+            if (options?.signal?.aborted) {
+                throw aborted(ALGORITHM, submitted.id);
+            }
+        }
+        await ctx.readback.read(matrix.buffer, bytes, dist);
+        ctx.assertReady();
+        return { dist, n };
+    } finally {
+        scope.dispose();
+    }
+}
+
+/**
+ * All-pairs shortest paths on the device (design 8.7, 3.3 line 813): blocked Floyd-Warshall over 32 x 32 tiles of one
+ * `n x n` f32 matrix. `dist[i * n + j]` is the distance from `i` to `j`, `+Infinity` when unreachable, `0` on the
+ * diagonal. `E_TOO_LARGE` above `floor(sqrt(maxStorageBufferBindingSize / 4))` nodes (23,170 at a 2 GiB binding, the
+ * usual hardware adapter under the context's default `limits: "raise"`; 5,792 at the 128 MiB spec default);
+ * `E_UNSUPPORTED` for a negative or non-finite weight unless `weighted: false`.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - `weighted` (default: the snapshot has weights), plus dest (a Float32Array of length n * n) / signal / onProgress
+ * @returns the row-major `n x n` distances and `n`
+ */
+export function allPairsShortestPath(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: ApspOptions & GpuRunOptions,
+): Promise<GpuApspResult> {
+    return allPairsWithTuning(ctx, s, options, {});
+}