@graphty/webgpu-graph-algorithms 0.2.1 → 0.3.0

package/src/algorithms/spectral.ts

@@ -0,0 +1,300 @@
+/**
+ * HITS, eigenvector centrality and Katz centrality on the device (spec 3.3 lines 794-796, 8.2 lines 2603-2605):
+ * three entry points over the ONE power-iteration driver, differing only in the adjacency the pull walks, the
+ * normaliser and the coefficients. Eigenvector is the L2-normalised iteration over the forward core; Katz is
+ * `alpha * A^T x + beta` over the reverse view with no per-iteration normaliser; HITS alternates the two pulls with
+ * sum normalisation, `a(i) = A^T norm(h(i-1))` and `h(i) = A norm(a(i-1))` (the CPU package's recurrence, which
+ * design 9.7 makes the parity target), as TWO interleaved chains of the driver -- the reverse-first chain from the
+ * hub seed and the forward-first chain from the authority seed -- so a call is still two runs and two readbacks.
+ * Every result is normalised ONCE on the host after the readback (sum for HITS, L2 for the other two), matching
+ * the f64 oracle; the per-iteration normaliser never leaves the device (PD-10).
+ */
+
+import { type F32, type GraphSnapshot } from "@graphty/graph-format";
+
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import {
+    type EigenvectorOptions,
+    type GpuHitsResult,
+    type GpuScoresResult,
+    type HitsOptions,
+    type KatzOptions,
+} from "../types/algorithms.js";
+import { type Binding } from "../types/memory.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { aborted, checkDest, coreOf, type PowerIterationRun, reverseOf, runPowerIteration } from "./power-iteration.js";
+
+/** The three options every entry point shares, resolved. */
+interface Resolved {
+    readonly n: number;
+    readonly maxIterations: number;
+    readonly tolerance: number;
+    readonly weights: Binding | null | undefined;
+    readonly dest: F32 | null;
+}
+
+/**
+ * Resolves and validates the shared options and the run options' `dest` / `signal`.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param options - maxIterations / tolerance / weighted plus dest / signal
+ * @param algorithm - the public name, for messages
+ * @returns the resolved options
+ */
+function resolve(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options: (HitsOptions & GpuRunOptions) | undefined,
+    algorithm: string,
+): Resolved {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const maxIterations = options?.maxIterations ?? 100;
+    const tolerance = options?.tolerance ?? 1e-6;
+    if (!Number.isInteger(maxIterations) || maxIterations < 1) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${algorithm}: maxIterations must be a positive integer`, {
+            argument: "maxIterations",
+            value: maxIterations,
+            expected: "a positive integer",
+        });
+    }
+    const dest = checkDest(options?.dest, n, algorithm);
+    if (options?.signal?.aborted) {
+        throw aborted(algorithm);
+    }
+    // weighted: false runs UNWEIGHTED on a weighted snapshot: the pull folds 1 per arc (prepareSpmvPull's null)
+    return { n, maxIterations, tolerance, weights: options?.weighted === false ? null : undefined, dest };
+}
+
+/**
+ * A finite coefficient, or E_INVALID_ARGUMENT.
+ * @param value - the caller's value, or undefined for the default
+ * @param fallback - the default
+ * @param argument - the option name
+ * @returns the coefficient
+ */
+function finite(value: number | undefined, fallback: number, argument: string): number {
+    const resolved = value ?? fallback;
+    if (!Number.isFinite(resolved)) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `katzCentrality: ${argument} must be a finite number`, {
+            argument,
+            value: resolved,
+            expected: "a finite number",
+        });
+    }
+    return resolved;
+}
+
+/**
+ * Copies the raw iterate into its destination divided by its norm (unchanged when the norm is not positive).
+ * @param raw - the driver's iterate
+ * @param dest - the caller's destination, or null for the raw array itself
+ * @param norm - "sum" (L1) or "l2"
+ * @returns the normalised scores
+ */
+function normalised(raw: F32, dest: F32 | null, norm: "sum" | "l2"): F32 {
+    let acc = 0;
+    for (const v of raw) {
+        acc += norm === "sum" ? Math.abs(v) : v * v;
+    }
+    const scale = norm === "sum" ? acc : Math.sqrt(acc);
+    const out = dest ?? raw;
+    for (let v = 0; v < raw.length; v++) {
+        out[v] = scale > 0 ? raw[v] / scale : raw[v];
+    }
+    return out;
+}
+
+/**
+ * The score result of one run.
+ * @param run - the driver's run
+ * @param dest - the caller's destination, or null
+ * @param norm - the final normaliser
+ * @returns the result
+ */
+function scoresOf(run: PowerIterationRun, dest: F32 | null, norm: "sum" | "l2"): GpuScoresResult {
+    return {
+        scores: normalised(run.scores, dest, norm),
+        iterations: run.iterations,
+        converged: run.converged,
+        precision: "f32",
+    };
+}
+
+/**
+ * The n = 0 result: nothing to iterate.
+ * @param dest - the caller's destination, or null
+ * @param total - the run's progress denominator, reported to onProgress as both done and total
+ * @param onProgress - the caller's progress callback
+ * @returns the empty result
+ */
+function empty(
+    dest: F32 | null,
+    total: number,
+    onProgress: ((done: number, total: number) => void) | undefined,
+): GpuScoresResult {
+    onProgress?.(total, total);
+    return { scores: dest ?? new Float32Array(0), iterations: 0, converged: true, precision: "f32" };
+}
+
+/**
+ * The latest iterate of one kind across the two HITS chains: a chain holds its seed's kind after an even number of
+ * iterations m (in `scores`, index m) and the other kind's last iterate one back (in `previous`, index m - 1, never
+ * null on an alternating run; the fallback only satisfies the type).
+ * @param sameSeed - the chain seeded with the wanted kind
+ * @param otherSeed - the chain seeded with the other kind
+ * @returns the raw iterate with the higher index
+ */
+function latestOfKind(sameSeed: PowerIterationRun, otherSeed: PowerIterationRun): F32 {
+    const fromSame = sameSeed.iterationsRun % 2 === 0 ? sameSeed.iterationsRun : sameSeed.iterationsRun - 1;
+    const fromOther = otherSeed.iterationsRun % 2 === 1 ? otherSeed.iterationsRun : otherSeed.iterationsRun - 1;
+    const chain = fromSame >= fromOther ? sameSeed : otherSeed;
+    const index = Math.max(fromSame, fromOther);
+    return (index === chain.iterationsRun ? chain.scores : chain.previous) ?? chain.scores;
+}
+
+/**
+ * Eigenvector centrality on the device (spec 3.3, 8.2): the L2-normalised power iteration over the forward
+ * adjacency, converging on `delta < n * tolerance`; the scores are L2-normalised.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged and precision
+ */
+export async function eigenvectorCentrality(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: EigenvectorOptions & GpuRunOptions,
+): Promise<GpuScoresResult> {
+    const algorithm = "eigenvectorCentrality";
+    const r = resolve(ctx, s, options, algorithm);
+    if (r.n === 0) {
+        return empty(r.dest, r.maxIterations, options?.onProgress);
+    }
+    const run = await runPowerIteration(ctx, r.n, {
+        normMode: 2,
+        adjacency: coreOf(ctx, s, algorithm),
+        alternate: null,
+        alpha: 1,
+        beta: 0,
+        uniformP: 0,
+        maxIterations: r.maxIterations,
+        tolerance: r.tolerance,
+        weights: r.weights,
+        label: algorithm,
+        signal: options?.signal,
+        onProgress: options?.onProgress,
+    });
+    return scoresOf(run, r.dest, "l2");
+}
+
+/**
+ * Katz centrality on the device (spec 3.3, 8.2): `x = alpha * A^T x + beta` over the reverse adjacency with no
+ * per-iteration normaliser; the scores are L2-normalised once at the end.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - alpha 0.1 / beta 1 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged and precision
+ */
+export async function katzCentrality(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: KatzOptions & GpuRunOptions,
+): Promise<GpuScoresResult> {
+    const algorithm = "katzCentrality";
+    const alpha = finite(options?.alpha, 0.1, "alpha");
+    const beta = finite(options?.beta, 1, "beta");
+    const r = resolve(ctx, s, options, algorithm);
+    if (r.n === 0) {
+        return empty(r.dest, r.maxIterations, options?.onProgress);
+    }
+    const run = await runPowerIteration(ctx, r.n, {
+        normMode: 4,
+        adjacency: reverseOf(ctx, s),
+        alternate: null,
+        alpha,
+        beta,
+        uniformP: 1,
+        maxIterations: r.maxIterations,
+        tolerance: r.tolerance,
+        weights: r.weights,
+        label: algorithm,
+        signal: options?.signal,
+        onProgress: options?.onProgress,
+    });
+    return scoresOf(run, r.dest, "l2");
+}
+
+/**
+ * HITS on the device (spec 3.3, 8.2): `a(i) = A^T norm(h(i-1))` and `h(i) = A norm(a(i-1))` from uniform seeds,
+ * sum-normalised. Those two recurrences interleave into two independent chains, each alternating the reverse and
+ * the forward pull, so the driver runs twice: the chain seeded as hubs pulls reverse first and holds h(m) after an
+ * even number m of iterations and a(m) after an odd one; the chain seeded as authorities is the mirror image. Each
+ * chain stops at its own batch boundary, so the two can end on opposite parities holding the SAME kind; the result
+ * takes the latest iterate of each kind across both chains (a chain's last two iterates are one of each kind),
+ * which is h(m) and a(m) when both ran m iterations and never two vectors of one kind otherwise.
+ * `iterations` is the larger of the two and `converged` their conjunction. `dest`, when given, receives the hubs.
+ * Both vectors are sum-normalised.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns hubs, authorities, iterations, converged and precision
+ */
+export async function hits(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    options?: HitsOptions & GpuRunOptions,
+): Promise<GpuHitsResult> {
+    const algorithm = "hits";
+    const r = resolve(ctx, s, options, algorithm);
+    const total = 2 * r.maxIterations;
+    if (r.n === 0) {
+        const { scores, iterations, converged, precision } = empty(r.dest, total, options?.onProgress);
+        return { hubs: scores, authorities: new Float32Array(0), iterations, converged, precision };
+    }
+    const onProgress = options?.onProgress;
+    const shared = {
+        normMode: 1 as const,
+        alpha: 1,
+        beta: 0,
+        uniformP: 0,
+        maxIterations: r.maxIterations,
+        tolerance: r.tolerance,
+        weights: r.weights,
+        signal: options?.signal,
+    };
+    const forward = coreOf(ctx, s, algorithm);
+    const reverse = reverseOf(ctx, s);
+    const hubSeeded = await runPowerIteration(ctx, r.n, {
+        ...shared,
+        adjacency: reverse,
+        alternate: forward,
+        label: `${algorithm}/hub-seeded`,
+        onProgress:
+            onProgress === undefined
+                ? undefined
+                : (done) => {
+                      onProgress(done, total);
+                  },
+    });
+    const authoritySeeded = await runPowerIteration(ctx, r.n, {
+        ...shared,
+        adjacency: forward,
+        alternate: reverse,
+        label: `${algorithm}/authority-seeded`,
+        onProgress:
+            onProgress === undefined
+                ? undefined
+                : (done) => {
+                      onProgress(r.maxIterations + done, total);
+                  },
+    });
+    return {
+        hubs: normalised(latestOfKind(hubSeeded, authoritySeeded), r.dest, "sum"),
+        authorities: normalised(latestOfKind(authoritySeeded, hubSeeded), null, "sum"),
+        iterations: Math.max(hubSeeded.iterations, authoritySeeded.iterations),
+        converged: hubSeeded.converged && authoritySeeded.converged,
+        precision: "f32",
+    };
+}

package/src/index.ts

@@ -40,6 +40,11 @@ export type { PassTiming, Profiler } from "./kernel/profiler.js";
 // ==================== algorithms (P1: the walking-skeleton diagnostic, spec 3.3)
 export { degree } from "./algorithms/degree.js";
 
+// ==================== algorithms (P7: the SpMV family and WCC, spec 8.2, 8.3)
+export { connectedComponents } from "./algorithms/components.js";
+export { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
+export { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
+
 // ==================== layouts and the accelerator (P3)
 export { createAccelerator } from "./accelerator.js";
 export { createForceAtlas2 } from "./layouts/forceatlas2.js";
@@ -67,6 +72,19 @@ export type {
     SsspResultLike,
 } from "./types/accelerator.js";
 
+// ==================== types: the P7 algorithm results and option records (spec 3.3 lines 815-828, 9.7)
+export type {
+    ComponentsOptions,
+    EigenvectorOptions,
+    GpuHitsResult,
+    GpuLabelResult,
+    GpuPageRankResult,
+    GpuScoresResult,
+    HitsOptions,
+    KatzOptions,
+    PageRankOptions,
+} from "./types/algorithms.js";
+
 // ==================== types: context and capabilities (P0 / P1)
 export type {
     AdapterInfoLike,

package/src/kernel/dispatch.ts

@@ -123,7 +123,9 @@ export function plan2d(groups: number, caps: PlanCaps): DispatchPlan {
 }
 
 /**
- * P7 (spec 5.2): groups = min(groups, maxGroups ?? (caps.software ? 64 : 4096)) with the kernel looping by stride. P1-P3: throws E_UNSUPPORTED { feature: "planGridStride" } (lead f).
+ * P7 (spec 5.2): groups = min(ceil(items / wg), maxGroups ?? (caps.software ? 64 : 4096), the per-dimension limit) with the kernel looping by `stride = groups * wg`; items 0 -> { x: 0, stride: null }.
+ * The cap is the ONE performance default in src/ that may read `caps.software` (spec 2.4, 5.2): a grid-stride map is
+ * order-independent, so the result never depends on it and the same body serves both adapters.
  * PLAN DECISION: `maxGroups?` is spelled `?: number` rather than the contract's `?: number | undefined` because the
  * root ESLint rule no-duplicate-type-constituents rejects the explicit undefined on an optional parameter (the call
  * signature is identical).
@@ -131,12 +133,17 @@ export function plan2d(groups: number, caps: PlanCaps): DispatchPlan {
  * @param wg - the workgroup size
  * @param caps - the capability table
  * @param maxGroups - the group cap
+ * @returns the plan
  */
 export function planGridStride(items: number, wg: number, caps: PlanCaps, maxGroups?: number): DispatchPlan {
-    throw new WebGpuGraphError("E_UNSUPPORTED", "planGridStride lands with the grid-stride kernels of P7 (spec 5.2)", {
-        feature: "planGridStride",
-        hint: `items ${items}, wg ${wg}, maxGroups ${maxGroups ?? (caps.software ? 64 : 4096)}`,
-    });
+    assertCount("items", items);
+    assertWorkgroupSize(wg);
+    if (items === 0) {
+        return { x: 0, y: 1, z: 1, items, stride: null };
+    }
+    const cap = Math.min(maxGroups ?? (caps.software ? 64 : 4096), perDimension(caps));
+    const groups = Math.min(Math.ceil(items / wg), cap);
+    return { x: groups, y: 1, z: 1, items, stride: groups * wg };
 }
 
 /**

package/src/kernels.ts

@@ -6,7 +6,9 @@
  * test and PipelineCache.warm() iterate this table. P1-T4 lands degree, reduce, fill, fa2-repulsion-exact (K3)
  * and fa2-speed-finalize (K4) together with every generated block of contract 3.10.2; P2-T2 lands
  * segmented-reduce; P3-T2 adds fa2-stats-finalize (K1), fa2-attraction (K2), fa2-integrate (K5) and
- * fa2-to-scene. This file is the only importer of src/wgsl/** (spec 3.2; test/layers.test.ts).
+ * fa2-to-scene; M8b-T3 adds the seven P7 entries: spmv-pull, pr-scale, pr-finalize, wcc-link-sample,
+ * wcc-link-edges, wcc-compress and wcc-sample. This file is the only importer of src/wgsl/** (spec 3.2;
+ * test/layers.test.ts).
  */
 
 import { STATE_HEADER_BYTES } from "./constants.js";
@@ -23,10 +25,17 @@ import { fa2SpeedFinalizeWgsl } from "./wgsl/fa2-speed-finalize.wgsl.js";
 import { fa2StatsFinalizeWgsl } from "./wgsl/fa2-stats-finalize.wgsl.js";
 import { fa2ToSceneWgsl } from "./wgsl/fa2-to-scene.wgsl.js";
 import { fillWgsl } from "./wgsl/fill.wgsl.js";
+import { prFinalizeWgsl } from "./wgsl/pr-finalize.wgsl.js";
+import { prScaleWgsl } from "./wgsl/pr-scale.wgsl.js";
 import { reduceWgsl } from "./wgsl/reduce.wgsl.js";
 import { segmentedReduceWgsl } from "./wgsl/segmented-reduce.wgsl.js";
+import { spmvPullWgsl } from "./wgsl/spmv-pull.wgsl.js";
+import { wccCompressWgsl } from "./wgsl/wcc-compress.wgsl.js";
+import { wccLinkEdgesWgsl } from "./wgsl/wcc-link-edges.wgsl.js";
+import { wccLinkSampleWgsl } from "./wgsl/wcc-link-sample.wgsl.js";
+import { wccSampleWgsl } from "./wgsl/wcc-sample.wgsl.js";
 
-/** Every module id of P1-P3 (P4+ ids are appended, never renamed). */
+/** Every module id of P1-P3 and P7 (later ids are appended, never renamed). */
 export type KernelId =
     | "degree"
     | "reduce"
@@ -37,7 +46,14 @@ export type KernelId =
     | "fa2-repulsion-exact"
     | "fa2-speed-finalize"
     | "fa2-integrate"
-    | "fa2-to-scene";
+    | "fa2-to-scene"
+    | "spmv-pull"
+    | "pr-scale"
+    | "pr-finalize"
+    | "wcc-link-sample"
+    | "wcc-link-edges"
+    | "wcc-compress"
+    | "wcc-sample";
 
 /** One registry entry: everything of a WgslModuleSpec except the per-variant overrides and snippets. */
 export interface KernelEntry {
@@ -52,7 +68,7 @@ export interface KernelEntry {
     /** The snippet marker names the body carries (segmented-reduce: ["VALUE"]). */
     readonly snippetSlots: readonly string[];
     /** The phase the entry landed in (documentation and the compile-matrix filter). */
-    readonly phase: "P1" | "P2" | "P3";
+    readonly phase: "P1" | "P2" | "P3" | "P7";
 }
 
 // ---- the generated blocks (spec 5.3; contract 3.10.2): field order = byte order, offsets in the JSDoc
@@ -169,6 +185,64 @@ export const FA2_PARTIAL: UniformBlock = UniformBlock.define(
     { layout: "storage" },
 );
 
+/** `SpmvParams` (uniform, 32 B; spec 8.2): `n` @0 rows of the pull, the bound arc window `[arcBase, arcEnd)` @4 / @8 (0 and arcCount when not windowed), the grid-stride step `stride` @12, `alpha` @16, `beta` @20 (the `1 - alpha` term), `uniformP` @24 (the uniform personalization mass `1 / n`, 0 for a pure SpMV), `pad0` @28. */
+export const SPMV_PARAMS: UniformBlock = UniformBlock.define("SpmvParams", [
+    ["n", "u32"],
+    ["arcBase", "u32"],
+    ["arcEnd", "u32"],
+    ["stride", "u32"],
+    ["alpha", "f32"],
+    ["beta", "f32"],
+    ["uniformP", "f32"],
+    ["pad0", "u32"],
+]);
+
+/** `PrParams` (uniform, 32 B; spec 8.2): `n` @0, `groups` @4 (the per-workgroup partial count the finalize folds), `iteration` @8 (1-based), `trackConvergence` @12 (1 records firstConverged), `convergeThreshold` @16 (`tolerance * n`, the design's `delta < tol * n`), `pad0` @20, `pad1` @24, `pad2` @28. */
+export const PR_PARAMS: UniformBlock = UniformBlock.define("PrParams", [
+    ["n", "u32"],
+    ["groups", "u32"],
+    ["iteration", "u32"],
+    ["trackConvergence", "u32"],
+    ["convergeThreshold", "f32"],
+    ["pad0", "u32"],
+    ["pad1", "u32"],
+    ["pad2", "u32"],
+]);
+
+/**
+ * `PrPartial` (storage record, 32 B; spec 8.2). Element 0 is the HEADER, whose first 16 bytes are exactly the four
+ * fields the design names -- `danglingMass` @0, `delta` @4, `firstConvergedIteration` @8, `iteration` @12 -- plus
+ * `norm` @16, which M8b adds so HITS / eigenvector / Katz keep their normaliser on the device (PD-10). Element
+ * `1 + g` is workgroup g's partial: it uses `danglingMass`, `delta` and `norm` as three sums and leaves the two u32
+ * fields zero.
+ */
+export const PR_PARTIAL: UniformBlock = UniformBlock.define(
+    "PrPartial",
+    [
+        ["danglingMass", "f32"],
+        ["delta", "f32"],
+        ["firstConverged", "u32"],
+        ["iteration", "u32"],
+        ["norm", "f32"],
+        ["pad0", "f32"],
+        ["pad1", "f32"],
+        ["pad2", "f32"],
+    ],
+    { layout: "storage" },
+);
+
+/** `WccParams` (uniform, 32 B; spec 8.3): `n` @0, `items` @4 (rows for a sample round, edges for an edge round, 1024 for the sampler), `stride` @8, `r` @12 (the neighbour index of the sampled round, and the sampler's seed), `flagIndex` @16 (the changed word inside `comp`, PD-4), `giant` @20 (`U32_MAX` before the sample), `maxSteps` @24, `pad0` @28. */
+export const WCC_PARAMS: UniformBlock = UniformBlock.define("WccParams", [
+    ["n", "u32"],
+    ["items", "u32"],
+    ["stride", "u32"],
+    ["r", "u32"],
+    ["flagIndex", "u32"],
+    ["giant", "u32"],
+    ["maxSteps", "u32"],
+    ["pad0", "u32"],
+]);
+
 // ---- the entries (contract 3.10.1; group 0 = graph, 1 = state, 2 = params, 3 = cold)
 
 /**
@@ -381,13 +455,133 @@ const FA2_TO_SCENE: KernelEntry = {
     phase: "P3",
 };
 
+/** `spmv-pull` (spec 8.10): the grid-stride pull SpMV over the reverse adjacency; HAS_PERSONALIZATION / USE_DANGLING plus the standard USE_PERM / HAS_WEIGHTS; 8 storage bindings (the design's count). */
+const SPMV_PULL: KernelEntry = {
+    id: "spmv-pull",
+    body: spmvPullWgsl,
+    entryPoint: "spmv_pull",
+    bindings: GRAPH_SLOTS.concat(
+        decl(1, 0, "xNorm", "storage-ro", "array<f32>"),
+        decl(1, 1, "rankOut", "storage", "array<f32>"),
+        decl(1, 2, "personalization", "storage-ro", "array<f32>"),
+        decl(1, 3, "partials", "storage-ro", "array<PrPartial>"),
+        decl(2, 0, "P", "uniform", "SpmvParams"),
+    ),
+    overrideDecls: [
+        { name: "HAS_PERSONALIZATION", type: "bool", default: false },
+        { name: "USE_DANGLING", type: "bool", default: false },
+    ],
+    uniforms: [SPMV_PARAMS, PR_PARTIAL],
+    needs: [],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `pr-scale` (spec 8.2 dispatch (a), 8.10): the per-node normaliser and the per-workgroup partials; NORM_MODE 0 PageRank / 1 L1 pass / 2 L2 pass / 3 scale / 4 identity; 5 storage bindings; calls the reduction helpers. */
+const PR_SCALE: KernelEntry = {
+    id: "pr-scale",
+    body: prScaleWgsl,
+    entryPoint: "pr_scale",
+    bindings: [
+        decl(1, 0, "rankIn", "storage-ro", "array<f32>"),
+        decl(1, 1, "rankPrev", "storage-ro", "array<f32>"),
+        decl(1, 2, "outWeightSum", "storage-ro", "array<f32>"),
+        decl(1, 3, "xNorm", "storage", "array<f32>"),
+        decl(1, 4, "partials", "storage", "array<PrPartial>"),
+        decl(2, 0, "P", "uniform", "PrParams"),
+    ],
+    overrideDecls: [{ name: "NORM_MODE", type: "u32", default: 0 }],
+    uniforms: [PR_PARAMS, PR_PARTIAL],
+    needs: ["subgroups"],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `pr-finalize` (spec 8.2 dispatch (b), 8.10): the one-workgroup fold of the partials into the header at partials[0] and the firstConverged record; NORM_MODE 2 takes the square root; 1 storage binding; calls the reduction helpers. */
+const PR_FINALIZE: KernelEntry = {
+    id: "pr-finalize",
+    body: prFinalizeWgsl,
+    entryPoint: "pr_finalize",
+    bindings: [decl(1, 0, "partials", "storage", "array<PrPartial>"), decl(2, 0, "P", "uniform", "PrParams")],
+    overrideDecls: [{ name: "NORM_MODE", type: "u32", default: 0 }],
+    uniforms: [PR_PARAMS, PR_PARTIAL],
+    needs: ["subgroups"],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `wcc-link-sample` (spec 8.3): Afforest's sampled link round over the CSR rows (every vertex links its r-th neighbour); the standard USE_PERM / HAS_WEIGHTS only; 5 storage bindings (the four graph slots and the atomic `comp`, whose word at P.flagIndex is the changed flag, PD-4). */
+const WCC_LINK_SAMPLE: KernelEntry = {
+    id: "wcc-link-sample",
+    body: wccLinkSampleWgsl,
+    entryPoint: "wcc_link_sample",
+    bindings: GRAPH_SLOTS.concat(
+        decl(1, 0, "comp", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "WccParams"),
+    ),
+    overrideDecls: [],
+    uniforms: [WCC_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `wcc-link-edges` (spec 8.3, 8.10): Afforest's each-edge-once link round over the edge list; no overrides; 3 storage bindings (the design's count: edgeSrc, edgeDst and the atomic `comp` carrying the changed flag). */
+const WCC_LINK_EDGES: KernelEntry = {
+    id: "wcc-link-edges",
+    body: wccLinkEdgesWgsl,
+    entryPoint: "wcc_link_edges",
+    bindings: [
+        decl(1, 0, "edgeSrc", "storage-ro", "array<u32>"),
+        decl(1, 1, "edgeDst", "storage-ro", "array<u32>"),
+        decl(1, 2, "comp", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "WccParams"),
+    ],
+    overrideDecls: [],
+    uniforms: [WCC_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `wcc-compress` (spec 8.3, 8.10): Afforest's bounded pointer-jumping compress; no overrides; 1 storage binding. */
+const WCC_COMPRESS: KernelEntry = {
+    id: "wcc-compress",
+    body: wccCompressWgsl,
+    entryPoint: "wcc_compress",
+    bindings: [decl(1, 0, "comp", "storage", "array<atomic<u32>>"), decl(2, 0, "P", "uniform", "WccParams")],
+    overrideDecls: [],
+    uniforms: [WCC_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P7",
+};
+
+/** `wcc-sample` (spec 8.3, 8.10): the component-label sample of P.items pseudo-random vertices the host takes the mode of (PD-12); no overrides; 2 storage bindings. */
+const WCC_SAMPLE: KernelEntry = {
+    id: "wcc-sample",
+    body: wccSampleWgsl,
+    entryPoint: "wcc_sample",
+    bindings: [
+        decl(1, 0, "comp", "storage", "array<atomic<u32>>"),
+        decl(1, 1, "hist", "storage", "array<u32>"),
+        decl(2, 0, "P", "uniform", "WccParams"),
+    ],
+    overrideDecls: [],
+    uniforms: [WCC_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P7",
+};
+
 /**
  * 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
  * contract's `Readonly<Record<KernelId, KernelEntry>>` type by one assertion; the runtime membership check of
  * `entryOf` is the E_INVALID_ARGUMENT the contract documents for a JS caller's unknown id. P1-T4 landed the five
  * P1 entries, P2-T2 `"segmented-reduce"`, and P3-T2 `"fa2-stats-finalize"`, `"fa2-attraction"`, `"fa2-integrate"`
- * and `"fa2-to-scene"`, so every member of `KernelId` is present and the assertion is exact.
+ * and `"fa2-to-scene"`; M8b-T3 landed the seven P7 entries, so every member of `KernelId` is present and the
+ * assertion is exact.
  */
 const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze({
     degree: DEGREE,
@@ -400,6 +594,13 @@ const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze
     "fa2-speed-finalize": FA2_SPEED_FINALIZE,
     "fa2-integrate": FA2_INTEGRATE,
     "fa2-to-scene": FA2_TO_SCENE,
+    "spmv-pull": SPMV_PULL,
+    "pr-scale": PR_SCALE,
+    "pr-finalize": PR_FINALIZE,
+    "wcc-link-sample": WCC_LINK_SAMPLE,
+    "wcc-link-edges": WCC_LINK_EDGES,
+    "wcc-compress": WCC_COMPRESS,
+    "wcc-sample": WCC_SAMPLE,
 });
 
 /** THE registry (spec 3.5): every entry, keyed by id. */