bmssp 1.0.1 → 1.1.1

package/src/baseCase.mjs

@@ -1,4 +1,11 @@
 import { MinHeap } from "./heap.mjs";
+import {
+  compareKeys,
+  toBound,
+  makeTies,
+  orderKey,
+  relaxEdge,
+} from "./tieBreak.mjs";
 
 /**
  * BaseCase(B, S) — Algorithm 2 of "Breaking the Sorting Barrier for Directed
@@ -12,26 +19,40 @@ import { MinHeap } from "./heap.mjs";
  *
  * 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.
+ * to the levels above. Since #163 the heap is ordered by the composite
+ * [length, hops, id] keys of src/tieBreak.mjs, which realize the paper's
+ * Assumption 2.1 (distinct path lengths): a settled vertex carries its
+ * canonical (lexicographically minimal) label, which no later relaxation can
+ * improve. The settled filter below only skips canonical re-enqueue signals
+ * (exact label equality from the recorded predecessor), which is what keeps
+ * zero-weight plateaus quiescent instead of looping.
  *
  * Two outcomes:
  * - Full success (fewer than k + 1 vertices exist under B): every vertex
- *   with d(v) < B is settled and returned, with bound === B.
- * - Partial (the k + 1 cap was hit): bound = the largest settled distance
- *   B' <= B, and only the strictly-closer vertices (d̂ < B') are returned.
+ *   with key < B is settled and returned, with bound === B.
+ * - Partial (the k + 1 cap was hit): boundKey = the largest settled key
+ *   B' < B, and exactly the k strictly-closer vertices are returned. Under
+ *   the composite order the strictly-closer filter is exact — scalar-length
+ *   ties with the boundary vertex are broken by (hops, id), and a returned
+ *   vertex may therefore share the boundary's scalar length (the documented
+ *   d(v) <= bound caveat of the scalar view).
  *   Every returned vertex is complete either way.
  *
- * @param {number} B - Strict upper bound on the distances to settle (Infinity is allowed)
+ * @param {number|[number, number, *]} B - Strict upper bound on the keys to
+ *   settle: a number (Infinity is allowed) or a composite bound
  * @param {Set<*>|Iterable<*>} S - Singleton set holding the complete source x
  * @param {Map<*, number>} dHat - Global distance estimates d̂[·], updated in place
  * @param {Map<*, Array<[*, number]>>} adjacency - nodeId -> outgoing [to, weight] edges
  * @param {number} k - Settle cap parameter, >= 1 (floored); the paper's ⌊log^(1/3) n⌋
- * @returns {{ bound: number, vertices: Set<*> }} The boundary B' <= B and the
- *   set U of vertices settled below it
+ * @param {{ hops: Map<*, number>, preds: Map<*, *> }} [ties] - Canonical
+ *   tie-break labels updated alongside dHat; fresh throwaway maps by default
+ * @returns {{ bound: number|[number, number, *], boundKey: [number, number, *], vertices: Set<*> }}
+ *   The boundary B' <= B (same kind as the B passed in), its composite key,
+ *   and the set U of vertices settled below it
  * @throws {Error} If k is not a number >= 1, S is not a singleton, or the
  *   source has no finite distance estimate
  */
-function baseCase(B, S, dHat, adjacency, k) {
+function baseCase(B, S, dHat, adjacency, k, ties = makeTies()) {
   if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
     throw new Error("k must be a number >= 1");
   }
@@ -45,50 +66,53 @@ function baseCase(B, S, dHat, adjacency, k) {
   if (typeof sourceDistance !== "number" || !Number.isFinite(sourceDistance)) {
     throw new Error("the source must have a finite distance estimate");
   }
+  const boundKey = toBound(B);
 
   // U0 in the paper: the vertices settled by this call, seeded with x
   const settled = new Set([x]);
-  const heap = new MinHeap();
-  heap.insert(x, sourceDistance);
+  const heap = new MinHeap(compareKeys);
+  heap.insert(x, orderKey(x, dHat, ties));
 
   while (!heap.isEmpty() && settled.size < cap + 1) {
-    const { key: u, value: du } = heap.extractMin();
+    const { key: u } = heap.extractMin();
     settled.add(u);
     for (const [v, weight] of adjacency.get(u) ?? []) {
-      const candidate = du + weight;
-      // Paper relaxation: d̂[u] + w(u,v) <= d̂[v], and below the bound B
-      if (candidate <= (dHat.get(v) ?? Infinity) && candidate < B) {
-        dHat.set(v, candidate);
-        // With non-negative weights a vertex settled in this call cannot
-        // strictly improve, so an equal-sum relaxation (which the <= allows,
-        // e.g. via a zero-weight cycle) must not re-enter the heap.
-        if (settled.has(v)) continue;
-        if (heap.has(v)) {
-          heap.decreaseKey(v, candidate);
-        } else {
-          heap.insert(v, candidate);
-        }
+      // 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;
+      if (heap.has(v)) {
+        heap.decreaseKey(v, relaxed.key);
+      } else {
+        heap.insert(v, relaxed.key);
       }
     }
   }
 
   if (settled.size <= cap) {
     // Exhausted before the cap: everything under B is settled (B' = B)
-    return { bound: B, vertices: settled };
+    return { bound: B, boundKey, vertices: settled };
   }
 
-  // Hit the k + 1 cap: report B' = the largest settled distance and return
-  // only the vertices strictly below it
-  let boundary = -Infinity;
+  // Hit the k + 1 cap: report B' = the largest settled key and return the
+  // vertices strictly below it — exactly k of them, keys being distinct
+  let boundary = null;
   for (const v of settled) {
-    const distance = dHat.get(v);
-    if (distance > boundary) boundary = distance;
+    const key = orderKey(v, dHat, ties);
+    if (boundary === null || compareKeys(key, boundary) > 0) boundary = key;
   }
   const vertices = new Set();
   for (const v of settled) {
-    if (dHat.get(v) < boundary) vertices.add(v);
+    if (compareKeys(orderKey(v, dHat, ties), boundary) < 0) vertices.add(v);
   }
-  return { bound: boundary, vertices };
+  return {
+    bound: typeof B === "number" ? boundary[0] : boundary,
+    boundKey: boundary,
+    vertices,
+  };
 }
 
 export { baseCase };

package/src/blockList.mjs

@@ -22,15 +22,19 @@ class BlockList {
   /**
    * Initialize the structure (Lemma 3.3 Initialize).
    * @param {number} M - Block size / pull batch size, >= 1. At recursion level l this is 2^((l-1)·t).
-   * @param {number} B - Strict upper bound on every value ever stored (Infinity is allowed)
+   * @param {*} B - Strict upper bound on every value ever stored (Infinity is allowed)
+   * @param {(a: *, b: *) => number} [compare] - Value comparator (negative
+   *   when a < b). Defaults to numeric order; #163 passes composite
+   *   [length, hops, id] keys with their lexicographic comparator.
    * @throws {Error} If M is not a number >= 1
    */
-  constructor(M, B) {
+  constructor(M, B, compare) {
     if (typeof M !== "number" || Number.isNaN(M) || M < 1) {
       throw new Error("M must be a number >= 1");
     }
     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 = [];
@@ -61,12 +65,12 @@ class BlockList {
    * @throws {Error} If value >= B
    */
   insert(key, value) {
-    if (!(value < this.B)) {
+    if (!(this.compare(value, this.B) < 0)) {
       throw new Error("value must be < B");
     }
     const holder = this.locator.get(key);
     if (holder !== undefined) {
-      if (holder.entries.get(key) <= value) return;
+      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
@@ -74,7 +78,7 @@ class BlockList {
     let hi = this.d1.length - 1;
     while (lo < hi) {
       const mid = (lo + hi) >> 1;
-      if (this.d1[mid].bound >= value) {
+      if (this.compare(this.d1[mid].bound, value) >= 0) {
         hi = mid;
       } else {
         lo = mid + 1;
@@ -96,7 +100,7 @@ class BlockList {
   // simpler — acceptable for this correctness-first implementation.)
   splitBlock(index) {
     const block = this.d1[index];
-    const sorted = [...block.entries].sort((a, b) => a[1] - b[1]);
+    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]);
     for (let i = 0; i < half; i += 1) {
@@ -121,11 +125,11 @@ class BlockList {
     // Dedupe the batch, keeping the smallest value per key
     const best = new Map();
     for (const [key, value] of pairs) {
-      if (!(value < this.B)) {
+      if (!(this.compare(value, this.B) < 0)) {
         throw new Error("value must be < B");
       }
       const seen = best.get(key);
-      if (seen === undefined || value < seen) {
+      if (seen === undefined || this.compare(value, seen) < 0) {
         best.set(key, value);
       }
     }
@@ -134,7 +138,7 @@ class BlockList {
     for (const [key, value] of best) {
       const holder = this.locator.get(key);
       if (holder !== undefined) {
-        if (holder.entries.get(key) <= value) continue;
+        if (this.compare(holder.entries.get(key), value) <= 0) continue;
         this.removeKey(key, holder);
       }
       fresh.push([key, value]);
@@ -145,25 +149,32 @@ class BlockList {
     if (fresh.length <= this.M) {
       chunks = [fresh];
     } else {
-      fresh.sort((a, b) => a[1] - b[1]);
+      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));
       }
     }
-    // Prepend in reverse chunk order so the smallest chunk lands at the front
-    for (let c = chunks.length - 1; c >= 0; c -= 1) {
-      const chunk = chunks[c];
-      const block = this.makeBlock(-Infinity);
+    // 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).
+    const blocks = [];
+    for (const chunk of chunks) {
+      // Seed the block bound with the first value, then max-update — avoids
+      // needing a -Infinity sentinel that a custom comparator can't order
+      const block = this.makeBlock(chunk[0][1]);
       for (const [key, value] of chunk) {
         block.entries.set(key, value);
         this.locator.set(key, block);
-        if (value > block.bound) block.bound = value;
+        if (this.compare(value, block.bound) > 0) block.bound = value;
         this.count += 1;
       }
-      this.d0.unshift(block);
+      blocks.push(block);
     }
+    this.d0 = blocks.concat(this.d0);
   }
 
   /**
@@ -198,21 +209,24 @@ class BlockList {
       }
     }
     // Take the M smallest candidates out of the structure
-    candidates.sort((a, b) => a[1] - b[1]);
+    candidates.sort((a, b) => this.compare(a[1], b[1]));
     const keys = new Set();
     for (let i = 0; i < this.M; i += 1) {
       const [key, , block] = candidates[i];
       keys.add(key);
       this.removeKey(key, block);
     }
-    // Separator = smallest value still stored. Thanks to the inter-block
-    // ordering it lives in the first non-empty block of d0 or d1.
-    let bound = Infinity;
+    // Separator = smallest value still stored (non-null here: this branch
+    // only runs when more than M values were present). Thanks to the
+    // inter-block ordering it lives in the first non-empty block of d0/d1.
+    // 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 (const value of block.entries.values()) {
-          if (value < bound) bound = value;
+          if (bound === null || this.compare(value, bound) < 0) bound = value;
         }
       }
     }

package/src/bmssp.mjs

@@ -1,9 +1,20 @@
 import { baseCase } from "./baseCase.mjs";
 import { findPivots } from "./findPivots.mjs";
 import { BlockList } from "./blockList.mjs";
+import {
+  compareKeys,
+  toBound,
+  makeTies,
+  orderKey,
+  relaxEdge,
+} from "./tieBreak.mjs";
 
 class BMSSP {
   constructor(inputGraph) {
+    if (!Array.isArray(inputGraph)) {
+      throw new Error("Input graph must be an array of edges");
+    }
+
     // Main graph represented as an array of edges
     this.graph = [];
     // Set to store unique node IDs
@@ -14,8 +25,29 @@ class BMSSP {
     // Lets the algorithm fetch a node's edges in O(1) instead of scanning
     // the whole edge list on every lookup.
     this.adjacency = new Map();
+    // Canonical tie-break labels (#163): hops = edge count of the canonical
+    // shortest path, preds = its predecessor pointer. Updated in lockstep
+    // with shortestPaths by relaxEdge; together they realize the paper's
+    // Assumption 2.1 (distinct path lengths) via [length, hops, id] keys.
+    this.hops = new Map();
+    this.preds = new Map();
+    this.ties = makeTies(this.hops, this.preds);
+
+    for (let [index, edge] of inputGraph.entries()) {
+      if (!Array.isArray(edge) || edge.length !== 3) {
+        throw new Error(`Edge at index ${index} must be [from, to, weight]`);
+      }
+
+      const [from, to, weight] = edge;
+      if (!Number.isFinite(from) || !Number.isFinite(to)) {
+        throw new Error(`Edge at index ${index} must have numeric node IDs`);
+      }
+      if (!Number.isFinite(weight) || weight < 0) {
+        throw new Error(
+          `Edge at index ${index} must have a non-negative numeric weight`,
+        );
+      }
 
-    for (let edge of inputGraph) {
       // Create a deep copy of each edge array
       this.graph.push([...edge]);
 
@@ -57,11 +89,14 @@ class BMSSP {
     return this.adjacency.get(nodeId) ?? [];
   }
 
-  // Method to initialize the shortest paths map
+  // Method to initialize the shortest paths map (and the #163 tie-break
+  // labels that travel with it)
   initializeShortestPaths() {
     for (let nodeId of this.nodeIDs) {
       this.shortestPaths.set(nodeId, Infinity);
     }
+    this.hops.clear();
+    this.preds.clear();
   }
 
   /**
@@ -93,45 +128,79 @@ class BMSSP {
    *   path through some complete vertex of S.
    *
    * Distance estimates live in this.shortestPaths (the paper's d̂[·]) and
-   * are relaxed in place at every level.
+   * are relaxed in place at every level, together with the canonical hops
+   * and preds labels (#163). All internal ordering uses the composite
+   * [length, hops, id] keys of src/tieBreak.mjs, which realize the paper's
+   * Assumption 2.1: pull separators are strict, no key ever ties a bound,
+   * and the pre-#163 degenerate-tie guards (out-of-scope pivots,
+   * boundary-tied batch members, the empty-child stall escape hatch) are
+   * unnecessary by construction.
    *
-   * Two outcomes (Lemma 3.1):
-   * - Successful execution: the block list emptied — bound === B and
-   *   vertices holds every v with d(v) < B reachable through S.
-   * - Partial execution: the k·2^(l·t) workload guard tripped — bound < B
-   *   and vertices holds exactly the v with d(v) < bound.
+   * Two outcomes (Lemma 3.1, strict under the composite order):
+   * - Successful execution: the block list emptied — boundKey === B's key
+   *   and vertices holds every v with key(v) < B reachable through S.
+   * - Partial execution: the k·2^(l·t) workload guard tripped —
+   *   boundKey < B's key and vertices holds exactly the v with
+   *   key(v) < boundKey. In the scalar projection a returned vertex may tie
+   *   the returned bound's length (never exceed it).
    *   Every returned vertex is complete either way.
    *
    * @param {number} l - Recursion level; 0 delegates to baseCase
-   * @param {number} B - Strict upper bound on the distances in scope (Infinity is allowed)
+   * @param {number|[number, number, *]} B - Strict upper bound on the keys
+   *   in scope: a number (Infinity is allowed) or a composite bound
    * @param {Set<*>} S - Non-empty set of complete frontier sources
-   * @returns {{ bound: number, vertices: Set<*> }} The boundary B' <= B and
-   *   the set U of vertices completed below it
+   * @returns {{ bound: number|[number, number, *], boundKey: [number, number, *], vertices: Set<*> }}
+   *   The boundary B' <= B (same kind as the B passed in: scalar callers
+   *   get a scalar), its composite key, and the set U of vertices
+   *   completed below it
    */
   bmssp(l, B, S) {
     const dHat = this.shortestPaths;
+    const ties = this.ties;
+    const boundKey = toBound(B);
+    const scalarB = typeof B === "number";
+    // Project the composite result back to the caller's kind: a successful
+    // execution echoes B itself, a partial one reports the separator (whose
+    // length is strictly below a scalar B by construction)
+    const finish = (finalKey, vertices) => ({
+      bound: scalarB
+        ? compareKeys(finalKey, boundKey) === 0
+          ? B
+          : finalKey[0]
+        : finalKey,
+      boundKey: finalKey,
+      vertices,
+    });
+
     if (l === 0) {
-      return baseCase(B, S, dHat, this.adjacency, this.k);
+      const result = baseCase(boundKey, S, dHat, this.adjacency, this.k, ties);
+      return finish(result.boundKey, result.vertices);
     }
 
     // Shrink the frontier: only the pivots are worth recursing on, and W
     // is a batch of already-completed vertices folded in at the end
-    const { pivots, W } = findPivots(B, S, dHat, this.adjacency, this.k);
-
-    // Seed the Lemma 3.3 block list with the pivots. lastBound tracks the
-    // paper's Bi': B when P is empty, min d̂ over P before the first pull,
-    // then the boundary returned by the latest recursive call.
-    // A pivot with d̂ >= B is out of scope at this level (only possible
-    // when equal path lengths violate Assumption 2.1 and a pull returned
-    // a key tied with its separator): skip it — the ancestor whose band
-    // covers its distance is responsible for it.
-    const D = new BlockList(2 ** ((l - 1) * this.t), B);
-    let lastBound = B;
+    const { pivots, W } = findPivots(
+      boundKey,
+      S,
+      dHat,
+      this.adjacency,
+      this.k,
+      ties,
+    );
+
+    // Seed the Lemma 3.3 block list with the pivots. lastBoundKey tracks
+    // the paper's Bi': B when P is empty, min key over P before the first
+    // pull, then the boundary returned by the latest recursive call.
+    // The scope filter is for direct multi-source callers who may pass
+    // sources at or above B — internal calls can't produce one, because
+    // every pull separator is strict under the composite order.
+    const D = new BlockList(2 ** ((l - 1) * this.t), boundKey, compareKeys);
+    let lastBoundKey = boundKey;
     for (const x of pivots) {
-      const dx = dHat.get(x);
-      if (dx < B) {
-        D.insert(x, dx);
-        if (dx < lastBound) lastBound = dx;
+      const key = orderKey(x, dHat, ties);
+      if (compareKeys(key, boundKey) < 0) {
+        D.insert(x, key);
+        if (compareKeys(key, lastBoundKey) < 0) lastBoundKey = key;
       }
     }
 
@@ -140,86 +209,64 @@ class BMSSP {
 
     while (U.size < workloadCap && !D.isEmpty()) {
       // Bi, Si <- D.Pull(): the next-closest small batch and its separator
-      const { keys: Si, bound: Bi } = D.pull();
-      let { bound: BiPrime, vertices: Ui } = this.bmssp(l - 1, Bi, Si);
-
-      if (Ui.size === 0) {
-        // Degenerate tie stall: the child settled only vertices tied
-        // exactly at its boundary (possible only through zero-weight
-        // paths, which violate the paper's Assumption 2.1 — see #163),
-        // so its strict d̂ < B' filter returned nothing and this batch
-        // would be re-pulled forever. Escape hatch: settle everything
-        // below Bi reachable through the batch with an uncapped bounded
-        // Dijkstra per member — correct, just not sublinear.
-        Ui = new Set();
-        for (const x of Si) {
-          const { vertices } = baseCase(
-            Bi,
-            new Set([x]),
-            dHat,
-            this.adjacency,
-            Math.max(1, this.nodeIDs.size),
-          );
-          for (const v of vertices) Ui.add(v);
-        }
-        BiPrime = Bi;
-      }
+      const { keys: Si, bound: BiKey } = D.pull();
+      const child = this.bmssp(l - 1, BiKey, Si);
+      const BiPrimeKey = child.boundKey;
+      const Ui = child.vertices;
 
-      lastBound = BiPrime;
+      lastBoundKey = BiPrimeKey;
       for (const v of Ui) U.add(v);
 
-      // Relax out of the newly-completed Ui, routing improved neighbors
-      // by distance band: [Bi, B) re-enters the block list, [Bi', Bi) is
-      // staged for a batch prepend (closer than the current batch's floor)
+      // Relax out of the newly-completed Ui, routing improved neighbors by
+      // key band: [Bi, B) re-enters the block list, [Bi', Bi) is staged for
+      // a batch prepend (closer than the current batch's floor). An exact
+      // canonical equality re-enqueues a vertex that a deeper call labeled
+      // 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.
       const K = [];
       for (const u of Ui) {
-        const du = dHat.get(u);
         for (const [v, weight] of this.adjacency.get(u) ?? []) {
-          const candidate = du + weight;
-          // Paper relaxation: d̂[u] + w(u,v) <= d̂[v] always updates d̂
-          if (candidate <= (dHat.get(v) ?? Infinity)) {
-            dHat.set(v, candidate);
-            // A vertex already completed at this level cannot strictly
-            // improve (non-negative weights), so an equal-sum relaxation
-            // — which the <= allows, e.g. via a zero-weight cycle — must
-            // not be re-queued (mirrors the baseCase settled guard)
-            if (U.has(v)) continue;
-            if (candidate >= Bi && candidate < B) {
-              D.insert(v, candidate);
-            } else if (candidate >= BiPrime && candidate < Bi) {
-              K.push([v, candidate]);
-            }
+          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]);
           }
         }
       }
-      // Batch members the child did not complete (d̂ still in [Bi', Bi))
-      // go back in front of everything else. A member tied exactly at the
-      // separator (d̂ == Bi < B, an Assumption 2.1 violation) is still in
-      // scope at this level and re-enters through a regular insert.
+      // Batch members the child did not complete (key still in [Bi', Bi))
+      // go back in front of everything else
       for (const x of Si) {
         if (U.has(x)) continue;
-        const dx = dHat.get(x);
-        if (dx >= BiPrime && dx < Bi) {
-          K.push([x, dx]);
-        } else if (dx === Bi && Bi < B) {
-          D.insert(x, dx);
+        const key = orderKey(x, dHat, ties);
+        if (compareKeys(key, BiPrimeKey) >= 0 && compareKeys(key, BiKey) < 0) {
+          K.push([x, key]);
         }
       }
       if (K.length > 0) D.batchPrepend(K);
     }
 
     // B' <- min(last Bi', B); fold in the FindPivots batch below it
-    const bound = Math.min(lastBound, B);
+    const finalKey =
+      compareKeys(lastBoundKey, boundKey) < 0 ? lastBoundKey : boundKey;
     for (const x of W) {
-      if (dHat.get(x) < bound) U.add(x);
+      if (compareKeys(orderKey(x, dHat, ties), finalKey) < 0) U.add(x);
     }
-    return { bound, vertices: U };
+    return finish(finalKey, U);
   }
 
   // Method to calculate shortest paths from startNode via the BMSSP
   // recursion (Algorithm 3). The top-level call BMSSP(topLevel, ∞, {start})
   // is always a successful execution, so it completes every reachable
-  // vertex; unreachable ones keep their Infinity estimate.
+  // vertex; unreachable ones keep their Infinity estimate. Distances, hop
+  // counts and predecessor pointers all end at their canonical values —
+  // independent of edge or iteration order (#163).
   calculateShortestPaths(startNode) {
     // To clean the state before calculation
     this.initializeShortestPaths();
@@ -229,10 +276,36 @@ class BMSSP {
       throw new Error("Start node not found in the graph");
     }
 
-    // The source is complete at distance 0; everything else is Infinity
+    // The source is complete at distance 0 with zero hops and no
+    // predecessor; everything else is Infinity
     this.shortestPaths.set(startNode, 0);
+    this.hops.set(startNode, 0);
     this.bmssp(this.topLevel, Infinity, new Set([startNode]));
   }
+
+  /**
+   * Reconstruct the canonical shortest path from the most recent source to
+   * target. Returns an empty array when target is unreachable or no shortest
+   * path run has completed yet.
+   *
+   * @param {number} target - A node in the graph
+   * @returns {number[]} Node IDs from the source through target
+   * @throws {Error} If target is not in the graph
+   */
+  reconstructPath(target) {
+    if (!this.nodeIDs.has(target)) {
+      throw new Error("Target node not found in the graph");
+    }
+    if (this.shortestPaths.get(target) === Infinity) return [];
+
+    const path = [target];
+    let current = target;
+    while (this.preds.has(current)) {
+      current = this.preds.get(current);
+      path.push(current);
+    }
+    return path.reverse();
+  }
 }
 
 export { BMSSP };