@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/memory/upload-plan.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The pure upload planner of spec 4.2: from a snapshot's shape, the device limits and the core arrays a kernel
+ * needs, choose the one-buffer arena upload (the hot prefix, or the full arena when a cold segment is needed and
+ * fits), one buffer per array, or arc windows over the arc-indexed arrays. No GPU object is touched here:
+ * GraphResidency (./residency.ts) executes arena and perArray plans and P4 executes windowed plans (P1-P3 only
+ * plan them). Every byte length comes from counts and flags, so an identity permutation is never materialised
+ * (spec 4.1), and every arithmetic step uses `%` and Math.floor, never a bitwise operator: arc indices and byte
+ * offsets exceed 2^31 at the 10M / 100M tier (graph-format invariant I3, spec 4.2).
+ */
+import { type CoreArrayName, type GraphSnapshot } from "@graphty/graph-format";
+import { type PlanCaps, type PlanLimits } from "../types/context.js";
+import { type ArcWindow } from "../types/memory.js";
+/**
+ * Where one core array's bytes go: one or more buffers (split at window boundaries only when the array exceeds
+ * maxBufferSize). Exported with the plan union (contract 3.8): P4's windowed execution reads it; nothing at P1
+ * imports it by name.
+ * @public
+ */
+export interface PlannedArray {
+    readonly name: CoreArrayName;
+    readonly byteLength: number;
+    readonly buffers: readonly {
+        readonly byteOffset: number;
+        readonly byteLength: number;
+    }[];
+}
+/**
+ * The arena path: ONE buffer of `bytes`, one writeBuffer, per-segment bindings at `segment.byteOffset - arena.byteOffset`.
+ * A member of the exported UploadPlan union (contract 3.8 exports the three plan shapes by name); nothing imports it
+ * by name, which knip 5.77 reports.
+ * @public
+ */
+export interface ArenaPlan {
+    readonly kind: "arena";
+    readonly bytes: number;
+    readonly includesCold: boolean;
+    readonly segments: Readonly<Record<CoreArrayName, {
+        readonly offset: number;
+        readonly size: number;
+    } | null>>;
+}
+/**
+ * The per-array path: one buffer per needed array, whole-buffer bindings.
+ * A member of the exported UploadPlan union (contract 3.8 exports the three plan shapes by name); nothing imports it
+ * by name, which knip 5.77 reports.
+ * @public
+ */
+export interface PerArrayPlan {
+    readonly kind: "perArray";
+    readonly arrays: readonly PlannedArray[];
+}
+/**
+ * The windowed path: per-array buffers plus the arc windows kernels iterate (P4 executes; P1-P3 only plan).
+ * A member of the exported UploadPlan union (contract 3.8 exports the three plan shapes by name); nothing imports it
+ * by name, which knip 5.77 reports.
+ * @public
+ */
+export interface WindowedPlan {
+    readonly kind: "windowed";
+    readonly arrays: readonly PlannedArray[];
+    readonly windows: readonly ArcWindow[];
+    readonly arcsPerWindow: number;
+}
+/** One of the three plans. */
+export type UploadPlan = ArenaPlan | PerArrayPlan | WindowedPlan;
+/**
+ * The largest 64-aligned arc count one binding holds: floor(maxStorageBufferBindingSize / 4) rounded down to a
+ * multiple of ARC_WINDOW_ALIGN.
+ * @param limits - the device limits
+ * @returns the arcs per window (0 when the binding limit is below 256 bytes)
+ */
+export declare function arcsPerWindowFor(limits: PlanLimits): number;
+/**
+ * The window list for a rowPtr (pure; unit-tested with a synthetic rowPtr above 2^31 arcs): start = rowPtr[v0] -
+ * rowPtr[v0] % ARC_WINDOW_ALIGN, at most `arcsPerWindow` arcs per window, a row longer than a window split across
+ * windows. Whole rows first: a window ends at the last row boundary within `start + arcsPerWindow`; a row that does
+ * not fit a window opened at its own aligned start is split into aligned chunks whose `rowFirst === rowLast` is that
+ * row, and the next window continues the row at the chunk end. Every row belongs to a window (leading and trailing
+ * empty rows included); every window is placed in buffer 0 at offset 4 x start (planUpload re-places them when an
+ * array is split across buffers).
+ * @param rowPtr - nodeCount + 1 row offsets (rowPtr[nodeCount] === arcCount)
+ * @param arcCount - the arc count
+ * @param arcsPerWindow - a positive multiple of ARC_WINDOW_ALIGN
+ * @returns the windows in arc order (empty for arcCount 0)
+ */
+export declare function planArcWindows(rowPtr: Uint32Array, arcCount: number, arcsPerWindow: number): ArcWindow[];
+/**
+ * The pure planner of spec 4.2: arena (hot prefix unless `need` names a cold segment and the full arena fits) ->
+ * perArray -> windowed, in that order. `need` always contains "rowPtr" (it is added when absent); absent arrays
+ * (unweighted `weights`, identity permutations, zero-length arrays) are dropped; a snapshot with arcCount === 0
+ * plans rowPtr only. The arena path needs `bytes <= maxBufferSize` and every needed segment within both limits;
+ * ArenaPlan.segments lists every non-null segment inside the uploaded bytes (a needed cold segment outside them is
+ * null: the residency uploads it as its own buffer). The perArray path needs every needed array within both limits;
+ * otherwise the arc-indexed arrays are windowed (rowPtr and edgeToArc must fit, else E_TOO_LARGE).
+ * @param s - the snapshot (only arena, the counts, the flags and rowPtr are read)
+ * @param caps - the device capabilities (only `limits` is read)
+ * @param need - the core arrays the kernel binds
+ * @returns the plan
+ */
+export declare function planUpload(s: GraphSnapshot, caps: PlanCaps, need: readonly CoreArrayName[]): UploadPlan;
+//# sourceMappingURL=upload-plan.d.ts.map

package/dist/src/memory/upload-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-plan.d.ts","sourceRoot":"","sources":["../../../src/memory/upload-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI/E,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAQpD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7F;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC,CAAC;CACjH;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CAAC;AAiFjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,CA4CxG;AA6CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,UAAU,CAsEvG"}

package/dist/src/memory/upload-plan.js

@@ -0,0 +1,265 @@
+/**
+ * The pure upload planner of spec 4.2: from a snapshot's shape, the device limits and the core arrays a kernel
+ * needs, choose the one-buffer arena upload (the hot prefix, or the full arena when a cold segment is needed and
+ * fits), one buffer per array, or arc windows over the arc-indexed arrays. No GPU object is touched here:
+ * GraphResidency (./residency.ts) executes arena and perArray plans and P4 executes windowed plans (P1-P3 only
+ * plan them). Every byte length comes from counts and flags, so an identity permutation is never materialised
+ * (spec 4.1), and every arithmetic step uses `%` and Math.floor, never a bitwise operator: arc indices and byte
+ * offsets exceed 2^31 at the 10M / 100M tier (graph-format invariant I3, spec 4.2).
+ */
+import { ARC_WINDOW_ALIGN } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/** The five core arrays in arena (hot-to-cold) order. */
+const CORE_ORDER = Object.freeze(["rowPtr", "colIdx", "weights", "arcToEdge", "edgeToArc"]);
+/** The arc-indexed arrays: the only ones a window can cover (rowPtr is row-indexed, edgeToArc edge-indexed). */
+const ARC_INDEXED = new Set(["colIdx", "weights", "arcToEdge"]);
+/**
+ * Byte length of every core array from the counts and flags alone; 0 means absent (unweighted, an identity
+ * permutation, or zero length: spec 5.6 never binds a zero-length array). No array is read.
+ * @param s - the snapshot
+ * @returns the byte lengths keyed by core array name
+ */
+function coreByteLengths(s) {
+    const arcs = s.arcCount;
+    const identity = s.flags.arcToEdgeIsIdentity;
+    return {
+        rowPtr: 4 * (s.nodeCount + 1),
+        colIdx: 4 * arcs,
+        weights: s.flags.weighted && arcs > 0 ? 4 * arcs : 0,
+        arcToEdge: !identity && arcs > 0 ? 4 * arcs : 0,
+        edgeToArc: !identity && s.edgeCount > 0 ? 4 * s.edgeCount : 0,
+    };
+}
+/**
+ * rowPtr always, then every requested PRESENT array, in arena order (absent names are dropped, never an error).
+ * @param need - the requested names
+ * @param lengths - the byte lengths of coreByteLengths
+ * @returns the names to plan
+ */
+function neededNames(need, lengths) {
+    const wanted = new Set(need);
+    wanted.add("rowPtr");
+    return CORE_ORDER.filter((name) => wanted.has(name) && lengths[name] > 0);
+}
+/**
+ * Rounds an arc count down to a multiple of ARC_WINDOW_ALIGN with `%` (a bitwise `& ~63` breaks above 2^31).
+ * @param value - an arc count
+ * @returns the largest multiple of 64 not above it
+ */
+function alignDown(value) {
+    return value - (value % ARC_WINDOW_ALIGN);
+}
+/**
+ * The E_TOO_LARGE error of spec 5.7 for a plan that cannot exist.
+ * @param needed - the bytes that do not fit
+ * @param limit - the limit they exceed
+ * @param path - "rowPtr" (no window can hold rowPtr) or "binding" (an edge-indexed array cannot be windowed)
+ * @returns the error to throw
+ */
+function tooLarge(needed, limit, path) {
+    return new WebGpuGraphError("E_TOO_LARGE", `${path}: ${needed} bytes exceed the device limit of ${limit} bytes`, {
+        needed,
+        limit,
+        path,
+        algorithm: null,
+    });
+}
+/**
+ * The E_INVALID_ARGUMENT error of a bad planner input.
+ * @param argument - the argument name
+ * @param value - the value given
+ * @param expected - what was expected
+ * @returns the error to throw
+ */
+function invalid(argument, value, expected) {
+    return new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument}: expected ${expected}`, {
+        argument,
+        value,
+        expected,
+    });
+}
+/**
+ * The largest 64-aligned arc count one binding holds: floor(maxStorageBufferBindingSize / 4) rounded down to a
+ * multiple of ARC_WINDOW_ALIGN.
+ * @param limits - the device limits
+ * @returns the arcs per window (0 when the binding limit is below 256 bytes)
+ */
+export function arcsPerWindowFor(limits) {
+    return alignDown(Math.floor(limits.maxStorageBufferBindingSize / 4));
+}
+/**
+ * The window list for a rowPtr (pure; unit-tested with a synthetic rowPtr above 2^31 arcs): start = rowPtr[v0] -
+ * rowPtr[v0] % ARC_WINDOW_ALIGN, at most `arcsPerWindow` arcs per window, a row longer than a window split across
+ * windows. Whole rows first: a window ends at the last row boundary within `start + arcsPerWindow`; a row that does
+ * not fit a window opened at its own aligned start is split into aligned chunks whose `rowFirst === rowLast` is that
+ * row, and the next window continues the row at the chunk end. Every row belongs to a window (leading and trailing
+ * empty rows included); every window is placed in buffer 0 at offset 4 x start (planUpload re-places them when an
+ * array is split across buffers).
+ * @param rowPtr - nodeCount + 1 row offsets (rowPtr[nodeCount] === arcCount)
+ * @param arcCount - the arc count
+ * @param arcsPerWindow - a positive multiple of ARC_WINDOW_ALIGN
+ * @returns the windows in arc order (empty for arcCount 0)
+ */
+export function planArcWindows(rowPtr, arcCount, arcsPerWindow) {
+    if (rowPtr.length === 0) {
+        throw invalid("rowPtr", rowPtr.length, "nodeCount + 1 entries");
+    }
+    if (!Number.isInteger(arcsPerWindow) ||
+        arcsPerWindow < ARC_WINDOW_ALIGN ||
+        arcsPerWindow % ARC_WINDOW_ALIGN !== 0) {
+        throw invalid("arcsPerWindow", arcsPerWindow, `a positive multiple of ${ARC_WINDOW_ALIGN}`);
+    }
+    const n = rowPtr.length - 1;
+    if (rowPtr[n] !== arcCount) {
+        throw invalid("arcCount", arcCount, `rowPtr[${n}] === ${rowPtr[n]}`);
+    }
+    const windows = [];
+    if (arcCount === 0) {
+        return windows;
+    }
+    let pos = 0;
+    let v = 0;
+    let rowFirst = 0;
+    while (pos < arcCount) {
+        while (rowPtr[v + 1] <= pos) {
+            v++;
+        }
+        const start = alignDown(pos);
+        const limit = start + arcsPerWindow;
+        if (rowPtr[v + 1] > limit) {
+            windows.push({ start, end: limit, rowFirst, rowLast: v, bufferIndex: 0, offset: 4 * start });
+            pos = limit;
+            rowFirst = v;
+        }
+        else {
+            let u = v;
+            while (u + 1 < n && rowPtr[u + 2] <= limit) {
+                u++;
+            }
+            const end = rowPtr[u + 1];
+            windows.push({ start, end, rowFirst, rowLast: u, bufferIndex: 0, offset: 4 * start });
+            pos = end;
+            rowFirst = u + 1;
+        }
+    }
+    return windows;
+}
+/**
+ * Groups consecutive windows into buffers of at most `bufferLimit` bytes (spec 4.2: an array above maxBufferSize is
+ * split across buffers at window boundaries) and re-places every window with its buffer index and offset.
+ * @param windows - the windows of planArcWindows
+ * @param arcBytes - the byte length of one arc-indexed array
+ * @param bufferLimit - maxBufferSize
+ * @returns the buffer ranges shared by every arc-indexed array and the placed windows
+ */
+function placeWindows(windows, arcBytes, bufferLimit) {
+    if (arcBytes <= bufferLimit) {
+        return { buffers: [{ byteOffset: 0, byteLength: arcBytes }], placed: [...windows] };
+    }
+    const buffers = [];
+    const placed = [];
+    let first = 0;
+    while (first < windows.length) {
+        let last = first;
+        while (last + 1 < windows.length && 4 * (windows[last + 1].end - windows[first].start) <= bufferLimit) {
+            last++;
+        }
+        const base = windows[first].start;
+        const bufferIndex = buffers.length;
+        buffers.push({ byteOffset: 4 * base, byteLength: 4 * (windows[last].end - base) });
+        for (let i = first; i <= last; i++) {
+            const w = windows[i];
+            placed.push({
+                start: w.start,
+                end: w.end,
+                rowFirst: w.rowFirst,
+                rowLast: w.rowLast,
+                bufferIndex,
+                offset: 4 * (w.start - base),
+            });
+        }
+        first = last + 1;
+    }
+    return { buffers, placed };
+}
+/**
+ * The pure planner of spec 4.2: arena (hot prefix unless `need` names a cold segment and the full arena fits) ->
+ * perArray -> windowed, in that order. `need` always contains "rowPtr" (it is added when absent); absent arrays
+ * (unweighted `weights`, identity permutations, zero-length arrays) are dropped; a snapshot with arcCount === 0
+ * plans rowPtr only. The arena path needs `bytes <= maxBufferSize` and every needed segment within both limits;
+ * ArenaPlan.segments lists every non-null segment inside the uploaded bytes (a needed cold segment outside them is
+ * null: the residency uploads it as its own buffer). The perArray path needs every needed array within both limits;
+ * otherwise the arc-indexed arrays are windowed (rowPtr and edgeToArc must fit, else E_TOO_LARGE).
+ * @param s - the snapshot (only arena, the counts, the flags and rowPtr are read)
+ * @param caps - the device capabilities (only `limits` is read)
+ * @param need - the core arrays the kernel binds
+ * @returns the plan
+ */
+export function planUpload(s, caps, need) {
+    const { limits } = caps;
+    const binding = limits.maxStorageBufferBindingSize;
+    const bufferLimit = limits.maxBufferSize;
+    const fits = (bytes) => bytes <= binding && bytes <= bufferLimit;
+    const violated = (bytes) => (bytes > binding ? binding : bufferLimit);
+    const lengths = coreByteLengths(s);
+    const names = neededNames(need, lengths);
+    if (!fits(lengths.rowPtr)) {
+        throw tooLarge(lengths.rowPtr, violated(lengths.rowPtr), "rowPtr");
+    }
+    const { arena } = s;
+    if (arena !== null) {
+        const coldNeeded = names.some((name) => (name === "arcToEdge" || name === "edgeToArc") && arena.segments[name] !== null);
+        const includesCold = coldNeeded && arena.byteLength <= bufferLimit;
+        const bytes = includesCold ? arena.byteLength : arena.hotByteLength;
+        const bindable = names.every((name) => {
+            const segment = arena.segments[name];
+            return segment === null || fits(segment.byteLength);
+        });
+        if (bytes <= bufferLimit && bindable) {
+            const segmentOf = (name) => {
+                const segment = arena.segments[name];
+                if (segment === null) {
+                    return null;
+                }
+                const offset = segment.byteOffset - arena.byteOffset;
+                return offset + segment.byteLength <= bytes ? { offset, size: segment.byteLength } : null;
+            };
+            return {
+                kind: "arena",
+                bytes,
+                includesCold,
+                segments: {
+                    rowPtr: segmentOf("rowPtr"),
+                    colIdx: segmentOf("colIdx"),
+                    weights: segmentOf("weights"),
+                    arcToEdge: segmentOf("arcToEdge"),
+                    edgeToArc: segmentOf("edgeToArc"),
+                },
+            };
+        }
+    }
+    if (names.every((name) => fits(lengths[name]))) {
+        return {
+            kind: "perArray",
+            arrays: names.map((name) => ({
+                name,
+                byteLength: lengths[name],
+                buffers: [{ byteOffset: 0, byteLength: lengths[name] }],
+            })),
+        };
+    }
+    if (names.includes("edgeToArc") && !fits(lengths.edgeToArc)) {
+        throw tooLarge(lengths.edgeToArc, violated(lengths.edgeToArc), "binding");
+    }
+    const arcsPerWindow = Math.min(arcsPerWindowFor(limits), alignDown(Math.floor(bufferLimit / 4)));
+    if (arcsPerWindow < ARC_WINDOW_ALIGN) {
+        throw tooLarge(4 * ARC_WINDOW_ALIGN, binding, "binding");
+    }
+    const windows = planArcWindows(s.rowPtr, s.arcCount, arcsPerWindow);
+    const { buffers, placed } = placeWindows(windows, 4 * s.arcCount, bufferLimit);
+    const arrays = names.map((name) => ARC_INDEXED.has(name)
+        ? { name, byteLength: lengths[name], buffers }
+        : { name, byteLength: lengths[name], buffers: [{ byteOffset: 0, byteLength: lengths[name] }] });
+    return { kind: "windowed", arrays, windows: placed, arcsPerWindow };
+}
+//# sourceMappingURL=upload-plan.js.map

package/dist/src/memory/upload-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-plan.js","sourceRoot":"","sources":["../../../src/memory/upload-plan.ts"],"names":[],"mappings":"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"}

package/dist/src/node/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The ./node entry (spec 2.1, 2.3, 3.4; contract 3.7): Dawn through the optional peer dependency `webgpu`. The
+ * ONLY file of the package that names the "webgpu" module, and only inside `await import("webgpu")` in a
+ * function body, so the root and browser bundles never carry the specifier (spec 2.5; test/build-output.test.ts,
+ * test/layers.test.ts). P0-T3 wrote createNodeGpu, dawnFlags and their types; P1-T1 adds createNodeGpuContext,
+ * probeNodeWebGpu and the `extends Omit<GpuContextOptions, ...>` clause of NodeGpuOptions.
+ *
+ * Rule of spec 2.5 item 5 (also in CLAUDE.md): "./node" is imported only by Node entry points and tests.
+ */
+/// <reference types="@webgpu/types" preserve="true" />
+import { GpuContext } from "../context.js";
+import type { GpuContextOptions, ProbeResult } from "../types/context.js";
+/** Options of the Node helpers (spec 3.4). */
+export interface NodeGpuOptions extends Omit<GpuContextOptions, "gpu" | "adapter" | "device" | "runtime"> {
+    /** Dawn `adapter=<substring>`: a substring of the adapter name (`llvmpipe`, `4070`); an empty string is ignored; wins over `software`. */
+    readonly adapter?: string | undefined;
+    /** Dawn `backend=<name>`; `null` compiles pipelines and runs nothing (spec 5.1; the compile tests use it). */
+    readonly backend?: "vulkan" | "d3d12" | "d3d11" | "metal" | "opengl" | "opengles" | "null" | undefined;
+    /** Dawn toggles, emitted as `enable-dawn-features=a,b`. */
+    readonly dawnFeatures?: readonly string[] | undefined;
+    /** Shorthand for `adapter=llvmpipe` (Linux / Mesa specific, spec 2.3); ignored when `adapter` is given. */
+    readonly software?: boolean | undefined;
+    /** Install dawn.globals on globalThis (default true; spec 2.1 rule 2) so user code sees GPUBufferUsage and friends. */
+    readonly installGlobals?: boolean | undefined;
+}
+/** The Dawn GPU handle (spec 2.3): dispose() drops the reference so the process can exit. */
+export interface NodeGpuHandle {
+    /** The GPU of `dawn.create(flags)`; reading it after dispose() throws E_DISPOSED. */
+    readonly gpu: GPU;
+    /** Drops the GPU reference; idempotent. */
+    dispose(): void;
+}
+/**
+ * The Dawn flag list a NodeGpuOptions maps to (exported for the tests and scripts/gpu-report.js):
+ * adapter=<s>, backend=<s>, enable-dawn-features=a,b, and software -> adapter=llvmpipe; an explicit non-empty
+ * `adapter` wins over `software`; an empty feature list emits nothing.
+ * @param options - the Node options, or undefined for no flags
+ * @returns the strings for dawn.create(), in the order adapter, backend, features
+ */
+export declare function dawnFlags(options: NodeGpuOptions | undefined): string[];
+/**
+ * import("webgpu"), install dawn.globals unless installGlobals === false, dawn.create(flags) (spec 2.3).
+ * @param options - adapter / backend / dawnFeatures / software / installGlobals (and the test seam)
+ * @returns the handle; `dispose()` drops the GPU reference so the process can exit
+ * @throws WebGpuGraphError E_NO_WEBGPU { reason, hint } when the module does not load (missing, or its glibc is too old), has no create(), or create(flags) throws
+ */
+export declare function createNodeGpu(options?: NodeGpuOptions): Promise<NodeGpuHandle>;
+/**
+ * createNodeGpu + GpuContext.create({ gpu, runtime: "node", ...options }); ctx.dispose() also disposes the
+ * handle, and a create() failure disposes it before rethrowing. The handle is dropped once `ctx.lost` has
+ * settled, never before: under webgpu@0.4.0 a GPU object collected while the device it created is still
+ * tearing down (its lost / work-done callbacks in flight) crashes or deadlocks the process (PLAN DECISION,
+ * P1-T1; measured with tmp/p1t1/gc-race2.mjs), and device.destroy() reports the loss right away.
+ * @param options - the Node options
+ * @returns the context
+ */
+export declare function createNodeGpuContext(options?: NodeGpuOptions): Promise<GpuContext>;
+/**
+ * createNodeGpu + GpuContext.probe + dispose; never throws (a load failure is { code: "E_NO_WEBGPU" }).
+ * @param options - the Node options
+ * @returns the probe result
+ */
+export declare function probeNodeWebGpu(options?: NodeGpuOptions): Promise<ProbeResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE1E,8CAA8C;AAC9C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACrG,0IAA0I;IAC1I,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,8GAA8G;IAC9G,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IACvG,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtD,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,uHAAuH;IACvH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAMjD;AAED,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;CACnB;AA4DD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,EAAE,CAiBvE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BpF;AAqBD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBxF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBpF"}

package/dist/src/node/index.js

@@ -0,0 +1,183 @@
+/// <reference types="@webgpu/types" preserve="true" />
+/**
+ * The ./node entry (spec 2.1, 2.3, 3.4; contract 3.7): Dawn through the optional peer dependency `webgpu`. The
+ * ONLY file of the package that names the "webgpu" module, and only inside `await import("webgpu")` in a
+ * function body, so the root and browser bundles never carry the specifier (spec 2.5; test/build-output.test.ts,
+ * test/layers.test.ts). P0-T3 wrote createNodeGpu, dawnFlags and their types; P1-T1 adds createNodeGpuContext,
+ * probeNodeWebGpu and the `extends Omit<GpuContextOptions, ...>` clause of NodeGpuOptions.
+ *
+ * Rule of spec 2.5 item 5 (also in CLAUDE.md): "./node" is imported only by Node entry points and tests.
+ */
+import { GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+/** The install hint of E_NO_WEBGPU (spec 2.5 item 4); P-ENV re-pins the version together with the devDependency. */
+const INSTALL_HINT = "install the optional peer dependency webgpu@0.4.0";
+/**
+ * Whether a loaded module is usable as Dawn.
+ * @param loaded - the module namespace
+ * @returns true when it has a create() function
+ */
+function isDawnModule(loaded) {
+    return (typeof loaded === "object" && loaded !== null && typeof loaded.create === "function");
+}
+/**
+ * The message of a thrown value.
+ * @param err - what was caught
+ * @returns the Error message, or the value as a string
+ */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** The handle returned by createNodeGpu(): `gpu` is a getter so dispose() can drop the reference. */
+class DawnHandle {
+    /**
+     * Wraps a GPU object.
+     * @param gpu - the object dawn.create() returned
+     */
+    constructor(gpu) {
+        this.ref = gpu;
+    }
+    /**
+     * The GPU object; E_DISPOSED after dispose().
+     * @returns the GPU object
+     */
+    get gpu() {
+        if (this.ref === null) {
+            throw new WebGpuGraphError("E_DISPOSED", "the Dawn GPU handle was disposed", { label: "NodeGpuHandle" });
+        }
+        return this.ref;
+    }
+    /** Drops the reference; idempotent. */
+    dispose() {
+        this.ref = null;
+    }
+}
+/**
+ * The Dawn flag list a NodeGpuOptions maps to (exported for the tests and scripts/gpu-report.js):
+ * adapter=<s>, backend=<s>, enable-dawn-features=a,b, and software -> adapter=llvmpipe; an explicit non-empty
+ * `adapter` wins over `software`; an empty feature list emits nothing.
+ * @param options - the Node options, or undefined for no flags
+ * @returns the strings for dawn.create(), in the order adapter, backend, features
+ */
+export function dawnFlags(options) {
+    const flags = [];
+    if (options === undefined) {
+        return flags;
+    }
+    if (options.adapter !== undefined && options.adapter !== "") {
+        flags.push(`adapter=${options.adapter}`);
+    }
+    else if (options.software === true) {
+        flags.push("adapter=llvmpipe");
+    }
+    if (options.backend !== undefined) {
+        flags.push(`backend=${options.backend}`);
+    }
+    if (options.dawnFeatures !== undefined && options.dawnFeatures.length > 0) {
+        flags.push(`enable-dawn-features=${options.dawnFeatures.join(",")}`);
+    }
+    return flags;
+}
+/**
+ * import("webgpu"), install dawn.globals unless installGlobals === false, dawn.create(flags) (spec 2.3).
+ * @param options - adapter / backend / dawnFeatures / software / installGlobals (and the test seam)
+ * @returns the handle; `dispose()` drops the GPU reference so the process can exit
+ * @throws WebGpuGraphError E_NO_WEBGPU { reason, hint } when the module does not load (missing, or its glibc is too old), has no create(), or create(flags) throws
+ */
+export async function createNodeGpu(options) {
+    const load = options?.loadModule ?? (() => import("webgpu"));
+    let loaded;
+    try {
+        loaded = await load();
+    }
+    catch (err) {
+        const reason = messageOf(err);
+        throw new WebGpuGraphError("E_NO_WEBGPU", `the webgpu (Dawn) native module did not load: ${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });
+    }
+    if (!isDawnModule(loaded)) {
+        const reason = "the webgpu module exports no create() function";
+        throw new WebGpuGraphError("E_NO_WEBGPU", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });
+    }
+    if (options?.installGlobals !== false && typeof loaded.globals === "object" && loaded.globals !== null) {
+        Object.assign(globalThis, loaded.globals);
+    }
+    let gpu;
+    try {
+        gpu = loaded.create(dawnFlags(options));
+    }
+    catch (err) {
+        const reason = `dawn.create() threw: ${messageOf(err)}`;
+        throw new WebGpuGraphError("E_NO_WEBGPU", `${reason}; ${INSTALL_HINT}`, { reason, hint: INSTALL_HINT });
+    }
+    return new DawnHandle(gpu);
+}
+/**
+ * The GpuContextOptions part of a NodeGpuOptions, copied key by key so the Node-only `adapter` string never
+ * reaches GpuContext.create as a GPUAdapter.
+ * @param options - the Node options
+ * @returns the context options without gpu / adapter / device / runtime
+ */
+function contextOptionsOf(options) {
+    return {
+        powerPreference: options.powerPreference,
+        rejectSoftware: options.rejectSoftware,
+        limits: options.limits,
+        optionalFeatures: options.optionalFeatures,
+        requiredFeatures: options.requiredFeatures,
+        label: options.label,
+        onError: options.onError,
+        warnUnreleasedSnapshots: options.warnUnreleasedSnapshots,
+    };
+}
+/**
+ * createNodeGpu + GpuContext.create({ gpu, runtime: "node", ...options }); ctx.dispose() also disposes the
+ * handle, and a create() failure disposes it before rethrowing. The handle is dropped once `ctx.lost` has
+ * settled, never before: under webgpu@0.4.0 a GPU object collected while the device it created is still
+ * tearing down (its lost / work-done callbacks in flight) crashes or deadlocks the process (PLAN DECISION,
+ * P1-T1; measured with tmp/p1t1/gc-race2.mjs), and device.destroy() reports the loss right away.
+ * @param options - the Node options
+ * @returns the context
+ */
+export async function createNodeGpuContext(options) {
+    const handle = await createNodeGpu(options);
+    let ctx;
+    try {
+        ctx = await GpuContext.create({ ...contextOptionsOf(options ?? {}), gpu: handle.gpu, runtime: "node" });
+    }
+    catch (err) {
+        handle.dispose();
+        throw err;
+    }
+    const { lost } = ctx;
+    ctx.attachDisposer(() => {
+        void lost.then(() => {
+            handle.dispose();
+        });
+    });
+    return ctx;
+}
+/**
+ * createNodeGpu + GpuContext.probe + dispose; never throws (a load failure is { code: "E_NO_WEBGPU" }).
+ * @param options - the Node options
+ * @returns the probe result
+ */
+export async function probeNodeWebGpu(options) {
+    let handle;
+    try {
+        handle = await createNodeGpu(options);
+    }
+    catch (err) {
+        return { ok: false, code: "E_NO_WEBGPU", reason: messageOf(err), adapter: null, summary: null };
+    }
+    try {
+        return await GpuContext.probe({
+            gpu: handle.gpu,
+            powerPreference: options?.powerPreference ?? "high-performance",
+            rejectSoftware: options?.rejectSoftware,
+        });
+    }
+    finally {
+        handle.dispose();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"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"}