@graphty/webgpu-graph-algorithms 0.6.23 → 0.6.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.23",
+  "version": "0.6.25",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -95,8 +95,8 @@
     "vite": "^7.0.5",
     "vitest": "4.1.11",
     "webgpu": "0.4.0",
-    "@graphty/layout": "^2.0.6",
-    "@graphty/algorithms": "^3.1.6"
+    "@graphty/algorithms": "^3.1.8",
+    "@graphty/layout": "^2.0.8"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",

package/src/algorithms/betweenness.ts

@@ -2,18 +2,31 @@
  * Betweenness and edge betweenness on the device (design 8.4 "Betweenness (A7)", 3.3 lines 811-812, 9.7): Brandes'
  * algorithm as McLaughlin-Bader run it, k sources at a time.
  *
- * A source batch keeps four `n x k` arrays -- `depthK`, `sigmaK` (u32 shortest-path counts), `deltaK` (f32
- * dependencies) and the claim log `S` -- plus `ends`, the level boundaries into the log. Every array is indexed by
+ * A source batch keeps four `n x k` arrays -- `depthK`, `sigmaK` (u32 shortest-path counts, or the f32 bits of the
+ * rescaled ones), `deltaK` (f32 dependencies) and the claim log `S` -- plus `ends`, the level boundaries into the log,
+ * and `levelMax`, the f32 bits of the largest rescaled count at each depth. Every array is indexed by
  * `s * n + v`, and a log entry IS that index, so one u32 names a `(vertex, source)` pair: `4 n k` bytes can never
  * reach 2^32 because each array is one storage binding. The forward pass is a tagged breadth-first search: every
  * level is `bc-finalize` (the boundary: `ends[level + 1] = stackTop`, `done` on an empty level) and then ONE forward
  * dispatch, either `bc-forward` (block-mapped over the level's range of the log) or `bc-forward-edge` (every edge of
- * the `edgeList` view for every source), both claiming, counting and appending with the same rules. Levels are
- * recorded `MAX_LEVELS_PER_SUBMIT` per submit with one small readback (the counters block and the `ends` prefix), and
- * the log's `ends` is known on the host when the forward phase ends, so the backward pass is planned exactly: one
- * `bc-backward` dispatch per level from the deepest to depth 1, each writing `delta[s][w]` once by pulling over the
- * successors; then `bc-gather` adds each vertex's k dependencies into `bc` (and `bc-edge-gather` each arc's k terms
- * into `arcScores`). Nothing accumulates a float through an atomic, so the scores are bitwise reproducible.
+ * the `edgeList` view for every source), both claiming, counting and appending with the same rules.
+ * Levels are recorded `MAX_LEVELS_PER_SUBMIT` per submit with one small readback (the counters block and the `ends`
+ * prefix), and the log's `ends` is known on the host when the forward phase ends, so the backward pass is planned
+ * exactly: one `bc-backward` dispatch per level from the deepest to depth 1, each writing `delta[s][w]` once by pulling
+ * over the successors; then `bc-gather` adds each vertex's k dependencies into `bc` (and `bc-edge-gather` each arc's k
+ * terms into `arcScores`). Nothing accumulates a float through an atomic, so the scores are bitwise reproducible.
+ *
+ * Path counts that outgrow u32 (issue #719): a batch counts exactly in u32 first, and the forward kernels report a
+ * wrap. A 19 x 19 grid already has C(36, 18), about 9.1e9, corner-to-corner paths, and f32 counts would only move the
+ * cliff to a 68 x 68 grid. So a batch whose counts wrapped is abandoned before its backward pass and run again with
+ * every kernel's `SCALED` override: the forward bodies only claim, and after each level `bc-count` pulls the new
+ * depth's counts over the in-arcs (the `reverse` view; the forward core when undirected) as f32 divided by the power of
+ * two that keeps the previous depth's largest count at 2^BC_SIGMA_EXPONENT_CAP; `bc-backward` and `bc-edge-gather` undo
+ * that one step in the ratio Brandes' recursion reads, so the scores are what unbounded counts give. The rest of the
+ * run stays scaled. A batch that never wraps runs exactly as before, bit for bit. In the scaled form `sigmaOverflow`
+ * rises only when the counts at ONE depth span more than f32's exponent range (about 2^226; measured from a corner of a
+ * grid, 235 x 235 raises it and 230 x 230 does not); the `@graphty/algorithms` dispatcher then throws instead of
+ * returning the scores.
  *
  * The batch size k is planned from the device limits at 16 bytes per (node, source) -- the three arrays design 4.7
  * counts plus the 4-byte log entry it omits -- as `min(floor(maxStorageBufferBindingSize / 4n), floor(0.25 x
@@ -43,6 +56,7 @@ import { type F32, foldArcs, type GraphSnapshot, type U32 } from "@graphty/graph
 import {
     BC_BACKWARD_LEVELS_PER_SUBMIT,
     BC_BATCH_BUDGET_FRACTION,
+    BC_COUNT_MAX_GROUPS,
     BC_EDGE_PARALLEL_GAMMA,
     BC_MAX_BATCH,
     MAX_LEVELS_PER_SUBMIT,
@@ -53,6 +67,7 @@ import { CommandBatch } from "../kernel/batch.js";
 import { plan1d, planGridStride } from "../kernel/dispatch.js";
 import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
 import { BC_PARAMS, FILL_PARAMS, FRONTIER_COUNTERS, kernelSpec } from "../kernels.js";
+import { type CoreBinding } from "../memory/residency.js";
 import { assertWholeCore } from "../primitives/core-shape.js";
 import { W } from "../primitives/frontier.js";
 import { assertDeviceComputes } from "../primitives/verify.js";
@@ -60,6 +75,7 @@ import { type BetweennessAcceleratorOptions } from "../types/accelerator.js";
 import { type GpuBetweennessResult, type GpuEdgeScoresResult } from "../types/betweenness.js";
 import { type Binding } from "../types/memory.js";
 import { type GpuRunOptions } from "../types/run.js";
+import { reverseOf } from "./power-iteration.js";
 import { type AlgorithmScope, algorithmScope } from "./scope.js";
 import { aborted, bindingOf, checkDest } from "./sssp.js";
 
@@ -71,8 +87,8 @@ const BYTES_PER_NODE_SOURCE = 16;
 /** The seed of the deterministic draw of `k` sources (any fixed value: the draw only has to repeat). */
 const SAMPLE_SEED = 0x9e3779b9;
 
-/** Params slots of the ring: a backward submit's levels plus the fills, the seed, the gathers and the per-submit forward records. */
-const RING_SLOTS = BC_BACKWARD_LEVELS_PER_SUBMIT + 16;
+/** Params slots of the ring: a forward submit's records per level (boundary, forward and, when scaled, count) or a backward submit's levels, plus the fills, the seed and the gathers. */
+const RING_SLOTS = Math.max(3 * MAX_LEVELS_PER_SUBMIT, BC_BACKWARD_LEVELS_PER_SUBMIT) + 16;
 
 /** The device limits the batch planner reads. */
 interface BatchLimits {
@@ -99,9 +115,11 @@ export interface BetweennessBatchReport {
     readonly levels: number;
     /** `ends[0 .. levels + 1]`: the entries at depth L are `S[ends[L] .. ends[L + 1])`. */
     readonly ends: U32;
-    /** Whether a u32 path count wrapped in this batch. */
+    /** Whether the batch ran with rescaled f32 counts (its u32 counts wrapped on the first try). */
+    readonly scaled: boolean;
+    /** Whether a rescaled path count left f32's normal range in this batch. */
     readonly sigmaOverflow: boolean;
-    /** The `n x k` arrays as the batch left them (null unless the tuning asked for them). */
+    /** The `n x k` arrays as the batch left them (null unless the tuning asked for them); `sigmaK` as stored: u32 counts, or the f32 bits of the scaled ones. */
     readonly depthK: U32 | null;
     readonly sigmaK: U32 | null;
     readonly deltaK: F32 | null;
@@ -231,6 +249,7 @@ interface RunState {
     readonly n: number;
     readonly S: Binding;
     readonly ends: Binding;
+    readonly levelMax: Binding;
     readonly depthK: Binding;
     readonly sigmaK: Binding;
     readonly deltaK: Binding;
@@ -244,14 +263,63 @@ interface RunState {
     readonly edgeCount: number;
     readonly arcCount: number;
     readonly fill: Kernel;
+    readonly gather: Kernel;
+    /** The u32 kernels every batch tries first. */
+    readonly exact: ModeKernels;
+    /** The `SCALED` kernels, compiled when a batch's counts first wrap. */
+    scaled: ModeKernels | null;
+    /** Each bc kernel bound once per run: its resources never change inside a run, only the params offset does. */
+    readonly bound: Map<Kernel, BoundKernel>;
+}
+
+/** The kernels of one counting mode; `count` and `reverse` (the in-arcs it pulls over) only when scaled. */
+interface ModeKernels {
     readonly finalize: Kernel;
     readonly forward: Kernel;
     readonly forwardEdge: Kernel | null;
     readonly backward: Kernel;
-    readonly gather: Kernel;
     readonly edgeGather: Kernel | null;
-    /** Each bc kernel bound once per run: its resources never change inside a run, only the params offset does. */
-    readonly bound: Map<Kernel, BoundKernel>;
+    readonly count: { readonly kernel: Kernel; readonly rowPtr: Binding; readonly colIdx: Binding } | null;
+}
+
+/**
+ * Compiles the kernels of one counting mode.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param core - its forward core (the in-arcs of an undirected snapshot)
+ * @param withForwardEdge - also the edge-parallel forward body
+ * @param withEdges - also the per-arc gather
+ * @param scaled - the `SCALED` variants plus `bc-count`
+ * @returns the kernels
+ */
+async function modeKernels(
+    ctx: GpuContext,
+    s: GraphSnapshot,
+    core: CoreBinding,
+    withForwardEdge: boolean,
+    withEdges: boolean,
+    scaled: boolean,
+): Promise<ModeKernels> {
+    const SCALED = scaled;
+    const [finalize, forward, backward] = await Promise.all(
+        (["bc-finalize", "bc-forward", "bc-backward"] as const).map((id) =>
+            ctx.pipelines.kernel(kernelSpec(id, { SCALED })),
+        ),
+    );
+    const forwardEdge = withForwardEdge
+        ? await ctx.pipelines.kernel(kernelSpec("bc-forward-edge", { UNDIRECTED: !s.directed, SCALED }))
+        : null;
+    const edgeGather = withEdges ? await ctx.pipelines.kernel(kernelSpec("bc-edge-gather", { SCALED })) : null;
+    let count: ModeKernels["count"] = null;
+    if (scaled) {
+        const reverse = s.directed ? reverseOf(ctx, s) : core;
+        count = {
+            kernel: await ctx.pipelines.kernel(kernelSpec("bc-count")),
+            rowPtr: reverse.rowPtr,
+            colIdx: reverse.colIdx ?? reverse.rowPtr,
+        };
+    }
+    return { finalize, forward, forwardEdge, backward, edgeGather, count };
 }
 
 /**
@@ -278,6 +346,7 @@ function recordFill(state: RunState, pass: GPUComputePassEncoder, dst: Binding,
  * @param resources - its storage bindings (the same on every call for one kernel)
  * @param fields - the BcParams fields
  * @param items - the items the grid-stride plan covers
+ * @param maxGroups - the most workgroups the plan launches (default: the planner's cap)
  */
 function recordBc(
     state: RunState,
@@ -286,9 +355,10 @@ function recordBc(
     resources: Readonly<Record<string, Binding>>,
     fields: Readonly<Record<string, number>>,
     items: number,
+    maxGroups?: number,
 ): void {
     const { scope, ctx } = state;
-    const plan = planGridStride(items, ctx.workgroupSize, ctx.caps);
+    const plan = planGridStride(items, ctx.workgroupSize, ctx.caps, maxGroups);
     const params = scope.params(BC_PARAMS, { ...fields, stride: plan.stride ?? 0 });
     let bound = state.bound.get(kernel);
     if (bound === undefined) {
@@ -317,24 +387,27 @@ async function submit(state: RunState, batch: CommandBatch, signal: AbortSignal
 }
 
 /**
- * One source batch: seed, forward levels until an empty one, backward levels, the gathers.
+ * One source batch: seed, forward levels until an empty one, backward levels, the gathers. In the exact mode a batch
+ * whose u32 counts wrapped stops after its forward phase (`wrapped`), before anything reaches the scores.
  * @param state - the run
+ * @param mode - the kernels of the counting mode
  * @param sources - the batch's sources
  * @param form - the forward body
  * @param levelsPerSubmit - the forward cadence
  * @param tuning - the knobs
  * @param signal - the caller's signal
- * @returns the batch's levels and overflow flag
+ * @returns the batch's levels, whether its exact counts wrapped, and the scaled form's overflow flag
  */
 async function runBatch(
     state: RunState,
+    mode: ModeKernels,
     sources: readonly number[],
     form: ForwardForm,
     levelsPerSubmit: number,
     tuning: BetweennessTuning,
     signal: AbortSignal | undefined,
-): Promise<{ levels: number; overflow: boolean }> {
-    const { ctx, n, S, ends, depthK, sigmaK, deltaK, counters } = state;
+): Promise<{ levels: number; wrapped: boolean; overflow: boolean }> {
+    const { ctx, n, S, ends, levelMax, depthK, sigmaK, deltaK, counters } = state;
     const k = sources.length;
     const words = n * k;
     const seeds = Uint32Array.from(sources, (v, s) => s * n + v);
@@ -354,15 +427,18 @@ async function runBatch(
             recordFill(state, pass, depthK, words, 0xffffffff);
             recordFill(state, pass, sigmaK, words, 0);
             recordFill(state, pass, deltaK, words, 0);
-            recordBc(state, pass, state.finalize, { counters, ends, S, depthK, sigmaK }, { n, k, role: 1 }, 1);
+            if (mode.count !== null) {
+                recordFill(state, pass, levelMax, n + 2, 0);
+            }
+            recordBc(state, pass, mode.finalize, { counters, ends, S, depthK, sigmaK, levelMax }, { n, k, role: 1 }, 1);
         }
         for (let level = 0; level < levelsPerSubmit; level++) {
-            recordBc(state, pass, state.finalize, { counters, ends, S, depthK, sigmaK }, { n, k, role: 0 }, 1);
-            if (form === "edge" && state.forwardEdge !== null && state.edgeSrc !== null && state.edgeDst !== null) {
+            recordBc(state, pass, mode.finalize, { counters, ends, S, depthK, sigmaK, levelMax }, { n, k, role: 0 }, 1);
+            if (form === "edge" && mode.forwardEdge !== null && state.edgeSrc !== null && state.edgeDst !== null) {
                 recordBc(
                     state,
                     pass,
-                    state.forwardEdge,
+                    mode.forwardEdge,
                     { edgeSrc: state.edgeSrc, edgeDst: state.edgeDst, S, ends, counters, depthK, sigmaK },
                     forwardFields,
                     forwardItems,
@@ -371,12 +447,24 @@ async function runBatch(
                 recordBc(
                     state,
                     pass,
-                    state.forward,
+                    mode.forward,
                     { rowPtr: state.rowPtr, colIdx: state.colIdx, S, ends, counters, depthK, sigmaK },
                     forwardFields,
                     forwardItems,
                 );
             }
+            if (mode.count !== null) {
+                const { kernel, rowPtr, colIdx } = mode.count;
+                recordBc(
+                    state,
+                    pass,
+                    kernel,
+                    { rowPtr, colIdx, S, ends, counters, depthK, sigmaK, levelMax },
+                    { n, k },
+                    words,
+                    BC_COUNT_MAX_GROUPS,
+                );
+            }
         }
         recorded += levelsPerSubmit;
         batch.endPass();
@@ -389,6 +477,9 @@ async function runBatch(
             levels = words32[W.level];
             overflow = words32[W.sigmaOverflow] !== 0;
             endsWords = new Uint32Array(back, endsRequest.offset, endsCount).slice(0, levels + 1);
+            if (overflow && mode.count === null) {
+                return { levels, wrapped: true, overflow: false };
+            }
         } else if (recorded > n + 2) {
             // a batch claims at most n - 1 levels deep, then one level is empty
             throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: the done flag never rose in ${recorded} levels`, {
@@ -415,20 +506,28 @@ async function runBatch(
             recordBc(
                 state,
                 pass,
-                state.backward,
-                { rowPtr: state.rowPtr, colIdx: state.colIdx, S, depthK, sigmaK, deltaK },
+                mode.backward,
+                { rowPtr: state.rowPtr, colIdx: state.colIdx, S, depthK, sigmaK, deltaK, levelMax },
                 { n, k, start, count },
                 count,
             );
         }
         if (last) {
             recordBc(state, pass, state.gather, { deltaK, bc: state.bc }, { n, k }, n);
-            if (state.edgeGather !== null && state.arcScores !== null) {
+            if (mode.edgeGather !== null && state.arcScores !== null) {
                 recordBc(
                     state,
                     pass,
-                    state.edgeGather,
-                    { rowPtr: state.rowPtr, colIdx: state.colIdx, depthK, sigmaK, deltaK, arcScores: state.arcScores },
+                    mode.edgeGather,
+                    {
+                        rowPtr: state.rowPtr,
+                        colIdx: state.colIdx,
+                        depthK,
+                        sigmaK,
+                        deltaK,
+                        arcScores: state.arcScores,
+                        levelMax,
+                    },
                     { n, k, count: state.arcCount },
                     state.arcCount,
                 );
@@ -456,12 +555,13 @@ async function runBatch(
         forward: form,
         levels,
         ends: endsWords.slice(),
+        scaled: mode.count !== null,
         sigmaOverflow: overflow,
         depthK: arrays?.depthK ?? null,
         sigmaK: arrays?.sigmaK ?? null,
         deltaK: arrays?.deltaK ?? null,
     });
-    return { levels, overflow };
+    return { levels, wrapped: false, overflow };
 }
 
 /**
@@ -501,22 +601,17 @@ async function runRaw(
         const arrayBytes = 4 * n * kMax;
         const lease = (bytes: number, label: string): Binding => bindingOf(scope.scratch(bytes, label), bytes);
         const arcBytes = 4 * Math.max(1, s.arcCount);
-        const [fill, finalize, forward, backward, gather] = await Promise.all(
-            (["fill", "bc-finalize", "bc-forward", "bc-backward", "bc-gather"] as const).map((id) =>
-                ctx.pipelines.kernel(kernelSpec(id)),
-            ),
+        const [fill, gather] = await Promise.all(
+            (["fill", "bc-gather"] as const).map((id) => ctx.pipelines.kernel(kernelSpec(id))),
         );
-        const forwardEdge =
-            edgeView === null
-                ? null
-                : await ctx.pipelines.kernel(kernelSpec("bc-forward-edge", { UNDIRECTED: !s.directed }));
-        const edgeGather = withEdges ? await ctx.pipelines.kernel(kernelSpec("bc-edge-gather")) : null;
+        const exact = await modeKernels(ctx, s, core, edgeView !== null, withEdges, false);
         const state: RunState = {
             ctx,
             scope,
             n,
             S: lease(arrayBytes, "S"),
             ends: lease(4 * (n + 2), "ends"),
+            levelMax: lease(4 * (n + 2), "level-max"),
             depthK: lease(arrayBytes, "depthK"),
             sigmaK: lease(arrayBytes, "sigmaK"),
             deltaK: lease(arrayBytes, "deltaK"),
@@ -530,12 +625,9 @@ async function runRaw(
             edgeCount,
             arcCount: s.arcCount,
             fill,
-            finalize,
-            forward,
-            forwardEdge,
-            backward,
             gather,
-            edgeGather,
+            exact,
+            scaled: null,
             bound: new Map(),
         };
         await ctx.allocator.check();
@@ -559,11 +651,24 @@ async function runRaw(
             if (pinned === "auto" && previousLevels >= 0) {
                 form = previousLevels < BC_EDGE_PARALLEL_GAMMA * Math.log2(n) ? "edge" : "frontier";
             }
-            if (state.forwardEdge === null) {
+            if (state.exact.forwardEdge === null) {
                 form = "frontier"; // no edges to run edge-parallel over
             }
             const batch = sources.slice(start, start + k);
-            const outcome = await runBatch(state, batch, form, levelsPerSubmit, tuning, options?.signal);
+            let outcome = await runBatch(
+                state,
+                state.scaled ?? state.exact,
+                batch,
+                form,
+                levelsPerSubmit,
+                tuning,
+                options?.signal,
+            );
+            if (outcome.wrapped) {
+                // the u32 counts wrapped: this batch, and every later one, counts rescaled f32 instead
+                state.scaled ??= await modeKernels(ctx, s, core, edgeView !== null, withEdges, true);
+                outcome = await runBatch(state, state.scaled, batch, form, levelsPerSubmit, tuning, options?.signal);
+            }
             overflow = overflow || outcome.overflow;
             previousLevels = outcome.levels;
             start += k;
@@ -705,7 +810,9 @@ export async function edgeBetweennessWithTuning(
  * the sources run (`sourcesUsed` beside them; multiply by `n / sourcesUsed` for the estimator of the full sum). The
  * CPU package's convention: halved on an undirected snapshot, `normalized` divides by `(n - 1)(n - 2)` directed or
  * half that undirected. Weights are ignored (breadth-first on both packages). `endpoints: true` is E_UNSUPPORTED.
- * `sigmaOverflow` is true when some pair has more than 2^32 shortest paths: the scores are then wrong.
+ * The path counts are f32 rescaled per depth, so a lattice's astronomically many shortest paths are counted exactly
+ * enough; `sigmaOverflow` is true only when the counts at one depth spread wider than f32's exponent range (about
+ * 2^226): the scores are then wrong, and the `@graphty/algorithms` dispatcher throws instead of returning them.
  * @param ctx - the context whose device runs the kernels
  * @param s - the snapshot (uploaded through ctx.residency, or found there)
  * @param options - `normalized`, `endpoints`, `sources`, `k`, plus dest (a Float32Array of length n) / signal / onProgress (sources done, sources total)

package/src/constants.ts

@@ -265,6 +265,17 @@ export const BC_BATCH_BUDGET_FRACTION = 0.25;
 export const BC_MAX_BATCH = 64;
 /** Design 8.4 (McLaughlin-Bader): a betweenness batch runs the edge-parallel forward pass when the previous batch's level count is below `BC_EDGE_PARALLEL_GAMMA * log2(n)`. The design names the rule and no value; 2 is unmeasured and a benchmark run re-fixes it. */
 export const BC_EDGE_PARALLEL_GAMMA = 2;
+/**
+ * Betweenness path counts that wrapped u32 are recounted as f32, rescaled per depth by a power of two (`bc-count`):
+ * when the largest count at one depth has a binary exponent above this cap, the next depth's counts are scaled down so
+ * that largest count lands at 2^cap. A count then never exceeds 2^cap x 2 x (in-degree), below f32's 2^128 for any
+ * in-degree a binding can hold (2^25), and the counts at one depth may span 2^(cap + 126) before the smallest leaves
+ * f32's normal range, which is when the overflow flag rises (measured: a corner of a 235 x 235 grid, not of a 230 x 230
+ * one). Powers of two scale without rounding, so the scores do not depend on the cap.
+ */
+export const BC_SIGMA_EXPONENT_CAP = 100;
+/** The most workgroups one `bc-count` dispatch launches (it grid-strides over the level): sized for the largest level, a dispatch of n x k lanes costs every level a mostly idle launch, which doubled a 100 x 100 grid's run on an RTX 4070 SUPER; 256 measured 1.3 s against 2.0 s there. */
+export const BC_COUNT_MAX_GROUPS = 256;
 /** Backward-pass levels recorded per submit: each level is one dispatch with its own parameter record, so this bounds the uniform ring. */
 export const BC_BACKWARD_LEVELS_PER_SUBMIT = 64;
 /**

package/src/kernel/prelude.ts

@@ -13,6 +13,7 @@ import { INVALID_INDEX } from "@graphty/graph-format";
 
 import {
     APSP_TILE,
+    BC_SIGMA_EXPONENT_CAP,
     EXACT_TILES_PER_PASS,
     F32_INF_BITS,
     F32_SIGN_BIT,
@@ -76,6 +77,7 @@ const RADIX_DIGIT_MASK: u32 = ${RADIX_BINS - 1}u;
 const APSP_TILE: u32 = ${APSP_TILE}u;
 const GROUP_HASH_LOAD_FACTOR: u32 = ${GROUP_HASH_LOAD_FACTOR}u;
 const TRIANGLE_BINARY_SEARCH_RATIO: u32 = ${TRIANGLE_BINARY_SEARCH_RATIO}u;
+const BC_SIGMA_EXPONENT_CAP: i32 = ${BC_SIGMA_EXPONENT_CAP}i;
 const F32_MAX: f32 = 0x1.fffffep+127;
 override WG: u32 = ${WORKGROUP_SIZE}u;
 override USE_PERM: bool = false;
@@ -85,6 +87,8 @@ override SUBGROUP_MAX: u32 = 0u;
 
 fn linear_id(wid: vec3<u32>, lid: u32) -> u32 { return (wid.x + wid.y * MAX_WORKGROUPS_PER_DIM) * WG + lid; }
 fn group_id(wid: vec3<u32>) -> u32 { return wid.x + wid.y * MAX_WORKGROUPS_PER_DIM; }
+// betweenness: the power of two the counts of depth L + 1 are divided by, from the f32 bits of depth L's largest count
+fn sigma_shift(maxBits: u32) -> i32 { return max(0i, i32((maxBits >> 23u) & 0xffu) - 127i - BC_SIGMA_EXPONENT_CAP); }
 fn lowbias32(x0: u32) -> u32 {
     var x = x0;
     x = x ^ (x >> 16u);

package/src/kernels.ts

@@ -13,7 +13,7 @@
  * P8-T5 adds advance-expand; P8-T6 adds bfs-contract and sssp-pred; P8-T7 adds bfs-fused; P8-T8 adds bfs-bottom-up,
  * bfs-bitset-build and bfs-unvisited-flags; P8-T9 adds sssp-relax; P8-T10 adds bf-relax with the BfParams and BfFlags
  * blocks; P8-T11 adds closeness-sweep and closeness-reduce; P9 (betweenness) adds bc-finalize, bc-forward,
- * bc-backward, bc-gather, bc-edge-gather and bc-forward-edge with the BcParams block; all-pairs shortest paths
+ * bc-backward, bc-gather, bc-edge-gather, bc-forward-edge and bc-count (issue #719) with the BcParams block; all-pairs shortest paths
  * (design 8.7) adds apsp-init and apsp-fw with the ApspParams block. P11 (the structure and community phase, plan
  * design/webgpu/plans/2026-09-23-webgpu-p11-structure-and-community.md) adds the graph build on the device (coo-emit,
  * run-flags, coo-scatter), the per-row group-by-key (group-by-key-row), label propagation's step (lpa-step) and
@@ -32,6 +32,7 @@ import { advanceExpandWgsl } from "./wgsl/advance-expand.wgsl.js";
 import { apspFwWgsl } from "./wgsl/apsp-fw.wgsl.js";
 import { apspInitWgsl } from "./wgsl/apsp-init.wgsl.js";
 import { bcBackwardWgsl } from "./wgsl/bc-backward.wgsl.js";
+import { bcCountWgsl } from "./wgsl/bc-count.wgsl.js";
 import { bcEdgeGatherWgsl } from "./wgsl/bc-edge-gather.wgsl.js";
 import { bcFinalizeWgsl } from "./wgsl/bc-finalize.wgsl.js";
 import { bcForwardWgsl } from "./wgsl/bc-forward.wgsl.js";
@@ -144,6 +145,7 @@ export type KernelId =
     | "bc-forward"
     | "bc-backward"
     | "bc-gather"
+    | "bc-count"
     | "bc-edge-gather"
     | "bc-forward-edge"
     | "apsp-init"
@@ -433,8 +435,8 @@ export const COMPACT_PARAMS: UniformBlock = UniformBlock.define("CompactParams",
  * out-degree sum of the vertices the level claimed, accumulated by `bfs-next-degree` at the end of every level and
  * read, subtracted and zeroed by the next boundary -- Beamer's m_f measured on the frontier the boundary decides
  * for, not on the one it has just expanded); `stackTop` @104 (betweenness: the append cursor of the claim log, which
- * `bc-finalize` also writes into `ends` at every level boundary) and `sigmaOverflow` @108 (betweenness: 1 once a u32
- * path count wrapped) are APPENDED so every earlier word keeps its byte offset. The words nothing writes before P8-T8 / P8-T9 are declared now because
+ * `bc-finalize` also writes into `ends` at every level boundary) and `sigmaOverflow` @108 (betweenness: 1 once a
+ * rescaled path count left f32's normal range) are APPENDED so every earlier word keeps its byte offset. The words nothing writes before P8-T8 / P8-T9 are declared now because
  * the byte layout is what the single result copy decodes.
  */
 export const FRONTIER_COUNTERS: UniformBlock = UniformBlock.define(
@@ -1460,7 +1462,7 @@ const CLOSENESS_REDUCE: KernelEntry = {
     phase: "P8",
 };
 
-/** `bc-finalize` (design 8.4, 5.4): the one-lane bookkeeping of a betweenness batch -- role 1 seeds it (depth 0 and one path for the k seed entries of the claim log, `stackTop = k`, `level = U32_MAX`), role 0 is the level boundary (`ends[level + 1] = stackTop`, `frontierCount`, `done` on an empty level); 5 storage bindings (the counters block as `array<atomic<u32>>`, `ends`, `S` read-only, `depthK` and `sigmaK` plain: one lane writes the seed). The design's finalize row has 2; `ends` is the third (the level boundary), and the seed's `S`, `depthK` and `sigmaK` make it five. */
+/** `bc-finalize` (design 8.4, 5.4): the one-lane bookkeeping of a betweenness batch -- role 1 seeds it (depth 0 and one path for the k seed entries of the claim log, `stackTop = k`, `level = U32_MAX`), role 0 is the level boundary (`ends[level + 1] = stackTop`, `frontierCount`, `done` on an empty level); 6 storage bindings (the counters block as `array<atomic<u32>>`, `ends`, `S` read-only, `depthK`, `sigmaK` and `levelMax` plain: one lane writes the seed; `SCALED` seeds f32 bits). The design's finalize row has 2; `ends` is the third (the level boundary), and the seed's `S`, `depthK`, `sigmaK` and `levelMax` make it six. */
 const BC_FINALIZE: KernelEntry = {
     id: "bc-finalize",
     body: bcFinalizeWgsl,
@@ -1471,16 +1473,17 @@ const BC_FINALIZE: KernelEntry = {
         decl(1, 2, "S", "storage-ro", "array<u32>"),
         decl(1, 3, "depthK", "storage", "array<u32>"),
         decl(1, 4, "sigmaK", "storage", "array<u32>"),
+        decl(1, 5, "levelMax", "storage", "array<u32>"),
         decl(2, 0, "P", "uniform", "BcParams"),
     ],
-    overrideDecls: [],
+    overrideDecls: [{ name: "SCALED", type: "bool", default: false }],
     uniforms: [BC_PARAMS],
     needs: [],
     snippetSlots: [],
     phase: "P9",
 };
 
-/** `bc-forward` (design 8.4, 8.10 "BC forward (tagged)", 16.1): one level of the tagged multi-source BFS -- the block-mapped strip over the level's range of the claim log with the claim, the path count and the overflow report inline, the winners appended to the log; 7 storage bindings (`rowPtr`, `colIdx`, `S` read-write -- the level being read and the appends are ranges of ONE binding --, `ends` read-only, the counters block, `depthK` and `sigmaK` as `array<atomic<u32>>`); the inlined Hillis-Steele scan, so `needs: []`. */
+/** `bc-forward` (design 8.4, 8.10 "BC forward (tagged)", 16.1): one level of the tagged multi-source BFS -- the block-mapped strip over the level's range of the claim log with the claim, the path count and the overflow report inline (`SCALED`: the claim only, `bc-count` counts), the winners appended to the log; 7 storage bindings (`rowPtr`, `colIdx`, `S` read-write -- the level being read and the appends are ranges of ONE binding --, `ends` read-only, the counters block, `depthK` and `sigmaK` as `array<atomic<u32>>`); the inlined Hillis-Steele scan, so `needs: []`. */
 const BC_FORWARD: KernelEntry = {
     id: "bc-forward",
     body: bcForwardWgsl,
@@ -1495,14 +1498,14 @@ const BC_FORWARD: KernelEntry = {
         decl(1, 6, "sigmaK", "storage", "array<atomic<u32>>"),
         decl(2, 0, "P", "uniform", "BcParams"),
     ],
-    overrideDecls: [],
+    overrideDecls: [{ name: "SCALED", type: "bool", default: false }],
     uniforms: [BC_PARAMS],
     needs: [],
     snippetSlots: [],
     phase: "P9",
 };
 
-/** `bc-backward` (design 8.4, 8.10 "BC backward (successor pull)"): one level of the dependency accumulation, one invocation per log entry of a host-planned range, each pulling over its successors and writing its delta once; 6 storage bindings (`rowPtr`, `colIdx`, `S`, `depthK`, `sigmaK` read-only, `deltaK`). */
+/** `bc-backward` (design 8.4, 8.10 "BC backward (successor pull)"): one level of the dependency accumulation, one invocation per log entry of a host-planned range, each pulling over its successors and writing its delta once; 7 storage bindings (`rowPtr`, `colIdx`, `S`, `depthK`, `sigmaK` read-only, `deltaK`, `levelMax` read-only: the depth scale of `bc-count`, read under `SCALED`). */
 const BC_BACKWARD: KernelEntry = {
     id: "bc-backward",
     body: bcBackwardWgsl,
@@ -1514,9 +1517,10 @@ const BC_BACKWARD: KernelEntry = {
         decl(1, 3, "depthK", "storage-ro", "array<u32>"),
         decl(1, 4, "sigmaK", "storage-ro", "array<u32>"),
         decl(1, 5, "deltaK", "storage", "array<f32>"),
+        decl(1, 6, "levelMax", "storage-ro", "array<u32>"),
         decl(2, 0, "P", "uniform", "BcParams"),
     ],
-    overrideDecls: [],
+    overrideDecls: [{ name: "SCALED", type: "bool", default: false }],
     uniforms: [BC_PARAMS],
     needs: [],
     snippetSlots: [],
@@ -1540,7 +1544,7 @@ const BC_GATHER: KernelEntry = {
     phase: "P9",
 };
 
-/** `bc-edge-gather` (design 8.4 "edge BC accumulates per arc from the same n x k deltas"): the per-arc twin of `bc-gather`, one invocation per arc (its row found by an upper-bound search over `rowPtr`) adding the arc's term over the batch's sources; 6 storage bindings (`rowPtr`, `colIdx`, `depthK`, `sigmaK`, `deltaK` read-only, `arcScores`). */
+/** `bc-edge-gather` (design 8.4 "edge BC accumulates per arc from the same n x k deltas"): the per-arc twin of `bc-gather`, one invocation per arc (its row found by an upper-bound search over `rowPtr`) adding the arc's term over the batch's sources; 7 storage bindings (`rowPtr`, `colIdx`, `depthK`, `sigmaK`, `deltaK` read-only, `arcScores`, `levelMax` read-only). */
 const BC_EDGE_GATHER: KernelEntry = {
     id: "bc-edge-gather",
     body: bcEdgeGatherWgsl,
@@ -1552,16 +1556,17 @@ const BC_EDGE_GATHER: KernelEntry = {
         decl(1, 3, "sigmaK", "storage-ro", "array<u32>"),
         decl(1, 4, "deltaK", "storage-ro", "array<f32>"),
         decl(1, 5, "arcScores", "storage", "array<f32>"),
+        decl(1, 6, "levelMax", "storage-ro", "array<u32>"),
         decl(2, 0, "P", "uniform", "BcParams"),
     ],
-    overrideDecls: [],
+    overrideDecls: [{ name: "SCALED", type: "bool", default: false }],
     uniforms: [BC_PARAMS],
     needs: [],
     snippetSlots: [],
     phase: "P9",
 };
 
-/** `bc-forward-edge` (design 8.4 "the edge-parallel form", 8.8 row 7): one forward level edge-parallel over the `edgeList` view for every source of the batch, with `bc-forward`'s claim, count and overflow report, appending to the same claim log; `UNDIRECTED` relaxes both directions of every edge; 7 storage bindings (`edgeSrc`, `edgeDst`, `S` read-write, `ends` read-only, the counters block, `depthK` and `sigmaK` as `array<atomic<u32>>`). */
+/** `bc-forward-edge` (design 8.4 "the edge-parallel form", 8.8 row 7): one forward level edge-parallel over the `edgeList` view for every source of the batch, with `bc-forward`'s claim, count and overflow report (`SCALED`: the claim only), appending to the same claim log; `UNDIRECTED` relaxes both directions of every edge; 7 storage bindings (`edgeSrc`, `edgeDst`, `S` read-write, `ends` read-only, the counters block, `depthK` and `sigmaK` as `array<atomic<u32>>`). */
 const BC_FORWARD_EDGE: KernelEntry = {
     id: "bc-forward-edge",
     body: bcForwardEdgeWgsl,
@@ -1576,7 +1581,33 @@ const BC_FORWARD_EDGE: KernelEntry = {
         decl(1, 6, "sigmaK", "storage", "array<atomic<u32>>"),
         decl(2, 0, "P", "uniform", "BcParams"),
     ],
-    overrideDecls: [{ name: "UNDIRECTED", type: "bool", default: false }],
+    overrideDecls: [
+        { name: "UNDIRECTED", type: "bool", default: false },
+        { name: "SCALED", type: "bool", default: false },
+    ],
+    uniforms: [BC_PARAMS],
+    needs: [],
+    snippetSlots: [],
+    phase: "P9",
+};
+
+/** `bc-count` (design 8.4, issue #719): in a batch rerun because its u32 counts wrapped, the path counts of the depth a forward level just claimed, pulled over the in-arcs in CSR order as f32 bits and rescaled per depth by a power of two, the overflow flag raised when a count leaves f32's normal range; 8 storage bindings (the REVERSE core's `rowPtr` and `colIdx`, `S` and `ends` read-only, the counters block and `levelMax` as `array<atomic<u32>>`, `depthK` read-only, `sigmaK` read-write). */
+const BC_COUNT: KernelEntry = {
+    id: "bc-count",
+    body: bcCountWgsl,
+    entryPoint: "bc_count",
+    bindings: [
+        decl(1, 0, "rowPtr", "storage-ro", "array<u32>"),
+        decl(1, 1, "colIdx", "storage-ro", "array<u32>"),
+        decl(1, 2, "S", "storage-ro", "array<u32>"),
+        decl(1, 3, "ends", "storage-ro", "array<u32>"),
+        decl(1, 4, "counters", "storage", "array<atomic<u32>>"),
+        decl(1, 5, "depthK", "storage-ro", "array<u32>"),
+        decl(1, 6, "sigmaK", "storage", "array<u32>"),
+        decl(1, 7, "levelMax", "storage", "array<atomic<u32>>"),
+        decl(2, 0, "P", "uniform", "BcParams"),
+    ],
+    overrideDecls: [],
     uniforms: [BC_PARAMS],
     needs: [],
     snippetSlots: [],
@@ -1871,6 +1902,7 @@ const REGISTRY: Readonly<Partial<Record<KernelId, KernelEntry>>> = Object.freeze
     "bc-forward": BC_FORWARD,
     "bc-backward": BC_BACKWARD,
     "bc-gather": BC_GATHER,
+    "bc-count": BC_COUNT,
     "bc-edge-gather": BC_EDGE_GATHER,
     "bc-forward-edge": BC_FORWARD_EDGE,
     "apsp-init": APSP_INIT,

package/src/types/betweenness.ts

@@ -18,8 +18,11 @@ export interface GpuBetweennessResult extends GpuScoresResult {
     /** How many sources the scores sum over: `n` for an exact run, the sample size for a sampled one. */
     readonly sourcesUsed: number;
     /**
-     * True when some pair of vertices is joined by more than 2^32 shortest paths: the u32 path counts wrapped and the
-     * scores are WRONG, not approximate. Never clamped, never silent.
+     * True when the scores are WRONG, not approximate: the shortest-path counts at one depth from one batch of sources
+     * spread wider than f32's exponent range (about 2^226 between the smallest and the largest), so even the rescaled
+     * counts could not hold them. Counts past 2^32 alone do not raise it; they are recounted rescaled per depth (a 40 x
+     * 40 grid's 2.6e22 paths are exact). Measured from a corner of a grid: 235 x 235 raises it, 230 x 230 does not.
+     * Never clamped, never silent; the `@graphty/algorithms` dispatcher throws `PathCountOverflowError` on it.
      */
     readonly sigmaOverflow: boolean;
 }