@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/dist/src/primitives/grid-pyramid.js

@@ -0,0 +1,143 @@
+/**
+ * The grid pyramid (spec 6 row 12, 7.7 G4-G5; P4-T9): the planner that records, into the caller's pass, the finest
+ * centroids (G4, `grid-centroid`: thread per cell over `cells + 1`, the pseudo-cell included), the hub-cell
+ * completion (G4a: the T1 `indirect-finalize` over `hubCounters[0]` into `hubArgs` with `wg = 1`, so the finalize's
+ * `ceil(count / wg)` is ONE workgroup per hub cell; G4b: `grid-centroid-hub`, one workgroup per hub cell, dispatched
+ * indirectly; PD-13, DEP-P4-I) and one `grid-downsample` dispatch per coarser
+ * level (G5). Level 0 holds `[sum m x, sum m y, sum m z, sum m]` per cell; every parent is the sum of its 2^dim
+ * children; the pseudo-cell (index `cells` of level 0) is never a child. No atomics touch the sums (design 6 row 12:
+ * bitwise reproducible); the only atomics are the hub append and the occupancy max.
+ *
+ * The named grid buffers (`pyramid`, `hubList`, `hubCounters`, `hubArgs`) are the caller's (the model's
+ * `BufferSpec`s, so `inspect(name)` reaches them); the static params of the finalize and of every level are written
+ * ONCE at bind() through the scope's params writer (PD-11), so record() writes no uniform. `src/primitives/**` never
+ * imports `src/context.ts`.
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { GRID_LEVEL_PARAMS, INDIRECT_PARAMS, kernelSpec } from "../kernels.js";
+/**
+ * Prepares the pyramid's pipelines over a scope (G4, the finalize, G4b and G5; compiles once) so bind() and record()
+ * are synchronous. The planner lives exactly as long as the scope.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @param spec - the grid
+ * @returns the planner
+ */
+export async function preparePyramid(scope, spec) {
+    const centroid = await scope.pipelines.kernel(kernelSpec("grid-centroid"));
+    const finalize = await scope.pipelines.kernel(kernelSpec("indirect-finalize"));
+    const hub = await scope.pipelines.kernel(kernelSpec("grid-centroid-hub"));
+    const downsample = await scope.pipelines.kernel(kernelSpec("grid-downsample"));
+    return new GridPyramidPlannerImpl(scope, spec, { centroid, finalize, hub, downsample });
+}
+/** The planner: G4, G4a, G4b and G5 over one scope. */
+class GridPyramidPlannerImpl {
+    /**
+     * Wraps the resolved kernels; use preparePyramid().
+     * @param scope - the caller's scope
+     * @param spec - the grid
+     * @param kernels - the four kernels
+     */
+    constructor(scope, spec, kernels) {
+        this.bound = null;
+        this.dispatches = 0;
+        this.scope = scope;
+        this.spec = spec;
+        this.kernels = kernels;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Binds the buffers and writes the static params (see the interface).
+     * @param bindings - the buffers
+     */
+    bind(bindings) {
+        const { centroid, finalize, hub, downsample } = this.kernels;
+        const { spec, scope } = this;
+        const b = bindings;
+        const finalizeParams = scope.params(INDIRECT_PARAMS, {
+            countIndex: 0,
+            wg: 1, // the finalize plans ceil(count / wg) workgroups over ITEMS; G4b's item is a hub cell, one workgroup each
+            slot: 0,
+            pad0: 0,
+        });
+        const levels = [];
+        let parentSide = spec.g;
+        for (let level = 0; level + 1 < spec.levels; level++) {
+            parentSide /= 2;
+            const parentCells = parentSide ** spec.dim;
+            const params = scope.params(GRID_LEVEL_PARAMS, {
+                childBase: spec.levelOffsets[level],
+                parentBase: spec.levelOffsets[level + 1],
+                parentSide,
+                parentCells,
+                depth: spec.dim === 3 ? 2 : 1,
+                pad0: 0,
+                pad1: 0,
+                pad2: 0,
+            });
+            levels.push({
+                bound: downsample.bind({ pyramid: b.pyramid, P: params.binding }),
+                offset: params.offset,
+                parentCells,
+            });
+        }
+        this.bound = {
+            hubArgs: b.hubArgs,
+            centroid: centroid.bind({
+                sortedIdx: b.sortedIdx,
+                cellStart: b.cellStart,
+                pos: b.pos,
+                pyramid: b.pyramid,
+                hubList: b.hubList,
+                hubCounters: b.hubCounters,
+                P: b.params,
+            }),
+            finalize: finalize.bind({ counters: b.hubCounters, args: b.hubArgs, P: finalizeParams.binding }),
+            finalizeOffset: finalizeParams.offset,
+            hub: hub.bind({
+                sortedIdx: b.sortedIdx,
+                cellStart: b.cellStart,
+                pos: b.pos,
+                pyramid: b.pyramid,
+                hubList: b.hubList,
+                hubCount: b.hubCounters,
+                P: b.params,
+            }),
+            levels,
+        };
+    }
+    /**
+     * Records the stages (see the interface).
+     * @param pass - the compute pass
+     * @param paramsOffset - the `Fa2Params` dynamic offset
+     * @param upTo - the last stage
+     */
+    record(pass, paramsOffset, upTo) {
+        const { bound, scope, spec } = this;
+        if (bound === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "gridPyramid: record() before bind()", { argument: "bind" });
+        }
+        const { centroid, finalize, hub, downsample } = this.kernels;
+        const one = { x: 1, y: 1, z: 1, items: 1, stride: null };
+        centroid.dispatch(pass, bound.centroid, plan1d(spec.cells + 1, scope.workgroupSize, scope.caps), [paramsOffset]);
+        finalize.dispatch(pass, bound.finalize, one, [bound.finalizeOffset]);
+        hub.dispatchIndirect(pass, bound.hub, bound.hubArgs, 0, [paramsOffset]);
+        this.dispatches = 3;
+        if ((upTo ?? "G5") === "G4") {
+            return;
+        }
+        for (const level of bound.levels) {
+            downsample.dispatch(pass, level.bound, plan1d(level.parentCells, scope.workgroupSize, scope.caps), [
+                level.offset,
+            ]);
+            this.dispatches += 1;
+        }
+    }
+}
+//# sourceMappingURL=grid-pyramid.js.map

package/dist/src/primitives/grid-pyramid.js.map

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

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

@@ -0,0 +1,118 @@
+/**
+ * The grid build (spec 6 row 12, 7.7 G1-G3; P4-T8): `GridSpec` on the host (PD-9) and the planner that records, into
+ * the caller's pass, the cell keys (G1, `grid-cell-key`), the stable sort by key (G2: `radixSort` at GRID_SORT_BITS,
+ * or `countingSortByKey` when the caller asks for the set-deterministic path) and the per-cell histogram with its
+ * exclusive scan (G3: the `histogram` kernel over `cellKey` and the `scan` of it; DEP-P4-I names no grid-specific
+ * id). `cellHist` and `cellStart` hold `cells + 2` words: every real cell, the outside pseudo-cell at index `cells`
+ * and one more so `cellStart[cells + 1] === n` closes the last range. Every zeroing is a `fill` dispatch inside the
+ * pass (PD-12), never an encoder clear.
+ *
+ * The named grid buffers (`cellKey`, `cellVal`, `sortedKey`, `sortedIdx`, `cellHist`, `cellStart`) are the caller's
+ * (the model's `BufferSpec`s, so `inspect(name)` reaches them); the anonymous scratch of the sort (the digit-major
+ * table and its scan, the counting-sort cursor) is taken from the scope ONCE at bind() so the sub-kernels bind the
+ * same buffers every iteration and `Kernel.bind`'s identity cache holds (PD-11). `src/primitives/**` never imports
+ * `src/context.ts`.
+ */
+import { type ResolvedLayoutTuning } from "../types/layout.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+/** The grid's geometry (spec 7.7 geometry table; PD-9), computed on the host once per load. */
+export interface GridSpec {
+    /** 2 or 3. */
+    readonly dim: 2 | 3;
+    /** The finest side `G` per axis: a power of two in [GRID_MIN_SIDE, floorPow2(gridMax)]. */
+    readonly g: number;
+    /** `log2(G / GRID_COARSEST_SIDE) + 1`. */
+    readonly levels: number;
+    /** `G^dim` finest cells; the outside pseudo-cell is index `cells`. */
+    readonly cells: number;
+    /** `cells + 2`: the length of `cellHist` / `cellStart`. */
+    readonly histWords: number;
+    /** The first cell of every level inside the pyramid: `levelOffsets[0] = 0`, level 0 holds `cells + 1` (the pseudo-cell), level L `(G / 2^L)^dim`. */
+    readonly levelOffsets: readonly number[];
+    /** Every level's cells together: `levelOffsets[levels - 1] + GRID_COARSEST_SIDE^dim`. */
+    readonly pyramidCells: number;
+    /** Whether G2 is the stable radix sort (true) or the set-deterministic counting sort (false). */
+    readonly deterministic: boolean;
+}
+/**
+ * The grid of `n` nodes in `dim` dimensions under the tuning (spec 7.7 geometry table; PD-9): `G = clamp(nextPow2(2 *
+ * ceil(n^(1 / dim))), GRID_MIN_SIDE, floorPow2(gridMax))` where `gridMax` is `gridMax2D` or `gridMax3D`, rounded DOWN
+ * to a power of two so every level's side is an integer (512 and 128 stay; 100 becomes 64); `levels = log2(G /
+ * GRID_COARSEST_SIDE) + 1`. At the caps: 349,521 pyramid cells in 2D, 2,396,737 in 3D (the design's counts plus the
+ * pseudo-cell).
+ * @param n - the node count (>= 0)
+ * @param dim - 2 or 3
+ * @param tuning - the resolved layout tuning (`gridMax2D`, `gridMax3D`, `deterministic`)
+ * @returns the spec
+ */
+export declare function gridSpecFor(n: number, dim: 2 | 3, tuning: Pick<ResolvedLayoutTuning, "gridMax2D" | "gridMax3D" | "deterministic">): GridSpec;
+/**
+ * The bytes of the pyramid (spec 7.7: 16 B per cell, every level, the pseudo-cell included): 38,347,792 at the 3D cap.
+ * @param spec - the grid
+ * @returns the byte length
+ */
+export declare function gridPyramidBytes(spec: GridSpec): number;
+/**
+ * The buffers the build reads and writes (the model's named buffers; `state` and `params` are the blocks G1 reads).
+ * The parameter type of GridBuildPlanner.bind (knip: exported for the signature, not imported by name).
+ * @public
+ */
+export interface GridBuildBindings {
+    /** `array<vec4f>` positions (xyz, mass). */
+    readonly pos: Binding;
+    /** The `Fa2State` block (`gridMin`, `invCellSize`), read-only here. */
+    readonly state: Binding;
+    /** The `Fa2Params` uniform ring (`n`, `dim`, `gridMax`); `record()` takes the iteration's dynamic offset. */
+    readonly params: Binding;
+    /**
+     * `n` words: G1's keys, node-indexed until G2. On the deterministic path the radix sort ping-pongs through this
+     * pair (PD-5: three passes, the even one writes the input pair), so after G2 `cellKey` / `cellVal` hold the
+     * sort's last even-pass intermediate -- a permutation of the keys, which is why the histogram recorded after it
+     * counts the same multiset; the node-indexed keys of an iteration are read through `upTo: "G1"`. The counting
+     * path never writes them.
+     */
+    readonly cellKey: Binding;
+    /** `n` words: G1's values (`i`); the sort's working pair with `cellKey`. */
+    readonly cellVal: Binding;
+    /** `n` words: the sorted keys (the radix path's result pair; unused by the counting path). */
+    readonly sortedKey: Binding;
+    /** `n` words: the sorted node indices. */
+    readonly sortedIdx: Binding;
+    /** `cells + 2` words: the per-cell counts. */
+    readonly cellHist: Binding;
+    /** `cells + 2` words: the exclusive scan of `cellHist`. */
+    readonly cellStart: Binding;
+}
+/** Where `record()` stops: after the keys (G1), after the sort (G2) or after the histogram and its scan (G3, the default). */
+export type GridBuildStage = "G1" | "G2" | "G3";
+/** A prepared grid build (spec 7.7 G1-G3): binds once per load, records the stages of one iteration into a pass. */
+export interface GridBuildPlanner {
+    /**
+     * Binds the named buffers and takes the sort's scratch from the scope, sized by `cellKey` (its word count is the
+     * node capacity; PD-11); called once per load (a second call rebinds and takes fresh scratch, so it belongs to a
+     * reload, never to an iteration).
+     * @param bindings - the buffers
+     */
+    bind(bindings: GridBuildBindings): void;
+    /**
+     * Records G1, G2 and G3 for `n` nodes at the `Fa2Params` slot `paramsOffset`; `upTo` stops after the named
+     * stage (the counting path has no separate G2 stop: its sort and histogram are one sequence, so "G2" runs it all).
+     * @param pass - the compute pass
+     * @param n - the node count (in [1, the capacity]; the caller never records a grid iteration for an empty graph)
+     * @param paramsOffset - the dynamic offset of this iteration's `Fa2Params`
+     * @param upTo - the last stage to record (default "G3")
+     */
+    record(pass: GPUComputePassEncoder, n: number, paramsOffset: number, upTo?: GridBuildStage): void;
+    /** Dispatches the last record() issued. */
+    readonly lastDispatches: number;
+}
+/**
+ * Prepares the grid build's pipelines over a scope (G1 and the sort / histogram / scan planners it composes; compiles
+ * once) so bind() and record() are synchronous. The planner lives exactly as long as the scope.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @param spec - the grid
+ * @returns the planner
+ */
+export declare function prepareGridBuild(scope: ReduceScope, spec: GridSpec): Promise<GridBuildPlanner>;
+//# sourceMappingURL=grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../../src/primitives/grid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAQlD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACrB,cAAc;IACd,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACpB,2FAA2F;IAC3F,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qJAAqJ;IACrJ,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACnC;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACvB,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,CAAC,GAAG,CAAC,EACV,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC,GAChF,QAAQ,CA0BV;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAED,8HAA8H;AAC9H,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,oHAAoH;AACpH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACxC;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAClG,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAYD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAWpG"}

package/dist/src/primitives/grid.js

@@ -0,0 +1,225 @@
+/**
+ * The grid build (spec 6 row 12, 7.7 G1-G3; P4-T8): `GridSpec` on the host (PD-9) and the planner that records, into
+ * the caller's pass, the cell keys (G1, `grid-cell-key`), the stable sort by key (G2: `radixSort` at GRID_SORT_BITS,
+ * or `countingSortByKey` when the caller asks for the set-deterministic path) and the per-cell histogram with its
+ * exclusive scan (G3: the `histogram` kernel over `cellKey` and the `scan` of it; DEP-P4-I names no grid-specific
+ * id). `cellHist` and `cellStart` hold `cells + 2` words: every real cell, the outside pseudo-cell at index `cells`
+ * and one more so `cellStart[cells + 1] === n` closes the last range. Every zeroing is a `fill` dispatch inside the
+ * pass (PD-12), never an encoder clear.
+ *
+ * The named grid buffers (`cellKey`, `cellVal`, `sortedKey`, `sortedIdx`, `cellHist`, `cellStart`) are the caller's
+ * (the model's `BufferSpec`s, so `inspect(name)` reaches them); the anonymous scratch of the sort (the digit-major
+ * table and its scan, the counting-sort cursor) is taken from the scope ONCE at bind() so the sub-kernels bind the
+ * same buffers every iteration and `Kernel.bind`'s identity cache holds (PD-11). `src/primitives/**` never imports
+ * `src/context.ts`.
+ */
+import { GRID_COARSEST_SIDE, GRID_MIN_SIDE, GRID_SORT_BITS } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { kernelSpec } from "../kernels.js";
+import { prepareCountingSort, prepareHistogram, } from "./histogram.js";
+import { prepareRadixSort, radixHistBytes } from "./radix-sort.js";
+import { prepareScan } from "./scan.js";
+/**
+ * The smallest power of two >= x (by doubling; 1 for x <= 1).
+ * @param x - a non-negative number
+ * @returns the power of two
+ */
+function nextPow2(x) {
+    let p = 1;
+    while (p < x) {
+        p *= 2;
+    }
+    return p;
+}
+/**
+ * The largest power of two <= x (by doubling; 1 for x < 2).
+ * @param x - a number >= 1
+ * @returns the power of two
+ */
+function floorPow2(x) {
+    let p = 1;
+    while (p * 2 <= x) {
+        p *= 2;
+    }
+    return p;
+}
+/**
+ * The grid of `n` nodes in `dim` dimensions under the tuning (spec 7.7 geometry table; PD-9): `G = clamp(nextPow2(2 *
+ * ceil(n^(1 / dim))), GRID_MIN_SIDE, floorPow2(gridMax))` where `gridMax` is `gridMax2D` or `gridMax3D`, rounded DOWN
+ * to a power of two so every level's side is an integer (512 and 128 stay; 100 becomes 64); `levels = log2(G /
+ * GRID_COARSEST_SIDE) + 1`. At the caps: 349,521 pyramid cells in 2D, 2,396,737 in 3D (the design's counts plus the
+ * pseudo-cell).
+ * @param n - the node count (>= 0)
+ * @param dim - 2 or 3
+ * @param tuning - the resolved layout tuning (`gridMax2D`, `gridMax3D`, `deterministic`)
+ * @returns the spec
+ */
+export function gridSpecFor(n, dim, tuning) {
+    const gridMax = dim === 3 ? tuning.gridMax3D : tuning.gridMax2D;
+    const side = dim === 3 ? Math.cbrt(n) : Math.sqrt(n);
+    const cap = Math.max(GRID_MIN_SIDE, floorPow2(Math.max(1, gridMax)));
+    const g = Math.min(cap, Math.max(GRID_MIN_SIDE, nextPow2(2 * Math.ceil(side))));
+    let levels = 1;
+    for (let s = g; s > GRID_COARSEST_SIDE; s /= 2) {
+        levels++;
+    }
+    const cells = g ** dim;
+    const levelOffsets = [0];
+    let s = g;
+    for (let level = 0; level + 1 < levels; level++) {
+        levelOffsets.push(levelOffsets[level] + s ** dim + (level === 0 ? 1 : 0));
+        s /= 2;
+    }
+    return {
+        dim,
+        g,
+        levels,
+        cells,
+        histWords: cells + 2,
+        levelOffsets: Object.freeze(levelOffsets),
+        pyramidCells: levelOffsets[levels - 1] + GRID_COARSEST_SIDE ** dim,
+        deterministic: tuning.deterministic,
+    };
+}
+/**
+ * The bytes of the pyramid (spec 7.7: 16 B per cell, every level, the pseudo-cell included): 38,347,792 at the 3D cap.
+ * @param spec - the grid
+ * @returns the byte length
+ */
+export function gridPyramidBytes(spec) {
+    return 16 * spec.pyramidCells;
+}
+/**
+ * Prepares the grid build's pipelines over a scope (G1 and the sort / histogram / scan planners it composes; compiles
+ * once) so bind() and record() are synchronous. The planner lives exactly as long as the scope.
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @param spec - the grid
+ * @returns the planner
+ */
+export async function prepareGridBuild(scope, spec) {
+    const cellKey = await scope.pipelines.kernel(kernelSpec("grid-cell-key"));
+    const path = spec.deterministic
+        ? {
+            kind: "radix",
+            radix: await prepareRadixSort(scope),
+            histogram: await prepareHistogram(scope),
+            scan: await prepareScan(scope),
+        }
+        : { kind: "counting", counting: await prepareCountingSort(scope) };
+    return new GridBuildPlannerImpl(scope, spec, cellKey, path);
+}
+/** The planner: G1 and the composed sort / histogram / scan over one scope. */
+class GridBuildPlannerImpl {
+    /**
+     * Wraps the resolved kernel and planners; use prepareGridBuild().
+     * @param scope - the caller's scope
+     * @param spec - the grid
+     * @param cellKey - the `grid-cell-key` kernel
+     * @param path - the sort path
+     */
+    constructor(scope, spec, cellKey, path) {
+        this.bound = null;
+        this.dispatches = 0;
+        this.scope = scope;
+        this.spec = spec;
+        this.cellKey = cellKey;
+        this.path = path;
+    }
+    /**
+     * Dispatches the last record() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Binds the buffers and takes the sort's scratch (see the interface).
+     * @param bindings - the buffers
+     */
+    bind(bindings) {
+        const capacity = Math.floor(bindings.cellKey.size / 4);
+        if (capacity < 1) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "gridBuild: cellKey must hold at least one word", {
+                argument: "cellKey",
+                value: bindings.cellKey.size,
+                expected: 4,
+            });
+        }
+        const words = this.path.kind === "radix" ? radixHistBytes(capacity, this.scope.workgroupSize) / 4 : this.spec.histWords;
+        this.bound = {
+            bindings,
+            capacity,
+            scratchA: this.scratch(words, "grid/sort-scratch-a"),
+            scratchB: this.scratch(words, "grid/sort-scratch-b"),
+        };
+    }
+    /**
+     * Records the stages (see the interface).
+     * @param pass - the compute pass
+     * @param n - the node count
+     * @param paramsOffset - the `Fa2Params` dynamic offset
+     * @param upTo - the last stage
+     */
+    record(pass, n, paramsOffset, upTo) {
+        const { bound } = this;
+        if (bound === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "gridBuild: record() before bind()", { argument: "bind" });
+        }
+        if (!Number.isSafeInteger(n) || n < 1 || n > bound.capacity) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "gridBuild: n must be an integer in [1, the capacity]", {
+                argument: "n",
+                value: n,
+                expected: bound.capacity,
+            });
+        }
+        const stop = upTo ?? "G3";
+        const b = bound.bindings;
+        const keyBound = this.cellKey.bind({
+            pos: b.pos,
+            S: b.state,
+            cellKey: b.cellKey,
+            cellVal: b.cellVal,
+            P: b.params,
+        });
+        this.cellKey.dispatch(pass, keyBound, plan1d(n, this.scope.workgroupSize, this.scope.caps), [paramsOffset]);
+        this.dispatches = 1;
+        if (stop === "G1") {
+            return;
+        }
+        const { histWords: bins } = this.spec;
+        if (this.path.kind === "counting") {
+            const { counting } = this.path;
+            const scratch = { hist: b.cellHist, cursor: bound.scratchA };
+            counting.record(pass, b.cellKey, n, bins, scratch, b.sortedIdx, b.cellStart);
+            this.dispatches += counting.lastDispatches;
+            return;
+        }
+        const { radix, histogram, scan } = this.path;
+        radix.record(pass, b.cellKey, b.cellVal, n, GRID_SORT_BITS, {
+            keys: b.sortedKey,
+            vals: b.sortedIdx,
+            hist: bound.scratchA,
+            offsets: bound.scratchB,
+        });
+        this.dispatches += radix.lastDispatches;
+        if (stop === "G2") {
+            return;
+        }
+        histogram.record(pass, b.cellKey, n, bins, b.cellHist);
+        scan.record(pass, b.cellHist, bins, b.cellStart);
+        this.dispatches += histogram.lastDispatches + scan.lastDispatches;
+    }
+    /**
+     * A scratch of `words` u32 from the scope, bound whole.
+     * @param words - the word count (>= 1)
+     * @param label - the scratch label
+     * @returns the binding
+     */
+    scratch(words, label) {
+        const size = 4 * Math.max(1, words);
+        const buffer = this.scope.scratch(size, label);
+        return { buffer, offset: 0, size, window: null };
+    }
+}
+//# sourceMappingURL=grid.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grid.js","sourceRoot":"","sources":["../../../src/primitives/grid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,EAGH,mBAAmB,EACnB,gBAAgB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAyB,MAAM,iBAAiB,CAAC;AAE1F,OAAO,EAAE,WAAW,EAAoB,MAAM,WAAW,CAAC;AAsB1D;;;;GAIG;AACH,SAAS,QAAQ,CAAC,CAAS;IACvB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACX,CAAC,IAAI,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,CAAS;IACxB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAChB,CAAC,IAAI,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACvB,CAAS,EACT,GAAU,EACV,MAA+E;IAE/E,MAAM,OAAO,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAChE,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,EAAE,CAAC;IACb,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;IACvB,MAAM,YAAY,GAAa,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9C,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,CAAC,IAAI,CAAC,CAAC;IACX,CAAC;IACD,OAAO;QACH,GAAG;QACH,CAAC;QACD,MAAM;QACN,KAAK;QACL,SAAS,EAAE,KAAK,GAAG,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;QACzC,YAAY,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,kBAAkB,IAAI,GAAG;QAClE,aAAa,EAAE,MAAM,CAAC,aAAa;KACtC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC3C,OAAO,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC;AAClC,CAAC;AAqED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAkB,EAAE,IAAc;IACrE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAa,IAAI,CAAC,aAAa;QACrC,CAAC,CAAC;YACI,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,MAAM,gBAAgB,CAAC,KAAK,CAAC;YACpC,SAAS,EAAE,MAAM,gBAAgB,CAAC,KAAK,CAAC;YACxC,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC;SACjC;QACH,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;IACvE,OAAO,IAAI,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAChE,CAAC;AAUD,+EAA+E;AAC/E,MAAM,oBAAoB;IAQtB;;;;;;OAMG;IACH,YAAY,KAAkB,EAAE,IAAc,EAAE,OAAe,EAAE,IAAc;QAVvE,UAAK,GAAiB,IAAI,CAAC;QAC3B,eAAU,GAAG,CAAC,CAAC;QAUnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,QAA2B;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,gBAAgB,CAAC,oBAAoB,EAAE,gDAAgD,EAAE;gBAC/F,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI;gBAC5B,QAAQ,EAAE,CAAC;aACd,CAAC,CAAC;QACP,CAAC;QACD,MAAM,KAAK,GACP,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;QAC9G,IAAI,CAAC,KAAK,GAAG;YACT,QAAQ;YACR,QAAQ;YACR,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,qBAAqB,CAAC;YACpD,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,qBAAqB,CAAC;SACvD,CAAC;IACN,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAA2B,EAAE,CAAS,EAAE,YAAoB,EAAE,IAAqB;QACtF,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACvB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,gBAAgB,CAAC,cAAc,EAAE,mCAAmC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC1D,MAAM,IAAI,gBAAgB,CAAC,oBAAoB,EAAE,sDAAsD,EAAE;gBACrG,QAAQ,EAAE,GAAG;gBACb,KAAK,EAAE,CAAC;gBACR,QAAQ,EAAE,KAAK,CAAC,QAAQ;aAC3B,CAAC,CAAC;QACP,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,CAAC;QAC1B,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAC/B,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,CAAC,EAAE,CAAC,CAAC,KAAK;YACV,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,CAAC,EAAE,CAAC,CAAC,MAAM;SACd,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;QAC5G,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;YAC/B,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC7D,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;YAC7E,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC,cAAc,CAAC;YAC3C,OAAO;QACX,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;QAC7C,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE;YACxD,IAAI,EAAE,CAAC,CAAC,SAAS;YACjB,IAAI,EAAE,CAAC,CAAC,SAAS;YACjB,IAAI,EAAE,KAAK,CAAC,QAAQ;YACpB,OAAO,EAAE,KAAK,CAAC,QAAQ;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,cAAc,CAAC;QACxC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACK,OAAO,CAAC,KAAa,EAAE,KAAa;QACxC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC;CACJ"}

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

@@ -0,0 +1,67 @@
+/**
+ * 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 { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+/** A prepared histogram (spec 6 row 5): records the fill and the one counting dispatch into a pass. */
+export interface HistogramPlanner {
+    /**
+     * Records the histogram of `count` u32 keys of `keys` over `bins` bins into `hist` (zeroed first by a `fill`
+     * dispatch); a key >= bins is not counted. For count 0 only the fill is recorded, so `hist` is all zero.
+     * @param pass - the compute pass
+     * @param keys - the keys (at least 4 x count bytes)
+     * @param count - the key count (a non-negative integer below 2^32)
+     * @param bins - the bin count (an integer in [1, 2^32))
+     * @param hist - the counts (at least 4 x bins bytes)
+     */
+    record(pass: GPUComputePassEncoder, keys: Binding, count: number, bins: number, hist: Binding): void;
+    /** Dispatches the last record() issued: 1 (the fill) for count 0, else 2. */
+    readonly lastDispatches: number;
+}
+/** The two per-bin scratch arrays of a counting sort: the histogram and the scatter cursor, each at least 4 x bins bytes. */
+interface CountingSortScratch {
+    readonly hist: Binding;
+    readonly cursor: Binding;
+}
+/** A prepared counting sort by key (spec 6 row 5): records the histogram, the scan, the cursor fill and the scatter into a pass. */
+export interface CountingSortPlanner {
+    /**
+     * Records the counting sort of `count` keys of `keys` (every key < bins) into `outIndex` (the indices in key
+     * order; the order inside a bin follows the schedule) and `outStart` (the exclusive scan of the histogram, so bin
+     * k holds `outIndex[outStart[k] .. outStart[k + 1])` when outStart has bins + 1 words, as the grid's does).
+     * For count 0 the two fills and the scan run and `outStart` is all zero.
+     * @param pass - the compute pass
+     * @param keys - the keys (at least 4 x count bytes)
+     * @param count - the key count (a non-negative integer below 2^32)
+     * @param bins - the bin count (an integer in [1, 2^32))
+     * @param scratch - the per-bin histogram and cursor (each at least 4 x bins bytes)
+     * @param outIndex - the sorted indices (at least 4 x count bytes)
+     * @param outStart - the bin starts (at least 4 x bins bytes)
+     */
+    record(pass: GPUComputePassEncoder, keys: Binding, count: number, bins: number, scratch: CountingSortScratch, outIndex: Binding, outStart: Binding): void;
+    /** Dispatches the last record() issued: the histogram's + the scan's + 1 (the cursor fill) + 1 (the scatter, count > 0 only). */
+    readonly lastDispatches: number;
+}
+/**
+ * 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 declare function prepareHistogram(scope: ReduceScope): Promise<HistogramPlanner>;
+/**
+ * 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 declare function prepareCountingSort(scope: ReduceScope): Promise<CountingSortPlanner>;
+export {};
+//# sourceMappingURL=histogram.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../../src/primitives/histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrG,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED,6HAA6H;AAC7H,UAAU,mBAAmB;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC5B;AAED,oIAAoI;AACpI,MAAM,WAAW,mBAAmB;IAChC;;;;;;;;;;;;OAYG;IACH,MAAM,CACF,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,OAAO,GAClB,IAAI,CAAC;IACR,iIAAiI;IACjI,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAKD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEpF;AAaD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAK1F"}