bmssp 1.1.1 → 2.0.0

package/README.md

@@ -36,18 +36,30 @@ with every building block shipped, tested, and released individually:
 | 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** |
+| Exact Lemma 3.3 asymptotics: balanced-BST bound index + linear-time selection ([#167](https://github.com/Sirivasv/bmssp-js/issues/167)) | `src/boundIndex.mjs` + `src/select.mjs` | ✅ done |
+| Relaxation micro-optimizations: allocation-free hot loops, −13–23% wall-clock ([#168](https://github.com/Sirivasv/bmssp-js/issues/168)) | `src/tieBreak.mjs` + the algorithm modules | ✅ done — **1.2.0** |
+| Dense-index core: typed-array labels + CSR adjacency, ~½ the wall-clock ([#205](https://github.com/Sirivasv/bmssp-js/issues/205)) | `src/bmssp.mjs` (CSR) + `src/tieBreak.mjs` (typed labels) | ✅ done |
+| Typed / flexible graph inputs: `Graph` builder + adjacency Map/object + explicit vertex universe ([#172](https://github.com/Sirivasv/bmssp-js/issues/172)) | `src/graph.mjs` + `BMSSP` constructor | ✅ done |
+| Public multi-source / bounded entrypoint ([#171](https://github.com/Sirivasv/bmssp-js/issues/171)) | `BMSSP.calculateShortestPathsFrom()` | ✅ done |
+| Public API stabilization + 1.0→2.0 migration note ([#173](https://github.com/Sirivasv/bmssp-js/issues/173)) | `MIGRATION.md` + `docs/index.html` + contract test | ✅ done — **2.0.0** |
 
 > **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 — 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 —
+> and readability first — but the constant factors have come down a lot. Measured
+> head-to-head (algorithm time only, graph 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, but after the dense-index engine
+> ([#205](https://github.com/Sirivasv/bmssp-js/issues/205): typed-array labels + CSR
+> adjacency) **BMSSP is within ~1.1–1.4× on sparse graphs** (sparse-random 1.38×,
+> sparse-l4 1.07×, dense 1.16×) — down from ~2.5× before. And in the paper's own metric —
 > **comparisons between path lengths** — BMSSP does **fewer comparisons than Dijkstra
-> 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
+> from under n = 50k on sparse graphs** (`npm run bench:counts` measures 0.95× at 50k →
+> 0.76× at 200k → **0.65× at 1M**), and the advantage grows with size: the "sorting
+> barrier" is measurably broken. That crossover
+> used to sit at ~n = 1M until [#167](https://github.com/Sirivasv/bmssp-js/issues/167)
+> replaced the block structure's sort-based internals with the paper's exact machinery
+> (balanced-BST bound index + deterministic linear-time selection).
+> 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
@@ -69,11 +81,13 @@ 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 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.
+Dijkstra still wins the wall-clock race, but only by a small margin on sparse graphs now
+(~1.1–1.4× since the dense-index engine); in measured comparison counts this
+implementation already beats Dijkstra from under 50k nodes on sparse graphs, by a third
+at 1M ([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 first — with the constant factors brought down where it doesn't cost
+clarity.
 
 ## Installation
 
@@ -106,7 +120,77 @@ when the target is unreachable (or before any run) and throws for a node outside
 
 A reference `dijkstra` implementation is also exported. See the `examples/` directory for
 more, or the [public API reference](https://sirivasv.github.io/bmssp-js/) for the complete
-documented surface.
+documented surface. The public API is **stable as of 2.0.0** — see
+[MIGRATION.md](MIGRATION.md) for the 1.0 → 2.0 note (no breaking changes) and the locked
+surface.
+
+### Flexible graph inputs
+
+The constructor also accepts an **adjacency map/object** or a small **`Graph` builder** — all
+equivalent to the edge-array form (node IDs stay finite numbers). The builder is also the way
+to declare an **isolated vertex** (one with no incident edges), which the plain edge list
+can't express:
+
+```javascript
+import { BMSSP, Graph } from "bmssp";
+
+// Adjacency object ({ from: [[to, weight], ...] }) or a Map with the same shape:
+new BMSSP({ 0: [[1, 50], [2, 25]], 1: [[2, 75]] });
+
+// Or the chainable builder — addVertex declares nodes (incl. isolated ones):
+const g = new Graph()
+  .addEdge(0, 1, 50)
+  .addEdge(0, 2, 25)
+  .addEdge(1, 2, 75)
+  .addVertex(9); // an isolated vertex: present, but unreachable (Infinity)
+
+const graph = new BMSSP(g);
+graph.calculateShortestPaths(0);
+console.log(graph.shortestPaths.get(2)); // 25
+console.log(graph.shortestPaths.get(9)); // Infinity
+```
+
+(Plain-object keys are strings in JavaScript, so the object form coerces them to numbers;
+use a `Map` or the `Graph` builder if you want to keep numeric keys explicit.)
+
+### Multi-source and bounded runs
+
+`calculateShortestPathsFrom(sources, { bound })` runs the paper's `BMSSP(l, B, S)`
+generalization directly: from a **set** of sources, each with an initial distance, optionally
+under a strict distance **bound `B`**. Results land in `shortestPaths` just like
+`calculateShortestPaths` — single-source SSSP is exactly the special case
+`calculateShortestPathsFrom([start])`.
+
+```javascript
+import { BMSSP } from "bmssp";
+
+const g = new BMSSP([
+  [0, 1, 2],
+  [1, 2, 3],
+  [5, 2, 1],
+]);
+
+// Nearest of several sources (each seeded at distance 0):
+g.calculateShortestPathsFrom([0, 5]);
+console.log(g.shortestPaths.get(2)); // 1  (via 5 -> 2, beating 0 -> 1 -> 2 = 5)
+
+// Sources with explicit initial distances, as pairs / a Map / an object:
+g.calculateShortestPathsFrom([
+  [0, 0],
+  [5, 10],
+]);
+console.log(g.shortestPaths.get(2)); // 5  (via 0 -> 1 -> 2; 5's head start no longer wins)
+
+// Bounded: only vertices with distance < B are completed; the rest stay Infinity.
+g.calculateShortestPathsFrom([0], { bound: 4 });
+console.log(g.shortestPaths.get(1)); // 2
+console.log(g.shortestPaths.get(2)); // Infinity  (distance 5 is not < 4)
+```
+
+Sources accept a `Map<id, dist>`, an object `{ id: dist }`, an array of `[id, dist]` pairs, or
+a bare array of ids (each seeded at distance 0). Initial distances are treated as the sources'
+true (complete) distances — with the common all-zero seeding this is automatic. `bound`
+defaults to `Infinity` (unbounded).
 
 ### Optional: constant-degree transform
 
@@ -136,17 +220,24 @@ picks a valid start copy for an original node.
 
 ### Using the Docker image
 
-Run the bundled example:
+The published image is a pre-configured Node environment with `bmssp` installed and the
+[`examples/`](examples/) gallery bundled. Run the whole gallery — basic shortest paths,
+Dijkstra-oracle validation, the constant-degree transform, and a larger generated grid:
+
+```bash
+docker run --rm sirivasv/bmssp-js:latest
+```
+
+Run a single bundled example instead:
 
 ```bash
-docker run -it sirivasv/bmssp-js:latest
+docker run --rm sirivasv/bmssp-js:latest node examples/02-dijkstra-oracle.mjs
 ```
 
-Or run your own tests in a pre-configured environment (replace `folder-mytest/` with your
-tests folder and `index.mjs` with your test file):
+Or mount your own script and run it in the same environment (no local Node install needed):
 
 ```bash
-docker run -it -v ./folder-mytest/:/bmssp-js/folder-mytest/ sirivasv/bmssp-js:latest node /bmssp-js/folder-mytest/index.mjs
+docker run --rm -v "$PWD/mine.mjs:/bmssp-js/mine.mjs" sirivasv/bmssp-js:latest node mine.mjs
 ```
 
 Other image versions are on [Docker Hub](https://hub.docker.com/r/sirivasv/bmssp-js/tags).
@@ -183,8 +274,8 @@ graphs in a few seconds), and set `FUZZ_XL=1` for an additional 2-million-node r
 | --- | --- | --- |
 | [`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, 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 |
+| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, BMSSP-vs-Dijkstra benchmarks, cliff investigation, relaxation micro-optimizations | ✅ done |
+| `2.0.0` | API generalization — dense-index engine, typed/flexible inputs, public multi-source/bounded entry point, and public-API stabilization (migration note + locked surface) | ✅ done |
 
 ## Contributing (humans and AI agents welcome)
 

package/docs/index.html

@@ -141,7 +141,9 @@
         <pre><code>npm install bmssp</code></pre>
         <p>
             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.
+            edges with finite numeric node IDs and finite, non-negative weights — or,
+            equivalently, an adjacency <code>Map</code>/object or a <code>Graph</code> builder
+            (see below).
         </p>
 
         <h2>Quick start</h2>
@@ -158,18 +160,48 @@ 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>
+        <p>The package has exactly four exports: <code>BMSSP</code>, <code>Graph</code>,
+           <code>dijkstra</code>, and <code>constantDegreeTransform</code>. This surface is
+           <strong>stable as of 2.0.0</strong> — see the
+           <a href="https://github.com/Sirivasv/bmssp-js/blob/main/MIGRATION.md"
+              target="_blank" rel="noopener">1.0&nbsp;→&nbsp;2.0 migration note</a> and the
+           runnable <a href="https://github.com/Sirivasv/bmssp-js/tree/main/examples"
+              target="_blank" rel="noopener">examples gallery</a>. Anything not listed here
+           (the block list, the indexed heap, <code>BaseCase</code>/<code>FindPivots</code>,
+           and the <code>BMSSP</code> class's dense-index engine members) is internal and may
+           change in a minor release.</p>
 
-        <h3><code>new BMSSP(graph)</code></h3>
+        <h3><code>new BMSSP(input)</code></h3>
         <p>
-            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).
+            Accepts any of four input shapes and reduces them to a canonical graph: an array of
+            <code>[from, to, weight]</code> edges, an adjacency <code>Map</code>
+            (<code>Map&lt;from, [[to, weight], …]&gt;</code>), a plain adjacency object
+            (<code>{ from: [[to, weight], …] }</code>, numeric-string keys coerced to numbers),
+            or a <code>Graph</code> builder instance. Node IDs must be finite numbers and
+            weights finite and non-negative; malformed edges throw an <code>Error</code>
+            identifying the offending index. An empty graph in any shape is valid (it then has
+            no nodes, so any start node is rejected later).
         </p>
 
+        <h3><code>new Graph()</code></h3>
+        <p>
+            A small mutable input builder. <code>addVertex(id)</code> declares a vertex —
+            including an <strong>isolated</strong> one (present but with no incident edges),
+            which a bare edge list can't express — and <code>addEdge(from, to, weight)</code>
+            adds a directed weighted edge, auto-declaring its endpoints. Both validate eagerly
+            and chain; pass the instance to <code>new BMSSP(graph)</code>.
+        </p>
+<pre><code>import { BMSSP, Graph } from "bmssp";
+
+const g = new Graph()
+  .addEdge(0, 1, 50)
+  .addEdge(0, 2, 25)
+  .addVertex(9); // an isolated vertex — present, but unreachable
+
+const graph = new BMSSP(g);
+graph.calculateShortestPaths(0);
+graph.shortestPaths.get(9); // Infinity</code></pre>
+
         <h3><code>graph.calculateShortestPaths(source)</code></h3>
         <p>
             Computes shortest distances from <code>source</code> via the paper's method
@@ -183,6 +215,37 @@ graph.reconstructPath(1); // [0, 1]</code></pre>
             recomputes.
         </p>
 
+        <h3><code>graph.calculateShortestPathsFrom(sources, { bound })</code></h3>
+        <p>
+            The paper's multi-source, bounded generalization as public API: runs from a
+            <strong>set</strong> of sources, each with an initial distance, optionally under a
+            strict distance <code>bound</code> <em>B</em>. <code>sources</code> accepts a
+            <code>Map&lt;id, dist&gt;</code>, an object <code>{ id: dist }</code>, an array of
+            <code>[id, dist]</code> pairs, or a bare array of ids (each seeded at distance 0).
+            Single-source SSSP is the special case
+            <code>calculateShortestPathsFrom([start])</code>. Results land in
+            <code>shortestPaths</code> exactly like <code>calculateShortestPaths</code>. Under a
+            <strong>finite</strong> <code>bound</code>, only the completed set — vertices with
+            distance <em>&lt; B</em> — is exposed; BMSSP's above-<em>B</em> over-estimates are
+            pruned to <code>Infinity</code>. <code>bound</code> defaults to <code>Infinity</code>.
+        </p>
+<pre><code>const g = new BMSSP([[0, 1, 2], [1, 2, 3], [5, 2, 1]]);
+
+g.calculateShortestPathsFrom([0, 5]);          // nearest of two sources
+g.shortestPaths.get(2);                         // 1  (via 5 -> 2)
+
+g.calculateShortestPathsFrom([0], { bound: 4 }); // bounded
+g.shortestPaths.get(2);                         // Infinity  (distance 5 ≥ 4)</code></pre>
+
+        <div class="note">
+            <strong>Advanced:</strong> <code>graph.bmssp(l, B, S)</code> is the low-level
+            bounded multi-source primitive that <code>calculateShortestPathsFrom</code> wraps.
+            It works in composite <code>[length, hops, id]</code> key space and returns
+            <code>{ bound, boundKey, vertices }</code> (the paper's <em>B′</em>, its key, and
+            the completed set <em>U</em>). Most callers want
+            <code>calculateShortestPathsFrom</code> instead.
+        </div>
+
         <h3><code>graph.reconstructPath(target)</code></h3>
         <p>
             Returns the canonical shortest path from the most recent source to
@@ -221,18 +284,22 @@ t.collapse(g.shortestPaths);               // Map(3) { 0 => 0, 1 => 50, 2 => 25
 
         <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.
+            <code>BaseCase</code>, <code>FindPivots</code>, the linear-time selection and
+            balanced-BST bound index, the tie-break helpers, and the <code>BMSSP</code> class's
+            dense-index engine members (<code>csr</code>, <code>labels</code>,
+            <code>bmsspIndex</code>, the <code>syncLabels…</code> bridge, …) — are deliberately
+            <em>not</em> part of the public surface. They are implementation details, documented
+            in-source for contributors, and may change in a minor release.
         </div>
 
         <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
+            head-to-head, Dijkstra still wins wall-clock at practical sizes (the dense-index
+            engine narrowed the sparse gap to ~1.4×), but in the paper's own metric —
+            comparisons between path lengths — this implementation does fewer comparisons than
+            Dijkstra from well under n&nbsp;=&nbsp;50k 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.

package/index.mjs

@@ -1,16 +1,18 @@
-// 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.
+// Public API of the `bmssp` package (ESM-only). Four exports: the BMSSP
+// class, the reference `dijkstra`, the opt-in `constantDegreeTransform`, and
+// the `Graph` input builder. 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).
+ * `new BMSSP(graph)` accepts any of the #172 input shapes: an array of
+ * `[from, to, weight]` edges, an adjacency `Map`/object
+ * (`{ from: [[to, weight], ...] }`), or a `Graph` builder instance. Node IDs
+ * must be finite numbers and weights finite and non-negative; an empty graph
+ * is valid and 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
@@ -18,6 +20,14 @@
  */
 export { BMSSP } from "./src/bmssp.mjs";
 
+/**
+ * Graph — a small mutable input builder (#172). Declare vertices (including
+ * isolated ones via `addVertex`) and directed weighted edges (`addEdge`),
+ * then pass the instance to `new BMSSP(graph)`. Mutators chain
+ * (`new Graph().addEdge(0, 1, 50).addVertex(9)`). See `src/graph.mjs`.
+ */
+export { Graph } from "./src/graph.mjs";
+
 /**
  * Reference Dijkstra implementation — the oracle the BMSSP test suite is
  * validated against, exported for comparison and independent checking.

package/package.json

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

package/src/baseCase.mjs

@@ -2,9 +2,9 @@ import { MinHeap } from "./heap.mjs";
 import {
   compareKeys,
   toBound,
-  makeTies,
-  orderKey,
+  labelKey,
   relaxEdge,
+  RELAX_LOST,
 } from "./tieBreak.mjs";
 
 /**
@@ -14,18 +14,21 @@ import {
  * that stops after settling k + 1 vertices.
  *
  * Preconditions (guaranteed by the caller, Algorithm 3):
- * - S is a singleton {x} and x is complete (dHat holds its true distance).
+ * - S is a singleton {x} and x is complete (labels.dist holds its true
+ *   distance).
  * - Every incomplete vertex v with d(v) < B has a shortest path through x.
  *
- * 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. 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.
+ * Since #205 the engine works on dense vertex indices: S holds indices, the
+ * graph is the class's CSR bundle, and the labels are the shared typed
+ * arrays (see tieBreak's makeLabels) — updated in place, exactly like the
+ * paper's global d̂[·], so improvements made here are visible to the levels
+ * above. The heap is ordered by the composite [length, hops, index] keys,
+ * 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
@@ -33,26 +36,27 @@ import {
  * - 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).
+ *   ties with the boundary vertex are broken by (hops, index), 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|[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 {Set<number>|Iterable<number>} S - Singleton set holding the
+ *   complete source index x
+ * @param {{ dist: Float64Array, hops: Uint32Array, preds: Int32Array }} labels
+ *   - Engine label state (d̂[·] and tie-break labels), updated in place
+ * @param {{ offsets: Uint32Array, targets: Uint32Array, weights: Float64Array }} csr
+ *   - The graph in CSR layout over dense indices
  * @param {number} k - Settle cap parameter, >= 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 {{ bound: number|[number, number, *], boundKey: [number, number, *], vertices: Set<*> }}
+ * @returns {{ bound: number|[number, number, *], boundKey: [number, number, *], vertices: Set<number> }}
  *   The boundary B' <= B (same kind as the B passed in), its composite key,
- *   and the set U of vertices settled below it
+ *   and the set U of vertex indices 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, ties = makeTies()) {
+function baseCase(B, S, labels, csr, k) {
   if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
     throw new Error("k must be a number >= 1");
   }
@@ -62,32 +66,36 @@ function baseCase(B, S, dHat, adjacency, k, ties = makeTies()) {
     throw new Error("S must contain exactly one source node");
   }
   const [x] = sources;
-  const sourceDistance = dHat.get(x);
-  if (typeof sourceDistance !== "number" || !Number.isFinite(sourceDistance)) {
+  if (!Number.isFinite(labels.dist[x])) {
     throw new Error("the source must have a finite distance estimate");
   }
   const boundKey = toBound(B);
+  const { offsets, targets, weights } = csr;
 
   // U0 in the paper: the vertices settled by this call, seeded with x
   const settled = new Set([x]);
   const heap = new MinHeap(compareKeys);
-  heap.insert(x, orderKey(x, dHat, ties));
+  heap.insert(x, labelKey(x, labels));
 
   while (!heap.isEmpty() && settled.size < cap + 1) {
     const { key: u } = heap.extractMin();
     settled.add(u);
-    for (const [v, weight] of adjacency.get(u) ?? []) {
+    for (let e = offsets[u]; e < offsets[u + 1]; e += 1) {
+      const v = targets[e];
       // 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;
+      const result = relaxEdge(u, v, weights[e], labels, boundKey);
+      if (result === RELAX_LOST || settled.has(v)) continue;
+      // Non-lost ⇒ v's stored label IS the candidate; materialize its key
+      // only here, on the enqueue path (#168)
+      const key = labelKey(v, labels);
       if (heap.has(v)) {
-        heap.decreaseKey(v, relaxed.key);
+        heap.decreaseKey(v, key);
       } else {
-        heap.insert(v, relaxed.key);
+        heap.insert(v, key);
       }
     }
   }
@@ -101,12 +109,12 @@ function baseCase(B, S, dHat, adjacency, k, ties = makeTies()) {
   // vertices strictly below it — exactly k of them, keys being distinct
   let boundary = null;
   for (const v of settled) {
-    const key = orderKey(v, dHat, ties);
+    const key = labelKey(v, labels);
     if (boundary === null || compareKeys(key, boundary) > 0) boundary = key;
   }
   const vertices = new Set();
   for (const v of settled) {
-    if (compareKeys(orderKey(v, dHat, ties), boundary) < 0) vertices.add(v);
+    if (compareKeys(labelKey(v, labels), boundary) < 0) vertices.add(v);
   }
   return {
     bound: typeof B === "number" ? boundary[0] : boundary,