@graphty/webgpu-graph-algorithms 0.6.15 → 0.6.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "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,7 +61,7 @@
   "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.2"
+    "@graphty/graph-format": "^1.2.3"
   },
   "peerDependencies": {
     "@graphty/algorithms": "^1.0.0 || ^2.0.0 || ^3.0.0",
@@ -95,8 +95,8 @@
     "vite": "^7.0.5",
     "vitest": "4.1.11",
     "webgpu": "0.4.0",
-    "@graphty/layout": "^2.0.2",
-    "@graphty/algorithms": "^3.0.0"
+    "@graphty/algorithms": "^3.1.1",
+    "@graphty/layout": "^2.0.3"
   },
   "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,15 +17,19 @@
 
 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";
@@ -34,6 +39,7 @@ import {
     type BfsOptions,
     type ClosenessAcceleratorOptions,
     type GpuAccelerator,
+    type HitsOptionsLike,
     type SsspOptions,
 } from "./types/accelerator.js";
 import {
@@ -48,6 +54,7 @@ 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,
@@ -61,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. */
@@ -357,6 +365,53 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
             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, {});
+}

package/src/algorithms/components.ts

@@ -92,12 +92,12 @@ function bindingOf(buffer: GPUBuffer, size: number): Binding {
 
 /**
  * The result object over a label array whose labels are all `< n`: `count` blocks, `groups()` built lazily once in
- * first-seen label order (which for renumbered labels is index order).
+ * first-seen label order (which for renumbered labels is index order). Shared with label propagation.
  * @param labels - the labels
  * @param count - the block count
  * @returns the result
  */
-function labelResult(labels: U32, count: number): GpuLabelResult {
+export function labelResult(labels: U32, count: number): GpuLabelResult {
     let groups: U32[] | null = null;
     return {
         labels,

package/src/algorithms/label-propagation.ts

@@ -0,0 +1,280 @@
+/**
+ * Label propagation (design 8.6, 3.3 line 807; the P11 plan's P11-T6) over the simple symmetric graph of the
+ * snapshot (`buildSimpleSymmetric`). Every vertex starts with its own index as its label; each pass,
+ * `group-by-key-row` finds every vertex's weighted mode of its neighbours' labels (the lowest label on a tie) and
+ * `lpa-step` adopts it synchronously -- but only in the pass's direction: down to a lower label on even passes, up to
+ * a higher one on odd passes (cuGraph's swap-avoidance rule), which is what stops two neighbours trading labels
+ * forever. A pass that moves nothing in either direction after one that moved nothing in the other is a fixed point,
+ * and the run stops there or at `maxIterations` passes.
+ *
+ * Passes are recorded LABEL_PROP_PASSES_PER_SUBMIT to a submit with one readback of their move counts, because a
+ * readback per pass costs more than the passes on a small graph; the passes after the fixed point inside the last
+ * submit change nothing, so the labels are those of the fixed point. The first submit is the graph build's second.
+ * The labels are renumbered in first-seen order on the host (`renumberPartition`), as connected components' are.
+ *
+ * The result is bitwise reproducible on one device and between devices: the grouping is order-independent and every
+ * sum is an integer.
+ */
+
+import { type GraphSnapshot, renumberPartition, type U32 } from "@graphty/graph-format";
+
+import { LABEL_PROP_PASSES_PER_SUBMIT } from "../constants.js";
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { FILL_PARAMS, kernelSpec, LPA_PARAMS } from "../kernels.js";
+import { planGroupRows, prepareGroupByKeyRow } from "../primitives/group-by-key.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { type GpuLabelResult } from "../types/algorithms.js";
+import { type LabelPropagationOptions } from "../types/community.js";
+import { type Binding } from "../types/memory.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { labelResult } from "./components.js";
+import { algorithmScope } from "./scope.js";
+import { assertBindable, assertBuildSorted, buildSimpleSymmetric } from "./simple-symmetric.js";
+
+const ALGORITHM = "labelPropagation";
+/** The default pass cap, as in `@graphty/algorithms`' labelPropagation. */
+const DEFAULT_MAX_ITERATIONS = 100;
+/** Params slots of the largest batch: the graph build's second submit plus one batch of passes. */
+const RING_SLOTS = 1024;
+
+/**
+ * Validates `options.dest` for a label result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @returns the destination as a U32, or null when none was given
+ */
+function checkDest(dest: Float32Array | Uint32Array | undefined, n: number): U32 | null {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Uint32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest as U32;
+    }
+    throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `${ALGORITHM}: dest must be a Uint32Array of length ${n} over an ArrayBuffer`,
+        {
+            argument: "dest",
+            value: `${dest.constructor.name}(${dest.length})`,
+            expected: `Uint32Array(${n}) over an ArrayBuffer`,
+        },
+    );
+}
+
+/**
+ * The pass cap.
+ * @param value - options.maxIterations
+ * @returns the cap
+ */
+function maxIterationsOf(value: number | undefined): number {
+    if (value === undefined) {
+        return DEFAULT_MAX_ITERATIONS;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${ALGORITHM}: maxIterations must be a non-negative integer`, {
+            argument: "maxIterations",
+            value,
+            expected: "a non-negative integer",
+        });
+    }
+    return value;
+}
+
+/**
+ * An upper bound of every vertex's number of distinct neighbours in the simple symmetric graph: its arcs in both
+ * directions, which the merge of parallel edges and the drop of self-loops can only shrink.
+ * @param s - the snapshot
+ * @returns one bound per vertex
+ */
+function neighbourBound(s: GraphSnapshot): Uint32Array {
+    const out = s.outDegree();
+    if (!s.directed) {
+        return out;
+    }
+    const inDegree = s.inDegree();
+    const bound = new Uint32Array(s.nodeCount);
+    for (let v = 0; v < bound.length; v++) {
+        bound[v] = out[v] + inDegree[v];
+    }
+    return bound;
+}
+
+/**
+ * The labels as a result: every label must be a node index (a device bug otherwise), then renumbered first-seen.
+ * @param raw - the labels the device produced
+ * @param dest - the caller's destination, if any
+ * @returns the result
+ */
+function resultOf(raw: U32, dest: U32 | null): GpuLabelResult {
+    const n = raw.length;
+    for (let v = 0; v < n; v++) {
+        if (raw[v] >= n) {
+            throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: labels[${v}] = ${raw[v]} is not a node index`, {
+                label: `${ALGORITHM}/labels`,
+                message: `the device produced a label outside [0, ${n})`,
+            });
+        }
+    }
+    const { labels, count } = renumberPartition(raw, dest ?? undefined);
+    return labelResult(labels, count);
+}
+
+/**
+ * The identity labelling: every vertex its own community.
+ * @param n - the node count
+ * @param dest - the caller's destination, if any
+ * @returns the result
+ */
+function identityResult(n: number, dest: U32 | null): GpuLabelResult {
+    const labels = dest ?? new Uint32Array(n);
+    for (let v = 0; v < n; v++) {
+        labels[v] = v;
+    }
+    return labelResult(labels, n);
+}
+
+/**
+ * Label propagation on the device (see the file header).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (its edge list is uploaded through ctx.residency, or found there)
+ * @param options - maxIterations (default 100), weighted (default true), plus dest / signal / onProgress
+ * @returns the labels, dense in first-seen order, the community count and groups()
+ */
+export async function labelPropagation(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: LabelPropagationOptions & GpuRunOptions,
+): Promise<GpuLabelResult> {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    const n = s.nodeCount;
+    const dest = checkDest(options?.dest, n);
+    const maxIterations = maxIterationsOf(options?.maxIterations);
+    const weighted = options?.weighted !== false;
+    if (options?.signal?.aborted) {
+        throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted before any work started`, {});
+    }
+    if (n === 0 || s.edgeCount === 0 || maxIterations === 0) {
+        options?.onProgress?.(1, 1);
+        return identityResult(n, dest);
+    }
+    // the hash region of the workgroup tier is bound whole: refuse a graph it outgrows before any device work
+    const plan = planGroupRows(neighbourBound(s));
+    assertBindable(ctx, 4 * plan.regionWords, "the group-by hash region", ALGORITHM);
+    const scope = algorithmScope(ctx, ALGORITHM, RING_SLOTS);
+    try {
+        const build = await buildSimpleSymmetric(ctx, s, scope, weighted, ALGORITHM);
+        const { graph } = build;
+        if (graph.colIdx === null) {
+            // only self-loops: no vertex has a neighbour, so nothing ever moves
+            scope.flush();
+            const bytes = await build.batch.submit().readback;
+            ctx.assertReady();
+            assertBuildSorted(bytes, build, ALGORITHM);
+            options?.onProgress?.(1, 1);
+            return identityResult(n, dest);
+        }
+        const wg = ctx.workgroupSize;
+        const words = (count: number, label: string): Binding => {
+            const size = 4 * Math.max(1, count);
+            return { buffer: scope.scratch(size, label), offset: 0, size, window: null };
+        };
+        const rows = words(plan.words.length, "rows");
+        const region = words(plan.regionWords, "hashRegion");
+        const labelsA = words(n, "labelsA");
+        const labelsB = words(n, "labelsB");
+        const bestKey = words(n, "bestKey");
+        const bestScore = words(n, "bestScore");
+        const counters = words(LABEL_PROP_PASSES_PER_SUBMIT, "counters");
+        await ctx.allocator.check();
+        const { queue } = ctx.device;
+        queue.writeBuffer(rows.buffer, 0, plan.words);
+        queue.writeBuffer(region.buffer, 0, new Uint32Array(1));
+        const groupBy = await prepareGroupByKeyRow(scope);
+        const step = await ctx.pipelines.kernel(kernelSpec("lpa-step"));
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+        const nodePlan = plan1d(n, wg, ctx.caps);
+
+        let { batch } = build;
+        let first = true;
+        let cur = labelsA;
+        let next = labelsB;
+        let done = 0;
+        let previousLast = -1;
+        for (;;) {
+            const k = Math.min(LABEL_PROP_PASSES_PER_SUBMIT, maxIterations - done);
+            queue.writeBuffer(counters.buffer, 0, new Uint32Array(k));
+            const pass = batch.pass("passes");
+            if (first) {
+                const iota = scope.params(FILL_PARAMS, { count: n, value: 0, mode: 1, pad0: 0 });
+                fill.dispatch(pass, fill.bind({ dst: labelsA, P: iota.binding }), nodePlan, [iota.offset]);
+            }
+            for (let i = 0; i < k; i++) {
+                groupBy.record(pass, {
+                    rowPtr: graph.rowPtr,
+                    colIdx: graph.colIdx,
+                    weights: weighted ? graph.weights : null,
+                    keyIn: cur,
+                    plan,
+                    rows,
+                    hashRegion: region,
+                    bestKey,
+                    bestScore,
+                });
+                const params = scope.params(LPA_PARAMS, {
+                    n,
+                    direction: (done + i) % 2,
+                    counterIndex: i,
+                    pad0: 0,
+                });
+                step.dispatch(
+                    pass,
+                    step.bind({ labelsIn: cur, bestKey, labelsOut: next, counters, P: params.binding }),
+                    nodePlan,
+                    [params.offset],
+                );
+                [cur, next] = [next, cur];
+            }
+            batch.endPass();
+            const movesRequest = batch.readback(counters.buffer, 0, 4 * k);
+            const exhaustedRequest = batch.readback(region.buffer, 0, 4);
+            scope.flush();
+            const submitted = batch.submit();
+            const bytes = await submitted.readback;
+            ctx.assertReady();
+            if (first) {
+                assertBuildSorted(bytes, build, ALGORITHM);
+                first = false;
+            }
+            if (new Uint32Array(bytes, exhaustedRequest.offset, 1)[0] !== 0) {
+                throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: a hash probe exhausted its bound`, {
+                    label: `${ALGORITHM}/group-by-key`,
+                    message: "a compare-exchange loop of the workgroup tier ran out of steps",
+                });
+            }
+            const moves = new Uint32Array(bytes, movesRequest.offset, k);
+            done += k;
+            const lastTwo = k >= 2 ? moves[k - 2] + moves[k - 1] : previousLast + moves[0];
+            previousLast = moves[k - 1];
+            if (options?.signal?.aborted) {
+                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, {
+                    batchId: submitted.id,
+                });
+            }
+            options?.onProgress?.(done, maxIterations);
+            if (lastTwo === 0 || done >= maxIterations) {
+                break;
+            }
+            batch = new CommandBatch(ctx, `${ALGORITHM}/passes`);
+        }
+        const raw = new Uint32Array(n);
+        await ctx.readback.read(cur.buffer, 4 * n, raw);
+        ctx.assertReady();
+        return resultOf(raw, dest);
+    } finally {
+        scope.dispose();
+    }
+}