@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/dist/src/primitives/spmv.js

@@ -1,7 +1,6 @@
 /**
- * The pull SpMV primitive of spec 6 row 9 / 8.2 in its thread-per-row tier (P7; M8b plan PD-1 / PD-2): one
- * grid-stride dispatch of the `spmv-pull` module over the rows of a REVERSE adjacency, each invocation folding
- * `weight * xNorm[nbr]` over its row's in-arcs (Kahan-compensated, f32) and writing
+ * The pull SpMV primitive of spec 6 row 9 / 8.2 (P7; M8b plan PD-1 / PD-2): the `spmv-pull` module over the rows of
+ * a REVERSE adjacency, each row folding `weight * xNorm[nbr]` over its in-arcs (a two-level f32 sum) and writing
  * `rankOut[v] = beta * pv + alpha * (sum + danglingMass * pv)`, where `pv` is `personalization[v]` under
  * HAS_PERSONALIZATION and the uniform `P.uniformP` otherwise, and `danglingMass` is `partials[0].danglingMass`
  * under USE_DANGLING. PageRank sets alpha to the damping, beta to 1 - alpha and USE_DANGLING; HITS and eigenvector
@@ -9,93 +8,130 @@
  *
  * It is its own registry entry rather than a `segmentedReduce` VALUE snippet (PD-1): the snippet vocabulary is
  * `row, arc, nbr, weight, v` and cannot read `xNorm[nbr]`, and the design's binding table gives the kernel eight
- * storage bindings of its own. The in-degree tiers of `reverseDegreeOrder()` land at P4 (PD-2): `tiers !== null` is
- * E_UNSUPPORTED and USE_PERM is always false (the perm slot carries the rowPtr dummy of graphBindings). The row and
- * arc counts come from the core's binding sizes exactly as segmentedReduce derives them.
+ * storage bindings of its own. Without tiers it is ONE grid-stride dispatch (TIER 0, USE_PERM false: the perm slot
+ * carries the rowPtr dummy of graphBindings); with the in-degree tiers of `reverseDegreeOrder()` (P4-T5, PD-6) it
+ * is up to three dispatches over the permuted rows -- TIER 2 one workgroup per row over [0, hiEnd), TIER 1 32 lanes
+ * per row over [hiEnd, midEnd), TIER 0 grid-stride over [midEnd, n) -- each compiled only when its range is
+ * non-empty. The row and arc counts come from the core's binding sizes exactly as segmentedReduce derives them.
  */
 import { WebGpuGraphError } from "../errors.js";
-import { planGridStride } from "../kernel/dispatch.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
 import { graphBindings, graphOverrides, kernelSpec, SPMV_PARAMS } from "../kernels.js";
-import { arcCountOf, assertNotWindowed, rowCountOf } from "./core-shape.js";
-/** The thread-per-row planner: ONE `spmv-pull` dispatch, grid-stride over every row. */
+import { arcCountOf, assertNotWindowed, MID_TIER_LANES, rowCountOf } from "./core-shape.js";
+/**
+ * The tiered planner: without tiers ONE `spmv-pull` dispatch, grid-stride over every row; with tiers TIER 2 over
+ * [0, hiEnd) (one workgroup per row), then TIER 1 over [hiEnd, midEnd) (WG / 32 rows per workgroup), then TIER 0
+ * grid-stride over [midEnd, n), each with its own SpmvParams record (`n` is the range END) and the perm binding.
+ */
 class SpmvPullPlannerImpl {
     /**
-     * Wraps a compiled pipeline with the weights choice it was compiled for.
-     * @param scope - the scope the pipeline was prepared in
-     * @param kernel - the compiled kernel
-     * @param weights - the weights option the pipeline's HAS_WEIGHTS was derived from; record() binds the same way
+     * Wraps the compiled tier pipelines with the choices they were compiled for.
+     * @param scope - the scope the pipelines were prepared in
+     * @param tiers - the compiled tiers in dispatch order (TIER 2, 1, 0; only the non-empty ones)
+     * @param perm - the reverseDegreeOrder permutation binding (null: USE_PERM false, rows are node indices)
+     * @param weights - the weights option the pipelines' HAS_WEIGHTS was derived from; record() binds the same way
      */
-    constructor(scope, kernel, weights) {
+    constructor(scope, tiers, perm, weights) {
         this.dispatches = 0;
         this.scope = scope;
-        this.kernel = kernel;
+        this.tiers = tiers;
+        this.perm = perm;
         this.weights = weights;
     }
     /**
      * Dispatches the last record() issued.
-     * @returns 1, or 0 when the last record covered no rows
+     * @returns 0 when the last record covered no rows, else the number of non-empty tier ranges
      */
     get lastDispatches() {
         return this.dispatches;
     }
     /**
-     * Records the dispatch: rows [0, n), arcs [0, arcCount), planGridStride(n); nothing for n = 0 (no zero-length
-     * binding is ever created). `personalization ?? xNorm` follows the group-0 dummy rule: both slots are
-     * storage-ro, so the aliasing check of Kernel.bind does not fire, and HAS_PERSONALIZATION false never reads it.
+     * Records the dispatches: every tier's rows over the arcs [0, arcCount), each with its own params record (TIER 0
+     * grid-stride through planGridStride, the tiers through plan1d); nothing for n = 0 (no zero-length binding is
+     * ever created). `personalization ?? xNorm` follows the group-0 dummy rule: both slots are storage-ro, so the
+     * aliasing check of Kernel.bind does not fire, and HAS_PERSONALIZATION false never reads it.
      * @param pass - the pass to record into
-     * @param rev - the reverse core (any snapshot with the weights pattern the planner was prepared for)
+     * @param rev - the reverse core (any snapshot with the weights pattern the planner was prepared for; with tiers,
+     * the one the tiers were built from)
      * @param resources - xNorm, rankOut, personalization, partials
      * @param coefficients - alpha, beta, uniformP
      */
     record(pass, rev, resources, coefficients) {
         const n = rowCountOf(rev, "spmvPull");
-        const plan = planGridStride(n, this.scope.workgroupSize, this.scope.caps);
-        if (plan.x === 0) {
-            this.dispatches = 0;
-            return;
+        const wg = this.scope.workgroupSize;
+        this.dispatches = 0;
+        for (const { tier, kernel, start, end } of this.tiers) {
+            const last = tier === 0 ? n : end;
+            const rows = last - start;
+            if (rows <= 0) {
+                continue;
+            }
+            const plan = tier === 0
+                ? planGridStride(rows, wg, this.scope.caps)
+                : plan1d(rows, tier === 2 ? 1 : wg / MID_TIER_LANES, this.scope.caps);
+            if (plan.x === 0) {
+                continue;
+            }
+            const params = this.scope.params(SPMV_PARAMS, {
+                n: last,
+                arcBase: 0,
+                arcEnd: arcCountOf(rev),
+                stride: plan.stride ?? rows,
+                alpha: coefficients.alpha,
+                beta: coefficients.beta,
+                uniformP: coefficients.uniformP,
+                start,
+            });
+            const bound = kernel.bind({
+                ...graphBindings(rev, this.perm, this.weights),
+                xNorm: resources.xNorm,
+                rankOut: resources.rankOut,
+                personalization: resources.personalization ?? resources.xNorm,
+                partials: resources.partials,
+                P: params.binding,
+            });
+            kernel.dispatch(pass, bound, plan, [params.offset]);
+            this.dispatches++;
         }
-        const params = this.scope.params(SPMV_PARAMS, {
-            n,
-            arcBase: 0,
-            arcEnd: arcCountOf(rev),
-            stride: plan.stride ?? n,
-            alpha: coefficients.alpha,
-            beta: coefficients.beta,
-            uniformP: coefficients.uniformP,
-            pad0: 0,
-        });
-        const bound = this.kernel.bind({
-            ...graphBindings(rev, null, this.weights),
-            xNorm: resources.xNorm,
-            rankOut: resources.rankOut,
-            personalization: resources.personalization ?? resources.xNorm,
-            partials: resources.partials,
-            P: params.binding,
-        });
-        this.kernel.dispatch(pass, bound, plan, [params.offset]);
-        this.dispatches = 1;
     }
 }
 /**
- * Prepares the thread-per-row pull pipeline for a reverse core's weights pattern and the two variant flags.
+ * Prepares the pull pipelines for a reverse core's weights pattern and the two variant flags: TIER 0 always
+ * (USE_PERM = tiers !== null); TIER 1 iff a row of in-degree 32..1023 exists (segmentOffsets[2] >
+ * segmentOffsets[1]); TIER 2 iff a row of in-degree >= 1024 exists (segmentOffsets[1] > 0). The mid tier folds 32
+ * lanes per row, so a device whose workgroup size is below 32 is E_UNSUPPORTED { feature: "spmvPull.tiers" }.
  * @param scope - the reduce scope (pipelines, params writer)
- * @param rev - the reverse core whose weights pattern selects HAS_WEIGHTS (USE_PERM is false: no tiers at P7)
- * @param options - personalization, dangling, weights, tiers (must be null)
+ * @param rev - the reverse core whose weights pattern selects HAS_WEIGHTS
+ * @param options - personalization, dangling, weights, tiers (null: the single grid-stride dispatch)
  * @returns the planner
  */
 export async function prepareSpmvPull(scope, rev, options) {
-    if (options.tiers !== null) {
-        throw new WebGpuGraphError("E_UNSUPPORTED", "spmvPull: the in-degree tiers land at P4; pass tiers: null", {
-            feature: "spmvPull.tiers",
+    assertNotWindowed(rev, "spmvPull");
+    const { tiers } = options;
+    const perm = tiers?.perm ?? null;
+    if (tiers !== null && scope.workgroupSize < MID_TIER_LANES) {
+        throw new WebGpuGraphError("E_UNSUPPORTED", `spmvPull: the mid tier folds ${MID_TIER_LANES} lanes per row, more than the workgroup size ${scope.workgroupSize}`, { feature: "spmvPull.tiers" });
+    }
+    const ranges = tiers === null
+        ? [{ tier: 0, start: 0, end: rowCountOf(rev, "spmvPull") }]
+        : [
+            { tier: 2, start: 0, end: tiers.segmentOffsets[1] },
+            { tier: 1, start: tiers.segmentOffsets[1], end: tiers.segmentOffsets[2] },
+            { tier: 0, start: tiers.segmentOffsets[2], end: tiers.segmentOffsets[4] },
+        ];
+    const compiled = [];
+    for (const range of ranges) {
+        if (range.tier !== 0 && range.end <= range.start) {
+            continue;
+        }
+        const spec = kernelSpec("spmv-pull", {
+            ...graphOverrides(rev, perm, options.weights),
+            HAS_PERSONALIZATION: options.personalization,
+            USE_DANGLING: options.dangling,
+            TIER: range.tier,
         });
+        compiled.push({ ...range, kernel: await scope.pipelines.kernel(spec) });
     }
-    assertNotWindowed(rev, "spmvPull");
-    const spec = kernelSpec("spmv-pull", {
-        ...graphOverrides(rev, null, options.weights),
-        HAS_PERSONALIZATION: options.personalization,
-        USE_DANGLING: options.dangling,
-    });
-    const kernel = await scope.pipelines.kernel(spec);
-    return new SpmvPullPlannerImpl(scope, kernel, options.weights);
+    return new SpmvPullPlannerImpl(scope, compiled, perm, options.weights);
 }
 //# sourceMappingURL=spmv.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"spmv.js","sourceRoot":"","sources":["../../../src/primitives/spmv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGvF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAoC5E,wFAAwF;AACxF,MAAM,mBAAmB;IAMrB;;;;;OAKG;IACH,YAAY,KAAkB,EAAE,MAAc,EAAE,OAAmC;QAR3E,eAAU,GAAG,CAAC,CAAC;QASnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CACF,IAA2B,EAC3B,GAAgB,EAChB,SAAwB,EACxB,YAA8B;QAE9B,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1E,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;YACpB,OAAO;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE;YAC1C,CAAC;YACD,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC;YACxB,KAAK,EAAE,YAAY,CAAC,KAAK;YACzB,IAAI,EAAE,YAAY,CAAC,IAAI;YACvB,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,IAAI,EAAE,CAAC;SACV,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAC3B,GAAG,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC;YACzC,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,eAAe,EAAE,SAAS,CAAC,eAAe,IAAI,SAAS,CAAC,KAAK;YAC7D,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,CAAC,EAAE,MAAM,CAAC,OAAO;SACpB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IACxB,CAAC;CACJ;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,KAAkB,EAClB,GAAgB,EAChB,OAAwB;IAExB,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,4DAA4D,EAAE;YACtG,OAAO,EAAE,gBAAgB;SAC5B,CAAC,CAAC;IACP,CAAC;IACD,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE;QACjC,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;QAC7C,mBAAmB,EAAE,OAAO,CAAC,eAAe;QAC5C,YAAY,EAAE,OAAO,CAAC,QAAQ;KACjC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,IAAI,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"spmv.js","sourceRoot":"","sources":["../../../src/primitives/spmv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGvF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAoB,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAgD9G;;;;GAIG;AACH,MAAM,mBAAmB;IAOrB;;;;;;OAMG;IACH,YACI,KAAkB,EAClB,KAA8B,EAC9B,IAAoB,EACpB,OAAmC;QAb/B,eAAU,GAAG,CAAC,CAAC;QAenB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CACF,IAA2B,EAC3B,GAAgB,EAChB,SAAwB,EACxB,YAA8B;QAE9B,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACtC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpD,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;YAC1B,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACZ,SAAS;YACb,CAAC;YACD,MAAM,IAAI,GACN,IAAI,KAAK,CAAC;gBACN,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC3C,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9E,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACf,SAAS;YACb,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE;gBAC1C,CAAC,EAAE,IAAI;gBACP,OAAO,EAAE,CAAC;gBACV,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC;gBACvB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;gBAC3B,KAAK,EAAE,YAAY,CAAC,KAAK;gBACzB,IAAI,EAAE,YAAY,CAAC,IAAI;gBACvB,QAAQ,EAAE,YAAY,CAAC,QAAQ;gBAC/B,KAAK;aACR,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;gBACtB,GAAG,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC;gBAC9C,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,eAAe,EAAE,SAAS,CAAC,eAAe,IAAI,SAAS,CAAC,KAAK;gBAC7D,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,CAAC,EAAE,MAAM,CAAC,OAAO;aACpB,CAAC,CAAC;YACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACpD,IAAI,CAAC,UAAU,EAAE,CAAC;QACtB,CAAC;IACL,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,KAAkB,EAClB,GAAgB,EAChB,OAAwB;IAExB,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,MAAM,IAAI,GAAG,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,aAAa,GAAG,cAAc,EAAE,CAAC;QACzD,MAAM,IAAI,gBAAgB,CACtB,eAAe,EACf,gCAAgC,cAAc,gDAAgD,KAAK,CAAC,aAAa,EAAE,EACnH,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAChC,CAAC;IACN,CAAC;IACD,MAAM,MAAM,GACR,KAAK,KAAK,IAAI;QACV,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC;QAC3D,CAAC,CAAC;YACI,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE;YACnD,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE;YACzE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE;SAC5E,CAAC;IACZ,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/C,SAAS;QACb,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE;YACjC,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;YAC7C,mBAAmB,EAAE,OAAO,CAAC,eAAe;YAC5C,YAAY,EAAE,OAAO,CAAC,QAAQ;YAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;SACnB,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;AAC3E,CAAC"}

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

@@ -0,0 +1,49 @@
+/**
+ * The device self-check: one real exclusive scan of known numbers, run once per device before this package
+ * computes anything on it, so a device that returns wrong numbers is refused instead of believed.
+ *
+ * WHY IT EXISTS. On the Windows host lane -- Dawn's D3D12 backend over the Microsoft Basic Render Driver, the
+ * software renderer built into Windows -- every exclusive scan of more than one workgroup came back wrong: a
+ * block total of 1 where 256 belonged, or a second block nothing wrote at all, differing between two runs of
+ * identical code in one job. Everything built on the scan was wrong with it (the histogram, the radix sort, the
+ * grid build and every layout above them, eighteen test files), while every single-block scan and every earlier
+ * primitive stayed right. Three shader repairs failed; copying Microsoft's current redistributable renderer
+ * beside the runner's Node executable made all of it pass untouched. The defect is the driver's, and the danger
+ * to a caller is not a crash but silence: a graph laid out from wrong numbers with no error anywhere.
+ *
+ * WHY IT SCANS RATHER THAN PROBING A CONSTRUCT. An earlier hand-written probe matrix of workgroup constructs
+ * (test/primitives/workgroup-id-probe.test.ts) was measured PASSING on that renderer in the same job in which the
+ * real scan returned the wrong answer, so a copy of the shader's shape is not evidence about the shader. This
+ * check therefore drives the shipped `prepareScan` through the shipped composer and pipeline cache: it tests the
+ * code that runs, and it cannot drift away from it. One scan covers both recorded failures -- a value crossing
+ * `workgroupBarrier` inside a block, and a block total crossing from one dispatch of a compute pass to the next
+ * dispatch that reads it, which is the shape of every driver in this package.
+ *
+ * WHY IT REFUSES RATHER THAN ROUTING AROUND THE DEFECT. See docs/decisions/device-self-check.md: a barrier-free second
+ * implementation was designed and costed, and rejected because it would ship unverified on the only platform it
+ * exists for.
+ *
+ * WHERE IT RUNS. Lazily, at the first compute entry point a caller reaches, memoised per GPUDevice: the
+ * algorithms (degree, connectedComponents, the power-iteration family) and calibrateLayout await it on entry, and
+ * a layout simulation awaits it in the compile-and-bind promise `load()` starts -- the promise every batch and
+ * every debug run already awaits before it may submit. So a caller is covered whether the context was created,
+ * adopted through `create({ device })` or adopted through `GpuContext.from`, and a simulation refuses before its
+ * first iteration without the check sitting on the per-batch path, where an extra await would move the moment a
+ * submission becomes visible to a step() issued in the same tick and so change how the frame loop coalesces.
+ * It deliberately does NOT run in GpuContext.create:
+ * a context that only compiles -- Dawn's null backend, which computes nothing by design -- must stay usable, and
+ * `src/context.ts` may not import a primitive (the layer rule of spec 3.2).
+ */
+import { type CheckedContext, type DeviceCheck } from "../types/context.js";
+/**
+ * What this device computed when it was asked for an answer this package already knows, run once per device and
+ * remembered. A caller may await it before committing work to a context; every compute entry point of the
+ * package awaits it too, so the cost is paid once whoever asks first.
+ *
+ * It reports rather than throws, so a caller can ask a device a question without having to catch the answer. The
+ * entry points use `assertDeviceComputes`, which turns a failing report into E_DEVICE_INCORRECT.
+ * @param ctx - the context whose device is checked
+ * @returns the capability record; `ok` false means this device returns wrong numbers
+ */
+export declare function verifyDevice(ctx: CheckedContext): Promise<DeviceCheck>;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/primitives/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAA4B,MAAM,qBAAqB,CAAC;AA0ItG;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAatE"}

package/dist/src/primitives/verify.js

@@ -0,0 +1,229 @@
+/**
+ * The device self-check: one real exclusive scan of known numbers, run once per device before this package
+ * computes anything on it, so a device that returns wrong numbers is refused instead of believed.
+ *
+ * WHY IT EXISTS. On the Windows host lane -- Dawn's D3D12 backend over the Microsoft Basic Render Driver, the
+ * software renderer built into Windows -- every exclusive scan of more than one workgroup came back wrong: a
+ * block total of 1 where 256 belonged, or a second block nothing wrote at all, differing between two runs of
+ * identical code in one job. Everything built on the scan was wrong with it (the histogram, the radix sort, the
+ * grid build and every layout above them, eighteen test files), while every single-block scan and every earlier
+ * primitive stayed right. Three shader repairs failed; copying Microsoft's current redistributable renderer
+ * beside the runner's Node executable made all of it pass untouched. The defect is the driver's, and the danger
+ * to a caller is not a crash but silence: a graph laid out from wrong numbers with no error anywhere.
+ *
+ * WHY IT SCANS RATHER THAN PROBING A CONSTRUCT. An earlier hand-written probe matrix of workgroup constructs
+ * (test/primitives/workgroup-id-probe.test.ts) was measured PASSING on that renderer in the same job in which the
+ * real scan returned the wrong answer, so a copy of the shader's shape is not evidence about the shader. This
+ * check therefore drives the shipped `prepareScan` through the shipped composer and pipeline cache: it tests the
+ * code that runs, and it cannot drift away from it. One scan covers both recorded failures -- a value crossing
+ * `workgroupBarrier` inside a block, and a block total crossing from one dispatch of a compute pass to the next
+ * dispatch that reads it, which is the shape of every driver in this package.
+ *
+ * WHY IT REFUSES RATHER THAN ROUTING AROUND THE DEFECT. See docs/decisions/device-self-check.md: a barrier-free second
+ * implementation was designed and costed, and rejected because it would ship unverified on the only platform it
+ * exists for.
+ *
+ * WHERE IT RUNS. Lazily, at the first compute entry point a caller reaches, memoised per GPUDevice: the
+ * algorithms (degree, connectedComponents, the power-iteration family) and calibrateLayout await it on entry, and
+ * a layout simulation awaits it in the compile-and-bind promise `load()` starts -- the promise every batch and
+ * every debug run already awaits before it may submit. So a caller is covered whether the context was created,
+ * adopted through `create({ device })` or adopted through `GpuContext.from`, and a simulation refuses before its
+ * first iteration without the check sitting on the per-batch path, where an extra await would move the moment a
+ * submission becomes visible to a step() issued in the same tick and so change how the frame loop coalesces.
+ * It deliberately does NOT run in GpuContext.create:
+ * a context that only compiles -- Dawn's null backend, which computes nothing by design -- must stay usable, and
+ * `src/context.ts` may not import a primitive (the layer rule of spec 3.2).
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { UniformRing } from "../kernel/uniform-ring.js";
+import { prepareScan } from "./scan.js";
+/**
+ * The word written into every output slot before the dispatch, so a word NOTHING wrote is distinguishable from
+ * a word written wrongly. The Windows lane returned this value from the second block, which is how the failure
+ * was read as "the block was never written" rather than "the block was miscomputed".
+ */
+const POISON = 0xdeadbeef;
+/** Full workgroups the check scans; one partial workgroup of a single word follows them. */
+const CHECK_BLOCKS = 32;
+/** Params slots the scan's levels need (two levels of block scan plus one add-back, with room to spare). */
+const RING_SLOTS = 8;
+/** The settled check per device: the one work a second caller never repeats. A rejection is dropped, so a check that failed to RUN is retried. */
+const checked = new WeakMap();
+/**
+ * The input word at `i`: 1, 2, 3, ... so no two workgroups have the same block total (all-ones would give every
+ * block the same one, and a block total stored at the wrong index would still read correct -- which is exactly
+ * the Windows symptom) and every output word is a different number.
+ * @param i - the word index
+ * @returns the input value
+ */
+function inputAt(i) {
+    return i + 1;
+}
+/**
+ * The verdict: the first output word or total that disagrees with the arithmetic answer, or null when nothing
+ * does. Pure, so test/primitives/verify.test.ts can drive it past a fabricated wrong result and exercise the
+ * refusal without a broken device.
+ * @param words - the `count` output words read back from the device
+ * @param total - the total word read back from the device
+ * @param count - the words scanned
+ * @returns the first disagreement, or null
+ * @internal
+ */
+export function checkScanWords(words, total, count) {
+    let running = 0;
+    for (let i = 0; i < count; i++) {
+        const got = words[i];
+        if (got !== running) {
+            return { where: `out[${String(i)}]`, expected: running, actual: got, poison: got === POISON };
+        }
+        // u32 addition wraps in WGSL, so the host oracle wraps too: at WORKGROUP_SIZE 256 the total cannot
+        // reach 2^32, but a false refusal would deny every device on earth, so it is not left to that constant
+        running = (running + inputAt(i)) >>> 0;
+    }
+    if (total !== running) {
+        return { where: "total", expected: running, actual: total, poison: total === POISON };
+    }
+    return null;
+}
+/**
+ * Binds a whole scratch buffer.
+ * @param buffer - the buffer
+ * @param size - the bytes bound
+ * @returns the binding
+ */
+function whole(buffer, size) {
+    return { buffer, offset: 0, size, window: null };
+}
+/**
+ * Runs the check once: one scan of `CHECK_BLOCKS * workgroupSize + 1` words recorded into one compute pass, one
+ * submit, the output and the total read back and verified on the host.
+ *
+ * It never throws for a wrong ANSWER -- that is the returned record's job. A failure of the machinery (a lost
+ * device, a validation error, out of memory) propagates with its own code, so "the driver computes incorrectly"
+ * is never said about a device that merely died.
+ * @param ctx - the context to check
+ * @returns what the check found
+ */
+async function runCheck(ctx) {
+    const started = performance.now();
+    const wg = ctx.workgroupSize;
+    const count = CHECK_BLOCKS * wg + 1;
+    const bytes = 4 * count;
+    const lease = ctx.pool.lease();
+    const ring = new UniformRing(ctx.device, ctx.allocator, RING_SLOTS, "device-check/ring");
+    try {
+        const scope = {
+            device: ctx.device,
+            caps: ctx.caps,
+            pipelines: ctx.pipelines,
+            pool: ctx.pool,
+            workgroupSize: wg,
+            scratch: (byteLength, label) => lease.storage(byteLength, `device-check/${label}`),
+            params(block, values) {
+                const slot = ring.reserve(1);
+                ring.write(slot, block, values);
+                return { binding: ring.binding(block), offset: ring.offsetOf(slot) };
+            },
+        };
+        const planner = await prepareScan(scope);
+        const src = lease.storage(bytes, "device-check/src");
+        const out = lease.storage(bytes, "device-check/out");
+        const input = new Uint32Array(count);
+        for (let i = 0; i < count; i++) {
+            input[i] = inputAt(i);
+        }
+        ctx.device.queue.writeBuffer(src, 0, input);
+        ctx.device.queue.writeBuffer(out, 0, new Uint32Array(count).fill(POISON));
+        const encoder = ctx.device.createCommandEncoder({ label: "device-check" });
+        const pass = encoder.beginComputePass({ label: "device-check" });
+        const total = planner.record(pass, whole(src, bytes), count, whole(out, bytes));
+        pass.end();
+        ring.flush();
+        ctx.device.queue.submit([encoder.finish()]);
+        const words = new Uint32Array(await ctx.readback.read(out, bytes));
+        const totalWord = new Uint32Array(await ctx.readback.read(total.binding.buffer, 4, undefined, total.binding.offset + 4 * total.index));
+        const mismatch = checkScanWords(words, totalWord[0], count);
+        return {
+            check: "exclusive-scan",
+            ok: mismatch === null,
+            workgroupSize: wg,
+            count,
+            blocks: CHECK_BLOCKS,
+            ms: performance.now() - started,
+            vendor: ctx.caps.vendor,
+            architecture: ctx.caps.architecture,
+            description: ctx.caps.description,
+            mismatch,
+        };
+    }
+    finally {
+        ring.destroy();
+        lease.release();
+    }
+}
+/**
+ * What this device computed when it was asked for an answer this package already knows, run once per device and
+ * remembered. A caller may await it before committing work to a context; every compute entry point of the
+ * package awaits it too, so the cost is paid once whoever asks first.
+ *
+ * It reports rather than throws, so a caller can ask a device a question without having to catch the answer. The
+ * entry points use `assertDeviceComputes`, which turns a failing report into E_DEVICE_INCORRECT.
+ * @param ctx - the context whose device is checked
+ * @returns the capability record; `ok` false means this device returns wrong numbers
+ */
+export function verifyDevice(ctx) {
+    const cached = checked.get(ctx.device);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const running = runCheck(ctx).catch((err) => {
+        // only a settled verdict is worth keeping: a check that could not RUN (a lost device, a transient
+        // out-of-memory) must not answer for the device forever
+        checked.delete(ctx.device);
+        throw err;
+    });
+    checked.set(ctx.device, running);
+    return running;
+}
+/**
+ * The guard every compute entry point awaits: resolves on a device that computed the check correctly, throws
+ * E_DEVICE_INCORRECT on one that did not, carrying the first wrong word, what was required there, and the
+ * adapter strings that separate a broken driver from a fixed one.
+ * @param ctx - the context about to be computed on
+ * @internal
+ */
+export async function assertDeviceComputes(ctx) {
+    const check = await verifyDevice(ctx);
+    const { mismatch } = check;
+    if (mismatch === null) {
+        return;
+    }
+    const adapter = {
+        vendor: check.vendor,
+        architecture: check.architecture,
+        device: ctx.caps.device,
+        description: check.description,
+    };
+    const hint = check.architecture === "warp"
+        ? "this is the Microsoft Basic Render Driver; the Microsoft.Direct3D.WARP redistributable (1.0.21 or newer) beside the host executable computes it correctly"
+        : undefined;
+    const observed = mismatch.poison
+        ? `${mismatch.where} was never written (the ${String(POISON)} the check wrote beforehand survived the dispatch)`
+        : `${mismatch.where} came back as ${String(mismatch.actual)} where ${String(mismatch.expected)} was required`;
+    const message = `this device computes multi-workgroup shaders incorrectly: an exclusive scan of ${String(check.count)} ` +
+        `known numbers is wrong -- ${observed}. Refusing to run: every number this package computed here would ` +
+        `be unreliable. adapter: ${adapter.vendor}/${adapter.architecture} "${adapter.description}"`;
+    throw new WebGpuGraphError("E_DEVICE_INCORRECT", hint === undefined ? message : `${message}. ${hint}`, {
+        check: check.check,
+        where: mismatch.where,
+        expected: mismatch.expected,
+        actual: mismatch.actual,
+        poison: mismatch.poison,
+        count: check.count,
+        blocks: check.blocks,
+        workgroupSize: check.workgroupSize,
+        adapter,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+//# sourceMappingURL=verify.js.map

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

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

package/dist/src/types/context.d.ts

@@ -3,6 +3,7 @@
  * as a type, so every layer may `import type` from it without a value edge (the src/types zone of the
  * package eslint config). P0-T3 wrote AdapterInfoLike and AdapterSummary; P1-T1 completes the file.
  */
+import type { GpuContext } from "../context.js";
 import type { WebGpuGraphError } from "../errors.js";
 /** The limits `"raise"` takes from the adapter (spec 2.2); maxComputeWorkgroupsPerDimension is deliberately absent. */
 export type RaisableLimit = "maxBufferSize" | "maxStorageBufferBindingSize" | "maxStorageBuffersPerShaderStage" | "maxComputeWorkgroupStorageSize" | "maxComputeInvocationsPerWorkgroup" | "maxComputeWorkgroupSizeX";
@@ -111,4 +112,56 @@ export interface PlanCaps {
     readonly subgroupMaxSize: number;
     readonly software: boolean;
 }
+/**
+ * The context the device self-check runs on. `src/primitives/**` may not name GpuContext (the layer rule of
+ * spec 3.2), and this file may, so the alias is how src/primitives/verify.ts types its argument. It is
+ * GpuContext and nothing else: pass the context you were going to compute on.
+ */
+export type CheckedContext = GpuContext;
+/**
+ * The first word a device got wrong in the self-check. `poison` is true when the word still held the
+ * 0xdeadbeef the check wrote before the dispatch, which means NOTHING wrote it -- a different failure from a
+ * word written with the wrong value, and the distinction that made the Windows diagnosis possible.
+ */
+export interface DeviceCheckMismatch {
+    /** Where it was found: `out[<index>]`, or `total`. */
+    readonly where: string;
+    /** The value arithmetic requires there. */
+    readonly expected: number;
+    /** The value the device returned. */
+    readonly actual: number;
+    /** True when `actual` is the poison word the check wrote beforehand: nothing wrote this word. */
+    readonly poison: boolean;
+}
+/**
+ * What one device self-check found (spec 3.3): the capability record a caller may read BEFORE it commits work
+ * to a device, through `verifyDevice`. `mismatch === null` (equivalently `ok`) means every one of `count`
+ * output words and the total matched the arithmetic answer; a non-null `mismatch` is the device returning
+ * wrong numbers, which every compute entry point of this package turns into E_DEVICE_INCORRECT.
+ *
+ * It reports one property -- that values crossing a workgroup barrier and block totals crossing dispatches of
+ * one compute pass survive -- and is therefore a refusal mechanism, not a certificate of correctness.
+ */
+export interface DeviceCheck {
+    /** The check that ran; one today, named so a second can be added without changing the shape. */
+    readonly check: "exclusive-scan";
+    /** True when nothing disagreed. */
+    readonly ok: boolean;
+    /** The device's workgroup size (spec 5.1). */
+    readonly workgroupSize: number;
+    /** The words scanned: `blocks * workgroupSize + 1`, so the last workgroup is a partial one. */
+    readonly count: number;
+    /** The full workgroups of the scan (one partial one follows). */
+    readonly blocks: number;
+    /** Wall time of this check in milliseconds, pipeline compile included on the first call. */
+    readonly ms: number;
+    /** caps.vendor of the device that ran it. */
+    readonly vendor: string;
+    /** caps.architecture of the device that ran it. */
+    readonly architecture: string;
+    /** caps.description: the string that separates a broken driver from a fixed one. */
+    readonly description: string;
+    /** The first disagreement, or null when there was none. */
+    readonly mismatch: DeviceCheckMismatch | null;
+}
 //# sourceMappingURL=context.d.ts.map

package/dist/src/types/context.d.ts.map

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

package/dist/src/types/layout.d.ts

@@ -124,4 +124,24 @@ export interface ResolvedLayoutTuning {
     readonly extentFactor: number;
     readonly compat: "paper" | "networkx";
 }
+/** Spec 2.2 CalibrateOptions, verbatim: the probe sizes of calibrateLayout (default 8k / 16k / 32k / 65k). */
+export interface CalibrateOptions {
+    readonly sizes?: readonly number[] | undefined;
+}
+/**
+ * Spec 2.2 GpuCalibration, verbatim: the per-size ms per iteration of both repulsion tiers on the actual device,
+ * `pairsPerSecond` of the exact tier at the largest probed size, `suggestedExactMaxNodes` by the spec 7.8 rule
+ * (the largest probed n with exactMs(n) <= min(4 ms, gridMs(n)), rounded down to a power of two; when NO probed size
+ * qualifies -- the grid tier faster at every probe, or every probe over the budget -- the largest power of two strictly
+ * below the smallest probe, so the exact tier runs at no probed size and a value below floorPow2(min(sizes)) tells the
+ * caller the rule found nothing in the range: src/layouts/calibrate.ts) and the wall time of the whole call (pipeline
+ * compilation included on the first call).
+ */
+export interface GpuCalibration {
+    readonly pairsPerSecond: number;
+    readonly exactMsPerIter: Readonly<Record<number, number>>;
+    readonly gridMsPerIter: Readonly<Record<number, number>>;
+    readonly suggestedExactMaxNodes: number;
+    readonly firstCallMs: number;
+}
 //# sourceMappingURL=layout.d.ts.map