bmssp 1.0.1 → 1.1.1

package/src/constantDegree.mjs

@@ -0,0 +1,136 @@
+// Constant-degree transform — the paper's Preliminaries (knowledge/01 §
+// "Preliminaries / model assumptions"; term in knowledge/07). The
+// O(m·log^(2/3) n) bound is argued on a graph whose vertices all have
+// in-degree AND out-degree <= 2. This module rewrites any graph into that
+// shape while preserving every distance.
+//
+// OPT-IN, by design. Nothing in the core algorithm calls this: BMSSP is
+// correct on the untransformed graph (validated node-by-node against the
+// Dijkstra oracle). The transform only realizes the paper's structural
+// precondition for callers who want it — it changes constants, never
+// correctness (issue #164, milestone 1.1.0).
+
+// How it works: split each vertex into one "port" copy per incident edge
+// endpoint and thread those copies onto a zero-weight directed cycle. A cycle
+// gives every copy exactly one incoming and one outgoing cycle edge; a copy
+// that additionally hosts a single original endpoint therefore reaches
+// degree 2 on that one side and stays at 1 on the other — never more. Because
+// the cycle costs nothing to traverse, all copies of a vertex are mutually
+// reachable at zero added distance, so each copy's shortest distance equals
+// the original vertex's: the rewrite is distance-preserving.
+
+/**
+ * Rewrite a directed graph so every vertex has in-degree and out-degree <= 2,
+ * preserving all shortest-path distances.
+ *
+ * @param {Array<[number, number, number]>} graph - [from, to, weight] edges,
+ *   the same input contract as the BMSSP constructor: an array of exact
+ *   three-element arrays with finite numeric node IDs and finite, non-negative
+ *   weights. An empty array is valid.
+ * @returns {{
+ *   edges: Array<[number, number, number]>,
+ *   copiesOf: Map<number, number[]>,
+ *   originalOf: Map<number, number>,
+ *   sourceCopy: (original: number) => number,
+ *   collapse: (transformedDistances: Map<number, number>) => Map<number, number>
+ * }}
+ *   - `edges`: the transformed graph (fresh integer copy IDs from 0).
+ *   - `copiesOf`: original node ID -> its copy IDs, in allocation order.
+ *   - `originalOf`: copy ID -> the original node ID it belongs to.
+ *   - `sourceCopy(original)`: a canonical copy to start a run from (any copy
+ *     works — the zero-weight cycle equalizes them); throws for an unknown
+ *     node.
+ *   - `collapse(distances)`: fold a transformed-graph distance map back onto
+ *     the original node IDs (the min over each vertex's copies; all copies
+ *     share the same value, so the min is exact).
+ */
+function constantDegreeTransform(graph) {
+  if (!Array.isArray(graph)) {
+    throw new Error("Input graph must be an array of edges");
+  }
+
+  let nextCopyId = 0;
+  // original node ID -> its copy IDs, in allocation order
+  const copiesOf = new Map();
+  // copy ID -> the original node ID it belongs to
+  const originalOf = new Map();
+  // per original edge, the out-port copy of `from` and the in-port copy of `to`
+  const outCopyForEdge = new Array(graph.length);
+  const inCopyForEdge = new Array(graph.length);
+
+  const allocateCopy = (originalId) => {
+    const id = nextCopyId;
+    nextCopyId += 1;
+    originalOf.set(id, originalId);
+    let copies = copiesOf.get(originalId);
+    if (copies === undefined) {
+      copies = [];
+      copiesOf.set(originalId, copies);
+    }
+    copies.push(id);
+    return id;
+  };
+
+  // One copy per edge endpoint, allocated in edge order so the whole transform
+  // is deterministic: the out-port at `from`, the in-port at `to`. Validate
+  // exactly like the BMSSP constructor so the transform can front any graph.
+  graph.forEach((edge, index) => {
+    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`,
+      );
+    }
+    outCopyForEdge[index] = allocateCopy(from);
+    inCopyForEdge[index] = allocateCopy(to);
+  });
+
+  const edges = [];
+
+  // Zero-weight directed cycle through each vertex's copies. A vertex with a
+  // single incident endpoint has one copy and needs no cycle.
+  for (const copies of copiesOf.values()) {
+    if (copies.length < 2) continue;
+    for (let i = 0; i < copies.length; i += 1) {
+      const next = copies[(i + 1) % copies.length];
+      edges.push([copies[i], next, 0]);
+    }
+  }
+
+  // Each original edge connects its own out-copy to its own in-copy, weight
+  // unchanged.
+  graph.forEach(([, , weight], index) => {
+    edges.push([outCopyForEdge[index], inCopyForEdge[index], weight]);
+  });
+
+  const sourceCopy = (original) => {
+    const copies = copiesOf.get(original);
+    if (copies === undefined) {
+      throw new Error(`Node ${original} is not in the graph`);
+    }
+    return copies[0];
+  };
+
+  const collapse = (transformedDistances) => {
+    const result = new Map();
+    for (const [original, copies] of copiesOf) {
+      let best = Infinity;
+      for (const copy of copies) {
+        const d = transformedDistances.get(copy);
+        if (d !== undefined && d < best) best = d;
+      }
+      result.set(original, best);
+    }
+    return result;
+  };
+
+  return { edges, copiesOf, originalOf, sourceCopy, collapse };
+}
+
+export { constantDegreeTransform };

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,174 @@
+/**
+ * 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;
+
+// Running count of compareKeys calls — the paper's cost metric ("comparisons
+// between path lengths"). Every BMSSP-side comparison funnels through
+// compareKeys (the heap and BlockList receive it as their comparator, and
+// baseCase/findPivots/bmssp call it directly), so this one counter covers the
+// whole algorithm. The benchmark harness (#170) reads it to measure the
+// sorting barrier; one unconditional increment keeps the hot path branch-free.
+let comparisonCount = 0;
+
+/** Reset the compareKeys call counter to zero (benchmark instrumentation). */
+function resetComparisonCount() {
+  comparisonCount = 0;
+}
+
+/**
+ * Number of compareKeys calls since the last reset (benchmark
+ * instrumentation).
+ * @returns {number}
+ */
+function getComparisonCount() {
+  return comparisonCount;
+}
+
+/**
+ * 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) {
+  comparisonCount += 1;
+  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,
+  resetComparisonCount,
+  getComparisonCount,
+};