@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/src/kernel/kernel.ts

@@ -0,0 +1,311 @@
+/**
+ * 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";
+import { type Binding } from "../types/memory.js";
+import { type DispatchPlan } from "./dispatch.js";
+import { type BindingDecl, 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[];
+}
+
+/** Buffer identities for the bind-group cache key: every GPUBuffer seen by any Kernel gets one number, once. */
+const bufferIds = new WeakMap<GPUBuffer, number>();
+let nextBufferId = 1;
+
+/**
+ * The identity number of a buffer.
+ * @param buffer - the buffer
+ * @returns its number
+ */
+function bufferId(buffer: GPUBuffer): number {
+    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: Binding, b: Binding): boolean {
+    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 {
+    /** 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: GPUDevice;
+    /** The declarations of each group in binding order (index = group). */
+    private readonly groups: readonly (readonly BindingDecl[])[];
+    /** The uniform-binding count of each group (the dynamic offsets a setBindGroup takes). */
+    private readonly dynamicCounts: readonly number[];
+    /** Cached bind groups by buffer identity + offset + size. */
+    private readonly cache = new Map<string, BoundKernel>();
+
+    /**
+     * 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[],
+    ) {
+        this.device = device;
+        this.spec = spec;
+        this.pipeline = pipeline;
+        this.layouts = layouts;
+        this.workgroupSize = composed.overrides.WG as number;
+        this.entryPoint = composed.entryPoint;
+        const groups: BindingDecl[][] = 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: KernelBindings): BoundKernel {
+        const { id } = this.spec;
+        const declared = new Map(this.spec.bindings.map((decl) => [decl.name, decl] as const));
+        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: { readonly decl: BindingDecl; readonly binding: Binding }[] = [];
+        for (const decl of this.spec.bindings) {
+            const binding = resources[decl.name] as Binding | undefined;
+            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] as const));
+        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) as Binding;
+                    return {
+                        binding: decl.binding,
+                        resource: { buffer: binding.buffer, offset: binding.offset, size: binding.size },
+                    };
+                }),
+            }),
+        );
+        const dynamicGroups: number[] = [];
+        this.dynamicCounts.forEach((count, group) => {
+            if (count > 0) {
+                dynamicGroups.push(group);
+            }
+        });
+        const bound: BoundKernel = 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: GPUComputePassEncoder,
+        bound: BoundKernel,
+        plan: DispatchPlan,
+        dynamicOffsets?: readonly number[],
+    ): void {
+        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: number[] = [];
+                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(): void {
+        this.cache.clear();
+    }
+}

package/src/kernel/pipeline-cache.ts

@@ -0,0 +1,288 @@
+/**
+ * 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 { formatCompilationInfo } from "../device/error-scope.js";
+import { WebGpuGraphError } from "../errors.js";
+import { type PlanCaps } from "../types/context.js";
+import { Kernel } from "./kernel.js";
+import { bindGroupLayoutDescriptors, type ComposedModule, composeWgsl, type WgslModuleSpec } from "./wgsl.js";
+
+/** One cached entry: the pipeline, its layouts and the Kernel built on them. */
+interface CacheEntry {
+    readonly key: string;
+    readonly composed: ComposedModule;
+    readonly pipeline: GPUComputePipeline;
+    readonly layouts: readonly GPUBindGroupLayout[];
+    readonly kernel: Kernel;
+}
+
+/**
+ * JSON with the keys of every (nested) object sorted, so two override records with the same content give one key.
+ * @param value - a JSON-compatible value
+ * @returns the canonical text
+ */
+function stableJson(value: unknown): string {
+    if (Array.isArray(value)) {
+        return `[${value.map((item: unknown) => stableJson(item)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value as Record<string, unknown>;
+        const keys = Object.keys(record).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+
+/**
+ * FNV-1a (32-bit) of a text as 8 hex digits; "0" for an absent or empty snippet record. Hashes text, never an arc
+ * index or a byte offset, so the bitwise operators are within the house rule.
+ * @param snippets - the snippet record
+ * @returns the hash text
+ */
+function hashSnippets(snippets: Readonly<Record<string, string>> | undefined): string {
+    if (snippets === undefined || Object.keys(snippets).length === 0) {
+        return "0";
+    }
+    const text = stableJson(snippets);
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+
+/**
+ * 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 function pipelineKey(spec: WgslModuleSpec, caps: PlanCaps): string {
+    const present = spec.needs.filter((need) => caps.features.has(need)).join(",");
+    return `${spec.id}|${stableJson(spec.overrides)}|${present}|${hashSnippets(spec.snippets)}`;
+}
+
+/**
+ * The message of an unknown error value.
+ * @param err - the thrown value
+ * @returns its message text
+ */
+function messageOf(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+}
+
+/** Compile-once pipelines keyed by (id, overrides, needs present on the device, snippets) with explicit bind-group layouts (spec 5.1). */
+export class PipelineCache {
+    private readonly device: GPUDevice;
+    private readonly caps: PlanCaps;
+    /** In-flight and finished compiles by key (a promise, so two concurrent get() calls share one compile). */
+    private readonly pending = new Map<string, Promise<CacheEntry>>();
+    /** Finished compiles by key. */
+    private readonly entries = new Map<string, CacheEntry>();
+    /** Keys in the order their compiles were started (a failed compile is removed again). */
+    private readonly order: string[] = [];
+    private disposed = false;
+
+    /**
+     * 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) {
+        this.device = device;
+        this.caps = caps;
+    }
+
+    /**
+     * 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 {
+        return pipelineKey(spec, this.caps);
+    }
+
+    /**
+     * 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)
+     */
+    async get(spec: WgslModuleSpec): Promise<GPUComputePipeline> {
+        return (await this.entry(spec)).pipeline;
+    }
+
+    /**
+     * 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)
+     */
+    async kernel(spec: WgslModuleSpec): Promise<Kernel> {
+        return (await this.entry(spec)).kernel;
+    }
+
+    /**
+     * Compiles every spec not yet cached (load() calls it so the first step() does not compile).
+     * @param specs - the modules
+     */
+    async warm(specs: readonly WgslModuleSpec[]): Promise<void> {
+        await Promise.all(specs.map((spec) => this.entry(spec)));
+    }
+
+    /**
+     * Number of cached pipelines.
+     * @returns the count of finished compiles
+     */
+    get size(): number {
+        return this.entries.size;
+    }
+
+    /**
+     * Every key created so far, in creation order (the override-matrix coverage test reads it).
+     * PLAN DECISION: keys are listed in compile-START order and only those whose compile finished (warm() compiles
+     * concurrently, so completion order is not deterministic; a failed compile is removed).
+     * @returns the keys
+     * @internal
+     */
+    keys(): readonly string[] {
+        return this.order.filter((key) => this.entries.has(key));
+    }
+
+    /**
+     * The bind-group layouts of a cached kernel by key.
+     * @param key - a key from keys()
+     * @returns the layouts, or null when the key is not cached
+     * @internal
+     */
+    layoutsOf(key: string): readonly GPUBindGroupLayout[] | null {
+        return this.entries.get(key)?.layouts ?? null;
+    }
+
+    /**
+     * 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 {
+        this.disposed = true;
+        this.pending.clear();
+        this.entries.clear();
+        this.order.length = 0;
+    }
+
+    /**
+     * The cached entry of a spec, compiling it once per key.
+     * @param spec - the module
+     * @returns the entry
+     */
+    private entry(spec: WgslModuleSpec): Promise<CacheEntry> {
+        if (this.disposed) {
+            return Promise.reject(
+                new WebGpuGraphError("E_DISPOSED", "PipelineCache: disposed", { label: "PipelineCache" }),
+            );
+        }
+        const key = this.key(spec);
+        const inFlight = this.pending.get(key);
+        if (inFlight !== undefined) {
+            return inFlight;
+        }
+        this.order.push(key);
+        const compile = this.compile(spec, key).then(
+            (entry) => {
+                if (!this.disposed) {
+                    this.entries.set(key, entry);
+                }
+                return entry;
+            },
+            (err: unknown) => {
+                this.pending.delete(key);
+                const at = this.order.indexOf(key);
+                if (at >= 0) {
+                    this.order.splice(at, 1);
+                }
+                throw err;
+            },
+        );
+        this.pending.set(key, compile);
+        return compile;
+    }
+
+    /**
+     * 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 async compile(spec: WgslModuleSpec, key: string): Promise<CacheEntry> {
+        const composed = composeWgsl(spec, this.caps);
+        const { device } = this;
+        const label = `${spec.id}|pipeline`;
+        device.pushErrorScope("validation");
+        const module = device.createShaderModule({ code: composed.code, label: spec.id });
+        const layouts = bindGroupLayoutDescriptors(spec).map((descriptor, group) =>
+            device.createBindGroupLayout({ ...descriptor, label: `${spec.id}/layout${group}` }),
+        );
+        const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: layouts, label: `${spec.id}|layout` });
+        const popped = device.popErrorScope();
+        const info = await module.getCompilationInfo();
+        const scopeError = await popped;
+        const errors = info.messages.filter((message) => message.type === "error");
+        if (errors.length > 0) {
+            const preludeLines = composed.bodyLine - 1;
+            throw new WebGpuGraphError(
+                "E_SHADER_COMPILE",
+                `${spec.id}: WGSL compilation failed (${errors.length} error(s))`,
+                {
+                    id: spec.id,
+                    stage: "compile",
+                    messages: formatCompilationInfo(info, preludeLines),
+                    lines: errors.map((message) => message.lineNum - preludeLines),
+                },
+            );
+        }
+        if (scopeError !== null) {
+            throw new WebGpuGraphError("E_VALIDATION", `${spec.id}: ${scopeError.message}`, {
+                label,
+                message: scopeError.message,
+            });
+        }
+        // dawn.node's WebIDL layer rejects a boolean pipeline constant ("value is not a number"), so bools travel as 1 / 0;
+        // only the REFERENCED overrides are supplied (composed.constants): WebKit rejects a constant for an unread override
+        const constants: Record<string, number> = {};
+        for (const [name, value] of Object.entries(composed.constants)) {
+            if (typeof value === "boolean") {
+                constants[name] = value ? 1 : 0;
+            } else {
+                constants[name] = value;
+            }
+        }
+        let pipeline: GPUComputePipeline;
+        try {
+            pipeline = await device.createComputePipelineAsync({
+                label: key,
+                layout: pipelineLayout,
+                compute: { module, entryPoint: composed.entryPoint, constants },
+            });
+        } catch (err: unknown) {
+            const message = messageOf(err);
+            throw new WebGpuGraphError("E_VALIDATION", `${spec.id}: pipeline creation failed: ${message}`, {
+                label,
+                message,
+            });
+        }
+        const kernel = new Kernel(device, spec, composed, pipeline, layouts);
+        return { key, composed, pipeline, layouts, kernel };
+    }
+}