@graphty/webgpu-graph-algorithms 0.2.1 → 0.4.0

package/src/types/accelerator.ts

@@ -1,41 +1,34 @@
 /**
- * The structural mirrors of @graphty/layout's LayoutSimulation / LayoutAccelerator (spec 9.3) and of
- * the @graphty/algorithms AlgorithmAccelerator (spec 9.2), plus the package's own accelerator surface (spec 3.3).
- * Until W1 these ARE the mirrors (D27): from W1 the mirrors become `import type` of the real packages and
- * test/types/conformance.test-d.ts asserts mutual assignability. Types only.
+ * The layout half of spec 9.3 and the @graphty/algorithms AlgorithmAccelerator mirror (spec 9.2), plus the
+ * package's own accelerator surface (spec 3.3). D27's two halves are now on different footings: at W1b the LAYOUT
+ * mirrors became `import type` of the real `@graphty/layout` interfaces, re-exported here so this package's public
+ * surface is unchanged; the ALGORITHMS mirrors stay structural until A2/M8a gives them something real to point at.
+ * test/types/conformance.test-d.ts is the cross-compile that holds the layout half honest. Types only.
  */
 
-import type { F32, F64, GraphSnapshot, NodeMask, NumericVector, U32 } from "@graphty/graph-format";
+import type { F32, F64, GraphSnapshot, NumericVector, U32 } from "@graphty/graph-format";
+import type { LayoutAccelerator, LayoutSimulation } from "@graphty/layout";
 
 import type { GpuContext } from "../context.js";
+import type {
+    ComponentsOptions,
+    EigenvectorOptions,
+    GpuHitsResult,
+    GpuLabelResult,
+    GpuPageRankResult,
+    GpuScoresResult,
+    HitsOptions,
+    KatzOptions,
+    PageRankOptions,
+} from "./algorithms.js";
 import type { ForceAtlas2Stats, GpuLayoutSimulation, GpuLayoutTuning } from "./layout.js";
-import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
+import type { ForceAtlas2Options } from "./options.js";
 
-// ---- mirrors of @graphty/layout (spec 9.3)
+// ---- the real @graphty/layout interfaces (spec 9.3, D27): imported at W1b, re-exported so the package's public
+// surface is unchanged and src/types/layout.ts keeps resolving them from here. `export type`, never a bare
+// `export { ... }`: isolatedModules makes the bare form TS1205.
 
-/** Design 14.3 LayoutSimulation, verbatim. */
-export interface LayoutSimulation {
-    load(snapshot: GraphSnapshot, positions: F32): void;
-    step(iterations?: number): void | Promise<void>;
-    readonly settled: boolean;
-    setFixed(mask: NodeMask): void;
-    setPosition(index: number, x: number, y: number, z: number): void;
-    dispose(): void;
-}
-
-/**
- * Spec 9.3 LayoutAccelerator, verbatim.
- * Exported: published mirror (spec 3.3, D27); re-exported from src/index.ts at P3-T3.
- * @public
- */
-export interface LayoutAccelerator {
-    readonly kind: string;
-    forceAtlas2?(options?: ForceAtlas2Options): LayoutSimulation;
-    fruchtermanReingold?(options?: FruchtermanReingoldOptions): LayoutSimulation;
-    springElectrical?(options?: SpringElectricalOptions): LayoutSimulation;
-    release?(s: GraphSnapshot): void;
-    dispose?(): void;
-}
+export type { LayoutAccelerator, LayoutSimulation };
 
 // ---- mirrors of @graphty/algorithms (spec 9.2); the option types named there do not exist before A2, so they are
 // mirrored as empty-extensible records
@@ -221,8 +214,12 @@ export interface AcceleratorOptions {
 }
 
 /**
- * The injectable object (spec 3.3); at P3 it carries forceAtlas2, release and dispose -- the algorithm members
- * arrive with P7+.
+ * The injectable object (spec 3.3): P3's forceAtlas2, release and dispose, plus P7's seven algorithm members
+ * (spec 8.2, 8.3; M8b-T8), non-optional here and returning the `Gpu*Result` shapes, which satisfy the `*ResultLike`
+ * mirrors (spec 9.7: `precision` is an extra field, `F32` is a `NumericVector`). `connectedComponents` and
+ * `weaklyConnectedComponents` are the same algorithm (spec 3.3: WCC semantics on directed input) under both names
+ * the mirror declares; their options parameter stays OPTIONAL, because the mirror declares none and an extra
+ * REQUIRED parameter would stop the member satisfying it. 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
  */
@@ -231,6 +228,17 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     readonly ctx: GpuContext;
     readonly options: Readonly<AcceleratorOptions>;
     forceAtlas2(options?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats>;
+    pageRank(s: GraphSnapshot, options?: PageRankOptions): Promise<GpuPageRankResult>;
+    personalizedPageRank(
+        s: GraphSnapshot,
+        personalization: F32 | F64,
+        options?: PageRankOptions,
+    ): Promise<GpuPageRankResult>;
+    hits(s: GraphSnapshot, options?: HitsOptions): Promise<GpuHitsResult>;
+    eigenvectorCentrality(s: GraphSnapshot, options?: EigenvectorOptions): Promise<GpuScoresResult>;
+    katzCentrality(s: GraphSnapshot, options?: KatzOptions): Promise<GpuScoresResult>;
+    connectedComponents(s: GraphSnapshot, options?: ComponentsOptions): Promise<GpuLabelResult>;
+    weaklyConnectedComponents(s: GraphSnapshot, options?: ComponentsOptions): Promise<GpuLabelResult>;
     release(s: GraphSnapshot): void;
     dispose(): void;
 }

package/src/types/algorithms.ts

@@ -0,0 +1,83 @@
+/**
+ * The result and option records of the P7 algorithms (spec 3.3 lines 815-828, 9.7). The `Gpu*Result` shapes are the
+ * design's verbatim; the option records are this package's own, spelled MEMBER FOR MEMBER as the CPU seam spells
+ * them so one object literal satisfies both sides (the D27 mirror rule src/types/options.ts followed for the
+ * layout options until W1b, when those became `import type` re-exports of `@graphty/layout`'s declarations).
+ * Types only: this file imports nothing at runtime.
+ *
+ * The CPU counterparts, when phase M8a lands them (plan 2026-09-19-webgpu-m8a-algorithms-seam, Task M8a-T8):
+ * `PageRankOptions` here is `IndexedPageRankOptions` there (`{ dampingFactor?, maxIterations?, tolerance?,
+ * weighted? }`); `HitsOptions`, `EigenvectorOptions` and `KatzOptions` here all correspond to the ONE
+ * `HitsOptionsLike` there (`{ maxIterations?, tolerance?, weighted? }`), which is why every one of them carries
+ * those three members and `KatzOptions` adds `alpha` / `beta` on top; `ComponentsOptions` has no CPU counterpart at
+ * all, because `AlgorithmAccelerator.connectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>` declares no
+ * options parameter. `weighted`, never `weight`: that is the member name graph-format design 14.2 fixes at
+ * `design/graph-format/graph-format-design.md:3892` and the one M8a ports.
+ */
+
+import type { F32, U32 } from "@graphty/graph-format";
+
+/** Spec 3.3 line 815: every score result carries `precision` so a consumer can label GPU scores (Q-24). */
+export interface GpuScoresResult {
+    readonly scores: F32;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly precision: "f32";
+}
+
+/** Spec 3.3 line 816: `iterations` is the first iteration whose L1 delta fell below the tolerance (8.2), not the batch boundary. */
+export interface GpuPageRankResult extends GpuScoresResult {
+    readonly danglingMass: number;
+}
+
+/** Spec 3.3 line 817. */
+export interface GpuHitsResult {
+    readonly hubs: F32;
+    readonly authorities: F32;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly precision: "f32";
+}
+
+/** Spec 3.3 line 818: labels dense 0..count-1 in first-seen order (renumberPartition); groups() is index-aligned. */
+export interface GpuLabelResult {
+    readonly labels: U32;
+    readonly count: number;
+    groups(): U32[];
+}
+
+/** The CPU seam's IndexedPageRankOptions, member for member (M8a Task M8a-T8; graph-format design 14.2 :3892). */
+export interface PageRankOptions {
+    readonly dampingFactor?: number | undefined;
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** The CPU seam's HitsOptionsLike, member for member (M8a Task M8a-T8). */
+export interface HitsOptions {
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** The CPU seam's HitsOptionsLike again: `eigenvectorCentrality` takes that same shape on the CPU side. */
+export interface EigenvectorOptions {
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** HitsOptionsLike plus Katz's own two: `alpha` is the attenuation and `beta` the constant term. */
+export interface KatzOptions {
+    readonly alpha?: number | undefined;
+    readonly beta?: number | undefined;
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** GPU-only (spec 3.3 line 797: `renumber: true` by default, Q-12); the CPU seam's connectedComponents takes none. */
+export interface ComponentsOptions {
+    readonly renumber?: boolean | undefined;
+}

package/src/types/layout.ts

@@ -1,6 +1,6 @@
 /**
  * The layout-facing public types (spec 3.3, 7.19): the stats records, the GPU simulation interface that extends the
- * design-14.3 LayoutSimulation mirror, the run options and the GPU-only tuning knobs. Types only.
+ * real `@graphty/layout` LayoutSimulation (design 14.3), the run options and the GPU-only tuning knobs. Types only.
  */
 
 import type { F32, GraphSnapshot, NodeMask } from "@graphty/graph-format";
@@ -50,7 +50,7 @@ export interface RunOptions {
     readonly signal?: AbortSignal | undefined;
 }
 
-/** Spec 3.3 GpuLayoutSimulation, verbatim (LayoutSimulation is the design-14.3 mirror of accelerator.ts). */
+/** Spec 3.3 GpuLayoutSimulation, verbatim (LayoutSimulation is `@graphty/layout`'s, via accelerator.ts). */
 export interface GpuLayoutSimulation<Options, Stats extends LayoutStatsBase> extends LayoutSimulation {
     load(snapshot: GraphSnapshot, positions: F32): void;
     /**

package/src/types/options.ts

@@ -1,60 +1,29 @@
 /**
- * The option records of the layouts (spec 9.3, 7.14): structural mirrors of @graphty/layout's option types (D27),
- * copied field for field so a `ForceAtlas2Options` object the element parses is accepted here without a cast. Types
- * only: this file imports nothing at runtime.
+ * The option records of the layouts (spec 9.3, 7.14). The five layout-owned records come from `@graphty/layout` by
+ * `import type` and are re-exported here, so a `ForceAtlas2Options` object the element parses is not merely
+ * shaped like the one this package takes -- it IS the same declaration (W1b; the D27 mirrors are gone).
+ * `ResolvedForceAtlas2Options` below is this package's own and stays local. Types only: nothing here is a runtime
+ * import.
  */
 
-import type { F32, NodeId, NodeMask } from "@graphty/graph-format";
+import type { F32, NodeId } from "@graphty/graph-format";
+import type {
+    CommonLayoutOptions,
+    ForceAtlas2Options,
+    FruchtermanReingoldOptions,
+    SimulationOptions,
+    SpringElectricalOptions,
+} from "@graphty/layout";
 
-/** Design 14.3 CommonLayoutOptions, mirrored verbatim. */
-export interface CommonLayoutOptions {
-    readonly dim?: 2 | 3 | undefined;
-    readonly scale?: number | undefined;
-    readonly center?: ArrayLike<number> | undefined;
-    readonly seed?: number | null | undefined;
-}
-
-/** Spec 9.3 SimulationOptions, mirrored verbatim (layout-owned; the CPU simulations ignore maxInFlight). */
-export interface SimulationOptions {
-    readonly settleThreshold?: number | undefined;
-    readonly settleWindow?: number | undefined;
-    readonly iterationsPerStep?: number | undefined;
-    readonly maxInFlight?: number | undefined;
-}
-
-/**
- * Spec 9.3 ForceAtlas2Options, mirrored verbatim (same names and defaults as
- * layout/src/layouts/force-directed/forceatlas2.ts lines 26-42).
- */
-export interface ForceAtlas2Options extends CommonLayoutOptions, SimulationOptions {
-    readonly maxIter?: number | undefined;
-    readonly jitterTolerance?: number | undefined;
-    readonly scalingRatio?: number | undefined;
-    readonly gravity?: number | undefined;
-    readonly strongGravity?: boolean | undefined;
-    readonly distributedAction?: boolean | undefined;
-    readonly linlog?: boolean | undefined;
-    readonly nodeMass?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
-    readonly nodeSize?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
-    readonly weight?: boolean | string | null | undefined;
-    readonly dissuadeHubs?: boolean | undefined;
-}
-
-/** Spec 9.3 FruchtermanReingoldOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
-export interface FruchtermanReingoldOptions extends CommonLayoutOptions, SimulationOptions {
-    readonly k?: number | null | undefined;
-    readonly iterations?: number | undefined;
-    readonly fixed?: NodeMask | string | null | undefined;
-}
-
-/** Spec 9.3 SpringElectricalOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
-export interface SpringElectricalOptions extends CommonLayoutOptions, SimulationOptions {
-    readonly springLength?: number | undefined;
-    readonly springCoefficient?: number | undefined;
-    readonly gravity?: number | undefined;
-    readonly dragCoefficient?: number | undefined;
-    readonly timeStep?: number | undefined;
-}
+// The five layout-owned option records are @graphty/layout's declarations, re-exported so src/index.ts's barrel
+// and the option type tests keep resolving them from here (W1b, Task M5b-T2).
+export type {
+    CommonLayoutOptions,
+    ForceAtlas2Options,
+    FruchtermanReingoldOptions,
+    SimulationOptions,
+    SpringElectricalOptions,
+};
 
 /**
  * The resolved (defaults applied) ForceAtlas2 option record the simulation keeps; every field present.

package/src/wgsl/pr-finalize.wgsl.ts

@@ -0,0 +1,36 @@
+/**
+ * The `pr-finalize` kernel body (spec 8.2 dispatch (b)): ONE workgroup folds the `P.groups` per-workgroup partials
+ * into the header at `partials[0]` -- a STORAGE region, never a uniform, read by the next dispatch of the same
+ * pass -- and records `firstConverged` the first time the delta falls below `P.convergeThreshold`. NORM_MODE 2
+ * stores the square root of the folded norm (the L2 case). The recorded iteration is `P.iteration - 1u` because
+ * the delta a scale pass produces at iteration i is `|x(i-1) - x(i-2)|`, the error of iteration i - 1 (PD-9).
+ * The body is normative: a sabotage mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `pr_finalize`; override NORM_MODE (2 takes the square root of the folded norm, every other value stores it as folded). */
+export const prFinalizeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn pr_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    var d = 0.0;
+    var e = 0.0;
+    var m = 0.0;
+    for (var g = lid.x; g < P.groups; g = g + WG) {
+        d = d + partials[1u + g].danglingMass;
+        e = e + partials[1u + g].delta;
+        m = m + partials[1u + g].norm;
+    }
+    let folded = wg_reduce_vec4(vec4f(d, e, m, 0.0), lid.x, 0u);
+    if (lid.x == 0u) {
+        partials[0].danglingMass = folded.x;
+        partials[0].delta = folded.y;
+        var norm = folded.z;
+        if (NORM_MODE == 2u) { norm = sqrt(max(0.0, folded.z)); }
+        partials[0].norm = norm;
+        partials[0].iteration = P.iteration;
+        let unset = partials[0].firstConverged == U32_MAX;
+        if (P.trackConvergence == 1u && P.iteration >= 2u && folded.y < P.convergeThreshold && unset) {
+            partials[0].firstConverged = P.iteration - 1u;
+        }
+    }
+}
+`;

package/src/wgsl/pr-scale.wgsl.ts

@@ -0,0 +1,48 @@
+/**
+ * The `pr-scale` kernel body (spec 8.2 dispatch (a)): one invocation per node writes `xNorm[u]` and contributes a
+ * per-workgroup partial of the dangling mass, the L1 delta `|rankIn - rankPrev|` and, for the spectral modes, the
+ * norm term. NORM_MODE selects the divisor: 0 PageRank (`rankIn[u] / outWeightSum[u]`, 0 and a dangling
+ * contribution when the sum is not positive); 1 and 2 are NORM PASSES that write no xNorm and only accumulate
+ * `abs(x)` (L1) or `x * x` (L2); 3 divides by the scalar `partials[0].norm` the previous dispatch folded; 4 is the
+ * identity (Katz). The body is normative: a sabotage mutation is a textual edit of it, so it is not restyled.
+ *
+ * The guard is named `inRange`, never `active`: `active` is a WGSL reserved word (spec 16.2) and the composer
+ * rejects it before a device is touched.
+ */
+
+/** Entry point `pr_scale`; override NORM_MODE (0 PageRank, 1 L1 norm pass, 2 L2 norm pass, 3 scale by partials[0].norm, 4 identity). */
+export const prScaleWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn pr_scale(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let u = linear_id(wid, lid.x);
+    let inRange = u < P.n;
+    var x = 0.0;
+    var prev = 0.0;
+    if (inRange) { x = rankIn[u]; prev = rankPrev[u]; }
+    var dangling = 0.0;
+    var delta = 0.0;
+    var normTerm = 0.0;
+    if (inRange) {
+        delta = abs(x - prev);
+        if (NORM_MODE == 0u) {
+            let divisor = outWeightSum[u];
+            if (divisor <= 0.0) { dangling = x; xNorm[u] = 0.0; } else { xNorm[u] = x / divisor; }
+        }
+        if (NORM_MODE == 1u) { normTerm = abs(x); }
+        if (NORM_MODE == 2u) { normTerm = x * x; }
+        if (NORM_MODE == 3u) {
+            var scale = partials[0].norm;
+            if (scale <= 0.0) { scale = 1.0; }
+            xNorm[u] = x / scale;
+        }
+        if (NORM_MODE == 4u) { xNorm[u] = x; }
+    }
+    let folded = wg_reduce_vec4(vec4f(dangling, delta, normTerm, 0.0), lid.x, 0u);
+    if (lid.x == 0u) {
+        let slot = 1u + group_id(wid);
+        partials[slot].danglingMass = folded.x;
+        partials[slot].delta = folded.y;
+        partials[slot].norm = folded.z;
+    }
+}
+`;

package/src/wgsl/spmv-pull.wgsl.ts

@@ -0,0 +1,47 @@
+/**
+ * The `spmv-pull` kernel body (spec 6 row 9, 8.2; PD-1 of the M8b plan): one invocation per row of the REVERSE
+ * adjacency, grid-stride over `[0, P.n)`, folding `weight * xNorm[nbr]` over the row's in-arcs in chunks of 64
+ * terms (a two-level f32 sum: the chunk absorbs the rounding of 64 terms, the row total the rounding of the chunk
+ * count, so a 10,000-arc hub row loses about 200 rounding steps instead of 10,000; Kahan compensation is not used
+ * because Metal's shader compiler folds `((acc + term) - acc) - term` to zero whatever hides it) and writing
+ * `rankOut[v] = beta * pv + alpha * (sum + danglingMass * pv)`, where `pv` is `personalization[v]` when
+ * HAS_PERSONALIZATION and the uniform `P.uniformP` otherwise. PageRank sets alpha to the
+ * damping factor, beta to `1 - alpha` and USE_DANGLING; HITS and eigenvector set alpha 1, beta 0, uniformP 0; Katz
+ * sets alpha to the attenuation, beta to its constant and uniformP 1. The body is normative: a sabotage mutation
+ * (test/helpers/sabotage.ts) is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `spmv_pull`; overrides HAS_PERSONALIZATION and USE_DANGLING plus the standard USE_PERM / HAS_WEIGHTS. */
+export const spmvPullWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn spmv_pull(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    var dangling = 0.0;
+    if (USE_DANGLING) { dangling = partials[0].danglingMass; }
+    let first = linear_id(wid, lid.x);
+    for (var row = first; row < P.n; row = row + P.stride) {
+        let v = select(row, perm[row], USE_PERM);
+        let a0 = max(rowPtr[v], P.arcBase);
+        let a1 = min(rowPtr[v + 1u], P.arcEnd);
+        var acc = 0.0;
+        var chunk = 0.0;
+        var inChunk = 0u;
+        for (var arc = a0; arc < a1; arc = arc + 1u) {
+            let nbr = colIdx[arc - P.arcBase];               // \`target\` is a WGSL reserved word (spec 16.2)
+            var weight = 1.0;
+            if (HAS_WEIGHTS) { weight = weights[arc - P.arcBase]; }
+            // two-level sum: 64 terms into chunk, chunk into acc (see the header; no compensation, no select)
+            chunk = chunk + (weight * xNorm[nbr]);
+            inChunk = inChunk + 1u;
+            if (inChunk == 64u) {
+                acc = acc + chunk;
+                chunk = 0.0;
+                inChunk = 0u;
+            }
+        }
+        acc = acc + chunk;
+        var pv = P.uniformP;
+        if (HAS_PERSONALIZATION) { pv = personalization[v]; }
+        rankOut[v] = (P.beta * pv) + (P.alpha * (acc + (dangling * pv)));
+    }
+}
+`;

package/src/wgsl/wcc-compress.wgsl.ts

@@ -0,0 +1,26 @@
+/**
+ * The `wcc-compress` kernel body (spec 8.3): pointer jumping to the root, reading through `atomicLoad` on the same
+ * `array<atomic<u32>>` because WGSL forbids mixing atomic and plain access to one element. The walk is bounded by
+ * `P.maxSteps`; a walk that runs out leaves a shorter path, which the next round finishes. The body is normative:
+ * a sabotage mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `wcc_compress`; no overrides. */
+export const wccCompressWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn wcc_compress(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var v = first; v < P.items; v = v + P.stride) {
+        var root = atomicLoad(&comp[v]);
+        var steps = 0u;
+        loop {
+            let parent = atomicLoad(&comp[root]);
+            if (parent == root) { break; }
+            if (steps >= P.maxSteps) { break; }
+            steps = steps + 1u;
+            root = parent;
+        }
+        atomicStore(&comp[v], root);
+    }
+}
+`;

package/src/wgsl/wcc-link-edges.wgsl.ts

@@ -0,0 +1,46 @@
+/**
+ * The `wcc-link-edges` kernel body (spec 8.3): the each-edge-once link round of Afforest, correct for directed and
+ * undirected input alike because `edgeList()` yields every logical edge once in declared orientation (design 10.1).
+ * `link_pair` is the same GAP `Link` transcription as wcc-link-sample (each module is composed alone, so the helper
+ * is copied, not shared): all-u32 CAS on `comp`, an `array<atomic<u32>>` because WGSL forbids mixing atomic and
+ * plain access to one element, with a bounded retry loop (PD-5) and the changed flag at `P.flagIndex` inside the
+ * same array (PD-4). The `P.giant` guard is GAP's "skip the vertices already in the giant component" and is a pure
+ * optimisation -- linking two vertices already in one component is a no-op. The body is normative: a sabotage
+ * mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `wcc_link_edges`; no overrides. */
+export const wccLinkEdgesWgsl = /* wgsl */ `
+fn link_pair(a: u32, b: u32) {
+    var p1 = atomicLoad(&comp[a]);
+    var p2 = atomicLoad(&comp[b]);
+    var steps = 0u;
+    loop {
+        if (p1 == p2) { break; }
+        if (steps >= P.maxSteps) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        steps = steps + 1u;
+        let hi = max(p1, p2);
+        let lo = min(p1, p2);
+        let pHigh = atomicLoad(&comp[hi]);
+        if (pHigh == lo) { break; }
+        if (pHigh == hi) {
+            let swapped = atomicCompareExchangeWeak(&comp[hi], hi, lo);
+            if (swapped.exchanged) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        }
+        p1 = atomicLoad(&comp[atomicLoad(&comp[hi])]);
+        p2 = atomicLoad(&comp[lo]);
+    }
+}
+
+@compute @workgroup_size(WG)
+fn wcc_link_edges(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var e = first; e < P.items; e = e + P.stride) {
+        let u = edgeSrc[e];
+        let v = edgeDst[e];
+        if (u == v) { continue; }
+        if (atomicLoad(&comp[u]) == P.giant && atomicLoad(&comp[v]) == P.giant) { continue; }
+        link_pair(u, v);
+    }
+}
+`;

package/src/wgsl/wcc-link-sample.wgsl.ts

@@ -0,0 +1,45 @@
+/**
+ * The `wcc-link-sample` kernel body (spec 8.3): one of Afforest's sampled link rounds -- every vertex links its
+ * r-th neighbour, `colIdx[rowPtr[v] + P.r]`, when it has one. `link_pair` is GAP's `Link` (gapbs/cc.cc lines
+ * 40-150) transcribed for WGSL: all-u32 CAS on `comp`, which is `array<atomic<u32>>` because WGSL forbids mixing
+ * atomic and plain access to one element, with a bounded retry loop (PD-5). The changed flag is the word at
+ * `P.flagIndex` inside the same array (PD-4). The body is normative: a sabotage mutation is a textual edit of it,
+ * so it is not restyled.
+ */
+
+/** Entry point `wcc_link_sample`; standard USE_PERM / HAS_WEIGHTS only (the body reads neither weights nor a permutation beyond the row select). */
+export const wccLinkSampleWgsl = /* wgsl */ `
+fn link_pair(a: u32, b: u32) {
+    var p1 = atomicLoad(&comp[a]);
+    var p2 = atomicLoad(&comp[b]);
+    var steps = 0u;
+    loop {
+        if (p1 == p2) { break; }
+        if (steps >= P.maxSteps) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        steps = steps + 1u;
+        let hi = max(p1, p2);
+        let lo = min(p1, p2);
+        let pHigh = atomicLoad(&comp[hi]);
+        if (pHigh == lo) { break; }
+        if (pHigh == hi) {
+            let swapped = atomicCompareExchangeWeak(&comp[hi], hi, lo);
+            if (swapped.exchanged) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        }
+        p1 = atomicLoad(&comp[atomicLoad(&comp[hi])]);
+        p2 = atomicLoad(&comp[lo]);
+    }
+}
+
+@compute @workgroup_size(WG)
+fn wcc_link_sample(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var row = first; row < P.items; row = row + P.stride) {
+        let v = select(row, perm[row], USE_PERM);
+        let a0 = rowPtr[v];
+        let a1 = rowPtr[v + 1u];
+        if (a0 + P.r < a1) {
+            link_pair(v, colIdx[a0 + P.r]);
+        }
+    }
+}
+`;

package/src/wgsl/wcc-sample.wgsl.ts

@@ -0,0 +1,18 @@
+/**
+ * The `wcc-sample` kernel body (spec 8.3 "a 1,024-entry histogram readback to find the giant component"): writes
+ * the component label of `P.items` pseudo-randomly chosen vertices into `hist`, which the host reads back and takes
+ * the mode of (PD-12: GAP's SampleFrequentElement counts on the host too, and a device histogram over component
+ * ids would return a bucket, not an id). The sampler uses the prelude's `lowbias32` and `%`, never a bitwise
+ * operator on an index.
+ */
+
+/** Entry point `wcc_sample`; no overrides. */
+export const wccSampleWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn wcc_sample(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.items) { return; }
+    let v = lowbias32(i + P.r) % P.n;
+    hist[i] = atomicLoad(&comp[v]);
+}
+`;