@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.5

package/src/primitives/frontier.ts

@@ -0,0 +1,372 @@
+/**
+ * The `Frontier` of design 6 row 7 and the device-side dispatch selector of design 5.4 (P8-T4; the P8 plan's PD-1,
+ * PD-3, PD-8, PD-23, DEP-P8-A, DEP-P8-C). A traversal's per-level state is two n-slot vertex queues, ONE 25-word
+ * counters block (every counter of the phase is a word of it: a four-byte word is never a legal storage-binding
+ * offset, and the selector must reach every count it acts on through one binding) and the edge queue. The host
+ * never reads a counter inside a submit: `frontier-finalize`, one lane, runs at the START of every level (role 0:
+ * rotates `nextFrontierCount` into `frontierCount`, advances `level`, decides `done`, chooses the level's path) and
+ * again once the edge queue is filled (role 1: clamps `edgeCount`, or on an overflow -- `edgeCountUnclamped >
+ * edgeCapacity` -- switches the path to the fused retry, PD-23). The choice is the block's `path` word (`W.path`,
+ * word 24); every level kernel is a direct grid-stride dispatch that reads it first and does nothing unless the
+ * word names it (design/decisions/2026-09-25-frontier-kernels-dispatch-directly.md: the seven indirect slots the
+ * selector once wrote per level cost about 0.4 ms of Dawn validation each and were 97 % of a traversal's wall
+ * time; they and their args buffer are gone). The host records up to `MAX_LEVELS_PER_SUBMIT` levels per submit and
+ * reads `done` (four bytes) once per submit; a boundary that finds `done` set writes path 0 and moves no counter,
+ * so the recorded levels past the end are no-ops and the counters freeze at the finishing boundary's values.
+ *
+ * The seed: `frontierCount` is NEVER seeded, because the first boundary rotates it out unread. A BFS driver calls
+ * `reset(queue, source, { nextFrontierCount: 1, level: U32_MAX })`: the first boundary rotates the 1 in, adds it into
+ * `visitedCount`, and wraps `level` to 0, so the level-0 expansion claims the source's neighbours at `level + 1 == 1`.
+ * `reset` is a queue write, ordered before the submit that follows, and it puts the source on side 0.
+ *
+ * Every buffer comes from the caller's ONE lease (`scope.scratch`) so the algorithm's dispose()
+ * releases them together (design 4.4). The two vertex queues are two BUFFERS, never two ranges of one: `Kernel.bind`
+ * rejects one buffer bound read-only and read-write in one dispatch even for disjoint ranges. `src/primitives/**`
+ * never imports `src/context.ts`.
+ */
+
+import { MAX_LEVELS_PER_SUBMIT, U32_MAX } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { FRONTIER_COUNTERS, FRONTIER_PARAMS, kernelSpec } from "../kernels.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+
+/** The values of the `path` word (`W.path`): what a level's kernels run; every level kernel reads it first. */
+export const PATH: Readonly<{
+    none: 0;
+    twoPhase: 1;
+    fused: 2;
+    bottomUp: 3;
+    fusedRetry: 4;
+    near: 5;
+    far: 6;
+}> = Object.freeze({ none: 0, twoPhase: 1, fused: 2, bottomUp: 3, fusedRetry: 4, near: 5, far: 6 });
+
+/** The words of the counters block (`FRONTIER_COUNTERS`), by index: byte offset 4 x word; no driver types a number. */
+export const W: Readonly<{
+    frontierCount: 0;
+    nextFrontierCount: 1;
+    frontierDegreeSum: 2;
+    prevFrontierCount: 3;
+    prevDegreeSum: 4;
+    unvisitedCount: 5;
+    unvisitedDegreeSum: 6;
+    unvisitedListLen: 7;
+    edgeCount: 8;
+    edgeCountUnclamped: 9;
+    overflowLevels: 10;
+    level: 11;
+    visitedCount: 12;
+    switches: 13;
+    direction: 14;
+    done: 15;
+    arcsScanned: 16;
+    fusedLevels: 17;
+    twoPhaseLevels: 18;
+    bottomUpLevels: 19;
+    farCount: 20;
+    nextFarCount: 21;
+    thresholdBits: 22;
+    deltaBits: 23;
+    path: 24;
+}> = Object.freeze({
+    frontierCount: 0,
+    nextFrontierCount: 1,
+    frontierDegreeSum: 2,
+    prevFrontierCount: 3,
+    prevDegreeSum: 4,
+    unvisitedCount: 5,
+    unvisitedDegreeSum: 6,
+    unvisitedListLen: 7,
+    edgeCount: 8,
+    edgeCountUnclamped: 9,
+    overflowLevels: 10,
+    level: 11,
+    visitedCount: 12,
+    switches: 13,
+    direction: 14,
+    done: 15,
+    arcsScanned: 16,
+    fusedLevels: 17,
+    twoPhaseLevels: 18,
+    bottomUpLevels: 19,
+    farCount: 20,
+    nextFarCount: 21,
+    thresholdBits: 22,
+    deltaBits: 23,
+    path: 24,
+});
+
+/** The words a `reset` seeds (every other word is zeroed). */
+export type FrontierSeed = Readonly<Partial<Record<keyof typeof W, number>>>;
+
+/** The `FrontierParams` fields a caller passes to `recordFinalize`; the planner fills `role`, `wg`, `edgeCapacity` and `n` itself. A missing field is written as 0. */
+export type FrontierFinalizeFields = Readonly<
+    Partial<
+        Record<
+            | "alpha"
+            | "beta"
+            | "fusedMax"
+            | "maxDepth"
+            | "mode"
+            | "cutoffBits"
+            | "arcBase"
+            | "arcEnd"
+            | "predKind"
+            | "bitsBase"
+            | "source"
+            | "stride"
+            | "firstOfSubmit"
+            | "iteration",
+            number
+        >
+    >
+>;
+
+/**
+ * The given words of a partial record (a key spelled with an undefined value is dropped, so the block writer sees
+ * only numbers).
+ * @param words - the partial record
+ * @returns the defined entries
+ */
+function definedWords(words: Readonly<Partial<Record<string, number>>>): Record<string, number> {
+    const out: Record<string, number> = {};
+    for (const [name, value] of Object.entries(words)) {
+        if (value !== undefined) {
+            out[name] = value;
+        }
+    }
+    return out;
+}
+
+/** The largest role `frontier-finalize` knows: 0 and 1 land here (P8-T4), 2 and 3 are the SSSP piles' (P8-T9). */
+const MAX_ROLE = 3;
+
+/**
+ * The E_INVALID_ARGUMENT of a value that is not a non-negative integer.
+ * @param argument - the argument name
+ * @param value - the value
+ */
+function assertCount(argument: string, value: number): void {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `frontier: ${argument} must be a non-negative integer`, {
+            argument,
+            value,
+            expected: "a non-negative integer",
+        });
+    }
+}
+
+/** The frontier queue of design 6 row 7: two vertex queues, the counters block and the edge queue, all leased by the caller's scope. */
+export class Frontier {
+    /** The two n-slot u32 vertex queues (`vertices[side]` is the input of the current level). */
+    readonly vertices: readonly [Binding, Binding];
+    /** The `FrontierCounters` block, 112 B, bound by every kernel as `array<atomic<u32>>`. */
+    readonly counters: Binding;
+    /** The edge queue: `edgeCapacity` entries of u32 (the target vertex of an arc). */
+    readonly edgeQueue: Binding;
+    /** How many entries the edge queue holds; role 1 clamps `edgeCount` to it and detects an overflow above it. */
+    readonly edgeCapacity: number;
+    /** The vertex count (a `reset` source is below it). */
+    readonly n: number;
+    private sideIndex: 0 | 1 = 0;
+
+    /**
+     * Wraps the leased buffers; use prepareFrontier().
+     * @param vertices - the two vertex queues
+     * @param counters - the counters block
+     * @param edgeQueue - the edge queue
+     * @param edgeCapacity - the edge queue's entry count
+     * @param n - the vertex count
+     */
+    constructor(
+        vertices: readonly [Binding, Binding],
+        counters: Binding,
+        edgeQueue: Binding,
+        edgeCapacity: number,
+        n: number,
+    ) {
+        this.vertices = vertices;
+        this.counters = counters;
+        this.edgeQueue = edgeQueue;
+        this.edgeCapacity = edgeCapacity;
+        this.n = n;
+    }
+
+    /**
+     * Which vertex queue is the input of the current level (a host-side index between two cached bind-group sets).
+     * @returns 0 or 1
+     */
+    get side(): 0 | 1 {
+        return this.sideIndex;
+    }
+
+    /**
+     * The vertex queue the current level expands from.
+     * @returns `vertices[side]`
+     */
+    get input(): Binding {
+        return this.sideIndex === 0 ? this.vertices[0] : this.vertices[1];
+    }
+
+    /**
+     * The vertex queue the current level's claims append to.
+     * @returns `vertices[1 - side]`
+     */
+    get output(): Binding {
+        return this.sideIndex === 0 ? this.vertices[1] : this.vertices[0];
+    }
+
+    /** Flips the two vertex queues; the counts rotate inside the block, so nothing else moves. */
+    swap(): void {
+        this.sideIndex = this.sideIndex === 0 ? 1 : 0;
+    }
+
+    /**
+     * Seeds a traversal: one `queue.writeBuffer` of the whole 112-byte block (zero except the caller's words) and one of
+     * `vertices[0][0] = source`, both ordered before the submit that follows; the source is on side 0 afterwards.
+     * `frontierCount` is not a word to seed: the first boundary rotates word 1 into it (the BFS seed is
+     * `{ nextFrontierCount: 1, level: U32_MAX }`). A source outside `[0, n)`, an unknown word or a value that is not a
+     * u32 is E_INVALID_ARGUMENT before anything is written.
+     * @param queue - the device queue
+     * @param source - the source vertex
+     * @param seed - the words to seed
+     */
+    reset(queue: GPUQueue, source: number, seed: FrontierSeed): void {
+        if (!Number.isInteger(source) || source < 0 || source >= this.n) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `frontier: source ${source} is outside [0, ${this.n})`, {
+                argument: "source",
+                value: source,
+                expected: `an integer in [0, ${this.n})`,
+            });
+        }
+        const bytes = new ArrayBuffer(FRONTIER_COUNTERS.byteLength);
+        FRONTIER_COUNTERS.write(new DataView(bytes), definedWords(seed));
+        this.sideIndex = 0;
+        queue.writeBuffer(this.counters.buffer, this.counters.offset, bytes);
+        queue.writeBuffer(this.vertices[0].buffer, this.vertices[0].offset, Uint32Array.of(source));
+    }
+}
+
+/** A prepared frontier (design 6 row 7): the leased queue and the recorded selector dispatches. */
+export interface FrontierPlanner {
+    /** The queue the planner's selector rotates and chooses the path of. */
+    readonly frontier: Frontier;
+    /**
+     * Records one `frontier-finalize` dispatch (one workgroup) in `role` for `level` of the current submit: one
+     * `FrontierParams` record with `wg`, `edgeCapacity` and `n` filled by the planner and every other field from
+     * `fields`. A level outside `[0, MAX_LEVELS_PER_SUBMIT)` (the selector addresses nothing by level any more, but
+     * the host's submit cadence still is the bound) or a role outside `[0, 3]` is E_INVALID_ARGUMENT before
+     * anything is recorded.
+     * @param pass - the compute pass
+     * @param role - 0 the level boundary, 1 the edge-queue role (2 and 3 are P8-T9's)
+     * @param level - the level inside the submit
+     * @param fields - the tuning and window words
+     */
+    recordFinalize(pass: GPUComputePassEncoder, role: number, level: number, fields: FrontierFinalizeFields): void;
+}
+
+/**
+ * Leases the frontier's buffers from the scope and compiles the selector so `recordFinalize` is synchronous. The
+ * edge capacity defaults to `max(1, min(arcCount, floor(maxStorageBufferBindingSize / 4)))` (never a zero-length
+ * buffer: the one-node graph has no arcs); a test passes a small one to force the overflow path. The planner lives
+ * exactly as long as the scope: never use it after the scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @param n - the vertex count
+ * @param arcCount - the arc count (the natural edge-queue size)
+ * @param edgeCapacity - the edge queue's entry count, when the caller chooses it (an integer >= 1)
+ * @returns the planner
+ */
+export async function prepareFrontier(
+    scope: ReduceScope,
+    n: number,
+    arcCount: number,
+    edgeCapacity?: number,
+): Promise<FrontierPlanner> {
+    assertCount("n", n);
+    assertCount("arcCount", arcCount);
+    const capacity =
+        edgeCapacity ?? Math.max(1, Math.min(arcCount, Math.floor(scope.caps.limits.maxStorageBufferBindingSize / 4)));
+    if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "frontier: edgeCapacity must be an integer >= 1", {
+            argument: "edgeCapacity",
+            value: capacity,
+            expected: "an integer in [1, 2^32)",
+        });
+    }
+    const kernel = await scope.pipelines.kernel(kernelSpec("frontier-finalize"));
+    const queueBytes = 4 * Math.max(1, n);
+    const vertices: readonly [Binding, Binding] = [
+        { buffer: scope.scratch(queueBytes, "frontier/vertices-0"), offset: 0, size: queueBytes, window: null },
+        { buffer: scope.scratch(queueBytes, "frontier/vertices-1"), offset: 0, size: queueBytes, window: null },
+    ];
+    const counters: Binding = {
+        buffer: scope.scratch(FRONTIER_COUNTERS.byteLength, "frontier/counters"),
+        offset: 0,
+        size: FRONTIER_COUNTERS.byteLength,
+        window: null,
+    };
+    const edgeQueue: Binding = {
+        buffer: scope.scratch(4 * capacity, "frontier/edge-queue"),
+        offset: 0,
+        size: 4 * capacity,
+        window: null,
+    };
+    const frontier = new Frontier(vertices, counters, edgeQueue, capacity, n);
+    return new FrontierPlannerImpl(scope, kernel, frontier);
+}
+
+/** The planner: the selector kernel bound once to the frontier's block. */
+class FrontierPlannerImpl implements FrontierPlanner {
+    readonly frontier: Frontier;
+    private readonly scope: ReduceScope;
+    private readonly kernel: Kernel;
+
+    /**
+     * Wraps the resolved kernel; use prepareFrontier().
+     * @param scope - the caller's scope
+     * @param kernel - the `frontier-finalize` kernel
+     * @param frontier - the leased queue
+     */
+    constructor(scope: ReduceScope, kernel: Kernel, frontier: Frontier) {
+        this.scope = scope;
+        this.kernel = kernel;
+        this.frontier = frontier;
+    }
+
+    /**
+     * Records one selector dispatch (see the interface).
+     * @param pass - the compute pass
+     * @param role - the role
+     * @param level - the level inside the submit
+     * @param fields - the caller's fields
+     */
+    recordFinalize(pass: GPUComputePassEncoder, role: number, level: number, fields: FrontierFinalizeFields): void {
+        if (!Number.isInteger(level) || level < 0 || level >= MAX_LEVELS_PER_SUBMIT) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `frontier: level ${level} is outside the submit`, {
+                argument: "level",
+                value: level,
+                expected: `an integer in [0, ${MAX_LEVELS_PER_SUBMIT})`,
+            });
+        }
+        if (!Number.isInteger(role) || role < 0 || role > MAX_ROLE) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `frontier: role ${role} is not a finalize role`, {
+                argument: "role",
+                value: role,
+                expected: `an integer in [0, ${MAX_ROLE}]`,
+            });
+        }
+        const { scope, frontier } = this;
+        const params = scope.params(FRONTIER_PARAMS, {
+            ...definedWords(fields),
+            role,
+            wg: scope.workgroupSize,
+            edgeCapacity: frontier.edgeCapacity,
+            n: frontier.n,
+        });
+        const bound = this.kernel.bind({ counters: frontier.counters, P: params.binding });
+        this.kernel.dispatch(pass, bound, plan1d(1, scope.workgroupSize, scope.caps), [params.offset]);
+    }
+}

package/src/types/accelerator.ts

@@ -10,6 +10,7 @@ import type {
     ApspResultLike,
     BellmanFordResultLike,
     BetweennessAcceleratorOptions,
+    BfsOptions,
     BfsResultLike,
     CommunityResultLike,
     CorenessResultLike,
@@ -20,6 +21,7 @@ import type {
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
+    SsspOptions,
     SsspResultLike,
 } from "@graphty/algorithms";
 import type { F32, F64, GraphSnapshot } from "@graphty/graph-format";
@@ -45,6 +47,7 @@ import type {
     SpringElectricalStats,
 } from "./layout.js";
 import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.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
 // surface is unchanged and src/types/layout.ts keeps resolving them from here. `export type`, never a bare
@@ -61,6 +64,7 @@ export type {
     ApspResultLike,
     BellmanFordResultLike,
     BetweennessAcceleratorOptions,
+    BfsOptions,
     BfsResultLike,
     CommunityResultLike,
     CorenessResultLike,
@@ -71,6 +75,7 @@ export type {
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
+    SsspOptions,
     SsspResultLike,
 };
 
@@ -95,11 +100,15 @@ export interface AcceleratorOptions {
  * The injectable object (spec 3.3): P3's forceAtlas2, release and dispose, P5's fruchtermanReingold and
  * springElectrical (the two other optional members of the real LayoutAccelerator, spec 9.3; the CPU option types in,
  * the GPU simulations out), 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.
+ * (spec 8.2, 8.3; M8b-T8) and P8's four traversal members (spec 8.4; P8-T13 PD-16), 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. The four traversals
+ * take the seam's OWN option types (PD-19: `BfsOptions`, `SsspOptions` for both `sssp` and `bellmanFord`,
+ * `HitsOptionsLike` for `closenessCentrality`), so a key the CPU dispatcher forwards is exactly a key the GPU reads;
+ * `test/types/conformance.test-d.ts` holds each parameter EQUAL to the seam's, not merely assignable. 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
  */
@@ -123,6 +132,10 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     katzCentrality(s: GraphSnapshot, options?: KatzOptions): Promise<GpuScoresResult>;
     connectedComponents(s: GraphSnapshot, options?: ComponentsOptions): Promise<GpuLabelResult>;
     weaklyConnectedComponents(s: GraphSnapshot, options?: ComponentsOptions): Promise<GpuLabelResult>;
+    breadthFirstSearch(s: GraphSnapshot, source: number, options?: BfsOptions): Promise<GpuBfsResult>;
+    sssp(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<GpuSsspResult>;
+    bellmanFord(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<GpuBellmanFordResult>;
+    closenessCentrality(s: GraphSnapshot, options?: HitsOptionsLike): Promise<GpuScoresResult>;
     release(s: GraphSnapshot): void;
     dispose(): void;
 }

package/src/types/traversal.ts

@@ -0,0 +1,56 @@
+/**
+ * The result records of the P8 frontier family (design 3.3 lines 830-832, 9.7), verbatim. The OPTION types are the
+ * seam's own -- `BfsOptions` and `SsspOptions` from `@graphty/algorithms`, re-exported through
+ * `src/types/accelerator.ts` beside `HitsOptionsLike` -- and are deliberately NOT redeclared here (P8 PD-19): a
+ * member the CPU dispatcher forwards options into must read exactly the keys the CPU port reads. Every sentinel is
+ * spelled on its field, because a consumer who reads `parent[root] === 4294967295` and guesses is the failure this
+ * file prevents. Types only: this file imports nothing at runtime.
+ */
+
+import type { F32, U32 } from "@graphty/graph-format";
+
+/**
+ * Design 3.3 line 830: what `breadthFirstSearch` returns. Satisfies the seam's `BfsResultLike` (`depth`, `parent`,
+ * `order`, `visitedCount`) with `levels` and `switches` on top. Every array is bitwise reproducible (PD-14).
+ */
+export interface GpuBfsResult {
+    /** Per node: its hop count from the source; `INVALID_INDEX` (4294967295) = unreached. */
+    readonly depth: U32;
+    /**
+     * Per node: the SMALLEST node index `u` with `depth[u] + 1 == depth[v]` and an arc `u -> v` (PD-24: a post-pass over
+     * the settled depths, so the chain to the source strictly decreases `depth`); `INVALID_INDEX` for the source and
+     * for an unreached node.
+     */
+    readonly parent: U32;
+    /** Length `visitedCount`: the reached nodes grouped by depth, ascending by node index within a depth (PD-14). */
+    readonly order: U32;
+    /** How many nodes were reached, the source included. */
+    readonly visitedCount: number;
+    /** `max depth + 1`; 1 for a source with no out-arcs. */
+    readonly levels: number;
+    /** Direction changes of the direction-optimizing search (a device counter, design 8.4); 0 on a top-down-only run. */
+    readonly switches: number;
+}
+
+/**
+ * Design 3.3 line 831: what `sssp` returns. Satisfies the seam's `SsspResultLike` (`dist: NumericVector` admits `F32`;
+ * `predArc: U32`). `dist` is bitwise reproducible (PD-9) and `predArc` is a function of it alone (PD-27).
+ */
+export interface GpuSsspResult {
+    /** Per node: its shortest distance from the source in f32; `+Infinity` = unreached, which includes beyond `cutoff`. */
+    readonly dist: F32;
+    /**
+     * Per node `v`: a TIGHT arc `a` into `v` (`fround(dist[src(a)] + w(a)) == dist[v]`) whose source sits one PD-27 key
+     * step below `v`, the smallest such arc index; the chain `v -> src(a) -> ...` always ends at the source.
+     * `INVALID_INDEX` (4294967295) for the source and for an unreached node.
+     */
+    readonly predArc: U32;
+    /** How many nodes have a finite `dist`, the source included. */
+    readonly reachedCount: number;
+}
+
+/** Design 3.3 line 832: what `bellmanFord` returns. Satisfies the seam's `BellmanFordResultLike`. */
+export interface GpuBellmanFordResult extends GpuSsspResult {
+    /** When true, `dist` and `predArc` are the values of the last round, not shortest paths. */
+    readonly hasNegativeCycle: boolean;
+}

package/src/wgsl/advance-expand.wgsl.ts

@@ -0,0 +1,68 @@
+/**
+ * The `advance-expand` kernel body (design 6 row 8, 8.10 "BFS expand"; P8-T5, the P8 plan's PD-23): Gunrock's
+ * block-mapped expansion of a vertex frontier into the edge queue. Each workgroup loads up to `WG` frontier entries,
+ * reads their degrees clipped to the bound arc window `[P.arcBase, P.arcEnd)` (so the window-aware form of P8-T12
+ * changes nothing here), runs the prelude's INCLUSIVE workgroup scan `wg_scan_u32` over those degrees -- the subgroup
+ * form when the device has the feature, the Hillis-Steele form otherwise, which is the ONLY text that differs between
+ * the twin's two compilations -- and then every invocation strips the range `[0, aggregate)` with a binary search
+ * (`upper_bound`) over the scanned degrees to find which entry its arc belongs to. One `atomicAdd` per WORKGROUP
+ * reserves the block's span in the queue (`edgeCount`), the same aggregate lands in `edgeCountUnclamped` (the overflow
+ * detector, never clamped) and in `frontierDegreeSum` (Beamer's m_f); a lane whose queue position is at or past
+ * `P.edgeCapacity` writes nothing (the clamp). The queue holds the TARGET vertex of each arc only (PD-24: `parent`
+ * comes from the post-pass). Uniformity (spec 3.5 rule 1): the guarded loads write locals, the scan call and the
+ * `workgroupUniformLoad` sit unconditionally after the guard, and the strip loop is bounded by a uniform value.
+ * There is no `TIER` override: a hub row is balanced over all `WG` lanes inside its block, and the small-frontier
+ * workgroup-per-row structure is `bfs-fused` (P8-T7). Body only (spec 3.5, D9); the text is normative: the
+ * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const advanceExpandWgsl = /* wgsl */ `
+var<workgroup> sh: array<u32, WG>;          // the block's degrees, then their inclusive scan
+var<workgroup> rowStart: array<u32, WG>;    // the first bound arc of each entry's row
+var<workgroup> base: u32;                   // the block's reserved span in the edge queue
+var<workgroup> wcount: u32;                 // the frontier's length on a two-phase level, 0 on any other
+
+@compute @workgroup_size(WG)
+fn advance_expand(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (lid.x == 0u) { wcount = select(0u, atomicLoad(&counters[0]), atomicLoad(&counters[24]) == 1u); }   // frontierCount, on the two-phase path only (the path word)
+    let count = workgroupUniformLoad(&wcount);                       // uniform: the block loop below holds barriers
+    for (var b0 = group_id(wid) * WG; b0 < count; b0 = b0 + P.stride) {   // grid-stride over blocks of WG entries (a direct dispatch of the plan's groups)
+        let i = b0 + lid.x;                                          // this lane's frontier entry
+        var deg = 0u;
+        var start = 0u;
+        if (i < count) {                                                 // guarded loads into locals (3.5 rule 1)
+            let v = frontierIn[i];
+            let lo = max(rowPtr[v], P.arcBase);                          // the row clipped to the bound window (P8-T12)
+            let hi = min(rowPtr[v + 1u], P.arcEnd);
+            start = lo;
+            deg = select(0u, hi - lo, hi > lo);
+        }
+        let inclusive = wg_scan_u32(deg, lid.x);                         // the prelude's inclusive scan in LANE order (P8-T1 Step 5); the twin
+        sh[lid.x] = inclusive;                                           // sh is monotone in lid.x, the index the binary search walks
+        rowStart[lid.x] = start;
+        workgroupBarrier();
+        let aggregate = workgroupUniformLoad(&sh[WG - 1u]);              // uniform; includes a barrier
+        if (lid.x == 0u) {
+            base = atomicAdd(&counters[8], aggregate);                   // edgeCount: ONE reservation per workgroup, not one per arc
+            atomicAdd(&counters[9], aggregate);                          // edgeCountUnclamped: the overflow detector (PD-23)
+            atomicAdd(&counters[2], aggregate);                          // frontierDegreeSum: Beamer's m_f (P8-T8)
+        }
+        workgroupBarrier();
+        for (var p = lid.x; p < aggregate; p = p + WG) {                 // strip [0, aggregate): lane j takes j, j + WG, ...
+            var lo = 0u;                                                 // upper_bound: the first k with sh[k] > p owns arc p
+            var hi = WG;
+            loop {
+                if (lo >= hi) { break; }
+                let mid = (lo + hi) / 2u;
+                if (sh[mid] > p) { hi = mid; } else { lo = mid + 1u; }
+            }
+            let k = lo;
+            var exclusive = 0u;
+            if (k > 0u) { exclusive = sh[k - 1u]; }
+            let arc = rowStart[k] + (p - exclusive);
+            let q = base + p;
+            if (q < P.edgeCapacity) { edgeQueue[q] = colIdx[arc - P.arcBase]; }   // the clamp of PD-23; the queue holds the target vertex only (PD-24)
+        }
+        workgroupBarrier();                                              // sh, rowStart and base are reused by the next block
+    }
+}
+`;

package/src/wgsl/bf-relax.wgsl.ts

@@ -0,0 +1,57 @@
+/**
+ * The `bf-relax` kernel body (design 8.4 "Bellman-Ford"; P8-T10, the P8 plan's PD-12 / PD-22 / PD-27 / DEP-P8-E):
+ * one edge-parallel relaxation round over the `edgeList()` view -- every logical edge once, in declared orientation,
+ * and under `UNDIRECTED` the other direction too, because an undirected edge has ONE weight (read through its
+ * forward arc, `weights[edgeToArc[e]]`, from the run's arc-indexed vector: the snapshot's column or the uploaded
+ * override). `dist` is `array<atomic<u32>>` holding the f32 bit patterns (`F32_INF_BITS` = unreached, tested as the
+ * pattern: `bitcast<f32>(F32_INF_BITS)` is a const-expression Tint rejects). `atomicMin` on the patterns is `min` on
+ * the values for NON-NEGATIVE floats only (PD-9); with a negative distance the bit-pattern order reverses, so the
+ * claim is a compare-exchange loop on the pattern: read, compute, compare as floats, try to exchange. WGSL lets
+ * `atomicCompareExchangeWeak` fail spuriously, so the loop is BOUNDED (PD-12: `P.maxRetries`, the driver's
+ * `MAX_RETRIES`; contention is per vertex, not global) and a lane that exhausts it sets `flags[1]`
+ * (`retryExhausted`): the driver treats the round as changed and runs on, so the lost update is retried by the next
+ * round, which examines every edge anyway; a bound hit in the decision round is E_VALIDATION, never a guess. A
+ * successful exchange sets `flags[0]` (`changed`); the driver stops when a batch of rounds changed nothing, and a
+ * change in the round after `n - 1` is the negative cycle. `P.cutoffBits` is the CPU port's `dv <= cutoff` guard
+ * (`+Inf` when absent; with negative weights a negative cutoff legitimately relaxes). Grid-strided over
+ * `planGridStride(edgeCount)` with `P.stride` the plan's stride; no barrier anywhere, so the loops may be per lane.
+ * The whole arc array is bound (never windowed, DEP-P8-E). Body only (spec 3.5, D9); the text is normative: the
+ * sabotage rows of test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bfRelaxWgsl = /* wgsl */ `
+fn relax(v: u32, nd: f32) {
+    var cur = atomicLoad(&dist[v]);
+    var tries = 0u;
+    loop {
+        if (!(nd < bitcast<f32>(cur))) { break; }                     // no improvement; +Inf is greater than every finite nd
+        let r = atomicCompareExchangeWeak(&dist[v], cur, bitcast<u32>(nd));
+        if (r.exchanged) { atomicStore(&flags[0], 1u); break; }        // changed
+        cur = r.old_value;
+        tries = tries + 1u;
+        if (tries >= P.maxRetries) { atomicStore(&flags[1], 1u); break; }   // retryExhausted (PD-12)
+    }
+}
+
+@compute @workgroup_size(WG)
+fn bf_relax(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    let cutoff = bitcast<f32>(P.cutoffBits);
+    for (var e = first; e < P.edgeCount; e = e + P.stride) {          // each logical edge once (edgeList)
+        let u = edgeSrc[e];
+        let v = edgeDst[e];
+        let w = weights[edgeToArc[e]];                                 // the edge's weight through its forward arc
+        let du = atomicLoad(&dist[u]);
+        if (du != F32_INF_BITS) {                                      // unreached is tested as the bit pattern, as sssp-pred does
+            let nd = bitcast<f32>(du) + w;
+            if (nd <= cutoff) { relax(v, nd); }
+        }
+        if (UNDIRECTED) {                                              // the other direction of an undirected edge
+            let dv = atomicLoad(&dist[v]);
+            if (dv != F32_INF_BITS) {
+                let nd = bitcast<f32>(dv) + w;
+                if (nd <= cutoff) { relax(u, nd); }
+            }
+        }
+    }
+}
+`;

package/src/wgsl/bfs-bitset-build.wgsl.ts

@@ -0,0 +1,23 @@
+/**
+ * The `bfs-bitset-build` kernel body (design 8.4 "the bitset frontier"; P8-T8): the vertex-list-to-bitset hand-off
+ * of a bottom-up level. One invocation per entry of the input frontier (`frontierCount`, word 0), each `atomicOr`ing
+ * its vertex's bit into the `ceil(n / 32)`-word bitset at `P.bitsBase` inside the `sweepIn` buffer (the region a
+ * `fill` zeroed just before, on every level). The design's "bulk non-atomic path when the frontier is >= 40% of
+ * n" iterates WORDS of a frontier that is already a bitset; this frontier is a vertex list, so a word-owning store
+ * has nothing to iterate and `atomicOr` per vertex is the whole kernel. The sweep appends what it claims as a plain
+ * vertex list, exactly as the contract does, and writes no second bitset: the next level's bits come from this
+ * kernel running over that list, so one representation of a frontier (a vertex list plus a count) serves the whole
+ * phase and the hand-off in either direction is free. The early return keys on a counter and `local_invocation_id`
+ * with no barrier after it (spec 3.5 rule 1). Body only (spec 3.5, D9); the text is normative: the sabotage rows of
+ * test/helpers/sabotage.ts are textual edits of it.
+ */
+export const bfsBitsetBuildWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bfs_bitset_build(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let count = select(0u, atomicLoad(&counters[0]), atomicLoad(&counters[24]) == 3u);   // frontierCount, on the bottom-up path only (the path word)
+    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {   // grid-stride; no barrier anywhere
+        let v = frontierIn[i];
+        atomicOr(&bits[P.bitsBase + (v >> 5u)], 1u << (v & 31u));
+    }
+}
+`;