@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.4

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

@@ -0,0 +1,62 @@
+/**
+ * The `advance` primitive of design 6 row 8 (P8-T5 / P8-T12; the P8 plan's PD-1, PD-23, DEP-P8-A, DEP-P8-E): the
+ * block-mapped expansion of a `Frontier`'s input queue into its edge queue by the `advance-expand` kernel, a DIRECT
+ * grid-stride dispatch over a grid planned for n entries that loops to `frontierCount` and runs only when the `path`
+ * word `frontier-finalize` role 0 wrote earlier in the same pass says the level is two-phase; the host never knows
+ * the frontier's size. The kernel leaves `edgeCount` (clamped later by role 1),
+ * `edgeCountUnclamped` (the overflow detector) and `frontierDegreeSum` in the counters block.
+ *
+ * Design 6 row 8 names three structures -- block-mapped, a WORKGROUP_PER_ROW tier for rows above 1,024 arcs, and a
+ * subgroup tier. Here they are: the block-mapped body is the large-frontier kernel and already balances a hub row
+ * over all `WG` lanes of its block (a 10,000-degree entry costs its block 40 strips, never one lane 10,000 reads);
+ * the workgroup-per-row structure IS `bfs-fused` (P8-T7), one workgroup per frontier entry, which the selector
+ * chooses for a small frontier such as a hub-only level, so `advance-expand` declares no `TIER` override and the tier
+ * choice is the fused / two-phase choice; and the subgroup tier is not a second body but the same body compiled
+ * against the prelude's subgroup helper block (`wg_scan_u32` becomes `subgroupExclusiveAdd` / `subgroupAdd` plus the
+ * elected-lane slot carry), which `needs: ["subgroups"]` in the registry entry switches on when the device has the
+ * feature. Both forms return each lane's prefix in LANE order, so the arcs land at the same queue positions; only
+ * the order ACROSS workgroups (the `atomicAdd` reservation order) is schedule-dependent, which is why a test compares
+ * sorted queues.
+ *
+ * A windowed core (spec 4.2: `colIdx` above `maxStorageBufferBindingSize`, bound as arc windows) is executed, not
+ * refused (P8-T12 lifts DEP-P8-E for the frontier family): one dispatch per window, the frontier and its count the
+ * same in every window, each dispatch binding that window's `colIdx` and
+ * carrying its owned arc range in `arcBase` / `arcEnd` (`coreWindows`: the ranges partition the arcs, which P4's
+ * overlapping window bounds do not). The body clips every row to the range, so a row straddling two windows emits
+ * each arc exactly once, and the per-window dispatches accumulate into the same edge queue through the same
+ * `edgeCount` reservation while `edgeCountUnclamped` and `frontierDegreeSum` add up across windows to the level's
+ * totals. `src/primitives/**` never imports `src/context.ts`.
+ */
+import { type Kernel } from "../kernel/kernel.js";
+import { type CoreBinding } from "../memory/residency.js";
+import { type CoreWindow } from "./core-shape.js";
+import { type Frontier, type FrontierScope } from "./frontier.js";
+/** A prepared advance (design 6 row 8): records one expansion of a frontier per level. */
+export interface AdvancePlanner {
+    /** The compiled `advance-expand` kernel (so `bfs-fused` can share its bind groups' shape). */
+    readonly kernel: Kernel;
+    /** The arc windows every level dispatches over: one over the whole core, or the windowed core's (P8-T12). */
+    readonly windows: readonly CoreWindow[];
+    /**
+     * Records the expansion of `frontier.input` into `frontier.edgeQueue` as a DIRECT grid-stride dispatch per window
+     * (`planGridStride(n)`: the frontier holds at most n entries; the kernel loops to the count word and runs only
+     * when the selector's path word says the level is two-phase): one `FrontierParams` record per window
+     * (`edgeCapacity`, `n`, `wg`, `stride` and the window's arc range) and the kernel bound to the window's graph
+     * arrays, the input queue, the counters block and the edge queue (`Kernel.bind` reuses the bind groups of the
+     * same buffers and ranges, so the two sides of a frontier cost two bind-group sets per window). A frontier
+     * whose `n` is not the core's row count is E_INVALID_ARGUMENT before anything is recorded.
+     * @param pass - the compute pass
+     * @param frontier - the queue to expand (its `input` side)
+     */
+    record(pass: GPUComputePassEncoder, frontier: Frontier): void;
+}
+/**
+ * Compiles `advance-expand` for the core's weights pattern (no permutation: the frontier names rows directly) so
+ * `record` is synchronous, and resolves the core's windows once. The planner lives exactly as long as the scope:
+ * never use it after the scope's dispose().
+ * @param scope - the caller's scope (pipelines, params)
+ * @param core - the resident core arrays of the snapshot the frontier walks (windowed or not)
+ * @returns the planner
+ */
+export declare function prepareAdvance(scope: FrontierScope, core: CoreBinding): Promise<AdvancePlanner>;
+//# sourceMappingURL=advance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"advance.d.ts","sourceRoot":"","sources":["../../../src/primitives/advance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAElE,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6GAA6G;IAC7G,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CACjE;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAGrG"}

package/dist/src/primitives/advance.js

@@ -0,0 +1,95 @@
+/**
+ * The `advance` primitive of design 6 row 8 (P8-T5 / P8-T12; the P8 plan's PD-1, PD-23, DEP-P8-A, DEP-P8-E): the
+ * block-mapped expansion of a `Frontier`'s input queue into its edge queue by the `advance-expand` kernel, a DIRECT
+ * grid-stride dispatch over a grid planned for n entries that loops to `frontierCount` and runs only when the `path`
+ * word `frontier-finalize` role 0 wrote earlier in the same pass says the level is two-phase; the host never knows
+ * the frontier's size. The kernel leaves `edgeCount` (clamped later by role 1),
+ * `edgeCountUnclamped` (the overflow detector) and `frontierDegreeSum` in the counters block.
+ *
+ * Design 6 row 8 names three structures -- block-mapped, a WORKGROUP_PER_ROW tier for rows above 1,024 arcs, and a
+ * subgroup tier. Here they are: the block-mapped body is the large-frontier kernel and already balances a hub row
+ * over all `WG` lanes of its block (a 10,000-degree entry costs its block 40 strips, never one lane 10,000 reads);
+ * the workgroup-per-row structure IS `bfs-fused` (P8-T7), one workgroup per frontier entry, which the selector
+ * chooses for a small frontier such as a hub-only level, so `advance-expand` declares no `TIER` override and the tier
+ * choice is the fused / two-phase choice; and the subgroup tier is not a second body but the same body compiled
+ * against the prelude's subgroup helper block (`wg_scan_u32` becomes `subgroupExclusiveAdd` / `subgroupAdd` plus the
+ * elected-lane slot carry), which `needs: ["subgroups"]` in the registry entry switches on when the device has the
+ * feature. Both forms return each lane's prefix in LANE order, so the arcs land at the same queue positions; only
+ * the order ACROSS workgroups (the `atomicAdd` reservation order) is schedule-dependent, which is why a test compares
+ * sorted queues.
+ *
+ * A windowed core (spec 4.2: `colIdx` above `maxStorageBufferBindingSize`, bound as arc windows) is executed, not
+ * refused (P8-T12 lifts DEP-P8-E for the frontier family): one dispatch per window, the frontier and its count the
+ * same in every window, each dispatch binding that window's `colIdx` and
+ * carrying its owned arc range in `arcBase` / `arcEnd` (`coreWindows`: the ranges partition the arcs, which P4's
+ * overlapping window bounds do not). The body clips every row to the range, so a row straddling two windows emits
+ * each arc exactly once, and the per-window dispatches accumulate into the same edge queue through the same
+ * `edgeCount` reservation while `edgeCountUnclamped` and `frontierDegreeSum` add up across windows to the level's
+ * totals. `src/primitives/**` never imports `src/context.ts`.
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { planGridStride } from "../kernel/dispatch.js";
+import { FRONTIER_PARAMS, graphBindings, graphOverrides, kernelSpec } from "../kernels.js";
+import { coreWindows, rowCountOf } from "./core-shape.js";
+/**
+ * Compiles `advance-expand` for the core's weights pattern (no permutation: the frontier names rows directly) so
+ * `record` is synchronous, and resolves the core's windows once. The planner lives exactly as long as the scope:
+ * never use it after the scope's dispose().
+ * @param scope - the caller's scope (pipelines, params)
+ * @param core - the resident core arrays of the snapshot the frontier walks (windowed or not)
+ * @returns the planner
+ */
+export async function prepareAdvance(scope, core) {
+    const kernel = await scope.pipelines.kernel(kernelSpec("advance-expand", graphOverrides(core, null)));
+    return new AdvancePlannerImpl(scope, core, kernel);
+}
+/** The planner: the compiled kernel over one core's windows. */
+class AdvancePlannerImpl {
+    /**
+     * Wraps the resolved kernel; use prepareAdvance().
+     * @param scope - the caller's scope
+     * @param core - the core the kernel was compiled for
+     * @param kernel - the `advance-expand` kernel
+     */
+    constructor(scope, core, kernel) {
+        this.scope = scope;
+        this.kernel = kernel;
+        this.windows = coreWindows(core);
+        this.n = rowCountOf(core, "advance");
+    }
+    /**
+     * Records one direct expansion per window (see the interface).
+     * @param pass - the compute pass
+     * @param frontier - the queue to expand
+     */
+    record(pass, frontier) {
+        if (frontier.n !== this.n) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `advance: the frontier holds ${frontier.n} vertices, the core ${this.n} rows`, {
+                argument: "frontier",
+                value: frontier.n,
+                expected: this.n,
+            });
+        }
+        const { scope } = this;
+        const plan = planGridStride(frontier.n, scope.workgroupSize, scope.caps); // the frontier holds at most n entries
+        for (const w of this.windows) {
+            const params = scope.params(FRONTIER_PARAMS, {
+                wg: scope.workgroupSize,
+                edgeCapacity: frontier.edgeCapacity,
+                n: frontier.n,
+                arcBase: w.arcBase,
+                arcEnd: w.arcEnd,
+                stride: plan.stride ?? scope.workgroupSize,
+            });
+            const bound = this.kernel.bind({
+                ...graphBindings(w.core, null),
+                frontierIn: frontier.input,
+                counters: frontier.counters,
+                edgeQueue: frontier.edgeQueue,
+                P: params.binding,
+            });
+            this.kernel.dispatch(pass, bound, plan, [params.offset]);
+        }
+    }
+}
+//# sourceMappingURL=advance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"advance.js","sourceRoot":"","sources":["../../../src/primitives/advance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,EAAmB,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAuB3E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAoB,EAAE,IAAiB;IACxE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,gBAAgB,EAAE,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACtG,OAAO,IAAI,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,gEAAgE;AAChE,MAAM,kBAAkB;IAMpB;;;;;OAKG;IACH,YAAY,KAAoB,EAAE,IAAiB,EAAE,MAAc;QAC/D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAA2B,EAAE,QAAkB;QAClD,IAAI,QAAQ,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,gBAAgB,CACtB,oBAAoB,EACpB,+BAA+B,QAAQ,CAAC,CAAC,uBAAuB,IAAI,CAAC,CAAC,OAAO,EAC7E;gBACI,QAAQ,EAAE,UAAU;gBACpB,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACjB,QAAQ,EAAE,IAAI,CAAC,CAAC;aACnB,CACJ,CAAC;QACN,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACvB,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,uCAAuC;QACjH,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE;gBACzC,EAAE,EAAE,KAAK,CAAC,aAAa;gBACvB,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACb,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,aAAa;aAC7C,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;gBAC3B,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC;gBAC9B,UAAU,EAAE,QAAQ,CAAC,KAAK;gBAC1B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS;gBAC7B,CAAC,EAAE,MAAM,CAAC,OAAO;aACpB,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7D,CAAC;IACL,CAAC;CACJ"}

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

@@ -0,0 +1,89 @@
+/**
+ * The `compact` and `dedupe` primitive driver (spec 6 row 4; P8-T3, the P8 plan's PD-1 / DEP-P8-A). `compact` is
+ * flag, scan, scatter: the flags are the caller's (one u32 per entry, written by the kernel that produced the queue),
+ * `exclusiveScan` turns them into offsets, and `compact-scatter` lands every flagged entry at its offset in queue
+ * order -- order-preserving, so bitwise reproducible -- and writes the total into one word of the caller's block.
+ * `dedupe` is Davidson's ownership trick in two dispatches: `dedupe-claim` stores every entry's index into
+ * `owner[vertex]`, `dedupe-filter` keeps the entries that still own their vertex. Two dispatches because a plain
+ * store read back in the same dispatch is a data race (WGSL 6.5.7); between dispatches the relaxed atomics make
+ * last-writer-wins well defined, so exactly one index per distinct vertex survives (set-deterministic: the SET is
+ * fixed, the order inside `out` follows the schedule).
+ *
+ * `owner` needs NO reset between calls, whatever it holds: a word is read only by an entry `i` whose vertex `v` a
+ * claim of the SAME call has just written, so a stale index or garbage at `owner[v]` is overwritten before any lane
+ * compares against it, and a word no current entry names is never read. The design's row implies a reset; the `fill`
+ * over `n` per round is the dispatch this saves.
+ *
+ * The count of `compact` is host-known. `dedupe`'s callers (the SSSP piles of P8-T9) only know their entry count on
+ * the device, so `countIndex` names a word of the counters block and the kernels read `min(counters[countIndex],
+ * count)` -- the device word clamped to the capacity `count` -- or `count` alone when `countIndex` is `U32_MAX`. The
+ * counters block is bound WHOLE and indexed, for the count word and for the output word alike, because
+ * `Kernel.bind` rejects a binding whose offset is not a multiple of 256 and a four-byte word never is.
+ *
+ * The driver owns 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";
+/** One compaction: `count` entries of `queue` whose `flags` word is non-zero go to `out` in order; the total goes to `outCount[outIndex]`. */
+export interface CompactRecord {
+    /** The entries (at least 4 x count bytes). */
+    readonly queue: Binding;
+    /** One u32 per entry, 0 or 1 (at least 4 x count bytes). */
+    readonly flags: Binding;
+    /** The entry count (a non-negative integer below 2^32; host-known). */
+    readonly count: number;
+    /** The compacted entries (at least 4 x count bytes; the words past the total are not written). */
+    readonly out: Binding;
+    /** The block whose word `outIndex` receives the total (bound whole). */
+    readonly outCount: Binding;
+    /** The word of `outCount` to write. */
+    readonly outIndex: number;
+}
+/** One dedupe: the entries of `queue` are filtered to one per distinct vertex into `out`; the surviving count is ADDED to `outCount[outIndex]`, which the caller zeroes before the pass. */
+export interface DedupeRecord {
+    /** The entries, vertex indices below the owner's length (at least 4 x count bytes). */
+    readonly queue: Binding;
+    /** The entry count when `countIndex` is `U32_MAX`, else the capacity the device count is clamped to (a non-negative integer below 2^32). */
+    readonly count: number;
+    /** `U32_MAX` for a host-known count; else the word of `counters` holding the entry count on the device. */
+    readonly countIndex: number;
+    /** The block the count word is read from; with a device count it must be the SAME range as `outCount` (both kernels read the word through their own binding), and it is bound but never read when `countIndex` is `U32_MAX`. */
+    readonly counters: Binding;
+    /** The ownership words, one per vertex (the caller's promise: at least 4 x n bytes; never reset). */
+    readonly owner: Binding;
+    /** The surviving entries (at least 4 x count bytes; the words past the count are not written). */
+    readonly out: Binding;
+    /** The block whose word `outIndex` accumulates the surviving count (bound whole; zeroed by the caller before the pass). */
+    readonly outCount: Binding;
+    /** The word of `outCount` to add to; never equal to `countIndex`. */
+    readonly outIndex: number;
+}
+/** A prepared compact / dedupe (spec 6 row 4): records the dispatches of one call into a pass. */
+export interface CompactPlanner {
+    /**
+     * Records the compaction (the flags' exclusive scan, then the scatter). For count 0 nothing is recorded and
+     * `outCount[outIndex]` keeps its prior value: a four-byte write at an unaligned offset is impossible, so every
+     * caller zeroes its block before the pass.
+     * @param pass - the compute pass
+     * @param record - the buffers and the count
+     */
+    record(pass: GPUComputePassEncoder, record: CompactRecord): void;
+    /**
+     * Records the claim and the filter over `plan1d(count)`; nothing for count 0 (`outCount[outIndex]` then keeps
+     * its prior value).
+     * @param pass - the compute pass
+     * @param record - the buffers, the count and the count word
+     */
+    recordDedupe(pass: GPUComputePassEncoder, record: DedupeRecord): void;
+    /** Dispatches the last record*() issued: compact 0 for count 0, else the scan's `2 x levels - 1` plus one (`2 x levels`); dedupe 0 for a direct count 0, else 2. */
+    readonly lastDispatches: number;
+}
+/**
+ * Prepares the three pipelines and the scan of a scope (compiles once) so record() is synchronous. The planner
+ * lives exactly as long as the scope (the scan keeps a scratch word of it): never use it after the scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export declare function prepareCompact(scope: ReduceScope): Promise<CompactPlanner>;
+//# sourceMappingURL=compact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/primitives/compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,8IAA8I;AAC9I,MAAM,WAAW,aAAa;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED,4LAA4L;AAC5L,MAAM,WAAW,YAAY;IACzB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4IAA4I;IAC5I,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2GAA2G;IAC3G,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gOAAgO;IAChO,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kGAAkG;IAClG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IACjE;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACtE,oKAAoK;IACpK,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAMhF"}

package/dist/src/primitives/compact.js

@@ -0,0 +1,233 @@
+/**
+ * The `compact` and `dedupe` primitive driver (spec 6 row 4; P8-T3, the P8 plan's PD-1 / DEP-P8-A). `compact` is
+ * flag, scan, scatter: the flags are the caller's (one u32 per entry, written by the kernel that produced the queue),
+ * `exclusiveScan` turns them into offsets, and `compact-scatter` lands every flagged entry at its offset in queue
+ * order -- order-preserving, so bitwise reproducible -- and writes the total into one word of the caller's block.
+ * `dedupe` is Davidson's ownership trick in two dispatches: `dedupe-claim` stores every entry's index into
+ * `owner[vertex]`, `dedupe-filter` keeps the entries that still own their vertex. Two dispatches because a plain
+ * store read back in the same dispatch is a data race (WGSL 6.5.7); between dispatches the relaxed atomics make
+ * last-writer-wins well defined, so exactly one index per distinct vertex survives (set-deterministic: the SET is
+ * fixed, the order inside `out` follows the schedule).
+ *
+ * `owner` needs NO reset between calls, whatever it holds: a word is read only by an entry `i` whose vertex `v` a
+ * claim of the SAME call has just written, so a stale index or garbage at `owner[v]` is overwritten before any lane
+ * compares against it, and a word no current entry names is never read. The design's row implies a reset; the `fill`
+ * over `n` per round is the dispatch this saves.
+ *
+ * The count of `compact` is host-known. `dedupe`'s callers (the SSSP piles of P8-T9) only know their entry count on
+ * the device, so `countIndex` names a word of the counters block and the kernels read `min(counters[countIndex],
+ * count)` -- the device word clamped to the capacity `count` -- or `count` alone when `countIndex` is `U32_MAX`. The
+ * counters block is bound WHOLE and indexed, for the count word and for the output word alike, because
+ * `Kernel.bind` rejects a binding whose offset is not a multiple of 256 and a four-byte word never is.
+ *
+ * The driver owns 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 { U32_MAX } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
+import { COMPACT_PARAMS, kernelSpec } from "../kernels.js";
+import { prepareScan } from "./scan.js";
+/**
+ * Prepares the three pipelines and the scan of a scope (compiles once) so record() is synchronous. The planner
+ * lives exactly as long as the scope (the scan keeps a scratch word of it): never use it after the scope's dispose().
+ * @param scope - the caller's scope (device, caps, cache, scratch, params)
+ * @returns the planner
+ */
+export async function prepareCompact(scope) {
+    const scatter = await scope.pipelines.kernel(kernelSpec("compact-scatter"));
+    const claim = await scope.pipelines.kernel(kernelSpec("dedupe-claim"));
+    const filter = await scope.pipelines.kernel(kernelSpec("dedupe-filter"));
+    const scan = await prepareScan(scope);
+    return new CompactPlannerImpl(scope, scatter, claim, filter, scan);
+}
+/**
+ * The E_INVALID_ARGUMENT of a bad count.
+ * @param what - the primitive's name for the message
+ * @param count - the count
+ */
+function checkCount(what, count) {
+    if (!Number.isSafeInteger(count) || count < 0 || count > U32_MAX) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${what}: count must be a non-negative integer below 2^32`, {
+            argument: "count",
+            value: count,
+        });
+    }
+}
+/**
+ * The E_INVALID_ARGUMENT of a binding shorter than `words` u32.
+ * @param what - the primitive's name for the message
+ * @param name - the argument name
+ * @param binding - the binding
+ * @param words - the words it must hold
+ */
+function checkWords(what, name, binding, words) {
+    if (binding.size < 4 * words) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${what}: ${name} is smaller than 4 x ${words} bytes`, {
+            argument: name,
+            value: binding.size,
+            expected: 4 * words,
+        });
+    }
+}
+/**
+ * The E_INVALID_ARGUMENT of a word index outside a block.
+ * @param what - the primitive's name for the message
+ * @param name - the argument name
+ * @param index - the word index
+ * @param block - the block it indexes
+ */
+function checkWordIndex(what, name, index, block) {
+    if (!Number.isSafeInteger(index) || index < 0 || 4 * (index + 1) > block.size) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${what}: ${name} ${index} is outside the block`, {
+            argument: name,
+            value: index,
+            expected: `0 <= ${name} < ${Math.floor(block.size / 4)}`,
+        });
+    }
+}
+/**
+ * The argument checks of record() (E_INVALID_ARGUMENT before anything is recorded).
+ * @param r - the record
+ */
+function checkCompactArguments(r) {
+    checkCount("compact", r.count);
+    checkWords("compact", "queue", r.queue, r.count);
+    checkWords("compact", "flags", r.flags, r.count);
+    checkWords("compact", "out", r.out, r.count);
+    checkWordIndex("compact", "outIndex", r.outIndex, r.outCount);
+}
+/**
+ * The argument checks of recordDedupe(): the count, the two entry buffers (`out` holds at
+ * most one entry per owner word, so it is checked against `min(count, owner words)`: the SSSP piles of P8-T9 dedupe
+ * a raw half of `arcCount` capacity into an `n`-word pile), the output word, and -- with a device count -- a count
+ * word that is inside `counters`, is not the output word (the filter's atomicAdd would corrupt the count other
+ * workgroups of the same dispatch still read) and lives in the block `outCount` names (the two kernels read it
+ * through their own binding).
+ * @param r - the record
+ */
+function checkDedupeArguments(r) {
+    checkCount("dedupe", r.count);
+    checkWords("dedupe", "queue", r.queue, r.count);
+    checkWords("dedupe", "out", r.out, Math.min(r.count, Math.floor(r.owner.size / 4)));
+    checkWordIndex("dedupe", "outIndex", r.outIndex, r.outCount);
+    if (r.countIndex === U32_MAX) {
+        return;
+    }
+    checkWordIndex("dedupe", "countIndex", r.countIndex, r.counters);
+    if (r.countIndex === r.outIndex) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "dedupe: countIndex must not be the output word outIndex", {
+            argument: "countIndex",
+            value: r.countIndex,
+        });
+    }
+    if (r.counters.buffer !== r.outCount.buffer ||
+        r.counters.offset !== r.outCount.offset ||
+        r.counters.size !== r.outCount.size) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "dedupe: counters must be the same range as outCount when countIndex names a device word", {
+            argument: "counters",
+            value: r.counters.size,
+            expected: r.outCount.size,
+        });
+    }
+}
+/** The planner: the three resolved kernels and the scan over one scope. */
+class CompactPlannerImpl {
+    /**
+     * Wraps the resolved kernels; use prepareCompact().
+     * @param scope - the caller's scope
+     * @param scatter - the `compact-scatter` kernel
+     * @param claim - the `dedupe-claim` kernel
+     * @param filter - the `dedupe-filter` kernel
+     * @param scan - the scan planner of the same scope
+     */
+    constructor(scope, scatter, claim, filter, scan) {
+        this.dispatches = 0;
+        this.scope = scope;
+        this.scatter = scatter;
+        this.claim = claim;
+        this.filter = filter;
+        this.scan = scan;
+    }
+    /**
+     * Dispatches the last record*() issued.
+     * @returns the count
+     */
+    get lastDispatches() {
+        return this.dispatches;
+    }
+    /**
+     * Records the scan and the scatter (see the interface).
+     * @param pass - the compute pass
+     * @param r - the record
+     */
+    record(pass, r) {
+        checkCompactArguments(r);
+        if (r.count === 0) {
+            this.dispatches = 0;
+            return;
+        }
+        const size = 4 * r.count;
+        const offsets = { buffer: this.scope.scratch(size, "compact/offsets"), offset: 0, size, window: null };
+        this.scan.record(pass, r.flags, r.count, offsets);
+        const params = this.scope.params(COMPACT_PARAMS, {
+            count: r.count,
+            outIndex: r.outIndex,
+            countIndex: U32_MAX,
+            stride: 0,
+        });
+        const bound = this.scatter.bind({
+            queue: r.queue,
+            flags: r.flags,
+            offsets,
+            out: r.out,
+            outCount: r.outCount,
+            P: params.binding,
+        });
+        this.scatter.dispatch(pass, bound, plan1d(r.count, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+        this.dispatches = this.scan.lastDispatches + 1;
+    }
+    /**
+     * Records the claim and the filter over plan1d(count) (see the interface).
+     * @param pass - the compute pass
+     * @param r - the record
+     */
+    recordDedupe(pass, r) {
+        checkDedupeArguments(r);
+        if (r.count === 0) {
+            this.dispatches = 0;
+            return;
+        }
+        const plan = planGridStride(r.count, this.scope.workgroupSize, this.scope.caps);
+        const bound = this.bindDedupe(r, plan.stride ?? this.scope.workgroupSize);
+        this.claim.dispatch(pass, bound.claim, plan, [bound.offset]);
+        this.filter.dispatch(pass, bound.filter, plan, [bound.offset]);
+        this.dispatches = 2;
+    }
+    /**
+     * One params record (both kernels read the same values) and the two bind groups.
+     * @param r - the record
+     * @param stride - the grid-stride plan's stride (entries per pass over the grid)
+     * @returns the bound kernels and the record's dynamic offset
+     */
+    bindDedupe(r, stride) {
+        const params = this.scope.params(COMPACT_PARAMS, {
+            count: r.count,
+            outIndex: r.outIndex,
+            countIndex: r.countIndex,
+            stride,
+        });
+        return {
+            claim: this.claim.bind({ queue: r.queue, owner: r.owner, counters: r.counters, P: params.binding }),
+            filter: this.filter.bind({
+                queue: r.queue,
+                owner: r.owner,
+                out: r.out,
+                outCount: r.outCount,
+                P: params.binding,
+            }),
+            offset: params.offset,
+        };
+    }
+}
+//# sourceMappingURL=compact.js.map

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

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

package/dist/src/primitives/core-shape.d.ts

@@ -44,6 +44,25 @@ export declare function arcCountOf(core: CoreBinding): number;
  * @returns the binding; E_INVALID_ARGUMENT when the core is not windowed or the array is absent
  */
 export declare function windowBinding(core: CoreBinding, name: "colIdx" | "weights" | "arcToEdge", w: ArcWindow): Binding;
+/** One dispatch of a frontier-walking kernel over a core (P8-T12): the arc range it owns and the core with its arc-indexed arrays bound to that window (the core itself, over every arc, when it is not windowed). */
+export interface CoreWindow {
+    readonly arcBase: number;
+    readonly arcEnd: number;
+    readonly core: CoreBinding;
+}
+/**
+ * The per-window dispatches of a kernel that walks rows named by a FRONTIER rather than by a row range (P8-T12:
+ * `advance-expand`, `bfs-fused`, `bfs-bottom-up`, `sssp-pred`): every window sees every frontier entry and clips
+ * each row to `[arcBase, arcEnd)`, so the ranges must PARTITION `[0, arcCount)` or a row is expanded twice. P4's
+ * windows do not: `planArcWindows` opens a window at the previous window's end aligned DOWN to 64 arcs, so two
+ * consecutive windows overlap by up to 63 arcs at an unaligned row boundary (the overlap belongs to the earlier
+ * window's rows, which a row-range dispatch such as `degree` never revisits). Here a window owns `[start, next
+ * window's start)` -- the last one `[start, end)` -- which is inside its binding (`next.start <= end`) and
+ * partitions the arcs exactly; a window whose owned range is empty dispatches, harmlessly, over nothing.
+ * @param core - the core (windowed or not)
+ * @returns one entry per window, in arc order; exactly one entry over `[0, arcCount)` when the core is not windowed
+ */
+export declare function coreWindows(core: CoreBinding): readonly CoreWindow[];
 /**
  * Rejects a windowed core: the pull cannot accumulate its affine epilogue across windows (DEP-P4-B).
  * @param core - the core
@@ -67,7 +86,9 @@ export declare function assertWholeCore(core: CoreBinding, arcCount: number, lim
  * package. `plan` is "perArray" because views always upload per array (spec 4.3 lines 1182-1186) and `windows` is
  * null because a view is never windowed, which is what makes assertNotWindowed pass for a view. `serial` is -1: a
  * view is not a core and no caller of this function reads serial (nothing in src/primitives or src/algorithms
- * reads CoreBinding.serial).
+ * reads CoreBinding.serial). A zero-size `colIdx` or `weights` binding (the reverse view of an arc-less directed
+ * snapshot uploads zero-byte arc arrays) becomes null, the core's own spelling of "no arcs", so `graphBindings` binds
+ * the dummy instead of a zero-length range (P8-T8: the one-node directed fixture of the BFS suite).
  * @param v - the view binding, from residency.view(s, "reverse") or view(s, "edgeList")
  * @param arcCount - the arc count of the view, from v.scalars.arcCount[0]; it must agree with the colIdx binding,
  * which is what record() derives the arc window from (E_INVALID_ARGUMENT { argument: "arcCount" } otherwise)

package/dist/src/primitives/core-shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-shape.d.ts","sourceRoot":"","sources":["../../../src/primitives/core-shape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElE,iJAAiJ;AACjJ,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,gIAAgI;AAChI,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CA4B5D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAcvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAUhH;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQ3G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAmCxE"}
+{"version":3,"file":"core-shape.d.ts","sourceRoot":"","sources":["../../../src/primitives/core-shape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElE,iJAAiJ;AACjJ,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,gIAAgI;AAChI,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CA4B5D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAcvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAUhH;AAED,sNAAsN;AACtN,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,UAAU,EAAE,CAapE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQ3G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAqCxE"}

package/dist/src/primitives/core-shape.js

@@ -83,6 +83,32 @@ export function windowBinding(core, name, w) {
     }
     return { buffer, offset: w.offset, size: 4 * (w.end - w.start), window: w };
 }
+/**
+ * The per-window dispatches of a kernel that walks rows named by a FRONTIER rather than by a row range (P8-T12:
+ * `advance-expand`, `bfs-fused`, `bfs-bottom-up`, `sssp-pred`): every window sees every frontier entry and clips
+ * each row to `[arcBase, arcEnd)`, so the ranges must PARTITION `[0, arcCount)` or a row is expanded twice. P4's
+ * windows do not: `planArcWindows` opens a window at the previous window's end aligned DOWN to 64 arcs, so two
+ * consecutive windows overlap by up to 63 arcs at an unaligned row boundary (the overlap belongs to the earlier
+ * window's rows, which a row-range dispatch such as `degree` never revisits). Here a window owns `[start, next
+ * window's start)` -- the last one `[start, end)` -- which is inside its binding (`next.start <= end`) and
+ * partitions the arcs exactly; a window whose owned range is empty dispatches, harmlessly, over nothing.
+ * @param core - the core (windowed or not)
+ * @returns one entry per window, in arc order; exactly one entry over `[0, arcCount)` when the core is not windowed
+ */
+export function coreWindows(core) {
+    if (core.windows === null) {
+        return [{ arcBase: 0, arcEnd: arcCountOf(core), core }];
+    }
+    return core.windows.map((w, k, all) => ({
+        arcBase: w.start,
+        arcEnd: k + 1 < all.length ? all[k + 1].start : w.end,
+        core: {
+            ...core,
+            colIdx: windowBinding(core, "colIdx", w),
+            weights: core.weights === null ? null : windowBinding(core, "weights", w),
+        },
+    }));
+}
 /**
  * Rejects a windowed core: the pull cannot accumulate its affine epilogue across windows (DEP-P4-B).
  * @param core - the core
@@ -116,7 +142,9 @@ export function assertWholeCore(core, arcCount, limit, algorithm) {
  * package. `plan` is "perArray" because views always upload per array (spec 4.3 lines 1182-1186) and `windows` is
  * null because a view is never windowed, which is what makes assertNotWindowed pass for a view. `serial` is -1: a
  * view is not a core and no caller of this function reads serial (nothing in src/primitives or src/algorithms
- * reads CoreBinding.serial).
+ * reads CoreBinding.serial). A zero-size `colIdx` or `weights` binding (the reverse view of an arc-less directed
+ * snapshot uploads zero-byte arc arrays) becomes null, the core's own spelling of "no arcs", so `graphBindings` binds
+ * the dummy instead of a zero-length range (P8-T8: the one-node directed fixture of the BFS suite).
  * @param v - the view binding, from residency.view(s, "reverse") or view(s, "edgeList")
  * @param arcCount - the arc count of the view, from v.scalars.arcCount[0]; it must agree with the colIdx binding,
  * which is what record() derives the arc window from (E_INVALID_ARGUMENT { argument: "arcCount" } otherwise)
@@ -131,8 +159,10 @@ export function coreOfView(v, arcCount) {
             expected: "a view with a rowPtr binding (reverse)",
         });
     }
-    const colIdx = v.bindings.colIdx ?? null;
-    const weights = v.bindings.weights ?? null;
+    // an arc-less DIRECTED snapshot's reverse view uploads zero-byte arc arrays; the core spells "no arcs" as null
+    // (graphBindings then binds the rowPtr dummy), and a zero-size binding is never bound (spec 3.6)
+    const colIdx = v.bindings.colIdx === undefined || v.bindings.colIdx.size === 0 ? null : v.bindings.colIdx;
+    const weights = v.bindings.weights === undefined || v.bindings.weights.size === 0 ? null : v.bindings.weights;
     const bound = colIdx === null ? 0 : colIdx.size / 4;
     if (bound !== arcCount) {
         throw new WebGpuGraphError("E_INVALID_ARGUMENT", `the ${v.view} view binds ${bound} arcs but its arcCount scalar says ${arcCount}`, {