@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.5

package/dist/src/algorithms/closeness.js

@@ -0,0 +1,323 @@
+/**
+ * Closeness centrality on the device (design 8.4, 3.3 line 810, 9.7; P8-T11, the P8 plan's PD-13 / PD-19 / PD-25 /
+ * DEP-P8-E / DEP-P8-F): `score[s] = 1 / sumDist_s`, with `sumDist_s` the exact sum of the finite distances from `s`
+ * to every OTHER node -- an unreached node adds nothing -- and `0` when nothing is reached. No reached factor and no
+ * Wasserman-Faust scaling: this is EXACTLY the legacy default (`normalized: false`) of `closenessCentrality` in
+ * `@graphty/algorithms`, the number graphty-element's closeness panel shows today, so a future `indexed` port has one
+ * number to match (the NetworkX form is 33x it on karate and could never have been substituted silently).
+ *
+ * The unweighted route is ONE bit-parallel multi-source search per batch of 32 sources (`ceil(n / 32)` batches):
+ * the batch's state is one `bits` buffer of four regions of `bitsBase = roundUp(n, 64)` words (`visited`, two
+ * frontier regions that swap by the level's parity, `flags`), bit `s` of word `v` meaning "source `s` has reached /
+ * is at / is next at `v`"; a level is, all host-recorded, `closeness-reduce` role 0 (the boundary: `done` from the
+ * previous level's compacted count, the level's claims folded into the exact 64-bit per-source sums at `level + 1`),
+ * `compact` of the flags into the frontier list, two `fill`s zeroing the level's next region and the flags (AFTER
+ * the compaction that consumed them), and `closeness-sweep` (the block-mapped expansion with the claim inline, a
+ * direct grid-stride dispatch looping to the list's count). `MAX_LEVELS_PER_SUBMIT` levels per submit and
+ * one readback per submit (the `done` word and the 512-byte `perSource` block together, so the finished batch needs
+ * no extra map); the host folds `sumHi x 2^32 + sumLo` into `1 / sum` in f64 and stores f32. The weighted route
+ * (`weighted` true on a snapshot whose column is not all ones) is one `sssp` per source with the sums reduced on the
+ * host between calls: design 8.4's own answer, slow and correct. `weighted` defaults to the snapshot's `flags.weighted`;
+ * `weighted: false` on a weighted snapshot ignores the column by request and sweeps; `weighted: true` over unit
+ * weights or no column sweeps too (every `sssp` would route to a BFS anyway). `maxIterations` and `tolerance` are the
+ * seam's placeholder keys and an exact traversal has neither, so a defined value is REFUSED before any device work
+ * (`E_UNSUPPORTED { option }`, the package's rule for an option it does not implement, PD-25); `undefined` is legal.
+ * `iterations` reports the source batches run (the sources, on the weighted route), `converged` is always true.
+ *
+ * Cost, stated so nobody is surprised: closeness is O(n x m) on any device -- at 1M nodes it is 31,250 batches of a
+ * full multi-source traversal, minutes on the card, and no target in design 10.4 asks for less. `compact.record`
+ * leases its offsets and the scan's block sums afresh on every call, once per LEVEL here, so the planner is given a
+ * scope whose `scratch` hands the same buffer back for the same label and size: the dispatches of one pass run in
+ * order, a level's scan overwrites the previous level's, and the run holds one set instead of `levels x batches`.
+ * The sweep keeps DEP-P8-E's refusal of a windowed core (`assertWholeCore`): the bit-parallel claim needs the whole
+ * arc array bound. The tuning entry `closenessWithTuning` (PD-26's shape) is what the tests drive; nothing public
+ * exposes it.
+ */
+import { MAX_LEVELS_PER_SUBMIT } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d, planGridStride } from "../kernel/dispatch.js";
+import { FILL_PARAMS, FRONTIER_COUNTERS, FRONTIER_PARAMS, graphBindings, graphOverrides, kernelSpec, } from "../kernels.js";
+import { prepareCompact } from "../primitives/compact.js";
+import { assertWholeCore } from "../primitives/core-shape.js";
+import { W } from "../primitives/frontier.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { algorithmScope } from "./scope.js";
+import { aborted, bindingOf, checkDest, sssp } from "./sssp.js";
+const ALGORITHM = "closenessCentrality";
+/**
+ * Design 8.4: 32 sources per `u32` word, one batch per word.
+ * @internal
+ */
+export const SOURCES_PER_BATCH = 32;
+/**
+ * The `perSource` block of a batch: `newCount[32]` @0, `reached[32]` @32, `sumLo[32]` @64, `sumHi[32]` @96.
+ * @internal
+ */
+export const PER_SOURCE_WORDS = 4 * SOURCES_PER_BATCH;
+/**
+ * Params slots of the ring, COUNTED (`UniformRing.reserve` wraps silently): per level `compact`'s records (its scan
+ * is at most four levels for any n below 2^32, so at most 8 records) while the boundary, the finalize, the fill and
+ * the two sweep records (one per parity) are written once per submit, plus the seed's two records on a batch's first
+ * submit (the iota fill flushes in its own submit).
+ */
+const RING_SLOTS = 8 * MAX_LEVELS_PER_SUBMIT + 16;
+/**
+ * A scope whose `scratch` hands the SAME buffer back for the same label and size (see the file comment).
+ * @param scope - the algorithm's scope
+ * @returns the reusing scope
+ */
+function reusingScratch(scope) {
+    const held = new Map();
+    return {
+        ...scope,
+        scratch: (byteLength, label) => {
+            const key = `${label}/${byteLength}`;
+            let buffer = held.get(key);
+            if (buffer === undefined) {
+                buffer = scope.scratch(byteLength, label);
+                held.set(key, buffer);
+            }
+            return buffer;
+        },
+    };
+}
+/**
+ * The weighted route: one `sssp` per source, the sums reduced on the host.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param scores - the destination
+ * @param options - the run options
+ * @returns the result
+ */
+async function weightedRoute(ctx, s, scores, options) {
+    const n = s.nodeCount;
+    for (let source = 0; source < n; source++) {
+        if (options?.signal?.aborted) {
+            throw aborted(ALGORITHM);
+        }
+        const { dist } = await sssp(ctx, s, source, { signal: options?.signal });
+        let sum = 0;
+        for (let v = 0; v < n; v++) {
+            const d = dist[v];
+            if (v !== source && d !== Infinity) {
+                sum += d;
+            }
+        }
+        scores[source] = sum === 0 ? 0 : 1 / sum;
+        options?.onProgress?.(source + 1, n);
+    }
+    return { scores, iterations: n, converged: true, precision: "f32" };
+}
+/**
+ * The bit-parallel route (see the file comment).
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param scores - the destination
+ * @param levelsPerSubmit - the submit cadence
+ * @param options - the run options
+ * @param tuning - the knobs
+ * @returns the result
+ */
+async function sweepRoute(ctx, s, scores, levelsPerSubmit, options, tuning) {
+    const n = s.nodeCount;
+    if (n === 0) {
+        return { scores, iterations: 0, converged: true, precision: "f32" };
+    }
+    const core = ctx.residency.core(s);
+    assertWholeCore(core, s.arcCount, ctx.caps.limits.maxStorageBufferBindingSize, ALGORITHM);
+    const scope = algorithmScope(ctx, ALGORITHM, RING_SLOTS);
+    try {
+        const wg = ctx.workgroupSize;
+        const bytes = 4 * n;
+        // the four regions of the bits buffer, each bitsBase words so its byte offset is 256-aligned and fill and
+        // compact can bind one alone: visited 0, the frontier pair 1 and 2, flags 3
+        const bitsBase = Math.ceil(n / 64) * 64;
+        const regionBytes = 4 * bitsBase;
+        const bits = bindingOf(scope.scratch(4 * regionBytes, "bits"), 4 * regionBytes);
+        const region = (index) => ({
+            buffer: bits.buffer,
+            offset: index * regionBytes,
+            size: regionBytes,
+            window: null,
+        });
+        const flags = region(3);
+        const frontierList = bindingOf(scope.scratch(bytes, "frontier-list"), bytes);
+        const iota = bindingOf(scope.scratch(bytes, "iota"), bytes);
+        const counters = bindingOf(scope.scratch(FRONTIER_COUNTERS.byteLength, "counters"), FRONTIER_COUNTERS.byteLength);
+        const perSourceBytes = 4 * PER_SOURCE_WORDS;
+        const perSource = bindingOf(scope.scratch(perSourceBytes, "per-source"), perSourceBytes);
+        await ctx.allocator.check();
+        const compact = await prepareCompact(reusingScratch(scope));
+        const sweep = await ctx.pipelines.kernel(kernelSpec("closeness-sweep", graphOverrides(core, null)));
+        const reduce = await ctx.pipelines.kernel(kernelSpec("closeness-reduce"));
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+        const graph = graphBindings(core, null);
+        const onePlan = plan1d(1, wg, ctx.caps);
+        const regionPlan = plan1d(bitsBase, wg, ctx.caps);
+        const sweepPlan = planGridStride(n, wg, ctx.caps); // the list holds at most n entries; the sweep loops to the count word
+        const recordFill = (pass, dst, count, mode) => {
+            const params = scope.params(FILL_PARAMS, { count, value: 0, mode, pad0: 0 });
+            fill.dispatch(pass, fill.bind({ dst, P: params.binding }), plan1d(count, wg, ctx.caps), [params.offset]);
+        };
+        const submit = (batch) => {
+            scope.flush();
+            return batch.submit();
+        };
+        // setup: the iota queue compact reads, once per run
+        const setup = new CommandBatch(ctx, `${ALGORITHM}/setup`);
+        recordFill(setup.pass("fill"), iota, n, 1);
+        setup.endPass();
+        await submit(setup).readback;
+        ctx.assertReady();
+        let batches = 0;
+        for (let batchStart = 0; batchStart < n; batchStart += SOURCES_PER_BATCH) {
+            let level = 0;
+            for (let first = true;; first = false) {
+                const batch = new CommandBatch(ctx, `${ALGORITHM}/levels`);
+                const pass = batch.pass("closeness");
+                if (first) {
+                    // the batch's seed: the four regions and the block zeroed, then role 1 (the sources' bits, their
+                    // flags, counters[0] = k, level = U32_MAX)
+                    recordFill(pass, bits, 4 * bitsBase, 0);
+                    recordFill(pass, perSource, PER_SOURCE_WORDS, 0);
+                    const seed = scope.params(FRONTIER_PARAMS, { role: 1, n, bitsBase, source: batchStart });
+                    reduce.dispatch(pass, reduce.bind({ counters, perSource, bits, P: seed.binding }), onePlan, [
+                        seed.offset,
+                    ]);
+                }
+                // the records every level of the submit shares (the ring wraps, so they are written per submit)
+                const boundary = scope.params(FRONTIER_PARAMS, { role: 0, n, bitsBase });
+                const boundBoundary = reduce.bind({ counters, perSource, bits, P: boundary.binding });
+                const clear = scope.params(FILL_PARAMS, { count: bitsBase, value: 0, mode: 0, pad0: 0 });
+                // parity 0 sweeps region 1 into region 2, parity 1 region 2 into region 1: the next region is cleared
+                const boundClearNext = [region(2), region(1)].map((dst) => fill.bind({ dst, P: clear.binding }));
+                const boundClearFlags = fill.bind({ dst: flags, P: clear.binding });
+                const boundSweep = [0, 1].map((mode) => {
+                    const params = scope.params(FRONTIER_PARAMS, {
+                        wg,
+                        n,
+                        bitsBase,
+                        arcBase: 0,
+                        arcEnd: s.arcCount,
+                        mode,
+                        stride: sweepPlan.stride ?? wg,
+                    });
+                    return {
+                        bound: sweep.bind({ ...graph, frontierList, counters, bits, perSource, P: params.binding }),
+                        offset: params.offset,
+                    };
+                });
+                for (let k = 0; k < levelsPerSubmit; k++, level++) {
+                    const parity = level % 2;
+                    reduce.dispatch(pass, boundBoundary, onePlan, [boundary.offset]);
+                    compact.record(pass, {
+                        queue: iota,
+                        flags,
+                        count: n,
+                        out: frontierList,
+                        outCount: counters,
+                        outIndex: W.frontierCount,
+                    });
+                    fill.dispatch(pass, boundClearNext[parity], regionPlan, [clear.offset]);
+                    fill.dispatch(pass, boundClearFlags, regionPlan, [clear.offset]);
+                    sweep.dispatch(pass, boundSweep[parity].bound, sweepPlan, [boundSweep[parity].offset]);
+                }
+                batch.endPass();
+                const doneRequest = batch.readback(counters.buffer, counters.offset + 4 * W.done, 4);
+                const blockRequest = batch.readback(perSource.buffer, perSource.offset, perSourceBytes);
+                const submitted = submit(batch);
+                const back = await submitted.readback;
+                ctx.assertReady();
+                if (options?.signal?.aborted) {
+                    throw aborted(ALGORITHM, submitted.id);
+                }
+                if (new Uint32Array(back, doneRequest.offset, 1)[0] !== 0) {
+                    const block = new Uint32Array(back, blockRequest.offset, PER_SOURCE_WORDS);
+                    const count = Math.min(SOURCES_PER_BATCH, n - batchStart);
+                    for (let i = 0; i < count; i++) {
+                        const sum = block[3 * SOURCES_PER_BATCH + i] * 2 ** 32 + block[2 * SOURCES_PER_BATCH + i];
+                        scores[batchStart + i] = sum === 0 ? 0 : 1 / sum;
+                    }
+                    tuning.onBatch?.(batchStart, block.slice());
+                    break;
+                }
+                if (level > n + 3) {
+                    // a batch claims at most n - 1 levels deep, then one level claims nothing and one is empty
+                    throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: the done flag never rose in ${level} levels of the batch at ${batchStart}`, { label: ALGORITHM, message: `the done flag never rose in ${level} levels` });
+                }
+            }
+            batches += 1;
+            options?.onProgress?.(Math.min(batchStart + SOURCES_PER_BATCH, n), n);
+        }
+        return { scores, iterations: batches, converged: true, precision: "f32" };
+    }
+    finally {
+        scope.dispose();
+    }
+}
+/**
+ * Closeness with the test knobs of PD-26's shape; `closenessCentrality` is this with an empty tuning.
+ * @internal
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - the seam's `HitsOptionsLike` (`weighted` honoured, the other two refused when defined), plus dest / signal / onProgress
+ * @param tuning - the knobs
+ * @returns the scores, the batches run, `converged: true` and `precision: "f32"`
+ */
+export async function closenessWithTuning(ctx, s, options, tuning) {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    for (const key of ["maxIterations", "tolerance"]) {
+        if (options?.[key] !== undefined) {
+            throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: ${key} has no meaning for an exact traversal`, {
+                option: key,
+                hint: "closeness is an exact traversal; the option has no meaning here",
+            });
+        }
+    }
+    const n = s.nodeCount;
+    const levelsPerSubmit = tuning.levelsPerSubmit ?? MAX_LEVELS_PER_SUBMIT;
+    if (!Number.isInteger(levelsPerSubmit) || levelsPerSubmit < 1 || levelsPerSubmit > MAX_LEVELS_PER_SUBMIT) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${ALGORITHM}: levelsPerSubmit must be an integer in [1, ${MAX_LEVELS_PER_SUBMIT}]`, {
+            argument: "levelsPerSubmit",
+            value: levelsPerSubmit,
+            expected: `an integer in [1, ${MAX_LEVELS_PER_SUBMIT}]`,
+        });
+    }
+    const scores = checkDest(ALGORITHM, options?.dest, n) ?? new Float32Array(n);
+    const weighted = options?.weighted ?? s.flags.weighted;
+    if (options?.signal?.aborted) {
+        throw aborted(ALGORITHM);
+    }
+    if (weighted && s.weights !== null && !s.flags.allWeightsOne) {
+        if (!s.flags.nonNegativeWeights) {
+            throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: a negative weight has no shortest-path distance to sum`, {
+                feature: "closenessCentrality.negativeWeights",
+                hint: "pass weighted: false to ignore the column",
+            });
+        }
+        if (!s.flags.finiteWeights) {
+            throw new WebGpuGraphError("E_UNSUPPORTED", `${ALGORITHM}: a NaN or infinite weight has no shortest path`, {
+                feature: "closenessCentrality.nonFiniteWeights",
+            });
+        }
+        return weightedRoute(ctx, s, scores, options);
+    }
+    return sweepRoute(ctx, s, scores, levelsPerSubmit, options, tuning);
+}
+/**
+ * Closeness centrality on the device (spec 3.3 line 810, design 8.4, 9.7): `scores[s] = 1 / sumDist_s` over the finite
+ * distances from `s` to every other node, `0` when nothing is reached -- the legacy default of `@graphty/algorithms`'
+ * `closenessCentrality`, unweighted by one bit-parallel multi-source search per 32 sources, weighted by one `sssp`
+ * per source; `weighted` defaults to the snapshot's flag, `maxIterations` / `tolerance` are refused when defined
+ * (PD-25). `iterations` is the source batches run and `converged` is always true.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - the seam's `HitsOptionsLike`, plus dest (a Float32Array of length n for `scores`) / signal / onProgress
+ * @returns the scores, the batches run, `converged: true` and `precision: "f32"`
+ */
+export function closenessCentrality(ctx, s, options) {
+    return closenessWithTuning(ctx, s, options, {});
+}
+//# sourceMappingURL=closeness.js.map

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

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

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

@@ -8,12 +8,14 @@
  */
 import { type GpuContext } from "../context.js";
 import { type ReduceScope } from "../primitives/reduce.js";
-/** A ReduceScope over a context plus the two lifecycle calls an algorithm makes: flush() before submit, dispose() in its finally. */
+/** A ReduceScope over a context plus the two lifecycle calls an algorithm makes: flush() before submit, dispose() in its finally. (The `indirect()` lease it once added for the frontier's args buffer went with that buffer, 2026-09-25.) */
 export interface AlgorithmScope extends ReduceScope {
     /** queue.writeBuffer of the params slots written since the last flush (called before the batch is submitted). */
     flush(): void;
     /** Destroys the ring and releases every scratch buffer of the lease; idempotent. */
     dispose(): void;
+    /** The ring's `overruns` so far: reservations that wrapped over a record the batch being recorded still reads (0 on a correctly sized ring; P8-T12). */
+    ringOverruns(): number;
 }
 /**
  * The scope of one algorithm call.

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

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/algorithms/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,qIAAqI;AACrI,MAAM,WAAW,cAAe,SAAQ,WAAW;IAC/C,iHAAiH;IACjH,KAAK,IAAI,IAAI,CAAC;IACd,oFAAoF;IACpF,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAuB5F"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/algorithms/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,8OAA8O;AAC9O,MAAM,WAAW,cAAe,SAAQ,WAAW;IAC/C,iHAAiH;IACjH,KAAK,IAAI,IAAI,CAAC;IACd,oFAAoF;IACpF,OAAO,IAAI,IAAI,CAAC;IAChB,wJAAwJ;IACxJ,YAAY,IAAI,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAwB5F"}

package/dist/src/algorithms/scope.js

@@ -36,6 +36,7 @@ export function algorithmScope(ctx, label, slots) {
             ring.destroy();
             lease.release();
         },
+        ringOverruns: () => ring.overruns,
     };
 }
 //# sourceMappingURL=scope.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../src/algorithms/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAWxD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAe,EAAE,KAAa,EAAE,KAAa;IACxE,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IAChF,OAAO;QACH,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,OAAO,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,YAAY,EAAE,CAAC;QAC5F,MAAM,CAAC,KAAK,EAAE,MAAM;YAChB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzE,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACR,IAAI,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACH,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,KAAK,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../src/algorithms/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAaxD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAe,EAAE,KAAa,EAAE,KAAa;IACxE,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IAChF,OAAO;QACH,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,OAAO,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,YAAY,EAAE,CAAC;QAC5F,MAAM,CAAC,KAAK,EAAE,MAAM;YAChB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzE,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACR,IAAI,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACH,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,KAAK,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;QACD,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ;KACpC,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,72 @@
+/**
+ * Weighted single-source shortest paths on the device (design 8.4, 3.3 line 808, 9.7; P8-T9, the P8 plan's PD-9 /
+ * PD-10 / PD-11 / PD-14 / PD-19 / PD-20 / PD-22 / PD-27 / DEP-P8-E): Davidson's near-far queue over the `Frontier`
+ * of P8-T4 with the `dedupe` of P8-T3, every per-round decision made ON THE DEVICE. `dist` is `array<atomic<u32>>`
+ * holding the f32 bit patterns of the distances (`F32_INF_BITS` = unreached), claimed by `atomicMin`, which is
+ * exact on non-negative floats (PD-9): the settled value is the minimum of a fixed set of f32 sums, so it is
+ * bitwise reproducible, bitwise identical across adapters, and bitwise equal to the f32 Dijkstra oracle.
+ *
+ * A round is eight recorded dispatches: `frontier-finalize` role 2 (the round boundary: a non-empty raw near half
+ * is deduped into `nearIn` for a near round; an empty one with a non-empty far half raises the threshold by the
+ * delta and dedupes the far half into `farIn` for a pass-through; both empty is `done`), `dedupe-claim` and
+ * `dedupe-filter` over each half (direct grid-stride dispatches; role 2 writes the chosen half's raw count into that
+ * dedupe's count word -- `edgeCount` for the near half, `edgeCountUnclamped` for the far one, two words SSSP borrows
+ * -- and 0 into the other's, so the half not chosen is a no-op), role 3 (restarts the raw half the round consumed),
+ * and `sssp-relax` twice (role 0 over `nearIn` sized by `frontierCount`, role 1 over `farIn` sized by `farCount`;
+ * the block's `path` word, 5 a near round and 6 a far one, makes the other role's dispatch a no-op). Nothing in a
+ * round is an indirect dispatch (2026-09-25). The far pile is re-bucketed by the
+ * relax kernel's pass-through, not by `compact` (PD-20): a far entry whose settled distance fell below the previous
+ * threshold was relaxed in the near band already and is dropped, the rest go back to near or far against the raised
+ * threshold. The near pile is ONE pile (no sub-partitions). The host records `MAX_LEVELS_PER_SUBMIT` rounds per
+ * submit and reads four bytes, the `done` word: 1 finished, 2 a raw half above its capacity (E_TOO_LARGE
+ * `sssp.pile`: the far half accumulates one entry per improving relaxation beyond the threshold across a bucket's
+ * near rounds and is deduped only at the split, so the refusal is reachable on a graph whose vertices improve many
+ * times inside one bucket), 3 the f32 threshold absorbed the delta (E_UNSUPPORTED `sssp.thresholdAbsorbed`). The
+ * rounds are at most `n + ceil(sum / delta) + 1` (each near round settles the pile's minimum, one pass-through per
+ * bucket), so more submits than that is E_VALIDATION, never a hang.
+ *
+ * The two routings (PD-22) are decided by the RUN's weight vector: `options.weights` when given (`arcCount` long or
+ * E_INVALID_ARGUMENT; narrowed to `Float32Array` when it is not one -- a `U32` or `I32` value above 2^24, or the
+ * bits of an `F64` value below the f32 ulp, is rounded silently, the package-wide f32 caveat and not a refusal --
+ * uploaded into a lease buffer and bound in the graph group's weights slot with `HAS_WEIGHTS` set even on an
+ * unweighted snapshot), else the snapshot's column, else none. A run whose vector is all ones, or has none, is the
+ * unit-weight BFS of P8-T6 with a depth cap derived from `cutoff` (`dv <= cutoff` on unit weights is
+ * `depth <= floor(cutoff)`), its `predArc` from `sssp-pred` in depth mode writing arc indices, `reachedCount` the
+ * visited count -- not a fallback, a better algorithm for the input. A negative weight is E_UNSUPPORTED
+ * `sssp.negativeWeights` (use bellmanFord), a non-finite one E_UNSUPPORTED `sssp.nonFiniteWeights` (the bit-pattern
+ * order is undefined for NaN); `cutoff: NaN` is E_INVALID_ARGUMENT, because the CPU port's `dv <= NaN` relaxes
+ * nothing while the kernel's `nd > NaN` guard would relax everything (PD-19). All host-side, before any device work.
+ * The delta is `SSSP_DELTA_FACTOR x avgWeight / avgDegree` over the vector in use (1 for an all-zero vector), seeded
+ * into the counters block as `deltaBits` and `thresholdBits`.
+ *
+ * `predArc` is a second pass over the settled distances (PD-11), never packed into the distance atomic: `sssp-pred`
+ * in `MODE 0` follows PD-27's plateau rule -- the smallest TIGHT arc whose source sits one key step below `v`, the
+ * key `(dist, hops)` with `hops` the plateau depth from a root -- through three roles over one buffer (the arcs,
+ * the hop counts, the changed word and the orphan word), so the chain strictly decreases the key, ends at the
+ * source, and is bitwise reproducible. A hop batch of `MAX_LEVELS_PER_SUBMIT` passes that still changed something
+ * is recorded again without the roots pass; a reached node the key never reached is a kernel bug (E_VALIDATION),
+ * never a result. The tuning entry `ssspWithTuning` (PD-26's shape) is what the tests drive; nothing public
+ * exposes it.
+ *
+ * The host-side helpers of the two routings (`resolveWeights`, `normaliseCutoff`, `checkDest`, `assertSource`,
+ * `unitWeightRoute`) and the predecessor pass (`predecessorPass`, both PD-27 keys) are shared with
+ * `bellman-ford.ts` (P8-T10), which is the same seam type over the same `SsspOptions`; they take the algorithm's
+ * name for their messages and are `@internal`.
+ */
+import { type GpuContext } from "../context.js";
+import { type SsspOptions } from "../types/accelerator.js";
+import { type GpuRunOptions } from "../types/run.js";
+import { type GpuSsspResult } from "../types/traversal.js";
+/**
+ * Single-source shortest paths on the device (spec 3.3 line 808, design 8.4, 9.7): `dist` in f32, bitwise equal to
+ * the f32 Dijkstra (PD-9), `predArc` a tight arc one PD-27 key step below each reached node (the chain always ends
+ * at the source), `reachedCount`; `cutoff` as the CPU port reads it (`dv <= cutoff`), `weights` a per-arc override
+ * of the snapshot's column for this run; a run with unit weights is the BFS (PD-22).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param source - the source node index (E_INVALID_ARGUMENT outside `[0, n)`)
+ * @param options - `cutoff` and `weights`, plus dest (a Float32Array of length n for `dist`) / signal / onProgress
+ * @returns the distances, the predecessor arcs and the reached count
+ */
+export declare function sssp(ctx: GpuContext, s: GraphSnapshot, source: number, options?: SsspOptions & GpuRunOptions): Promise<GpuSsspResult>;
+//# sourceMappingURL=sssp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sssp.d.ts","sourceRoot":"","sources":["../../../src/algorithms/sssp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAKH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAkBhD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA6pB3D;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAChB,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,GACtC,OAAO,CAAC,aAAa,CAAC,CAExB"}