@graphty/webgpu-graph-algorithms 0.5.0 → 0.6.0

package/src/primitives/verify.ts

@@ -0,0 +1,249 @@
+/**
+ * The device self-check: one real exclusive scan of known numbers, run once per device before this package
+ * computes anything on it, so a device that returns wrong numbers is refused instead of believed.
+ *
+ * WHY IT EXISTS. On the Windows host lane -- Dawn's D3D12 backend over the Microsoft Basic Render Driver, the
+ * software renderer built into Windows -- every exclusive scan of more than one workgroup came back wrong: a
+ * block total of 1 where 256 belonged, or a second block nothing wrote at all, differing between two runs of
+ * identical code in one job. Everything built on the scan was wrong with it (the histogram, the radix sort, the
+ * grid build and every layout above them, eighteen test files), while every single-block scan and every earlier
+ * primitive stayed right. Three shader repairs failed; copying Microsoft's current redistributable renderer
+ * beside the runner's Node executable made all of it pass untouched. The defect is the driver's, and the danger
+ * to a caller is not a crash but silence: a graph laid out from wrong numbers with no error anywhere.
+ *
+ * WHY IT SCANS RATHER THAN PROBING A CONSTRUCT. An earlier hand-written probe matrix of workgroup constructs
+ * (test/primitives/workgroup-id-probe.test.ts) was measured PASSING on that renderer in the same job in which the
+ * real scan returned the wrong answer, so a copy of the shader's shape is not evidence about the shader. This
+ * check therefore drives the shipped `prepareScan` through the shipped composer and pipeline cache: it tests the
+ * code that runs, and it cannot drift away from it. One scan covers both recorded failures -- a value crossing
+ * `workgroupBarrier` inside a block, and a block total crossing from one dispatch of a compute pass to the next
+ * dispatch that reads it, which is the shape of every driver in this package.
+ *
+ * WHY IT REFUSES RATHER THAN ROUTING AROUND THE DEFECT. See docs/decisions/device-self-check.md: a barrier-free second
+ * implementation was designed and costed, and rejected because it would ship unverified on the only platform it
+ * exists for.
+ *
+ * WHERE IT RUNS. Lazily, at the first compute entry point a caller reaches, memoised per GPUDevice: the
+ * algorithms (degree, connectedComponents, the power-iteration family) and calibrateLayout await it on entry, and
+ * a layout simulation awaits it in the compile-and-bind promise `load()` starts -- the promise every batch and
+ * every debug run already awaits before it may submit. So a caller is covered whether the context was created,
+ * adopted through `create({ device })` or adopted through `GpuContext.from`, and a simulation refuses before its
+ * first iteration without the check sitting on the per-batch path, where an extra await would move the moment a
+ * submission becomes visible to a step() issued in the same tick and so change how the frame loop coalesces.
+ * It deliberately does NOT run in GpuContext.create:
+ * a context that only compiles -- Dawn's null backend, which computes nothing by design -- must stay usable, and
+ * `src/context.ts` may not import a primitive (the layer rule of spec 3.2).
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { UniformRing } from "../kernel/uniform-ring.js";
+import { type CheckedContext, type DeviceCheck, type DeviceCheckMismatch } from "../types/context.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+import { prepareScan } from "./scan.js";
+
+/**
+ * The word written into every output slot before the dispatch, so a word NOTHING wrote is distinguishable from
+ * a word written wrongly. The Windows lane returned this value from the second block, which is how the failure
+ * was read as "the block was never written" rather than "the block was miscomputed".
+ */
+const POISON = 0xdeadbeef;
+
+/** Full workgroups the check scans; one partial workgroup of a single word follows them. */
+const CHECK_BLOCKS = 32;
+
+/** Params slots the scan's levels need (two levels of block scan plus one add-back, with room to spare). */
+const RING_SLOTS = 8;
+
+/** The settled check per device: the one work a second caller never repeats. A rejection is dropped, so a check that failed to RUN is retried. */
+const checked = new WeakMap<GPUDevice, Promise<DeviceCheck>>();
+
+/**
+ * The input word at `i`: 1, 2, 3, ... so no two workgroups have the same block total (all-ones would give every
+ * block the same one, and a block total stored at the wrong index would still read correct -- which is exactly
+ * the Windows symptom) and every output word is a different number.
+ * @param i - the word index
+ * @returns the input value
+ */
+function inputAt(i: number): number {
+    return i + 1;
+}
+
+/**
+ * The verdict: the first output word or total that disagrees with the arithmetic answer, or null when nothing
+ * does. Pure, so test/primitives/verify.test.ts can drive it past a fabricated wrong result and exercise the
+ * refusal without a broken device.
+ * @param words - the `count` output words read back from the device
+ * @param total - the total word read back from the device
+ * @param count - the words scanned
+ * @returns the first disagreement, or null
+ * @internal
+ */
+export function checkScanWords(words: Uint32Array, total: number, count: number): DeviceCheckMismatch | null {
+    let running = 0;
+    for (let i = 0; i < count; i++) {
+        const got = words[i];
+        if (got !== running) {
+            return { where: `out[${String(i)}]`, expected: running, actual: got, poison: got === POISON };
+        }
+        // u32 addition wraps in WGSL, so the host oracle wraps too: at WORKGROUP_SIZE 256 the total cannot
+        // reach 2^32, but a false refusal would deny every device on earth, so it is not left to that constant
+        running = (running + inputAt(i)) >>> 0;
+    }
+    if (total !== running) {
+        return { where: "total", expected: running, actual: total, poison: total === POISON };
+    }
+    return null;
+}
+
+/**
+ * Binds a whole scratch buffer.
+ * @param buffer - the buffer
+ * @param size - the bytes bound
+ * @returns the binding
+ */
+function whole(buffer: GPUBuffer, size: number): Binding {
+    return { buffer, offset: 0, size, window: null };
+}
+
+/**
+ * Runs the check once: one scan of `CHECK_BLOCKS * workgroupSize + 1` words recorded into one compute pass, one
+ * submit, the output and the total read back and verified on the host.
+ *
+ * It never throws for a wrong ANSWER -- that is the returned record's job. A failure of the machinery (a lost
+ * device, a validation error, out of memory) propagates with its own code, so "the driver computes incorrectly"
+ * is never said about a device that merely died.
+ * @param ctx - the context to check
+ * @returns what the check found
+ */
+async function runCheck(ctx: CheckedContext): Promise<DeviceCheck> {
+    const started = performance.now();
+    const wg = ctx.workgroupSize;
+    const count = CHECK_BLOCKS * wg + 1;
+    const bytes = 4 * count;
+    const lease = ctx.pool.lease();
+    const ring = new UniformRing(ctx.device, ctx.allocator, RING_SLOTS, "device-check/ring");
+    try {
+        const scope: ReduceScope = {
+            device: ctx.device,
+            caps: ctx.caps,
+            pipelines: ctx.pipelines,
+            pool: ctx.pool,
+            workgroupSize: wg,
+            scratch: (byteLength, label) => lease.storage(byteLength, `device-check/${label}`),
+            params(block, values) {
+                const slot = ring.reserve(1);
+                ring.write(slot, block, values);
+                return { binding: ring.binding(block), offset: ring.offsetOf(slot) };
+            },
+        };
+        const planner = await prepareScan(scope);
+        const src = lease.storage(bytes, "device-check/src");
+        const out = lease.storage(bytes, "device-check/out");
+        const input = new Uint32Array(count);
+        for (let i = 0; i < count; i++) {
+            input[i] = inputAt(i);
+        }
+        ctx.device.queue.writeBuffer(src, 0, input);
+        ctx.device.queue.writeBuffer(out, 0, new Uint32Array(count).fill(POISON));
+        const encoder = ctx.device.createCommandEncoder({ label: "device-check" });
+        const pass = encoder.beginComputePass({ label: "device-check" });
+        const total = planner.record(pass, whole(src, bytes), count, whole(out, bytes));
+        pass.end();
+        ring.flush();
+        ctx.device.queue.submit([encoder.finish()]);
+        const words = new Uint32Array(await ctx.readback.read(out, bytes));
+        const totalWord = new Uint32Array(
+            await ctx.readback.read(total.binding.buffer, 4, undefined, total.binding.offset + 4 * total.index),
+        );
+        const mismatch = checkScanWords(words, totalWord[0], count);
+        return {
+            check: "exclusive-scan",
+            ok: mismatch === null,
+            workgroupSize: wg,
+            count,
+            blocks: CHECK_BLOCKS,
+            ms: performance.now() - started,
+            vendor: ctx.caps.vendor,
+            architecture: ctx.caps.architecture,
+            description: ctx.caps.description,
+            mismatch,
+        };
+    } finally {
+        ring.destroy();
+        lease.release();
+    }
+}
+
+/**
+ * What this device computed when it was asked for an answer this package already knows, run once per device and
+ * remembered. A caller may await it before committing work to a context; every compute entry point of the
+ * package awaits it too, so the cost is paid once whoever asks first.
+ *
+ * It reports rather than throws, so a caller can ask a device a question without having to catch the answer. The
+ * entry points use `assertDeviceComputes`, which turns a failing report into E_DEVICE_INCORRECT.
+ * @param ctx - the context whose device is checked
+ * @returns the capability record; `ok` false means this device returns wrong numbers
+ */
+export function verifyDevice(ctx: CheckedContext): Promise<DeviceCheck> {
+    const cached = checked.get(ctx.device);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const running = runCheck(ctx).catch((err: unknown) => {
+        // only a settled verdict is worth keeping: a check that could not RUN (a lost device, a transient
+        // out-of-memory) must not answer for the device forever
+        checked.delete(ctx.device);
+        throw err;
+    });
+    checked.set(ctx.device, running);
+    return running;
+}
+
+/**
+ * The guard every compute entry point awaits: resolves on a device that computed the check correctly, throws
+ * E_DEVICE_INCORRECT on one that did not, carrying the first wrong word, what was required there, and the
+ * adapter strings that separate a broken driver from a fixed one.
+ * @param ctx - the context about to be computed on
+ * @internal
+ */
+export async function assertDeviceComputes(ctx: CheckedContext): Promise<void> {
+    const check = await verifyDevice(ctx);
+    const { mismatch } = check;
+    if (mismatch === null) {
+        return;
+    }
+    const adapter = {
+        vendor: check.vendor,
+        architecture: check.architecture,
+        device: ctx.caps.device,
+        description: check.description,
+    };
+    const hint =
+        check.architecture === "warp"
+            ? "this is the Microsoft Basic Render Driver; the Microsoft.Direct3D.WARP redistributable (1.0.21 or newer) beside the host executable computes it correctly"
+            : undefined;
+    const observed = mismatch.poison
+        ? `${mismatch.where} was never written (the ${String(POISON)} the check wrote beforehand survived the dispatch)`
+        : `${mismatch.where} came back as ${String(mismatch.actual)} where ${String(mismatch.expected)} was required`;
+    const message =
+        `this device computes multi-workgroup shaders incorrectly: an exclusive scan of ${String(check.count)} ` +
+        `known numbers is wrong -- ${observed}. Refusing to run: every number this package computed here would ` +
+        `be unreliable. adapter: ${adapter.vendor}/${adapter.architecture} "${adapter.description}"`;
+    throw new WebGpuGraphError(
+        "E_DEVICE_INCORRECT",
+        hint === undefined ? message : `${message}. ${hint}`,
+        {
+            check: check.check,
+            where: mismatch.where,
+            expected: mismatch.expected,
+            actual: mismatch.actual,
+            poison: mismatch.poison,
+            count: check.count,
+            blocks: check.blocks,
+            workgroupSize: check.workgroupSize,
+            adapter,
+            ...(hint === undefined ? {} : { hint }),
+        },
+    );
+}

package/src/types/accelerator.ts

@@ -37,8 +37,14 @@ import type {
     KatzOptions,
     PageRankOptions,
 } from "./algorithms.js";
-import type { ForceAtlas2Stats, GpuLayoutSimulation, GpuLayoutTuning } from "./layout.js";
-import type { ForceAtlas2Options } from "./options.js";
+import type {
+    ForceAtlas2Stats,
+    FruchtermanReingoldStats,
+    GpuLayoutSimulation,
+    GpuLayoutTuning,
+    SpringElectricalStats,
+} from "./layout.js";
+import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.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
@@ -86,7 +92,9 @@ export interface AcceleratorOptions {
 }
 
 /**
- * The injectable object (spec 3.3): P3's forceAtlas2, release and dispose, plus P7's seven algorithm members
+ * 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
@@ -100,6 +108,10 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     readonly ctx: GpuContext;
     readonly options: Readonly<AcceleratorOptions>;
     forceAtlas2(options?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats>;
+    fruchtermanReingold(
+        options?: FruchtermanReingoldOptions,
+    ): GpuLayoutSimulation<FruchtermanReingoldOptions, FruchtermanReingoldStats>;
+    springElectrical(options?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats>;
     pageRank(s: GraphSnapshot, options?: PageRankOptions): Promise<GpuPageRankResult>;
     personalizedPageRank(
         s: GraphSnapshot,

package/src/types/context.ts

@@ -4,6 +4,7 @@
  * package eslint config). P0-T3 wrote AdapterInfoLike and AdapterSummary; P1-T1 completes the file.
  */
 
+import type { GpuContext } from "../context.js";
 import type { WebGpuGraphError } from "../errors.js";
 
 /** The limits `"raise"` takes from the adapter (spec 2.2); maxComputeWorkgroupsPerDimension is deliberately absent. */
@@ -133,3 +134,58 @@ export interface PlanCaps {
 export interface GpuDebugFlags {
     inspect: boolean;
 }
+
+/**
+ * The context the device self-check runs on. `src/primitives/**` may not name GpuContext (the layer rule of
+ * spec 3.2), and this file may, so the alias is how src/primitives/verify.ts types its argument. It is
+ * GpuContext and nothing else: pass the context you were going to compute on.
+ */
+export type CheckedContext = GpuContext;
+
+/**
+ * The first word a device got wrong in the self-check. `poison` is true when the word still held the
+ * 0xdeadbeef the check wrote before the dispatch, which means NOTHING wrote it -- a different failure from a
+ * word written with the wrong value, and the distinction that made the Windows diagnosis possible.
+ */
+export interface DeviceCheckMismatch {
+    /** Where it was found: `out[<index>]`, or `total`. */
+    readonly where: string;
+    /** The value arithmetic requires there. */
+    readonly expected: number;
+    /** The value the device returned. */
+    readonly actual: number;
+    /** True when `actual` is the poison word the check wrote beforehand: nothing wrote this word. */
+    readonly poison: boolean;
+}
+
+/**
+ * What one device self-check found (spec 3.3): the capability record a caller may read BEFORE it commits work
+ * to a device, through `verifyDevice`. `mismatch === null` (equivalently `ok`) means every one of `count`
+ * output words and the total matched the arithmetic answer; a non-null `mismatch` is the device returning
+ * wrong numbers, which every compute entry point of this package turns into E_DEVICE_INCORRECT.
+ *
+ * It reports one property -- that values crossing a workgroup barrier and block totals crossing dispatches of
+ * one compute pass survive -- and is therefore a refusal mechanism, not a certificate of correctness.
+ */
+export interface DeviceCheck {
+    /** The check that ran; one today, named so a second can be added without changing the shape. */
+    readonly check: "exclusive-scan";
+    /** True when nothing disagreed. */
+    readonly ok: boolean;
+    /** The device's workgroup size (spec 5.1). */
+    readonly workgroupSize: number;
+    /** The words scanned: `blocks * workgroupSize + 1`, so the last workgroup is a partial one. */
+    readonly count: number;
+    /** The full workgroups of the scan (one partial one follows). */
+    readonly blocks: number;
+    /** Wall time of this check in milliseconds, pipeline compile included on the first call. */
+    readonly ms: number;
+    /** caps.vendor of the device that ran it. */
+    readonly vendor: string;
+    /** caps.architecture of the device that ran it. */
+    readonly architecture: string;
+    /** caps.description: the string that separates a broken driver from a fixed one. */
+    readonly description: string;
+    /** The first disagreement, or null when there was none. */
+    readonly mismatch: DeviceCheckMismatch | null;
+}

package/src/types/layout.ts

@@ -43,6 +43,42 @@ export interface ForceAtlas2Stats extends LayoutStatsBase {
     readonly trace: ReadonlyArray<ForceAtlas2TraceRecord>;
 }
 
+/**
+ * One per-iteration trace record of the last completed batch of a Fruchterman-Reingold simulation (spec 3.3
+ * FruchtermanReingoldStats.trace element): K1 writes `temperature` from the iteration's uniform slot (spec 7.20).
+ * @public
+ */
+export interface FruchtermanReingoldTraceRecord {
+    readonly temperature: number;
+    readonly meanDisplacement: number;
+    readonly settledCount: number;
+}
+
+/** Spec 3.3 FruchtermanReingoldStats, verbatim: the cooling schedule's value replaces the controller fields. */
+export interface FruchtermanReingoldStats extends LayoutStatsBase {
+    readonly temperature: number;
+    readonly trace: ReadonlyArray<FruchtermanReingoldTraceRecord>;
+}
+
+/**
+ * One per-iteration trace record of the last completed batch of a spring-electrical simulation (spec 3.3
+ * SpringElectricalStats.trace element): `kineticEnergy` is `0.5 * sum m |v|^2` over the free nodes after the
+ * PREVIOUS iteration's integrate: K5 writes it into partials B and the NEXT iteration's K1 folds it (PD-4), so the
+ * first record after load() carries 0 and record i carries the energy of iteration i - 1.
+ * @public
+ */
+export interface SpringElectricalTraceRecord {
+    readonly kineticEnergy: number;
+    readonly meanDisplacement: number;
+    readonly settledCount: number;
+}
+
+/** Spec 3.3 SpringElectricalStats, verbatim; `kineticEnergy` is the last folded value, one iteration behind the last integrate (PD-4). */
+export interface SpringElectricalStats extends LayoutStatsBase {
+    readonly kineticEnergy: number;
+    readonly trace: ReadonlyArray<SpringElectricalTraceRecord>;
+}
+
 /** Options of GpuLayoutSimulation.run (spec 3.3). */
 export interface RunOptions {
     readonly maxIter?: number | undefined;
@@ -101,3 +137,25 @@ export interface ResolvedLayoutTuning {
     readonly extentFactor: number;
     readonly compat: "paper" | "networkx";
 }
+
+/** Spec 2.2 CalibrateOptions, verbatim: the probe sizes of calibrateLayout (default 8k / 16k / 32k / 65k). */
+export interface CalibrateOptions {
+    readonly sizes?: readonly number[] | undefined;
+}
+
+/**
+ * Spec 2.2 GpuCalibration, verbatim: the per-size ms per iteration of both repulsion tiers on the actual device,
+ * `pairsPerSecond` of the exact tier at the largest probed size, `suggestedExactMaxNodes` by the spec 7.8 rule
+ * (the largest probed n with exactMs(n) <= min(4 ms, gridMs(n)), rounded down to a power of two; when NO probed size
+ * qualifies -- the grid tier faster at every probe, or every probe over the budget -- the largest power of two strictly
+ * below the smallest probe, so the exact tier runs at no probed size and a value below floorPow2(min(sizes)) tells the
+ * caller the rule found nothing in the range: src/layouts/calibrate.ts) and the wall time of the whole call (pipeline
+ * compilation included on the first call).
+ */
+export interface GpuCalibration {
+    readonly pairsPerSecond: number;
+    readonly exactMsPerIter: Readonly<Record<number, number>>;
+    readonly gridMsPerIter: Readonly<Record<number, number>>;
+    readonly suggestedExactMaxNodes: number;
+    readonly firstCallMs: number;
+}

package/src/types/options.ts

@@ -6,7 +6,7 @@
  * import.
  */
 
-import type { F32, NodeId } from "@graphty/graph-format";
+import type { F32, NodeId, NodeMask } from "@graphty/graph-format";
 import type {
     CommonLayoutOptions,
     ForceAtlas2Options,
@@ -51,3 +51,47 @@ export interface ResolvedForceAtlas2Options {
     readonly iterationsPerStep: number;
     readonly maxInFlight: number;
 }
+
+/**
+ * The resolved (defaults applied) Fruchterman-Reingold option record (spec 7.20, 9.3): `k` null means `1 / sqrt(n)`
+ * at load; `fixed` is applied at load through ModelInputs.fixed (PD-6). Exported for src/layouts/fruchterman-reingold.ts
+ * and the option tests.
+ * @public
+ */
+export interface ResolvedFruchtermanReingoldOptions {
+    readonly k: number | null;
+    readonly iterations: number;
+    readonly cooling: "linear" | "adaptive";
+    readonly fixed: NodeMask | string | null;
+    readonly dim: 2 | 3;
+    readonly scale: number;
+    readonly center: readonly [number, number, number];
+    readonly seed: number | null;
+    readonly settleThreshold: number;
+    readonly settleWindow: number;
+    readonly iterationsPerStep: number;
+    readonly maxInFlight: number;
+}
+
+/**
+ * The resolved spring-electrical option record (spec 7.20, 9.3; ngraph's names): `gravity` is the Coulomb constant
+ * (negative repels), never FA2's centre gravity. `gravity` and `springCoefficient` are null when left to their
+ * defaults: ngraph's constant scaled by min(1, SE_SCALE_REFERENCE_NODES / n) once n is known at load. Exported for
+ * src/layouts/spring-electrical.ts and the option tests.
+ * @public
+ */
+export interface ResolvedSpringElectricalOptions {
+    readonly springLength: number;
+    readonly springCoefficient: number | null;
+    readonly gravity: number | null;
+    readonly dragCoefficient: number;
+    readonly timeStep: number;
+    readonly dim: 2 | 3;
+    readonly scale: number;
+    readonly center: readonly [number, number, number];
+    readonly seed: number | null;
+    readonly settleThreshold: number;
+    readonly settleWindow: number;
+    readonly iterationsPerStep: number;
+    readonly maxInFlight: number;
+}

package/src/wgsl/counting-scatter.wgsl.ts

@@ -0,0 +1,16 @@
+/**
+ * The `counting-scatter` kernel body (spec 6 row 5; P4-T3): the scatter of a counting sort. `start[k]` is the
+ * exclusive scan of the histogram, `cursor[k]` a zeroed per-bin atomic; an element takes the slot `start[k] +
+ * atomicAdd(&cursor[k], 1u)`. The order inside a bin depends on the schedule (set-deterministic, design 6). Body
+ * only; normative text.
+ */
+export const countingScatterWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn counting_scatter(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.count) { return; }                                  // no barrier follows
+    let k = keys[i];
+    let slot = atomicAdd(&cursor[k], 1u);                          // the per-bin cursor (6 row 5)
+    outIndex[start[k] + slot] = i;
+}
+`;

package/src/wgsl/fa2-attraction.wgsl.ts

@@ -1,37 +1,120 @@
 /**
- * K2 of the ForceAtlas2 iteration, `fa2-attraction` (spec 7.5; contract 4.5): the thread-per-row gather of the
- * attraction force over the undirected CSR rows (both arcs present, so the sum is symmetric with no atomics), the
- * linear or linlog law, the optional weights, the distributed-action division by the mass in `pos.w`, written as
- * the FIRST writer of `force` each iteration. P3 ships the thread-per-row tier over `[tierStart, tierEnd)` = `[0, n)`
- * with `USE_PERM = false`; the subgroup / workgroup tiers arrive with P4 (`TIER`).
+ * K2 of the ForceAtlas2 iteration, `fa2-attraction` (spec 7.5; contract 4.5): the gather of the attraction force
+ * over the undirected CSR rows (both arcs present, so the sum is symmetric with no atomics), the linear or linlog
+ * law, the optional weights, the distributed-action division by the mass in `pos.w`, written as the FIRST writer of
+ * `force` each iteration (or combined into it under `P.accumulate`, the windowed pattern of 4.2). The arcs are read
+ * inside the bound window [P.arcBase, P.arcEnd). P4-T5 (PD-6, PD-7) gives it the three degree tiers: TIER 0 is one
+ * row per thread over `[P.tierStart, P.tierEnd)`; TIER 1 is 32 lanes per row over `[P.hiEnd, P.midEnd)` with a
+ * five-step tree in workgroup memory; TIER 2 is one workgroup per row over `[0, P.hiEnd)` through `wg_reduce_vec4`
+ * (hence `needs: ["subgroups"]`); the row is `perm[row]` under USE_PERM. `LAW` (P5, spec 7.20) picks the pair law:
+ * 0 = the FA2 text, 1 = Fruchterman-Reingold `d^2 / k` (unfloored), 2 = ngraph's Hooke spring `k_s (d - L)`; under
+ * 1 / 2 the models compile `LINLOG = false` and `HAS_WEIGHTS = false`, and the law overwrites `w` so weights are
+ * ignored either way.
  *
- * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5) are textual edits of it.
+ * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5, P5-T7, P4-T5 / T6) are
+ * textual edits of it.
+ *
+ * TIER 0 folds its row through `row_force_dense`, a stride-one copy of `row_force`, because the shader compiler
+ * emits `row_force(i, 0u, 1u)` as a call and leaves the stride in a parameter: the loop then walks the row with a
+ * runtime step, which costs the strength-reduced addressing into colIdx / weights and the unrolling that keeps
+ * several loads in flight per thread. TIER 0 runs on every load -- alone when no row reaches degree 32, and over
+ * the low-degree rows, which are most of them, when the tiers are bound. The two folds spell their locals apart
+ * (`arc` / `nbr` / `weight` / `total` against `a` / `j` / `w` / `f`) so that each sabotage row names exactly one
+ * of them.
  */
 
-/** The K2 body: entry point `attraction`; an early return is legal here because no barrier follows (spec 3.5 rule 1). */
+/** The K2 body: entry point `attraction`; the tier bodies are functions called under the uniform `TIER` override, so the barriers of `tiered` are reached in uniform control flow and `tier0`'s early return is legal (spec 3.5 rule 1). */
 export const fa2AttractionWgsl = /* wgsl */ `fn store_force(i: u32, f: vec3f) {
     force[3u * i] = f.x;
     force[3u * i + 1u] = f.y;
     force[3u * i + 2u] = f.z;
 }
-
-@compute @workgroup_size(WG)
-fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
-    let row = linear_id(wid, lid.x) + P.tierStart;
-    if (row >= P.tierEnd) { return; }                          // no barrier follows in this tier (3.5 rule 1)
-    let i = select(row, perm[row], USE_PERM);
+fn load_force(i: u32) -> vec3f { return vec3f(force[3u * i], force[3u * i + 1u], force[3u * i + 2u]); }
+fn row_node(row: u32) -> u32 { return select(row, perm[row], USE_PERM); }
+fn row_force(i: u32, lane: u32, step: u32) -> vec3f {           // the arcs of row i this lane walks inside the bound window [P.arcBase, P.arcEnd) (4.2)
     let pi = pos[i];                                           // xyz + mass in one load (D23)
+    let a0 = max(rowPtr[i], P.arcBase);
+    let a1 = min(rowPtr[i + 1u], P.arcEnd);
     var f = vec3f(0.0);
-    for (var a = rowPtr[i]; a < rowPtr[i + 1u]; a = a + 1u) {
-        let j = colIdx[a];
+    for (var a = a0 + lane; a < a1; a = a + step) {
+        let j = colIdx[a - P.arcBase];
         if (j == i) { continue; }                              // a self-loop exerts no force
         var w = 1.0;
-        if (HAS_WEIGHTS) { w = weights[a]; }
+        if (HAS_WEIGHTS) { w = weights[a - P.arcBase]; }
         let d = pos[j].xyz - pi.xyz;                           // toward j
         let len = max(length(d), FA2_DIST_FLOOR);
+        if (LAW == 1u) { w = length(d) / P.frK; }              // LAW 1 (FR, 7.20): |F| = d^2 / k along d / d, unfloored; the linear select below applies w as is
+        if (LAW == 2u) { w = P.springCoefficient * (len - P.springLength) / len; }   // LAW 2 (spring, ngraph generateCreateSpringForce.js:33-36): Hooke k_s (d - L) toward j
         let mag = select(w, w * log(1.0 + len) / len, LINLOG); // linear: |F| = w len; linlog: |F| = w log(1 + len)
         f = f + d * mag;
     }
-    if (DISTRIBUTED) { f = f / pi.w; }
+    return f;
+}
+fn row_force_dense(i: u32) -> vec3f {                          // TIER 0's stride-one twin of row_force (see the header)
+    let pi = pos[i];
+    let lo = max(rowPtr[i], P.arcBase);
+    let hi = min(rowPtr[i + 1u], P.arcEnd);
+    var total = vec3f(0.0);
+    for (var arc = lo; arc < hi; arc = arc + 1u) {
+        let k = arc - P.arcBase;                               // the window-local index; this walk is contiguous
+        let nbr = colIdx[k];
+        if (nbr == i) { continue; }                            // a self-loop exerts no force
+        var weight = 1.0;
+        if (HAS_WEIGHTS) { weight = weights[k]; }
+        let d = pos[nbr].xyz - pi.xyz;                         // toward the neighbour
+        let len = max(length(d), FA2_DIST_FLOOR);
+        if (LAW == 1u) { weight = length(d) / P.frK; }         // LAW 1 (FR, 7.20), as in row_force
+        if (LAW == 2u) { weight = P.springCoefficient * (len - P.springLength) / len; }   // LAW 2 (spring), as in row_force
+        let mag = select(weight, weight * log(1.0 + len) / len, LINLOG);
+        total = total + d * mag;
+    }
+    return total;
+}
+fn finish(i: u32, f0: vec3f) {
+    var f = f0;
+    if (DISTRIBUTED) { f = f / pos[i].w; }
+    if (P.accumulate == 1u) { f = f + load_force(i); }         // the windowed loop of 4.2 (arcBase != 0 dispatches after the first)
     store_force(i, f);                                         // overwrites: attraction is the first writer of force each iteration
+}
+fn tier0(wid: vec3<u32>, lane: u32) {                          // TIER 0: one row per thread over [tierStart, tierEnd); no barrier, so the early return is legal (3.5 rule 1)
+    let row = linear_id(wid, lane) + P.tierStart;
+    if (row >= P.tierEnd) { return; }
+    let i = row_node(row);
+    finish(i, row_force_dense(i));
+}
+
+var<workgroup> sh: array<vec3f, WG>;
+
+fn tiered(wid: vec3<u32>, lid: u32) {                          // TIER 1: 32 lanes per row over [hiEnd, midEnd); TIER 2: WG lanes per row over [0, hiEnd) (PD-6, PD-7)
+    let g = group_id(wid);
+    var row = g;
+    var end = P.hiEnd;
+    var lane = lid;
+    var step = WG;
+    if (TIER == 1u) { row = P.hiEnd + g * (WG / 32u) + lid / 32u; end = P.midEnd; lane = lid % 32u; step = 32u; }
+    let valid = row < end;
+    var i = 0u;
+    var f = vec3f(0.0);
+    if (valid) { i = row_node(row); f = row_force(i, lane, step); }
+    if (TIER == 1u) {
+        sh[lid] = f;
+        workgroupBarrier();
+        for (var s = 16u; s >= 1u; s = s / 2u) {                 // the five-step tree over each 32-lane group; every lane runs every step
+            var t = vec3f(0.0);
+            if (lane < s) { t = sh[lid + s]; }
+            workgroupBarrier();
+            sh[lid] = sh[lid] + t;
+            workgroupBarrier();
+        }
+        if (valid && lane == 0u) { finish(i, sh[lid]); }
+    }
+    if (TIER == 2u) {
+        let t = wg_reduce_vec4(vec4f(f, 0.0), lid, 0u);
+        if (valid && lid == 0u) { finish(i, t.xyz); }
+    }
+}
+
+@compute @workgroup_size(WG)
+fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    if (TIER == 0u) { tier0(wid, lid.x); } else { tiered(wid, lid.x); }
 }`;