bmssp 1.1.1 → 2.0.0

package/src/boundIndex.mjs

@@ -0,0 +1,243 @@
+/**
+ * Self-balancing (AVL) ordered sequence — the "balanced BST over block upper
+ * bounds" of Lemma 3.3 (issue #167; replaces BlockList's plain-array bound
+ * index, whose splice-based maintenance paid O(#blocks) per split/drop).
+ *
+ * BlockList keeps its d1 blocks with non-decreasing value bounds. This tree
+ * stores that block sequence POSITIONALLY: a node's in-order position is its
+ * sequence position, and the tree itself never compares items. Because the
+ * bounds are monotone along the sequence, findFirst with a monotone
+ * predicate binary-searches the sequence in O(log size) — the paper's bound
+ * lookup — while insertBefore / append / remove stay O(log size) via AVL
+ * rebalancing.
+ *
+ * Nodes are plain objects { item, parent, left, right, height } returned as
+ * handles; callers keep the handle to later remove or iterate from it.
+ */
+class BoundIndex {
+  constructor() {
+    this.root = null;
+    this.count = 0;
+  }
+
+  // Number of items currently stored
+  get size() {
+    return this.count;
+  }
+
+  // Drop every item
+  clear() {
+    this.root = null;
+    this.count = 0;
+  }
+
+  // First node in sequence order, or null when empty
+  first() {
+    let node = this.root;
+    if (node === null) return null;
+    while (node.left !== null) node = node.left;
+    return node;
+  }
+
+  // Last node in sequence order, or null when empty
+  last() {
+    let node = this.root;
+    if (node === null) return null;
+    while (node.right !== null) node = node.right;
+    return node;
+  }
+
+  // In-order successor of a node, or null at the end of the sequence
+  next(node) {
+    if (node.right !== null) {
+      let succ = node.right;
+      while (succ.left !== null) succ = succ.left;
+      return succ;
+    }
+    let child = node;
+    let parent = child.parent;
+    while (parent !== null && parent.right === child) {
+      child = parent;
+      parent = parent.parent;
+    }
+    return parent;
+  }
+
+  /**
+   * Leftmost node whose item satisfies the predicate, or null when none
+   * does. The predicate must be monotone along the sequence (a prefix of
+   * false followed by a suffix of true) — with BlockList's non-decreasing
+   * bounds, `(block) => compare(block.bound, value) >= 0` is exactly that.
+   * O(log size).
+   * @param {(item: *) => boolean} predicate
+   * @returns {*} The matching node handle, or null
+   */
+  findFirst(predicate) {
+    let node = this.root;
+    let found = null;
+    while (node !== null) {
+      if (predicate(node.item)) {
+        found = node;
+        node = node.left;
+      } else {
+        node = node.right;
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Insert an item at the end of the sequence. O(log size).
+   * @returns {*} The new node handle
+   */
+  append(item) {
+    const node = this.makeNode(item);
+    if (this.root === null) {
+      this.root = node;
+    } else {
+      const tail = this.last();
+      tail.right = node;
+      node.parent = tail;
+      this.rebalance(tail);
+    }
+    this.count += 1;
+    return node;
+  }
+
+  /**
+   * Insert an item immediately before an existing node. O(log size).
+   * @param {*} reference - Node handle the new item goes in front of
+   * @returns {*} The new node handle
+   */
+  insertBefore(reference, item) {
+    const node = this.makeNode(item);
+    if (reference.left === null) {
+      reference.left = node;
+      node.parent = reference;
+    } else {
+      let pred = reference.left;
+      while (pred.right !== null) pred = pred.right;
+      pred.right = node;
+      node.parent = pred;
+    }
+    this.count += 1;
+    this.rebalance(node.parent);
+    return node;
+  }
+
+  /**
+   * Remove a node from the sequence. O(log size).
+   * @param {*} node - Node handle previously returned by append/insertBefore
+   */
+  remove(node) {
+    let start; // deepest structurally-changed node, where rebalancing begins
+    if (node.left === null) {
+      start = node.parent;
+      this.replaceInParent(node, node.right);
+    } else if (node.right === null) {
+      start = node.parent;
+      this.replaceInParent(node, node.left);
+    } else {
+      // Two children: splice out the in-order successor (which has no left
+      // child) and put it in the removed node's place
+      let succ = node.right;
+      while (succ.left !== null) succ = succ.left;
+      if (succ.parent === node) {
+        start = succ;
+      } else {
+        start = succ.parent;
+        this.replaceInParent(succ, succ.right);
+        succ.right = node.right;
+        succ.right.parent = succ;
+      }
+      this.replaceInParent(node, succ);
+      succ.left = node.left;
+      succ.left.parent = succ;
+      succ.height = node.height;
+    }
+    node.parent = node.left = node.right = null;
+    this.count -= 1;
+    this.rebalance(start);
+  }
+
+  // Internal: fresh leaf node
+  makeNode(item) {
+    return { item, parent: null, left: null, right: null, height: 1 };
+  }
+
+  // Internal: make replacement take node's place under node's parent
+  // (replacement may be null)
+  replaceInParent(node, replacement) {
+    const parent = node.parent;
+    if (parent === null) {
+      this.root = replacement;
+    } else if (parent.left === node) {
+      parent.left = replacement;
+    } else {
+      parent.right = replacement;
+    }
+    if (replacement !== null) replacement.parent = parent;
+  }
+
+  // Internal: height of a possibly-null subtree
+  heightOf(node) {
+    return node === null ? 0 : node.height;
+  }
+
+  // Internal: recompute a node's height from its children
+  updateHeight(node) {
+    node.height =
+      1 + Math.max(this.heightOf(node.left), this.heightOf(node.right));
+  }
+
+  // Internal: left-minus-right height difference
+  balanceOf(node) {
+    return this.heightOf(node.left) - this.heightOf(node.right);
+  }
+
+  // Internal: walk from node to the root, updating heights and rotating
+  // wherever the AVL invariant |balance| <= 1 broke (deletion can require a
+  // rotation at every level; insertion at most one — the loop covers both)
+  rebalance(node) {
+    while (node !== null) {
+      this.updateHeight(node);
+      const balance = this.balanceOf(node);
+      if (balance > 1) {
+        if (this.balanceOf(node.left) < 0) this.rotateLeft(node.left);
+        node = this.rotateRight(node);
+      } else if (balance < -1) {
+        if (this.balanceOf(node.right) > 0) this.rotateRight(node.right);
+        node = this.rotateLeft(node);
+      }
+      node = node.parent;
+    }
+  }
+
+  // Internal: standard AVL rotation; returns the subtree's new root
+  rotateLeft(node) {
+    const pivot = node.right;
+    node.right = pivot.left;
+    if (pivot.left !== null) pivot.left.parent = node;
+    this.replaceInParent(node, pivot);
+    pivot.left = node;
+    node.parent = pivot;
+    this.updateHeight(node);
+    this.updateHeight(pivot);
+    return pivot;
+  }
+
+  // Internal: mirror of rotateLeft
+  rotateRight(node) {
+    const pivot = node.left;
+    node.left = pivot.right;
+    if (pivot.right !== null) pivot.right.parent = node;
+    this.replaceInParent(node, pivot);
+    pivot.right = node;
+    node.parent = pivot;
+    this.updateHeight(node);
+    this.updateHeight(pivot);
+    return pivot;
+  }
+}
+
+export { BoundIndex };

package/src/findPivots.mjs

@@ -1,4 +1,9 @@
-import { compareKeys, toBound, makeTies, relaxEdge } from "./tieBreak.mjs";
+import {
+  compareKeyParts,
+  toBound,
+  relaxEdge,
+  RELAX_LOST,
+} from "./tieBreak.mjs";
 
 /**
  * FindPivots(B, S) — Algorithm 1 of "Breaking the Sorting Barrier for Directed
@@ -9,17 +14,19 @@ import { compareKeys, toBound, makeTies, relaxEdge } from "./tieBreak.mjs";
  * the pivots need to be carried into the deeper BMSSP recursion.
  *
  * Preconditions (guaranteed by the caller, Algorithm 3):
- * - Every vertex in S is complete (dHat holds its true distance).
+ * - Every vertex in S is complete (labels.dist holds its true distance).
  * - Every incomplete vertex v with d(v) < B has a shortest path through some
  *   complete vertex in S.
  *
- * Distance estimates are read from and written into dHat in place — exactly
- * like the paper's global d̂[·] labels, so improvements made here are visible
- * to the levels above. Relaxation is canonical (#163, src/tieBreak.mjs):
- * d̂, hops and preds move together under the composite [length, hops, id]
- * order, and an exact-equality result re-admits a vertex to W through its
- * one canonical label-setter (the paper's `≤` made deterministic). The `< B`
- * test only gates membership in W; d̂ updates are not gated.
+ * Since #205 the engine works on dense vertex indices: S holds indices, the
+ * graph is the class's CSR bundle, and the labels are the shared typed
+ * arrays (see tieBreak's makeLabels) — updated in place, exactly like the
+ * paper's global d̂[·], so improvements made here are visible to the levels
+ * above. Relaxation is canonical (#163): dist, hops and preds move together
+ * under the composite [length, hops, index] order, and an exact-equality
+ * result re-admits a vertex to W through its one canonical label-setter (the
+ * paper's `≤` made deterministic). The `< B` test only gates membership in
+ * W; label updates are not gated.
  *
  * The paper's tight-edge forest falls out of the canonical labels: each
  * vertex of W \ S hangs off its recorded canonical predecessor, which is
@@ -38,19 +45,20 @@ import { compareKeys, toBound, makeTies, relaxEdge } from "./tieBreak.mjs";
  *
  * @param {number|[number, number, *]} B - Strict upper bound gating membership
  *   in W: a number (Infinity is allowed) or a composite bound
- * @param {Set<*>|Iterable<*>} S - Non-empty set of complete frontier sources
- * @param {Map<*, number>} dHat - Global distance estimates d̂[·], updated in place
- * @param {Map<*, Array<[*, number]>>} adjacency - nodeId -> outgoing [to, weight] edges
+ * @param {Set<number>|Iterable<number>} S - Non-empty set of complete frontier
+ *   source indices
+ * @param {{ dist: Float64Array, hops: Uint32Array, preds: Int32Array }} labels
+ *   - Engine label state (d̂[·] and tie-break labels), updated in place
+ * @param {{ offsets: Uint32Array, targets: Uint32Array, weights: Float64Array }} csr
+ *   - The graph in CSR layout over dense indices
  * @param {number} k - Relaxation rounds / tree-size threshold, >= 1 (floored);
  *   the paper's ⌊log^(1/3) n⌋
- * @param {{ hops: Map<*, number>, preds: Map<*, *> }} [ties] - Canonical
- *   tie-break labels updated alongside dHat; fresh throwaway maps by default
- * @returns {{ pivots: Set<*>, W: Set<*> }} The pivot subset of S and the set W
- *   of vertices touched below B (W always contains S)
+ * @returns {{ pivots: Set<number>, W: Set<number> }} The pivot subset of S and
+ *   the set W of vertex indices touched below B (W always contains S)
  * @throws {Error} If k is not a number >= 1, S is empty, or any source has no
  *   finite distance estimate
  */
-function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
+function findPivots(B, S, labels, csr, k) {
   if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
     throw new Error("k must be a number >= 1");
   }
@@ -60,12 +68,12 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
     throw new Error("S must contain at least one source node");
   }
   for (const x of sources) {
-    const distance = dHat.get(x);
-    if (typeof distance !== "number" || !Number.isFinite(distance)) {
+    if (!Number.isFinite(labels.dist[x])) {
       throw new Error("every source must have a finite distance estimate");
     }
   }
   const boundKey = toBound(B);
+  const { offsets, targets, weights } = csr;
 
   // W accumulates everything relaxed below B; layer is the paper's W_{i-1}
   const sourceSet = new Set(sources);
@@ -75,12 +83,18 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
   for (let i = 1; i <= rounds; i += 1) {
     const nextLayer = new Set();
     for (const u of layer) {
-      for (const [v, weight] of adjacency.get(u) ?? []) {
-        // Canonical relaxation: d̂ updates are not gated by B (paper), and
-        // both improvements and exact canonical equality admit v to the
-        // next layer when its key is below B
-        const relaxed = relaxEdge(u, v, weight, dHat, ties);
-        if (relaxed !== null && compareKeys(relaxed.key, boundKey) < 0) {
+      for (let e = offsets[u]; e < offsets[u + 1]; e += 1) {
+        const v = targets[e];
+        // Canonical relaxation: label updates are not gated by B (paper),
+        // and both improvements and exact canonical equality admit v to the
+        // next layer when its key is below B. Non-lost ⇒ v's stored label
+        // is the candidate, so the W gate compares the unpacked stored
+        // components — no key allocation (#168).
+        const result = relaxEdge(u, v, weights[e], labels);
+        if (
+          result !== RELAX_LOST &&
+          compareKeyParts(labels.dist[v], labels.hops[v], v, boundKey) < 0
+        ) {
           nextLayer.add(v);
         }
       }
@@ -99,7 +113,7 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
   const children = new Map();
   for (const v of W) {
     if (sourceSet.has(v)) continue;
-    const parent = ties.preds.get(v);
+    const parent = labels.preds[v];
     if (!children.has(parent)) children.set(parent, []);
     children.get(parent).push(v);
   }

package/src/graph.mjs

@@ -0,0 +1,174 @@
+// #172 — typed / flexible graph inputs.
+//
+// A small builder (`Graph`) plus a normalizer (`normalizeGraphInput`) that
+// lets the BMSSP constructor accept several input shapes and reduce them to
+// one canonical internal form: `{ edges: [[from, to, weight], ...],
+// vertices: [id, ...] }`.
+//
+// `vertices` carries the EXPLICIT vertex universe — every node the caller
+// declared, including isolated ones with no incident edges. Edge endpoints
+// are still folded in by the BMSSP constructor, so an empty `vertices`
+// (the plain edge-list form) reproduces the pre-#172 "infer nodes from
+// edges" behavior exactly.
+//
+// Node-ID semantics are unchanged from earlier versions: IDs are finite
+// numbers. Value validation (finite IDs, finite non-negative weights) with
+// the "Edge at index N" messages stays in the BMSSP constructor so there is
+// a single source of truth; the pieces here validate only what they must to
+// build a well-formed normalized shape (and the builder validates eagerly at
+// the call site for a friendlier failure).
+
+/**
+ * A tiny mutable graph builder. Declare vertices (including isolated ones)
+ * and directed weighted edges, then hand the instance straight to
+ * `new BMSSP(graph)`.
+ *
+ * All mutators return `this`, so calls chain:
+ * `new Graph().addEdge(0, 1, 50).addEdge(1, 2, 75).addVertex(9)`.
+ *
+ * Node IDs must be finite numbers and weights finite and non-negative — the
+ * same contract the edge-array form has always enforced.
+ */
+class Graph {
+  constructor() {
+    // Declared vertex universe (numbers). addEdge folds in its endpoints too.
+    this._vertices = new Set();
+    // Declared directed edges as [from, to, weight] triples.
+    this._edges = [];
+  }
+
+  /**
+   * Declare a vertex. Safe to call for a node that already exists (idempotent)
+   * and the only way to introduce an isolated vertex (one with no edges).
+   * @param {number} id finite node ID
+   * @returns {Graph} this
+   */
+  addVertex(id) {
+    if (!Number.isFinite(id)) {
+      throw new Error("Graph.addVertex: node id must be a finite number");
+    }
+    this._vertices.add(id);
+    return this;
+  }
+
+  /**
+   * Add a directed edge `from -> to` of the given weight. Both endpoints are
+   * declared automatically.
+   * @param {number} from finite source node ID
+   * @param {number} to finite target node ID
+   * @param {number} weight finite, non-negative edge weight
+   * @returns {Graph} this
+   */
+  addEdge(from, to, weight) {
+    if (!Number.isFinite(from) || !Number.isFinite(to)) {
+      throw new Error("Graph.addEdge: node ids must be finite numbers");
+    }
+    if (!Number.isFinite(weight) || weight < 0) {
+      throw new Error(
+        "Graph.addEdge: weight must be a finite, non-negative number",
+      );
+    }
+    this._vertices.add(from);
+    this._vertices.add(to);
+    this._edges.push([from, to, weight]);
+    return this;
+  }
+
+  /** @param {number} id @returns {boolean} whether the vertex is declared */
+  hasVertex(id) {
+    return this._vertices.has(id);
+  }
+
+  /** @returns {number} number of declared vertices */
+  get vertexCount() {
+    return this._vertices.size;
+  }
+
+  /** @returns {number} number of declared edges */
+  get edgeCount() {
+    return this._edges.length;
+  }
+
+  /**
+   * The canonical normalized form the BMSSP constructor consumes. Returns
+   * fresh copies so later mutation of this builder cannot affect a graph
+   * already constructed from it.
+   * @returns {{ edges: number[][], vertices: number[] }}
+   */
+  toNormalized() {
+    return {
+      edges: this._edges.map((edge) => [...edge]),
+      vertices: [...this._vertices],
+    };
+  }
+}
+
+function isIterable(value) {
+  return value != null && typeof value[Symbol.iterator] === "function";
+}
+
+/**
+ * Reduce an adjacency form to `{ edges, vertices }`. Each entry maps a source
+ * node to an iterable of `[to, weight]` pairs; the source is always declared
+ * (so a node with an empty/absent neighbor list becomes an isolated vertex).
+ * When `coerceKeys` is set (plain-object form, whose keys are strings), the
+ * source key is converted to a number — finiteness is then checked by the
+ * BMSSP constructor's vertex validation.
+ */
+function adjacencyToNormalized(entries, coerceKeys) {
+  const edges = [];
+  const vertices = [];
+  for (const [rawFrom, neighbors] of entries) {
+    const from = coerceKeys ? Number(rawFrom) : rawFrom;
+    vertices.push(from);
+    if (neighbors == null) continue;
+    if (!isIterable(neighbors)) {
+      throw new Error(
+        `Adjacency list for node ${rawFrom} must be an iterable of [to, weight]`,
+      );
+    }
+    for (const pair of neighbors) {
+      if (!Array.isArray(pair) || pair.length !== 2) {
+        throw new Error(
+          `Adjacency entry for node ${rawFrom} must be [to, weight]`,
+        );
+      }
+      edges.push([from, pair[0], pair[1]]);
+    }
+  }
+  return { edges, vertices };
+}
+
+/**
+ * Normalize any accepted graph input into `{ edges, vertices }`:
+ * - a `Graph` builder instance,
+ * - an edge array `[[from, to, weight], ...]` (vertices inferred from edges),
+ * - an adjacency `Map<from, Iterable<[to, weight]>>`, or
+ * - a plain adjacency object `{ from: [[to, weight], ...] }` (numeric-string
+ *   keys, coerced to numbers).
+ *
+ * Only structural checks live here; per-edge value validation stays in the
+ * BMSSP constructor so its "Edge at index N" messages remain the single
+ * source of truth.
+ * @param {*} input
+ * @returns {{ edges: number[][], vertices: number[] }}
+ */
+function normalizeGraphInput(input) {
+  if (input instanceof Graph) {
+    return input.toNormalized();
+  }
+  if (Array.isArray(input)) {
+    return { edges: input, vertices: [] };
+  }
+  if (input instanceof Map) {
+    return adjacencyToNormalized(input.entries(), false);
+  }
+  if (input !== null && typeof input === "object") {
+    return adjacencyToNormalized(Object.entries(input), true);
+  }
+  throw new Error(
+    "Input graph must be an edge array, an adjacency map/object, or a Graph instance",
+  );
+}
+
+export { Graph, normalizeGraphInput };

package/src/select.mjs

@@ -0,0 +1,144 @@
+/**
+ * Deterministic worst-case-linear selection — the "linear-time median
+ * selection" Lemma 3.3 prescribes for BlockList block splits, batch
+ * chunking and pulls (issue #167; replaces the sort-based O(M log M)
+ * shortcut).
+ *
+ * Introselect construction: quickselect with a deterministic median-of-3
+ * pivot (~2–3n comparisons on typical inputs — well below a sort's n log n)
+ * guarded by a work budget. If pathological pivots exhaust the budget, the
+ * pivot switches to median-of-medians (groups of 5), whose guaranteed
+ * middle-40% pivot makes the remainder linear — so the whole selection is
+ * O(n) worst case. Median-of-medians alone would also be linear but costs
+ * ~10–20n comparisons, MORE than sorting at practical sizes; the budgeted
+ * hybrid keeps both the bound and the constant. No randomness anywhere:
+ * runs stay fully reproducible.
+ */
+
+// Internal: swap two array slots
+function swap(items, i, j) {
+  const tmp = items[i];
+  items[i] = items[j];
+  items[j] = tmp;
+}
+
+// Internal: insertion-sort the closed range [lo, hi] (only ever called on
+// ranges of at most 5 elements)
+function sortRange(items, lo, hi, compare) {
+  for (let i = lo + 1; i <= hi; i += 1) {
+    const item = items[i];
+    let j = i - 1;
+    while (j >= lo && compare(items[j], item) > 0) {
+      items[j + 1] = items[j];
+      j -= 1;
+    }
+    items[j + 1] = item;
+  }
+}
+
+// Internal: cheap deterministic pivot — median of the first, middle and
+// last elements of the range
+function medianOfThree(items, lo, hi, compare) {
+  const first = items[lo];
+  const middle = items[lo + ((hi - lo) >> 1)];
+  const last = items[hi];
+  if (compare(first, middle) < 0) {
+    if (compare(middle, last) < 0) return middle;
+    return compare(first, last) < 0 ? last : first;
+  }
+  if (compare(first, last) < 0) return first;
+  return compare(middle, last) < 0 ? last : middle;
+}
+
+// Internal: median-of-medians pivot for the closed range [lo, hi] — the
+// budget-exhausted fallback. Sorts each group of 5, gathers the group
+// medians at the front of the range, and recursively selects their median;
+// the result splits the range at worst 30/70.
+function medianOfMedians(items, lo, hi, compare) {
+  let write = lo;
+  for (let i = lo; i <= hi; i += 5) {
+    const groupHi = Math.min(i + 4, hi);
+    sortRange(items, i, groupHi, compare);
+    swap(items, write, i + ((groupHi - i) >> 1));
+    write += 1;
+  }
+  const mid = lo + ((write - 1 - lo) >> 1);
+  selectRange(items, mid, compare, lo, write - 1, 6 * (write - lo));
+  return items[mid];
+}
+
+// Internal: budgeted quickselect on the closed range [lo, hi]. Elements
+// outside the active range are already on their correct side, so when the
+// range narrows to the rank (or the rank falls inside the pivot-equal band)
+// the whole prefix [0..rank] holds the rank+1 smallest.
+function selectRange(items, rank, compare, lo, hi, budget) {
+  while (lo < hi) {
+    if (hi - lo < 5) {
+      sortRange(items, lo, hi, compare);
+      return;
+    }
+    const size = hi - lo + 1;
+    const pivot =
+      budget > 0
+        ? medianOfThree(items, lo, hi, compare)
+        : medianOfMedians(items, lo, hi, compare);
+    budget -= size;
+    // Three-way partition: [lo, lt) < pivot, [lt, gt] == pivot, (gt, hi] >
+    // pivot. The equal band makes duplicate-heavy inputs terminate in one
+    // round instead of degrading.
+    let lt = lo;
+    let i = lo;
+    let gt = hi;
+    while (i <= gt) {
+      const order = compare(items[i], pivot);
+      if (order < 0) {
+        swap(items, lt, i);
+        lt += 1;
+        i += 1;
+      } else if (order > 0) {
+        swap(items, i, gt);
+        gt -= 1;
+      } else {
+        i += 1;
+      }
+    }
+    if (rank < lt) {
+      hi = lt - 1;
+    } else if (rank > gt) {
+      lo = gt + 1;
+    } else {
+      return;
+    }
+  }
+}
+
+/**
+ * Partially reorder items IN PLACE so that items[0..rank] are the rank+1
+ * smallest under compare and items[rank] is the largest of them (i.e. the
+ * rank-th smallest overall, 0-indexed). Order within the two sides is
+ * unspecified — exactly what a semi-sorted block structure needs.
+ * @param {Array<*>} items - Reordered in place
+ * @param {number} rank - 0-indexed target rank, 0 <= rank < items.length
+ * @param {(a: *, b: *) => number} [compare] - Comparator (negative when
+ *   a < b). Defaults to numeric order.
+ * @param {number} [cheapBudget] - Elements the median-of-3 phase may visit
+ *   before pivots switch to median-of-medians. Defaults to 6·items.length
+ *   (never reached on non-adversarial inputs); pass 0 to force the
+ *   median-of-medians path throughout (used by tests).
+ * @returns {*} items[rank], the rank-th smallest element
+ * @throws {Error} If items is not a non-empty array or rank is out of range
+ */
+function partitionByRank(items, rank, compare, cheapBudget) {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error("items must be a non-empty array");
+  }
+  if (!Number.isInteger(rank) || rank < 0 || rank >= items.length) {
+    throw new Error("rank must be an integer index into items");
+  }
+  const order = compare ?? ((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const budget = cheapBudget ?? 6 * items.length;
+  selectRange(items, rank, order, 0, items.length - 1, budget);
+  return items[rank];
+}
+
+export { partitionByRank };