bmssp 1.1.1 → 1.2.0

package/README.md

@@ -36,6 +36,8 @@ with every building block shipped, tested, and released individually:
 | Opt-in constant-degree transform, in/out-degree ≤ 2 ([#164](https://github.com/Sirivasv/bmssp-js/issues/164)) | `constantDegreeTransform()` | ✅ done |
 | BMSSP-vs-Dijkstra head-to-head in the benchmark harness ([#170](https://github.com/Sirivasv/bmssp-js/issues/170)) | `npm run bench` / `npm run bench:counts` | ✅ done |
 | Performance-cliff investigation; quadratic `BatchPrepend` fixed ([#182](https://github.com/Sirivasv/bmssp-js/issues/182)) | `src/blockList.mjs` | ✅ done — **1.1.1** |
+| Exact Lemma 3.3 asymptotics: balanced-BST bound index + linear-time selection ([#167](https://github.com/Sirivasv/bmssp-js/issues/167)) | `src/boundIndex.mjs` + `src/select.mjs` | ✅ done |
+| Relaxation micro-optimizations: allocation-free hot loops, −13–23% wall-clock ([#168](https://github.com/Sirivasv/bmssp-js/issues/168)) | `src/tieBreak.mjs` + the algorithm modules | ✅ done — **1.2.0** |
 
 > **Honest note:** the paper's win is asymptotic, and this repo optimizes for correctness
 > and readability, not raw speed. Measured head-to-head (algorithm time only, graph
@@ -44,10 +46,13 @@ with every building block shipped, tested, and released individually:
 > Dijkstra still wins on wall-clock at every practical size, though the gap narrows as
 > sparse graphs grow (2.5× at 50k nodes → 1.57× at 2M). But in the paper's own metric —
 > **comparisons between path lengths** — BMSSP does **fewer comparisons than Dijkstra
-> from about n = 1M on sparse graphs** (`npm run bench:counts` measures the ratio falling
-> 1.20× at 50k → 1.03× at 200k → 0.98× at 1M; 0.91× at 2M in the record), and the
-> advantage grows with size: the "sorting barrier" is measurably broken; what remains is
-> JS constant factors. The two performance cliffs found in the 1.0.0 measurements were
+> from under n = 50k on sparse graphs** (`npm run bench:counts` measures 0.95× at 50k →
+> 0.76× at 200k → **0.65× at 1M**), and the advantage grows with size: the "sorting
+> barrier" is measurably broken; what remains is JS constant factors. That crossover
+> used to sit at ~n = 1M until [#167](https://github.com/Sirivasv/bmssp-js/issues/167)
+> replaced the block structure's sort-based internals with the paper's exact machinery
+> (balanced-BST bound index + deterministic linear-time selection).
+> The two performance cliffs found in the 1.0.0 measurements were
 > run down in [#182](https://github.com/Sirivasv/bmssp-js/issues/182): the star-graph
 > blowup was a quadratic in `BatchPrepend`'s bookkeeping — fixed in `1.1.1` (500k-node
 > star: 61 s → ~3 s) — and the recursion-level step is an inherent, measured ~+24% per
@@ -70,8 +75,9 @@ with every building block shipped, tested, and released individually:
    closest batch without paying the Θ(log n)-per-vertex "sorting barrier."
 
 The wall-clock crossover point is astronomically large, but the asymptotics are real: in
-measured comparison counts this implementation already beats Dijkstra past ~1M nodes on
-sparse graphs ([benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)). This repo
+measured comparison counts this implementation already beats Dijkstra from under 50k
+nodes on sparse graphs, by a third at 1M
+([benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)). This repo
 optimizes for a **correct, readable, well-tested** implementation, validated line-by-line
 against a Dijkstra oracle — not for raw speed.
 
@@ -183,8 +189,8 @@ graphs in a few seconds), and set `FUZZ_XL=1` for an additional 2-million-node r
 | --- | --- | --- |
 | [`1.0.0`](https://github.com/Sirivasv/bmssp-js/milestones) | First end-to-end functional BMSSP (issues #40–#45) | ✅ done |
 | `1.1.0` | Correctness hardening — fuzz tests, edge cases, tie-breaking, input validation, constant-degree transform, API docs | ✅ done |
-| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, BMSSP-vs-Dijkstra benchmarks, performance-cliff investigation | 🔨 current focus |
-| `2.0.0` | API generalization — public multi-source/bounded entry point, flexible inputs | planned |
+| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, BMSSP-vs-Dijkstra benchmarks, cliff investigation, relaxation micro-optimizations | ✅ done |
+| `2.0.0` | API generalization — public multi-source/bounded entry point, flexible inputs | 🔨 next |
 
 ## Contributing (humans and AI agents welcome)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [

package/src/baseCase.mjs

@@ -5,6 +5,7 @@ import {
   makeTies,
   orderKey,
   relaxEdge,
+  RELAX_LOST,
 } from "./tieBreak.mjs";
 
 /**
@@ -76,18 +77,25 @@ function baseCase(B, S, dHat, adjacency, k, ties = makeTies()) {
   while (!heap.isEmpty() && settled.size < cap + 1) {
     const { key: u } = heap.extractMin();
     settled.add(u);
-    for (const [v, weight] of adjacency.get(u) ?? []) {
+    const edges = adjacency.get(u);
+    if (edges === undefined) continue;
+    for (let i = 0; i < edges.length; i += 1) {
+      const edge = edges[i];
+      const v = edge[0];
       // Canonical relaxation, gated by the bound (the paper's `< B`). An
       // exact-equality result means u is v's recorded label-setter (v was
       // labeled by an earlier phase without being completed) and v must be
       // (re-)enqueued — unless this very call already settled it, which is
       // what keeps zero-weight plateaus finite.
-      const relaxed = relaxEdge(u, v, weight, dHat, ties, boundKey);
-      if (relaxed === null || settled.has(v)) continue;
+      const result = relaxEdge(u, v, edge[1], dHat, ties, boundKey);
+      if (result === RELAX_LOST || settled.has(v)) continue;
+      // Non-lost ⇒ v's stored label IS the candidate; materialize its key
+      // only here, on the enqueue path (#168)
+      const key = orderKey(v, dHat, ties);
       if (heap.has(v)) {
-        heap.decreaseKey(v, relaxed.key);
+        heap.decreaseKey(v, key);
       } else {
-        heap.insert(v, relaxed.key);
+        heap.insert(v, key);
       }
     }
   }

package/src/blockList.mjs

@@ -1,3 +1,6 @@
+import { BoundIndex } from "./boundIndex.mjs";
+import { partitionByRank } from "./select.mjs";
+
 /**
  * Block-based "partial-sort" structure D from Lemma 3.3 of the BMSSP paper
  * ("Breaking the Sorting Barrier for Directed Single-Source Shortest Paths").
@@ -11,12 +14,16 @@
  * Internal layout:
  * - d1: blocks filled by insert(). Each block carries an upper bound on its
  *   values; bounds are non-decreasing across blocks, and the last block
- *   always has bound B so every value < B has a home.
- * - d0: blocks filled by batchPrepend() only; they conceptually sit in front
- *   of d1 (their values are smaller than everything inserted so far).
+ *   always has bound B so every value < B has a home. The sequence lives in
+ *   a self-balancing BST (BoundIndex) searched through the monotone bounds.
+ * - d0: blocks filled by batchPrepend() only, kept as a doubly-linked list;
+ *   they conceptually sit in front of d1 (their values are smaller than
+ *   everything inserted so far).
  *
- * The block-bound index is a plain array searched with binary search instead
- * of the paper's balanced BST — same behavior, worse constants (issue #167).
+ * Since #167 the structure meets Lemma 3.3's exact bounds: the bound index
+ * is a balanced BST (O(log #blocks) search/split/drop instead of O(#blocks)
+ * array splices) and splits/chunking/pulls use deterministic linear-time
+ * selection (partitionByRank) instead of an O(M log M) sort.
  */
 class BlockList {
   /**
@@ -35,17 +42,26 @@ class BlockList {
     this.M = Math.floor(M);
     this.B = B;
     this.compare = compare ?? ((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    // d1 starts as a single empty block with upper bound B
-    this.d1 = [this.makeBlock(B)];
-    this.d0 = [];
+    // Shared [key, value]-pair comparator for splits/chunking/pulls, hoisted
+    // so the hot paths don't allocate a closure per call
+    this.compareBySecond = (a, b) => this.compare(a[1], b[1]);
+    // d1 starts as a single empty block with upper bound B; that block is
+    // kept as the sequence's last forever so every value < B has a home
+    this.d1 = new BoundIndex();
+    this.lastD1Block = this.makeBlock(this.B);
+    this.lastD1Block.node = this.d1.append(this.lastD1Block);
+    // d0 is a doubly-linked list of blocks; the head holds the smallest values
+    this.d0Head = null;
     // key -> block currently holding that key, for O(1) duplicate handling
     this.locator = new Map();
     this.count = 0;
   }
 
-  // Internal: create an empty block with the given value upper bound
+  // Internal: create an empty block with the given value upper bound.
+  // node is the handle in the d1 BoundIndex (null for d0 blocks);
+  // prev/next thread the d0 linked list (null for d1 blocks).
   makeBlock(bound) {
-    return { bound, entries: new Map() };
+    return { bound, entries: new Map(), node: null, prev: null, next: null };
   }
 
   // Number of pairs currently stored
@@ -73,43 +89,37 @@ class BlockList {
       if (this.compare(holder.entries.get(key), value) <= 0) return;
       this.removeKey(key, holder);
     }
-    // Binary-search d1 for the first block whose bound covers the value
-    let lo = 0;
-    let hi = this.d1.length - 1;
-    while (lo < hi) {
-      const mid = (lo + hi) >> 1;
-      if (this.compare(this.d1[mid].bound, value) >= 0) {
-        hi = mid;
-      } else {
-        lo = mid + 1;
-      }
-    }
-    const block = this.d1[lo];
+    // First d1 block whose bound covers the value: bounds are monotone along
+    // the sequence, so this predicate search is the paper's O(log #blocks)
+    // BST lookup. It always succeeds — the last block's bound is B > value.
+    const node = this.d1.findFirst(
+      (candidate) => this.compare(candidate.bound, value) >= 0,
+    );
+    const block = node.item;
     block.entries.set(key, value);
     this.locator.set(key, block);
     this.count += 1;
     if (block.entries.size > this.M) {
-      this.splitBlock(lo);
+      this.splitBlock(block);
     }
   }
 
   // Internal: split an overfull d1 block into two halves around its median
-  // value. The lower half gets bound = its own max value; the upper half
-  // keeps the original bound, so inter-block ordering is preserved.
-  // (The paper uses linear-time median selection; sorting is O(M log M) but
-  // simpler — acceptable for this correctness-first implementation.)
-  splitBlock(index) {
-    const block = this.d1[index];
-    const sorted = [...block.entries].sort((a, b) => this.compare(a[1], b[1]));
-    const half = sorted.length >> 1;
-    const lower = this.makeBlock(sorted[half - 1][1]);
+  // value (deterministic linear-time selection, as Lemma 3.3 prescribes).
+  // The lower half gets bound = the median (its own max value); the upper
+  // half keeps the original bound, so inter-block ordering is preserved.
+  splitBlock(block) {
+    const pairs = [...block.entries];
+    const half = pairs.length >> 1;
+    partitionByRank(pairs, half - 1, this.compareBySecond);
+    const lower = this.makeBlock(pairs[half - 1][1]);
     for (let i = 0; i < half; i += 1) {
-      const [key, value] = sorted[i];
+      const [key, value] = pairs[i];
       block.entries.delete(key);
       lower.entries.set(key, value);
       this.locator.set(key, lower);
     }
-    this.d1.splice(index, 0, lower);
+    lower.node = this.d1.insertBefore(block.node, lower);
   }
 
   /**
@@ -144,23 +154,34 @@ class BlockList {
       fresh.push([key, value]);
     }
     if (fresh.length === 0) return;
-    // One block if the batch fits, otherwise sorted chunks of <= ceil(M/2)
+    // One block if the batch fits; otherwise value-ordered chunks of
+    // <= ceil(M/2) — O(|L|/M) blocks built with O(|L|·max{1, log(|L|/M)})
+    // comparisons, the Lemma 3.3 bound
     let chunks;
     if (fresh.length <= this.M) {
       chunks = [fresh];
     } else {
-      fresh.sort((a, b) => this.compare(a[1], b[1]));
       const chunkSize = Math.ceil(this.M / 2);
       chunks = [];
-      for (let i = 0; i < fresh.length; i += chunkSize) {
-        chunks.push(fresh.slice(i, i + chunkSize));
+      if (fresh.length >= chunkSize * chunkSize) {
+        // Many chunks (|L| >= chunkSize², e.g. the M = 1 star regime, where
+        // |L|/M ~ |L|): sorting's O(|L| log |L|) is within 2x of the
+        // O(|L| log(|L|/chunkSize)) target — |L| >= c² gives
+        // log |L| <= 2 log(|L|/c) — and a single sort is much faster than
+        // log(|L|/M) rounds of median selection
+        fresh.sort(this.compareBySecond);
+        for (let i = 0; i < fresh.length; i += chunkSize) {
+          chunks.push(fresh.slice(i, i + chunkSize));
+        }
+      } else {
+        // Few chunks (|L| < chunkSize²): repeated median splitting — here
+        // the recursion is at most log2(chunkSize) levels deep, and a sort
+        // would overshoot the Lemma bound (up to O(|L| log |L|) for
+        // O(|L| log(|L|/M)) with |L| close to M)
+        this.chunkByMedian(fresh, chunkSize, chunks);
       }
     }
-    // Materialize the chunks as blocks (ascending, so chunk 0 — the smallest
-    // values — ends up frontmost) and prepend them all in one concat. A
-    // per-chunk unshift here re-shifts the whole d0 array every time: with a
-    // small M the chunk count approaches |L| and the loop turns quadratic —
-    // the #182 star-graph blowup (~n single-entry chunks at M = 1).
+    // Materialize the chunks as blocks (ascending order)...
     const blocks = [];
     for (const chunk of chunks) {
       // Seed the block bound with the first value, then max-update — avoids
@@ -174,7 +195,28 @@ class BlockList {
       }
       blocks.push(block);
     }
-    this.d0 = blocks.concat(this.d0);
+    // ...and link them in front of d0, smallest chunk becoming the new head
+    let head = this.d0Head;
+    for (let i = blocks.length - 1; i >= 0; i -= 1) {
+      const block = blocks[i];
+      block.next = head;
+      if (head !== null) head.prev = block;
+      head = block;
+    }
+    this.d0Head = head;
+  }
+
+  // Internal: recursively median-split pairs (in place / via slices) into
+  // value-ordered chunks of at most maxSize, appended to out ascending
+  chunkByMedian(pairs, maxSize, out) {
+    if (pairs.length <= maxSize) {
+      out.push(pairs);
+      return;
+    }
+    const half = pairs.length >> 1;
+    partitionByRank(pairs, half - 1, this.compareBySecond);
+    this.chunkByMedian(pairs.slice(0, half), maxSize, out);
+    this.chunkByMedian(pairs.slice(half), maxSize, out);
   }
 
   /**
@@ -189,8 +231,10 @@ class BlockList {
     if (this.count <= this.M) {
       // Everything fits in one batch: drain the structure and reset it
       const keys = new Set(this.locator.keys());
-      this.d0 = [];
-      this.d1 = [this.makeBlock(this.B)];
+      this.d0Head = null;
+      this.d1.clear();
+      this.lastD1Block = this.makeBlock(this.B);
+      this.lastD1Block.node = this.d1.append(this.lastD1Block);
       this.locator.clear();
       this.count = 0;
       return { keys, bound: this.B };
@@ -198,18 +242,31 @@ class BlockList {
     // Collect prefix blocks from each sequence until that side holds >= M
     // candidate elements (or runs out). The M smallest overall are in there.
     const candidates = [];
-    for (const seq of [this.d0, this.d1]) {
-      let collected = 0;
-      for (const block of seq) {
-        if (collected >= this.M) break;
-        for (const [key, value] of block.entries) {
-          candidates.push([key, value, block]);
-        }
-        collected += block.entries.size;
+    let collected = 0;
+    for (
+      let block = this.d0Head;
+      block !== null && collected < this.M;
+      block = block.next
+    ) {
+      for (const [key, value] of block.entries) {
+        candidates.push([key, value, block]);
       }
+      collected += block.entries.size;
     }
-    // Take the M smallest candidates out of the structure
-    candidates.sort((a, b) => this.compare(a[1], b[1]));
+    collected = 0;
+    for (
+      let node = this.d1.first();
+      node !== null && collected < this.M;
+      node = this.d1.next(node)
+    ) {
+      for (const [key, value] of node.item.entries) {
+        candidates.push([key, value, node.item]);
+      }
+      collected += node.item.entries.size;
+    }
+    // Move the M smallest candidates to the front (linear-time selection,
+    // the Lemma 3.3 O(M) pull) and take them out of the structure
+    partitionByRank(candidates, this.M - 1, this.compareBySecond);
     const keys = new Set();
     for (let i = 0; i < this.M; i += 1) {
       const [key, , block] = candidates[i];
@@ -222,12 +279,20 @@ class BlockList {
     // Under a strict total order (#163's composite keys) this separator is
     // strictly above every pulled value — no boundary ties.
     let bound = null;
-    for (const seq of [this.d0, this.d1]) {
-      const block = seq.find((b) => b.entries.size > 0);
-      if (block) {
+    for (let block = this.d0Head; block !== null; block = block.next) {
+      if (block.entries.size > 0) {
         for (const value of block.entries.values()) {
           if (bound === null || this.compare(value, bound) < 0) bound = value;
         }
+        break;
+      }
+    }
+    for (let node = this.d1.first(); node !== null; node = this.d1.next(node)) {
+      if (node.item.entries.size > 0) {
+        for (const value of node.item.entries.values()) {
+          if (bound === null || this.compare(value, bound) < 0) bound = value;
+        }
+        break;
       }
     }
     return { keys, bound };
@@ -244,18 +309,18 @@ class BlockList {
     }
   }
 
-  // Internal: physically remove an emptied block. The last d1 block (bound B)
-  // is kept even when empty so insert always finds a home for any value < B.
+  // Internal: physically remove an emptied block from its sequence — an
+  // O(log #blocks) BST removal for d1, an O(1) unlink for d0. The last d1
+  // block (bound B) is kept even when empty so insert always finds a home.
   dropIfEmpty(block) {
-    const i0 = this.d0.indexOf(block);
-    if (i0 !== -1) {
-      this.d0.splice(i0, 1);
+    if (block.node !== null) {
+      if (block === this.lastD1Block) return;
+      this.d1.remove(block.node);
       return;
     }
-    const i1 = this.d1.indexOf(block);
-    if (i1 !== -1 && i1 < this.d1.length - 1) {
-      this.d1.splice(i1, 1);
-    }
+    if (block.prev !== null) block.prev.next = block.next;
+    else this.d0Head = block.next;
+    if (block.next !== null) block.next.prev = block.prev;
   }
 }
 

package/src/bmssp.mjs

@@ -3,10 +3,12 @@ import { findPivots } from "./findPivots.mjs";
 import { BlockList } from "./blockList.mjs";
 import {
   compareKeys,
+  compareKeyParts,
   toBound,
   makeTies,
   orderKey,
   relaxEdge,
+  RELAX_LOST,
 } from "./tieBreak.mjs";
 
 class BMSSP {
@@ -224,19 +226,26 @@ class BMSSP {
       // without completing (the paper's `≤` relaxation, deterministic here:
       // only the recorded label-setter triggers it); vertices already
       // completed at this level are filtered so re-enqueues stay finite.
+      // A non-lost relaxation leaves v's stored label equal to the
+      // candidate, so the band tests compare the unpacked stored components
+      // and a key array is built only for the enqueue itself (#168).
       const K = [];
       for (const u of Ui) {
-        for (const [v, weight] of this.adjacency.get(u) ?? []) {
-          const relaxed = relaxEdge(u, v, weight, dHat, ties);
-          if (relaxed === null || U.has(v)) continue;
-          const key = relaxed.key;
-          if (compareKeys(key, BiKey) >= 0 && compareKeys(key, boundKey) < 0) {
-            D.insert(v, key);
-          } else if (
-            compareKeys(key, BiPrimeKey) >= 0 &&
-            compareKeys(key, BiKey) < 0
-          ) {
-            K.push([v, key]);
+        const edges = this.adjacency.get(u);
+        if (edges === undefined) continue;
+        for (let i = 0; i < edges.length; i += 1) {
+          const edge = edges[i];
+          const v = edge[0];
+          const result = relaxEdge(u, v, edge[1], dHat, ties);
+          if (result === RELAX_LOST || U.has(v)) continue;
+          const length = dHat.get(v);
+          const hopCount = ties.hops.get(v) ?? 0;
+          if (compareKeyParts(length, hopCount, v, BiKey) >= 0) {
+            if (compareKeyParts(length, hopCount, v, boundKey) < 0) {
+              D.insert(v, [length, hopCount, v]);
+            }
+          } else if (compareKeyParts(length, hopCount, v, BiPrimeKey) >= 0) {
+            K.push([v, [length, hopCount, v]]);
           }
         }
       }
@@ -244,9 +253,13 @@ class BMSSP {
       // go back in front of everything else
       for (const x of Si) {
         if (U.has(x)) continue;
-        const key = orderKey(x, dHat, ties);
-        if (compareKeys(key, BiPrimeKey) >= 0 && compareKeys(key, BiKey) < 0) {
-          K.push([x, key]);
+        const length = dHat.get(x) ?? Infinity;
+        const hopCount = ties.hops.get(x) ?? 0;
+        if (
+          compareKeyParts(length, hopCount, x, BiKey) < 0 &&
+          compareKeyParts(length, hopCount, x, BiPrimeKey) >= 0
+        ) {
+          K.push([x, [length, hopCount, x]]);
         }
       }
       if (K.length > 0) D.batchPrepend(K);
@@ -256,7 +269,10 @@ class BMSSP {
     const finalKey =
       compareKeys(lastBoundKey, boundKey) < 0 ? lastBoundKey : boundKey;
     for (const x of W) {
-      if (compareKeys(orderKey(x, dHat, ties), finalKey) < 0) U.add(x);
+      const length = dHat.get(x) ?? Infinity;
+      if (compareKeyParts(length, ties.hops.get(x) ?? 0, x, finalKey) < 0) {
+        U.add(x);
+      }
     }
     return finish(finalKey, U);
   }

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,10 @@
-import { compareKeys, toBound, makeTies, relaxEdge } from "./tieBreak.mjs";
+import {
+  compareKeyParts,
+  toBound,
+  makeTies,
+  relaxEdge,
+  RELAX_LOST,
+} from "./tieBreak.mjs";
 
 /**
  * FindPivots(B, S) — Algorithm 1 of "Breaking the Sorting Barrier for Directed
@@ -75,12 +81,21 @@ 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) ?? []) {
+      const edges = adjacency.get(u);
+      if (edges === undefined) continue;
+      for (let j = 0; j < edges.length; j += 1) {
+        const edge = edges[j];
+        const v = edge[0];
         // 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) {
+        // 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, edge[1], dHat, ties);
+        if (
+          result !== RELAX_LOST &&
+          compareKeyParts(dHat.get(v), ties.hops.get(v) ?? 0, v, boundKey) < 0
+        ) {
           nextLayer.add(v);
         }
       }

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 };

package/src/tieBreak.mjs

@@ -78,6 +78,26 @@ function compareKeys(a, b) {
   return 0;
 }
 
+/**
+ * Lexicographic comparison of an UNPACKED key (length, hops, id) against a
+ * packed one — identical order to compareKeys without materializing the
+ * left-hand array (#168: the hot relax/routing loops call this instead of
+ * allocating a throwaway key per test). Counts as one comparison.
+ * @param {number} length - Left key's length component
+ * @param {number} hops - Left key's hops component
+ * @param {*} id - Left key's id component
+ * @param {[number, number, *]} key - Right key, packed
+ * @returns {number} Negative when (length, hops, id) < key, positive when
+ *   greater, 0 when equal
+ */
+function compareKeyParts(length, hops, id, key) {
+  comparisonCount += 1;
+  if (length !== key[0]) return length < key[0] ? -1 : 1;
+  if (hops !== key[1]) return hops < key[1] ? -1 : 1;
+  if (id !== key[2]) return id < key[2] ? -1 : 1;
+  return 0;
+}
+
 /**
  * Normalize a bound to a composite key. A scalar B becomes the infimum of
  * all keys of length B, preserving the strict "distance < B" contract;
@@ -130,6 +150,11 @@ function orderKey(v, dHat, ties) {
  * tied alternative parents; callers filter already-completed vertices to
  * keep the re-enqueue finite, exactly like the paper.
  *
+ * Allocation-free since #168: the result is one of the three RELAX_* codes,
+ * and a caller that needs v's (possibly updated) order key materializes it
+ * with orderKey(v, dHat, ties) — only on the rare paths that enqueue v,
+ * instead of on every attempt.
+ *
  * @param {*} u - Edge tail (its labels are read)
  * @param {*} v - Edge head (its labels may be updated)
  * @param {number} weight - Edge weight, >= 0
@@ -137,38 +162,59 @@ function orderKey(v, dHat, ties) {
  * @param {{ hops: Map<*, number>, preds: Map<*, *> }} ties - Updated in place
  * @param {[number, number, *]} [bound] - Optional gate: skip (no d̂ update)
  *   unless the resulting order key would be strictly below this bound
- * @returns {{ key: [number, number, *], improved: boolean }|null} v's order
- *   key [d̂[v], hops[v], v] with `improved: true` when the labels were
- *   updated, `improved: false` when the candidate exactly matches v's
- *   canonical label; null when the candidate loses (or the bound gates it)
+ * @returns {number} RELAX_IMPROVED when the labels were updated,
+ *   RELAX_EQUAL when the candidate exactly matches v's canonical label
+ *   (the re-enqueue signal), RELAX_LOST when the candidate loses or the
+ *   bound gates it (labels untouched)
  */
 function relaxEdge(u, v, weight, dHat, ties, bound) {
   const length = dHat.get(u) + weight;
   const hopCount = (ties.hops.get(u) ?? 0) + 1;
-  if (bound !== undefined && compareKeys([length, hopCount, v], bound) >= 0) {
-    return null;
+  if (bound !== undefined && compareKeyParts(length, hopCount, v, bound) >= 0) {
+    return RELAX_LOST;
   }
-  const currentPathKey = [
-    dHat.get(v) ?? Infinity,
-    ties.hops.get(v) ?? 0,
-    ties.preds.has(v) ? ties.preds.get(v) : NO_PRED,
-  ];
-  const cmp = compareKeys([length, hopCount, u], currentPathKey);
-  if (cmp > 0) return null;
-  if (cmp === 0) return { key: [length, hopCount, v], improved: false };
+  // Candidate path key [length, hopCount, u] vs. v's current path key
+  // [d̂[v], hops[v], preds[v] ?? NO_PRED] — compareKeys inlined on the
+  // unpacked components (one counted comparison, no arrays)
+  comparisonCount += 1;
+  let cmp;
+  const currentLength = dHat.get(v) ?? Infinity;
+  if (length !== currentLength) {
+    cmp = length < currentLength ? -1 : 1;
+  } else {
+    const currentHops = ties.hops.get(v) ?? 0;
+    if (hopCount !== currentHops) {
+      cmp = hopCount < currentHops ? -1 : 1;
+    } else {
+      const currentPred = ties.preds.has(v) ? ties.preds.get(v) : NO_PRED;
+      cmp = u !== currentPred ? (u < currentPred ? -1 : 1) : 0;
+    }
+  }
+  if (cmp > 0) return RELAX_LOST;
+  if (cmp === 0) return RELAX_EQUAL;
   dHat.set(v, length);
   ties.hops.set(v, hopCount);
   ties.preds.set(v, u);
-  return { key: [length, hopCount, v], improved: true };
+  return RELAX_IMPROVED;
 }
 
+// relaxEdge result codes (#168): distinct, and only RELAX_LOST is falsy-like
+// in comparisons — callers must compare against the constants, not truthiness
+const RELAX_LOST = -1;
+const RELAX_EQUAL = 0;
+const RELAX_IMPROVED = 1;
+
 export {
   compareKeys,
+  compareKeyParts,
   toBound,
   makeTies,
   orderKey,
   relaxEdge,
   NO_PRED,
+  RELAX_LOST,
+  RELAX_EQUAL,
+  RELAX_IMPROVED,
   resetComparisonCount,
   getComparisonCount,
 };