@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.1

package/src/types/accelerator.ts

@@ -0,0 +1,236 @@
+/**
+ * The structural mirrors of @graphty/layout's LayoutSimulation / LayoutAccelerator (spec 9.3) and of
+ * the @graphty/algorithms AlgorithmAccelerator (spec 9.2), plus the package's own accelerator surface (spec 3.3).
+ * Until W1 these ARE the mirrors (D27): from W1 the mirrors become `import type` of the real packages and
+ * test/types/conformance.test-d.ts asserts mutual assignability. Types only.
+ */
+
+import type { F32, F64, GraphSnapshot, NodeMask, NumericVector, U32 } from "@graphty/graph-format";
+
+import type { GpuContext } from "../context.js";
+import type { ForceAtlas2Stats, GpuLayoutSimulation, GpuLayoutTuning } from "./layout.js";
+import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
+
+// ---- mirrors of @graphty/layout (spec 9.3)
+
+/** Design 14.3 LayoutSimulation, verbatim. */
+export interface LayoutSimulation {
+    load(snapshot: GraphSnapshot, positions: F32): void;
+    step(iterations?: number): void | Promise<void>;
+    readonly settled: boolean;
+    setFixed(mask: NodeMask): void;
+    setPosition(index: number, x: number, y: number, z: number): void;
+    dispose(): void;
+}
+
+/**
+ * Spec 9.3 LayoutAccelerator, verbatim.
+ * Exported: published mirror (spec 3.3, D27); re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface LayoutAccelerator {
+    readonly kind: string;
+    forceAtlas2?(options?: ForceAtlas2Options): LayoutSimulation;
+    fruchtermanReingold?(options?: FruchtermanReingoldOptions): LayoutSimulation;
+    springElectrical?(options?: SpringElectricalOptions): LayoutSimulation;
+    release?(s: GraphSnapshot): void;
+    dispose?(): void;
+}
+
+// ---- mirrors of @graphty/algorithms (spec 9.2); the option types named there do not exist before A2, so they are
+// mirrored as empty-extensible records
+
+/**
+ * Placeholder for the CPU option types the AlgorithmAccelerator methods take before A2 lands (spec 9.2: "the
+ * accelerator methods reuse the indexed.* option types").
+ * Exported: published mirror (spec 9.2); re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export type CpuAlgorithmOptions = Readonly<Record<string, unknown>>;
+
+/**
+ * Score-shaped result of the CPU package (spec 9.7).
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface ScoresResultLike {
+    readonly scores: NumericVector;
+    readonly iterations: number;
+    readonly converged: boolean;
+}
+
+/**
+ * PageRank result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface PageRankResultLike extends ScoresResultLike {
+    readonly danglingMass?: number | undefined;
+}
+
+/**
+ * HITS result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface HitsResultLike {
+    readonly hubs: NumericVector;
+    readonly authorities: NumericVector;
+    readonly iterations: number;
+    readonly converged: boolean;
+}
+
+/**
+ * Label result mirror (components, label propagation).
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface LabelResultLike {
+    readonly labels: U32;
+    readonly count: number;
+    groups(): U32[];
+}
+
+/**
+ * BFS result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface BfsResultLike {
+    readonly depth: U32;
+    readonly parent: U32;
+    readonly order: U32;
+    readonly visitedCount: number;
+}
+
+/**
+ * SSSP result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface SsspResultLike {
+    readonly dist: NumericVector;
+    readonly predArc: U32;
+}
+
+/**
+ * Bellman-Ford result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface BellmanFordResultLike extends SsspResultLike {
+    readonly hasNegativeCycle: boolean;
+}
+
+/**
+ * Edge-score result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface EdgeScoresResultLike {
+    readonly scores: NumericVector;
+}
+
+/**
+ * APSP result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface ApspResultLike {
+    readonly dist: NumericVector;
+    readonly n: number;
+}
+
+/**
+ * k-core result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface CorenessResultLike {
+    readonly coreness: U32;
+}
+
+/**
+ * Minimum-spanning-tree result mirror.
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface MstResultLike {
+    readonly edges: U32;
+    readonly totalWeight: number;
+}
+
+/**
+ * Community result mirror (Louvain).
+ * Exported: published mirror; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface CommunityResultLike extends LabelResultLike {
+    readonly modularity: number;
+}
+
+/**
+ * Spec 9.2 AlgorithmAccelerator, verbatim (every member optional; option types are CpuAlgorithmOptions until A2).
+ * Exported: published mirror (spec 9.2, D27); re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface AlgorithmAccelerator {
+    readonly kind: string;
+    pageRank?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<PageRankResultLike>;
+    personalizedPageRank?(
+        s: GraphSnapshot,
+        personalization: F32 | F64,
+        options?: CpuAlgorithmOptions,
+    ): Promise<PageRankResultLike>;
+    hits?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<HitsResultLike>;
+    eigenvectorCentrality?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<ScoresResultLike>;
+    katzCentrality?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<ScoresResultLike>;
+    connectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>;
+    weaklyConnectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>;
+    breadthFirstSearch?(s: GraphSnapshot, source: number, options?: CpuAlgorithmOptions): Promise<BfsResultLike>;
+    sssp?(s: GraphSnapshot, source: number, options?: CpuAlgorithmOptions): Promise<SsspResultLike>;
+    bellmanFord?(s: GraphSnapshot, source: number, options?: CpuAlgorithmOptions): Promise<BellmanFordResultLike>;
+    closenessCentrality?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<ScoresResultLike>;
+    betweennessCentrality?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<ScoresResultLike>;
+    edgeBetweennessCentrality?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<EdgeScoresResultLike>;
+    allPairsShortestPath?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<ApspResultLike>;
+    kCoreDecomposition?(s: GraphSnapshot): Promise<CorenessResultLike>;
+    triangleCount?(s: GraphSnapshot): Promise<{ readonly perNode: U32; readonly total: number }>;
+    labelPropagation?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<LabelResultLike>;
+    minimumSpanningTree?(s: GraphSnapshot): Promise<MstResultLike>;
+    louvain?(s: GraphSnapshot, options?: CpuAlgorithmOptions): Promise<CommunityResultLike>;
+    release?(s: GraphSnapshot): void;
+    dispose?(): void;
+}
+
+// ---- the package's own accelerator surface (spec 3.3); grows one method per shipped algorithm from P7
+
+/**
+ * Spec 3.3 AcceleratorOptions, verbatim.
+ * Exported: consumed by src/accelerator.ts (P3-T3); re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface AcceleratorOptions {
+    readonly layout?: GpuLayoutTuning | undefined;
+    readonly algorithms?:
+        | {
+              readonly betweenness?:
+                  { readonly k?: number | undefined; readonly sources?: readonly number[] | undefined } | undefined;
+          }
+        | undefined;
+}
+
+/**
+ * The injectable object (spec 3.3); at P3 it carries forceAtlas2, release and dispose -- the algorithm members
+ * arrive with P7+.
+ * Exported: implemented by src/accelerator.ts (P3-T3); re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator {
+    readonly kind: "webgpu";
+    readonly ctx: GpuContext;
+    readonly options: Readonly<AcceleratorOptions>;
+    forceAtlas2(options?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats>;
+    release(s: GraphSnapshot): void;
+    dispose(): void;
+}

package/src/types/context.ts

@@ -0,0 +1,135 @@
+/**
+ * Context and capability types (spec 2.2, 3.3; contract 3.3). Types only: the file imports the error class
+ * as a type, so every layer may `import type` from it without a value edge (the src/types zone of the
+ * package eslint config). P0-T3 wrote AdapterInfoLike and AdapterSummary; P1-T1 completes the file.
+ */
+
+import type { WebGpuGraphError } from "../errors.js";
+
+/** The limits `"raise"` takes from the adapter (spec 2.2); maxComputeWorkgroupsPerDimension is deliberately absent. */
+export type RaisableLimit =
+    | "maxBufferSize"
+    | "maxStorageBufferBindingSize"
+    | "maxStorageBuffersPerShaderStage"
+    | "maxComputeWorkgroupStorageSize"
+    | "maxComputeInvocationsPerWorkgroup"
+    | "maxComputeWorkgroupSizeX";
+
+/** How `create()` builds `requiredLimits` (spec 2.2 step 3). */
+export type LimitPolicy = "default" | "raise" | Readonly<Partial<Record<RaisableLimit, number>>>;
+
+/** Options of GpuContext.create (spec 2.2). */
+export interface GpuContextOptions {
+    /** browser: navigator.gpu; Node: the handle of createNodeGpu(). */
+    readonly gpu?: GPU | undefined;
+    /** Skips requestAdapter(); the adapter must be UNUSED (spec 2.2 step 1). */
+    readonly adapter?: GPUAdapter | undefined;
+    /** Adopts a device the caller owns (ownsDevice false). */
+    readonly device?: GPUDevice | undefined;
+    /** Default "high-performance". */
+    readonly powerPreference?: GPUPowerPreference | undefined;
+    /** Default false; true -> E_SOFTWARE_ONLY instead of a device on lavapipe / SwiftShader. */
+    readonly rejectSoftware?: boolean | undefined;
+    /** Default "raise". */
+    readonly limits?: LimitPolicy | undefined;
+    /** Default ["subgroups", "timestamp-query"]; requested only when the adapter has them. */
+    readonly optionalFeatures?: readonly GPUFeatureName[] | undefined;
+    /** Default []; a missing one -> E_NO_DEVICE. */
+    readonly requiredFeatures?: readonly GPUFeatureName[] | undefined;
+    /** The device label and the context label (default "webgpu-graph-algorithms"). */
+    readonly label?: string | undefined;
+    /** The uncapturederror sink; default: keep the last error and throw it from the next public call (spec 5.7). */
+    readonly onError?: ((error: WebGpuGraphError) => void) | undefined;
+    /** Default 2: console.warn once when more snapshots than this are resident (spec 4.1). */
+    readonly warnUnreleasedSnapshots?: number | undefined;
+    /** CONTRACT DECISION: set by the ./browser and ./node entries ("browser" / "node"), never by sniffing globals (spec 2.2 step 4); consumers leave it unset ("unknown"). */
+    readonly runtime?: "browser" | "node" | "unknown" | undefined;
+}
+
+/** The structural subset of GPUAdapterInfo the package reads (CONTRACT DECISION: structural so tests can fake it without the __brand of @webgpu/types). */
+export interface AdapterInfoLike {
+    readonly vendor: string;
+    readonly architecture: string;
+    readonly device: string;
+    readonly description: string;
+    readonly isFallbackAdapter?: boolean | undefined;
+    readonly subgroupMinSize?: number | undefined;
+    readonly subgroupMaxSize?: number | undefined;
+}
+
+/** What the app displays or logs about an adapter (spec 2.2). */
+export interface AdapterSummary {
+    readonly vendor: string;
+    readonly architecture: string;
+    readonly device: string;
+    readonly description: string;
+    readonly software: boolean;
+    readonly subgroupMinSize: number;
+    readonly subgroupMaxSize: number;
+    readonly features: readonly string[];
+    readonly limits: Readonly<Record<string, number>>;
+}
+
+/** Result of GpuContext.probe (spec 2.2); `adapter` is the UNUSED adapter to pass to create({ adapter }). */
+export interface ProbeResult {
+    readonly ok: boolean;
+    readonly code: "OK" | "E_NO_WEBGPU" | "E_NO_ADAPTER" | "E_SOFTWARE_ONLY";
+    readonly reason: string | null;
+    readonly adapter: GPUAdapter | null;
+    readonly summary: AdapterSummary | null;
+}
+
+/** Options of GpuContext.probe (spec 2.2). `gpu` may be undefined so an app can pass `navigator.gpu` without a guard: undefined -> E_NO_WEBGPU. */
+export interface ProbeOptions {
+    readonly gpu: GPU | undefined;
+    readonly powerPreference?: GPUPowerPreference | undefined;
+    readonly rejectSoftware?: boolean | undefined;
+}
+
+/** The limits every planner reads; GPUSupportedLimits is structurally assignable to it (CONTRACT DECISION: planners take PlanCaps so faked tables need no cast). */
+export interface PlanLimits {
+    readonly maxBufferSize: number;
+    readonly maxStorageBufferBindingSize: number;
+    readonly maxStorageBuffersPerShaderStage: number;
+    readonly minStorageBufferOffsetAlignment: number;
+    readonly minUniformBufferOffsetAlignment: number;
+    readonly maxComputeWorkgroupsPerDimension: number;
+    readonly maxComputeInvocationsPerWorkgroup: number;
+    readonly maxComputeWorkgroupSizeX: number;
+    readonly maxComputeWorkgroupStorageSize: number;
+    readonly maxUniformBufferBindingSize: number;
+}
+
+/** The capability record every planner and kernel reads (spec 3.3). */
+export interface GpuCaps {
+    /** device.limits (never adapter.limits, spec 2.2 step 4). */
+    readonly limits: GPUSupportedLimits;
+    /** device.features. */
+    readonly features: ReadonlySet<string>;
+    /** navigator.gpu.wgslLanguageFeatures / the Dawn equivalent; informational only (never relied on). */
+    readonly wgslFeatures: ReadonlySet<string>;
+    /** 0 when the "subgroups" feature is absent from the device. */
+    readonly subgroupMinSize: number;
+    /** 0 when the "subgroups" feature is absent from the device. */
+    readonly subgroupMaxSize: number;
+    readonly software: boolean;
+    readonly runtime: "browser" | "node" | "unknown";
+    readonly vendor: string;
+    readonly architecture: string;
+    readonly device: string;
+    readonly description: string;
+}
+
+/** What the pure planners need of GpuCaps: `limits` narrowed to PlanLimits plus the four scalar facts. A GpuCaps IS a PlanCaps. */
+export interface PlanCaps {
+    readonly limits: PlanLimits;
+    readonly features: ReadonlySet<string>;
+    readonly subgroupMinSize: number;
+    readonly subgroupMaxSize: number;
+    readonly software: boolean;
+}
+
+/** Mutable test-build flags on a context (@internal; set by test/setup/gpu.ts from GRAPHTY_GPU_INSPECT, spec 11.9 item 2). */
+export interface GpuDebugFlags {
+    inspect: boolean;
+}

package/src/types/layout.ts

@@ -0,0 +1,103 @@
+/**
+ * The layout-facing public types (spec 3.3, 7.19): the stats records, the GPU simulation interface that extends the
+ * design-14.3 LayoutSimulation mirror, the run options and the GPU-only tuning knobs. Types only.
+ */
+
+import type { F32, GraphSnapshot, NodeMask } from "@graphty/graph-format";
+
+import type { LayoutSimulation } from "./accelerator.js";
+
+/** Spec 3.3 LayoutStatsBase, verbatim; the three grid fields are null on the exact tier (P3 always). */
+export interface LayoutStatsBase {
+    readonly iteration: number;
+    readonly meanDisplacement: number;
+    readonly rmsRadius: number;
+    readonly layoutRadius: number;
+    readonly centroid: readonly [number, number, number];
+    readonly repulsionTier: "exact" | "grid";
+    readonly maxCellOccupancy: number | null;
+    readonly outsideGrid: number | null;
+    readonly msPerIteration: number | null;
+}
+
+/**
+ * One per-iteration trace record of the last completed batch (spec 3.3 ForceAtlas2Stats.trace element).
+ * Exported: the element type of ForceAtlas2Stats.trace; re-exported from src/index.ts at P3-T3.
+ * @public
+ */
+export interface ForceAtlas2TraceRecord {
+    readonly swing: number;
+    readonly traction: number;
+    readonly speed: number;
+    readonly speedEfficiency: number;
+    readonly meanDisplacement: number;
+    readonly settledCount: number;
+}
+
+/** Spec 3.3 ForceAtlas2Stats, verbatim. */
+export interface ForceAtlas2Stats extends LayoutStatsBase {
+    readonly swing: number;
+    readonly traction: number;
+    readonly speed: number;
+    readonly speedEfficiency: number;
+    readonly trace: ReadonlyArray<ForceAtlas2TraceRecord>;
+}
+
+/** Options of GpuLayoutSimulation.run (spec 3.3). */
+export interface RunOptions {
+    readonly maxIter?: number | undefined;
+    readonly batch?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+
+/** Spec 3.3 GpuLayoutSimulation, verbatim (LayoutSimulation is the design-14.3 mirror of accelerator.ts). */
+export interface GpuLayoutSimulation<Options, Stats extends LayoutStatsBase> extends LayoutSimulation {
+    load(snapshot: GraphSnapshot, positions: F32): void;
+    /**
+     * Submits k iterations; resolves when their batch has been read back into `positions`. With `maxInFlight`
+     * batches in flight the call COALESCES: nothing is queued and the OLDEST pending batch's promise is returned
+     * (spec 7.19 item 3).
+     * @param iterations - the number of iterations to submit (default `iterationsPerStep`)
+     * @returns resolves when the batch carrying them has landed in the owner's array
+     */
+    step(iterations?: number): Promise<void>;
+    readonly settled: boolean;
+    setFixed(mask: NodeMask): void;
+    setPosition(index: number, x: number, y: number, z: number): void;
+    dispose(): void;
+    readonly inFlight: number;
+    readonly iterationsDone: number;
+    readonly stats: Stats;
+    flush(): Promise<void>;
+    reheat(): void;
+    setParams(patch: Partial<Options>): void;
+    run(options?: RunOptions): Promise<Stats>;
+    inspect?(name: string): Promise<Float32Array | Uint32Array>;
+}
+
+/**
+ * Spec 3.3 GpuLayoutTuning, verbatim; the grid knobs are accepted and stored in P3 but only `repulsion`,
+ * `exactMaxNodes`, `deterministic` and `compat` have an effect (grid tier = P4).
+ */
+export interface GpuLayoutTuning {
+    readonly repulsion?: "exact" | "grid" | "auto" | undefined;
+    readonly exactMaxNodes?: number | undefined;
+    readonly nearMax?: number | undefined;
+    readonly deterministic?: boolean | undefined;
+    readonly gridMax2D?: number | undefined;
+    readonly gridMax3D?: number | undefined;
+    readonly extentFactor?: number | undefined;
+    readonly compat?: "paper" | "networkx" | undefined;
+}
+
+/** The resolved tuning record (defaults from constants.ts LAYOUT_TUNING_DEFAULTS applied). */
+export interface ResolvedLayoutTuning {
+    readonly repulsion: "exact" | "grid" | "auto";
+    readonly exactMaxNodes: number;
+    readonly nearMax: number;
+    readonly deterministic: boolean;
+    readonly gridMax2D: number;
+    readonly gridMax3D: number;
+    readonly extentFactor: number;
+    readonly compat: "paper" | "networkx";
+}

package/src/types/memory.ts

@@ -0,0 +1,23 @@
+/**
+ * The two types the memory AND the kernel layers share (spec 4.1, 4.2; contract 3.3 CONTRACT DECISION):
+ * they live here so src/kernel/kernel.ts never imports src/memory/** for a type and the layer graph has no
+ * P1 cycle (test/layers.test.ts). Types only; GPUBuffer is the ambient @webgpu/types global.
+ */
+
+/** One 64-arc-aligned window of colIdx / weights (spec 4.2). P1-P3 PLAN windows; executing them is P4. */
+export interface ArcWindow {
+    readonly start: number;
+    readonly end: number;
+    readonly rowFirst: number;
+    readonly rowLast: number;
+    readonly bufferIndex: number;
+    readonly offset: number;
+}
+
+/** A storage-buffer range (spec 4.1); `window` is non-null only for a binding of one arc window. */
+export interface Binding {
+    readonly buffer: GPUBuffer;
+    readonly offset: number;
+    readonly size: number;
+    readonly window: ArcWindow | null;
+}

package/src/types/options.ts

@@ -0,0 +1,84 @@
+/**
+ * The option records of the layouts (spec 9.3, 7.14): structural mirrors of @graphty/layout's option types (D27),
+ * copied field for field so a `ForceAtlas2Options` object the element parses is accepted here without a cast. Types
+ * only: this file imports nothing at runtime.
+ */
+
+import type { F32, NodeId, NodeMask } from "@graphty/graph-format";
+
+/** Design 14.3 CommonLayoutOptions, mirrored verbatim. */
+export interface CommonLayoutOptions {
+    readonly dim?: 2 | 3 | undefined;
+    readonly scale?: number | undefined;
+    readonly center?: ArrayLike<number> | undefined;
+    readonly seed?: number | null | undefined;
+}
+
+/** Spec 9.3 SimulationOptions, mirrored verbatim (layout-owned; the CPU simulations ignore maxInFlight). */
+export interface SimulationOptions {
+    readonly settleThreshold?: number | undefined;
+    readonly settleWindow?: number | undefined;
+    readonly iterationsPerStep?: number | undefined;
+    readonly maxInFlight?: number | undefined;
+}
+
+/**
+ * Spec 9.3 ForceAtlas2Options, mirrored verbatim (same names and defaults as
+ * layout/src/layouts/force-directed/forceatlas2.ts lines 26-42).
+ */
+export interface ForceAtlas2Options extends CommonLayoutOptions, SimulationOptions {
+    readonly maxIter?: number | undefined;
+    readonly jitterTolerance?: number | undefined;
+    readonly scalingRatio?: number | undefined;
+    readonly gravity?: number | undefined;
+    readonly strongGravity?: boolean | undefined;
+    readonly distributedAction?: boolean | undefined;
+    readonly linlog?: boolean | undefined;
+    readonly nodeMass?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
+    readonly nodeSize?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
+    readonly weight?: boolean | string | null | undefined;
+    readonly dissuadeHubs?: boolean | undefined;
+}
+
+/** Spec 9.3 FruchtermanReingoldOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
+export interface FruchtermanReingoldOptions extends CommonLayoutOptions, SimulationOptions {
+    readonly k?: number | null | undefined;
+    readonly iterations?: number | undefined;
+    readonly fixed?: NodeMask | string | null | undefined;
+}
+
+/** Spec 9.3 SpringElectricalOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
+export interface SpringElectricalOptions extends CommonLayoutOptions, SimulationOptions {
+    readonly springLength?: number | undefined;
+    readonly springCoefficient?: number | undefined;
+    readonly gravity?: number | undefined;
+    readonly dragCoefficient?: number | undefined;
+    readonly timeStep?: number | undefined;
+}
+
+/**
+ * The resolved (defaults applied) ForceAtlas2 option record the simulation keeps; every field present.
+ * Exported: consumed by src/layouts/forceatlas2.ts (P3-T2, resolveForceAtlas2Options) and the option tests.
+ * @public
+ */
+export interface ResolvedForceAtlas2Options {
+    readonly maxIter: number;
+    readonly jitterTolerance: number;
+    readonly scalingRatio: number;
+    readonly gravity: number;
+    readonly strongGravity: boolean;
+    readonly distributedAction: boolean;
+    readonly linlog: boolean;
+    readonly nodeMass: F32 | string | Readonly<Record<NodeId, number>> | null;
+    readonly nodeSize: F32 | string | Readonly<Record<NodeId, number>> | null;
+    readonly weight: boolean | string | null;
+    readonly dissuadeHubs: boolean;
+    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/types/run.ts

@@ -0,0 +1,13 @@
+/**
+ * The run options every algorithm function accepts beside its own (spec 3.3, design 10.7; contract 3.3).
+ * Types only.
+ */
+
+/** Options every algorithm function accepts in addition to its own (spec 3.3, design 10.7). */
+export interface GpuRunOptions {
+    /** A preallocated destination of exact length; E_INVALID_ARGUMENT when the length does not match. */
+    readonly dest?: Float32Array | Uint32Array | undefined;
+    /** Checked between batches; E_ABORTED. */
+    readonly signal?: AbortSignal | undefined;
+    readonly onProgress?: ((done: number, total: number) => void) | undefined;
+}

package/src/wgsl/degree.wgsl.ts

@@ -0,0 +1,24 @@
+/**
+ * The `degree` kernel body (contract 4.5; spec 6 row 3, 11.5): the out-degree of every row of `[P.start, P.end)`
+ * through the row-walking gather with the USE_PERM dummy pattern, counting the arcs of the bound window whose
+ * neighbour index is a valid node; `P.accumulate == 1` adds into `out[i]` instead of overwriting (the P4 windowed
+ * loop). Bindings, overrides and the `RangeParams` block come from the registry entry (src/kernels.ts); WG,
+ * USE_PERM and `linear_id` from the prelude. The text is normative: test/helpers/sabotage.ts mutates it textually,
+ * so it is copied from the contract and never re-derived or restyled.
+ */
+export const degreeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn degree(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let row = linear_id(wid, lid.x) + P.start;
+    if (row >= P.end) { return; }
+    let i = select(row, perm[row], USE_PERM);
+    let a0 = max(rowPtr[i], P.arcBase);
+    let a1 = min(rowPtr[i + 1u], P.arcEnd);
+    var d = 0u;
+    for (var arc = a0; arc < a1; arc = arc + 1u) {
+        let nbr = colIdx[arc - P.arcBase];               // \`target\` is a WGSL reserved word (spec 16.2); never use it as an identifier
+        d = d + select(0u, 1u, nbr < P.n);
+    }
+    out[i] = select(d, out[i] + d, P.accumulate == 1u);
+}
+`;

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

@@ -0,0 +1,37 @@
+/**
+ * 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`).
+ *
+ * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5) are textual edits of it.
+ */
+
+/** The K2 body: entry point `attraction`; an early return is legal here because no barrier follows (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);
+    let pi = pos[i];                                           // xyz + mass in one load (D23)
+    var f = vec3f(0.0);
+    for (var a = rowPtr[i]; a < rowPtr[i + 1u]; a = a + 1u) {
+        let j = colIdx[a];
+        if (j == i) { continue; }                              // a self-loop exerts no force
+        var w = 1.0;
+        if (HAS_WEIGHTS) { w = weights[a]; }
+        let d = pos[j].xyz - pi.xyz;                           // toward j
+        let len = max(length(d), FA2_DIST_FLOOR);
+        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; }
+    store_force(i, f);                                         // overwrites: attraction is the first writer of force each iteration
+}`;