bmssp 1.0.1 → 1.1.0

package/src/findPivots.mjs

@@ -1,3 +1,5 @@
+import { compareKeys, toBound, makeTies, relaxEdge } from "./tieBreak.mjs";
+
 /**
  * FindPivots(B, S) — Algorithm 1 of "Breaking the Sorting Barrier for Directed
  * Single-Source Shortest Paths". Shrinks the frontier S: runs k rounds of
@@ -13,30 +15,42 @@
  *
  * 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. The `<=` relaxation updates d̂ unconditionally; the
- * `< B` test only gates membership in W.
+ * 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.
+ *
+ * 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
+ * always itself in W. Equal-length paths cannot make this a DAG (one pred
+ * per vertex) and tight zero-weight cycles cannot occur (a zero-weight edge
+ * strictly increases the hops component), so parent chains always terminate
+ * in S — the two #44-era tie ambiguities are gone by construction. Members
+ * of S are roots by definition and never count toward another source's tree.
  *
  * Two outcomes:
  * - Early exit (|W| grows past k·|S|): the frontier is already small relative
  *   to W, so every vertex of S is a pivot.
  * - Forest case (k rounds complete with |W| <= k·|S|): pivots are the S-roots
- *   of tight-edge trees with >= k vertices. Equal-length paths can make the
- *   tight-edge graph a DAG (see #163); each vertex is assigned at most one
- *   parent deterministically (first tight edge in W iteration order) so tree
- *   sizes are well-defined. Guarantees |pivots| <= |W| / k either way.
+ *   of canonical-predecessor trees with >= k vertices.
+ *   Guarantees |pivots| <= |W| / k either way.
  *
- * @param {number} B - Strict upper bound gating membership in W (Infinity is allowed)
+ * @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 {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)
  * @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) {
+function findPivots(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");
   }
@@ -51,8 +65,10 @@ function findPivots(B, S, dHat, adjacency, k) {
       throw new Error("every source must have a finite distance estimate");
     }
   }
+  const boundKey = toBound(B);
 
   // W accumulates everything relaxed below B; layer is the paper's W_{i-1}
+  const sourceSet = new Set(sources);
   const W = new Set(sources);
   let layer = new Set(sources);
 
@@ -60,11 +76,12 @@ function findPivots(B, S, dHat, adjacency, k) {
     const nextLayer = new Set();
     for (const u of layer) {
       for (const [v, weight] of adjacency.get(u) ?? []) {
-        const candidate = dHat.get(u) + weight;
-        // Paper relaxation: <= always updates d̂; < B gates the W membership
-        if (candidate <= (dHat.get(v) ?? Infinity)) {
-          dHat.set(v, candidate);
-          if (candidate < B) nextLayer.add(v);
+        // 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) {
+          nextLayer.add(v);
         }
       }
     }
@@ -76,28 +93,20 @@ function findPivots(B, S, dHat, adjacency, k) {
     }
   }
 
-  // Forest F of tight edges inside W. Each vertex takes at most one parent,
-  // chosen deterministically, so tree sizes stay well-defined even when ties
-  // make F a DAG. Vertices on tight cycles (zero-weight cycles) all end up
-  // with parents, so they belong to no root's tree.
+  // Forest of canonical predecessors inside W: every vertex of W \ S was
+  // (re-)labeled through some layer member during this call, so its
+  // recorded pred is in W and parent chains end in S
   const children = new Map();
-  const hasParent = new Set();
-  for (const u of W) {
-    const du = dHat.get(u);
-    for (const [v, weight] of adjacency.get(u) ?? []) {
-      if (v === u || !W.has(v) || hasParent.has(v)) continue;
-      if (dHat.get(v) === du + weight) {
-        hasParent.add(v);
-        if (!children.has(u)) children.set(u, []);
-        children.get(u).push(v);
-      }
-    }
+  for (const v of W) {
+    if (sourceSet.has(v)) continue;
+    const parent = ties.preds.get(v);
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(v);
   }
 
-  // Pivots: sources that root a tight-edge tree with >= k vertices
+  // Pivots: sources that root a canonical tree with >= k vertices
   const pivots = new Set();
   for (const x of sources) {
-    if (hasParent.has(x)) continue;
     let size = 0;
     const stack = [x];
     while (stack.length > 0) {

package/src/heap.mjs

@@ -14,11 +14,29 @@
  * duplicate-and-skip variant used inside src/dijkstra.mjs.
  */
 class MinHeap {
-  constructor() {
+  /**
+   * @param {(a: *, b: *) => number} [compare] - Value comparator (negative
+   *   when a < b). Defaults to numeric order, in which case values must be
+   *   numbers; with a custom comparator values are opaque (#163 passes
+   *   composite [length, hops, id] keys).
+   */
+  constructor(compare) {
     // entries[i] = [key, value], heap-ordered by value
     this.entries = [];
     // key -> index of that key in entries, for O(1) membership / lookup
     this.position = new Map();
+    this.numericValues = compare === undefined;
+    this.compare = compare ?? ((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+
+  // Internal: reject non-number values, but only in default numeric mode
+  checkValue(value) {
+    if (
+      this.numericValues &&
+      (typeof value !== "number" || Number.isNaN(value))
+    ) {
+      throw new Error("value must be a number");
+    }
   }
 
   // Number of pairs currently stored
@@ -65,9 +83,7 @@ class MinHeap {
    * @throws {Error} If the key is already stored, or value is not a number
    */
   insert(key, value) {
-    if (typeof value !== "number" || Number.isNaN(value)) {
-      throw new Error("value must be a number");
-    }
+    this.checkValue(value);
     if (this.position.has(key)) {
       throw new Error("key already in heap — use decreaseKey");
     }
@@ -85,14 +101,12 @@ class MinHeap {
    * @throws {Error} If the key is not stored, or value is not a number
    */
   decreaseKey(key, value) {
-    if (typeof value !== "number" || Number.isNaN(value)) {
-      throw new Error("value must be a number");
-    }
+    this.checkValue(value);
     const index = this.position.get(key);
     if (index === undefined) {
       throw new Error("key not in heap — use insert");
     }
-    if (this.entries[index][1] <= value) return;
+    if (this.compare(this.entries[index][1], value) <= 0) return;
     this.entries[index][1] = value;
     this.siftUp(index);
   }
@@ -132,7 +146,7 @@ class MinHeap {
     let i = index;
     while (i > 0) {
       const parent = (i - 1) >> 1;
-      if (this.entries[parent][1] <= this.entries[i][1]) break;
+      if (this.compare(this.entries[parent][1], this.entries[i][1]) <= 0) break;
       this.swap(parent, i);
       i = parent;
     }
@@ -147,13 +161,13 @@ class MinHeap {
       let smallest = i;
       if (
         left < this.entries.length &&
-        this.entries[left][1] < this.entries[smallest][1]
+        this.compare(this.entries[left][1], this.entries[smallest][1]) < 0
       ) {
         smallest = left;
       }
       if (
         right < this.entries.length &&
-        this.entries[right][1] < this.entries[smallest][1]
+        this.compare(this.entries[right][1], this.entries[smallest][1]) < 0
       ) {
         smallest = right;
       }

package/src/tieBreak.mjs

@@ -0,0 +1,142 @@
+/**
+ * Deterministic tie-breaking for equal-length paths (#163) — the code-level
+ * stand-in for the paper's Assumption 2.1 ("all paths have distinct
+ * lengths", "Breaking the Sorting Barrier for Directed Single-Source
+ * Shortest Paths").
+ *
+ * Every path is ranked by a composite key `[length, hops, id]`, compared
+ * lexicographically:
+ *
+ * - `length` — the ordinary path length (sum of weights). Always dominates,
+ *   so plain distances are unaffected.
+ * - `hops`   — the number of edges on the path (the paper's "#vertices"
+ *   tie-break component). A zero-weight edge leaves `length` unchanged but
+ *   always increments `hops`, so extending a path strictly increases its
+ *   key: tight (zero-weight) cycles cannot tie with themselves and an
+ *   equal-sum re-relaxation can never loop.
+ * - `id`     — a final disambiguator standing in for the paper's full
+ *   "vertex sequence" (O(1) to compare instead of O(path)): inside
+ *   relaxation it is the candidate predecessor's id (picking the canonical
+ *   parent among equal-(length, hops) alternatives), while for frontier
+ *   ordering it is the vertex's own id (making the order on vertices a
+ *   strict total order).
+ *
+ * With distinct vertex ids no two frontier keys are ever equal, which is
+ * exactly what Assumption 2.1 grants the paper: every BlockList pull
+ * separator is strict, no vertex ties with a bound, and Lemma 3.1 holds in
+ * its strict form — the guards that #40/#43/#161 had to add for degenerate
+ * ties become dead code.
+ *
+ * Scalar bounds stay expressible: `toBound(B)` maps the number B to
+ * `[B, -Infinity, -Infinity]`, the infimum of every real key of length B,
+ * so "key < toBound(B)" is exactly the public "distance strictly below B"
+ * contract.
+ *
+ * The canonical labels live in three maps updated together by `relaxEdge`:
+ * d̂ (the class's `shortestPaths`), plus `hops` and `preds` bundled as a
+ * `ties` object. Missing entries default to hops 0 (an externally seeded
+ * source is a hop-0 root) and "no predecessor" (which never loses a tie).
+ */
+
+// Sentinel predecessor for sources: compares below every real id, so a
+// source's own label never loses an equal-(length, hops) comparison.
+const NO_PRED = -Infinity;
+
+/**
+ * Lexicographic comparison of two composite keys.
+ * @param {[number, number, *]} a - [length, hops, id]
+ * @param {[number, number, *]} b - [length, hops, id]
+ * @returns {number} Negative when a < b, positive when a > b, 0 when equal
+ */
+function compareKeys(a, b) {
+  if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+  if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
+  if (a[2] !== b[2]) return a[2] < b[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;
+ * a composite bound (an array) passes through unchanged.
+ * @param {number|[number, number, *]} B
+ * @returns {[number, number, *]}
+ */
+function toBound(B) {
+  return typeof B === "number" ? [B, -Infinity, -Infinity] : B;
+}
+
+/**
+ * Bundle (or create) the tie-break label maps that accompany d̂.
+ * @param {Map<*, number>} [hops] - Canonical path edge counts
+ * @param {Map<*, *>} [preds] - Canonical predecessor of each vertex
+ * @returns {{ hops: Map<*, number>, preds: Map<*, *> }}
+ */
+function makeTies(hops = new Map(), preds = new Map()) {
+  return { hops, preds };
+}
+
+/**
+ * The frontier-ordering key of a vertex under its current labels.
+ * @param {*} v - Vertex id
+ * @param {Map<*, number>} dHat - Distance estimates d̂[·]
+ * @param {{ hops: Map<*, number> }} ties - Tie-break labels
+ * @returns {[number, number, *]} [d̂[v], hops[v], v]
+ */
+function orderKey(v, dHat, ties) {
+  return [dHat.get(v) ?? Infinity, ties.hops.get(v) ?? 0, v];
+}
+
+/**
+ * Attempt the canonical relaxation of edge (u, v). The candidate path
+ * (canonical path to u, then this edge) has path key
+ * [d̂[u] + w, hops[u] + 1, u]; it wins iff it is strictly smaller than v's
+ * current path key [d̂[v], hops[v], preds[v]] — so d̂, hops and preds move
+ * together and the chosen predecessor is deterministic regardless of edge
+ * or iteration order. Improvements strictly decrease v's path key, which is
+ * bounded below, so chains of relaxations always terminate (no zero-weight
+ * cycle can loop).
+ *
+ * The exact-equality case — the candidate IS v's current canonical label —
+ * is reported separately as `improved: false`. It is the paper's `≤`
+ * re-relaxation made canonical: when a caller completes u and relaxes its
+ * edges, an equal result on (u, v) means u is v's recorded label-setter and
+ * v may need to be re-enqueued at this level (it was labeled by a deeper
+ * call that did not complete it). Only the one canonical predecessor
+ * triggers this, so re-enqueues are deterministic and never duplicated by
+ * tied alternative parents; callers filter already-completed vertices to
+ * keep the re-enqueue finite, exactly like the paper.
+ *
+ * @param {*} u - Edge tail (its labels are read)
+ * @param {*} v - Edge head (its labels may be updated)
+ * @param {number} weight - Edge weight, >= 0
+ * @param {Map<*, number>} dHat - Distance estimates d̂[·], updated in place
+ * @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)
+ */
+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;
+  }
+  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 };
+  dHat.set(v, length);
+  ties.hops.set(v, hopCount);
+  ties.preds.set(v, u);
+  return { key: [length, hopCount, v], improved: true };
+}
+
+export { compareKeys, toBound, makeTies, orderKey, relaxEdge, NO_PRED };