@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.1

package/package.json

@@ -1,26 +1,117 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @graphty/webgpu-graph-algorithms",
-  "license": "MIT",
+  "version": "0.2.1",
+  "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/graphty-org/webgpu-graph-algorithms.git",
-    "directory": "packages/webgpu-graph-algorithms"
-  },
-  "homepage": "https://github.com/graphty-org/webgpu-graph-algorithms#readme",
-  "bugs": {
-    "url": "https://github.com/graphty-org/webgpu-graph-algorithms/issues"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
+  "type": "module",
+  "main": "dist/webgpu-graph-algorithms.js",
+  "types": "dist/webgpu-graph-algorithms.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/webgpu-graph-algorithms.d.ts",
+      "import": "./dist/webgpu-graph-algorithms.js",
+      "default": "./dist/webgpu-graph-algorithms.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
+    }
   },
+  "sideEffects": false,
   "files": [
     "dist/",
     "src/",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphty-org/graphty-monorepo.git",
+    "directory": "webgpu-graph-algorithms"
+  },
+  "keywords": [
+    "graph",
+    "webgpu",
+    "wgsl",
+    "gpu",
+    "graph-algorithms",
+    "force-directed",
+    "forceatlas2",
+    "layout",
+    "graph-format"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/graphty-org/graphty-monorepo/issues"
+  },
+  "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/webgpu-graph-algorithms#readme",
+  "dependencies": {
+    "@webgpu/types": "^0.1.72",
+    "@graphty/graph-format": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@graphty/algorithms": "^1.0.0",
+    "@graphty/graph-format": "^1.0.0",
+    "@graphty/layout": "^1.0.0",
+    "webgpu": ">=0.4.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@graphty/algorithms": {
+      "optional": true
+    },
+    "@graphty/layout": {
+      "optional": true
+    },
+    "webgpu": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/browser": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "fast-check": "^4.2.0",
+    "playwright": "^1.54.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.5",
+    "vitest": "^3.2.4",
+    "webgpu": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:bundle": "node scripts/build-bundle.js",
+    "build:all": "npm run build && npm run build:bundle",
+    "lint": "eslint && tsc --noEmit -p tsconfig.json && tsc -p tsconfig.strict-consumer.json",
+    "lint:fix": "eslint --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:strict-consumer": "tsc -p tsconfig.strict-consumer.json",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run --project=node",
+    "test:node": "vitest run --project=node",
+    "test:browser": "vitest run --project=browser",
+    "test:browser:ci": "node scripts/run-browser-project.js",
+    "test:limits": "vitest run --project=node-limits",
+    "coverage": "vitest run --project=node --coverage",
+    "coverage:preview": "npx serve coverage -p 9058",
+    "bench": "tsx benchmarks/run.ts",
+    "bench:compare": "node scripts/bench-compare.js",
+    "benchmark": "tsx benchmarks/run.ts",
+    "gpu:report": "node scripts/gpu-report.js",
+    "ready:commit": "npm run build:all && npm run lint && npm run test:node"
+  }
+}

package/src/accelerator.ts

@@ -0,0 +1,117 @@
+/**
+ * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
+ * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
+ * src/types/accelerator.ts until W1, D27). At P3 it carries `forceAtlas2`, `release` and `dispose` and nothing
+ * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.pageRank !== undefined` and
+ * route to the CPU when the member is absent (spec 2.4 row "method missing"), so a method the GPU does not
+ * implement must not exist here -- never a throwing stub. The algorithm members arrive one per shipped algorithm
+ * from P7; `fruchtermanReingold` / `springElectrical` with P5.
+ */
+
+import { type GraphSnapshot } from "@graphty/graph-format";
+
+import { type GpuContext } from "./context.js";
+import { createForceAtlas2 } from "./layouts/forceatlas2.js";
+import { type AcceleratorOptions, type GpuAccelerator } from "./types/accelerator.js";
+import { type ForceAtlas2Stats, type GpuLayoutSimulation, type GpuLayoutTuning } from "./types/layout.js";
+import { type ForceAtlas2Options } from "./types/options.js";
+
+/** The `algorithms` record of AcceleratorOptions (spec 3.3), named for the copy helpers. */
+type AlgorithmDefaults = NonNullable<AcceleratorOptions["algorithms"]>;
+
+/** The `algorithms.betweenness` record of AcceleratorOptions (spec 3.3: the `k` / `sources` defaults until A2). */
+type BetweennessDefaults = NonNullable<AlgorithmDefaults["betweenness"]>;
+
+/**
+ * Frozen copy of the betweenness defaults; `sources` is copied into a fresh frozen array so a later mutation of
+ * the caller's list is never seen by the accelerator.
+ * @param defaults - the caller's record
+ * @returns the frozen copy
+ */
+function copyBetweenness(defaults: BetweennessDefaults): BetweennessDefaults {
+    const copy: { k?: number | undefined; sources?: readonly number[] | undefined } = { ...defaults };
+    if (defaults.sources !== undefined) {
+        copy.sources = Object.freeze([...defaults.sources]);
+    }
+    return Object.freeze(copy);
+}
+
+/**
+ * Frozen copy of the algorithms record, one level deeper for `betweenness`.
+ * @param algorithms - the caller's record
+ * @returns the frozen copy
+ */
+function copyAlgorithms(algorithms: AlgorithmDefaults): AlgorithmDefaults {
+    const copy: { betweenness?: BetweennessDefaults | undefined } = { ...algorithms };
+    if (algorithms.betweenness !== undefined) {
+        copy.betweenness = copyBetweenness(algorithms.betweenness);
+    }
+    return Object.freeze(copy);
+}
+
+/**
+ * The frozen deep copy of the accelerator options (spec 3.3 GpuAccelerator.options: "the tuning defaults given
+ * to createAccelerator; frozen"; contract 3.14): the record, its `layout` tuning, its `algorithms` record, the
+ * `betweenness` record and the `sources` list are each fresh frozen objects, so neither the caller's later edits
+ * nor a consumer's writes can change what the accelerator's simulations inherit.
+ * @param options - the caller's options, or undefined
+ * @returns the frozen copy (an empty frozen record when nothing was given)
+ */
+function freezeOptions(options: AcceleratorOptions | undefined): Readonly<AcceleratorOptions> {
+    if (options === undefined) {
+        return Object.freeze({});
+    }
+    const copy: { layout?: GpuLayoutTuning | undefined; algorithms?: AlgorithmDefaults | undefined } = { ...options };
+    if (options.layout !== undefined) {
+        copy.layout = Object.freeze({ ...options.layout });
+    }
+    if (options.algorithms !== undefined) {
+        copy.algorithms = copyAlgorithms(options.algorithms);
+    }
+    return Object.freeze(copy);
+}
+
+/**
+ * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
+ * structurally; at P3 it carries forceAtlas2, release and dispose. One per call (the app creates one and injects
+ * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
+ * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
+ * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
+ * `release(s)` is `ctx.release(s)`; `dispose()` is `ctx.dispose()`.
+ * @param ctx - the context every simulation the accelerator creates runs on
+ * @param options - GPU-only defaults inherited by every simulation (`layout`) and, from P9, the algorithm defaults
+ * @returns the injectable accelerator
+ * @throws E_DISPOSED / E_DEVICE_LOST from `ctx.assertReady()` (here and inside `forceAtlas2()`); `forceAtlas2()`
+ *   also throws what createForceAtlas2 throws (E_UNSUPPORTED for `nodeSize`, E_INVALID_ARGUMENT for a bad range)
+ */
+export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions): GpuAccelerator {
+    ctx.assertReady();
+    const frozen = freezeOptions(options);
+    return {
+        kind: "webgpu",
+        ctx,
+        options: frozen,
+        /**
+         * The ForceAtlas2 simulation with this accelerator's layout tuning (spec 3.3; contract 3.14).
+         * @param o - the CPU option type (spec 9.3 ForceAtlas2Options); GPU tuning keys come from `options.layout`
+         * @returns a fresh simulation in state "created"
+         */
+        forceAtlas2(o?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats> {
+            ctx.assertReady();
+            return createForceAtlas2(ctx, { ...o, ...frozen.layout });
+        },
+        /**
+         * Destroys every device buffer recorded for the snapshot (spec 4.5); delegates to ctx.release.
+         * @param s - the snapshot the app is done with
+         */
+        release(s: GraphSnapshot): void {
+            ctx.release(s);
+        },
+        /**
+         * Disposes the context (spec 2.8); delegates to ctx.dispose, idempotent.
+         */
+        dispose(): void {
+            ctx.dispose();
+        },
+    };
+}

package/src/algorithms/degree.ts

@@ -0,0 +1,142 @@
+/**
+ * `degree(ctx, s)` -- the walking-skeleton algorithm, kept public as a diagnostic (spec 3.3, 11.5): the out-degree of
+ * every node computed on the device by the row-walking `degree` kernel (4.5) over the resident core of the snapshot,
+ * with the group-0 dummy-binding pattern of spec 3.5 (`colIdx` in the `weights` slot when the snapshot is unweighted,
+ * `rowPtr` in the `perm` slot because P1-P3 pass no row permutation, so `USE_PERM` is false). The result equals
+ * `snapshot.outDegree()`; the point of the kernel is to prove the upload, bind, dispatch and readback path end to end
+ * on every adapter (bitwise identical across adapters, spec 11.5), not to be faster than the CPU (the README says
+ * so).
+ *
+ * Contract (3.12): `ctx.assertReady()` first; `nodeCount === 0` returns an empty `Uint32Array` (or `dest`) with no
+ * GPU work (spec 5.6: there is no work, which is not a fallback); an already-aborted `signal` is `E_ABORTED` before
+ * any work; `dest` must be a `Uint32Array` of length n over an `ArrayBuffer`; a windowed core is `E_TOO_LARGE
+ * { path: "windowed", algorithm: "degree" }` until P4 executes windows -- `residency.core()` (3.8) throws that error
+ * itself with `algorithm: null` before it would ever return a windowed `CoreBinding`, so `degree` catches it and
+ * re-throws the same error with `algorithm: "degree"` (the 3.12 detail) instead of testing `core.plan`, which never
+ * observes "windowed" in P1-P3; `arcCount === 0` skips the dispatch (only `rowPtr` is resident)
+ * and the result is zeros; otherwise ONE dispatch over rows [0, n) with `accumulate = 0` (every row is written, so no
+ * fill precedes it), a readback into the result, `onProgress(1, 1)`, and the scratch returned in a finally. Two runs
+ * are bitwise identical (spec 11.9 item 4).
+ */
+
+import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
+
+import { type GpuContext } from "../context.js";
+import { BufferUsage } from "../device/webgpu-constants.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { graphBindings, graphOverrides, kernelSpec, RANGE_PARAMS } from "../kernels.js";
+import { type CoreBinding } from "../memory/residency.js";
+import { type Binding } from "../types/memory.js";
+import { type GpuRunOptions } from "../types/run.js";
+
+/**
+ * Validates `options.dest` for a result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @returns the destination as a U32, or null when none was given
+ */
+function checkDest(dest: Float32Array | Uint32Array | undefined, n: number): U32 | null {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Uint32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest as U32;
+    }
+    throw new WebGpuGraphError(
+        "E_INVALID_ARGUMENT",
+        `degree: dest must be a Uint32Array of length ${n} over an ArrayBuffer`,
+        {
+            argument: "dest",
+            value: `${dest.constructor.name}(${dest.length})`,
+            expected: `Uint32Array(${n}) over an ArrayBuffer`,
+        },
+    );
+}
+
+/**
+ * Uploads (or finds) the core through the residency; a windowed plan, which the residency reports as `E_TOO_LARGE
+ * { path: "windowed", algorithm: null }` (3.8), is re-thrown with `algorithm: "degree"` (3.12) and its other details
+ * (`needed`, `limit`, `path`) kept. Every other error passes through untouched.
+ * @param ctx - the context whose residency holds the core
+ * @param s - the snapshot
+ * @returns the resident core binding (arena or perArray)
+ */
+function coreOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding {
+    try {
+        return ctx.residency.core(s);
+    } catch (error: unknown) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError(
+                "E_TOO_LARGE",
+                "degree: the arc arrays need a windowed upload, which P1-P3 plan but do not execute",
+                { ...error.details, algorithm: "degree" },
+            );
+        }
+        throw error;
+    }
+}
+
+/**
+ * The walking-skeleton kernel, kept public as a diagnostic (spec 3.3): out-degree per node through the row-walking
+ * gather with the USE_PERM dummy pattern; equals snapshot.outDegree().
+ * @param ctx - the context whose device runs the kernel
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dest / signal / onProgress (spec 3.3). PLAN DECISION: spelled `?: GpuRunOptions` rather than the
+ *   contract's `?: GpuRunOptions | undefined` because the root ESLint rule no-duplicate-type-constituents rejects the
+ *   explicit undefined on an optional parameter (the call signature is identical; P1-T3 made the same choice).
+ * @returns the out-degree of every node, index-aligned (`dest` itself when given)
+ */
+export async function degree(ctx: GpuContext, s: GraphSnapshot, options?: GpuRunOptions): Promise<U32> {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const dest = checkDest(options?.dest, n);
+    if (options?.signal?.aborted) {
+        throw new WebGpuGraphError("E_ABORTED", "degree: the signal was aborted before any work started", {});
+    }
+    if (n === 0) {
+        options?.onProgress?.(1, 1);
+        return dest ?? new Uint32Array(0);
+    }
+    const core = coreOf(ctx, s);
+    if (s.arcCount === 0) {
+        const zeros = dest ?? new Uint32Array(n);
+        zeros.fill(0);
+        options?.onProgress?.(1, 1);
+        return zeros;
+    }
+    const byteLength = n * 4;
+    const out = ctx.pool.acquire(
+        byteLength,
+        BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST,
+        "degree/out",
+    );
+    const params = ctx.pool.acquire(
+        RANGE_PARAMS.byteLength,
+        BufferUsage.UNIFORM | BufferUsage.COPY_DST,
+        "degree/params",
+    );
+    try {
+        await ctx.allocator.check();
+        const kernel = await ctx.pipelines.kernel(kernelSpec("degree", graphOverrides(core, null)));
+        const bytes = new ArrayBuffer(RANGE_PARAMS.byteLength);
+        RANGE_PARAMS.write(new DataView(bytes), { start: 0, end: n, arcBase: 0, arcEnd: s.arcCount, accumulate: 0, n });
+        ctx.device.queue.writeBuffer(params, 0, bytes);
+        const outBinding: Binding = { buffer: out, offset: 0, size: byteLength, window: null };
+        const paramsBinding: Binding = { buffer: params, offset: 0, size: RANGE_PARAMS.byteLength, window: null };
+        const bound = kernel.bind({ ...graphBindings(core, null), out: outBinding, P: paramsBinding });
+        const encoder = ctx.device.createCommandEncoder({ label: "degree" });
+        const pass = encoder.beginComputePass({ label: "degree" });
+        kernel.dispatch(pass, bound, plan1d(n, ctx.workgroupSize, ctx.caps), [0]);
+        pass.end();
+        ctx.device.queue.submit([encoder.finish()]);
+        ctx.assertReady();
+        const result = await ctx.readback.read(out, byteLength, dest ?? undefined);
+        ctx.assertReady();
+        options?.onProgress?.(1, 1);
+        return dest ?? new Uint32Array(result);
+    } finally {
+        ctx.pool.release(params);
+        ctx.pool.release(out);
+    }
+}

package/src/browser/index.ts

@@ -0,0 +1,57 @@
+/// <reference types="@webgpu/types" preserve="true" />
+/**
+ * The ./browser entry (spec 2.1, 2.3, 3.4; contract 3.6): the only directory of the package allowed to read
+ * navigator.gpu. probeBrowserWebGpu never throws; requestGpuContext tags the context runtime "browser".
+ */
+
+import { GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import type { GpuContextOptions, ProbeResult } from "../types/context.js";
+
+/** Options of the browser helpers (spec 3.4); a type alias, not an empty `extends` interface, which strictTypeChecked's no-empty-object-type (allowInterfaces "never") reports. */
+export type BrowserGpuOptions = Omit<GpuContextOptions, "gpu" | "device" | "runtime">;
+
+/**
+ * navigator.gpu, or undefined when the runtime has no navigator or no WebGPU (Node 22 has a navigator
+ * without gpu; browsers without WebGPU have navigator.gpu undefined).
+ * @returns the GPU object or undefined
+ */
+function navigatorGpu(): GPU | undefined {
+    if (typeof navigator === "undefined") {
+        return undefined;
+    }
+    const candidate: { readonly gpu?: GPU | undefined } = navigator;
+    return candidate.gpu;
+}
+
+/**
+ * navigator.gpu absent -> { ok: false, code: "E_NO_WEBGPU" }; else GpuContext.probe. Never throws.
+ * @param options - the power preference and the software policy
+ * @returns the probe result
+ */
+export function probeBrowserWebGpu(options?: BrowserGpuOptions): Promise<ProbeResult> {
+    return GpuContext.probe({
+        gpu: navigatorGpu(),
+        powerPreference: options?.powerPreference ?? "high-performance",
+        rejectSoftware: options?.rejectSoftware,
+    });
+}
+
+/**
+ * GpuContext.create({ gpu: navigator.gpu, powerPreference: "high-performance", runtime: "browser", ...options });
+ * pass `{ adapter: probe.adapter }` to reuse the probed adapter; create() honours rejectSoftware.
+ * @param options - see BrowserGpuOptions
+ * @returns the context
+ */
+export function requestGpuContext(options?: BrowserGpuOptions): Promise<GpuContext> {
+    const gpu = navigatorGpu();
+    if (gpu === undefined && options?.adapter === undefined) {
+        return Promise.reject(
+            new WebGpuGraphError("E_NO_WEBGPU", "navigator.gpu is undefined: this browser or context has no WebGPU", {
+                reason: "navigator.gpu is undefined",
+                hint: "WebGPU needs a supporting browser and a secure context (https or localhost)",
+            }),
+        );
+    }
+    return GpuContext.create({ powerPreference: "high-performance", ...options, gpu, runtime: "browser" });
+}

package/src/constants.ts

@@ -0,0 +1,116 @@
+/**
+ * Every numeric constant the package and the WGSL prelude share (spec 3.1, 3.5, 5.2, 7.8, 7.14, 7.17;
+ * contract 3.2). The prelude (src/kernel/prelude.ts, P1-T3) interpolates these values and never retypes them
+ * as literals (the literal grep of spec 3.5 enforces it); the planners read them; test/device/constants.test.ts
+ * pins them. graph-format's INVALID_INDEX is imported by the prelude directly and is deliberately not copied.
+ */
+
+/** Workgroup size of every 1D kernel; `WG = min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup)` at runtime (spec 5.1). */
+export const WORKGROUP_SIZE = 256;
+/** The spec minimum of maxComputeWorkgroupsPerDimension; asserted equal to the device limit at create() (spec 2.2, 5.2). */
+export const MAX_WORKGROUPS_PER_DIM = 65535;
+/** Items a 1D dispatch of WORKGROUP_SIZE covers: 65535 x 256 = 16,776,960, NOT 2^24 (design 10.6). */
+export const MAX_1D_ITEMS = MAX_WORKGROUPS_PER_DIM * WORKGROUP_SIZE;
+/** The largest u32 (the `min` identity of the u32 reduce); interpolated into the prelude as `U32_MAX` so no body types the literal (contract 4.1). */
+export const U32_MAX = 0xffffffff;
+/** Arc-window boundaries are multiples of 64 arcs = 256 bytes (design 10.6). */
+export const ARC_WINDOW_ALIGN = 64;
+/** Storage-binding offset alignment the package always honours (spec 2.6): the graph-format arena is 256-aligned. */
+export const STORAGE_ALIGN = 256;
+/** Stride of one UniformRing slot: minUniformBufferOffsetAlignment is 256 on every runtime the package targets (spec 5.3). */
+export const UNIFORM_SLOT_BYTES = 256;
+/**
+ * Exact-tier crossover default, re-fixed at G3 by the spec 7.8 rule (spec Q-6; docs/decisions/G3.md section 3): the
+ * largest rung of the T-4 ladder (1k / 4k / 8k / 16k / 32k / 65k, E = 10n, 2D) with <= 4 ms per iteration, rounded down
+ * to a power of two. Measured on the RTX 4070 SUPER under Dawn-node: benchmarks/results/nvidia-lovelace-driver580.json,
+ * session 2026-09-16T02:07:45.933Z, the "ms/iteration (profiler)" rows (the GPU time of the iteration's passes at the
+ * card's working clock; the step(1) wall rows beside them include the 12n readback): 2.560 ms at 32k, 8.405 ms at 65k.
+ * The rule's second clause -- not slower than the grid tier at the same n -- has no grid tier to compare with in P3 and
+ * is re-checked at G4 (spec 7.8). A consumer whose GPU differs (integrated, Apple, T4) passes its own value through
+ * createAccelerator(ctx, { layout: { exactMaxNodes } }); P4's calibrateLayout(ctx) measures it.
+ */
+export const EXACT_MAX_NODES = 32768;
+/** Default number of MAP_READ staging buffers in the Readback ring (spec 4.4). */
+export const DEFAULT_STAGING_SLOTS = 3;
+/** Timestamp query-set size of the Profiler (spec 5.5: "a query set of 256 slots"; 2 slots per pass). */
+export const PROFILER_QUERY_SLOTS = 256;
+/** Byte size above which createBuffer runs inside an "out-of-memory" error scope (spec 5.7). */
+export const OOM_SCOPE_THRESHOLD_BYTES = 16 * 1024 * 1024;
+/** Idle buffers kept per (size class, usage) by the BufferPool (spec 4.4). */
+export const POOL_MAX_IDLE_PER_CLASS = 4;
+/** Smallest power-of-two pool class (spec 4.4). */
+export const POOL_MIN_CLASS_BYTES = 4 * 1024;
+/** Largest power-of-two pool class; above it the classes grow linearly (spec 4.4). */
+export const POOL_MAX_POW2_CLASS_BYTES = 64 * 1024 * 1024;
+/** The linear step of the pool classes above the largest power of two (spec 4.4). */
+export const POOL_LINEAR_STEP_BYTES = 16 * 1024 * 1024;
+/** Default `warnUnreleasedSnapshots` (spec 2.2, 4.1). */
+export const DEFAULT_WARN_UNRELEASED_SNAPSHOTS = 2;
+/** CONTRACT DECISION: the largest `iterations` a single step() records (the trace region and the uniform ring are sized by it); larger values are E_INVALID_ARGUMENT. */
+export const MAX_ITERATIONS_PER_STEP = 256;
+/** Bytes of one Fa2Trace record (spec 7.3: 32-byte records). */
+export const TRACE_RECORD_BYTES = 32;
+/** CONTRACT DECISION: the state header is padded to 256 bytes so the trace region that follows it in the same buffer starts at a legal 256-aligned binding offset (spec 7.3 says "128 + k x 32"; 128 is not a legal storage offset). */
+export const STATE_HEADER_BYTES = 256;
+/** Bytes of one per-workgroup partials record (spec 7.3: exactly 64 B). */
+export const PARTIAL_BYTES = 64;
+/** ForceAtlas2 defaults (spec 7.14, 7.17, 7.19). */
+export const FA2_DEFAULTS: Readonly<{
+    maxIter: 100;
+    jitterTolerance: 1;
+    scalingRatio: 2;
+    gravity: 1;
+    strongGravity: false;
+    distributedAction: false;
+    linlog: false;
+    dissuadeHubs: false;
+    dim: 2;
+    scale: 1;
+    settleThreshold: 0.001;
+    settleWindow: 10;
+    iterationsPerStep: 1;
+    maxInFlight: 2;
+}> = Object.freeze({
+    maxIter: 100,
+    jitterTolerance: 1,
+    scalingRatio: 2,
+    gravity: 1,
+    strongGravity: false,
+    distributedAction: false,
+    linlog: false,
+    dissuadeHubs: false,
+    dim: 2,
+    scale: 1,
+    settleThreshold: 0.001,
+    settleWindow: 10,
+    iterationsPerStep: 1,
+    maxInFlight: 2,
+});
+/** GPU-only layout tuning defaults (spec 7.14): repulsion "auto", exactMaxNodes EXACT_MAX_NODES, nearMax 64, deterministic true, gridMax2D 512, gridMax3D 128, extentFactor 6, compat "paper". */
+export const LAYOUT_TUNING_DEFAULTS: Readonly<{
+    repulsion: "auto";
+    exactMaxNodes: number;
+    nearMax: 64;
+    deterministic: true;
+    gridMax2D: 512;
+    gridMax3D: 128;
+    extentFactor: 6;
+    compat: "paper";
+}> = Object.freeze({
+    repulsion: "auto",
+    exactMaxNodes: EXACT_MAX_NODES,
+    nearMax: 64,
+    deterministic: true,
+    gridMax2D: 512,
+    gridMax3D: 128,
+    extentFactor: 6,
+    compat: "paper",
+});
+/** The distance floor `max(d, 0.01)` of spec 7.2; interpolated into the prelude (contract 4.1). */
+export const FA2_DISTANCE_FLOOR = 0.01;
+/** The square of FA2_DISTANCE_FLOOR. */
+export const FA2_DISTANCE_FLOOR_SQ = 0.0001;
+/** The coincident threshold `d^2 < 1e-8` of spec 7.2. */
+export const FA2_COINCIDENT_SQ = 1e-8;
+/** Bits of Fa2Params.flags (contract 4.4). */
+export const FA2_FLAG_FIRST = 1;