bmssp 1.0.1 → 1.1.1

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,18 +30,34 @@ 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 |
+| BMSSP-vs-Dijkstra head-to-head in the benchmark harness ([#170](https://github.com/Sirivasv/bmssp-js/issues/170)) | `npm run bench` / `npm run bench:counts` | ✅ done |
+| Performance-cliff investigation; quadratic `BatchPrepend` fixed ([#182](https://github.com/Sirivasv/bmssp-js/issues/182)) | `src/blockList.mjs` | ✅ done — **1.1.1** |
 
 > **Honest note:** the paper's win is asymptotic, and this repo optimizes for correctness
 > and readability, not raw speed. Measured head-to-head (algorithm time only, graph
-> loading excluded — see [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)):
+> loading excluded — rerun it yourself with `npm run bench`; methodology and the deep
+> 1.0.0 record in [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.
+> from about n = 1M on sparse graphs** (`npm run bench:counts` measures the ratio falling
+> 1.20× at 50k → 1.03× at 200k → 0.98× at 1M; 0.91× at 2M in the record), and the
+> advantage grows with size: the "sorting barrier" is measurably broken; what remains is
+> JS constant factors. The two performance cliffs found in the 1.0.0 measurements were
+> run down in [#182](https://github.com/Sirivasv/bmssp-js/issues/182): the star-graph
+> blowup was a quadratic in `BatchPrepend`'s bookkeeping — fixed in `1.1.1` (500k-node
+> star: 61 s → ~3 s) — and the recursion-level step is an inherent, measured ~+24% per
+> extra level (see the addendum in
+> [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)).
 > 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).
+> 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)
 
@@ -68,7 +84,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";
@@ -81,10 +98,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
 
@@ -107,37 +155,51 @@ 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 run lint      # Prettier + ESLint
-npm run bench     # seeded micro-benchmarks (see benchmarks/README.md)
+npm test              # Jest suite — every graph seeded, every failure reproducible (~7 s)
+npm run lint          # Prettier + ESLint
+npm run bench         # BMSSP-vs-Dijkstra head-to-head per graph shape, outputs verified
+npm run bench:counts  # …plus comparison-count tables (the paper's own cost metric)
 ```
 
-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 benchmark harness runs the measured BMSSP-vs-Dijkstra head-to-head on every
+`npm run bench` ([#170](https://github.com/Sirivasv/bmssp-js/issues/170)); methodology,
+the deep 1.0.0 record (up to n = 4M) and the "when to use which" guidance live in
+[benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md) and
+[benchmarks/README.md](benchmarks/README.md).
 
 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. 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), and direct multi-source
-bounded calls checked against per-source oracles. 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). Failures always report the seed that
-produced them.
+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.1",
+  "version": "1.1.1",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [
@@ -35,6 +35,7 @@
   "scripts": {
     "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage",
     "bench": "node benchmarks/run.mjs",
+    "bench:counts": "node benchmarks/run.mjs --counts",
     "lint": "npm run prettier && npm run eslint",
     "format": "npm run prettier:fix && npm run eslint:fix",
     "eslint": "eslint --max-warnings=0 .",