@graphty/webgpu-graph-algorithms 0.2.1 → 0.3.0

package/dist/node.js

@@ -1,4 +1,4 @@
-import { W as WebGpuGraphError, G as GpuContext } from "./chunks/context-E6iKaeuJ.js";
+import { W as WebGpuGraphError, G as GpuContext } from "./chunks/context-CRbw2Wyo.js";
 const INSTALL_HINT = "install the optional peer dependency webgpu@0.4.0";
 function isDawnModule(loaded) {
   return typeof loaded === "object" && loaded !== null && typeof loaded.create === "function";

package/dist/src/accelerator.d.ts

@@ -1,17 +1,20 @@
 /**
  * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
  * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
- * src/types/accelerator.ts until W1, D27). At P3 it carries `forceAtlas2`, `release` and `dispose` and nothing
- * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.pageRank !== undefined` and
- * route to the CPU when the member is absent (spec 2.4 row "method missing"), so a method the GPU does not
- * implement must not exist here -- never a throwing stub. The algorithm members arrive one per shipped algorithm
- * from P7; `fruchtermanReingold` / `springElectrical` with P5.
+ * src/types/accelerator.ts until W1, D27). It carries P3's `forceAtlas2`, `release` and `dispose` and P7's seven
+ * algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and nothing else: the CPU-side dispatchers (`accelerated()`,
+ * `createSimulation()`) test `acc.betweennessCentrality !== undefined` and route to the CPU when the member is
+ * absent (spec 2.4 row "method missing"), so a method the GPU does not implement must not exist here -- never a
+ * throwing stub. The remaining algorithm members arrive one per shipped algorithm from P8; `fruchtermanReingold` /
+ * `springElectrical` with P5.
  */
 import { type GpuContext } from "./context.js";
 import { type AcceleratorOptions, type GpuAccelerator } from "./types/accelerator.js";
 /**
  * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
- * structurally; at P3 it carries forceAtlas2, release and dispose. One per call (the app creates one and injects
+ * structurally; P3's forceAtlas2, release and dispose plus P7's seven algorithm members, each a delegation to
+ * its algorithm with `ctx.assertReady()` first. The accelerator's algorithm defaults are not consulted by any of
+ * them: only `betweenness` has any, and it belongs to P9. One per call (the app creates one and injects
  * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
  * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
  * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);

package/dist/src/accelerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accelerator.d.ts","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA2DtF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CA8B/F"}
+{"version":3,"file":"accelerator.d.ts","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAsEtF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CA2G/F"}

package/dist/src/accelerator.js

@@ -1,12 +1,16 @@
 /**
  * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
  * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
- * src/types/accelerator.ts until W1, D27). At P3 it carries `forceAtlas2`, `release` and `dispose` and nothing
- * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.pageRank !== undefined` and
- * route to the CPU when the member is absent (spec 2.4 row "method missing"), so a method the GPU does not
- * implement must not exist here -- never a throwing stub. The algorithm members arrive one per shipped algorithm
- * from P7; `fruchtermanReingold` / `springElectrical` with P5.
+ * src/types/accelerator.ts until W1, D27). It carries P3's `forceAtlas2`, `release` and `dispose` and P7's seven
+ * algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and nothing else: the CPU-side dispatchers (`accelerated()`,
+ * `createSimulation()`) test `acc.betweennessCentrality !== undefined` and route to the CPU when the member is
+ * absent (spec 2.4 row "method missing"), so a method the GPU does not implement must not exist here -- never a
+ * throwing stub. The remaining algorithm members arrive one per shipped algorithm from P8; `fruchtermanReingold` /
+ * `springElectrical` with P5.
  */
+import { connectedComponents } from "./algorithms/components.js";
+import { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
+import { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 import { createForceAtlas2 } from "./layouts/forceatlas2.js";
 /**
  * Frozen copy of the betweenness defaults; `sources` is copied into a fresh frozen array so a later mutation of
@@ -56,7 +60,9 @@ function freezeOptions(options) {
 }
 /**
  * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
- * structurally; at P3 it carries forceAtlas2, release and dispose. One per call (the app creates one and injects
+ * structurally; P3's forceAtlas2, release and dispose plus P7's seven algorithm members, each a delegation to
+ * its algorithm with `ctx.assertReady()` first. The accelerator's algorithm defaults are not consulted by any of
+ * them: only `betweenness` has any, and it belongs to P9. One per call (the app creates one and injects
  * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
  * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
  * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
@@ -83,6 +89,79 @@ export function createAccelerator(ctx, options) {
             ctx.assertReady();
             return createForceAtlas2(ctx, { ...o, ...frozen.layout });
         },
+        /**
+         * PageRank on the device (spec 8.2; contract 3.14).
+         * @param gs - the snapshot
+         * @param o - the CPU option record (spec 9.2 PageRankOptions)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         */
+        async pageRank(gs, o) {
+            ctx.assertReady();
+            return await pageRank(ctx, gs, o);
+        },
+        /**
+         * Personalized PageRank on the device (spec 8.2; contract 3.14). The mirror admits an f64 personalization
+         * (spec 9.2 `F32 | F64`); the kernel reads f32, so an f64 vector is narrowed on the host first.
+         * @param gs - the snapshot
+         * @param personalization - one finite non-negative mass per node, not all zero
+         * @param o - the CPU option record (spec 9.2 PageRankOptions)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         */
+        async personalizedPageRank(gs, personalization, o) {
+            ctx.assertReady();
+            const mass = personalization instanceof Float32Array ? personalization : Float32Array.from(personalization);
+            return await personalizedPageRank(ctx, gs, mass, o);
+        },
+        /**
+         * HITS hubs and authorities on the device (spec 8.2; contract 3.14).
+         * @param gs - the snapshot
+         * @param o - the CPU option record (spec 9.2 HitsOptions)
+         * @returns hubs and authorities with `precision: "f32"` (spec 9.7)
+         */
+        async hits(gs, o) {
+            ctx.assertReady();
+            return await hits(ctx, gs, o);
+        },
+        /**
+         * Eigenvector centrality on the device (spec 8.2; contract 3.14).
+         * @param gs - the snapshot
+         * @param o - the CPU option record (spec 9.2 EigenvectorOptions)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         */
+        async eigenvectorCentrality(gs, o) {
+            ctx.assertReady();
+            return await eigenvectorCentrality(ctx, gs, o);
+        },
+        /**
+         * Katz centrality on the device (spec 8.2; contract 3.14).
+         * @param gs - the snapshot
+         * @param o - the CPU option record (spec 9.2 KatzOptions)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         */
+        async katzCentrality(gs, o) {
+            ctx.assertReady();
+            return await katzCentrality(ctx, gs, o);
+        },
+        /**
+         * Weakly connected components on the device (spec 8.3; contract 3.14): WCC semantics on directed input.
+         * @param gs - the snapshot
+         * @param o - `renumber` (default true); the mirror passes none
+         * @returns the labels, the count and groups() (spec 9.7 LabelResultLike)
+         */
+        async connectedComponents(gs, o) {
+            ctx.assertReady();
+            return await connectedComponents(ctx, gs, o);
+        },
+        /**
+         * The same algorithm as `connectedComponents` under the mirror's other name (spec 3.3, 9.2).
+         * @param gs - the snapshot
+         * @param o - `renumber` (default true); the mirror passes none
+         * @returns the labels, the count and groups() (spec 9.7 LabelResultLike)
+         */
+        async weaklyConnectedComponents(gs, o) {
+            ctx.assertReady();
+            return await connectedComponents(ctx, gs, o);
+        },
         /**
          * Destroys every device buffer recorded for the snapshot (spec 4.5); delegates to ctx.release.
          * @param s - the snapshot the app is done with

package/dist/src/accelerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"accelerator.js","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAW7D;;;;;GAKG;AACH,SAAS,eAAe,CAAC,QAA6B;IAClD,MAAM,IAAI,GAAwE,EAAE,GAAG,QAAQ,EAAE,CAAC;IAClG,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,UAA6B;IACjD,MAAM,IAAI,GAAsD,EAAE,GAAG,UAAU,EAAE,CAAC;IAClF,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,OAAuC;IAC1D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,GAAyF,EAAE,GAAG,OAAO,EAAE,CAAC;IAClH,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAe,EAAE,OAA4B;IAC3E,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO;QACH,IAAI,EAAE,QAAQ;QACd,GAAG;QACH,OAAO,EAAE,MAAM;QACf;;;;WAIG;QACH,WAAW,CAAC,CAAsB;YAC9B,GAAG,CAAC,WAAW,EAAE,CAAC;YAClB,OAAO,iBAAiB,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD;;;WAGG;QACH,OAAO,CAAC,CAAgB;YACpB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;QACD;;WAEG;QACH,OAAO;YACH,GAAG,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"accelerator.js","sourceRoot":"","sources":["../../src/accelerator.ts"],"names":[],"mappings":"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"}

package/dist/src/algorithms/components.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Weakly connected components on the device (spec 8.3, 3.3): Afforest from GAP's cc.cc, step for step. `comp[v] = v`
+ * by `fill` mode 1; two sampled link rounds over the r-th out-neighbour of every row plus a compress (one batch, no
+ * readback); a 1,024-vertex label sample the host takes the mode of, which is the giant component (PD-12); then
+ * each-edge-once link rounds over `edgeList()` -- correct for directed and undirected input alike, which is what
+ * makes the partition the WEAK one -- in batches of four `link + compress` pairs, ONE readback of the changed flag per
+ * batch, until the flag stays 0; a final compress; readback; `renumberPartition` on the host in first-seen order so
+ * the labels are IDENTICAL to the CPU's (spec 9.7), or the raw roots when `renumber: false`.
+ *
+ * PLAN DECISION PD-4: the changed flag is the word at `comp[n]`, so the link kernels bind three buffers (design 8.10).
+ * PLAN DECISION PD-11: `E_PARTITION` is NOT a pass-through. The kernels only ever store a value read out of `comp`,
+ * which `fill` seeded with `v < n`, so no label can be `INVALID_INDEX`; the host verifies every label is `< n` before
+ * `renumberPartition` sees it and raises `E_VALIDATION { label: "connectedComponents/labels" }` if that ever fails --
+ * it would mean a GPU bug, which no caller could act on as `E_PARTITION`.
+ * DEP-M8B-C: no `dedupe` primitive; Afforest's link is idempotent, so a repeated edge is a no-op.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { type ComponentsOptions, type GpuLabelResult } from "../types/algorithms.js";
+import { type GpuRunOptions } from "../types/run.js";
+/**
+ * Weakly connected components on the device (spec 3.3, 8.3): Afforest over the resident core and the edge list;
+ * labels dense in first-seen order (`renumber: true`, the default) or the raw roots (`renumber: false`).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - renumber (default true), plus dest / signal / onProgress
+ * @returns the labels, the component count and groups()
+ */
+export declare function connectedComponents(ctx: GpuContext, s: GraphSnapshot, options?: ComponentsOptions & GpuRunOptions): Promise<GpuLabelResult>;
+//# sourceMappingURL=components.d.ts.map

package/dist/src/algorithms/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../../src/algorithms/components.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,aAAa,EAA+B,MAAM,uBAAuB,CAAC;AAGxF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAMhD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAErF,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA6JrD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACrC,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,GAC5C,OAAO,CAAC,cAAc,CAAC,CAsJzB"}

package/dist/src/algorithms/components.js

@@ -0,0 +1,300 @@
+/**
+ * Weakly connected components on the device (spec 8.3, 3.3): Afforest from GAP's cc.cc, step for step. `comp[v] = v`
+ * by `fill` mode 1; two sampled link rounds over the r-th out-neighbour of every row plus a compress (one batch, no
+ * readback); a 1,024-vertex label sample the host takes the mode of, which is the giant component (PD-12); then
+ * each-edge-once link rounds over `edgeList()` -- correct for directed and undirected input alike, which is what
+ * makes the partition the WEAK one -- in batches of four `link + compress` pairs, ONE readback of the changed flag per
+ * batch, until the flag stays 0; a final compress; readback; `renumberPartition` on the host in first-seen order so
+ * the labels are IDENTICAL to the CPU's (spec 9.7), or the raw roots when `renumber: false`.
+ *
+ * PLAN DECISION PD-4: the changed flag is the word at `comp[n]`, so the link kernels bind three buffers (design 8.10).
+ * PLAN DECISION PD-11: `E_PARTITION` is NOT a pass-through. The kernels only ever store a value read out of `comp`,
+ * which `fill` seeded with `v < n`, so no label can be `INVALID_INDEX`; the host verifies every label is `< n` before
+ * `renumberPartition` sees it and raises `E_VALIDATION { label: "connectedComponents/labels" }` if that ever fails --
+ * it would mean a GPU bug, which no caller could act on as `E_PARTITION`.
+ * DEP-M8B-C: no `dedupe` primitive; Afforest's link is idempotent, so a repeated edge is a no-op.
+ */
+import { renumberPartition } from "@graphty/graph-format";
+import { U32_MAX } from "../constants.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
+import { FILL_PARAMS, graphBindings, graphOverrides, kernelSpec, WCC_PARAMS } from "../kernels.js";
+import { algorithmScope } from "./scope.js";
+const ALGORITHM = "connectedComponents";
+/** Link rounds between two reads of the changed flag (design 8.3: "checked every 4 rounds"). */
+const ROUNDS_PER_BATCH = 4;
+/** The edge-round cap; the flag not settling by then is a hard error, never a fallback. */
+const MAX_WCC_ROUNDS = 64;
+/** The sampled vertices the giant component is found from (design 8.3). */
+const SAMPLE_SIZE = 1024;
+/** The bound of a CAS retry loop and of a compress walk (PD-5). */
+const MAX_STEPS = 1024;
+/** Params slots of the largest batch: four link + four compress blocks; the setup batch uses fill + 2 links + compress. */
+const RING_SLOTS = 2 * ROUNDS_PER_BATCH;
+/**
+ * Validates `options.dest` for a label result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @returns the destination as a U32, or null when none was given
+ */
+function checkDest(dest, n) {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Uint32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest;
+    }
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${ALGORITHM}: dest must be a Uint32Array of length ${n} over an ArrayBuffer`, {
+        argument: "dest",
+        value: `${dest.constructor.name}(${dest.length})`,
+        expected: `Uint32Array(${n}) over an ArrayBuffer`,
+    });
+}
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @returns the core binding
+ */
+function coreOf(ctx, s) {
+    try {
+        return ctx.residency.core(s);
+    }
+    catch (error) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError("E_TOO_LARGE", `${ALGORITHM}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`, { ...error.details, algorithm: ALGORITHM });
+        }
+        throw error;
+    }
+}
+/**
+ * Whole-buffer binding of a scratch buffer over its first `size` bytes.
+ * @param buffer - the buffer
+ * @param size - the bound byte length
+ * @returns the binding
+ */
+function bindingOf(buffer, size) {
+    return { buffer, offset: 0, size, window: null };
+}
+/**
+ * The result object over a label array whose labels are all `< n`: `count` blocks, `groups()` built lazily once in
+ * first-seen label order (which for renumbered labels is index order).
+ * @param labels - the labels
+ * @param count - the block count
+ * @returns the result
+ */
+function labelResult(labels, count) {
+    let groups = null;
+    return {
+        labels,
+        count,
+        groups() {
+            if (groups !== null) {
+                return groups;
+            }
+            const n = labels.length;
+            const dense = new Uint32Array(n).fill(U32_MAX);
+            const sizes = new Uint32Array(count);
+            let next = 0;
+            for (let v = 0; v < n; v++) {
+                let k = dense[labels[v]];
+                if (k === U32_MAX) {
+                    k = next++;
+                    dense[labels[v]] = k;
+                }
+                sizes[k]++;
+            }
+            const built = Array.from(sizes, (size) => new Uint32Array(size));
+            const filled = new Uint32Array(count);
+            for (let v = 0; v < n; v++) {
+                const k = dense[labels[v]];
+                built[k][filled[k]++] = v;
+            }
+            groups = built;
+            return built;
+        },
+    };
+}
+/**
+ * The mode of the sampled labels (GAP's SampleFrequentElement, counted on the host; PD-12).
+ * @param sample - the sampled labels
+ * @returns the most frequent label
+ */
+function modeOf(sample) {
+    const counts = new Map();
+    let best = sample[0];
+    let bestCount = 0;
+    for (const label of sample) {
+        const c = (counts.get(label) ?? 0) + 1;
+        counts.set(label, c);
+        if (c > bestCount) {
+            best = label;
+            bestCount = c;
+        }
+    }
+    return best;
+}
+/**
+ * Verifies every label is a node index (so `renumberPartition` can never see `INVALID_INDEX`, PD-11) and counts the
+ * distinct roots.
+ * @param raw - the labels the device produced
+ * @returns the number of distinct labels
+ */
+function checkLabels(raw) {
+    const n = raw.length;
+    const seen = new Uint8Array(n);
+    let count = 0;
+    for (let v = 0; v < n; v++) {
+        const label = raw[v];
+        if (label >= n) {
+            throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: labels[${v}] = ${label} is not a node index`, {
+                label: `${ALGORITHM}/labels`,
+                message: `the device produced a label outside [0, ${n})`,
+            });
+        }
+        if (seen[label] === 0) {
+            seen[label] = 1;
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Weakly connected components on the device (spec 3.3, 8.3): Afforest over the resident core and the edge list;
+ * labels dense in first-seen order (`renumber: true`, the default) or the raw roots (`renumber: false`).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - renumber (default true), plus dest / signal / onProgress
+ * @returns the labels, the component count and groups()
+ */
+export async function connectedComponents(ctx, s, options) {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const renumber = options?.renumber !== false;
+    const dest = checkDest(options?.dest, n);
+    if (options?.signal?.aborted) {
+        throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted before any work started`, {});
+    }
+    if (n === 0) {
+        options?.onProgress?.(1, 1);
+        return labelResult(dest ?? new Uint32Array(0), 0);
+    }
+    const core = coreOf(ctx, s);
+    if (s.arcCount === 0) {
+        // every node is its own block, and the identity is already first-seen dense: renumbered and raw agree
+        const labels = dest ?? new Uint32Array(n);
+        for (let v = 0; v < n; v++) {
+            labels[v] = v;
+        }
+        options?.onProgress?.(1, 1);
+        return labelResult(labels, n);
+    }
+    const edges = ctx.residency.view(s, "edgeList");
+    const edgeCount = edges.scalars.edgeCount[0];
+    const scope = algorithmScope(ctx, ALGORITHM, RING_SLOTS);
+    try {
+        const compBytes = 4 * (n + 1);
+        const comp = scope.scratch(compBytes, "comp");
+        const items = Math.min(SAMPLE_SIZE, n);
+        const hist = scope.scratch(4 * items, "hist");
+        await ctx.allocator.check();
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill", {}));
+        const linkSample = await ctx.pipelines.kernel(kernelSpec("wcc-link-sample", graphOverrides(core, null)));
+        const linkEdges = await ctx.pipelines.kernel(kernelSpec("wcc-link-edges", {}));
+        const compress = await ctx.pipelines.kernel(kernelSpec("wcc-compress", {}));
+        const sample = await ctx.pipelines.kernel(kernelSpec("wcc-sample", {}));
+        const { queue } = ctx.device;
+        const compBinding = bindingOf(comp, compBytes);
+        const histBinding = bindingOf(hist, 4 * items);
+        const rowPlan = planGridStride(n, ctx.workgroupSize, ctx.caps);
+        const edgePlan = planGridStride(edgeCount, ctx.workgroupSize, ctx.caps);
+        const flagIndex = n;
+        const zero = new Uint32Array(1);
+        const wccParams = (fields) => scope.params(WCC_PARAMS, { n, ...fields, flagIndex, maxSteps: MAX_STEPS, pad0: 0 });
+        const recordCompress = (pass) => {
+            const params = wccParams({ items: n, stride: rowPlan.stride ?? n, r: 0, giant: U32_MAX });
+            compress.dispatch(pass, compress.bind({ comp: compBinding, P: params.binding }), rowPlan, [params.offset]);
+        };
+        const submit = (batch) => {
+            scope.flush();
+            return batch.submit();
+        };
+        // batch 1: comp[v] = v, the flag cleared, two sampled link rounds over the r-th out-neighbour, one compress
+        queue.writeBuffer(comp, 4 * flagIndex, zero);
+        const setup = new CommandBatch(ctx, `${ALGORITHM}/setup`);
+        let pass = setup.pass("sample-rounds");
+        const fillParams = scope.params(FILL_PARAMS, { count: n, value: 0, mode: 1, pad0: 0 });
+        fill.dispatch(pass, fill.bind({ dst: bindingOf(comp, 4 * n), P: fillParams.binding }), plan1d(n, ctx.workgroupSize, ctx.caps), [fillParams.offset]);
+        const graph = graphBindings(core, null);
+        for (let r = 0; r < 2; r++) {
+            const params = wccParams({ items: n, stride: rowPlan.stride ?? n, r, giant: U32_MAX });
+            const bound = linkSample.bind({ ...graph, comp: compBinding, P: params.binding });
+            linkSample.dispatch(pass, bound, rowPlan, [params.offset]);
+        }
+        recordCompress(pass);
+        setup.endPass();
+        await submit(setup).readback;
+        ctx.assertReady();
+        // batch 2: the label sample, whose mode is the giant component
+        const sampler = new CommandBatch(ctx, `${ALGORITHM}/sample`);
+        pass = sampler.pass("sample");
+        const sampleParams = wccParams({ items, stride: 0, r: 0, giant: U32_MAX });
+        sample.dispatch(pass, sample.bind({ comp: compBinding, hist: histBinding, P: sampleParams.binding }), plan1d(items, ctx.workgroupSize, ctx.caps), [sampleParams.offset]);
+        sampler.endPass();
+        const histRequest = sampler.readback(hist, 0, 4 * items);
+        const histBytes = await submit(sampler).readback;
+        ctx.assertReady();
+        const giant = modeOf(new Uint32Array(histBytes, histRequest.offset, items));
+        // the edge rounds: four (link + compress) per batch, one readback of the changed flag per batch
+        const edgeBindings = { edgeSrc: edges.bindings.src, edgeDst: edges.bindings.dst, comp: compBinding };
+        let rounds = 0;
+        for (;;) {
+            queue.writeBuffer(comp, 4 * flagIndex, zero);
+            const batch = new CommandBatch(ctx, `${ALGORITHM}/rounds`);
+            pass = batch.pass("edge-rounds");
+            for (let i = 0; i < ROUNDS_PER_BATCH; i++) {
+                const params = wccParams({ items: edgeCount, stride: edgePlan.stride ?? edgeCount, r: 0, giant });
+                const bound = linkEdges.bind({ ...edgeBindings, P: params.binding });
+                linkEdges.dispatch(pass, bound, edgePlan, [params.offset]);
+                recordCompress(pass);
+            }
+            batch.endPass();
+            const flagRequest = batch.readback(comp, 4 * flagIndex, 4);
+            const submitted = submit(batch);
+            const back = await submitted.readback;
+            rounds += ROUNDS_PER_BATCH;
+            ctx.assertReady();
+            if (options?.signal?.aborted) {
+                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, { batchId: submitted.id });
+            }
+            if (new Uint32Array(back, flagRequest.offset, 1)[0] === 0) {
+                break;
+            }
+            if (rounds >= MAX_WCC_ROUNDS) {
+                throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: the changed flag never settled in ${MAX_WCC_ROUNDS} rounds`, { label: ALGORITHM, message: `the changed flag never settled in ${MAX_WCC_ROUNDS} rounds` });
+            }
+        }
+        // the final compress, then the labels
+        const final = new CommandBatch(ctx, `${ALGORITHM}/final`);
+        recordCompress(final.pass("compress"));
+        final.endPass();
+        await submit(final).readback;
+        ctx.assertReady();
+        const raw = !renumber && dest !== null ? dest : new Uint32Array(n);
+        await ctx.readback.read(comp, 4 * n, raw);
+        ctx.assertReady();
+        const distinct = checkLabels(raw);
+        options?.onProgress?.(1, 1);
+        if (!renumber) {
+            return labelResult(raw, distinct);
+        }
+        const { labels, count } = renumberPartition(raw, dest ?? undefined);
+        return labelResult(labels, count);
+    }
+    finally {
+        scope.dispose();
+    }
+}
+//# sourceMappingURL=components.js.map

package/dist/src/algorithms/components.js.map

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

package/dist/src/algorithms/pagerank.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PageRank and personalized PageRank on the device (spec 8.2, 3.3): a pull over the reverse adjacency with the
+ * out-weight normaliser folded into `xNorm` by `pr-scale`, the dangling mass and the L1 delta folded by
+ * `pr-finalize` into the header at `partials[0]`, and `spmv-pull` writing the next iterate. Iterations run in
+ * batches of PR_BATCH per submit, ONE readback per batch (the header and the iterate together), and the device
+ * records `firstConverged` the first time the delta falls below `tolerance * n`, so the reported `iterations` is the
+ * first converged iteration and not the batch boundary (spec 9.7).
+ *
+ * PLAN DECISION PD-7: the ping-pong is TWO buffers (`rankA`, `rankB`) alternated through two cached bind groups;
+ * one buffer of two aliased halves would bind (each kernel sees the halves in one access mode) but saves nothing.
+ * PLAN DECISION PD-8: `outWeightSum` is call scratch from the Lease, one `segmentedReduce` pass per call.
+ * PLAN DECISION PD-9: `pr-scale` at iteration i reads x(i-1) and x(i-2), so its delta is the error of iteration
+ * i - 1 and `pr-finalize` records `P.iteration - 1`; the ping-pong supplies `rankPrev` for free because it is the
+ * buffer this iteration overwrites, and `pr-scale` runs before `spmv-pull` in the same pass.
+ */
+import { type F32, type GraphSnapshot } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { type GpuPageRankResult, type PageRankOptions } from "../types/algorithms.js";
+import { type GpuRunOptions } from "../types/run.js";
+/**
+ * PageRank on the device (spec 3.3, 8.2): NetworkX semantics, f32 scores, `iterations` the first converged
+ * iteration (spec 9.7).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export declare function pageRank(ctx: GpuContext, s: GraphSnapshot, options?: PageRankOptions & GpuRunOptions): Promise<GpuPageRankResult>;
+/**
+ * Personalized PageRank on the device (spec 3.3, 8.2): the personalization vector replaces the uniform 1 / n in
+ * the teleport and the dangling redistribution; it is normalised to sum 1 on the host.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param personalization - one finite non-negative mass per node, not all zero
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export declare function personalizedPageRank(ctx: GpuContext, s: GraphSnapshot, personalization: F32, options?: PageRankOptions & GpuRunOptions): Promise<GpuPageRankResult>;
+//# sourceMappingURL=pagerank.d.ts.map

package/dist/src/algorithms/pagerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagerank.d.ts","sourceRoot":"","sources":["../../../src/algorithms/pagerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAShD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEtF,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA+PrD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACpB,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,OAAO,CAAC,EAAE,eAAe,GAAG,aAAa,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACtC,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,eAAe,EAAE,GAAG,EACpB,OAAO,CAAC,EAAE,eAAe,GAAG,aAAa,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}