@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/dist/src/primitives/histogram.js

@@ -0,0 +1,190 @@
+/**
+ * The `histogram` and `countingSortByKey` primitive drivers (spec 6 row 5; P4-T3, PD-4). `histogram` zeroes `hist`
+ * with a `fill` dispatch and then adds one per key in global memory: order-independent, so bitwise deterministic on
+ * every adapter. `countingSortByKey` is the histogram, an exclusive scan of it into `outStart`, a zeroed per-bin
+ * `cursor`, and the scatter `outIndex[outStart[k] + atomicAdd(&cursor[k], 1)] = i`: the SET of indices inside a bin
+ * is fixed, their order follows the schedule (set-deterministic, design 6). Every zeroing is a dispatch inside the
+ * caller's pass (PD-12), never an encoder clear.
+ *
+ * The drivers own no device objects: the caller supplies a ReduceScope (the same record `reduce` takes) and the
+ * compute pass to record into. `src/primitives/**` never imports `src/context.ts`.
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { FILL_PARAMS, HIST_PARAMS, kernelSpec } from "../kernels.js";
+import { prepareScan } from "./scan.js";
+/** The largest u32: the largest value `HistParams.count` / `bins` can carry. */
+const U32_MAX = 0xffffffff;
+/**
+ * Prepares the histogram pipelines of a scope (compiles `histogram` and `fill` once) so record() is synchronous.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export async function prepareHistogram(scope) {
+    return prepareHistogramImpl(scope);
+}
+/**
+ * The concrete histogram planner (its recordZero is what the counting sort reuses for the cursor).
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+async function prepareHistogramImpl(scope) {
+    const histogram = await scope.pipelines.kernel(kernelSpec("histogram"));
+    const fill = await scope.pipelines.kernel(kernelSpec("fill"));
+    return new HistogramPlannerImpl(scope, histogram, fill);
+}
+/**
+ * Prepares the counting-sort pipelines of a scope (the histogram's, the scan's and `counting-scatter`) so record()
+ * is synchronous. The planner lives exactly as long as the scope (the scan keeps a scratch word of it).
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+export async function prepareCountingSort(scope) {
+    const histogram = await prepareHistogramImpl(scope);
+    const scan = await prepareScan(scope);
+    const scatter = await scope.pipelines.kernel(kernelSpec("counting-scatter"));
+    return new CountingSortPlannerImpl(scope, histogram, scan, scatter);
+}
+/**
+ * The E_INVALID_ARGUMENT of a binding shorter than `words` u32.
+ * @param name - the argument name
+ * @param binding - the binding
+ * @param words - the words it must hold
+ */
+function checkWords(name, binding, words) {
+    if (binding.size < 4 * words) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `histogram: ${name} is smaller than 4 x ${words} bytes`, {
+            argument: name,
+            value: binding.size,
+            expected: 4 * words,
+        });
+    }
+}
+/**
+ * The argument checks shared by both record() methods (E_INVALID_ARGUMENT before anything is recorded).
+ * @param keys - the keys binding
+ * @param count - the key count
+ * @param bins - the bin count
+ * @param hist - the histogram binding
+ */
+function checkHistogramArguments(keys, count, bins, hist) {
+    if (!Number.isSafeInteger(count) || count < 0 || count > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "histogram: count must be a non-negative integer below 2^32", {
+            argument: "count",
+            value: count,
+        });
+    }
+    if (!Number.isSafeInteger(bins) || bins < 1 || bins > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "histogram: bins must be an integer in [1, 2^32)", {
+            argument: "bins",
+            value: bins,
+        });
+    }
+    checkWords("keys", keys, count);
+    checkWords("hist", hist, bins);
+}
+/** The planner: the histogram and fill kernels over one scope. */
+class HistogramPlannerImpl {
+    /**
+     * Wraps the resolved kernels; use prepareHistogram().
+     * @param scope - the caller's scope
+     * @param histogram - the `histogram` kernel
+     * @param fill - the `fill` kernel
+     */
+    constructor(scope, histogram, fill) {
+        this.dispatches = 0;
+        this.scope = scope;
+        this.histogram = histogram;
+        this.fill = fill;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Records the fill and the histogram (see the interface).
+     * @param pass - the compute pass
+     * @param keys - the keys
+     * @param count - the key count
+     * @param bins - the bin count
+     * @param hist - the counts
+     */
+    record(pass, keys, count, bins, hist) {
+        checkHistogramArguments(keys, count, bins, hist);
+        this.recordZero(pass, hist, bins);
+        this.dispatches = 1;
+        if (count === 0) {
+            return;
+        }
+        const params = this.scope.params(HIST_PARAMS, { count, bins, pad0: 0, pad1: 0 });
+        const bound = this.histogram.bind({ keys, hist, P: params.binding });
+        this.histogram.dispatch(pass, bound, plan1d(count, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+        this.dispatches = 2;
+    }
+    /**
+     * Records a `fill` of `words` zeros into `dst` (PD-12: a dispatch inside the pass, never an encoder clear).
+     * @param pass - the compute pass
+     * @param dst - the words to zero
+     * @param words - how many (>= 1)
+     */
+    recordZero(pass, dst, words) {
+        const params = this.scope.params(FILL_PARAMS, { count: words, value: 0, mode: 0, pad0: 0 });
+        const bound = this.fill.bind({ dst, P: params.binding });
+        this.fill.dispatch(pass, bound, plan1d(words, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+    }
+}
+/** The planner: the histogram planner, the scan planner and the scatter kernel over one scope. */
+class CountingSortPlannerImpl {
+    /**
+     * Wraps the resolved planners and kernel; use prepareCountingSort().
+     * @param scope - the caller's scope
+     * @param histogram - the histogram planner (also the zeroing of the cursor)
+     * @param scan - the scan planner
+     * @param scatter - the `counting-scatter` kernel
+     */
+    constructor(scope, histogram, scan, scatter) {
+        this.dispatches = 0;
+        this.scope = scope;
+        this.histogram = histogram;
+        this.scan = scan;
+        this.scatter = scatter;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Records the four stages (see the interface).
+     * @param pass - the compute pass
+     * @param keys - the keys
+     * @param count - the key count
+     * @param bins - the bin count
+     * @param scratch - the histogram and cursor
+     * @param outIndex - the sorted indices
+     * @param outStart - the bin starts
+     */
+    record(pass, keys, count, bins, scratch, outIndex, outStart) {
+        checkHistogramArguments(keys, count, bins, scratch.hist);
+        checkWords("cursor", scratch.cursor, bins);
+        checkWords("outIndex", outIndex, count);
+        checkWords("outStart", outStart, bins);
+        this.histogram.record(pass, keys, count, bins, scratch.hist);
+        this.scan.record(pass, scratch.hist, bins, outStart);
+        this.histogram.recordZero(pass, scratch.cursor, bins);
+        this.dispatches = this.histogram.lastDispatches + this.scan.lastDispatches + 1;
+        if (count === 0) {
+            return;
+        }
+        const params = this.scope.params(HIST_PARAMS, { count, bins, pad0: 0, pad1: 0 });
+        const bound = this.scatter.bind({ keys, start: outStart, cursor: scratch.cursor, outIndex, P: params.binding });
+        this.scatter.dispatch(pass, bound, plan1d(count, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+        this.dispatches += 1;
+    }
+}
+//# sourceMappingURL=histogram.js.map

package/dist/src/primitives/histogram.js.map

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

package/dist/src/primitives/radix-sort.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The `radixSort` primitive driver (spec 6 row 6; P4-T4, PD-5): a STABLE LSD key-value sort of u32 words, 8 bits per
+ * pass, `bits / 8` passes. Every pass runs `radix-hist` (one 256-bin digit histogram per WG-wide block, stored
+ * DIGIT-MAJOR `hist[digit * groups + group]`), `exclusiveScan` over that table (so each word becomes, per digit, the
+ * offset of its workgroup in workgroup order) and `radix-scatter` (lane 0 ranks its block's keys serially in index
+ * order, every lane writes its pair at `offsets[digit * groups + group] + rank`). The pairs swap after every pass, so an
+ * odd pass count (bits 8 / 24) leaves the result in the caller's scratch pair and an even one (16 / 32) in the input
+ * pair; record() RETURNS the pair so no caller guesses. u32 arithmetic and a serial ranking make two runs on any two
+ * adapters bitwise identical.
+ *
+ * The scan cannot run in place: `Kernel.bind` (and WebGPU's usage-scope rule) rejects one buffer bound `storage-ro`
+ * and `storage` in one dispatch, so the caller supplies TWO tables of `radixHistBytes`: `scratch.hist` (the raw
+ * digit-major table `radix-hist` writes; the LAST pass's table stays there) and `scratch.offsets` (its exclusive
+ * scan, what `radix-scatter` reads). Both are the caller's so a per-iteration sort (the grid, PD-11) binds the same
+ * buffers every iteration and `Kernel.bind`'s identity cache holds.
+ *
+ * The driver owns no device objects and acquires no scratch of its own: the caller supplies a ReduceScope (the
+ * record `reduce` and `exclusiveScan` take; the scan's block sums come from it) and the compute pass to record
+ * into. `src/primitives/**` never imports `src/context.ts`.
+ */
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+/** The key widths record() accepts: `bits / 8` passes, so the low `bits` of every key order the pairs. */
+export type RadixBits = 8 | 16 | 24 | 32;
+/**
+ * The caller's scratch: a second key-value pair the passes ping-pong with, the digit-major histogram table and its
+ * scanned twin (each `radixHistBytes` bytes at least).
+ */
+export interface RadixSortScratch {
+    readonly keys: Binding;
+    readonly vals: Binding;
+    /** The raw digit-major table `radix-hist` writes (the last pass's stays readable after the sort). */
+    readonly hist: Binding;
+    /** The exclusive scan of `hist`, what `radix-scatter` reads. */
+    readonly offsets: Binding;
+}
+/** Where the sorted pairs landed: the input pair or the scratch pair (record() decides by the pass count). */
+export interface RadixSortResult {
+    readonly keys: Binding;
+    readonly vals: Binding;
+}
+/** A prepared radix sort (spec 6 row 6): records the pass dispatches of one sort into a pass. */
+export interface RadixSortPlanner {
+    /**
+     * Records the stable sort of `count` (key, value) pairs by the low `bits` of the key; returns the pair holding the
+     * result (the scratch pair after an odd pass count, the input pair after an even one); count 0 records nothing and
+     * returns the input pair.
+     * @param pass - the compute pass
+     * @param keys - the keys (at least 4 x count bytes)
+     * @param vals - the values (at least 4 x count bytes)
+     * @param count - the pair count (a non-negative integer below 2^32)
+     * @param bits - the key width: 8, 16, 24 or 32
+     * @param scratch - the second pair, the histogram table and its scanned twin
+     * @returns the pair the result lives in
+     */
+    record(pass: GPUComputePassEncoder, keys: Binding, vals: Binding, count: number, bits: RadixBits, scratch: RadixSortScratch): RadixSortResult;
+    /** Dispatches the last record() issued: 0 for count 0, else `passes x (2 + the scan's dispatches over the table)`. */
+    readonly lastDispatches: number;
+}
+/**
+ * The byte size of the digit-major histogram table of one pass over `count` keys at workgroup size `wg`:
+ * `4 x 256 x ceil(count / wg)` (the caller sizes `scratch.hist` by it; 0 for count 0, which records nothing).
+ * @param count - the pair count
+ * @param wg - the workgroup size (`scope.workgroupSize`)
+ * @returns the bytes
+ */
+export declare function radixHistBytes(count: number, wg: number): number;
+/**
+ * Prepares the two radix pipelines and the scan of a scope (compiles once) so record() is synchronous. The planner
+ * lives exactly as long as the scope: never use a planner after its scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export declare function prepareRadixSort(scope: ReduceScope): Promise<RadixSortPlanner>;
+//# sourceMappingURL=radix-sort.d.ts.map

package/dist/src/primitives/radix-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"radix-sort.d.ts","sourceRoot":"","sources":["../../../src/primitives/radix-sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,0GAA0G;AAC1G,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC7B;AAED,8GAA8G;AAC9G,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CAC1B;AAED,iGAAiG;AACjG,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;;;;;OAWG;IACH,MAAM,CACF,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,gBAAgB,GAC1B,eAAe,CAAC;IACnB,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAKpF"}

package/dist/src/primitives/radix-sort.js

@@ -0,0 +1,168 @@
+/**
+ * The `radixSort` primitive driver (spec 6 row 6; P4-T4, PD-5): a STABLE LSD key-value sort of u32 words, 8 bits per
+ * pass, `bits / 8` passes. Every pass runs `radix-hist` (one 256-bin digit histogram per WG-wide block, stored
+ * DIGIT-MAJOR `hist[digit * groups + group]`), `exclusiveScan` over that table (so each word becomes, per digit, the
+ * offset of its workgroup in workgroup order) and `radix-scatter` (lane 0 ranks its block's keys serially in index
+ * order, every lane writes its pair at `offsets[digit * groups + group] + rank`). The pairs swap after every pass, so an
+ * odd pass count (bits 8 / 24) leaves the result in the caller's scratch pair and an even one (16 / 32) in the input
+ * pair; record() RETURNS the pair so no caller guesses. u32 arithmetic and a serial ranking make two runs on any two
+ * adapters bitwise identical.
+ *
+ * The scan cannot run in place: `Kernel.bind` (and WebGPU's usage-scope rule) rejects one buffer bound `storage-ro`
+ * and `storage` in one dispatch, so the caller supplies TWO tables of `radixHistBytes`: `scratch.hist` (the raw
+ * digit-major table `radix-hist` writes; the LAST pass's table stays there) and `scratch.offsets` (its exclusive
+ * scan, what `radix-scatter` reads). Both are the caller's so a per-iteration sort (the grid, PD-11) binds the same
+ * buffers every iteration and `Kernel.bind`'s identity cache holds.
+ *
+ * The driver owns no device objects and acquires no scratch of its own: the caller supplies a ReduceScope (the
+ * record `reduce` and `exclusiveScan` take; the scan's block sums come from it) and the compute pass to record
+ * into. `src/primitives/**` never imports `src/context.ts`.
+ */
+import { RADIX_BINS, U32_MAX } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, RADIX_PARAMS } from "../kernels.js";
+import { prepareScan } from "./scan.js";
+/** The bits of one pass. */
+const RADIX_DIGIT_BITS = 8;
+/**
+ * The byte size of the digit-major histogram table of one pass over `count` keys at workgroup size `wg`:
+ * `4 x 256 x ceil(count / wg)` (the caller sizes `scratch.hist` by it; 0 for count 0, which records nothing).
+ * @param count - the pair count
+ * @param wg - the workgroup size (`scope.workgroupSize`)
+ * @returns the bytes
+ */
+export function radixHistBytes(count, wg) {
+    return 4 * RADIX_BINS * Math.ceil(count / wg);
+}
+/**
+ * Prepares the two radix pipelines and the scan of a scope (compiles once) so record() is synchronous. The planner
+ * lives exactly as long as the scope: never use a planner after its scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export async function prepareRadixSort(scope) {
+    const hist = await scope.pipelines.kernel(kernelSpec("radix-hist"));
+    const scatter = await scope.pipelines.kernel(kernelSpec("radix-scatter"));
+    const scan = await prepareScan(scope);
+    return new RadixSortPlannerImpl(scope, hist, scatter, scan);
+}
+/**
+ * One binding-size check of record().
+ * @param argument - the argument name
+ * @param binding - the binding
+ * @param bytes - the bytes it must hold
+ */
+function checkBinding(argument, binding, bytes) {
+    if (binding.size < bytes) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `radixSort: ${argument} is smaller than ${bytes} bytes`, {
+            argument,
+            value: binding.size,
+            expected: bytes,
+        });
+    }
+}
+/**
+ * The argument checks of record() (E_INVALID_ARGUMENT before anything is recorded).
+ * @param keys - the keys
+ * @param vals - the values
+ * @param count - the pair count
+ * @param bits - the key width
+ * @param scratch - the scratch
+ * @param wg - the workgroup size
+ */
+function checkRecordArguments(keys, vals, count, bits, scratch, wg) {
+    if (bits !== 8 && bits !== 16 && bits !== 24 && bits !== 32) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "radixSort: bits must be 8, 16, 24 or 32", {
+            argument: "bits",
+            value: bits,
+            expected: [8, 16, 24, 32],
+        });
+    }
+    if (!Number.isSafeInteger(count) || count < 0 || count > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "radixSort: count must be a non-negative integer below 2^32", {
+            argument: "count",
+            value: count,
+        });
+    }
+    const pairBytes = 4 * count;
+    checkBinding("keys", keys, pairBytes);
+    checkBinding("vals", vals, pairBytes);
+    checkBinding("scratch.keys", scratch.keys, pairBytes);
+    checkBinding("scratch.vals", scratch.vals, pairBytes);
+    const tableBytes = radixHistBytes(count, wg);
+    checkBinding("scratch.hist", scratch.hist, tableBytes);
+    checkBinding("scratch.offsets", scratch.offsets, tableBytes);
+}
+/** The planner: the two resolved kernels and the scan over one scope. */
+class RadixSortPlannerImpl {
+    /**
+     * Wraps the resolved kernels; use prepareRadixSort().
+     * @param scope - the caller's scope
+     * @param hist - the `radix-hist` kernel
+     * @param scatter - the `radix-scatter` kernel
+     * @param scan - the scan planner of the same scope
+     */
+    constructor(scope, hist, scatter, scan) {
+        this.dispatches = 0;
+        this.scope = scope;
+        this.hist = hist;
+        this.scatter = scatter;
+        this.scan = scan;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Records the passes into the pass (see the interface).
+     * @param pass - the compute pass
+     * @param keys - the keys
+     * @param vals - the values
+     * @param count - the pair count
+     * @param bits - the key width
+     * @param scratch - the second pair, the histogram table and its scanned twin
+     * @returns the pair the result lives in
+     */
+    record(pass, keys, vals, count, bits, scratch) {
+        const wg = this.scope.workgroupSize;
+        checkRecordArguments(keys, vals, count, bits, scratch, wg);
+        if (count === 0) {
+            this.dispatches = 0;
+            return { keys, vals };
+        }
+        const groups = Math.ceil(count / wg);
+        const plan = plan1d(count, wg, this.scope.caps);
+        const tableWords = RADIX_BINS * groups;
+        const tableBytes = 4 * tableWords;
+        const histTable = { ...scratch.hist, size: tableBytes };
+        const offsets = { ...scratch.offsets, size: tableBytes };
+        let src = { keys, vals };
+        let dst = { keys: scratch.keys, vals: scratch.vals };
+        let dispatches = 0;
+        const passes = bits / RADIX_DIGIT_BITS;
+        for (let p = 0; p < passes; p++) {
+            const params = this.scope.params(RADIX_PARAMS, { count, shift: RADIX_DIGIT_BITS * p, groups, pad0: 0 });
+            const histBound = this.hist.bind({ keys: src.keys, hist: histTable, P: params.binding });
+            this.hist.dispatch(pass, histBound, plan, [params.offset]);
+            this.scan.record(pass, histTable, tableWords, offsets);
+            const scatterBound = this.scatter.bind({
+                keys: src.keys,
+                vals: src.vals,
+                offsets,
+                keysOut: dst.keys,
+                valsOut: dst.vals,
+                P: params.binding,
+            });
+            this.scatter.dispatch(pass, scatterBound, plan, [params.offset]);
+            dispatches += 2 + this.scan.lastDispatches;
+            [src, dst] = [dst, src];
+        }
+        this.dispatches = dispatches;
+        return src;
+    }
+}
+//# sourceMappingURL=radix-sort.js.map

package/dist/src/primitives/radix-sort.js.map

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

package/dist/src/primitives/scan.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The `exclusiveScan` primitive driver (spec 6 row 2; P4-T2, PD-3): a reduce-then-scan over u32 words. Level 0 runs
+ * `scan-block` over `count` items into `out` (each workgroup an exclusive Hillis-Steele scan of its WG-wide block) and
+ * writes one block sum per workgroup; while a level has more than one block, the next level scans its block sums
+ * (exclusive, into `offsets_L`) and writes its own block sums, recursively; the top level has ONE block, so its one
+ * sums word is the total. Then, top down, `scan-add` adds `offsets_L[g]` to every element of block `g` of level L's
+ * output. u32 addition is exact in any order, so two runs on any two adapters are bitwise identical; there is no
+ * subgroup variant (DEP-P4-E) and no decoupled look-back.
+ *
+ * The driver owns no device objects beyond a one-word zero it keeps for the empty scan: the caller supplies a
+ * ReduceScope (the same record `reduce` takes) and the compute pass to record into. `src/primitives/**` never imports
+ * `src/context.ts`.
+ */
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+/** Where the scan's total landed: one u32 word at `index` of `binding` (a word of the planner's scratch, valid until the next record()). */
+export interface ScanTotal {
+    readonly binding: Binding;
+    readonly index: number;
+}
+/** A prepared exclusive scan (spec 6 row 2): records the level dispatches of one scan into a pass. */
+export interface ScanPlanner {
+    /**
+     * Records the scan of `count` u32 of `src` into `out` (exclusive); returns where the total landed (a word of the
+     * planner's scratch, valid until the next record()); nothing for count 0 (the total word is then 0).
+     * @param pass - the compute pass
+     * @param src - the input words (at least 4 x count bytes)
+     * @param count - the word count (a non-negative integer below 2^32)
+     * @param out - the output words (at least 4 x count bytes)
+     * @returns the total's location
+     */
+    record(pass: GPUComputePassEncoder, src: Binding, count: number, out: Binding): ScanTotal;
+    /** Dispatches the last record() issued: 0 for count 0, else `2 x levels - 1` (one block scan per level, one add-back per level below the top). */
+    readonly lastDispatches: number;
+}
+/**
+ * Prepares the two scan pipelines of a scope (compiles once) so record() is synchronous. The zero word the empty
+ * scan's total points at is a scratch of `scope`, so the planner lives exactly as long as the scope: never use a
+ * planner after its scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export declare function prepareScan(scope: ReduceScope): Promise<ScanPlanner>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/src/primitives/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/primitives/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4IAA4I;AAC5I,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,sGAAsG;AACtG,MAAM,WAAW,WAAW;IACxB;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1F,kJAAkJ;IAClJ,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAKD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAM1E"}

package/dist/src/primitives/scan.js

@@ -0,0 +1,151 @@
+/**
+ * The `exclusiveScan` primitive driver (spec 6 row 2; P4-T2, PD-3): a reduce-then-scan over u32 words. Level 0 runs
+ * `scan-block` over `count` items into `out` (each workgroup an exclusive Hillis-Steele scan of its WG-wide block) and
+ * writes one block sum per workgroup; while a level has more than one block, the next level scans its block sums
+ * (exclusive, into `offsets_L`) and writes its own block sums, recursively; the top level has ONE block, so its one
+ * sums word is the total. Then, top down, `scan-add` adds `offsets_L[g]` to every element of block `g` of level L's
+ * output. u32 addition is exact in any order, so two runs on any two adapters are bitwise identical; there is no
+ * subgroup variant (DEP-P4-E) and no decoupled look-back.
+ *
+ * The driver owns no device objects beyond a one-word zero it keeps for the empty scan: the caller supplies a
+ * ReduceScope (the same record `reduce` takes) and the compute pass to record into. `src/primitives/**` never imports
+ * `src/context.ts`.
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { groupsOf, plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, SCAN_PARAMS } from "../kernels.js";
+/** The largest u32: the largest count `ScanParams.count` can carry. */
+const U32_MAX = 0xffffffff;
+/**
+ * Prepares the two scan pipelines of a scope (compiles once) so record() is synchronous. The zero word the empty
+ * scan's total points at is a scratch of `scope`, so the planner lives exactly as long as the scope: never use a
+ * planner after its scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export async function prepareScan(scope) {
+    const block = await scope.pipelines.kernel(kernelSpec("scan-block"));
+    const add = await scope.pipelines.kernel(kernelSpec("scan-add"));
+    const zero = scope.scratch(4, "scan/zero");
+    scope.device.queue.writeBuffer(zero, 0, new Uint32Array(1));
+    return new ScanPlannerImpl(scope, block, add, { buffer: zero, offset: 0, size: 4, window: null });
+}
+/**
+ * The argument checks of record() (E_INVALID_ARGUMENT before anything is recorded).
+ * @param src - the input binding
+ * @param count - the word count
+ * @param out - the output binding
+ */
+function checkRecordArguments(src, count, out) {
+    if (!Number.isSafeInteger(count) || count < 0 || count > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "scan: count must be a non-negative integer below 2^32", {
+            argument: "count",
+            value: count,
+        });
+    }
+    if (src.size < 4 * count) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "scan: src is smaller than 4 x count bytes", {
+            argument: "src",
+            value: src.size,
+            expected: 4 * count,
+        });
+    }
+    if (out.size < 4 * count) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "scan: out is smaller than 4 x count bytes", {
+            argument: "out",
+            value: out.size,
+            expected: 4 * count,
+        });
+    }
+}
+/** The planner: the two resolved kernels over one scope. */
+class ScanPlannerImpl {
+    /**
+     * Wraps the resolved kernels; use prepareScan().
+     * @param scope - the caller's scope
+     * @param block - the `scan-block` kernel
+     * @param add - the `scan-add` kernel
+     * @param zero - a one-word binding holding 0 (the total of the empty scan)
+     */
+    constructor(scope, block, add, zero) {
+        this.dispatches = 0;
+        this.scope = scope;
+        this.block = block;
+        this.add = add;
+        this.zero = zero;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Records the levels into the pass (see the interface).
+     * @param pass - the compute pass
+     * @param src - the input words
+     * @param count - the word count
+     * @param out - the output words
+     * @returns the total's location
+     */
+    record(pass, src, count, out) {
+        checkRecordArguments(src, count, out);
+        if (count === 0) {
+            this.dispatches = 0;
+            return { binding: this.zero, index: 0 };
+        }
+        const wg = this.scope.workgroupSize;
+        const levels = [];
+        let input = src;
+        let output = out;
+        let levelCount = count;
+        for (;;) {
+            const blocks = Math.ceil(levelCount / wg);
+            // Sized by the PADDED workgroup count (reduce's shape, reduce.ts partials-1): above MAX_1D_ITEMS plan1d pads
+            // the grid to x * y >= blocks, and every padded workgroup still stores its (zero) block sum at its own index.
+            // The next level scans only `blocks` words, so the padded tail is written and never read.
+            const plan = plan1d(levelCount, wg, this.scope.caps);
+            const groups = groupsOf(plan);
+            const sums = this.scratch(groups, `scan/sums${levels.length}`);
+            levels.push({ input, output, count: levelCount, plan, sums });
+            if (blocks === 1) {
+                break;
+            }
+            input = sums;
+            output = this.scratch(groups, `scan/offsets${levels.length}`);
+            levelCount = blocks;
+        }
+        for (const level of levels) {
+            const params = this.scope.params(SCAN_PARAMS, { count: level.count, pad0: 0, pad1: 0, pad2: 0 });
+            const bound = this.block.bind({
+                src: level.input,
+                out: level.output,
+                blockSums: level.sums,
+                P: params.binding,
+            });
+            this.block.dispatch(pass, bound, level.plan, [params.offset]);
+        }
+        for (let l = levels.length - 2; l >= 0; l--) {
+            const level = levels[l];
+            const params = this.scope.params(SCAN_PARAMS, { count: level.count, pad0: 0, pad1: 0, pad2: 0 });
+            const bound = this.add.bind({ out: level.output, blockOffsets: levels[l + 1].output, P: params.binding });
+            this.add.dispatch(pass, bound, level.plan, [params.offset]);
+        }
+        this.dispatches = 2 * levels.length - 1;
+        const top = levels[levels.length - 1];
+        return { binding: top.sums, index: 0 };
+    }
+    /**
+     * A scratch of `words` u32 from the scope, bound whole (never zero-length; the pool rounds the buffer up).
+     * @param words - the word count (>= 1)
+     * @param label - the scratch label
+     * @returns the binding
+     */
+    scratch(words, label) {
+        const size = 4 * words;
+        const buffer = this.scope.scratch(size, label);
+        return { buffer, offset: 0, size, window: null };
+    }
+}
+//# sourceMappingURL=scan.js.map