@graphty/algorithms 2.1.2 → 2.2.0

package/src/indexed/structures/min-heap.ts

@@ -11,13 +11,18 @@ export class IndexedMinHeap {
     private readonly heap: U32; // slot -> node
     private readonly slot: U32; // node -> slot, INVALID_INDEX when absent
     private readonly key: F64; // node -> key
+    private readonly tieBreakByIndex: boolean;
     private size = 0;
 
     /**
      * Create an empty heap over node indices in `[0, capacity)`.
      * @param capacity - The number of distinct node indices the heap may hold
+     * @param tieBreakByIndex - When true, of two equal keys the lower node index pops first, so
+     * the pop order is fully determined by the keys; when false (the default) equal keys pop in
+     * an order that depends on the push history
      */
-    constructor(capacity: number) {
+    constructor(capacity: number, tieBreakByIndex = false) {
+        this.tieBreakByIndex = tieBreakByIndex;
         this.heap = new Uint32Array(capacity);
         this.slot = new Uint32Array(capacity).fill(INVALID_INDEX);
         this.key = new Float64Array(capacity);
@@ -31,12 +36,42 @@ export class IndexedMinHeap {
         return this.size === 0;
     }
 
+    /**
+     * Whether a node is currently in the heap.
+     * @param node - The node index
+     * @returns True when the node was pushed and has not been popped since
+     */
+    has(node: number): boolean {
+        return this.slot[node] !== INVALID_INDEX;
+    }
+
+    /**
+     * The key a node was last given. Meaningful only while `has(node)` is true.
+     * @param node - The node index
+     * @returns Its key
+     */
+    keyOf(node: number): number {
+        return this.key[node];
+    }
+
+    /**
+     * The smallest key in the heap, without removing it.
+     * @returns The minimum key, or Infinity when the heap is empty
+     */
+    peekKey(): number {
+        return this.size === 0 ? Infinity : this.key[this.heap[0]];
+    }
+
     /**
      * Insert a node that is not in the heap.
      * @param node - The node index
      * @param key - Its key
+     * @throws RangeError when the node index is outside `[0, capacity)`
      */
     push(node: number, key: number): void {
+        if (!(node >= 0 && node < this.slot.length)) {
+            throw new RangeError(`Node index ${String(node)} is outside the heap's ${String(this.slot.length)} nodes`);
+        }
         this.key[node] = key;
         this.heap[this.size] = node;
         this.slot[node] = this.size;
@@ -79,14 +114,25 @@ export class IndexedMinHeap {
         return top;
     }
 
+    /**
+     * Whether node `a` pops before node `b`.
+     * @param a - A node index in the heap
+     * @param b - A node index in the heap
+     * @returns True when a's key is smaller, or equal with the tie-break on and a lower index
+     */
+    private before(a: number, b: number): boolean {
+        const ka = this.key[a];
+        const kb = this.key[b];
+        return ka < kb || (this.tieBreakByIndex && ka === kb && a < b);
+    }
+
     private siftUp(from: number): void {
         let at = from;
         const node = this.heap[at];
-        const key = this.key[node];
         while (at > 0) {
             const parent = (at - 1) >> 1;
             const parentNode = this.heap[parent];
-            if (this.key[parentNode] <= key) {
+            if (!this.before(node, parentNode)) {
                 break;
             }
             this.heap[at] = parentNode;
@@ -100,16 +146,15 @@ export class IndexedMinHeap {
     private siftDown(from: number): void {
         let at = from;
         const node = this.heap[at];
-        const key = this.key[node];
         for (;;) {
             const left = 2 * at + 1;
             if (left >= this.size) {
                 break;
             }
             const right = left + 1;
-            const child = right < this.size && this.key[this.heap[right]] < this.key[this.heap[left]] ? right : left;
+            const child = right < this.size && this.before(this.heap[right], this.heap[left]) ? right : left;
             const childNode = this.heap[child];
-            if (key <= this.key[childNode]) {
+            if (!this.before(childNode, node)) {
                 break;
             }
             this.heap[at] = childNode;

package/src/indexed/structures/ring-queue.ts

@@ -0,0 +1,70 @@
+/**
+ * A fixed-capacity FIFO queue of node indices over one `Uint32Array`, for the frontier of a
+ * breadth-first sweep that may re-enqueue a node (label propagation, SPFA-style relaxation) and so
+ * cannot use the one-pass `order` array plain BFS does. Overflow and underflow throw rather than
+ * silently overwrite: a wrong capacity is a bug in the caller.
+ */
+export class RingQueue {
+    private readonly buffer: Uint32Array;
+    private head = 0;
+    private count = 0;
+
+    /**
+     * Create an empty queue.
+     * @param capacity - The most entries the queue holds at once
+     */
+    constructor(capacity: number) {
+        this.buffer = new Uint32Array(capacity);
+    }
+
+    /**
+     * The number of queued entries.
+     * @returns The entry count
+     */
+    get size(): number {
+        return this.count;
+    }
+
+    /**
+     * Whether the queue holds no entries.
+     * @returns True when empty
+     */
+    isEmpty(): boolean {
+        return this.count === 0;
+    }
+
+    /**
+     * Append a value at the tail.
+     * @param value - A node index
+     * @throws RangeError when the queue is full
+     */
+    push(value: number): void {
+        const capacity = this.buffer.length;
+        if (this.count === capacity) {
+            throw new RangeError(`RingQueue: full at capacity ${String(capacity)}`);
+        }
+        this.buffer[(this.head + this.count) % capacity] = value;
+        this.count++;
+    }
+
+    /**
+     * Remove and return the value at the head.
+     * @returns The oldest queued node index
+     * @throws RangeError when the queue is empty
+     */
+    shift(): number {
+        if (this.count === 0) {
+            throw new RangeError("RingQueue: shift on an empty queue");
+        }
+        const value = this.buffer[this.head];
+        this.head = (this.head + 1) % this.buffer.length;
+        this.count--;
+        return value;
+    }
+
+    /** Drop every entry, keeping the buffer for reuse. */
+    clear(): void {
+        this.head = 0;
+        this.count = 0;
+    }
+}

package/src/indexed/sync.ts

@@ -0,0 +1,229 @@
+import type { F64, GraphSnapshot, U32 } from "@graphty/graph-format";
+
+import { SeededRandom } from "../utils/math-utilities.js";
+
+/** Options of the index-based SynC clustering, matching the legacy `syncClustering`. @public */
+export interface SyncClusteringOptions {
+    /** Number of cluster centres: an integer in `[1, nodeCount]` (legacy rounds a fraction up; the port throws). */
+    readonly numClusters: number;
+    /** Iteration cap; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** Stop when the loss changes by less than this between iterations; default 1e-6. */
+    readonly tolerance?: number | undefined;
+    /** Seed of the embedding initialisation and the centre draws; default 42. */
+    readonly seed?: number | undefined;
+    /** Gradient step; default 0.01. */
+    readonly learningRate?: number | undefined;
+    /** Weight of the neighbour-reconstruction and regularisation terms; default 0.1. */
+    readonly lambda?: number | undefined;
+}
+
+/** Result of the index-based SynC clustering. @public */
+export interface SyncClusteringResult {
+    /** The centre each node is closest to, in `[0, count)`. A centre may end up with no node. */
+    readonly labels: U32;
+    /** Number of cluster centres: `numClusters`. */
+    readonly count: number;
+    /** Node embeddings, row-major: node i is `embeddings.subarray(i * dimensions, (i + 1) * dimensions)`. */
+    readonly embeddings: F64;
+    /** Embedding length: `min(64, nodeCount)`. */
+    readonly dimensions: number;
+    /** Loss of the last iteration run (Infinity when none ran). */
+    readonly loss: number;
+    /** Loss of the iteration before the last (Infinity when fewer than two ran). */
+    readonly previousLoss: number;
+    /** Iterations run. */
+    readonly iterations: number;
+    /** Whether the loss settled within the tolerance before the cap. */
+    readonly converged: boolean;
+}
+
+/**
+ * Euclidean distance between two rows of a row-major matrix.
+ * @param a - First matrix
+ * @param i - Row of a
+ * @param b - Second matrix
+ * @param j - Row of b
+ * @param dim - Row length
+ * @returns The distance
+ */
+function distance(a: F64, i: number, b: F64, j: number, dim: number): number {
+    let sum = 0;
+    for (let k = 0; k < dim; k++) {
+        const diff = a[i * dim + k] - b[j * dim + k];
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}
+
+/**
+ * SynC over a snapshot: node embeddings seeded from degree and a seeded generator, pulled toward
+ * their out-neighbours by gradient steps, and clustered by k-means with k-means++ centres. The
+ * arithmetic, and the order of every random draw, are the legacy `syncClustering`'s, so for the same
+ * seed the labels and embeddings agree with it to rounding; the port draws from its own generator
+ * instead of replacing `Math.random` for the duration of the call.
+ *
+ * Weights are ignored and a parallel arc pulls once per arc. The seeding degree is legacy's: in plus
+ * out when directed, the stored arc count when undirected, so an undirected self-loop counts once.
+ * @param s - The snapshot
+ * @param options - {@link SyncClusteringOptions}
+ * @returns Assignments, embeddings and convergence
+ */
+export function syncClustering(s: GraphSnapshot, options: SyncClusteringOptions): SyncClusteringResult {
+    const {
+        numClusters,
+        maxIterations = 100,
+        tolerance = 1e-6,
+        seed = 42,
+        learningRate = 0.01,
+        lambda = 0.1,
+    } = options;
+    const n = s.nodeCount;
+    if (n === 0) {
+        return {
+            labels: new Uint32Array(0),
+            count: numClusters,
+            embeddings: new Float64Array(0),
+            dimensions: 0,
+            loss: 0,
+            previousLoss: Infinity,
+            iterations: 0,
+            converged: true,
+        };
+    }
+    if (!Number.isInteger(numClusters) || numClusters <= 0 || numClusters > n) {
+        throw new Error(`Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(n)}`);
+    }
+    const random = SeededRandom.createGenerator(seed);
+    const dim = Math.min(64, n);
+    const { rowPtr, colIdx } = s;
+
+    const emb = new Float64Array(n * dim);
+    // Legacy's degree: an undirected self-loop counts once (its single stored arc), not twice.
+    const degree = s.directed ? s.degree() : s.outDegree();
+    for (let u = 0; u < n; u++) {
+        const normalized = degree[u] / Math.max(1, n - 1);
+        for (let k = 0; k < dim; k++) {
+            emb[u * dim + k] = (random() - 0.5) * 0.1 + normalized * 0.1;
+        }
+    }
+
+    // k-means++: the first centre uniformly, each next one with probability proportional to the
+    // squared distance to the nearest centre so far. A draw that rounding carries past the last
+    // node adds no centre, as in legacy, so there may be fewer than numClusters.
+    const centres = new Float64Array(numClusters * dim);
+    const pick = Math.floor(random() * n);
+    centres.set(emb.subarray(pick * dim, (pick + 1) * dim), 0);
+    let centreCount = 1;
+    const weight = new Float64Array(n);
+    for (let k = 1; k < numClusters; k++) {
+        let total = 0;
+        for (let u = 0; u < n; u++) {
+            let nearest = Infinity;
+            for (let c = 0; c < centreCount; c++) {
+                nearest = Math.min(nearest, distance(emb, u, centres, c, dim));
+            }
+            weight[u] = nearest * nearest;
+            total += nearest * nearest;
+        }
+        let draw = random() * total;
+        for (let u = 0; u < n; u++) {
+            draw -= weight[u];
+            if (draw <= 0) {
+                centres.set(emb.subarray(u * dim, (u + 1) * dim), centreCount * dim);
+                centreCount++;
+                break;
+            }
+        }
+    }
+
+    const labels = new Uint32Array(n);
+    const assign = (): void => {
+        for (let u = 0; u < n; u++) {
+            let bestCentre = 0;
+            let bestDistance = Infinity;
+            for (let c = 0; c < centreCount; c++) {
+                const d = distance(emb, u, centres, c, dim);
+                if (d < bestDistance) {
+                    bestDistance = d;
+                    bestCentre = c;
+                }
+            }
+            labels[u] = bestCentre;
+        }
+    };
+
+    const gradient = new Float64Array(n * dim);
+    const sums = new Float64Array(numClusters * dim);
+    const sizes = new Uint32Array(numClusters);
+    let previousLoss = Infinity;
+    let loss = Infinity;
+    let iterations = 0;
+    let converged = false;
+    while (iterations < maxIterations) {
+        iterations++;
+        assign();
+
+        // Every gradient from the embeddings before this step, then one step for all.
+        gradient.fill(0);
+        for (let u = 0; u < n; u++) {
+            const row = u * dim;
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                const other = colIdx[a] * dim;
+                for (let k = 0; k < dim; k++) {
+                    gradient[row + k] += lambda * (emb[row + k] - emb[other + k]);
+                }
+            }
+            for (let k = 0; k < dim; k++) {
+                gradient[row + k] += lambda * emb[row + k];
+            }
+        }
+        for (let i = 0; i < emb.length; i++) {
+            emb[i] -= learningRate * gradient[i];
+        }
+
+        sums.fill(0);
+        sizes.fill(0);
+        for (let u = 0; u < n; u++) {
+            const c = labels[u];
+            for (let k = 0; k < dim; k++) {
+                sums[c * dim + k] += emb[u * dim + k];
+            }
+            sizes[c]++;
+        }
+        for (let c = 0; c < centreCount; c++) {
+            if (sizes[c] > 0) {
+                for (let k = 0; k < dim; k++) {
+                    centres[c * dim + k] = sums[c * dim + k] / sizes[c];
+                }
+            }
+        }
+
+        let clustering = 0;
+        let reconstruction = 0;
+        let regularization = 0;
+        for (let u = 0; u < n; u++) {
+            clustering += distance(emb, u, centres, labels[u], dim) ** 2;
+        }
+        for (let u = 0; u < n; u++) {
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                reconstruction += distance(emb, u, emb, colIdx[a], dim) ** 2;
+            }
+        }
+        for (const value of emb) {
+            regularization += value ** 2;
+        }
+        const current = clustering + lambda * reconstruction + lambda * regularization;
+        if (iterations > 1) {
+            previousLoss = loss;
+        }
+        loss = current;
+        if (Math.abs(previousLoss - loss) < tolerance) {
+            converged = true;
+            break;
+        }
+    }
+    assign();
+
+    return { labels, count: numClusters, embeddings: emb, dimensions: dim, loss, previousLoss, iterations, converged };
+}

package/src/indexed/terahac.ts

@@ -0,0 +1,290 @@
+import { type F64, type GraphSnapshot, renumberPartition, type U32 } from "@graphty/graph-format";
+
+import { type LabelResult, withGroups } from "./components.js";
+
+/** Options of the index-based TeraHAC, matching the legacy `teraHAC`. @public */
+export interface TeraHacOptions {
+    /**
+     * How the distance between two clusters is read from their members' pairwise distances: the
+     * minimum, the maximum, the mean, or (`"ward"`) the mean of the squares; default `"average"`.
+     */
+    readonly linkage?: "single" | "complete" | "average" | "ward" | undefined;
+    /** Stop merging at this many clusters; a positive integer. Default: merge until one is left. */
+    readonly numClusters?: number | undefined;
+    /** Stop at the first merge whose linkage distance is above this. Default: no threshold. */
+    readonly distanceThreshold?: number | undefined;
+    /**
+     * Pairwise distance: hop count along out-arcs (true, the default), or 1 for an arc from the
+     * lower to the higher node index and 2 for none (false).
+     */
+    readonly useGraphDistance?: boolean | undefined;
+}
+
+/**
+ * Result of the index-based TeraHAC: the flat clustering plus the dendrogram. Dendrogram node
+ * `i < n` is node index i; node `n + k` is the k-th join, with children `left[k]` and `right[k]`.
+ * @public
+ */
+export interface TeraHacResult extends LabelResult {
+    /** Left child of each join (the legacy `ClusterNode.left`). */
+    readonly left: U32;
+    /** Right child of each join. */
+    readonly right: U32;
+    /** Linkage distance of each join; Infinity for the joins that tie the remaining clusters under one root. */
+    readonly distance: F64;
+    /** Node count under each join. */
+    readonly size: U32;
+    /** Joins made by distance: `distance.subarray(0, merges)` is the legacy `distances` list. */
+    readonly merges: number;
+    /** The dendrogram root: `2n - 2`, or 0 for a single node. */
+    readonly root: number;
+}
+
+/** The distance legacy gives an unreachable pair, so that disconnected clusters still merge last. */
+const UNREACHABLE = 100;
+
+/**
+ * All-pairs distances into a row-major n x n matrix: BFS hop counts along out-arcs (Infinity when
+ * unreachable) or the 1 / 2 adjacency distance.
+ * @param s - The snapshot
+ * @param useGraphDistance - Which distance
+ * @returns The matrix
+ */
+function pairwiseDistances(s: GraphSnapshot, useGraphDistance: boolean): Float64Array {
+    const n = s.nodeCount;
+    const d = new Float64Array(n * n);
+    if (!useGraphDistance) {
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                d[i * n + j] = d[j * n + i] = s.hasArc(i, j) ? 1 : 2;
+            }
+        }
+        return d;
+    }
+    d.fill(Infinity);
+    const queue = new Uint32Array(n);
+    for (let source = 0; source < n; source++) {
+        const row = source * n;
+        d[row + source] = 0;
+        queue[0] = source;
+        let head = 0;
+        let tail = 1;
+        while (head < tail) {
+            const u = queue[head++];
+            const next = d[row + u] + 1;
+            for (let a = s.rowPtr[u]; a < s.rowPtr[u + 1]; a++) {
+                const v = s.colIdx[a];
+                if (d[row + v] === Infinity) {
+                    d[row + v] = next;
+                    queue[tail++] = v;
+                }
+            }
+        }
+    }
+    return d;
+}
+
+/**
+ * TeraHAC over a snapshot: agglomerative clustering that repeatedly merges the closest pair of
+ * clusters, with the same distances, merge order and tie-breaks as the legacy `teraHAC` -- but
+ * over node indices, so the result no longer depends on what the node ids are.
+ *
+ * The linkage is kept per ordered cluster pair as an aggregate (minimum, maximum, sum of distances
+ * or sum of squared distances) and updated on each merge, instead of rescanning every member pair;
+ * the pairwise distances are integers, so the sums, and the means divided out of them, are exact.
+ * A pair's distance reads the aggregate in the orientation legacy reads it, which matters on a
+ * directed snapshot, and ties go to the pair legacy's stable sort puts first: two original nodes
+ * before any pair with a merged cluster, and among those the most recent merge last.
+ *
+ * Weights are ignored (legacy counts hops). O(n^2) memory and O(n (n + m)) for the distances; the
+ * merging keeps each cluster's closest partner and rescans a row only when that partner merges.
+ * @param s - The snapshot
+ * @param options - {@link TeraHacOptions}
+ * @returns The flat clustering and the dendrogram
+ */
+export function teraHAC(s: GraphSnapshot, options: TeraHacOptions = {}): TeraHacResult {
+    const { linkage = "average", numClusters, distanceThreshold, useGraphDistance = true } = options;
+    if (numClusters !== undefined && (numClusters < 1 || !Number.isInteger(numClusters))) {
+        throw new Error("numClusters must be a positive integer");
+    }
+    const n = s.nodeCount;
+    if (n === 0) {
+        throw new Error("Cannot cluster empty graph");
+    }
+
+    // ponytail: dense n x n aggregate matrix, the same memory as legacy's distance matrix; a sparse
+    // candidate structure is the upgrade if graphs past ~10k nodes need this.
+    const agg = pairwiseDistances(s, useGraphDistance);
+    if (linkage === "ward") {
+        for (let i = 0; i < agg.length; i++) {
+            agg[i] *= agg[i];
+        }
+    }
+    const extremes = { single: Math.min, complete: Math.max, average: null, ward: null };
+    const extreme = extremes[linkage];
+
+    const joins = Math.max(0, n - 1);
+    const left = new Uint32Array(joins);
+    const right = new Uint32Array(joins);
+    const distance = new Float64Array(joins);
+    const size = new Uint32Array(joins);
+
+    // Slot i holds one active cluster: its dendrogram id, its size, and its closest partner.
+    const clusterId = new Uint32Array(n);
+    const members = new Uint32Array(n).fill(1);
+    const active = new Uint8Array(n).fill(1);
+    for (let i = 0; i < n; i++) {
+        clusterId[i] = i;
+    }
+    const orient = (x: number, y: number): boolean => {
+        // true when x is the pair's first cluster: the lower id of two originals, else the newer one
+        const a = clusterId[x];
+        const b = clusterId[y];
+        return a < n && b < n ? a < b : a > b;
+    };
+    const pairDistance = (x: number, y: number): number => {
+        const [p, q] = orient(x, y) ? [x, y] : [y, x];
+        let value = agg[p * n + q];
+        if (clusterId[p] < n && clusterId[q] < n) {
+            // Legacy reads two original nodes' distance straight from the matrix, unsquared even for ward.
+            value = linkage === "ward" ? Math.sqrt(value) : value;
+        } else if (!extreme) {
+            value /= members[p] * members[q];
+        }
+        return value === Infinity ? UNREACHABLE : value;
+    };
+    const pairOrder = (x: number, y: number): number => {
+        const a = clusterId[x];
+        const b = clusterId[y];
+        const lo = Math.min(a, b);
+        const hi = Math.max(a, b);
+        return hi < n ? lo * n + hi : n * n + hi * 2 * n + lo;
+    };
+    const best = new Int32Array(n).fill(-1);
+    const bestDistance = new Float64Array(n);
+    const bestOrder = new Float64Array(n);
+    const offer = (x: number, y: number): void => {
+        const d = pairDistance(x, y);
+        const o = pairOrder(x, y);
+        if (best[x] === -1 || d < bestDistance[x] || (d === bestDistance[x] && o < bestOrder[x])) {
+            best[x] = y;
+            bestDistance[x] = d;
+            bestOrder[x] = o;
+        }
+    };
+    const rescan = (x: number): void => {
+        best[x] = -1;
+        for (let y = 0; y < n; y++) {
+            if (active[y] && y !== x) {
+                offer(x, y);
+            }
+        }
+    };
+    for (let x = 0; x < n; x++) {
+        rescan(x);
+    }
+
+    let remaining = n;
+    let merges = 0;
+    while (remaining > 1 && (numClusters === undefined || remaining > numClusters)) {
+        let x = -1;
+        for (let i = 0; i < n; i++) {
+            if (
+                active[i] &&
+                (x === -1 ||
+                    bestDistance[i] < bestDistance[x] ||
+                    (bestDistance[i] === bestDistance[x] && bestOrder[i] < bestOrder[x]))
+            ) {
+                x = i;
+            }
+        }
+        const d = bestDistance[x];
+        if (distanceThreshold !== undefined && d > distanceThreshold) {
+            break;
+        }
+        const [keep, drop] = orient(x, best[x]) ? [x, best[x]] : [best[x], x];
+        left[merges] = clusterId[keep];
+        right[merges] = clusterId[drop];
+        distance[merges] = d;
+        size[merges] = members[keep] + members[drop];
+        for (let c = 0; c < n; c++) {
+            if (active[c] && c !== keep && c !== drop) {
+                const kc = keep * n + c;
+                const dc = drop * n + c;
+                const ck = c * n + keep;
+                const cd = c * n + drop;
+                agg[kc] = extreme ? extreme(agg[kc], agg[dc]) : agg[kc] + agg[dc];
+                agg[ck] = extreme ? extreme(agg[ck], agg[cd]) : agg[ck] + agg[cd];
+            }
+        }
+        clusterId[keep] = n + merges;
+        members[keep] = size[merges];
+        active[drop] = 0;
+        merges++;
+        remaining--;
+        rescan(keep);
+        for (let c = 0; c < n; c++) {
+            if (active[c] && c !== keep) {
+                if (best[c] === keep || best[c] === drop) {
+                    rescan(c);
+                } else {
+                    offer(c, keep);
+                }
+            }
+        }
+    }
+
+    // Tie what is left under one root, in ascending cluster id, as legacy does.
+    const rest = Array.from(clusterId.filter((_, i) => active[i] === 1)).sort((a, b) => a - b);
+    let root = rest[0];
+    const sizeOf = (c: number): number => (c < n ? 1 : size[c - n]);
+    for (let k = 1; k < rest.length; k++) {
+        const j = merges + k - 1;
+        left[j] = root;
+        right[j] = rest[k];
+        distance[j] = Infinity;
+        size[j] = sizeOf(root) + sizeOf(rest[k]);
+        root = n + j;
+    }
+
+    const cut = cutDendrogram(n, left, right, root, numClusters ?? remaining);
+    const { labels, count } = renumberPartition(cut);
+    return { ...withGroups(labels, count), left, right, distance, size, merges, root };
+}
+
+/**
+ * Legacy's flat clustering: split dendrogram nodes breadth-first from the root until splitting the
+ * next one would exceed `k` clusters, then label every node by the cluster above it.
+ * @param n - Node count
+ * @param left - Left child of each join
+ * @param right - Right child of each join
+ * @param root - The root
+ * @param k - The cluster count asked for
+ * @returns A cluster number per node index
+ */
+function cutDendrogram(n: number, left: U32, right: U32, root: number, k: number): U32 {
+    const kept: number[] = [];
+    const queue = [root];
+    let head = 0;
+    while (head < queue.length && kept.length < k) {
+        const c = queue[head++];
+        if (c < n || k === 1 || kept.length + (queue.length - head) + 1 >= k) {
+            kept.push(c);
+        } else {
+            queue.push(left[c - n], right[c - n]);
+        }
+    }
+    const labels = new Uint32Array(n);
+    kept.forEach((top, label) => {
+        const stack = [top];
+        while (stack.length > 0) {
+            const c = stack.pop() ?? 0;
+            if (c < n) {
+                labels[c] = label;
+            } else {
+                stack.push(left[c - n], right[c - n]);
+            }
+        }
+    });
+    return labels;
+}