@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/src/device/caps.ts

@@ -0,0 +1,122 @@
+/**
+ * Capability capture (spec 2.2 step 4, 3.3, 5.1, 5.2; contract 3.4): the GpuCaps record of a DEVICE (its
+ * limits and features, never the adapter's), the zero-cost variant for an adopted device, the two planner
+ * facts asserted at create(), and the workgroup size a device runs.
+ */
+
+import { MAX_WORKGROUPS_PER_DIM, WORKGROUP_SIZE } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import type { AdapterInfoLike, GpuCaps, PlanCaps } from "../types/context.js";
+import { isSoftwareAdapter } from "./acquire.js";
+
+/**
+ * Step 4 of create(): the GpuCaps of a DEVICE (device.limits, never adapter.limits) with the adapter info
+ * and the runtime tag. The subgroup sizes are the adapter's only when the device has the "subgroups"
+ * feature, else 0 (spec 3.3).
+ * @param device - the device the caps describe
+ * @param info - the adapter's info (vendor, architecture, subgroup sizes)
+ * @param runtime - the tag the creating entry sets ("unknown" for consumers of the core)
+ * @param wgslFeatures - navigator.gpu.wgslLanguageFeatures or the Dawn equivalent (informational)
+ * @returns the capability record
+ */
+export function captureCaps(
+    device: GPUDevice,
+    info: AdapterInfoLike,
+    runtime: "browser" | "node" | "unknown",
+    wgslFeatures: Iterable<string>,
+): GpuCaps {
+    const features: ReadonlySet<string> = new Set(device.features);
+    const subgroups = features.has("subgroups");
+    return {
+        limits: device.limits,
+        features,
+        wgslFeatures: new Set(wgslFeatures),
+        subgroupMinSize: subgroups ? (info.subgroupMinSize ?? 0) : 0,
+        subgroupMaxSize: subgroups ? (info.subgroupMaxSize ?? 0) : 0,
+        software: isSoftwareAdapter(info),
+        runtime,
+        vendor: info.vendor,
+        architecture: info.architecture,
+        device: info.device,
+        description: info.description,
+    };
+}
+
+/**
+ * GpuContext.from(device, info?): caps from device.limits / device.features and the partial info given;
+ * software false and runtime "unknown" unless given; the subgroup sizes are honoured only when the device
+ * has the feature.
+ * @param device - the adopted device
+ * @param info - what the caller knows about the adapter, if anything
+ * @returns the capability record
+ */
+export function capsFromDevice(device: GPUDevice, info: Partial<GpuCaps> | undefined): GpuCaps {
+    const features: ReadonlySet<string> = new Set(device.features);
+    const subgroups = features.has("subgroups");
+    return {
+        limits: device.limits,
+        features,
+        wgslFeatures: info?.wgslFeatures ?? new Set<string>(),
+        subgroupMinSize: subgroups ? (info?.subgroupMinSize ?? 0) : 0,
+        subgroupMaxSize: subgroups ? (info?.subgroupMaxSize ?? 0) : 0,
+        software: info?.software ?? false,
+        runtime: info?.runtime ?? "unknown",
+        vendor: info?.vendor ?? "",
+        architecture: info?.architecture ?? "",
+        device: info?.device ?? "",
+        description: info?.description ?? "",
+    };
+}
+
+/**
+ * The workgroup size a device runs: min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup) rounded
+ * down to a power of two (spec 5.1; the formula of contract 3.2 / 3.4). maxComputeWorkgroupSizeX is not a term:
+ * every adapter supports its 256 default (WebGPU 3.6.2), so the result never exceeds it. Rounds down by doubling
+ * (no bitwise operator).
+ * @param caps - the capability record (a GpuCaps is a PlanCaps)
+ * @returns the workgroup size
+ */
+export function workgroupSizeFor(caps: PlanCaps): number {
+    const cap = Math.min(WORKGROUP_SIZE, caps.limits.maxComputeInvocationsPerWorkgroup);
+    let size = 1;
+    while (size * 2 <= cap) {
+        size *= 2;
+    }
+    return size;
+}
+
+/**
+ * Asserts the two facts the planners bake in: maxComputeWorkgroupsPerDimension === MAX_WORKGROUPS_PER_DIM
+ * (the prelude's linear_id and plan1d / plan2d use the constant) and WG is a power of two >= 64 (spec 2.2,
+ * 5.2). The limit is never requested, so a device reports the spec default whatever its adapter says.
+ * @param caps - the capability record of the device
+ */
+export function assertPlanLimits(caps: GpuCaps): void {
+    const perDim = caps.limits.maxComputeWorkgroupsPerDimension;
+    if (perDim !== MAX_WORKGROUPS_PER_DIM) {
+        throw new WebGpuGraphError(
+            "E_NO_DEVICE",
+            `maxComputeWorkgroupsPerDimension is ${perDim}; the dispatch planner and the WGSL prelude bake ${MAX_WORKGROUPS_PER_DIM}`,
+            {
+                reason: "maxComputeWorkgroupsPerDimension",
+                adapter: null,
+                requested: MAX_WORKGROUPS_PER_DIM,
+                available: perDim,
+            },
+        );
+    }
+    const wg = workgroupSizeFor(caps);
+    if (wg < 64) {
+        throw new WebGpuGraphError(
+            "E_NO_DEVICE",
+            `the device allows a workgroup of ${wg} invocations; the kernels need a power of two >= 64`,
+            {
+                reason: "limit",
+                adapter: null,
+                limit: "maxComputeInvocationsPerWorkgroup",
+                requested: 64,
+                available: wg,
+            },
+        );
+    }
+}

package/src/device/error-scope.ts

@@ -0,0 +1,171 @@
+/**
+ * Error scopes (spec 5.7; contract 3.4): a validation scope that turns a captured GPUValidationError into
+ * E_VALIDATION { label, message }, the compilation-info formatter with body-relative line numbers, and the
+ * AllocationTracker that wraps large createBuffer calls in an out-of-memory scope and keeps the resident-byte
+ * bookkeeping the residency, the pool and the staging ring share (it is owned by the context).
+ */
+
+import { OOM_SCOPE_THRESHOLD_BYTES } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+
+/**
+ * Runs `fn` inside pushErrorScope("validation"); a captured error becomes E_VALIDATION { label, message }
+ * thrown from the returned promise (spec 5.7). An error `fn` itself throws is rethrown unchanged after the
+ * scope is popped, so the device's scope stack stays balanced.
+ * @param device - the device
+ * @param label - names the operation in the error (every object the package creates is labelled)
+ * @param fn - the work; may return a promise
+ * @returns the value of `fn`
+ */
+export async function withValidationScope<T>(device: GPUDevice, label: string, fn: () => Promise<T> | T): Promise<T> {
+    device.pushErrorScope("validation");
+    let result: T;
+    try {
+        result = await fn();
+    } catch (err) {
+        await device.popErrorScope().catch(() => null);
+        throw err;
+    }
+    const error = await device.popErrorScope();
+    if (error !== null) {
+        throw new WebGpuGraphError("E_VALIDATION", `${label}: ${error.message}`, { label, message: error.message });
+    }
+    return result;
+}
+
+/**
+ * Formats GPUCompilationInfo messages with line numbers relative to the kernel BODY: `preludeLines` (the
+ * lines the composer emitted before the body) is subtracted, a message located inside those lines is
+ * reported as `prelude:<line>`, and a message without a location (lineNum 0) carries no position (spec 5.1).
+ * @param info - the compilation info of the shader module
+ * @param preludeLines - the number of emitted lines before the body's first line
+ * @returns one string per message: `<type> <line>:<column> <message>`
+ */
+export function formatCompilationInfo(info: GPUCompilationInfo, preludeLines: number): string[] {
+    return info.messages.map((m) => {
+        if (m.lineNum === 0) {
+            return `${m.type} ${m.message}`;
+        }
+        const line = m.lineNum - preludeLines;
+        if (line >= 1) {
+            return `${m.type} ${line}:${m.linePos} ${m.message}`;
+        }
+        return `${m.type} prelude:${m.lineNum}:${m.linePos} ${m.message}`;
+    });
+}
+
+/**
+ * Creates buffers, wrapping sizes >= OOM_SCOPE_THRESHOLD_BYTES in an "out-of-memory" scope whose pop is
+ * collected; `check()` surfaces the first OOM (spec 4.4, 5.7). Owned by the context, shared by the
+ * residency and the pool.
+ */
+export class AllocationTracker {
+    private readonly device: GPUDevice;
+    private readonly threshold: number;
+    private readonly live = new Map<GPUBuffer, number>();
+    private residentBytes = 0;
+    private pending: Promise<void>[] = [];
+    private failure: WebGpuGraphError | null = null;
+    private serial = 0;
+
+    /**
+     * Creates a tracker over one device.
+     * @param device - the device buffers are created on
+     * @param thresholdBytes - the byte size from which createBuffer runs inside an out-of-memory scope (default OOM_SCOPE_THRESHOLD_BYTES)
+     */
+    constructor(device: GPUDevice, thresholdBytes?: number) {
+        this.device = device;
+        this.threshold = thresholdBytes ?? OOM_SCOPE_THRESHOLD_BYTES;
+    }
+
+    /**
+     * createBuffer with the scope rule; every buffer is labelled (an unlabelled descriptor becomes `buffer-<n>`).
+     * @param descriptor - the buffer descriptor
+     * @returns the buffer
+     */
+    createBuffer(descriptor: GPUBufferDescriptor): GPUBuffer {
+        this.serial += 1;
+        const label =
+            descriptor.label === undefined || descriptor.label === "" ? `buffer-${this.serial}` : descriptor.label;
+        const { size } = descriptor;
+        const scoped = size >= this.threshold;
+        if (scoped) {
+            this.device.pushErrorScope("out-of-memory");
+        }
+        const buffer = this.device.createBuffer({ ...descriptor, label });
+        this.live.set(buffer, size);
+        this.residentBytes += size;
+        if (scoped) {
+            const pop = this.device.popErrorScope().then(
+                (error) => {
+                    if (error === null) {
+                        return;
+                    }
+                    if (this.live.has(buffer)) {
+                        this.live.delete(buffer);
+                        this.residentBytes -= size;
+                    }
+                    if (this.failure === null) {
+                        this.failure = new WebGpuGraphError(
+                            "E_OUT_OF_MEMORY",
+                            `out of memory creating "${label}" (${size} bytes, ${this.residentBytes} resident): ${error.message}`,
+                            { requested: size, resident: this.residentBytes, label },
+                        );
+                    }
+                },
+                () => undefined,
+            );
+            this.pending.push(pop);
+        }
+        return buffer;
+    }
+
+    /**
+     * Destroys a buffer created here and decrements `resident`; a buffer the tracker does not know is destroyed
+     * without touching the bookkeeping, so destroying twice is harmless.
+     * @param buffer - the buffer to destroy
+     */
+    destroy(buffer: GPUBuffer): void {
+        const size = this.live.get(buffer);
+        if (size !== undefined) {
+            this.live.delete(buffer);
+            this.residentBytes -= size;
+        }
+        buffer.destroy();
+    }
+
+    /**
+     * Awaits every outstanding scope pop; the first OOM -> E_OUT_OF_MEMORY { requested, resident, label }; later
+     * calls after a failure throw the same error again until `reset()`.
+     */
+    async check(): Promise<void> {
+        while (this.pending.length > 0) {
+            const batch = this.pending.splice(0);
+            await Promise.all(batch);
+        }
+        if (this.failure !== null) {
+            throw this.failure;
+        }
+    }
+
+    /** Forgets a recorded OOM after the caller released what it allocated. */
+    reset(): void {
+        this.failure = null;
+    }
+
+    /**
+     * Bytes of live buffers created through this tracker.
+     * @returns the resident byte count
+     */
+    get resident(): number {
+        return this.residentBytes;
+    }
+
+    /**
+     * Number of live buffers created through this tracker.
+     * @returns the live buffer count
+     */
+    get liveBuffers(): number {
+        return this.live.size;
+    }
+}

package/src/device/lost.ts

@@ -0,0 +1,142 @@
+/**
+ * Device-loss and uncaptured-error plumbing (spec 5.7, 2.2 step 5; contract 3.4): the pending-error slot a
+ * context throws from its next public call, the uncapturederror listener that routes each event to the
+ * caller's sink or to the slot, the device.lost watcher and the E_DEVICE_LOST constructor. Nothing here
+ * throws; errors are constructed and handed on.
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+
+/** The context's pending-error slot (spec 5.7): the last uncaptured error not yet delivered; `take()` clears it. */
+export class PendingErrorSlot {
+    private readonly queue: WebGpuGraphError[] = [];
+
+    /**
+     * Stores an error; a second error before `take()` is kept as `details.next` of the first.
+     * @param error - the error to hold until the next public call
+     */
+    set(error: WebGpuGraphError): void {
+        this.queue.push(error);
+    }
+
+    /**
+     * Returns and clears the pending error, or null. With several errors queued the FIRST is returned and
+     * each later one is chained as `details.next` of its predecessor (a copy: `details` is frozen).
+     * @returns the first pending error with the chain attached, or null
+     */
+    take(): WebGpuGraphError | null {
+        if (this.queue.length === 0) {
+            return null;
+        }
+        const errors = this.queue.splice(0);
+        let chained: WebGpuGraphError | null = null;
+        for (let i = errors.length - 1; i >= 0; i -= 1) {
+            const error = errors[i];
+            chained =
+                chained === null
+                    ? error
+                    : new WebGpuGraphError(error.code, error.message, { ...error.details, next: chained });
+        }
+        return chained;
+    }
+
+    /**
+     * True when an error is pending.
+     * @returns whether `take()` would return an error
+     */
+    get pending(): boolean {
+        return this.queue.length > 0;
+    }
+}
+
+/**
+ * The WebGpuGraphError for one uncaptured GPUError: E_OUT_OF_MEMORY for a GPUOutOfMemoryError (recognised
+ * by its class name so no global is read, spec 2.1 rule 1), E_VALIDATION otherwise.
+ * @param error - the event's error
+ * @param label - the device label the error is attributed to
+ * @returns the wrapped error
+ */
+function uncapturedError(error: GPUError, label: string): WebGpuGraphError {
+    const { message } = error;
+    if (error.constructor.name === "GPUOutOfMemoryError") {
+        // the documented shape is { requested, resident, label } (contract 3.1); the event names no size and the
+        // sink tracks no residency, so both are 0 and the runtime's text lives in the message only
+        return new WebGpuGraphError("E_OUT_OF_MEMORY", `uncaptured out-of-memory error on "${label}": ${message}`, {
+            requested: 0,
+            resident: 0,
+            label,
+        });
+    }
+    return new WebGpuGraphError("E_VALIDATION", `uncaptured validation error on "${label}": ${message}`, {
+        label,
+        message,
+    });
+}
+
+/**
+ * Installs the uncapturederror listener: each event becomes E_VALIDATION { label, message } (or
+ * E_OUT_OF_MEMORY for GPUOutOfMemoryError) routed to `onError`, else stored in `slot`. Returns the
+ * uninstaller. `label` is the device's label (the descriptor label create() gave it).
+ * @param device - the device to listen on
+ * @param slot - where errors go when no sink is given
+ * @param onError - the caller's sink, or null
+ * @returns a function that removes the listener
+ */
+export function installUncapturedErrorSink(
+    device: GPUDevice,
+    slot: PendingErrorSlot,
+    onError: ((error: WebGpuGraphError) => void) | null,
+): () => void {
+    let installed = true;
+    const label = device.label ?? "";
+    const listener = (event: GPUUncapturedErrorEvent): void => {
+        if (!installed) {
+            return;
+        }
+        const wrapped = uncapturedError(event.error, label);
+        if (onError !== null) {
+            onError(wrapped);
+        } else {
+            slot.set(wrapped);
+        }
+    };
+    device.addEventListener("uncapturederror", listener);
+    return () => {
+        installed = false;
+        if (typeof device.removeEventListener === "function") {
+            device.removeEventListener("uncapturederror", listener);
+        }
+    };
+}
+
+/**
+ * Chains device.lost into `onLost` exactly once; returns the promise the context exposes as `ctx.lost`.
+ * @param device - the device whose loss is watched
+ * @param onLost - called once with the lost info
+ * @returns the lost info, after `onLost` ran
+ */
+export function watchDeviceLost(
+    device: GPUDevice,
+    onLost: (info: GPUDeviceLostInfo) => void,
+): Promise<GPUDeviceLostInfo> {
+    let delivered = false;
+    return device.lost.then((info) => {
+        if (!delivered) {
+            delivered = true;
+            onLost(info);
+        }
+        return info;
+    });
+}
+
+/**
+ * The E_DEVICE_LOST error for a lost-info record.
+ * @param info - the device.lost result
+ * @returns E_DEVICE_LOST { reason, message }
+ */
+export function deviceLostError(info: GPUDeviceLostInfo): WebGpuGraphError {
+    return new WebGpuGraphError("E_DEVICE_LOST", `device lost (${info.reason}): ${info.message}`, {
+        reason: info.reason,
+        message: info.message,
+    });
+}

package/src/device/webgpu-constants.ts

@@ -0,0 +1,44 @@
+/**
+ * GPUBufferUsage / GPUMapMode / GPUShaderStage as numbers (spec 2.1 rule 1; contract 3.4): under Dawn-node the
+ * global namespaces do not exist until `Object.assign(globalThis, dawn.globals)` has run, so the core never reads
+ * them at module top level and keeps its own copies here. Each field names the WebGPU spec constant it mirrors;
+ * test/device/constants.test.ts compares every field with the runtime globals so a drift is caught.
+ */
+
+/** GPUBufferUsage bits as numbers so the core never reads the global at module top level (spec 2.1 rule 1). */
+export const BufferUsage: Readonly<{
+    MAP_READ: 0x0001;
+    MAP_WRITE: 0x0002;
+    COPY_SRC: 0x0004;
+    COPY_DST: 0x0008;
+    INDEX: 0x0010;
+    VERTEX: 0x0020;
+    UNIFORM: 0x0040;
+    STORAGE: 0x0080;
+    INDIRECT: 0x0100;
+    QUERY_RESOLVE: 0x0200;
+}> = Object.freeze({
+    MAP_READ: 0x0001, // GPUBufferUsage.MAP_READ
+    MAP_WRITE: 0x0002, // GPUBufferUsage.MAP_WRITE
+    COPY_SRC: 0x0004, // GPUBufferUsage.COPY_SRC
+    COPY_DST: 0x0008, // GPUBufferUsage.COPY_DST
+    INDEX: 0x0010, // GPUBufferUsage.INDEX
+    VERTEX: 0x0020, // GPUBufferUsage.VERTEX
+    UNIFORM: 0x0040, // GPUBufferUsage.UNIFORM
+    STORAGE: 0x0080, // GPUBufferUsage.STORAGE
+    INDIRECT: 0x0100, // GPUBufferUsage.INDIRECT
+    QUERY_RESOLVE: 0x0200, // GPUBufferUsage.QUERY_RESOLVE
+});
+
+/** GPUMapMode bits. */
+export const MapMode: Readonly<{ READ: 0x0001; WRITE: 0x0002 }> = Object.freeze({
+    READ: 0x0001, // GPUMapMode.READ
+    WRITE: 0x0002, // GPUMapMode.WRITE
+});
+
+/** GPUShaderStage bits. */
+export const ShaderStage: Readonly<{ VERTEX: 0x1; FRAGMENT: 0x2; COMPUTE: 0x4 }> = Object.freeze({
+    VERTEX: 0x1, // GPUShaderStage.VERTEX
+    FRAGMENT: 0x2, // GPUShaderStage.FRAGMENT
+    COMPUTE: 0x4, // GPUShaderStage.COMPUTE
+});

package/src/errors.ts

@@ -0,0 +1,94 @@
+/**
+ * The error class and the closed code set of @graphty/webgpu-graph-algorithms (spec 3.3, 5.7; contract 3.1).
+ *
+ * Every condition the package detects itself is thrown as a WebGpuGraphError carrying a stable `code` and a
+ * frozen shallow copy of the `details` the thrower supplied. Errors raised by @graphty/graph-format accessors
+ * the package calls on the caller's behalf pass through unchanged (D12); PASSTHROUGH_FORMAT_CODES lists the
+ * codes a public call may let escape. Constructors never throw. Messages are plain ASCII.
+ *
+ * `details` keys per code (contract 3.1, so tests can assert them): E_NO_WEBGPU { reason, hint };
+ * E_NO_ADAPTER { reason }; E_NO_DEVICE { reason, adapter, limit?, requested?, available? } (reason "consumed" |
+ * "requestDevice" | "limit" | "feature" | "maxComputeWorkgroupsPerDimension"); E_SOFTWARE_ONLY { adapter };
+ * E_DEVICE_LOST { reason, message }; E_DISPOSED { label }; E_VALIDATION { label, message, batchId? };
+ * E_SHADER_COMPILE { id, stage: "compose" | "compile", slot?, messages? }; E_OUT_OF_MEMORY { requested, resident,
+ * label }; E_TOO_LARGE { needed, limit, path, algorithm }; E_UNSUPPORTED { feature? | option?, hint? } (exactly
+ * one of feature / option); E_INVALID_ARGUMENT { argument, value, expected? }; E_SNAPSHOT { reason, serial };
+ * E_RELEASED { serial }; E_NOT_LOADED { state }; E_ABORTED { batchId? }.
+ */
+
+/** Every condition the package detects itself carries one of these codes (spec 3.3). */
+export type WebGpuGraphErrorCode =
+    | "E_NO_WEBGPU"
+    | "E_NO_ADAPTER"
+    | "E_NO_DEVICE"
+    | "E_SOFTWARE_ONLY"
+    | "E_DEVICE_LOST"
+    | "E_DISPOSED"
+    | "E_VALIDATION"
+    | "E_SHADER_COMPILE"
+    | "E_OUT_OF_MEMORY"
+    | "E_TOO_LARGE"
+    | "E_UNSUPPORTED"
+    | "E_INVALID_ARGUMENT"
+    | "E_SNAPSHOT"
+    | "E_RELEASED"
+    | "E_NOT_LOADED"
+    | "E_ABORTED";
+
+/** The graph-format error codes a public call lets propagate unchanged (D12, spec 5.7): raised by accessors the package calls on the caller's behalf. */
+export const PASSTHROUGH_FORMAT_CODES: readonly [
+    "E_GPU_INELIGIBLE",
+    "E_UNKNOWN_NODE",
+    "E_UNKNOWN_COLUMN",
+    "E_COLUMN_LENGTH",
+] = Object.freeze(["E_GPU_INELIGIBLE", "E_UNKNOWN_NODE", "E_UNKNOWN_COLUMN", "E_COLUMN_LENGTH"] as const);
+
+const EMPTY_DETAILS: Readonly<Record<string, unknown>> = Object.freeze({});
+
+/** The one error class the package throws for conditions it detects itself: a stable `code` and frozen `details` (spec 3.3). */
+export class WebGpuGraphError extends Error {
+    /** The stable code. */
+    readonly code: WebGpuGraphErrorCode;
+
+    /** Frozen shallow copy of the details given to the constructor (`{}` when none). */
+    readonly details: Readonly<Record<string, unknown>>;
+
+    /** `name` is always "WebGpuGraphError". */
+    override readonly name: "WebGpuGraphError";
+
+    /**
+     * Create a WebGpuGraphError.
+     * @param code - the stable code the caller can branch on
+     * @param message - a plain-ASCII human-readable message naming the offending label, limit or value
+     * @param details - optional machine-readable context; copied shallowly and frozen
+     */
+    constructor(code: WebGpuGraphErrorCode, message: string, details?: Record<string, unknown>) {
+        super(message);
+        this.name = "WebGpuGraphError";
+        this.code = code;
+        this.details = details === undefined ? EMPTY_DETAILS : Object.freeze({ ...details });
+    }
+}
+
+/**
+ * Brand check that survives two package copies: `name === "WebGpuGraphError"` and a string `code`.
+ * @param x - anything, typically a caught value
+ * @returns true when `x` is structurally a WebGpuGraphError (instanceof is NOT required)
+ */
+export function isWebGpuGraphError(x: unknown): x is WebGpuGraphError {
+    if (typeof x !== "object" || x === null) {
+        return false;
+    }
+    const candidate = x as { readonly name?: unknown; readonly code?: unknown };
+    return candidate.name === "WebGpuGraphError" && typeof candidate.code === "string";
+}
+
+/**
+ * Brand check that survives two package copies: `code === x.code` for an `isWebGpuGraphError(x)`.
+ * @param x - anything, typically a caught value
+ * @param code - the code to test for
+ * @returns true when `x` is a WebGpuGraphError carrying `code`
+ */
+export function hasErrorCode(x: unknown, code: WebGpuGraphErrorCode): boolean {
+    return isWebGpuGraphError(x) && x.code === code;
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+/// <reference types="@webgpu/types" preserve="true" />
+/**
+ * The public barrel of @graphty/webgpu-graph-algorithms (spec 2.5, 3.3; contract 3.15): explicit named exports only,
+ * values and `export type`, no star re-exports, no default export, nothing from src/browser/** or src/node/** (their
+ * own entries; imported by nothing else in src/, 2.4) and nothing of the internal surface (GraphResidency,
+ * BufferPool, Readback, Lease, PipelineCache, Kernel, CommandBatch, UniformRing, UniformBlock, composeWgsl, KERNELS,
+ * ForceSimulation, ForceAtlas2Model: tests import them from their files). P0: the error class, the constants and
+ * isSoftwareAdapter. P1 adds GpuContext and degree (values) and the context / run / profiler types. P2 adds nothing
+ * (Lease, CommandBatch, UniformRing are internal). P3 adds the layout factory, the accelerator, the two default
+ * tables, the seeder and the layout / accelerator types. test/index.test.ts pins the value list and
+ * test/types/public-api.test-d.ts the type list; P4+ extends both. This comment must never spell the internal
+ * JSDoc tag: it is the leading comment of the first export statement, and stripInternal would drop that statement
+ * from the emitted declarations.
+ */
+
+// ==================== constants and errors (P0; FA2_DEFAULTS / LAYOUT_TUNING_DEFAULTS public from P3)
+export {
+    ARC_WINDOW_ALIGN,
+    EXACT_MAX_NODES,
+    FA2_DEFAULTS,
+    LAYOUT_TUNING_DEFAULTS,
+    MAX_1D_ITEMS,
+    MAX_WORKGROUPS_PER_DIM,
+    STORAGE_ALIGN,
+    WORKGROUP_SIZE,
+} from "./constants.js";
+export {
+    hasErrorCode,
+    isWebGpuGraphError,
+    PASSTHROUGH_FORMAT_CODES,
+    WebGpuGraphError,
+    type WebGpuGraphErrorCode,
+} from "./errors.js";
+
+// ==================== context, adapter classifier, profiler (P0 / P1)
+export { GpuContext } from "./context.js";
+export { isSoftwareAdapter } from "./device/acquire.js";
+export type { PassTiming, Profiler } from "./kernel/profiler.js";
+
+// ==================== algorithms (P1: the walking-skeleton diagnostic, spec 3.3)
+export { degree } from "./algorithms/degree.js";
+
+// ==================== layouts and the accelerator (P3)
+export { createAccelerator } from "./accelerator.js";
+export { createForceAtlas2 } from "./layouts/forceatlas2.js";
+export { seedPositions } from "./layouts/seed.js";
+
+// ==================== types: the accelerator surface and the CPU-package mirrors (spec 9.2, 9.3; D27)
+export type {
+    AcceleratorOptions,
+    AlgorithmAccelerator,
+    ApspResultLike,
+    BellmanFordResultLike,
+    BfsResultLike,
+    CommunityResultLike,
+    CorenessResultLike,
+    CpuAlgorithmOptions,
+    EdgeScoresResultLike,
+    GpuAccelerator,
+    HitsResultLike,
+    LabelResultLike,
+    LayoutAccelerator,
+    LayoutSimulation,
+    MstResultLike,
+    PageRankResultLike,
+    ScoresResultLike,
+    SsspResultLike,
+} from "./types/accelerator.js";
+
+// ==================== types: context and capabilities (P0 / P1)
+export type {
+    AdapterInfoLike,
+    AdapterSummary,
+    GpuCaps,
+    GpuContextOptions,
+    LimitPolicy,
+    PlanCaps,
+    PlanLimits,
+    ProbeOptions,
+    ProbeResult,
+    RaisableLimit,
+} from "./types/context.js";
+
+// ==================== types: layouts (P3)
+export type {
+    ForceAtlas2Stats,
+    ForceAtlas2TraceRecord,
+    GpuLayoutSimulation,
+    GpuLayoutTuning,
+    LayoutStatsBase,
+    RunOptions,
+} from "./types/layout.js";
+export type {
+    CommonLayoutOptions,
+    ForceAtlas2Options,
+    FruchtermanReingoldOptions,
+    SimulationOptions,
+    SpringElectricalOptions,
+} from "./types/options.js";
+
+// ==================== types: run options (P1)
+export type { GpuRunOptions } from "./types/run.js";