@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.1

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

@@ -0,0 +1,116 @@
+/**
+ * The CommandBatch of spec 5.8: one GPUCommandEncoder, one compute pass per "phase" (a pass may hold
+ * many dispatches; dispatches inside a pass are ordered), the staging copies of every readback
+ * request at the end, and ONE queue.submit. The batch borrows one slot of the Readback ring for its
+ * lifetime (spec 4.4) and returns it when its readback settles -- resolved, discarded or rejected --
+ * so the ring never grows because of a slot left pending. mapAsync on that slot is the completion
+ * signal; a batch never calls onSubmittedWorkDone.
+ *
+ * Errors (spec 5.7): under Dawn-node an uncapturederror is delivered SYNCHRONOUSLY inside the API
+ * call that fails, so an error pending in the context's slot when submit() runs belongs to this batch
+ * and rejects ITS OWN readback (an invalid command buffer is a no-op submit; the staging bytes would be
+ * stale). In browsers delivery is asynchronous: the batch takes the slot again after its map completes,
+ * and whatever arrives later is thrown by the context's next public call. Device loss is raced against
+ * the map, so a readback rejects E_DEVICE_LOST whether the runtime rejects, resolves or never settles
+ * the pending map of a destroyed buffer; the slot goes back only once the map has settled (or the grace
+ * ran out), because a staging buffer is never unmapped while its map is pending (readback.ts).
+ */
+import type { AllocationTracker } from "../device/error-scope.js";
+import { WebGpuGraphError } from "../errors.js";
+import type { Readback } from "../memory/readback.js";
+import type { Binding } from "../types/memory.js";
+import type { Profiler } from "./profiler.js";
+/** What a CommandBatch needs of its owner (GpuContext satisfies it structurally; kernel/ never imports context.ts). */
+export interface BatchHost {
+    readonly device: GPUDevice;
+    readonly readback: Readback;
+    readonly profiler: Profiler | null;
+    readonly allocator: AllocationTracker;
+    assertReady(): void;
+    takePendingError(): WebGpuGraphError | null;
+    nextBatchId(): number;
+    /** Registers a device-loss listener and returns the unregister function (GpuContext.onLost, contract 3.5): the batch races its map against loss. PLAN DECISION 1: an amendment to contract 3.9, which declares the seven members above. */
+    onLost(listener: (info: GPUDeviceLostInfo) => void): () => void;
+}
+/** A readback scheduled into the batch's staging slot: `offset` is the slot-relative byte offset the caller reads at. */
+export interface ReadbackRequest {
+    readonly src: GPUBuffer;
+    readonly srcOffset: number;
+    readonly byteLength: number;
+    readonly offset: number;
+}
+/** What submit() returns (spec 5.8). `readback` resolves with the mapped bytes COPIED out (one ArrayBuffer holding every request at its offset) after allocator.check(); it rejects with E_VALIDATION { batchId } when the pending-error slot held an error right after submit and with E_DEVICE_LOST after loss; a discarded batch resolves an empty ArrayBuffer (see discard()). */
+export interface SubmittedBatch {
+    readonly id: number;
+    readonly generation: number;
+    readonly readback: Promise<ArrayBuffer>;
+    /** Marks the batch stale: its readback still awaits mapAsync (so the slot is returned) but resolves with an empty ArrayBuffer and the caller ignores it (spec 7.19 item 6). */
+    discard(): void;
+}
+/** Records dispatches / copies into one encoder and submits once (spec 5.8). */
+export declare class CommandBatch {
+    readonly id: number;
+    readonly generation: number;
+    readonly label: string;
+    private readonly host;
+    private readonly encoder;
+    private readonly requests;
+    private openPass;
+    private dispatchCount;
+    private stagingBytes;
+    private slot;
+    private submitted;
+    /**
+     * Creates the encoder; the id comes from host.nextBatchId().
+     * @param host - the owner (the GpuContext)
+     * @param label - names the encoder, its passes and the E_VALIDATION details
+     * @param generation - the simulation generation the batch carries (default 0)
+     */
+    constructor(host: BatchHost, label: string, generation?: number);
+    /**
+     * Dispatch count recorded so far (tests bound it).
+     * @returns the number of dispatchWorkgroups / dispatchWorkgroupsIndirect calls on this batch's passes
+     */
+    get dispatches(): number;
+    /**
+     * Begins a compute pass (ending the previous one); with a profiler present the pass carries timestampWrites and
+     * `label` names it in Profiler.resolveInto / timings.
+     * @param label - the pass name
+     * @returns the pass encoder kernels dispatch into
+     */
+    pass(label: string): GPUComputePassEncoder;
+    /** Ends the open pass, if any. */
+    endPass(): void;
+    /**
+     * copyBufferToBuffer between two bindings (after endPass).
+     * @param src - the source range
+     * @param dst - the destination range
+     * @param byteLength - a positive multiple of 4 no larger than either binding
+     */
+    copy(src: Binding, dst: Binding, byteLength: number): void;
+    /**
+     * Schedules a copy of `byteLength` bytes from `src` into the borrowed staging slot; the slot is borrowed at the
+     * first request and re-borrowed larger when the sum of requests outgrows it (nothing is recorded before submit).
+     * @param src - the source buffer
+     * @param srcOffset - a non-negative multiple of 4
+     * @param byteLength - a positive multiple of 4 with srcOffset + byteLength <= src.size
+     * @returns the request; `offset` is where the caller reads inside the readback bytes
+     */
+    readback(src: GPUBuffer, srcOffset: number, byteLength: number): ReadbackRequest;
+    /**
+     * Ends passes, records the staging copies, submits, checks the pending-error slot (spec 5.7), returns the handle.
+     * A batch can be submitted once; submit() after device loss throws E_DEVICE_LOST.
+     * @returns the submitted-batch handle
+     */
+    submit(): SubmittedBatch;
+    private rejectReadback;
+    private awaitReadback;
+    private classify;
+    private attribute;
+    private ensureSlot;
+    private releaseSlot;
+    private countDispatches;
+    private assertOpen;
+    private checkByteLength;
+}
+//# sourceMappingURL=batch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/kernel/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAwC9C,uHAAuH;AACvH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,WAAW,IAAI,IAAI,CAAC;IACpB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAC5C,WAAW,IAAI,MAAM,CAAC;IACtB,2OAA2O;IAC3O,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,yHAAyH;AACzH,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,sXAAsX;AACtX,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACxC,+KAA+K;IAC/K,OAAO,IAAI,IAAI,CAAC;CACnB;AAOD,gFAAgF;AAChF,qBAAa,YAAY;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;OAKG;gBACS,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAQ/D;;;OAGG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB;IAc1C,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAOf;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAkB1D;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe;IAmChF;;;;OAIG;IACH,MAAM,IAAI,cAAc;IAyCxB,OAAO,CAAC,cAAc;YAKR,aAAa;YAiCb,QAAQ;IAwCtB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,eAAe;CAa1B"}

package/dist/src/kernel/batch.js

@@ -0,0 +1,335 @@
+/**
+ * The CommandBatch of spec 5.8: one GPUCommandEncoder, one compute pass per "phase" (a pass may hold
+ * many dispatches; dispatches inside a pass are ordered), the staging copies of every readback
+ * request at the end, and ONE queue.submit. The batch borrows one slot of the Readback ring for its
+ * lifetime (spec 4.4) and returns it when its readback settles -- resolved, discarded or rejected --
+ * so the ring never grows because of a slot left pending. mapAsync on that slot is the completion
+ * signal; a batch never calls onSubmittedWorkDone.
+ *
+ * Errors (spec 5.7): under Dawn-node an uncapturederror is delivered SYNCHRONOUSLY inside the API
+ * call that fails, so an error pending in the context's slot when submit() runs belongs to this batch
+ * and rejects ITS OWN readback (an invalid command buffer is a no-op submit; the staging bytes would be
+ * stale). In browsers delivery is asynchronous: the batch takes the slot again after its map completes,
+ * and whatever arrives later is thrown by the context's next public call. Device loss is raced against
+ * the map, so a readback rejects E_DEVICE_LOST whether the runtime rejects, resolves or never settles
+ * the pending map of a destroyed buffer; the slot goes back only once the map has settled (or the grace
+ * ran out), because a staging buffer is never unmapped while its map is pending (readback.ts).
+ */
+import { deviceLostError } from "../device/lost.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+/** How long a batch waits for the context's loss fan-out after its map rejected with a foreign error (a destroyed buffer rejects before device.lost settles), and for the runtime to settle a pending map after the loss won the race. */
+const LOSS_GRACE_MS = 2000;
+/**
+ * Resolves when the promise settles either way, or after the grace (a runtime that never settles a pending map).
+ * @param pending - the promise
+ * @param graceMs - the ceiling
+ */
+async function settled(pending, graceMs) {
+    let timer;
+    const grace = new Promise((resolve) => {
+        timer = setTimeout(resolve, graceMs);
+    });
+    await Promise.race([
+        pending.then(() => undefined, () => undefined),
+        grace,
+    ]);
+    clearTimeout(timer);
+}
+/**
+ * A plain message for a thrown value (the house pattern of graph-io's report.ts).
+ * @param error - whatever the runtime rejected with
+ * @returns the Error message, the string itself, or a typeof note
+ */
+function messageOf(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return `non-error thrown (${typeof error})`;
+}
+/** Records dispatches / copies into one encoder and submits once (spec 5.8). */
+export class CommandBatch {
+    /**
+     * Creates the encoder; the id comes from host.nextBatchId().
+     * @param host - the owner (the GpuContext)
+     * @param label - names the encoder, its passes and the E_VALIDATION details
+     * @param generation - the simulation generation the batch carries (default 0)
+     */
+    constructor(host, label, generation) {
+        this.requests = [];
+        this.openPass = null;
+        this.dispatchCount = 0;
+        this.stagingBytes = 0;
+        this.slot = null;
+        this.submitted = false;
+        this.host = host;
+        this.id = host.nextBatchId();
+        this.generation = generation ?? 0;
+        this.label = label;
+        this.encoder = host.device.createCommandEncoder({ label: `batch/${label}#${this.id}` });
+    }
+    /**
+     * Dispatch count recorded so far (tests bound it).
+     * @returns the number of dispatchWorkgroups / dispatchWorkgroupsIndirect calls on this batch's passes
+     */
+    get dispatches() {
+        return this.dispatchCount;
+    }
+    /**
+     * Begins a compute pass (ending the previous one); with a profiler present the pass carries timestampWrites and
+     * `label` names it in Profiler.resolveInto / timings.
+     * @param label - the pass name
+     * @returns the pass encoder kernels dispatch into
+     */
+    pass(label) {
+        this.assertOpen("pass");
+        this.endPass();
+        const descriptor = { label: `batch/${this.label}#${this.id}/${label}` };
+        const timestampWrites = this.host.profiler?.beginPass(label);
+        if (timestampWrites !== undefined) {
+            descriptor.timestampWrites = timestampWrites;
+        }
+        const pass = this.encoder.beginComputePass(descriptor);
+        this.countDispatches(pass);
+        this.openPass = pass;
+        return pass;
+    }
+    /** Ends the open pass, if any. */
+    endPass() {
+        if (this.openPass !== null) {
+            this.openPass.end();
+            this.openPass = null;
+        }
+    }
+    /**
+     * copyBufferToBuffer between two bindings (after endPass).
+     * @param src - the source range
+     * @param dst - the destination range
+     * @param byteLength - a positive multiple of 4 no larger than either binding
+     */
+    copy(src, dst, byteLength) {
+        this.assertOpen("copy");
+        this.checkByteLength(byteLength);
+        if (byteLength > src.size || byteLength > dst.size) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `copy of ${byteLength} bytes exceeds a binding (src ${src.size}, dst ${dst.size})`, {
+                argument: "byteLength",
+                value: byteLength,
+                expected: `<= ${Math.min(src.size, dst.size)}`,
+            });
+        }
+        this.endPass();
+        this.encoder.copyBufferToBuffer(src.buffer, src.offset, dst.buffer, dst.offset, byteLength);
+    }
+    /**
+     * Schedules a copy of `byteLength` bytes from `src` into the borrowed staging slot; the slot is borrowed at the
+     * first request and re-borrowed larger when the sum of requests outgrows it (nothing is recorded before submit).
+     * @param src - the source buffer
+     * @param srcOffset - a non-negative multiple of 4
+     * @param byteLength - a positive multiple of 4 with srcOffset + byteLength <= src.size
+     * @returns the request; `offset` is where the caller reads inside the readback bytes
+     */
+    readback(src, srcOffset, byteLength) {
+        this.assertOpen("readback");
+        this.checkByteLength(byteLength);
+        if (!Number.isInteger(srcOffset) || srcOffset < 0 || srcOffset % 4 !== 0 || srcOffset + byteLength > src.size) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `readback of [${srcOffset}, ${srcOffset + byteLength}) is outside the ${src.size}-byte source or not 4-aligned`, {
+                argument: "srcOffset",
+                value: srcOffset,
+                expected: `a multiple of 4 with srcOffset + byteLength <= ${src.size}`,
+            });
+        }
+        const request = { src, srcOffset, byteLength, offset: this.stagingBytes };
+        this.requests.push(request);
+        this.stagingBytes += byteLength;
+        this.ensureSlot(this.stagingBytes);
+        return request;
+    }
+    /**
+     * Records `resolveQuerySet` after ending the open pass; used by Profiler.resolveInto only.
+     * @internal
+     * @param querySet - the timestamp query set
+     * @param firstQuery - first query index
+     * @param queryCount - number of queries
+     * @param destination - a QUERY_RESOLVE | COPY_SRC buffer written at offset 0
+     */
+    resolveQuerySet(querySet, firstQuery, queryCount, destination) {
+        this.assertOpen("resolveQuerySet");
+        this.endPass();
+        this.encoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, 0);
+    }
+    /**
+     * Ends passes, records the staging copies, submits, checks the pending-error slot (spec 5.7), returns the handle.
+     * A batch can be submitted once; submit() after device loss throws E_DEVICE_LOST.
+     * @returns the submitted-batch handle
+     */
+    submit() {
+        this.assertOpen("submit");
+        this.submitted = true;
+        this.endPass();
+        const { slot } = this;
+        const pendingBefore = this.host.takePendingError();
+        try {
+            this.host.assertReady();
+        }
+        catch (error) {
+            this.releaseSlot();
+            throw error;
+        }
+        if (slot !== null) {
+            for (const request of this.requests) {
+                this.encoder.copyBufferToBuffer(request.src, request.srcOffset, slot.buffer, request.offset, request.byteLength);
+            }
+        }
+        const commandBuffer = this.encoder.finish({ label: `batch/${this.label}#${this.id}` });
+        this.host.device.queue.submit([commandBuffer]);
+        // the slot is drained a second time so a finish() / submit() error raised by a command buffer the first error
+        // already invalidated never leaks to the next public call; the FIRST error is the one reported
+        const pendingAfter = this.host.takePendingError();
+        const pending = pendingBefore ?? pendingAfter;
+        const state = { discarded: false };
+        const readback = pending === null ? this.awaitReadback(slot, state) : this.rejectReadback(pending);
+        return {
+            id: this.id,
+            generation: this.generation,
+            readback,
+            discard: () => {
+                state.discarded = true;
+            },
+        };
+    }
+    rejectReadback(pending) {
+        this.releaseSlot();
+        return Promise.reject(this.attribute(pending));
+    }
+    async awaitReadback(slot, state) {
+        if (slot === null) {
+            await this.host.allocator.check();
+            return new ArrayBuffer(0);
+        }
+        const total = this.stagingBytes;
+        let unregister = () => undefined;
+        const lost = new Promise((_resolve, reject) => {
+            unregister = this.host.onLost((info) => {
+                reject(deviceLostError(info));
+            });
+        });
+        void lost.catch(() => undefined);
+        const mapped = this.host.readback.mapSlot(slot, total);
+        void mapped.catch(() => undefined);
+        let bytes;
+        try {
+            await Promise.race([mapped, lost]);
+            this.host.assertReady();
+            bytes = state.discarded ? new ArrayBuffer(0) : slot.buffer.getMappedRange(0, total).slice(0);
+        }
+        catch (error) {
+            // the loss may have won the race: let the runtime settle the map before the slot is unmapped and returned
+            await settled(mapped, LOSS_GRACE_MS);
+            this.releaseSlot();
+            throw await this.classify(error, lost);
+        }
+        finally {
+            unregister();
+        }
+        this.releaseSlot();
+        await this.host.allocator.check();
+        return bytes;
+    }
+    async classify(error, lost) {
+        if (isWebGpuGraphError(error)) {
+            return error.code === "E_DEVICE_LOST" || error.code === "E_DISPOSED" ? error : this.attribute(error);
+        }
+        try {
+            this.host.assertReady();
+        }
+        catch (state) {
+            if (isWebGpuGraphError(state)) {
+                return state.code === "E_DEVICE_LOST" || state.code === "E_DISPOSED" ? state : this.attribute(state);
+            }
+        }
+        let timer;
+        const grace = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                resolve(null);
+            }, LOSS_GRACE_MS);
+        });
+        const late = await Promise.race([
+            lost.then(() => null, (reason) => reason),
+            grace,
+        ]);
+        clearTimeout(timer);
+        if (isWebGpuGraphError(late)) {
+            return late;
+        }
+        const message = messageOf(error);
+        return new WebGpuGraphError("E_VALIDATION", `mapAsync failed for batch ${this.id} "${this.label}": ${message}`, {
+            label: this.label,
+            message,
+            batchId: this.id,
+        });
+    }
+    attribute(error) {
+        return new WebGpuGraphError(error.code, `${error.message} (delivered to batch ${this.id} "${this.label}")`, {
+            ...error.details,
+            batchId: this.id,
+            batchLabel: this.label,
+        });
+    }
+    ensureSlot(byteLength) {
+        if (this.slot !== null && this.slot.capacity >= byteLength) {
+            return;
+        }
+        this.releaseSlot();
+        this.slot = this.host.readback.borrowSlot(byteLength);
+    }
+    releaseSlot() {
+        if (this.slot === null) {
+            return;
+        }
+        const { slot } = this;
+        this.slot = null;
+        try {
+            this.host.readback.returnSlot(slot);
+        }
+        catch (error) {
+            if (!isWebGpuGraphError(error) || error.code !== "E_DISPOSED") {
+                throw error;
+            }
+        }
+    }
+    countDispatches(pass) {
+        const direct = pass.dispatchWorkgroups.bind(pass);
+        const indirect = pass.dispatchWorkgroupsIndirect.bind(pass);
+        pass.dispatchWorkgroups = (x, y, z) => {
+            this.dispatchCount += 1;
+            direct(x, y, z);
+            return undefined;
+        };
+        pass.dispatchWorkgroupsIndirect = (buffer, offset) => {
+            this.dispatchCount += 1;
+            indirect(buffer, offset);
+            return undefined;
+        };
+    }
+    assertOpen(operation) {
+        if (this.submitted) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${operation}() after submit() on batch ${this.id} "${this.label}"`, {
+                argument: operation,
+                value: this.id,
+                expected: "a batch that has not been submitted",
+            });
+        }
+    }
+    checkByteLength(byteLength) {
+        if (!Number.isInteger(byteLength) || byteLength <= 0 || byteLength % 4 !== 0) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `byteLength ${byteLength} is not a positive multiple of 4`, {
+                argument: "byteLength",
+                value: byteLength,
+                expected: "a positive multiple of 4",
+            });
+        }
+    }
+}
+//# sourceMappingURL=batch.js.map

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * 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 { type PlanCaps } from "../types/context.js";
+/** A dispatch shape (spec 5.2). `stride` is the grid-stride step (null for plain 1D / 2D plans). */
+export interface DispatchPlan {
+    readonly x: number;
+    readonly y: number;
+    readonly z: 1;
+    readonly items: number;
+    readonly stride: number | 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 declare function plan1d(items: number, wg: number, caps: PlanCaps): DispatchPlan;
+/**
+ * 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 declare function plan2d(groups: number, caps: PlanCaps): DispatchPlan;
+/**
+ * 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 declare function planGridStride(items: number, wg: number, caps: PlanCaps, maxGroups?: number): DispatchPlan;
+/**
+ * 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 declare function planIndirect(count: number, wg: number, caps: PlanCaps): DispatchPlan;
+/**
+ * The workgroup count of a plan (x * y).
+ * @param plan - the plan
+ * @returns the count
+ */
+export declare function groupsOf(plan: DispatchPlan): number;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/kernel/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,oGAAoG;AACpG,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AA8ED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAI9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAGnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAK1G;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAKpF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEnD"}