@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.0

package/dist/src/kernel/pipeline-cache.js

@@ -0,0 +1,251 @@
+/**
+ * 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 { Kernel } from "./kernel.js";
+import { bindGroupLayoutDescriptors, composeWgsl } from "./wgsl.js";
+/**
+ * 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) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        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) {
+    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, caps) {
+    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) {
+    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 {
+    /**
+     * Builds a cache over a device.
+     * @param device - the device pipelines are created on
+     * @param caps - its capabilities (WG, subgroup sizes, features)
+     */
+    constructor(device, caps) {
+        /** In-flight and finished compiles by key (a promise, so two concurrent get() calls share one compile). */
+        this.pending = new Map();
+        /** Finished compiles by key. */
+        this.entries = new Map();
+        /** Keys in the order their compiles were started (a failed compile is removed again). */
+        this.order = [];
+        this.disposed = false;
+        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) {
+        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) {
+        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) {
+        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) {
+        await Promise.all(specs.map((spec) => this.entry(spec)));
+    }
+    /**
+     * Number of cached pipelines.
+     * @returns the count of finished compiles
+     */
+    get size() {
+        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() {
+        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) {
+        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() {
+        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
+     */
+    entry(spec) {
+        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) => {
+            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
+     */
+    async compile(spec, key) {
+        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 = {};
+        for (const [name, value] of Object.entries(composed.constants)) {
+            if (typeof value === "boolean") {
+                constants[name] = value ? 1 : 0;
+            }
+            else {
+                constants[name] = value;
+            }
+        }
+        let pipeline;
+        try {
+            pipeline = await device.createComputePipelineAsync({
+                label: key,
+                layout: pipelineLayout,
+                compute: { module, entryPoint: composed.entryPoint, constants },
+            });
+        }
+        catch (err) {
+            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 };
+    }
+}
+//# sourceMappingURL=pipeline-cache.js.map

package/dist/src/kernel/pipeline-cache.js.map

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

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

@@ -0,0 +1,35 @@
+/**
+ * The WGSL prelude every composed module receives first (contract 4.1), the two reduction-helper blocks the
+ * composer splices for a body whose spec lists `needs: ["subgroups"]` (contract 4.3, D16), and the WGSL
+ * reserved-word list the composer rejects identifiers from (contract 3.9).
+ *
+ * CONTRACT DECISION (3.9): this text lives in the kernel layer, not in `src/wgsl/`, because the composer must own
+ * what it splices and `src/wgsl/` then holds kernel BODIES only. Every numeric constant is interpolated from
+ * `constants.ts` and graph-format's `INVALID_INDEX`; the literal-grep test of spec 3.5 (`test/kernel/wgsl.test.ts`)
+ * covers this file's template, so no u32 sentinel or workgroup-size literal is ever typed here.
+ */
+/**
+ * Formats a finite number as a WGSL f32 literal that always carries a decimal point or an exponent (`0.01`,
+ * `1e-8`, `2.0`), so an integral value never becomes an abstract-int literal (contract 4.1).
+ * @param value - the number to format
+ * @returns the literal text
+ */
+export declare function wgslF32Literal(value: number): string;
+/** The prelude text with the constants interpolated from constants.ts and graph-format's INVALID_INDEX (4.1). */
+export declare const PRELUDE_WGSL: string;
+/** Line count of PRELUDE_WGSL (the compilation-info formatter subtracts it plus the emitted declarations). */
+export declare const PRELUDE_LINES: number;
+/** The workgroup-memory reduction helpers (the twin) (4.3). */
+export declare const REDUCE_HELPERS_WORKGROUP_WGSL: string;
+/** The subgroup reduction helpers, spliced only with `enable subgroups;` (4.3). */
+export declare const REDUCE_HELPERS_SUBGROUP_WGSL: string;
+/** The helper function names a body may call when its spec lists needs: ["subgroups"]. */
+export declare const REDUCE_HELPER_NAMES: readonly ["wg_reduce_f32", "wg_reduce_u32", "wg_reduce_vec4"];
+/**
+ * The WGSL reserved words of spec section 16.2 (the `_reserved` production), frozen; composeWgsl rejects a body or
+ * snippet that uses one (3.9). PLAN DECISION: the list is the 146 words of the W3C Candidate Recommendation Draft
+ * of 2026-08-31 (identical to the editor's draft of 2026-09-01); the contract's count of 147 predates the removal
+ * of `binding_array`. `free`, `valid`, `tile`, `slot`, `key` and `count` are NOT reserved.
+ */
+export declare const WGSL_RESERVED_WORDS: readonly string[];
+//# sourceMappingURL=prelude.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.d.ts","sourceRoot":"","sources":["../../../src/kernel/prelude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAeH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUpD;AAED,iHAAiH;AACjH,eAAO,MAAM,YAAY,EAAE,MAwCzB,CAAC;AAEH,8GAA8G;AAC9G,eAAO,MAAM,aAAa,EAAE,MAAwC,CAAC;AAErE,+DAA+D;AAC/D,eAAO,MAAM,6BAA6B,EAAE,MAoCsE,CAAC;AAEnH,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,EAAE,MA2EuE,CAAC;AAEnH,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB,+DAAgE,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAchD,CAAC"}

package/dist/src/kernel/prelude.js

@@ -0,0 +1,211 @@
+/**
+ * The WGSL prelude every composed module receives first (contract 4.1), the two reduction-helper blocks the
+ * composer splices for a body whose spec lists `needs: ["subgroups"]` (contract 4.3, D16), and the WGSL
+ * reserved-word list the composer rejects identifiers from (contract 3.9).
+ *
+ * CONTRACT DECISION (3.9): this text lives in the kernel layer, not in `src/wgsl/`, because the composer must own
+ * what it splices and `src/wgsl/` then holds kernel BODIES only. Every numeric constant is interpolated from
+ * `constants.ts` and graph-format's `INVALID_INDEX`; the literal-grep test of spec 3.5 (`test/kernel/wgsl.test.ts`)
+ * covers this file's template, so no u32 sentinel or workgroup-size literal is ever typed here.
+ */
+import { INVALID_INDEX } from "@graphty/graph-format";
+import { FA2_COINCIDENT_SQ, FA2_DISTANCE_FLOOR, FA2_DISTANCE_FLOOR_SQ, FA2_FLAG_FIRST, MAX_WORKGROUPS_PER_DIM, U32_MAX, WORKGROUP_SIZE, } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+/**
+ * Formats a finite number as a WGSL f32 literal that always carries a decimal point or an exponent (`0.01`,
+ * `1e-8`, `2.0`), so an integral value never becomes an abstract-int literal (contract 4.1).
+ * @param value - the number to format
+ * @returns the literal text
+ */
+export function wgslF32Literal(value) {
+    if (!Number.isFinite(value)) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `wgslF32Literal: ${value} is not a finite number`, {
+            argument: "value",
+            value,
+            expected: "a finite number",
+        });
+    }
+    const text = String(value);
+    return /[.e]/.test(text) ? text : `${text}.0`;
+}
+/** The prelude text with the constants interpolated from constants.ts and graph-format's INVALID_INDEX (4.1). */
+export const PRELUDE_WGSL = /* wgsl */ `// ---- prelude: constants, standard overrides, helpers (every module receives this text first)
+const INVALID_INDEX: u32 = ${INVALID_INDEX}u;
+const U32_MAX: u32 = ${U32_MAX}u;
+const MAX_WORKGROUPS_PER_DIM: u32 = ${MAX_WORKGROUPS_PER_DIM}u;
+const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
+const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
+const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};
+const FA2_FLAG_FIRST: u32 = ${FA2_FLAG_FIRST}u;
+const F32_MAX: f32 = 0x1.fffffep+127;
+override WG: u32 = ${WORKGROUP_SIZE}u;
+override USE_PERM: bool = false;
+override HAS_WEIGHTS: bool = false;
+override SUBGROUP_MIN: u32 = 4u;
+override SUBGROUP_MAX: u32 = 0u;
+
+fn linear_id(wid: vec3<u32>, lid: u32) -> u32 { return (wid.x + wid.y * MAX_WORKGROUPS_PER_DIM) * WG + lid; }
+fn group_id(wid: vec3<u32>) -> u32 { return wid.x + wid.y * MAX_WORKGROUPS_PER_DIM; }
+fn lowbias32(x0: u32) -> u32 {
+    var x = x0;
+    x = x ^ (x >> 16u);
+    x = x * 0x7feb352du;
+    x = x ^ (x >> 15u);
+    x = x * 0x846ca68bu;
+    x = x ^ (x >> 16u);
+    return x;
+}
+fn mask_bit(w: u32, i: u32) -> bool { return ((w >> (i & 31u)) & 1u) == 1u; }
+fn unpack_u8(w: u32, i: u32) -> u32 { return (w >> (8u * (i & 3u))) & 0xFFu; }
+fn pair_hash(i: u32, j: u32) -> u32 { return lowbias32((min(i, j) * 0x9E3779B9u) ^ max(i, j)); }
+fn hash_unit(h: u32) -> f32 { return f32(h >> 8u) * (1.0 / 16777216.0); }
+fn hash_dir(h: u32, dim: u32) -> vec3f {
+    let phi = 6.283185307179586 * hash_unit(h);
+    if (dim == 2u) { return vec3f(cos(phi), sin(phi), 0.0); }
+    let z = 2.0 * hash_unit(lowbias32(h ^ 0x5bd1e995u)) - 1.0;
+    let r = sqrt(max(0.0, 1.0 - z * z));
+    return vec3f(r * cos(phi), r * sin(phi), z);
+}
+fn kick_dir(i: u32, j: u32, dim: u32) -> vec3f {
+    let d = hash_dir(pair_hash(i, j), dim);
+    return select(d, -d, i > j);
+}`;
+/** Line count of PRELUDE_WGSL (the compilation-info formatter subtracts it plus the emitted declarations). */
+export const PRELUDE_LINES = PRELUDE_WGSL.split("\n").length;
+/** The workgroup-memory reduction helpers (the twin) (4.3). */
+export const REDUCE_HELPERS_WORKGROUP_WGSL = /* wgsl */ `var<workgroup> wg_scratch_v: array<vec4f, WG>;
+var<workgroup> wg_scratch_u: array<u32, WG>;
+fn combine_v(a: vec4f, b: vec4f, op: u32) -> vec4f {
+    if (op == 1u) { return min(a, b); }
+    if (op == 2u) { return max(a, b); }
+    return a + b;
+}
+fn combine_u(a: u32, b: u32, op: u32) -> u32 {
+    if (op == 1u) { return min(a, b); }
+    if (op == 2u) { return max(a, b); }
+    return a + b;
+}
+fn wg_reduce_vec4(v: vec4f, lid: u32, op: u32) -> vec4f {
+    workgroupBarrier();
+    wg_scratch_v[lid] = v;
+    workgroupBarrier();
+    for (var s = WG / 2u; s > 0u; s = s >> 1u) {
+        if (lid < s) { wg_scratch_v[lid] = combine_v(wg_scratch_v[lid], wg_scratch_v[lid + s], op); }
+        workgroupBarrier();
+    }
+    let total = wg_scratch_v[0];
+    workgroupBarrier();
+    return total;
+}
+fn wg_reduce_u32(v: u32, lid: u32, op: u32) -> u32 {
+    workgroupBarrier();
+    wg_scratch_u[lid] = v;
+    workgroupBarrier();
+    for (var s = WG / 2u; s > 0u; s = s >> 1u) {
+        if (lid < s) { wg_scratch_u[lid] = combine_u(wg_scratch_u[lid], wg_scratch_u[lid + s], op); }
+        workgroupBarrier();
+    }
+    let total = wg_scratch_u[0];
+    workgroupBarrier();
+    return total;
+}
+fn wg_reduce_f32(v: f32, lid: u32, op: u32) -> f32 { return wg_reduce_vec4(vec4f(v, 0.0, 0.0, 0.0), lid, op).x; }`;
+/** The subgroup reduction helpers, spliced only with `enable subgroups;` (4.3). */
+export const REDUCE_HELPERS_SUBGROUP_WGSL = /* wgsl */ `override SG_SLOTS: u32 = (WG + SUBGROUP_MIN - 1u) / SUBGROUP_MIN;   // one slot per subgroup; the count is largest when the compiler picks the SMALLEST size
+var<workgroup> sg_counter: atomic<u32>;
+var<workgroup> sg_val_v: array<vec4f, SG_SLOTS>;
+var<workgroup> sg_val_u: array<u32, SG_SLOTS>;
+var<workgroup> sg_key: array<u32, SG_SLOTS>;
+var<workgroup> sg_sorted_v: array<vec4f, SG_SLOTS>;
+var<workgroup> sg_sorted_u: array<u32, SG_SLOTS>;
+fn combine_v(a: vec4f, b: vec4f, op: u32) -> vec4f {
+    if (op == 1u) { return min(a, b); }
+    if (op == 2u) { return max(a, b); }
+    return a + b;
+}
+fn combine_u(a: u32, b: u32, op: u32) -> u32 {
+    if (op == 1u) { return min(a, b); }
+    if (op == 2u) { return max(a, b); }
+    return a + b;
+}
+fn wg_reduce_vec4(v: vec4f, lid: u32, op: u32) -> vec4f {
+    workgroupBarrier();
+    if (lid == 0u) { atomicStore(&sg_counter, 0u); }
+    workgroupBarrier();
+    let s_add = subgroupAdd(v);
+    let s_min = subgroupMin(v);
+    let s_max = subgroupMax(v);
+    var partial = s_add;
+    if (op == 1u) { partial = s_min; }
+    if (op == 2u) { partial = s_max; }
+    let key = subgroupMin(lid);                       // the smallest local id of this subgroup: a stable identity without @builtin(subgroup_id)
+    var slot = 0u;
+    if (subgroupElect()) { slot = atomicAdd(&sg_counter, 1u); }   // D16: the elected lane takes a slot from the counter
+    slot = subgroupBroadcast(slot, 0u);                            // and broadcasts it (lane 0 is the elected lane in uniform control flow)
+    if (subgroupElect()) { sg_val_v[slot] = partial; sg_key[slot] = key; }
+    workgroupBarrier();
+    let count = atomicLoad(&sg_counter);
+    if (lid < count) {                                             // rank the slots by key so the final sum has a fixed order (11.9 item 4)
+        let mine = sg_key[lid];
+        var rank = 0u;
+        for (var k = 0u; k < count; k = k + 1u) { if (sg_key[k] < mine) { rank = rank + 1u; } }
+        sg_sorted_v[rank] = sg_val_v[lid];
+    }
+    workgroupBarrier();
+    var total = sg_sorted_v[0];
+    for (var k = 1u; k < count; k = k + 1u) { total = combine_v(total, sg_sorted_v[k], op); }
+    workgroupBarrier();
+    return total;
+}
+fn wg_reduce_u32(v: u32, lid: u32, op: u32) -> u32 {
+    workgroupBarrier();
+    if (lid == 0u) { atomicStore(&sg_counter, 0u); }
+    workgroupBarrier();
+    let s_add = subgroupAdd(v);
+    let s_min = subgroupMin(v);
+    let s_max = subgroupMax(v);
+    var partial = s_add;
+    if (op == 1u) { partial = s_min; }
+    if (op == 2u) { partial = s_max; }
+    let key = subgroupMin(lid);
+    var slot = 0u;
+    if (subgroupElect()) { slot = atomicAdd(&sg_counter, 1u); }
+    slot = subgroupBroadcast(slot, 0u);
+    if (subgroupElect()) { sg_val_u[slot] = partial; sg_key[slot] = key; }
+    workgroupBarrier();
+    let count = atomicLoad(&sg_counter);
+    if (lid < count) {
+        let mine = sg_key[lid];
+        var rank = 0u;
+        for (var k = 0u; k < count; k = k + 1u) { if (sg_key[k] < mine) { rank = rank + 1u; } }
+        sg_sorted_u[rank] = sg_val_u[lid];
+    }
+    workgroupBarrier();
+    var total = sg_sorted_u[0];
+    for (var k = 1u; k < count; k = k + 1u) { total = combine_u(total, sg_sorted_u[k], op); }
+    workgroupBarrier();
+    return total;
+}
+fn wg_reduce_f32(v: f32, lid: u32, op: u32) -> f32 { return wg_reduce_vec4(vec4f(v, 0.0, 0.0, 0.0), lid, op).x; }`;
+/** The helper function names a body may call when its spec lists needs: ["subgroups"]. */
+export const REDUCE_HELPER_NAMES = ["wg_reduce_f32", "wg_reduce_u32", "wg_reduce_vec4"];
+/**
+ * The WGSL reserved words of spec section 16.2 (the `_reserved` production), frozen; composeWgsl rejects a body or
+ * snippet that uses one (3.9). PLAN DECISION: the list is the 146 words of the W3C Candidate Recommendation Draft
+ * of 2026-08-31 (identical to the editor's draft of 2026-09-01); the contract's count of 147 predates the removal
+ * of `binding_array`. `free`, `valid`, `tile`, `slot`, `key` and `count` are NOT reserved.
+ */
+export const WGSL_RESERVED_WORDS = Object.freeze(`NULL Self abstract active alignas alignof as asm asm_fragment async attribute auto await become cast catch class
+    co_await co_return co_yield coherent column_major common compile compile_fragment concept const_cast consteval
+    constexpr constinit crate debugger decltype delete demote demote_to_helper do dynamic_cast enum explicit export
+    extends extern external fallthrough filter final finally friend from fxgroup get goto groupshared highp impl
+    implements import inline instanceof interface layout lowp macro macro_rules match mediump meta mod module move
+    mut mutable namespace new nil noexcept noinline nointerpolation non_coherent noncoherent noperspective null
+    nullptr of operator package packoffset partition pass patch pixelfragment precise precision premerge priv
+    protected pub public readonly ref regardless register reinterpret_cast require resource restrict self set shared
+    sizeof smooth snorm static static_assert static_cast std subroutine super target template this thread_local
+    throw trait try type typedef typeid typename typeof union unless unorm unsafe unsized use using varying virtual
+    volatile wgsl where with writeonly yield`
+    .trim()
+    .split(/\s+/));
+//# sourceMappingURL=prelude.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../../src/kernel/prelude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EACH,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,OAAO,EACP,cAAc,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,gBAAgB,CAAC,oBAAoB,EAAE,mBAAmB,KAAK,yBAAyB,EAAE;YAChG,QAAQ,EAAE,OAAO;YACjB,KAAK;YACL,QAAQ,EAAE,iBAAiB;SAC9B,CAAC,CAAC;IACP,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;AAClD,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,MAAM,YAAY,GAAW,UAAU,CAAC;6BAClB,aAAa;uBACnB,OAAO;sCACQ,sBAAsB;8BAC9B,cAAc,CAAC,kBAAkB,CAAC;iCAC/B,cAAc,CAAC,qBAAqB,CAAC;iCACrC,cAAc,CAAC,iBAAiB,CAAC;8BACpC,cAAc;;qBAEvB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BjC,CAAC;AAEH,8GAA8G;AAC9G,MAAM,CAAC,MAAM,aAAa,GAAW,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAErE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,6BAA6B,GAAW,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kHAoCkD,CAAC;AAEnH,mFAAmF;AACnF,MAAM,CAAC,MAAM,4BAA4B,GAAW,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kHA2EmD,CAAC;AAEnH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,eAAe,EAAE,eAAe,EAAE,gBAAgB,CAAU,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAC/D;;;;;;;;;;6CAUyC;KACpC,IAAI,EAAE;KACN,KAAK,CAAC,KAAK,CAAC,CACpB,CAAC"}

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

@@ -0,0 +1,64 @@
+/**
+ * Timestamp profiling of spec 5.5: when "timestamp-query" was granted the context owns a Profiler
+ * whose query set (PROFILER_QUERY_SLOTS slots, two per pass) is written by the timestampWrites of
+ * every CommandBatch pass; `resolveInto(batch)` records the resolve plus a copy into the batch's
+ * staging slot and `timings(bytes, request)` decodes `{ label, ns }` per pass from the batch's
+ * readback bytes. Chromium quantises timestamps to 100 us (`quantised: true`); Dawn-node reports
+ * 1,024 ns ticks (spec 2.6). The profiler never throws: a full query set drops timings and a device
+ * without the feature disables it. Slot pairs are handed out in order and the cursor restarts at 0
+ * after every resolve: queue order guarantees the resolve of batch A reads its slots before batch B
+ * overwrites them, and one resolve buffer suffices for the same reason.
+ */
+import type { CommandBatch, ReadbackRequest } from "./batch.js";
+/** One resolved pass timing. */
+export interface PassTiming {
+    readonly label: string;
+    readonly ns: number;
+}
+/** Timestamp profiling when "timestamp-query" was granted (spec 5.5). */
+export declare class Profiler {
+    /** True when the feature was granted and a query set exists. */
+    readonly enabled: boolean;
+    /** True in browsers (100 us quantisation), false under Dawn-node (spec 2.6). */
+    readonly quantised: boolean;
+    private readonly slots;
+    private readonly querySet;
+    private readonly resolveBuffer;
+    private readonly labels;
+    private pending;
+    private cursor;
+    private destroyed;
+    /**
+     * Creates the query set and the resolve buffer when usable; `slots` defaults to PROFILER_QUERY_SLOTS = 256
+     * (spec 5.5); 2 query slots per pass. `enabled` is also false when the device lacks "timestamp-query" or
+     * `slots < 2`, so no caller can make the profiler raise a validation error.
+     * @param device - the device the query set is created on
+     * @param enabled - whether the caller wants profiling (the context passes `features.has("timestamp-query")`)
+     * @param quantised - true in browsers
+     * @param slots - query slots, two per pass (default PROFILER_QUERY_SLOTS)
+     */
+    constructor(device: GPUDevice, enabled: boolean, quantised: boolean, slots?: number);
+    /**
+     * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots.
+     * @param label - the pass name reported by `timings()`
+     * @returns the descriptor a CommandBatch puts on beginComputePass, or undefined
+     */
+    beginPass(label: string): GPUComputePassTimestampWrites | undefined;
+    /**
+     * Records the resolve + copy into the batch's staging slot; returns the request's byte range, or null when
+     * nothing was written (disabled, destroyed, or no pass begun since the last resolve).
+     * @param batch - the batch whose passes were timed (it must still be open)
+     * @returns the readback request `timings()` decodes, or null
+     */
+    resolveInto(batch: CommandBatch): ReadbackRequest | null;
+    /**
+     * Decodes the timings of a batch from its readback bytes.
+     * @param bytes - the resolved readback of the batch
+     * @param request - the request `resolveInto()` returned for it
+     * @returns one timing per pass in pass order (empty for a request this profiler did not create)
+     */
+    timings(bytes: ArrayBuffer, request: ReadbackRequest): readonly PassTiming[];
+    /** Destroys the query set and the resolve buffer; idempotent. */
+    destroy(): void;
+}
+//# sourceMappingURL=profiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profiler.d.ts","sourceRoot":"","sources":["../../../src/kernel/profiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhE,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACvB;AAQD,yEAAyE;AACzE,qBAAa,QAAQ;IACjB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;IAC5E,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;;;;OAQG;gBACS,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM;IAmBnF;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,6BAA6B,GAAG,SAAS;IAUnE;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI;IAgBxD;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,UAAU,EAAE;IAmB5E,iEAAiE;IACjE,OAAO,IAAI,IAAI;CAclB"}