@graphty/webgpu-graph-algorithms 0.6.21 → 0.6.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "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",
@@ -95,8 +95,8 @@
     "vite": "^7.0.5",
     "vitest": "4.1.11",
     "webgpu": "0.4.0",
-    "@graphty/algorithms": "^3.1.5",
-    "@graphty/layout": "^2.0.6"
+    "@graphty/layout": "^2.0.6",
+    "@graphty/algorithms": "^3.1.6"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",

package/src/accelerator.ts

@@ -8,7 +8,7 @@
  * 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), `allPairsShortestPath` (design 8.7), P11's
- * `triangleCount` and `labelPropagation`, and nothing else: the CPU-side dispatchers
+ * `triangleCount` and `labelPropagation`, Boruvka's `minimumSpanningTree`, 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
@@ -24,6 +24,7 @@ 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 { minimumSpanningTree } from "./algorithms/mst.js";
 import { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 import { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 import { sssp } from "./algorithms/sssp.js";
@@ -40,6 +41,7 @@ import {
     type ClosenessAcceleratorOptions,
     type GpuAccelerator,
     type HitsOptionsLike,
+    type MstOptions,
     type SsspOptions,
 } from "./types/accelerator.js";
 import {
@@ -68,7 +70,7 @@ import {
     type FruchtermanReingoldOptions,
     type SpringElectricalOptions,
 } from "./types/options.js";
-import { type GpuTriangleResult } from "./types/structure.js";
+import { type GpuMstResult, 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. */
@@ -412,6 +414,24 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
             }
             return await labelPropagation(ctx, gs, { maxIterations: o?.maxIterations, weighted: o?.weighted });
         },
+        /**
+         * Boruvka's minimum spanning forest (design 8.5; P11-T4): the forest of the total edge order (weight, then
+         * edge index), which is the one `kruskalMST` accepts. The seam's per-arc `weights` override is refused when
+         * defined: the forest runs over the snapshot's own edge weights.
+         * @param gs - the snapshot
+         * @param o - the seam's `MstOptions`; `weights` refused when defined
+         * @returns the forest's logical edge indices and its f64 total weight
+         */
+        async minimumSpanningTree(gs: GraphSnapshot, o?: MstOptions): Promise<GpuMstResult> {
+            ctx.assertReady();
+            if (o?.weights !== undefined) {
+                throw new WebGpuGraphError("E_UNSUPPORTED", "minimumSpanningTree: weights is not supported", {
+                    option: "weights",
+                    hint: "the spanning forest runs over the snapshot's own edge weights",
+                });
+            }
+            return await minimumSpanningTree(ctx, gs);
+        },
         /**
          * 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/mst.ts

@@ -0,0 +1,269 @@
+/**
+ * Boruvka's minimum spanning forest (design 8.5, 3.3 line 808; the P11 plan's P11-T4) over the snapshot's edge list,
+ * each logical edge once, so a directed snapshot is spanned as its underlying undirected multigraph -- what
+ * `@graphty/algorithms`' `kruskalMST` does. Every vertex starts as its own component (`comp[v] = v`); each round:
+ *
+ * 1. `fill` resets every component's `bestKey` and `bestEdge` to `U32_MAX`;
+ * 2. `mst-best` twice (PD-7): the per-component minimum of the TOTAL edge order -- the order-preserving key of the
+ *    weight first (PD-6: negative weights order below positive ones, -0 equals +0), the edge index among ties -- over
+ *    the edges whose endpoints lie in different components, so self-loops and edges inside a component never compete;
+ * 3. `mst-link`: each root with a best edge hooks onto the component at its other end and records the edge, the lower
+ *    root of a two-cycle keeping its label so the edge is recorded once;
+ * 4. `wcc-compress` (PD-7: the Afforest kernel, unchanged) until every vertex points at its root: a walk of at most
+ *    COMPRESS_STEPS per dispatch divides every depth by COMPRESS_STEPS, so `compressPasses(n)` dispatches suffice.
+ *
+ * Because the order is total the forest is unique: it is the one Kruskal accepts when its sort breaks ties by edge
+ * index, which `kruskalMST` does. So the edge SET equals the CPU's on every graph, tied weights included; only the
+ * order of `edges` differs.
+ *
+ * BORUVKA_ROUNDS_PER_SUBMIT rounds are recorded per submit with one readback of their recorded-edge counts; a round
+ * that records nothing ends the run (rounds after it inside the same submit change nothing). The round count is at
+ * most ceil(log2 n) + 1, because every round at least halves the components that still have an outgoing edge;
+ * MAX_ROUNDS is the bound a device bug cannot pass, never a fallback. The forest is read back once at the end.
+ *
+ * PLAN DECISION (P11-T4 Step 3 appends each edge through an `atomicAdd` on the counters block): a root records its
+ * edge in its own word of `treeEdge`, because a root hooks at most once in a run. The result is then deterministic
+ * (the edges in root order, round by round) with no host sort, where an atomic append is ordered by the schedule.
+ *
+ * `totalWeight` is summed on the host in f64 over the snapshot's own edge weights, so it differs from
+ * `kruskalMST`'s only by the order of the summation.
+ */
+
+import { type GraphSnapshot, INVALID_INDEX, type U32 } from "@graphty/graph-format";
+
+import { BORUVKA_ROUNDS_PER_SUBMIT, U32_MAX } from "../constants.js";
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
+import { FILL_PARAMS, kernelSpec, MST_PARAMS, WCC_PARAMS } from "../kernels.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { type Binding } from "../types/memory.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { type GpuMstResult } from "../types/structure.js";
+import { algorithmScope } from "./scope.js";
+
+const ALGORITHM = "minimumSpanningTree";
+/** The bound of one compress walk (the `maxSteps` of `wcc-compress`), as connected components uses. */
+const COMPRESS_STEPS = 1024;
+/** A round count no correct run reaches: at most ceil(log2 n) + 1 <= 33 rounds for any u32 node count. */
+const MAX_ROUNDS = 64;
+/** Params slots of the largest batch: the first one's two initial fills, the reset fill, the shared best-pass and compress blocks, and one link block per round. */
+const RING_SLOTS = 5 + BORUVKA_ROUNDS_PER_SUBMIT;
+
+/**
+ * The `wcc-compress` dispatches that flatten any forest of `n` vertices: each one divides every depth by
+ * COMPRESS_STEPS (a vertex lands at least COMPRESS_STEPS ancestors up, or on its root).
+ * @param n - the vertex count
+ * @returns the dispatch count, at least 1
+ */
+export function compressPasses(n: number): number {
+    let passes = 1;
+    for (let reach = COMPRESS_STEPS; reach < n; reach *= COMPRESS_STEPS) {
+        passes++;
+    }
+    return passes;
+}
+
+/**
+ * The forest from the per-root `treeEdge` words, with the host-side f64 total.
+ * @param s - the snapshot
+ * @param treeEdge - one word per vertex, the edge its component recorded or INVALID_INDEX
+ * @param expected - the edge count the rounds reported
+ * @returns the result
+ */
+function resultOf(s: GraphSnapshot, treeEdge: Uint32Array, expected: number): GpuMstResult {
+    const edges: U32 = new Uint32Array(expected);
+    const { weights } = s.edgeList();
+    let taken = 0;
+    let totalWeight = 0;
+    for (const e of treeEdge) {
+        if (e === INVALID_INDEX) {
+            continue;
+        }
+        if (e >= s.edgeCount || taken === expected) {
+            throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: the device recorded an edge it did not count`, {
+                label: `${ALGORITHM}/treeEdge`,
+                message: `edge ${e} at forest position ${taken} of ${expected}`,
+            });
+        }
+        edges[taken++] = e;
+        totalWeight += weights === null ? 1 : weights[e];
+    }
+    if (taken !== expected) {
+        throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: ${taken} recorded edges, ${expected} counted`, {
+            label: `${ALGORITHM}/treeEdge`,
+            message: "the per-round counts disagree with the recorded forest",
+        });
+    }
+    return { edges, totalWeight };
+}
+
+/**
+ * Boruvka's minimum spanning forest 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 - signal, onProgress (`dest` is refused: the forest's length is not known before the run)
+ * @returns the forest's logical edge indices and its total weight
+ */
+export async function minimumSpanningTree(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: GpuRunOptions,
+): Promise<GpuMstResult> {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    if (options?.dest !== undefined) {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: dest is not supported`, {
+            option: "dest",
+            hint: "the forest's edge count is known only after the run",
+        });
+    }
+    if (options?.signal?.aborted) {
+        throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted before any work started`, {});
+    }
+    const n = s.nodeCount;
+    const m = s.edgeCount;
+    if (n === 0 || m === 0) {
+        options?.onProgress?.(1, 1);
+        return { edges: new Uint32Array(0), totalWeight: 0 };
+    }
+    // core() is what records (or re-records, after a release) the snapshot in the residency; only the edge list is read
+    ctx.residency.core(s, ["rowPtr"]);
+    const edges = ctx.residency.view(s, "edgeList");
+    const edgeWeight = edges.bindings.weights ?? null;
+    const scope = algorithmScope(ctx, ALGORITHM, RING_SLOTS);
+    try {
+        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 comp = words(n, "comp");
+        const bestKey = words(n, "bestKey");
+        const bestEdge = words(n, "bestEdge");
+        const treeEdge = words(n, "treeEdge");
+        const counters = words(BORUVKA_ROUNDS_PER_SUBMIT, "counters");
+        await ctx.allocator.check();
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+        const weighted = edgeWeight !== null;
+        const minKey = await ctx.pipelines.kernel(kernelSpec("mst-best", { PASS: 0, WEIGHTED: weighted }));
+        const minEdge = await ctx.pipelines.kernel(kernelSpec("mst-best", { PASS: 1, WEIGHTED: weighted }));
+        const link = await ctx.pipelines.kernel(kernelSpec("mst-link"));
+        const compress = await ctx.pipelines.kernel(kernelSpec("wcc-compress"));
+        const nodePlan = plan1d(n, wg, ctx.caps);
+        const edgePlan = plan1d(m, wg, ctx.caps);
+        const compressPlan = planGridStride(n, wg, ctx.caps);
+        const passes = compressPasses(n);
+        const { queue } = ctx.device;
+
+        let batch = new CommandBatch(ctx, `${ALGORITHM}/rounds`);
+        let first = true;
+        let rounds = 0;
+        let recorded = 0;
+        for (;;) {
+            queue.writeBuffer(counters.buffer, 0, new Uint32Array(BORUVKA_ROUNDS_PER_SUBMIT));
+            const pass = batch.pass("rounds");
+            const fillFor = (value: number, mode: number): { binding: Binding; offset: number } =>
+                scope.params(FILL_PARAMS, { count: n, value, mode, pad0: 0 });
+            if (first) {
+                const iota = fillFor(0, 1);
+                fill.dispatch(pass, fill.bind({ dst: comp, P: iota.binding }), nodePlan, [iota.offset]);
+                const none = fillFor(INVALID_INDEX, 0);
+                fill.dispatch(pass, fill.bind({ dst: treeEdge, P: none.binding }), nodePlan, [none.offset]);
+            }
+            const reset = fillFor(U32_MAX, 0);
+            const edgeParams = scope.params(MST_PARAMS, { count: m, counterIndex: 0, pad0: 0, pad1: 0 });
+            const compressParams = scope.params(WCC_PARAMS, {
+                n,
+                items: n,
+                stride: compressPlan.stride ?? n,
+                r: 0,
+                flagIndex: 0,
+                giant: U32_MAX,
+                maxSteps: COMPRESS_STEPS,
+                pad0: 0,
+            });
+            const graph = {
+                edgeSrc: edges.bindings.src,
+                edgeDst: edges.bindings.dst,
+                edgeWeight: edgeWeight ?? edges.bindings.src,
+            };
+            for (let i = 0; i < BORUVKA_ROUNDS_PER_SUBMIT; i++) {
+                for (const dst of [bestKey, bestEdge]) {
+                    fill.dispatch(pass, fill.bind({ dst, P: reset.binding }), nodePlan, [reset.offset]);
+                }
+                for (const kernel of [minKey, minEdge]) {
+                    kernel.dispatch(
+                        pass,
+                        kernel.bind({ ...graph, comp, bestKey, bestEdge, P: edgeParams.binding }),
+                        edgePlan,
+                        [edgeParams.offset],
+                    );
+                }
+                const linkParams = scope.params(MST_PARAMS, { count: n, counterIndex: i, pad0: 0, pad1: 0 });
+                link.dispatch(
+                    pass,
+                    link.bind({
+                        edgeSrc: graph.edgeSrc,
+                        edgeDst: graph.edgeDst,
+                        bestEdge,
+                        comp,
+                        treeEdge,
+                        counters,
+                        P: linkParams.binding,
+                    }),
+                    nodePlan,
+                    [linkParams.offset],
+                );
+                for (let j = 0; j < passes; j++) {
+                    compress.dispatch(pass, compress.bind({ comp, P: compressParams.binding }), compressPlan, [
+                        compressParams.offset,
+                    ]);
+                }
+            }
+            batch.endPass();
+            const countsRequest = batch.readback(counters.buffer, 0, 4 * BORUVKA_ROUNDS_PER_SUBMIT);
+            scope.flush();
+            const submitted = batch.submit();
+            const bytes = await submitted.readback;
+            ctx.assertReady();
+            first = false;
+            if (options?.signal?.aborted) {
+                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, {
+                    batchId: submitted.id,
+                });
+            }
+            const counts = new Uint32Array(bytes, countsRequest.offset, BORUVKA_ROUNDS_PER_SUBMIT);
+            let settled = false;
+            for (const count of counts) {
+                recorded += count;
+                settled ||= count === 0;
+            }
+            rounds += BORUVKA_ROUNDS_PER_SUBMIT;
+            if (recorded > n - 1) {
+                throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: ${recorded} forest edges on ${n} nodes`, {
+                    label: `${ALGORITHM}/counters`,
+                    message: "a spanning forest has at most n - 1 edges",
+                });
+            }
+            if (settled) {
+                break;
+            }
+            if (rounds >= MAX_ROUNDS) {
+                throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: still merging after ${rounds} rounds`, {
+                    label: `${ALGORITHM}/rounds`,
+                    message: "Boruvka halves the components every round; the device did not",
+                });
+            }
+            batch = new CommandBatch(ctx, `${ALGORITHM}/rounds`);
+        }
+        const raw = new Uint32Array(n);
+        await ctx.readback.read(treeEdge.buffer, 4 * n, raw);
+        ctx.assertReady();
+        options?.onProgress?.(1, 1);
+        return resultOf(s, raw, recorded);
+    } finally {
+        scope.dispose();
+    }
+}

package/src/constants.ts

@@ -295,9 +295,14 @@ export const LABEL_PROP_PASSES_PER_SUBMIT = 8;
  * per submit. Each readback is a device-to-host synchronisation that costs about 2 ms in Chromium, and at one per
  * round the syncs are 61 % of the 100,000-node call; four rounds per submit amortise them over O(log n) rounds, moving
  * the Chromium crossover from 6,000 to 4,600 nodes (design/decisions/2026-09-26-which-algorithms-earn-the-gpu.md).
- * Declared ahead of the minimum-spanning-tree driver, which reads it when it lands.
+ * `src/algorithms/mst.ts` reads it.
  */
 export const BORUVKA_ROUNDS_PER_SUBMIT = 4;
+/**
+ * The sign bit of an f32 bit pattern; interpolated into the prelude as `F32_SIGN_BIT` for `order_key`, the
+ * order-preserving u32 key of an f32 that Boruvka's `atomicMin` over edge weights runs on (P11 PD-6).
+ */
+export const F32_SIGN_BIT = 0x80000000;
 /** The per-row group-by-key (design 8.6): a row of at most this many arcs is grouped by one thread in registers; a longer row by a workgroup over a global open-addressing region. */
 export const GROUP_ROW_THREAD_MAX = 32;
 /** The largest row the thread tier accepts when a caller forces the tier: its pairwise scan is about d^2 / 2 loop steps, and llvmpipe stops every loop of an invocation after 65,535 steps in total. */

package/src/index.ts

@@ -67,6 +67,7 @@ export { sssp } from "./algorithms/sssp.js";
 export { allPairsShortestPath } from "./algorithms/all-pairs.js";
 // ==================== algorithms (P11: structure and community, design 3.3 lines 806-807, 8.5, 8.6)
 export { labelPropagation } from "./algorithms/label-propagation.js";
+export { minimumSpanningTree } from "./algorithms/mst.js";
 export { triangleCount } from "./algorithms/triangles.js";
 
 // ==================== layouts and the accelerator (P3; the two P5 factories; P4's calibrateLayout, spec 2.2)
@@ -98,6 +99,7 @@ export type {
     LabelResultLike,
     LayoutAccelerator,
     LayoutSimulation,
+    MstOptions,
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
@@ -108,7 +110,7 @@ export type {
 // ==================== types: the P8 traversal results (spec 3.3 lines 830-832, 9.7); the option types are the seam's
 // BfsOptions / SsspOptions / HitsOptionsLike above (P8 PD-19)
 export type { LabelPropagationOptions } from "./types/community.js";
-export type { GpuTriangleResult } from "./types/structure.js";
+export type { GpuMstResult, GpuTriangleResult } from "./types/structure.js";
 export type { GpuBellmanFordResult, GpuBfsResult, GpuSsspResult } from "./types/traversal.js";
 
 // ==================== types: the betweenness results (spec 3.3 lines 833-834); the option type is the seam's

package/src/kernel/prelude.ts

@@ -15,6 +15,7 @@ import {
     APSP_TILE,
     EXACT_TILES_PER_PASS,
     F32_INF_BITS,
+    F32_SIGN_BIT,
     FA2_COINCIDENT_SQ,
     FA2_DISTANCE_FLOOR,
     FA2_DISTANCE_FLOOR_SQ,
@@ -57,6 +58,7 @@ export const PRELUDE_WGSL: string = /* wgsl */ `// ---- prelude: constants, stan
 const INVALID_INDEX: u32 = ${INVALID_INDEX}u;
 const U32_MAX: u32 = ${U32_MAX}u;
 const F32_INF_BITS: u32 = ${F32_INF_BITS}u;
+const F32_SIGN_BIT: u32 = ${F32_SIGN_BIT}u;
 const MAX_WORKGROUPS_PER_DIM: u32 = ${MAX_WORKGROUPS_PER_DIM}u;
 const EXACT_TILES_PER_PASS: u32 = ${EXACT_TILES_PER_PASS}u;
 const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
@@ -95,6 +97,11 @@ fn lowbias32(x0: u32) -> u32 {
 fn mask_bit(w: u32, i: u32) -> bool { return ((w >> (i & 31u)) & 1u) == 1u; }
 fn unpack_u8(w: u32, i: u32) -> u32 { return (w >> (8u * (i & 3u))) & 0xFFu; }
 fn pair_hash(i: u32, j: u32) -> u32 { return lowbias32((min(i, j) * 0x9E3779B9u) ^ max(i, j)); }
+fn order_key(w: f32) -> u32 {
+    let raw = bitcast<u32>(w);
+    let bits = select(raw, 0u, raw == F32_SIGN_BIT);
+    return select(bits | F32_SIGN_BIT, ~bits, (bits & F32_SIGN_BIT) != 0u);
+}
 fn hash_unit(h: u32) -> f32 { return f32(h >> 8u) * (1.0 / 16777216.0); }
 fn hash_dir(h: u32, dim: u32) -> vec3f {
     let phi = 6.283185307179586 * hash_unit(h);

package/src/kernels.ts

@@ -17,7 +17,8 @@
  * (design 8.7) adds apsp-init and apsp-fw with the ApspParams block. P11 (the structure and community phase, plan
  * design/webgpu/plans/2026-09-23-webgpu-p11-structure-and-community.md) adds the graph build on the device (coo-emit,
  * run-flags, coo-scatter), the per-row group-by-key (group-by-key-row), label propagation's step (lpa-step) and
- * triangle counting (orient-flags, tri-intersect). This file is the only importer of src/wgsl/** (spec 3.2;
+ * triangle counting (orient-flags, tri-intersect), and Boruvka's minimum spanning tree adds mst-best and mst-link
+ * with the MstParams block. This file is the only importer of src/wgsl/** (spec 3.2;
  * test/layers.test.ts).
  */
 
@@ -70,6 +71,8 @@ import { groupByKeyRowWgsl } from "./wgsl/group-by-key-row.wgsl.js";
 import { histogramWgsl } from "./wgsl/histogram.wgsl.js";
 import { indirectFinalizeWgsl } from "./wgsl/indirect-finalize.wgsl.js";
 import { lpaStepWgsl } from "./wgsl/lpa-step.wgsl.js";
+import { mstBestWgsl } from "./wgsl/mst-best.wgsl.js";
+import { mstLinkWgsl } from "./wgsl/mst-link.wgsl.js";
 import { orientFlagsWgsl } from "./wgsl/orient-flags.wgsl.js";
 import { prFinalizeWgsl } from "./wgsl/pr-finalize.wgsl.js";
 import { prScaleWgsl } from "./wgsl/pr-scale.wgsl.js";
@@ -151,7 +154,9 @@ export type KernelId =
     | "orient-flags"
     | "tri-intersect"
     | "group-by-key-row"
-    | "lpa-step";
+    | "lpa-step"
+    | "mst-best"
+    | "mst-link";
 
 /** One registry entry: everything of a WgslModuleSpec except the per-variant overrides and snippets. */
 export interface KernelEntry {
@@ -566,6 +571,14 @@ export const LPA_PARAMS: UniformBlock = UniformBlock.define("LpaParams", [
     ["pad0", "u32"],
 ]);
 
+/** `MstParams` (uniform, 16 B; P11): `count` @0 (the edges of `mst-best`, the vertices of `mst-link`), `counterIndex` @4 (the word of `counters` that receives the round's recorded edges), `pad0` @8, `pad1` @12. */
+export const MST_PARAMS: UniformBlock = UniformBlock.define("MstParams", [
+    ["count", "u32"],
+    ["counterIndex", "u32"],
+    ["pad0", "u32"],
+    ["pad1", "u32"],
+]);
+
 // ---- the entries (contract 3.10.1; group 0 = graph, 1 = state, 2 = params, 3 = cold)
 
 /**
@@ -1747,6 +1760,51 @@ const LPA_STEP: KernelEntry = {
     phase: "P11",
 };
 
+/** `mst-best` (design 8.5; P11-T4, PD-7): one edge per invocation offers itself to both endpoint components; PASS 0 takes the minimum `order_key` of the weight, PASS 1 the minimum edge index among that key's edges; 6 storage bindings. */
+const MST_BEST: KernelEntry = {
+    id: "mst-best",
+    body: mstBestWgsl,
+    entryPoint: "mst_best",
+    bindings: [
+        decl(1, 0, "edgeSrc", "storage-ro", "array<u32>"),
+        decl(1, 1, "edgeDst", "storage-ro", "array<u32>"),
+        decl(1, 2, "edgeWeight", "storage-ro", "array<f32>"),
+        decl(1, 3, "comp", "storage-ro", "array<u32>"),
+        decl(1, 4, "bestKey", "storage", "array<atomic<u32>>"),
+        decl(1, 5, "bestEdge", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "MstParams"),
+    ],
+    overrideDecls: [
+        { name: "PASS", type: "u32", default: 0 },
+        { name: "WEIGHTED", type: "bool", default: false },
+    ],
+    uniforms: [MST_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P11",
+};
+
+/** `mst-link` (design 8.5; P11-T4): a component root hooks onto the component its best edge reaches and records the edge, the lower root of a two-cycle staying; one atomic per workgroup counts the recorded edges; 6 storage bindings. */
+const MST_LINK: KernelEntry = {
+    id: "mst-link",
+    body: mstLinkWgsl,
+    entryPoint: "mst_link",
+    bindings: [
+        decl(1, 0, "edgeSrc", "storage-ro", "array<u32>"),
+        decl(1, 1, "edgeDst", "storage-ro", "array<u32>"),
+        decl(1, 2, "bestEdge", "storage-ro", "array<u32>"),
+        decl(1, 3, "comp", "storage", "array<atomic<u32>>"),
+        decl(1, 4, "treeEdge", "storage", "array<u32>"),
+        decl(1, 5, "counters", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "MstParams"),
+    ],
+    overrideDecls: [],
+    uniforms: [MST_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P11",
+};
+
 /**
  * The entries by id, in dispatch order. PLAN DECISION: `KernelId` is declared in full (contract 3.10) while the
  * entries landed phase by phase, so the table is built as a Partial record and exported below through the
@@ -1758,7 +1816,8 @@ const LPA_STEP: KernelEntry = {
  * P8-T7 `"bfs-fused"`, P8-T8 `"bfs-bottom-up"`, `"bfs-bitset-build"` and `"bfs-unvisited-flags"`, P8-T9
  * `"sssp-relax"`, P8-T10 `"bf-relax"` and P8-T11 `"closeness-sweep"` and `"closeness-reduce"`, betweenness the
  * six `"bc-*"` entries, all-pairs shortest paths `"apsp-init"` and `"apsp-fw"`, and P11 its seven (the graph
- * build, the group-by-key, label propagation's step and triangle counting), so every member of `KernelId`
+ * build, the group-by-key, label propagation's step and triangle counting) plus Boruvka's `"mst-best"` and
+ * `"mst-link"`, so every member of `KernelId`
  * is present and the assertion is exact.
  */
 const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze({
@@ -1823,6 +1882,8 @@ const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze
     "tri-intersect": TRI_INTERSECT,
     "group-by-key-row": GROUP_BY_KEY_ROW,
     "lpa-step": LPA_STEP,
+    "mst-best": MST_BEST,
+    "mst-link": MST_LINK,
 });
 
 /** THE registry (spec 3.5): every entry, keyed by id. */

package/src/types/accelerator.ts

@@ -20,6 +20,7 @@ import type {
     HitsOptionsLike,
     HitsResultLike,
     LabelResultLike,
+    MstOptions,
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
@@ -52,7 +53,7 @@ import type {
     SpringElectricalStats,
 } from "./layout.js";
 import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
-import type { GpuTriangleResult } from "./structure.js";
+import type { GpuMstResult, GpuTriangleResult } from "./structure.js";
 import type { GpuBellmanFordResult, GpuBfsResult, GpuSsspResult } from "./traversal.js";
 
 // ---- the real @graphty/layout interfaces (spec 9.3, D27): imported at W1b, re-exported so the package's public
@@ -80,6 +81,7 @@ export type {
     HitsOptionsLike,
     HitsResultLike,
     LabelResultLike,
+    MstOptions,
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
@@ -120,8 +122,9 @@ export interface AcceleratorOptions {
  * betweenness members take the seam's `BetweennessAcceleratorOptions`. `allPairsShortestPath` (design 8.7) takes the
  * seam's `SsspOptions` too and refuses both of its keys. P11 adds `triangleCount` (its result carries `coefficient`
  * and `transitivity` beyond the seam's `{ perNode, total }`, which a wider object satisfies) and `labelPropagation`
- * (the seam's `HitsOptionsLike`: `maxIterations` and `weighted` honoured, `tolerance` refused). Later phases add one
- * member per shipped algorithm.
+ * (the seam's `HitsOptionsLike`: `maxIterations` and `weighted` honoured, `tolerance` refused), and
+ * `minimumSpanningTree` (Boruvka; the seam's `MstOptions`, whose per-arc `weights` override is refused). Later phases
+ * add one member per shipped algorithm.
  * Exported: implemented by src/accelerator.ts (P3-T3); re-exported from src/index.ts at P3-T3.
  * @public
  */
@@ -156,6 +159,7 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     allPairsShortestPath(s: GraphSnapshot, options?: SsspOptions): Promise<GpuApspResult>;
     triangleCount(s: GraphSnapshot): Promise<GpuTriangleResult>;
     labelPropagation(s: GraphSnapshot, options?: HitsOptionsLike): Promise<GpuLabelResult>;
+    minimumSpanningTree(s: GraphSnapshot, options?: MstOptions): Promise<GpuMstResult>;
     release(s: GraphSnapshot): void;
     dispose(): void;
 }

package/src/types/structure.ts

@@ -26,3 +26,21 @@ export interface GpuTriangleResult {
     /** The graph's transitivity, `3 x triangles / connected triples`; 0 when the graph has no connected triple. */
     readonly transitivity: number;
 }
+
+/**
+ * Boruvka's minimum spanning forest (design 3.3 line 808, 8.5): the result shape of design 3.3, `{ edges,
+ * totalWeight }`, which is the shape `@graphty/algorithms`' `kruskalMST` returns.
+ * @public
+ */
+export interface GpuMstResult {
+    /**
+     * The LOGICAL edge indices of the forest: one tree per connected component, so `nodeCount - components` edges.
+     * The forest is the one of the total edge order (weight, then edge index): on distinct weights it is THE minimum
+     * spanning forest, and on tied weights it is exactly the forest `kruskalMST` accepts, whose sort breaks ties by
+     * edge index too. The order of the array is not Kruskal's acceptance order: it is deterministic, grouped by the
+     * Boruvka round that chose each edge.
+     */
+    readonly edges: U32;
+    /** The sum of the forest's edge weights (1 per edge on an unweighted snapshot), summed in f64 on the host. */
+    readonly totalWeight: number;
+}

package/src/wgsl/mst-best.wgsl.ts

@@ -0,0 +1,31 @@
+/**
+ * The `mst-best` kernel body (design 8.5; the P11 plan's P11-T4, PD-6 and PD-7): one logical edge per invocation of
+ * a Boruvka round. An edge whose endpoints lie in different components (`comp` holds every vertex's root) offers
+ * itself to both components. `atomicMin` exists for u32 only and no atomic compares one word and writes another, so
+ * the per-component minimum of the total edge order (weight, then edge index) is TWO passes of this one body, chosen
+ * by the `PASS` override: pass 0 takes the minimum `order_key` of the weight into `bestKey`, pass 1 the minimum edge
+ * index among the edges that hold that key into `bestEdge`. `order_key` (the prelude) orders negative weights below
+ * positive ones and -0 equal to +0, which a raw bit pattern does not. Without `WEIGHTED` every edge weighs 1 and
+ * the index alone decides, as in Kruskal. Body only (spec 3.5, D9); normative text: a sabotage mutation is a textual
+ * edit of it.
+ */
+export const mstBestWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn mst_best(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let e = linear_id(wid, lid.x);
+    if (e >= P.count) { return; }
+    let cu = comp[edgeSrc[e]];
+    let cv = comp[edgeDst[e]];
+    if (cu == cv) { return; }                                     // inside one component, or a self-loop
+    var w = 1.0;
+    if (WEIGHTED) { w = edgeWeight[e]; }
+    let k = order_key(w);
+    if (PASS == 0u) {
+        atomicMin(&bestKey[cu], k);
+        atomicMin(&bestKey[cv], k);
+    } else {
+        if (k == atomicLoad(&bestKey[cu])) { atomicMin(&bestEdge[cu], e); }
+        if (k == atomicLoad(&bestKey[cv])) { atomicMin(&bestEdge[cv], e); }
+    }
+}
+`;