@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/kernel/dispatch.js

@@ -0,0 +1,139 @@
+/**
+ * Dispatch planning (spec 5.2; contract 3.9): the 16,776,960 rule. `ceil(items / wg)` workgroups as a 1D dispatch
+ * while the count fits one dimension (65,535 groups x 256 = 16,776,960 items, NOT 2^24), else a 2D grid whose
+ * kernels linearise their id with the prelude's `linear_id()` and guard `id >= items`. Pure functions with no
+ * device: every branch is unit-tested against faked capability tables.
+ */
+import { MAX_WORKGROUPS_PER_DIM } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/**
+ * The per-dimension workgroup limit a plan honours. PLAN DECISION: the minimum of the spec constant and the table's
+ * `maxComputeWorkgroupsPerDimension`; the two are asserted equal on a real device at create() (spec 2.2), so every
+ * capability table of the tests yields the same plans and a faked table below the constant is still honoured.
+ * @param caps - the capability table
+ * @returns the limit
+ */
+function perDimension(caps) {
+    return Math.min(MAX_WORKGROUPS_PER_DIM, caps.limits.maxComputeWorkgroupsPerDimension);
+}
+/**
+ * Validates a non-negative integer argument.
+ * @param argument - the argument name
+ * @param value - the value
+ */
+function assertCount(argument, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument} must be a non-negative integer, got ${value}`, {
+            argument,
+            value,
+            expected: "a non-negative integer",
+        });
+    }
+}
+/**
+ * Validates a workgroup size: a power of two >= 1 (the reduction trees of 4.3 need it). Arithmetic, no bit tricks.
+ * @param wg - the workgroup size
+ */
+function assertWorkgroupSize(wg) {
+    let rest = wg;
+    while (Number.isInteger(rest) && rest > 1 && rest % 2 === 0) {
+        rest /= 2;
+    }
+    if (rest !== 1) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `wg must be a power of two, got ${wg}`, {
+            argument: "wg",
+            value: wg,
+            expected: "a power of two >= 1",
+        });
+    }
+}
+/**
+ * The grid of `groups` workgroups: 1D up to the per-dimension limit, else `x = limit`, `y = ceil(groups / limit)`.
+ * @param groups - the workgroup count
+ * @param items - the item count the plan covers (recorded in the plan)
+ * @param caps - the capability table
+ * @returns the plan
+ */
+function grid(groups, items, caps) {
+    const limit = perDimension(caps);
+    if (groups === 0) {
+        return { x: 0, y: 1, z: 1, items, stride: null };
+    }
+    if (groups <= limit) {
+        return { x: groups, y: 1, z: 1, items, stride: null };
+    }
+    const y = Math.ceil(groups / limit);
+    if (y > limit) {
+        throw new WebGpuGraphError("E_TOO_LARGE", `${groups} workgroups exceed the 2D dispatch limit of ${limit * limit}`, {
+            needed: groups,
+            limit: limit * limit,
+            path: "dispatch",
+            algorithm: null,
+            items,
+        });
+    }
+    return { x: limit, y, z: 1, items, stride: null };
+}
+/**
+ * ceil(items / wg) groups as 1D up to MAX_WORKGROUPS_PER_DIM, else a 2D grid; items 0 -> { x: 0, y: 1 }; y above the limit -> E_TOO_LARGE.
+ * @param items - the item count
+ * @param wg - the workgroup size (a power of two)
+ * @param caps - the capability table
+ * @returns the plan
+ */
+export function plan1d(items, wg, caps) {
+    assertCount("items", items);
+    assertWorkgroupSize(wg);
+    return grid(Math.ceil(items / wg), items, caps);
+}
+/**
+ * The 2D form for a group count (x = MAX_WORKGROUPS_PER_DIM, y = ceil(groups / x)); exported for the indirect finalize kernel's host twin (P4).
+ * PLAN DECISION: plan1d's rule applied to a group count (spec 5.4: the finalize kernel uses "the same rule as
+ * plan1d") -- 1D `{ x: groups, y: 1 }` up to the per-dimension limit and the `x = limit` split only above it, through
+ * the same `grid()` as plan1d so the two cannot drift; P4's finalize WGSL mirrors exactly this rule. `items` of the
+ * returned plan is `groups` (the caller knows its own wg); groups 0 -> { x: 0, y: 1 }.
+ * @param groups - the workgroup count
+ * @param caps - the capability table
+ * @returns the plan
+ */
+export function plan2d(groups, caps) {
+    assertCount("groups", groups);
+    return grid(groups, groups, caps);
+}
+/**
+ * P7 (spec 5.2): groups = min(groups, maxGroups ?? (caps.software ? 64 : 4096)) with the kernel looping by stride. P1-P3: throws E_UNSUPPORTED { feature: "planGridStride" } (lead f).
+ * PLAN DECISION: `maxGroups?` is spelled `?: number` rather than the contract's `?: number | undefined` because the
+ * root ESLint rule no-duplicate-type-constituents rejects the explicit undefined on an optional parameter (the call
+ * signature is identical).
+ * @param items - the item count
+ * @param wg - the workgroup size
+ * @param caps - the capability table
+ * @param maxGroups - the group cap
+ */
+export function planGridStride(items, wg, caps, maxGroups) {
+    throw new WebGpuGraphError("E_UNSUPPORTED", "planGridStride lands with the grid-stride kernels of P7 (spec 5.2)", {
+        feature: "planGridStride",
+        hint: `items ${items}, wg ${wg}, maxGroups ${maxGroups ?? (caps.software ? 64 : 4096)}`,
+    });
+}
+/**
+ * P4 (spec 5.4): the (x, y, 1) args a device-side finalize kernel writes for a count. P1-P3: throws E_UNSUPPORTED { feature: "planIndirect" } (lead f).
+ * @param count - the device-side count
+ * @param wg - the workgroup size
+ * @param caps - the capability table
+ */
+export function planIndirect(count, wg, caps) {
+    throw new WebGpuGraphError("E_UNSUPPORTED", "planIndirect lands with the indirect dispatch of P4 (spec 5.4)", {
+        feature: "planIndirect",
+        hint: `count ${count}, wg ${wg}, limit ${perDimension(caps)}`,
+    });
+}
+/**
+ * The workgroup count of a plan (x * y).
+ * @param plan - the plan
+ * @returns the count
+ */
+export function groupsOf(plan) {
+    return plan.x * plan.y;
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/src/kernel/dispatch.js.map

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

package/dist/src/kernel/kernel.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Kernel (spec 5.1; contract 3.9): a compiled pipeline bound to the binding list of its spec. `bind()` creates the
+ * bind groups from a `Record<name, Binding>` keyed by the declared names and caches them by the identity of the
+ * buffers, offsets and sizes (a layout's bind groups are created once per load(), not per iteration); `dispatch()`
+ * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6).
+ */
+import { type Binding } from "../types/memory.js";
+import { type DispatchPlan } from "./dispatch.js";
+import { type ComposedModule, type WgslModuleSpec } from "./wgsl.js";
+/** The resources of one bind(): one Binding per BindingDecl name; a uniform decl takes the ring's whole-buffer binding (the slot is chosen by the dynamic offset at dispatch). */
+export type KernelBindings = Readonly<Record<string, Binding>>;
+/** A kernel with its bind groups created (spec 5.1: cached per set of buffers and offsets). */
+export interface BoundKernel {
+    readonly kernel: Kernel;
+    readonly bindGroups: readonly GPUBindGroup[];
+    /** Group indices whose bind group takes a dynamic offset (the uniform groups), in group order. */
+    readonly dynamicGroups: readonly number[];
+}
+/** A compiled pipeline plus the binding list of its spec (spec 5.1). */
+export declare class Kernel {
+    /** The module spec the pipeline was compiled from (its bindings drive bind()). */
+    readonly spec: WgslModuleSpec;
+    /** The compiled compute pipeline. */
+    readonly pipeline: GPUComputePipeline;
+    /** The explicit bind group layouts, one per group index (an empty layout for an unused index). */
+    readonly layouts: readonly GPUBindGroupLayout[];
+    /** The workgroup size the pipeline was compiled with (the effective WG override). */
+    readonly workgroupSize: number;
+    /** The entry point name the pipeline was compiled with. */
+    readonly entryPoint: string;
+    private readonly device;
+    /** The declarations of each group in binding order (index = group). */
+    private readonly groups;
+    /** The uniform-binding count of each group (the dynamic offsets a setBindGroup takes). */
+    private readonly dynamicCounts;
+    /** Cached bind groups by buffer identity + offset + size. */
+    private readonly cache;
+    /**
+     * Wraps a compiled pipeline.
+     * @param device - the device the bind groups are created on
+     * @param spec - the module
+     * @param composed - the composed text (workgroup size and entry point)
+     * @param pipeline - the compiled pipeline
+     * @param layouts - the explicit bind-group layouts, one per group 0..maxGroup
+     */
+    constructor(device: GPUDevice, spec: WgslModuleSpec, composed: ComposedModule, pipeline: GPUComputePipeline, layouts: readonly GPUBindGroupLayout[]);
+    /**
+     * Creates (or reuses, keyed by every buffer identity + offset + size) the bind groups, each labelled
+     * `<spec.id>/<group>`; a missing or extra name is E_INVALID_ARGUMENT; two bindings of one call whose ranges
+     * intersect on one buffer while either slot is `storage` (read_write) is E_INVALID_ARGUMENT
+     * { argument: "aliasing" } (the host-side mirror of WebGPU's writable buffer-binding-aliasing rule, 3.10.1, so
+     * the failure is synchronous and labelled). CONTRACT DECISION: bind() is synchronous, so a createBindGroup
+     * validation error (a wrong-size uniform binding, a usage mismatch) is NOT thrown here -- it reaches the
+     * pending-error slot as E_VALIDATION { label: "<spec.id>/<group>" } and is thrown by the batch's readback
+     * (Dawn-node) or the next assertReady() (browser), spec 5.7. An empty bind group is created for every empty
+     * layout index so setBindGroup is called for 0..maxGroup.
+     * PLAN DECISION (verified on Dawn 0.4.0 / lavapipe): one buffer bound with two DIFFERENT access modes when one is
+     * `storage` is also E_INVALID_ARGUMENT { argument: "aliasing", reason: "usage" } even with disjoint ranges, because
+     * WebGPU's usage-scope rule rejects "writable usage and another usage in the same synchronization scope" per
+     * BUFFER; two `storage` slots with disjoint ranges (the state header / trace pattern) are accepted; a zero-size
+     * binding (never bind a zero-length buffer, spec 3.6) and an offset that is not a multiple of STORAGE_ALIGN = 256
+     * (spec 2.6; Dawn: "does not satisfy the minimum ... alignment (256)") are E_INVALID_ARGUMENT.
+     * @param resources - one Binding per declared name
+     * @returns the bound kernel (the same object for the same buffers, offsets and sizes until invalidate())
+     */
+    bind(resources: KernelBindings): BoundKernel;
+    /**
+     * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, 1); a plan with x === 0 records nothing (spec 5.6).
+     * PLAN DECISION: one dynamic offset per dynamic GROUP, replicated over every uniform binding of that group (every
+     * P1-P3 kernel has exactly one params uniform per group); absent offsets mean 0; a BoundKernel of another kernel
+     * or an offset list of the wrong length is E_INVALID_ARGUMENT.
+     * PLAN DECISION: `dynamicOffsets?` is spelled `?: readonly number[]` rather than the contract's
+     * `?: readonly number[] | undefined` because the root ESLint rule no-duplicate-type-constituents rejects the
+     * explicit undefined on an optional parameter (the call signature is identical).
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of THIS kernel
+     * @param plan - the dispatch shape
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
+     */
+    dispatch(pass: GPUComputePassEncoder, bound: BoundKernel, plan: DispatchPlan, dynamicOffsets?: readonly number[]): void;
+    /** Drops cached bind groups (a layout's buffers changed). */
+    invalidate(): void;
+}
+//# sourceMappingURL=kernel.d.ts.map

package/dist/src/kernel/kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../../src/kernel/kernel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAoB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEvF,kLAAkL;AAClL,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/D,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AA+BD,wEAAwE;AACxE,qBAAa,MAAM;IACf,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,qFAAqF;IACrF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IAExD;;;;;;;OAOG;gBAEC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,kBAAkB,EAAE;IAmB1C;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,SAAS,EAAE,cAAc,GAAG,WAAW;IAuH5C;;;;;;;;;;;;OAYG;IACH,QAAQ,CACJ,IAAI,EAAE,qBAAqB,EAC3B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,YAAY,EAClB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,IAAI;IA8CP,6DAA6D;IAC7D,UAAU,IAAI,IAAI;CAGrB"}

package/dist/src/kernel/kernel.js

@@ -0,0 +1,239 @@
+/**
+ * Kernel (spec 5.1; contract 3.9): a compiled pipeline bound to the binding list of its spec. `bind()` creates the
+ * bind groups from a `Record<name, Binding>` keyed by the declared names and caches them by the identity of the
+ * buffers, offsets and sizes (a layout's bind groups are created once per load(), not per iteration); `dispatch()`
+ * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6).
+ */
+import { STORAGE_ALIGN } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/** Buffer identities for the bind-group cache key: every GPUBuffer seen by any Kernel gets one number, once. */
+const bufferIds = new WeakMap();
+let nextBufferId = 1;
+/**
+ * The identity number of a buffer.
+ * @param buffer - the buffer
+ * @returns its number
+ */
+function bufferId(buffer) {
+    let id = bufferIds.get(buffer);
+    if (id === undefined) {
+        id = nextBufferId;
+        nextBufferId += 1;
+        bufferIds.set(buffer, id);
+    }
+    return id;
+}
+/**
+ * True when two byte ranges intersect.
+ * @param a - one binding
+ * @param b - the other binding
+ * @returns whether [a.offset, a.offset + a.size) and [b.offset, b.offset + b.size) overlap
+ */
+function rangesIntersect(a, b) {
+    return a.offset < b.offset + b.size && b.offset < a.offset + a.size;
+}
+/** A compiled pipeline plus the binding list of its spec (spec 5.1). */
+export class Kernel {
+    /**
+     * Wraps a compiled pipeline.
+     * @param device - the device the bind groups are created on
+     * @param spec - the module
+     * @param composed - the composed text (workgroup size and entry point)
+     * @param pipeline - the compiled pipeline
+     * @param layouts - the explicit bind-group layouts, one per group 0..maxGroup
+     */
+    constructor(device, spec, composed, pipeline, layouts) {
+        /** Cached bind groups by buffer identity + offset + size. */
+        this.cache = new Map();
+        this.device = device;
+        this.spec = spec;
+        this.pipeline = pipeline;
+        this.layouts = layouts;
+        this.workgroupSize = composed.overrides.WG;
+        this.entryPoint = composed.entryPoint;
+        const groups = layouts.map(() => []);
+        for (const decl of spec.bindings) {
+            groups[decl.group].push(decl);
+        }
+        for (const group of groups) {
+            group.sort((a, b) => a.binding - b.binding);
+        }
+        this.groups = groups;
+        this.dynamicCounts = groups.map((group) => group.filter((decl) => decl.kind === "uniform").length);
+    }
+    /**
+     * Creates (or reuses, keyed by every buffer identity + offset + size) the bind groups, each labelled
+     * `<spec.id>/<group>`; a missing or extra name is E_INVALID_ARGUMENT; two bindings of one call whose ranges
+     * intersect on one buffer while either slot is `storage` (read_write) is E_INVALID_ARGUMENT
+     * { argument: "aliasing" } (the host-side mirror of WebGPU's writable buffer-binding-aliasing rule, 3.10.1, so
+     * the failure is synchronous and labelled). CONTRACT DECISION: bind() is synchronous, so a createBindGroup
+     * validation error (a wrong-size uniform binding, a usage mismatch) is NOT thrown here -- it reaches the
+     * pending-error slot as E_VALIDATION { label: "<spec.id>/<group>" } and is thrown by the batch's readback
+     * (Dawn-node) or the next assertReady() (browser), spec 5.7. An empty bind group is created for every empty
+     * layout index so setBindGroup is called for 0..maxGroup.
+     * PLAN DECISION (verified on Dawn 0.4.0 / lavapipe): one buffer bound with two DIFFERENT access modes when one is
+     * `storage` is also E_INVALID_ARGUMENT { argument: "aliasing", reason: "usage" } even with disjoint ranges, because
+     * WebGPU's usage-scope rule rejects "writable usage and another usage in the same synchronization scope" per
+     * BUFFER; two `storage` slots with disjoint ranges (the state header / trace pattern) are accepted; a zero-size
+     * binding (never bind a zero-length buffer, spec 3.6) and an offset that is not a multiple of STORAGE_ALIGN = 256
+     * (spec 2.6; Dawn: "does not satisfy the minimum ... alignment (256)") are E_INVALID_ARGUMENT.
+     * @param resources - one Binding per declared name
+     * @returns the bound kernel (the same object for the same buffers, offsets and sizes until invalidate())
+     */
+    bind(resources) {
+        const { id } = this.spec;
+        const declared = new Map(this.spec.bindings.map((decl) => [decl.name, decl]));
+        for (const name of Object.keys(resources)) {
+            if (!declared.has(name)) {
+                throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: no binding named "${name}"`, {
+                    argument: "bindings",
+                    value: name,
+                    expected: [...declared.keys()].join(", "),
+                });
+            }
+        }
+        const resolved = [];
+        for (const decl of this.spec.bindings) {
+            const binding = resources[decl.name];
+            if (binding === undefined) {
+                throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: binding "${decl.name}" is missing`, {
+                    argument: "bindings",
+                    value: decl.name,
+                    expected: "a Binding for every declared name",
+                });
+            }
+            if (!(Number.isInteger(binding.size) && binding.size > 0)) {
+                throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: binding "${decl.name}" has size ${binding.size}`, {
+                    argument: decl.name,
+                    value: binding.size,
+                    expected: "size > 0 (a zero-length buffer is never bound)",
+                });
+            }
+            if (!(Number.isInteger(binding.offset) && binding.offset >= 0 && binding.offset % STORAGE_ALIGN === 0)) {
+                throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: binding "${decl.name}" has offset ${binding.offset}`, {
+                    argument: decl.name,
+                    value: binding.offset,
+                    expected: `a multiple of ${STORAGE_ALIGN} (spec 2.6: the offset alignment the package always honours)`,
+                });
+            }
+            resolved.push({ decl, binding });
+        }
+        for (let i = 0; i < resolved.length; i++) {
+            for (let j = i + 1; j < resolved.length; j++) {
+                const a = resolved[i];
+                const b = resolved[j];
+                if (a.binding.buffer !== b.binding.buffer) {
+                    continue;
+                }
+                const writable = a.decl.kind === "storage" || b.decl.kind === "storage";
+                if (!writable) {
+                    continue;
+                }
+                if (a.decl.kind !== b.decl.kind) {
+                    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: "${a.decl.name}" and "${b.decl.name}" bind one buffer with different access modes (writable usage next to another usage)`, {
+                        argument: "aliasing",
+                        value: [a.decl.name, b.decl.name],
+                        expected: "one access mode per buffer when a slot is read_write",
+                        reason: "usage",
+                    });
+                }
+                if (rangesIntersect(a.binding, b.binding)) {
+                    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: "${a.decl.name}" and "${b.decl.name}" bind intersecting ranges of one read_write buffer`, {
+                        argument: "aliasing",
+                        value: [a.decl.name, b.decl.name],
+                        expected: "disjoint ranges",
+                        reason: "range",
+                    });
+                }
+            }
+        }
+        const key = resolved
+            .map(({ binding }) => `${bufferId(binding.buffer)}:${binding.offset}:${binding.size}`)
+            .join("|");
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const byName = new Map(resolved.map(({ decl, binding }) => [decl.name, binding]));
+        const bindGroups = this.layouts.map((layout, group) => this.device.createBindGroup({
+            label: `${id}/${group}`,
+            layout,
+            entries: this.groups[group].map((decl) => {
+                const binding = byName.get(decl.name);
+                return {
+                    binding: decl.binding,
+                    resource: { buffer: binding.buffer, offset: binding.offset, size: binding.size },
+                };
+            }),
+        }));
+        const dynamicGroups = [];
+        this.dynamicCounts.forEach((count, group) => {
+            if (count > 0) {
+                dynamicGroups.push(group);
+            }
+        });
+        const bound = Object.freeze({
+            kernel: this,
+            bindGroups: Object.freeze(bindGroups),
+            dynamicGroups: Object.freeze(dynamicGroups),
+        });
+        this.cache.set(key, bound);
+        return bound;
+    }
+    /**
+     * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, 1); a plan with x === 0 records nothing (spec 5.6).
+     * PLAN DECISION: one dynamic offset per dynamic GROUP, replicated over every uniform binding of that group (every
+     * P1-P3 kernel has exactly one params uniform per group); absent offsets mean 0; a BoundKernel of another kernel
+     * or an offset list of the wrong length is E_INVALID_ARGUMENT.
+     * PLAN DECISION: `dynamicOffsets?` is spelled `?: readonly number[]` rather than the contract's
+     * `?: readonly number[] | undefined` because the root ESLint rule no-duplicate-type-constituents rejects the
+     * explicit undefined on an optional parameter (the call signature is identical).
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of THIS kernel
+     * @param plan - the dispatch shape
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
+     */
+    dispatch(pass, bound, plan, dynamicOffsets) {
+        const { id } = this.spec;
+        if (bound.kernel !== this) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: the bound kernel belongs to "${bound.kernel.spec.id}"`, {
+                argument: "bound",
+                value: bound.kernel.spec.id,
+                expected: id,
+            });
+        }
+        if (dynamicOffsets !== undefined && dynamicOffsets.length !== bound.dynamicGroups.length) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${id}: ${dynamicOffsets.length} dynamic offsets for ${bound.dynamicGroups.length} dynamic groups`, {
+                argument: "dynamicOffsets",
+                value: dynamicOffsets.length,
+                expected: bound.dynamicGroups.length,
+            });
+        }
+        if (plan.x === 0) {
+            return;
+        }
+        pass.setPipeline(this.pipeline);
+        let next = 0;
+        bound.bindGroups.forEach((bindGroup, group) => {
+            const count = this.dynamicCounts[group];
+            if (count > 0) {
+                const offset = dynamicOffsets?.[next] ?? 0;
+                next += 1;
+                const offsets = [];
+                for (let k = 0; k < count; k++) {
+                    offsets.push(offset);
+                }
+                pass.setBindGroup(group, bindGroup, offsets);
+            }
+            else {
+                pass.setBindGroup(group, bindGroup);
+            }
+        });
+        pass.dispatchWorkgroups(plan.x, plan.y, 1);
+    }
+    /** Drops cached bind groups (a layout's buffers changed). */
+    invalidate() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=kernel.js.map

package/dist/src/kernel/kernel.js.map

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

package/dist/src/kernel/pipeline-cache.d.ts

@@ -0,0 +1,90 @@
+/**
+ * PipelineCache (spec 5.1; contract 3.9): compile-once compute pipelines keyed by
+ * `(id, overrides, needs present on the device, snippets)` with EXPLICIT bind-group layouts derived from
+ * `spec.bindings` (never `layout: "auto"`, so one layout serves every dummy-binding variant and bind groups are
+ * reused across variants). A WGSL error is `E_SHADER_COMPILE { stage: "compile", messages, lines }` with
+ * body-relative line numbers; a pipeline error that is not a compilation message (an oversized workgroup, an
+ * invalid layout) is `E_VALIDATION`.
+ */
+import { type PlanCaps } from "../types/context.js";
+import { Kernel } from "./kernel.js";
+import { type WgslModuleSpec } from "./wgsl.js";
+/**
+ * The cache key of a spec on a device (pure; PLAN DECISION: exported so the override-matrix helper of P2-T2 can
+ * compute keys without a device): `id + "|" + stableJson(overrides) + "|" + needs.filter(present).join(",") + "|" + hash(snippets)`.
+ * @param spec - the module
+ * @param caps - the device capabilities (the feature set decides which needs are present)
+ * @returns the key
+ */
+export declare function pipelineKey(spec: WgslModuleSpec, caps: PlanCaps): string;
+/** Compile-once pipelines keyed by (id, overrides, needs present on the device, snippets) with explicit bind-group layouts (spec 5.1). */
+export declare class PipelineCache {
+    private readonly device;
+    private readonly caps;
+    /** In-flight and finished compiles by key (a promise, so two concurrent get() calls share one compile). */
+    private readonly pending;
+    /** Finished compiles by key. */
+    private readonly entries;
+    /** Keys in the order their compiles were started (a failed compile is removed again). */
+    private readonly order;
+    private disposed;
+    /**
+     * Builds a cache over a device.
+     * @param device - the device pipelines are created on
+     * @param caps - its capabilities (WG, subgroup sizes, features)
+     */
+    constructor(device: GPUDevice, caps: PlanCaps);
+    /**
+     * The cache key of a spec on this device: `id + "|" + stableJson(overrides) + "|" + needs.filter(present).join(",") + "|" + hash(snippets)`.
+     * @param spec - the module
+     * @returns the key
+     */
+    key(spec: WgslModuleSpec): string;
+    /**
+     * createComputePipelineAsync inside a validation scope with the layouts derived from spec.bindings; compilation messages become E_SHADER_COMPILE { id, stage: "compile", messages } with body-relative lines.
+     * @param spec - the module
+     * @returns the pipeline (the same object for the same key)
+     */
+    get(spec: WgslModuleSpec): Promise<GPUComputePipeline>;
+    /**
+     * The Kernel (pipeline + layouts + binding names) for a spec; cached with the pipeline.
+     * @param spec - the module
+     * @returns the kernel (the same object for the same key)
+     */
+    kernel(spec: WgslModuleSpec): Promise<Kernel>;
+    /**
+     * Compiles every spec not yet cached (load() calls it so the first step() does not compile).
+     * @param specs - the modules
+     */
+    warm(specs: readonly WgslModuleSpec[]): Promise<void>;
+    /**
+     * Number of cached pipelines.
+     * @returns the count of finished compiles
+     */
+    get size(): number;
+    /**
+     * PLAN DECISION: forgets every pipeline and refuses further compiles with E_DISPOSED (the context's dispose()
+     * may call it; a GPUComputePipeline has no destroy(), so the objects are simply released).
+     */
+    dispose(): void;
+    /**
+     * The cached entry of a spec, compiling it once per key.
+     * @param spec - the module
+     * @returns the entry
+     */
+    private entry;
+    /**
+     * One compile: compose, create the shader module inside a synchronous push / pop validation pair (so concurrent
+     * compiles never interleave scopes), check the compilation info, create the layouts and the pipeline.
+     * PLAN DECISION: `E_SHADER_COMPILE` at stage "compile" also carries `lines` (the body-relative 1-based line of every
+     * error message, from `composed.bodyLine`) next to the contract's `messages`; a `createComputePipelineAsync`
+     * rejection (a GPUPipelineError, which pushes nothing into a validation scope on Dawn 0.4.0) is
+     * `E_VALIDATION { label: "<id>|pipeline", message }`; bool overrides travel as the pipeline constants 1 / 0
+     * because dawn.node's WebIDL layer rejects a boolean constant.
+     * @param spec - the module
+     * @param key - its key (the pipeline label)
+     * @returns the entry
+     */
+    private compile;
+}
+//# sourceMappingURL=pipeline-cache.d.ts.map

package/dist/src/kernel/pipeline-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-cache.d.ts","sourceRoot":"","sources":["../../../src/kernel/pipeline-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAgE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AA+C9G;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGxE;AAWD,0IAA0I;AAC1I,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAClE,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;OAIG;gBACS,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ;IAK7C;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAIjC;;;;OAIG;IACG,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI5D;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD;;;OAGG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAuBD;;;OAGG;IACH,OAAO,IAAI,IAAI;IAOf;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAgCb;;;;;;;;;;;OAWG;YACW,OAAO;CA4DxB"}