bmssp 1.0.0 → 1.1.0

package/README.md

@@ -17,8 +17,8 @@ first to beat Dijkstra's O(m + n·log n) bound on sparse directed graphs.
 
 **The algorithm is functional end-to-end as of `1.0.0`** 🎉 — `calculateShortestPaths()`
 computes distances via the paper's method (FindPivots → block list → recursive BMSSP with
-the bounded base case), validated node-by-node against a Dijkstra oracle, including on a
-real 2-million-node road network. The project was built piece by piece against the paper,
+the bounded base case), validated node-by-node against a Dijkstra oracle on thousands of
+seeded graphs — up to 2 million nodes. The project was built piece by piece against the paper,
 with every building block shipped, tested, and released individually:
 
 | Building block (paper) | Where | Status |
@@ -30,14 +30,24 @@ with every building block shipped, tested, and released individually:
 | `BaseCase(B, S)` — Algorithm 2, bounded mini-Dijkstra ([#40](https://github.com/Sirivasv/bmssp-js/issues/40)) | `src/baseCase.mjs` | ✅ done |
 | `FindPivots(B, S)` — Algorithm 1, frontier shrinking ([#44](https://github.com/Sirivasv/bmssp-js/issues/44)) | `src/findPivots.mjs` | ✅ done |
 | `BMSSP(l, B, S)` — Algorithm 3, the main recursion ([#43](https://github.com/Sirivasv/bmssp-js/issues/43)) | `src/bmssp.mjs` | ✅ done — **1.0.0** |
+| Deterministic tie-breaking — Assumption 2.1 realized ([#163](https://github.com/Sirivasv/bmssp-js/issues/163)) | `src/tieBreak.mjs` | ✅ done |
+| Shortest-path reconstruction ([#169](https://github.com/Sirivasv/bmssp-js/issues/169)) | `BMSSP.reconstructPath()` | ✅ done |
+| Constructor input validation ([#165](https://github.com/Sirivasv/bmssp-js/issues/165)) | `BMSSP` constructor | ✅ done |
+| Opt-in constant-degree transform, in/out-degree ≤ 2 ([#164](https://github.com/Sirivasv/bmssp-js/issues/164)) | `constantDegreeTransform()` | ✅ done |
 
 > **Honest note:** the paper's win is asymptotic, and this repo optimizes for correctness
-> and readability, not raw speed. On the full California road network (~2 M nodes, ~5.5 M
-> edges) this implementation currently runs about 2× slower than its own reference
-> Dijkstra — consistent with published experimental studies of the algorithm. Where inputs
-> violate the paper's distinct-path-lengths assumption (e.g. zero-weight edges), documented
-> tie guards keep the results correct
-> ([#163](https://github.com/Sirivasv/bmssp-js/issues/163) tracks a principled tie-break).
+> and readability, not raw speed. Measured head-to-head (algorithm time only, graph
+> loading excluded — see [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)):
+> 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** (0.91× at n = 2M), and the advantage grows with
+> size: the "sorting barrier" is measurably broken; what remains is JS constant factors.
+> Where inputs violate the paper's distinct-path-lengths assumption (e.g. zero-weight
+> edges), a principled deterministic tie-break
+> ([#163](https://github.com/Sirivasv/bmssp-js/issues/163)) realizes that assumption in
+> code: paths are ranked by composite `(length, hops, id)` keys, so distances, predecessor
+> pointers and completed sets are identical no matter how the edge list is ordered.
 
 ## How it works (in two ideas)
 
@@ -49,7 +59,9 @@ with every building block shipped, tested, and released individually:
    ordered *between* blocks but unsorted *within* them — enough to repeatedly pull the next
    closest batch without paying the Θ(log n)-per-vertex "sorting barrier."
 
-The asymptotic win is theoretical (the crossover point is astronomically large); this repo
+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
 optimizes for a **correct, readable, well-tested** implementation, validated line-by-line
 against a Dijkstra oracle — not for raw speed.
 
@@ -62,7 +74,8 @@ npm install bmssp
 ## Usage
 
 The package is ESM-only (`.mjs`). Graphs are arrays of `[from, to, weight]` edges with
-numeric node IDs and non-negative weights:
+finite numeric node IDs and finite, non-negative weights. The constructor rejects malformed
+edges with an error that identifies their array index; an empty edge array remains valid:
 
 ```javascript
 import { BMSSP } from "bmssp";
@@ -75,10 +88,41 @@ const graph = new BMSSP([
 
 graph.calculateShortestPaths(0);
 console.log(graph.shortestPaths); // Map(3) { 0 => 0, 1 => 50, 2 => 25 }
+console.log(graph.reconstructPath(1)); // [0, 1]
 ```
 
+`reconstructPath(target)` uses the latest `calculateShortestPaths()` run. It returns `[]`
+when the target is unreachable (or before any run) and throws for a node outside the graph.
+
 A reference `dijkstra` implementation is also exported. See the `examples/` directory for
-more.
+more, or the [public API reference](https://sirivasv.github.io/bmssp-js/) for the complete
+documented surface.
+
+### Optional: constant-degree transform
+
+The paper's bound assumes every vertex has in-degree and out-degree ≤ 2. That preprocessing
+is **not** required for correctness here — BMSSP is validated on arbitrary graphs — but it is
+available opt-in via `constantDegreeTransform`, which rewrites any graph into that shape by
+splitting each vertex into a zero-weight cycle of "port" copies. The rewrite is
+distance-preserving, so you run on the transformed graph and fold the result back onto your
+original node IDs:
+
+```javascript
+import { BMSSP, constantDegreeTransform } from "bmssp";
+
+const t = constantDegreeTransform([
+  [0, 1, 50],
+  [0, 2, 25],
+  [1, 2, 75],
+]);
+
+const g = new BMSSP(t.edges); // every node now has in/out-degree ≤ 2
+g.calculateShortestPaths(t.sourceCopy(0)); // start from a copy of original node 0
+console.log(t.collapse(g.shortestPaths)); // Map(3) { 0 => 0, 1 => 50, 2 => 25 }
+```
+
+`collapse` maps the transformed graph's distances back to the original node IDs; `sourceCopy`
+picks a valid start copy for an original node.
 
 ### Using the Docker image
 
@@ -101,26 +145,48 @@ Other image versions are on [Docker Hub](https://hub.docker.com/r/sirivasv/bmssp
 
 ```bash
 npm install
-npm test          # Jest suite, incl. BMSSP-vs-Dijkstra equivalence on a real road network
+npm test          # Jest suite — every graph seeded, every failure reproducible (~3 s)
 npm run lint      # Prettier + ESLint
 npm run bench     # seeded micro-benchmarks (see benchmarks/README.md)
 ```
 
+The measured BMSSP-vs-Dijkstra head-to-head — wall-clock and comparison counts, with
+methodology — lives in [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)
+([#170](https://github.com/Sirivasv/bmssp-js/issues/170) tracks harness integration).
+
 The test suite's core contract: for every node, BMSSP's distances must equal the Dijkstra
-oracle's — including on `test/roadNet-CA.txt`, a real road network from SNAP.
+oracle's. A seeded property/fuzz suite (`test/fuzz.test.mjs`) hammers that contract across
+eight graph shapes (sparse/dense random, grids, chains, stars, DAGs, disconnected forests,
+multigraphs), extreme weight regimes (all-zero, mixed zero/huge, exact floats), direct
+multi-source bounded calls checked against per-source oracles, and seeded scale runs up to
+150k nodes. It runs in `npm test` by default; crank the volume with the `FUZZ_ROUNDS`
+multiplier (e.g. `FUZZ_ROUNDS=25 npm test -- test/fuzz.test.mjs` checks several thousand
+graphs in a few seconds), and set `FUZZ_XL=1` for an additional 2-million-node round
+(~30 s). Failures always report the seed that produced them.
 
 ## Roadmap
 
 | Milestone | Theme | Status |
 | --- | --- | --- |
 | [`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 | 🔨 current focus |
-| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, path reconstruction, BMSSP-vs-Dijkstra benchmarks | planned |
+| `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 |
 
+## Contributing (humans and AI agents welcome)
+
 Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
 [`help wanted` / `good first issue` labels](https://github.com/Sirivasv/bmssp-js/issues).
 
+This repo is built to be **agent-friendly, model-agnostic**: everything a coding assistant
+needs to contribute is checked in, so you can point **any AI running any model** at the
+project and it can start working **without ever reading the source paper**. Have your agent
+read [`.claude/CLAUDE.md`](.claude/CLAUDE.md) first — it lays out the full working lifecycle
+as literal, follow-along checklists — backed by a self-contained knowledge base under
+[`.claude/knowledge/`](.claude/knowledge/) (a verified transcription of the paper, the
+current codebase map, the roadmap, and a glossary). Prefer to work by hand? The same
+knowledge base reads as plain documentation.
+
 ## Other implementations on GitHub
 
 <https://github.com/search?q=bmssp&type=repositories>

package/docs/index.html

@@ -2,8 +2,9 @@
 <html lang="en">
 <head>
     <meta charset="UTF-8">
-    <title>Tsinghua SSSP - BMSSP - Landing Page</title>
+    <title>bmssp — BMSSP shortest paths for JavaScript</title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="JavaScript implementation of BMSSP, the O(m log^(2/3) n) single-source shortest-paths algorithm — public API documentation.">
     <style>
         body {
             margin: 0;
@@ -14,35 +15,63 @@
             display: flex;
             flex-direction: column;
             align-items: center;
-            justify-content: center;
         }
         .container {
             background: #fff;
             border-radius: 18px;
             box-shadow: 0 4px 24px rgba(0,0,0,0.08);
             padding: 2.5rem 2rem;
-            max-width: 420px;
-            text-align: center;
+            margin: 2rem 1rem;
+            max-width: 760px;
+            width: calc(100% - 2rem);
+            box-sizing: border-box;
         }
+        header { text-align: center; }
         h1 {
             font-size: 2.2rem;
             margin-bottom: 0.5rem;
             color: #3a0ca3;
         }
-        p {
-            font-size: 1.1rem;
-            margin-bottom: 1.5rem;
+        h2 {
+            font-size: 1.4rem;
+            color: #3a0ca3;
+            border-bottom: 2px solid #e0e7ff;
+            padding-bottom: 0.3rem;
+            margin-top: 2.2rem;
+        }
+        h3 {
+            font-size: 1.05rem;
+            color: #22223b;
+            margin-bottom: 0.3rem;
+        }
+        p, li {
+            font-size: 1rem;
+            line-height: 1.55;
             color: #4a4e69;
         }
+        .tagline { font-size: 1.1rem; }
+        a { color: #4361ee; }
+        code {
+            font-family: 'Cascadia Code', Consolas, Menlo, monospace;
+            font-size: 0.92em;
+            background: #eef1ff;
+            border-radius: 4px;
+            padding: 0.08em 0.35em;
+        }
+        pre {
+            background: #22223b;
+            color: #f0fdfa;
+            border-radius: 10px;
+            padding: 1rem 1.2rem;
+            overflow-x: auto;
+        }
+        pre code { background: none; color: inherit; padding: 0; }
         .graphics {
-            margin: 1.5rem 0;
+            margin: 1.2rem 0 0.4rem;
             display: flex;
             justify-content: center;
         }
-        .node-graph {
-            width: 120px;
-            height: 120px;
-        }
+        .node-graph { width: 110px; height: 110px; }
         .btn {
             display: inline-block;
             padding: 0.7em 1.5em;
@@ -54,43 +83,164 @@
             text-decoration: none;
             transition: background 0.2s;
             cursor: pointer;
+            margin: 0.3rem 0.35rem;
         }
-        .btn:hover {
-            background: #3a0ca3;
+        .btn:hover { background: #3a0ca3; }
+        .btn.secondary { background: #4cc9f0; color: #22223b; }
+        .btn.secondary:hover { background: #3ab8de; }
+        .note {
+            background: #f0fdfa;
+            border-left: 4px solid #4cc9f0;
+            border-radius: 0 8px 8px 0;
+            padding: 0.7rem 1rem;
+            margin: 1rem 0;
         }
         footer {
-            margin-top: 2rem;
+            margin: 0 0 2rem;
             font-size: 0.95rem;
-            color: #adb5bd;
+            color: #6c757d;
+            text-align: center;
         }
+        footer a { color: #6c757d; }
     </style>
 </head>
 <body>
     <div class="container">
-        <h1>Tsinghua SSSP - BMSSP JS</h1>
+        <header>
+            <h1>bmssp</h1>
+            <p class="tagline">
+                A JavaScript (ESM) implementation of <strong>BMSSP</strong> —
+                <strong>B</strong>ounded <strong>M</strong>ulti-<strong>S</strong>ource
+                <strong>S</strong>hortest <strong>P</strong>aths — the deterministic
+                O(m·log<sup>2/3</sup> n) single-source shortest-paths algorithm from
+                <a href="https://dl.acm.org/doi/10.1145/3717823.3718179" target="_blank" rel="noopener">
+                    “Breaking the Sorting Barrier for Directed Single-Source Shortest Paths”</a>
+                (Duan, Mao, Mao, Shu, Yin — 2025), the first to beat Dijkstra on sparse directed graphs.
+            </p>
+            <div class="graphics">
+                <!-- SVG: stylized graph with nodes and edges -->
+                <svg class="node-graph" viewBox="0 0 120 120" role="img" aria-label="Stylized graph">
+                    <line x1="60" y1="20" x2="30" y2="60" stroke="#adb5bd" stroke-width="3"/>
+                    <line x1="60" y1="20" x2="90" y2="60" stroke="#adb5bd" stroke-width="3"/>
+                    <line x1="30" y1="60" x2="60" y2="100" stroke="#adb5bd" stroke-width="3"/>
+                    <line x1="90" y1="60" x2="60" y2="100" stroke="#adb5bd" stroke-width="3"/>
+                    <circle cx="60" cy="20" r="12" fill="#4361ee" />
+                    <circle cx="30" cy="60" r="10" fill="#4cc9f0" />
+                    <circle cx="90" cy="60" r="10" fill="#4cc9f0" />
+                    <circle cx="60" cy="100" r="12" fill="#3a0ca3" />
+                </svg>
+            </div>
+            <p>
+                <a class="btn" href="https://github.com/Sirivasv/bmssp-js" target="_blank" rel="noopener">GitHub</a>
+                <a class="btn secondary" href="https://www.npmjs.com/package/bmssp" target="_blank" rel="noopener">npm</a>
+                <a class="btn secondary" href="https://hub.docker.com/r/sirivasv/bmssp-js" target="_blank" rel="noopener">Docker&nbsp;Hub</a>
+            </p>
+        </header>
+
+        <h2>Install</h2>
+        <pre><code>npm install bmssp</code></pre>
         <p>
-            Implementation of the Single Source Shortest Path (SSSP) algorithm - Bounded Multiple Source Shortest Paths (BMSSP), originally published by Tsinghua University's research.
+            The package is ESM-only. Graphs are arrays of <code>[from, to, weight]</code>
+            edges with finite numeric node IDs and finite, non-negative weights.
         </p>
+
+        <h2>Quick start</h2>
+<pre><code>import { BMSSP } from "bmssp";
+
+const graph = new BMSSP([
+  [0, 1, 50],
+  [1, 2, 75],
+  [0, 2, 25],
+]);
+
+graph.calculateShortestPaths(0);
+graph.shortestPaths;      // Map(3) { 0 => 0, 1 => 50, 2 => 25 }
+graph.reconstructPath(1); // [0, 1]</code></pre>
+
+        <h2>Public API</h2>
+        <p>The package has exactly three exports: <code>BMSSP</code>, <code>dijkstra</code>,
+           and <code>constantDegreeTransform</code>.</p>
+
+        <h3><code>new BMSSP(graph)</code></h3>
         <p>
-            Read the original paper:
-            <a href="https://dl.acm.org/doi/10.1145/3717823.3718179" target="_blank">
-                Tsinghua SSSP Paper
-            </a>
+            Validates and stores the edge list. Every entry must be an exact three-element
+            <code>[from, to, weight]</code> array; node IDs must be finite numbers and weights
+            finite and non-negative. Malformed input throws an <code>Error</code> identifying
+            the offending edge index. An empty edge array is valid (the graph then has no
+            nodes, so any start node is rejected later).
         </p>
-        <div class="graphics">
-            <!-- SVG: stylized graph with nodes and edges -->
-            <svg class="node-graph" viewBox="0 0 120 120">
-                <circle cx="60" cy="20" r="12" fill="#4361ee" />
-                <circle cx="30" cy="60" r="10" fill="#4cc9f0" />
-                <circle cx="90" cy="60" r="10" fill="#4cc9f0" />
-                <circle cx="60" cy="100" r="12" fill="#3a0ca3" />
-                <line x1="60" y1="20" x2="30" y2="60" stroke="#adb5bd" stroke-width="3"/>
-                <line x1="60" y1="20" x2="90" y2="60" stroke="#adb5bd" stroke-width="3"/>
-                <line x1="30" y1="60" x2="60" y2="100" stroke="#adb5bd" stroke-width="3"/>
-                <line x1="90" y1="60" x2="60" y2="100" stroke="#adb5bd" stroke-width="3"/>
-            </svg>
+
+        <h3><code>graph.calculateShortestPaths(source)</code></h3>
+        <p>
+            Computes shortest distances from <code>source</code> via the paper's method
+            (FindPivots → block list → recursive BMSSP with the bounded base case — not by
+            calling Dijkstra). Throws if <code>source</code> is not a node of the graph.
+            Results land in <code>graph.shortestPaths</code>, a
+            <code>Map&lt;nodeId, distance&gt;</code> holding a value for every node —
+            <code>Infinity</code> where unreachable. Distances and predecessor pointers are
+            canonical: deterministic regardless of edge-list order, even with ties and
+            zero-weight edges. Calling it again with a different source resets state and
+            recomputes.
+        </p>
+
+        <h3><code>graph.reconstructPath(target)</code></h3>
+        <p>
+            Returns the canonical shortest path from the most recent source to
+            <code>target</code> as an array of node IDs (<code>[source, …, target]</code>).
+            Returns <code>[]</code> when <code>target</code> is unreachable or no run has
+            completed yet; throws for a node that is not in the graph.
+        </p>
+
+        <h3><code>dijkstra(graph, nodeIDs, source)</code></h3>
+        <p>
+            The reference Dijkstra implementation used as the test suite's ground-truth
+            oracle, exported for comparison and independent checking. Takes the raw edge
+            array, a <code>Set</code> of node IDs, and a source; returns a
+            <code>Map&lt;nodeId, distance&gt;</code> (<code>Infinity</code> if unreachable).
+        </p>
+
+        <h3><code>constantDegreeTransform(graph)</code></h3>
+        <p>
+            Opt-in preprocessing that rewrites any graph so every vertex has in-degree and
+            out-degree ≤ 2 (the paper's preliminary assumption) by splitting each vertex into
+            a zero-weight cycle of “port” copies. Distance-preserving and never required for
+            correctness — BMSSP is validated on arbitrary graphs. Returns
+            <code>{ edges, copiesOf, originalOf, sourceCopy, collapse }</code>:
+        </p>
+<pre><code>import { BMSSP, constantDegreeTransform } from "bmssp";
+
+const t = constantDegreeTransform([
+  [0, 1, 50],
+  [0, 2, 25],
+  [1, 2, 75],
+]);
+
+const g = new BMSSP(t.edges);              // in/out-degree ≤ 2 everywhere
+g.calculateShortestPaths(t.sourceCopy(0)); // start from a copy of node 0
+t.collapse(g.shortestPaths);               // Map(3) { 0 => 0, 1 => 50, 2 => 25 }</code></pre>
+
+        <div class="note">
+            Algorithm internals — the Lemma 3.3 block list, the indexed min-heap,
+            <code>BaseCase</code>, <code>FindPivots</code>, and the tie-break helpers — are
+            deliberately <em>not</em> exported. They are implementation details, documented
+            in-source for contributors.
         </div>
-        <a class="btn" href="https://github.com/sirivasv/tsinghua-sssp" target="_blank">View on GitHub</a>
+
+        <h2>Correctness &amp; performance</h2>
+        <p>
+            Every release is validated node-by-node against the Dijkstra oracle on thousands
+            of seeded graphs (up to 2 million nodes). The paper's win is asymptotic: measured
+            head-to-head, Dijkstra still wins wall-clock at practical sizes, but in the
+            paper's own metric — comparisons between path lengths — this implementation does
+            fewer comparisons than Dijkstra from about n&nbsp;=&nbsp;1M on sparse graphs. See
+            <a href="https://github.com/Sirivasv/bmssp-js/blob/main/benchmarks/HEAD-TO-HEAD.md"
+               target="_blank" rel="noopener">benchmarks/HEAD-TO-HEAD.md</a> for the data and
+            methodology.
+        </p>
     </div>
+    <footer>
+        <a href="https://github.com/Sirivasv/bmssp-js" target="_blank" rel="noopener">bmssp-js</a>
+        · MPL-2.0 · Saul Ivan Rivas Vega
+    </footer>
 </body>
-</html></svg>
+</html>

package/index.mjs

@@ -1,2 +1,41 @@
+// Public API of the `bmssp` package (ESM-only). Exactly three exports:
+// the BMSSP class, the reference `dijkstra`, and the opt-in
+// `constantDegreeTransform`. Algorithm-internal modules (the block list,
+// the indexed heap, BaseCase, FindPivots, the tie-break helpers) are
+// deliberately NOT re-exported — they are implementation details of the
+// recursion, not supported public API.
+
+/**
+ * BMSSP — the paper's Algorithm 3 behind a small class API.
+ *
+ * `new BMSSP(graph)` takes an array of `[from, to, weight]` edges with
+ * finite numeric node IDs and finite, non-negative weights (an empty array
+ * is valid; malformed edges throw with the offending index).
+ * `calculateShortestPaths(source)` computes canonical distances into the
+ * `shortestPaths` Map (`Infinity` for unreachable nodes), and
+ * `reconstructPath(target)` returns the canonical shortest path as an
+ * array of node IDs. Full JSDoc lives on the class in `src/bmssp.mjs`.
+ */
 export { BMSSP } from "./src/bmssp.mjs";
+
+/**
+ * Reference Dijkstra implementation — the oracle the BMSSP test suite is
+ * validated against, exported for comparison and independent checking.
+ *
+ * `dijkstra(graph, nodeIDs, source)` returns a `Map` from node ID to
+ * shortest distance (`Infinity` if unreachable). See `src/dijkstra.mjs`.
+ */
 export { dijkstra } from "./src/dijkstra.mjs";
+
+/**
+ * Opt-in constant-degree transform — rewrites any graph so every vertex
+ * has in-degree and out-degree <= 2 (the paper's preliminary assumption)
+ * by splitting each vertex into a zero-weight cycle of port copies. The
+ * rewrite is distance-preserving and never required for correctness.
+ *
+ * `constantDegreeTransform(graph)` returns
+ * `{ edges, copiesOf, originalOf, sourceCopy, collapse }`; run BMSSP on
+ * `edges` from `sourceCopy(source)` and `collapse()` the resulting
+ * distances back onto original node IDs. See `src/constantDegree.mjs`.
+ */
+export { constantDegreeTransform } from "./src/constantDegree.mjs";

package/package.json

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

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