@hviana/sema 0.1.4 → 0.1.5

package/dist/src/rabitq-hnsw/test/hnsw.test.js

@@ -1,233 +1,287 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { RaBitQuantizer, VectorDatabase, } from "../src/index.js";
+import { RaBitQuantizer, VectorDatabase } from "../src/index.js";
 // ----------------------------- tiny harness ----------------------------------
 let passed = 0;
 function assert(cond, msg) {
-    if (!cond)
-        throw new Error("ASSERTION FAILED: " + msg);
-    passed++;
+  if (!cond) {
+    throw new Error("ASSERTION FAILED: " + msg);
+  }
+  passed++;
 }
 function approxEqual(a, b, eps = 1e-4) {
-    return Math.abs(a - b) <= eps * (1 + Math.abs(a) + Math.abs(b));
+  return Math.abs(a - b) <= eps * (1 + Math.abs(a) + Math.abs(b));
 }
 function section(title) {
-    console.log("\n" + "=".repeat(72) + "\n" + title + "\n" + "=".repeat(72));
+  console.log("\n" + "=".repeat(72) + "\n" + title + "\n" + "=".repeat(72));
 }
 function now() {
-    return typeof performance !== "undefined" ? performance.now() : Date.now();
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
 // ------------------------------- seeded RNG ----------------------------------
 class RNG {
-    s;
-    constructor(seed) {
-        this.s = seed >>> 0 || 1;
-    }
-    next() {
-        let t = (this.s = (this.s + 0x6d2b79f5) | 0);
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    }
-    int(n) {
-        return (this.next() * n) | 0;
-    }
-    _gaussSpare = 0;
-    _gaussHasSpare = false;
-    /** Box-Muller — caches the second value so every call produces one Gaussian
-     *  without wasting the log/sqrt pair. */
-    gauss() {
-        if (this._gaussHasSpare) {
-            this._gaussHasSpare = false;
-            return this._gaussSpare;
-        }
-        let u = 0;
-        let v = 0;
-        while (u === 0)
-            u = this.next();
-        while (v === 0)
-            v = this.next();
-        const r = Math.sqrt(-2 * Math.log(u));
-        this._gaussSpare = r * Math.sin(2 * Math.PI * v);
-        this._gaussHasSpare = true;
-        return r * Math.cos(2 * Math.PI * v);
+  s;
+  constructor(seed) {
+    this.s = seed >>> 0 || 1;
+  }
+  next() {
+    let t = (this.s = (this.s + 0x6d2b79f5) | 0);
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  }
+  int(n) {
+    return (this.next() * n) | 0;
+  }
+  _gaussSpare = 0;
+  _gaussHasSpare = false;
+  /** Box-Muller — caches the second value so every call produces one Gaussian
+   *  without wasting the log/sqrt pair. */
+  gauss() {
+    if (this._gaussHasSpare) {
+      this._gaussHasSpare = false;
+      return this._gaussSpare;
+    }
+    let u = 0;
+    let v = 0;
+    while (u === 0) {
+      u = this.next();
     }
+    while (v === 0) {
+      v = this.next();
+    }
+    const r = Math.sqrt(-2 * Math.log(u));
+    this._gaussSpare = r * Math.sin(2 * Math.PI * v);
+    this._gaussHasSpare = true;
+    return r * Math.cos(2 * Math.PI * v);
+  }
 }
 function unit(v) {
-    let s = 0;
-    for (const x of v)
-        s += x * x;
-    const n = Math.sqrt(s) || 1;
-    return v.map((x) => x / n);
+  let s = 0;
+  for (const x of v) {
+    s += x * x;
+  }
+  const n = Math.sqrt(s) || 1;
+  return v.map((x) => x / n);
 }
 // =============================================================================
 // 1) Vector CRUD + persistence (SQLite file round-trip)
 // =============================================================================
 function testCrudAndPersistence() {
-    section("1) Vector CRUD + persistence (get returns the 1-bit code)");
-    const DIM = 48; // paddedDim 64 -> codeWords 2, distinctive codes
-    const dbPath = path.join(os.tmpdir(), `rabitq-test-crud-${Date.now()}.sqlite`);
-    let db = new VectorDatabase({
-        dbPath,
-        dim: DIM,
-        M: 8,
-        efConstruction: 64,
-        seed: 7,
-    });
-    // distinct directions so the 1-bit codes differ
-    const mk = (i, scale = 1) => {
-        const v = new Array(DIM).fill(0);
-        v[i] = scale;
-        return v;
-    };
-    // Integer IDs only
-    const ID = { alpha: 1, bravo: 2, charlie: 3, delta: 4, echo: 5 };
-    const vectors = {
-        alpha: mk(0),
-        bravo: mk(10),
-        charlie: mk(20),
-        delta: mk(30),
-        echo: mk(45),
-    };
-    // CREATE
-    for (const [name, v] of Object.entries(vectors)) {
-        db.insert(ID[name], v);
-    }
-    assert(db.size === 5, "size should be 5 after inserting 5 vectors");
-    let threw = false;
-    try {
-        db.insert(ID.alpha, vectors.alpha);
-    }
-    catch {
-        threw = true;
-    }
-    assert(threw, "inserting a duplicate external id must throw");
-    // READ — returns the bare 1-bit code (Uint32Array)
-    const code = db.get(ID.alpha);
-    assert(code !== null, "get(alpha) returns a stored code");
-    assert(code instanceof Uint32Array && code.length === 2, "code is 2 packed 32-bit words");
-    assert(code.length * 32 === 64, "code covers paddedDim = 64 sign bits");
-    assert(db.get(9999) === null, "get of unknown id returns null");
-    assert(db.has(ID.bravo) && !db.has(9999), "has() reflects membership");
-    // SEARCH — querying with an exact copy returns that vector first
-    assert(db.query(vectors.alpha, 3)[0].id === ID.alpha, "exact-copy query returns alpha first");
-    assert(db.query(vectors.bravo, 1)[0].id === ID.bravo, "exact-copy query returns bravo first");
-    // UPDATE
-    db.update(ID.charlie, mk(40));
-    assert(db.query(mk(40), 1)[0].id === ID.charlie, "updated charlie is found at its new location");
-    assert(db.size === 5, "size unchanged after update");
-    // DELETE
-    assert(db.delete(ID.delta) === true, "delete returns true for existing id");
-    assert(db.delete(ID.delta) === false, "delete returns false for already removed id");
-    assert(!db.has(ID.delta) && db.size === 4, "delta removed, size now 4");
-    assert(!db.query(vectors.delta, 4).some((r) => r.id === ID.delta), "deleted vector never appears in results");
-    // PERSISTENCE round-trip — capture state, then close and reopen the same file
-    const liveKeys = Array.from(db.keys());
-    const probe = mk(0);
-    const before = db.query(probe, 4);
-    const codesBefore = new Map();
-    for (const id of liveKeys)
-        codesBefore.set(id, db.get(id));
-    db.close();
-    const reloaded = new VectorDatabase({ dbPath });
-    assert(reloaded.size === db.size, "reloaded size matches");
-    for (const id of liveKeys) {
-        const a = codesBefore.get(id);
-        const b = reloaded.get(id);
-        assert(b !== null, `reloaded code for ${id} is not null`);
-        assert(a.length === b.length, `reloaded code length for ${id} matches`);
-        for (let i = 0; i < a.length; i++) {
-            assert(a[i] === b[i], `reloaded code word for ${id} matches`);
-        }
+  section("1) Vector CRUD + persistence (get returns the 1-bit code)");
+  const DIM = 48; // paddedDim 64 -> codeWords 2, distinctive codes
+  const dbPath = path.join(
+    os.tmpdir(),
+    `rabitq-test-crud-${Date.now()}.sqlite`,
+  );
+  let db = new VectorDatabase({
+    dbPath,
+    dim: DIM,
+    M: 8,
+    efConstruction: 64,
+    seed: 7,
+  });
+  // distinct directions so the 1-bit codes differ
+  const mk = (i, scale = 1) => {
+    const v = new Array(DIM).fill(0);
+    v[i] = scale;
+    return v;
+  };
+  // Integer IDs only
+  const ID = { alpha: 1, bravo: 2, charlie: 3, delta: 4, echo: 5 };
+  const vectors = {
+    alpha: mk(0),
+    bravo: mk(10),
+    charlie: mk(20),
+    delta: mk(30),
+    echo: mk(45),
+  };
+  // CREATE
+  for (const [name, v] of Object.entries(vectors)) {
+    db.insert(ID[name], v);
+  }
+  assert(db.size === 5, "size should be 5 after inserting 5 vectors");
+  let threw = false;
+  try {
+    db.insert(ID.alpha, vectors.alpha);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "inserting a duplicate external id must throw");
+  // READ — returns the bare 1-bit code (Uint32Array)
+  const code = db.get(ID.alpha);
+  assert(code !== null, "get(alpha) returns a stored code");
+  assert(
+    code instanceof Uint32Array && code.length === 2,
+    "code is 2 packed 32-bit words",
+  );
+  assert(code.length * 32 === 64, "code covers paddedDim = 64 sign bits");
+  assert(db.get(9999) === null, "get of unknown id returns null");
+  assert(db.has(ID.bravo) && !db.has(9999), "has() reflects membership");
+  // SEARCH — querying with an exact copy returns that vector first
+  assert(
+    db.query(vectors.alpha, 3)[0].id === ID.alpha,
+    "exact-copy query returns alpha first",
+  );
+  assert(
+    db.query(vectors.bravo, 1)[0].id === ID.bravo,
+    "exact-copy query returns bravo first",
+  );
+  // UPDATE
+  db.update(ID.charlie, mk(40));
+  assert(
+    db.query(mk(40), 1)[0].id === ID.charlie,
+    "updated charlie is found at its new location",
+  );
+  assert(db.size === 5, "size unchanged after update");
+  // DELETE
+  assert(db.delete(ID.delta) === true, "delete returns true for existing id");
+  assert(
+    db.delete(ID.delta) === false,
+    "delete returns false for already removed id",
+  );
+  assert(!db.has(ID.delta) && db.size === 4, "delta removed, size now 4");
+  assert(
+    !db.query(vectors.delta, 4).some((r) => r.id === ID.delta),
+    "deleted vector never appears in results",
+  );
+  // PERSISTENCE round-trip — capture state, then close and reopen the same file
+  const liveKeys = Array.from(db.keys());
+  const probe = mk(0);
+  const before = db.query(probe, 4);
+  const codesBefore = new Map();
+  for (const id of liveKeys) {
+    codesBefore.set(id, db.get(id));
+  }
+  db.close();
+  const reloaded = new VectorDatabase({ dbPath });
+  assert(reloaded.size === db.size, "reloaded size matches");
+  for (const id of liveKeys) {
+    const a = codesBefore.get(id);
+    const b = reloaded.get(id);
+    assert(b !== null, `reloaded code for ${id} is not null`);
+    assert(a.length === b.length, `reloaded code length for ${id} matches`);
+    for (let i = 0; i < a.length; i++) {
+      assert(a[i] === b[i], `reloaded code word for ${id} matches`);
     }
-    const after = reloaded.query(probe, 4);
-    assert(before.length === after.length, "reloaded query result length matches");
-    for (let i = 0; i < before.length; i++) {
-        assert(before[i].id === after[i].id, "reloaded query ordering matches");
-        assert(approxEqual(before[i].distance, after[i].distance, 1e-6), "reloaded query distance matches");
-    }
-    reloaded.close();
-    // Cleanup
-    fs.unlinkSync(dbPath);
-    console.log(`CRUD + persistence OK (get returns ${code.length}-word codes; reload identical)`);
+  }
+  const after = reloaded.query(probe, 4);
+  assert(
+    before.length === after.length,
+    "reloaded query result length matches",
+  );
+  for (let i = 0; i < before.length; i++) {
+    assert(before[i].id === after[i].id, "reloaded query ordering matches");
+    assert(
+      approxEqual(before[i].distance, after[i].distance, 1e-6),
+      "reloaded query distance matches",
+    );
+  }
+  reloaded.close();
+  // Cleanup
+  fs.unlinkSync(dbPath);
+  console.log(
+    `CRUD + persistence OK (get returns ${code.length}-word codes; reload identical)`,
+  );
 }
 // =============================================================================
 // 1b) insert / update / query by an already-quantized 1-bit code
 // =============================================================================
 function testCodeIO() {
-    section("1b) insert / update / query by a 1-bit code (length-detected)");
-    const DIM = 128; // paddedDim 128 -> codeWords 4
-    const rng = new RNG(909);
-    const vec = () => Array.from({ length: DIM }, () => rng.gauss());
-    const db = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 16,
-        efConstruction: 100,
-        seed: 5,
-    });
-    const N = 800;
-    for (let i = 0; i < N; i++)
-        db.insert(i, vec());
-    const src = db.get(123);
-    assert(src instanceof Uint32Array && src.length === 4, "get() yields a 4-word code");
-    // QUERY by code: a stored code finds itself at distance 0
-    const byCode = db.query(src, 5);
-    assert(byCode[0].id === 123, "query(code) returns the owning vector first");
-    assert(approxEqual(byCode[0].distance, 0, 1e-9), "query(code) distance to the same code is 0");
-    // INSERT by code (length-detected): the copy is a real, findable node
-    const copyId = N + 1;
-    db.insert(copyId, src);
-    assert(db.size === N + 1, "insert(code) adds a vector");
-    const copyCode = db.get(copyId);
-    for (let i = 0; i < src.length; i++) {
-        assert(copyCode[i] === src[i], "insert(code) stored the code verbatim");
-    }
-    const hits = db.query(src, 5).map((h) => h.id);
-    assert(hits.includes(copyId) && hits.includes(123), "both the original and its code-copy are retrievable");
-    // number[] code (e.g. after conversion) is detected the same way
-    const asArray = Array.from(src);
-    const arrId = N + 2;
-    db.insert(arrId, asArray);
-    const arrCode = db.get(arrId);
-    for (let i = 0; i < src.length; i++) {
-        assert(arrCode[i] === src[i], "insert(number[] code) works identically");
-    }
-    // UPDATE by code: move id 7 onto id 200's code
-    const target = db.get(200);
-    db.update(7, target);
-    const moved = db.get(7);
-    for (let i = 0; i < target.length; i++) {
-        assert(moved[i] === target[i], "update(code) replaced the code");
-    }
-    assert(db.size === N + 2, "update(code) keeps size (replace, not add)");
-    const near200 = db.query(target, 5).map((h) => h.id);
-    assert(near200.includes(7) && near200.includes(200), "updated-by-code id now sits with its target");
-    db.close();
-    console.log("insert / update / query by 1-bit code OK (Uint32Array and number[])");
+  section("1b) insert / update / query by a 1-bit code (length-detected)");
+  const DIM = 128; // paddedDim 128 -> codeWords 4
+  const rng = new RNG(909);
+  const vec = () => Array.from({ length: DIM }, () => rng.gauss());
+  const db = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 16,
+    efConstruction: 100,
+    seed: 5,
+  });
+  const N = 800;
+  for (let i = 0; i < N; i++) {
+    db.insert(i, vec());
+  }
+  const src = db.get(123);
+  assert(
+    src instanceof Uint32Array && src.length === 4,
+    "get() yields a 4-word code",
+  );
+  // QUERY by code: a stored code finds itself at distance 0
+  const byCode = db.query(src, 5);
+  assert(byCode[0].id === 123, "query(code) returns the owning vector first");
+  assert(
+    approxEqual(byCode[0].distance, 0, 1e-9),
+    "query(code) distance to the same code is 0",
+  );
+  // INSERT by code (length-detected): the copy is a real, findable node
+  const copyId = N + 1;
+  db.insert(copyId, src);
+  assert(db.size === N + 1, "insert(code) adds a vector");
+  const copyCode = db.get(copyId);
+  for (let i = 0; i < src.length; i++) {
+    assert(copyCode[i] === src[i], "insert(code) stored the code verbatim");
+  }
+  const hits = db.query(src, 5).map((h) => h.id);
+  assert(
+    hits.includes(copyId) && hits.includes(123),
+    "both the original and its code-copy are retrievable",
+  );
+  // number[] code (e.g. after conversion) is detected the same way
+  const asArray = Array.from(src);
+  const arrId = N + 2;
+  db.insert(arrId, asArray);
+  const arrCode = db.get(arrId);
+  for (let i = 0; i < src.length; i++) {
+    assert(arrCode[i] === src[i], "insert(number[] code) works identically");
+  }
+  // UPDATE by code: move id 7 onto id 200's code
+  const target = db.get(200);
+  db.update(7, target);
+  const moved = db.get(7);
+  for (let i = 0; i < target.length; i++) {
+    assert(moved[i] === target[i], "update(code) replaced the code");
+  }
+  assert(db.size === N + 2, "update(code) keeps size (replace, not add)");
+  const near200 = db.query(target, 5).map((h) => h.id);
+  assert(
+    near200.includes(7) && near200.includes(200),
+    "updated-by-code id now sits with its target",
+  );
+  db.close();
+  console.log(
+    "insert / update / query by 1-bit code OK (Uint32Array and number[])",
+  );
 }
 // =============================================================================
 // 2) Cosine metric sanity
 // =============================================================================
 function testCosine() {
-    section("2) Cosine sanity");
-    const DIM = 64;
-    const db = new VectorDatabase({ dbPath: ":memory:", dim: DIM, seed: 3 });
-    const axis = (i) => {
-        const v = new Array(DIM).fill(0);
-        v[i] = 1;
-        return v;
-    };
-    db.insert(1, axis(0)); // "x"
-    db.insert(2, axis(20)); // "y"
-    db.insert(3, axis(40)); // "z"
-    const r = db.query(axis(0), 3); // query along x's direction
-    assert(r[0].id === 1, "cosine: nearest direction to x's axis is x");
-    assert(r[0].distance <= 0.1, "cosine distance to an identical direction is ~ 0");
-    assert(r[r.length - 1].distance > r[0].distance, "orthogonal directions are farther than the aligned one");
-    db.close();
-    console.log("Cosine metric OK");
+  section("2) Cosine sanity");
+  const DIM = 64;
+  const db = new VectorDatabase({ dbPath: ":memory:", dim: DIM, seed: 3 });
+  const axis = (i) => {
+    const v = new Array(DIM).fill(0);
+    v[i] = 1;
+    return v;
+  };
+  db.insert(1, axis(0)); // "x"
+  db.insert(2, axis(20)); // "y"
+  db.insert(3, axis(40)); // "z"
+  const r = db.query(axis(0), 3); // query along x's direction
+  assert(r[0].id === 1, "cosine: nearest direction to x's axis is x");
+  assert(
+    r[0].distance <= 0.1,
+    "cosine distance to an identical direction is ~ 0",
+  );
+  assert(
+    r[r.length - 1].distance > r[0].distance,
+    "orthogonal directions are farther than the aligned one",
+  );
+  db.close();
+  console.log("Cosine metric OK");
 }
 // =============================================================================
 // 2a) Near-duplicate self-recall (tight cluster)
@@ -251,68 +305,86 @@ function testCosine() {
 // assertions pin both ends: an explicit 4 bits is measurably degraded, the
 // default recovers.
 function testNearDuplicateRecall() {
-    section("2a) Near-duplicate self-recall (tight cluster)");
-    const DIM = 256;
-    const N = 150;
-    const SPREAD = 0.15;
-    // A fixed base direction; each vector is the base plus a small per-coordinate
-    // perturbation, then normalised — a dense cluster of near-duplicates. A plain
-    // LCG drives the perturbation: it produces a uniformly spread cloud around the
-    // base (the regime where the queryBits effect is sharpest); the Box-Muller
-    // RNG above clusters too tightly to separate the two settings.
-    const build = (queryBits) => {
-        let s = 7 >>> 0;
-        const next = () => {
-            s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
-            return s / 4294967296;
-        };
-        const base = new Array(DIM);
-        for (let d = 0; d < DIM; d++)
-            base[d] = next() * 2 - 1;
-        const vecs = [];
-        const db = new VectorDatabase({
-            dbPath: ":memory:",
-            dim: DIM,
-            M: 16,
-            efConstruction: 64,
-            efSearch: 64,
-            seed: 123,
-            queryBits,
-        });
-        for (let i = 0; i < N; i++) {
-            const v = new Array(DIM);
-            let n = 0;
-            for (let d = 0; d < DIM; d++) {
-                v[d] = base[d] + SPREAD * (next() * 2 - 1);
-                n += v[d] * v[d];
-            }
-            n = Math.sqrt(n) || 1;
-            for (let d = 0; d < DIM; d++)
-                v[d] /= n;
-            vecs.push(v);
-            db.insert(i, v);
-        }
-        let self = 0;
-        for (let i = 0; i < N; i++) {
-            const h = db.query(vecs[i], 1);
-            if (h[0] && h[0].id === i)
-                self++;
-        }
-        db.close();
-        return self / N;
+  section("2a) Near-duplicate self-recall (tight cluster)");
+  const DIM = 256;
+  const N = 150;
+  const SPREAD = 0.15;
+  // A fixed base direction; each vector is the base plus a small per-coordinate
+  // perturbation, then normalised — a dense cluster of near-duplicates. A plain
+  // LCG drives the perturbation: it produces a uniformly spread cloud around the
+  // base (the regime where the queryBits effect is sharpest); the Box-Muller
+  // RNG above clusters too tightly to separate the two settings.
+  const build = (queryBits) => {
+    let s = 7 >>> 0;
+    const next = () => {
+      s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+      return s / 4294967296;
     };
-    const r4 = build(4); // explicitly coarse — the old default
-    const rDefault = build(8); // the library default after the fix
-    console.log(`near-duplicate self-recall: queryBits=4 ${(r4 * 100).toFixed(1)}%  ` +
-        `default(8) ${(rDefault * 100).toFixed(1)}%`);
-    // The bug: 4-bit query quantisation cannot resolve a tight cluster, so a
-    // sizeable fraction of vectors fail to retrieve themselves.
-    assert(r4 < 0.9, `queryBits=4 is degraded on a tight cluster (got ${(r4 * 100).toFixed(1)}%)`);
-    // The fix: the default B_q restores near-perfect self-recall — same stored
-    // codes, sharper query estimate.
-    assert(rDefault >= 0.95, `default queryBits recovers self-recall on a tight cluster (got ${(rDefault * 100).toFixed(1)}%)`);
-    assert(rDefault > r4, "the default queryBits must beat the coarse 4-bit setting");
-    console.log("Near-duplicate self-recall OK (queryBits resolves the cluster)");
+    const base = new Array(DIM);
+    for (let d = 0; d < DIM; d++) {
+      base[d] = next() * 2 - 1;
+    }
+    const vecs = [];
+    const db = new VectorDatabase({
+      dbPath: ":memory:",
+      dim: DIM,
+      M: 16,
+      efConstruction: 64,
+      efSearch: 64,
+      seed: 123,
+      queryBits,
+    });
+    for (let i = 0; i < N; i++) {
+      const v = new Array(DIM);
+      let n = 0;
+      for (let d = 0; d < DIM; d++) {
+        v[d] = base[d] + SPREAD * (next() * 2 - 1);
+        n += v[d] * v[d];
+      }
+      n = Math.sqrt(n) || 1;
+      for (let d = 0; d < DIM; d++) {
+        v[d] /= n;
+      }
+      vecs.push(v);
+      db.insert(i, v);
+    }
+    let self = 0;
+    for (let i = 0; i < N; i++) {
+      const h = db.query(vecs[i], 1);
+      if (h[0] && h[0].id === i) {
+        self++;
+      }
+    }
+    db.close();
+    return self / N;
+  };
+  const r4 = build(4); // explicitly coarse — the old default
+  const rDefault = build(8); // the library default after the fix
+  console.log(
+    `near-duplicate self-recall: queryBits=4 ${(r4 * 100).toFixed(1)}%  ` +
+      `default(8) ${(rDefault * 100).toFixed(1)}%`,
+  );
+  // The bug: 4-bit query quantisation cannot resolve a tight cluster, so a
+  // sizeable fraction of vectors fail to retrieve themselves.
+  assert(
+    r4 < 0.9,
+    `queryBits=4 is degraded on a tight cluster (got ${
+      (r4 * 100).toFixed(1)
+    }%)`,
+  );
+  // The fix: the default B_q restores near-perfect self-recall — same stored
+  // codes, sharper query estimate.
+  assert(
+    rDefault >= 0.95,
+    `default queryBits recovers self-recall on a tight cluster (got ${
+      (rDefault * 100).toFixed(1)
+    }%)`,
+  );
+  assert(
+    rDefault > r4,
+    "the default queryBits must beat the coarse 4-bit setting",
+  );
+  console.log("Near-duplicate self-recall OK (queryBits resolves the cluster)");
 }
 // =============================================================================
 // 2a-bis) The cosFactor bias — a known, deliberate approximation in estimate()
@@ -345,485 +417,643 @@ function testNearDuplicateRecall() {
 // here would tighten to ~0 and the negatives would vanish — at which point this
 // test is the tripwire that flags the behavioural change.
 function testCosFactorBias() {
-    section("2a-bis) cosFactor self-distance bias (fixed mean vs per-vector norm)");
-    const DIM = 256;
-    const N = 300;
-    const SPREAD = 0.15;
-    let s = 7 >>> 0;
-    const next = () => {
-        s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
-        return s / 4294967296;
-    };
-    const base = new Array(DIM);
-    for (let d = 0; d < DIM; d++)
-        base[d] = next() * 2 - 1;
-    const q = new RaBitQuantizer(DIM, { seed: 123 });
-    const vecs = [];
-    const codes = [];
-    for (let i = 0; i < N; i++) {
-        const v = new Array(DIM);
-        let n = 0;
-        for (let d = 0; d < DIM; d++) {
-            v[d] = base[d] + SPREAD * (next() * 2 - 1);
-            n += v[d] * v[d];
-        }
-        n = Math.sqrt(n) || 1;
-        for (let d = 0; d < DIM; d++)
-            v[d] /= n;
-        vecs.push(v);
-        codes.push(q.codeToBytes(q.encode(v)));
-    }
-    // Self-distance: each vector scored against its OWN code. An unbiased cosine
-    // estimator returns 0 here; the fixed cosFactor does not.
-    let sum = 0;
-    let max = 0;
-    let negatives = 0;
-    for (let i = 0; i < N; i++) {
-        const ctx = q.prepareQuery(vecs[i]);
-        const d = q.estimate(codes[i], 0, ctx);
-        sum += d;
-        if (d > max)
-            max = d;
-        if (d < 0)
-            negatives++; // distance < 0  <=>  estimated cosine > 1 (impossible)
-    }
-    const mean = sum / N;
-    console.log(`self-distance under fixed cosFactor: mean ${mean.toFixed(5)}, ` +
-        `max ${max.toFixed(5)}, negatives ${negatives}/${N} ` +
-        `(an unbiased estimator would give 0 with 0 negatives)`);
-    // The estimate is genuinely non-zero on a self-match: the fixed mean factor
-    // does not reproduce the per-vector normalisation.
-    assert(max > 0.005, `self-distance is biased away from 0 (max ${max.toFixed(5)})`);
-    // The fingerprint: a large fraction of self-matches yield an IMPOSSIBLE
-    // cosine > 1 (negative distance) — only a mean-vs-per-vector substitution
-    // produces this. If this ever drops to 0, estimate() changed.
-    assert(negatives > N / 10, `cosFactor produces impossible cosine>1 on self-matches ` +
-        `(${negatives}/${N} negative distances)`);
-    console.log("cosFactor bias documented (fixed mean L1 norm, not the per-vector factor)");
+  section(
+    "2a-bis) cosFactor self-distance bias (fixed mean vs per-vector norm)",
+  );
+  const DIM = 256;
+  const N = 300;
+  const SPREAD = 0.15;
+  let s = 7 >>> 0;
+  const next = () => {
+    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+    return s / 4294967296;
+  };
+  const base = new Array(DIM);
+  for (let d = 0; d < DIM; d++) {
+    base[d] = next() * 2 - 1;
+  }
+  const q = new RaBitQuantizer(DIM, { seed: 123 });
+  const vecs = [];
+  const codes = [];
+  for (let i = 0; i < N; i++) {
+    const v = new Array(DIM);
+    let n = 0;
+    for (let d = 0; d < DIM; d++) {
+      v[d] = base[d] + SPREAD * (next() * 2 - 1);
+      n += v[d] * v[d];
+    }
+    n = Math.sqrt(n) || 1;
+    for (let d = 0; d < DIM; d++) {
+      v[d] /= n;
+    }
+    vecs.push(v);
+    codes.push(q.codeToBytes(q.encode(v)));
+  }
+  // Self-distance: each vector scored against its OWN code. An unbiased cosine
+  // estimator returns 0 here; the fixed cosFactor does not.
+  let sum = 0;
+  let max = 0;
+  let negatives = 0;
+  for (let i = 0; i < N; i++) {
+    const ctx = q.prepareQuery(vecs[i]);
+    const d = q.estimate(codes[i], 0, ctx);
+    sum += d;
+    if (d > max) {
+      max = d;
+    }
+    if (d < 0) {
+      negatives++; // distance < 0  <=>  estimated cosine > 1 (impossible)
+    }
+  }
+  const mean = sum / N;
+  console.log(
+    `self-distance under fixed cosFactor: mean ${mean.toFixed(5)}, ` +
+      `max ${max.toFixed(5)}, negatives ${negatives}/${N} ` +
+      `(an unbiased estimator would give 0 with 0 negatives)`,
+  );
+  // The estimate is genuinely non-zero on a self-match: the fixed mean factor
+  // does not reproduce the per-vector normalisation.
+  assert(
+    max > 0.005,
+    `self-distance is biased away from 0 (max ${max.toFixed(5)})`,
+  );
+  // The fingerprint: a large fraction of self-matches yield an IMPOSSIBLE
+  // cosine > 1 (negative distance) — only a mean-vs-per-vector substitution
+  // produces this. If this ever drops to 0, estimate() changed.
+  assert(
+    negatives > N / 10,
+    `cosFactor produces impossible cosine>1 on self-matches ` +
+      `(${negatives}/${N} negative distances)`,
+  );
+  console.log(
+    "cosFactor bias documented (fixed mean L1 norm, not the per-vector factor)",
+  );
 }
 // =============================================================================
 // 2b) SQLite persistence round-trip
 // =============================================================================
 function testPersistence() {
-    section("2b) SQLite persistence round-trip");
-    const DIM = 96;
-    const rng = new RNG(2024);
-    const vec = () => Array.from({ length: DIM }, () => rng.gauss());
-    {
-        const dbPath = path.join(os.tmpdir(), `rabitq-test-persist-${Date.now()}.sqlite`);
-        const db = new VectorDatabase({
-            dbPath,
-            dim: DIM,
-            M: 12,
-            efConstruction: 80,
-            seed: 17,
-        });
-        for (let i = 0; i < 1500; i++)
-            db.insert(i, vec());
-        for (let i = 0; i < 150; i++)
-            db.delete(i * 10); // tombstones
-        for (let i = 0; i < 120; i++)
-            db.update(3 + i * 10, vec()); // re-inserts
-        // Capture state before closing
-        const liveKeys = Array.from(db.keys());
-        const codesBefore = new Map();
-        for (const id of liveKeys)
-            codesBefore.set(id, db.get(id));
-        const queriesBefore = [];
-        for (let q = 0; q < 40; q++) {
-            const query = vec();
-            queriesBefore.push({ query, results: db.query(query, 10) });
-        }
-        const sizeBefore = db.size;
-        db.close();
-        // Reopen from file
-        const db2 = new VectorDatabase({ dbPath });
-        assert(db2.size === sizeBefore, "size preserved across persistence round-trip");
-        // get() parity: identical codes for every live id
-        for (const id of liveKeys) {
-            const a = codesBefore.get(id);
-            const b = db2.get(id);
-            assert(b !== null, `id ${id} present after reload`);
-            assert(a.length === b.length, "code length identical after reload");
-            for (let i = 0; i < a.length; i++) {
-                assert(a[i] === b[i], "code identical after reload");
-            }
-        }
-        // query parity: identical ids and (bit-exact) distances
-        let maxDiff = 0;
-        for (const { query, results: ra } of queriesBefore) {
-            const rb = db2.query(query, 10);
-            assert(ra.length === rb.length, "result length identical after reload");
-            for (let i = 0; i < ra.length; i++) {
-                assert(ra[i].id === rb[i].id, "result id/order identical after reload");
-                maxDiff = Math.max(maxDiff, Math.abs(ra[i].distance - rb[i].distance));
-            }
-        }
-        assert(maxDiff === 0, `distances are bit-exact after reload (max diff ${maxDiff})`);
-        // Mutation still works after a reload
-        db2.insert(99999, vec());
-        assert(db2.has(99999), "insert works after persistence load");
-        assert(db2.get(99999) !== null, "get works after persistence load");
-        db2.close();
-        fs.unlinkSync(dbPath);
-        console.log(`${sizeBefore} vecs, round-trip via SQLite file — exact match`);
-    }
-    // Non-existent file: node:sqlite may create the file or may error — this is
-    // implementation-specific. We just verify no crash.
-    try {
-        new VectorDatabase({ dbPath: "/nonexistent/path/db.sqlite" });
-    }
-    catch {
-        // tolerated — either outcome is acceptable
-    }
-    console.log("Non-existent path handled gracefully");
+  section("2b) SQLite persistence round-trip");
+  const DIM = 96;
+  const rng = new RNG(2024);
+  const vec = () => Array.from({ length: DIM }, () => rng.gauss());
+  {
+    const dbPath = path.join(
+      os.tmpdir(),
+      `rabitq-test-persist-${Date.now()}.sqlite`,
+    );
+    const db = new VectorDatabase({
+      dbPath,
+      dim: DIM,
+      M: 12,
+      efConstruction: 80,
+      seed: 17,
+    });
+    for (let i = 0; i < 1500; i++) {
+      db.insert(i, vec());
+    }
+    for (let i = 0; i < 150; i++) {
+      db.delete(i * 10); // tombstones
+    }
+    for (let i = 0; i < 120; i++) {
+      db.update(3 + i * 10, vec()); // re-inserts
+    }
+    // Capture state before closing
+    const liveKeys = Array.from(db.keys());
+    const codesBefore = new Map();
+    for (const id of liveKeys) {
+      codesBefore.set(id, db.get(id));
+    }
+    const queriesBefore = [];
+    for (let q = 0; q < 40; q++) {
+      const query = vec();
+      queriesBefore.push({ query, results: db.query(query, 10) });
+    }
+    const sizeBefore = db.size;
+    db.close();
+    // Reopen from file
+    const db2 = new VectorDatabase({ dbPath });
+    assert(
+      db2.size === sizeBefore,
+      "size preserved across persistence round-trip",
+    );
+    // get() parity: identical codes for every live id
+    for (const id of liveKeys) {
+      const a = codesBefore.get(id);
+      const b = db2.get(id);
+      assert(b !== null, `id ${id} present after reload`);
+      assert(a.length === b.length, "code length identical after reload");
+      for (let i = 0; i < a.length; i++) {
+        assert(a[i] === b[i], "code identical after reload");
+      }
+    }
+    // query parity: identical ids and (bit-exact) distances
+    let maxDiff = 0;
+    for (const { query, results: ra } of queriesBefore) {
+      const rb = db2.query(query, 10);
+      assert(ra.length === rb.length, "result length identical after reload");
+      for (let i = 0; i < ra.length; i++) {
+        assert(ra[i].id === rb[i].id, "result id/order identical after reload");
+        maxDiff = Math.max(maxDiff, Math.abs(ra[i].distance - rb[i].distance));
+      }
+    }
+    assert(
+      maxDiff === 0,
+      `distances are bit-exact after reload (max diff ${maxDiff})`,
+    );
+    // Mutation still works after a reload
+    db2.insert(99999, vec());
+    assert(db2.has(99999), "insert works after persistence load");
+    assert(db2.get(99999) !== null, "get works after persistence load");
+    db2.close();
+    fs.unlinkSync(dbPath);
+    console.log(`${sizeBefore} vecs, round-trip via SQLite file — exact match`);
+  }
+  // Non-existent file: node:sqlite may create the file or may error — this is
+  // implementation-specific. We just verify no crash.
+  try {
+    new VectorDatabase({ dbPath: "/nonexistent/path/db.sqlite" });
+  } catch {
+    // tolerated — either outcome is acceptable
+  }
+  console.log("Non-existent path handled gracefully");
 }
 // =============================================================================
 // 2c) compact() — lossless rebuild that reclaims tombstones
 // =============================================================================
 function testCompact() {
-    section("2c) compact() — lossless rebuild reclaiming tombstones");
-    const DIM = 80;
-    const rng = new RNG(555);
-    const vec = () => Array.from({ length: DIM }, () => rng.gauss());
-    // ---- losslessness: build-then-delete-then-compact == fresh build of survivors ----
-    const N = 2500;
-    const data = [];
-    for (let i = 0; i < N; i++)
-        data.push(vec());
-    const deleted = new Set();
-    for (let i = 0; i < N; i += 3)
-        deleted.add(i); // delete ~1/3
-    const dbFull = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 16,
-        efConstruction: 100,
-        seed: 88,
-    });
-    for (let i = 0; i < N; i++)
-        dbFull.insert(i, data[i]);
-    for (const i of deleted)
-        dbFull.delete(i);
-    assert(dbFull.physicalSize === N, "before compact: tombstones still occupy physical slots");
-    assert(dbFull.size === N - deleted.size, "before compact: live size already excludes deleted");
-    dbFull.compact();
-    const survivors = [];
-    for (let i = 0; i < N; i++)
-        if (!deleted.has(i))
-            survivors.push(i);
-    assert(dbFull.size === survivors.length, "after compact: size is the survivor count");
-    assert(dbFull.physicalSize === survivors.length, "after compact: no tombstones remain (physical == live)");
-    for (const i of survivors) {
-        assert(dbFull.has(i), `survivor ${i} still present after compact`);
-    }
-    for (const i of deleted) {
-        assert(!dbFull.has(i), `deleted ${i} absent after compact`);
-    }
-    // Fresh index built from the survivors, same order + seed.
-    const dbFresh = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 16,
-        efConstruction: 100,
-        seed: 88,
-    });
-    for (const i of survivors)
-        dbFresh.insert(i, data[i]);
-    // HNSW is an approximate index — two builds with the same data+seed may
-    // produce slightly different graphs (the heuristic is not order-invariant
-    // under all edge cases).  What matters is that recall between the two is
-    // very high, and that distances are consistent.
-    let compactHits = 0;
-    let maxDistDiff = 0;
-    let totalCmp = 0;
-    for (let q = 0; q < 60; q++) {
-        const query = vec();
-        const a = dbFull.query(query, 10);
-        const b = dbFresh.query(query, 10);
-        const bIds = new Set(b.map((r) => r.id));
-        for (const r of a)
-            if (bIds.has(r.id))
-                compactHits++;
-        totalCmp += a.length;
-        for (let i = 0; i < Math.min(a.length, b.length); i++) {
-            maxDistDiff = Math.max(maxDistDiff, Math.abs(a[i].distance - b[i].distance));
-        }
+  section("2c) compact() — lossless rebuild reclaiming tombstones");
+  const DIM = 80;
+  const rng = new RNG(555);
+  const vec = () => Array.from({ length: DIM }, () => rng.gauss());
+  // ---- losslessness: build-then-delete-then-compact == fresh build of survivors ----
+  const N = 2500;
+  const data = [];
+  for (let i = 0; i < N; i++) {
+    data.push(vec());
+  }
+  const deleted = new Set();
+  for (let i = 0; i < N; i += 3) {
+    deleted.add(i); // delete ~1/3
+  }
+  const dbFull = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 16,
+    efConstruction: 100,
+    seed: 88,
+  });
+  for (let i = 0; i < N; i++) {
+    dbFull.insert(i, data[i]);
+  }
+  for (const i of deleted) {
+    dbFull.delete(i);
+  }
+  assert(
+    dbFull.physicalSize === N,
+    "before compact: tombstones still occupy physical slots",
+  );
+  assert(
+    dbFull.size === N - deleted.size,
+    "before compact: live size already excludes deleted",
+  );
+  dbFull.compact();
+  const survivors = [];
+  for (let i = 0; i < N; i++) {
+    if (!deleted.has(i)) {
+      survivors.push(i);
     }
-    const recallCompact = compactHits / totalCmp;
-    assert(recallCompact >= 0.97, `compacted recall vs fresh build must be high (got ${(recallCompact * 100).toFixed(1)}%)`);
-    assert(maxDistDiff < 0.05, `distance agreement across the two builds (max diff ${maxDistDiff})`);
-    console.log(`losslessness: ${N} built, ${deleted.size} deleted, compacted to ${survivors.length}; recall vs fresh=${(recallCompact * 100).toFixed(1)}%`);
-    // ---- compact also handles updates, and recall stays high on separable data ----
-    const G = 10;
-    const groups = 400;
-    const centers = [];
-    for (let g = 0; g < groups; g++)
-        centers.push(vec());
-    const db2 = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 16,
-        efConstruction: 100,
-        seed: 7,
-    });
-    const live = new Map();
-    let id = 0;
-    for (let g = 0; g < groups; g++) {
-        for (let j = 0; j < G; j++) {
-            const v = centers[g].map((c) => c + 0.1 * rng.gauss());
-            db2.insert(id, v);
-            live.set(id, v);
-            id++;
-        }
+  }
+  assert(
+    dbFull.size === survivors.length,
+    "after compact: size is the survivor count",
+  );
+  assert(
+    dbFull.physicalSize === survivors.length,
+    "after compact: no tombstones remain (physical == live)",
+  );
+  for (const i of survivors) {
+    assert(dbFull.has(i), `survivor ${i} still present after compact`);
+  }
+  for (const i of deleted) {
+    assert(!dbFull.has(i), `deleted ${i} absent after compact`);
+  }
+  // Fresh index built from the survivors, same order + seed.
+  const dbFresh = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 16,
+    efConstruction: 100,
+    seed: 88,
+  });
+  for (const i of survivors) {
+    dbFresh.insert(i, data[i]);
+  }
+  // HNSW is an approximate index — two builds with the same data+seed may
+  // produce slightly different graphs (the heuristic is not order-invariant
+  // under all edge cases).  What matters is that recall between the two is
+  // very high, and that distances are consistent.
+  let compactHits = 0;
+  let maxDistDiff = 0;
+  let totalCmp = 0;
+  for (let q = 0; q < 60; q++) {
+    const query = vec();
+    const a = dbFull.query(query, 10);
+    const b = dbFresh.query(query, 10);
+    const bIds = new Set(b.map((r) => r.id));
+    for (const r of a) {
+      if (bIds.has(r.id)) {
+        compactHits++;
+      }
     }
-    for (let k = 0; k < 400; k++)
-        db2.delete(k); // drop 40 whole groups
-    for (let k = 0; k < 400; k++)
-        live.delete(k);
-    for (let k = 600; k < 800; k++) {
-        const v = centers[Math.floor(k / G)].map((c) => c + 0.1 * rng.gauss());
-        db2.update(k, v); // re-place within the same group
-        live.set(k, v);
-    }
-    assert(db2.physicalSize > db2.size, "updates+deletes created tombstones");
-    db2.compact();
-    assert(db2.physicalSize === db2.size && db2.size === live.size, "compact reclaimed all tombstones");
-    // recall@10 over the surviving set after compaction
-    const liveIds = Array.from(live.keys());
-    const liveVecs = Array.from(live.values());
-    // Precompute data norms once (they don't change per query).
-    const liveNorms = new Float64Array(liveVecs.length);
-    for (let n = 0; n < liveVecs.length; n++) {
-        let s = 0;
-        const v = liveVecs[n];
-        for (let d = 0; d < DIM; d++)
-            s += v[d] * v[d];
-        liveNorms[n] = Math.sqrt(s) || 1;
+    totalCmp += a.length;
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+      maxDistDiff = Math.max(
+        maxDistDiff,
+        Math.abs(a[i].distance - b[i].distance),
+      );
     }
-    let hits = 0;
-    const Q = 100;
-    for (let q = 0; q < Q; q++) {
-        const center = centers[Math.floor((600 + (q % 200)) / G)];
-        const query = center.map((c) => c + 0.1 * rng.gauss());
-        // Query norm computed once, not N times.
-        let qn = 0;
-        for (let d = 0; d < DIM; d++)
-            qn += query[d] * query[d];
-        qn = Math.sqrt(qn) || 1;
-        const bd = new Float64Array(10).fill(Infinity);
-        const bi = new Int32Array(10).fill(-1);
-        for (let n = 0; n < liveVecs.length; n++) {
-            const v = liveVecs[n];
-            let dot = 0;
-            for (let d = 0; d < DIM; d++)
-                dot += v[d] * query[d];
-            const s = 1 - dot / (liveNorms[n] * qn);
-            if (s < bd[9]) {
-                let p = 9;
-                while (p > 0 && bd[p - 1] > s) {
-                    bd[p] = bd[p - 1];
-                    bi[p] = bi[p - 1];
-                    p--;
-                }
-                bd[p] = s;
-                bi[p] = liveIds[n];
-            }
+  }
+  const recallCompact = compactHits / totalCmp;
+  assert(
+    recallCompact >= 0.97,
+    `compacted recall vs fresh build must be high (got ${
+      (recallCompact * 100).toFixed(1)
+    }%)`,
+  );
+  assert(
+    maxDistDiff < 0.05,
+    `distance agreement across the two builds (max diff ${maxDistDiff})`,
+  );
+  console.log(
+    `losslessness: ${N} built, ${deleted.size} deleted, compacted to ${survivors.length}; recall vs fresh=${
+      (recallCompact * 100).toFixed(1)
+    }%`,
+  );
+  // ---- compact also handles updates, and recall stays high on separable data ----
+  const G = 10;
+  const groups = 400;
+  const centers = [];
+  for (let g = 0; g < groups; g++) {
+    centers.push(vec());
+  }
+  const db2 = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 16,
+    efConstruction: 100,
+    seed: 7,
+  });
+  const live = new Map();
+  let id = 0;
+  for (let g = 0; g < groups; g++) {
+    for (let j = 0; j < G; j++) {
+      const v = centers[g].map((c) => c + 0.1 * rng.gauss());
+      db2.insert(id, v);
+      live.set(id, v);
+      id++;
+    }
+  }
+  for (let k = 0; k < 400; k++) {
+    db2.delete(k); // drop 40 whole groups
+  }
+  for (let k = 0; k < 400; k++) {
+    live.delete(k);
+  }
+  for (let k = 600; k < 800; k++) {
+    const v = centers[Math.floor(k / G)].map((c) => c + 0.1 * rng.gauss());
+    db2.update(k, v); // re-place within the same group
+    live.set(k, v);
+  }
+  assert(db2.physicalSize > db2.size, "updates+deletes created tombstones");
+  db2.compact();
+  assert(
+    db2.physicalSize === db2.size && db2.size === live.size,
+    "compact reclaimed all tombstones",
+  );
+  // recall@10 over the surviving set after compaction
+  const liveIds = Array.from(live.keys());
+  const liveVecs = Array.from(live.values());
+  // Precompute data norms once (they don't change per query).
+  const liveNorms = new Float64Array(liveVecs.length);
+  for (let n = 0; n < liveVecs.length; n++) {
+    let s = 0;
+    const v = liveVecs[n];
+    for (let d = 0; d < DIM; d++) {
+      s += v[d] * v[d];
+    }
+    liveNorms[n] = Math.sqrt(s) || 1;
+  }
+  let hits = 0;
+  const Q = 100;
+  for (let q = 0; q < Q; q++) {
+    const center = centers[Math.floor((600 + (q % 200)) / G)];
+    const query = center.map((c) => c + 0.1 * rng.gauss());
+    // Query norm computed once, not N times.
+    let qn = 0;
+    for (let d = 0; d < DIM; d++) {
+      qn += query[d] * query[d];
+    }
+    qn = Math.sqrt(qn) || 1;
+    const bd = new Float64Array(10).fill(Infinity);
+    const bi = new Int32Array(10).fill(-1);
+    for (let n = 0; n < liveVecs.length; n++) {
+      const v = liveVecs[n];
+      let dot = 0;
+      for (let d = 0; d < DIM; d++) {
+        dot += v[d] * query[d];
+      }
+      const s = 1 - dot / (liveNorms[n] * qn);
+      if (s < bd[9]) {
+        let p = 9;
+        while (p > 0 && bd[p - 1] > s) {
+          bd[p] = bd[p - 1];
+          bi[p] = bi[p - 1];
+          p--;
         }
-        const truth = new Set(Array.from(bi).filter((x) => x >= 0));
-        for (const r of db2.query(query, 10))
-            if (truth.has(r.id))
-                hits++;
-    }
-    const recall = hits / (Q * 10);
-    assert(recall >= 0.9, `recall after compact stays high (got ${(recall * 100).toFixed(1)}%)`);
-    console.log(`updates+deletes: compacted to ${db2.size} live; recall@10 after compact ${(recall * 100).toFixed(1)}%`);
-    dbFull.close();
-    dbFresh.close();
-    db2.close();
+        bd[p] = s;
+        bi[p] = liveIds[n];
+      }
+    }
+    const truth = new Set(Array.from(bi).filter((x) => x >= 0));
+    for (const r of db2.query(query, 10)) {
+      if (truth.has(r.id)) {
+        hits++;
+      }
+    }
+  }
+  const recall = hits / (Q * 10);
+  assert(
+    recall >= 0.9,
+    `recall after compact stays high (got ${(recall * 100).toFixed(1)}%)`,
+  );
+  console.log(
+    `updates+deletes: compacted to ${db2.size} live; recall@10 after compact ${
+      (recall * 100).toFixed(1)
+    }%`,
+  );
+  dbFull.close();
+  dbFresh.close();
+  db2.close();
 }
 // =============================================================================
 // 3) Memory + recall + sub-linearity benchmark
 // =============================================================================
 function benchmark() {
-    section("3) Memory + recall + sub-linearity benchmark (HNSW over 1-bit codes)");
-    // Tweak these for a faster run or a wider sweep.
-    const DIM = 256; // 256-d -> 32-byte codes (the headline example)
-    const checkpoints = [1000, 2000, 4000, 8000, 16000, 32000];
-    const GROUP = 10; // well-separated groups of near-duplicates
-    const K = 10; // recall@K against the exact K nearest
-    const SPREAD = 0.1;
-    const Q = 200;
-    const EF = 150;
-    const rng = new RNG(12345);
-    const MAX_N = checkpoints[checkpoints.length - 1];
-    const numGroups = Math.ceil(MAX_N / GROUP);
-    console.log(`dim=${DIM}, ${GROUP}-point groups, queries=${Q}, k=${K}, efSearch=${EF}`);
-    console.log("generating data ...");
-    const centers = new Float32Array(numGroups * DIM);
-    for (let g = 0; g < numGroups; g++) {
-        for (let d = 0; d < DIM; d++)
-            centers[g * DIM + d] = rng.gauss();
-    }
-    const data = new Float32Array(MAX_N * DIM);
-    for (let i = 0; i < MAX_N; i++) {
-        const base = Math.floor(i / GROUP) * DIM;
-        const off = i * DIM;
-        for (let d = 0; d < DIM; d++) {
-            data[off + d] = centers[base + d] + SPREAD * rng.gauss();
+  section(
+    "3) Memory + recall + sub-linearity benchmark (HNSW over 1-bit codes)",
+  );
+  // Tweak these for a faster run or a wider sweep.
+  const DIM = 256; // 256-d -> 32-byte codes (the headline example)
+  const checkpoints = [1000, 2000, 4000, 8000, 16000, 32000];
+  const GROUP = 10; // well-separated groups of near-duplicates
+  const K = 10; // recall@K against the exact K nearest
+  const SPREAD = 0.1;
+  const Q = 200;
+  const EF = 150;
+  const rng = new RNG(12345);
+  const MAX_N = checkpoints[checkpoints.length - 1];
+  const numGroups = Math.ceil(MAX_N / GROUP);
+  console.log(
+    `dim=${DIM}, ${GROUP}-point groups, queries=${Q}, k=${K}, efSearch=${EF}`,
+  );
+  console.log("generating data ...");
+  const centers = new Float32Array(numGroups * DIM);
+  for (let g = 0; g < numGroups; g++) {
+    for (let d = 0; d < DIM; d++) {
+      centers[g * DIM + d] = rng.gauss();
+    }
+  }
+  const data = new Float32Array(MAX_N * DIM);
+  for (let i = 0; i < MAX_N; i++) {
+    const base = Math.floor(i / GROUP) * DIM;
+    const off = i * DIM;
+    for (let d = 0; d < DIM; d++) {
+      data[off + d] = centers[base + d] + SPREAD * rng.gauss();
+    }
+  }
+  // queries land in groups that exist at every checkpoint
+  const firstGroups = checkpoints[0] / GROUP;
+  const queries = new Float32Array(Q * DIM);
+  for (let q = 0; q < Q; q++) {
+    const base = rng.int(firstGroups) * DIM;
+    const off = q * DIM;
+    for (let d = 0; d < DIM; d++) {
+      queries[off + d] = centers[base + d] + SPREAD * rng.gauss();
+    }
+  }
+  const db = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 16,
+    efConstruction: 100,
+    efSearch: EF,
+    seed: 999,
+  });
+  // Precompute data vector norms once — O(N·D) instead of O(Q·N·D).
+  const dataNorms = new Float64Array(MAX_N);
+  for (let i = 0; i < MAX_N; i++) {
+    let s = 0;
+    const off = i * DIM;
+    for (let d = 0; d < DIM; d++) {
+      s += data[off + d] * data[off + d];
+    }
+    dataNorms[i] = Math.sqrt(s) || 1;
+  }
+  function bruteForceTopK(n, qOff) {
+    const bd = new Float64Array(K).fill(Infinity);
+    const bi = new Int32Array(K).fill(-1);
+    let qn = 0;
+    for (let d = 0; d < DIM; d++) {
+      qn += queries[qOff + d] * queries[qOff + d];
+    }
+    qn = Math.sqrt(qn) || 1;
+    for (let i = 0; i < n; i++) {
+      const off = i * DIM;
+      let dot = 0;
+      for (let d = 0; d < DIM; d++) {
+        dot += data[off + d] * queries[qOff + d];
+      }
+      const s = 1 - dot / (dataNorms[i] * qn);
+      if (s < bd[K - 1]) {
+        let p = K - 1;
+        while (p > 0 && bd[p - 1] > s) {
+          bd[p] = bd[p - 1];
+          bi[p] = bi[p - 1];
+          p--;
         }
+        bd[p] = s;
+        bi[p] = i;
+      }
     }
-    // queries land in groups that exist at every checkpoint
-    const firstGroups = checkpoints[0] / GROUP;
-    const queries = new Float32Array(Q * DIM);
-    for (let q = 0; q < Q; q++) {
-        const base = rng.int(firstGroups) * DIM;
-        const off = q * DIM;
-        for (let d = 0; d < DIM; d++) {
-            queries[off + d] = centers[base + d] + SPREAD * rng.gauss();
+    // Direct set from typed array filtered values.
+    const truth = new Set();
+    for (let i = 0; i < K; i++) {
+      if (bi[i] >= 0) {
+        truth.add(bi[i]);
+      }
+    }
+    return truth;
+  }
+  const rows = [];
+  let inserted = 0;
+  for (const cp of checkpoints) {
+    const tb = now();
+    for (; inserted < cp; inserted++) {
+      db.insert(inserted, data.subarray(inserted * DIM, inserted * DIM + DIM));
+    }
+    console.log(`  built N=${cp} (+${(now() - tb).toFixed(0)}ms)`);
+    for (let w = 0; w < 25; w++) {
+      const o = (w % Q) * DIM;
+      db.query(queries.subarray(o, o + DIM), K);
+    }
+    const hnswResults = new Array(Q);
+    let comps = 0;
+    const th = now();
+    for (let qi = 0; qi < Q; qi++) {
+      const o = qi * DIM;
+      hnswResults[qi] = db.query(queries.subarray(o, o + DIM), K).map((x) =>
+        x.id
+      );
+      comps += db.lastQueryDistanceComputations;
+    }
+    const hnswMs = now() - th;
+    const truths = new Array(Q);
+    const tbf = now();
+    for (let qi = 0; qi < Q; qi++) {
+      truths[qi] = bruteForceTopK(cp, qi * DIM);
+    }
+    const bruteMs = now() - tbf;
+    let hits = 0;
+    for (let qi = 0; qi < Q; qi++) {
+      for (const id of hnswResults[qi]) {
+        if (truths[qi].has(id)) {
+          hits++;
         }
+      }
     }
-    const db = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 16,
-        efConstruction: 100,
-        efSearch: EF,
-        seed: 999,
+    rows.push({
+      n: cp,
+      hnswUs: (hnswMs / Q) * 1000,
+      comps: comps / Q,
+      bruteUs: (bruteMs / Q) * 1000,
+      recall: hits / (Q * K),
+      speedup: bruteMs / hnswMs,
     });
-    // Precompute data vector norms once — O(N·D) instead of O(Q·N·D).
-    const dataNorms = new Float64Array(MAX_N);
-    for (let i = 0; i < MAX_N; i++) {
-        let s = 0;
-        const off = i * DIM;
-        for (let d = 0; d < DIM; d++)
-            s += data[off + d] * data[off + d];
-        dataNorms[i] = Math.sqrt(s) || 1;
-    }
-    function bruteForceTopK(n, qOff) {
-        const bd = new Float64Array(K).fill(Infinity);
-        const bi = new Int32Array(K).fill(-1);
-        let qn = 0;
-        for (let d = 0; d < DIM; d++)
-            qn += queries[qOff + d] * queries[qOff + d];
-        qn = Math.sqrt(qn) || 1;
-        for (let i = 0; i < n; i++) {
-            const off = i * DIM;
-            let dot = 0;
-            for (let d = 0; d < DIM; d++)
-                dot += data[off + d] * queries[qOff + d];
-            const s = 1 - dot / (dataNorms[i] * qn);
-            if (s < bd[K - 1]) {
-                let p = K - 1;
-                while (p > 0 && bd[p - 1] > s) {
-                    bd[p] = bd[p - 1];
-                    bi[p] = bi[p - 1];
-                    p--;
-                }
-                bd[p] = s;
-                bi[p] = i;
-            }
-        }
-        // Direct set from typed array filtered values.
-        const truth = new Set();
-        for (let i = 0; i < K; i++) {
-            if (bi[i] >= 0)
-                truth.add(bi[i]);
-        }
-        return truth;
-    }
-    const rows = [];
-    let inserted = 0;
-    for (const cp of checkpoints) {
-        const tb = now();
-        for (; inserted < cp; inserted++) {
-            db.insert(inserted, data.subarray(inserted * DIM, inserted * DIM + DIM));
-        }
-        console.log(`  built N=${cp} (+${(now() - tb).toFixed(0)}ms)`);
-        for (let w = 0; w < 25; w++) {
-            const o = (w % Q) * DIM;
-            db.query(queries.subarray(o, o + DIM), K);
-        }
-        const hnswResults = new Array(Q);
-        let comps = 0;
-        const th = now();
-        for (let qi = 0; qi < Q; qi++) {
-            const o = qi * DIM;
-            hnswResults[qi] = db.query(queries.subarray(o, o + DIM), K).map((x) => x.id);
-            comps += db.lastQueryDistanceComputations;
-        }
-        const hnswMs = now() - th;
-        const truths = new Array(Q);
-        const tbf = now();
-        for (let qi = 0; qi < Q; qi++)
-            truths[qi] = bruteForceTopK(cp, qi * DIM);
-        const bruteMs = now() - tbf;
-        let hits = 0;
-        for (let qi = 0; qi < Q; qi++) {
-            for (const id of hnswResults[qi])
-                if (truths[qi].has(id))
-                    hits++;
-        }
-        rows.push({
-            n: cp,
-            hnswUs: (hnswMs / Q) * 1000,
-            comps: comps / Q,
-            bruteUs: (bruteMs / Q) * 1000,
-            recall: hits / (Q * K),
-            speedup: bruteMs / hnswMs,
-        });
-    }
-    // ---- memory report ----
-    const st = db.storage;
-    const mb = (bytes) => (bytes / (1024 * 1024)).toFixed(2) + " MB";
-    console.log("");
-    console.log("Per-vector storage (vector payload only, excludes the HNSW graph):");
-    console.log(`  Float32 baseline     : ${st.float32BytesPerVector} B`);
-    console.log(`  1-bit RaBitQ code    : ${st.codeBytesPerVector} B   (${(st.float32BytesPerVector / st.codeBytesPerVector).toFixed(1)}x smaller)`);
-    console.log(`  code (kept)         : ${st.bytesPerVector} B   (${st.compressionRatio.toFixed(1)}x smaller overall)`);
-    console.log(`  payload at N=${MAX_N}     : Float32 ${mb(st.float32BytesPerVector * MAX_N)}  vs  index ${mb(st.bytesPerVector * MAX_N)}`);
-    // ---- results table ----
-    console.log("");
-    console.log("     N | HNSW q (us) | dist comps | Brute q (us) | recall@10 | speedup");
-    console.log("-------+-------------+------------+--------------+-----------+--------");
-    for (const r of rows) {
-        console.log(`${String(r.n).padStart(6)} | ${r.hnswUs.toFixed(1).padStart(11)} | ${r.comps.toFixed(0).padStart(10)} | ${r.bruteUs
-            .toFixed(1)
-            .padStart(12)} | ${(r.recall * 100).toFixed(1).padStart(8)}% | ${r.speedup.toFixed(1).padStart(6)}x`);
-    }
-    const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
-    const exponent = (xs, ys) => {
-        const lx = xs.map(Math.log);
-        const ly = ys.map((y) => Math.log(Math.max(y, 1e-12)));
-        const mx = mean(lx);
-        const my = mean(ly);
-        let num = 0;
-        let den = 0;
-        for (let i = 0; i < lx.length; i++) {
-            num += (lx[i] - mx) * (ly[i] - my);
-            den += (lx[i] - mx) * (lx[i] - mx);
-        }
-        return num / den;
-    };
-    const ns = rows.map((r) => r.n);
-    const expComps = exponent(ns, rows.map((r) => r.comps));
-    const expBrute = exponent(ns, rows.map((r) => r.bruteUs));
-    const avgRecall = mean(rows.map((r) => r.recall));
-    const range = ns[ns.length - 1] / ns[0];
-    console.log("");
-    console.log(`Empirical scaling over a ${range}x increase in N  (work ~ N^exponent):`);
-    console.log(`  HNSW distance computations : N^${expComps.toFixed(3)}   <- sub-linear (target < 1)`);
-    console.log(`  Brute-force query          : N^${expBrute.toFixed(3)}   (linear reference ~ 1.0)`);
-    console.log(`  Mean recall@${K}            : ${(avgRecall * 100).toFixed(2)}%`);
-    const last = rows[rows.length - 1];
-    assert(st.codeBytesPerVector === Math.ceil(DIM / 32) * 4, "code size is ceil(dim/32) 32-bit words");
-    assert(st.compressionRatio > 10, `index must be far smaller than Float32 (got ${st.compressionRatio.toFixed(1)}x)`);
-    assert(expComps < 0.8, `HNSW distance-computation growth must be sub-linear (got N^${expComps.toFixed(3)})`);
-    assert(avgRecall >= 0.9, `mean recall must be >= 90% (got ${(avgRecall * 100).toFixed(1)}%)`);
-    assert(last.hnswUs < last.bruteUs, "HNSW must be faster than brute force at the largest N");
-    assert(last.speedup > 1, `HNSW must be faster than brute force at the largest N (got ${last.speedup.toFixed(1)}x)`);
-    console.log("\nMemory, sub-linearity, recall and speed-up checks OK");
-    db.close();
+  }
+  // ---- memory report ----
+  const st = db.storage;
+  const mb = (bytes) => (bytes / (1024 * 1024)).toFixed(2) + " MB";
+  console.log("");
+  console.log(
+    "Per-vector storage (vector payload only, excludes the HNSW graph):",
+  );
+  console.log(`  Float32 baseline     : ${st.float32BytesPerVector} B`);
+  console.log(
+    `  1-bit RaBitQ code    : ${st.codeBytesPerVector} B   (${
+      (st.float32BytesPerVector / st.codeBytesPerVector).toFixed(1)
+    }x smaller)`,
+  );
+  console.log(
+    `  code (kept)         : ${st.bytesPerVector} B   (${
+      st.compressionRatio.toFixed(1)
+    }x smaller overall)`,
+  );
+  console.log(
+    `  payload at N=${MAX_N}     : Float32 ${
+      mb(st.float32BytesPerVector * MAX_N)
+    }  vs  index ${mb(st.bytesPerVector * MAX_N)}`,
+  );
+  // ---- results table ----
+  console.log("");
+  console.log(
+    "     N | HNSW q (us) | dist comps | Brute q (us) | recall@10 | speedup",
+  );
+  console.log(
+    "-------+-------------+------------+--------------+-----------+--------",
+  );
+  for (const r of rows) {
+    console.log(
+      `${String(r.n).padStart(6)} | ${r.hnswUs.toFixed(1).padStart(11)} | ${
+        r.comps.toFixed(0).padStart(10)
+      } | ${
+        r.bruteUs
+          .toFixed(1)
+          .padStart(12)
+      } | ${(r.recall * 100).toFixed(1).padStart(8)}% | ${
+        r.speedup.toFixed(1).padStart(6)
+      }x`,
+    );
+  }
+  const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+  const exponent = (xs, ys) => {
+    const lx = xs.map(Math.log);
+    const ly = ys.map((y) => Math.log(Math.max(y, 1e-12)));
+    const mx = mean(lx);
+    const my = mean(ly);
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < lx.length; i++) {
+      num += (lx[i] - mx) * (ly[i] - my);
+      den += (lx[i] - mx) * (lx[i] - mx);
+    }
+    return num / den;
+  };
+  const ns = rows.map((r) => r.n);
+  const expComps = exponent(ns, rows.map((r) => r.comps));
+  const expBrute = exponent(ns, rows.map((r) => r.bruteUs));
+  const avgRecall = mean(rows.map((r) => r.recall));
+  const range = ns[ns.length - 1] / ns[0];
+  console.log("");
+  console.log(
+    `Empirical scaling over a ${range}x increase in N  (work ~ N^exponent):`,
+  );
+  console.log(
+    `  HNSW distance computations : N^${
+      expComps.toFixed(3)
+    }   <- sub-linear (target < 1)`,
+  );
+  console.log(
+    `  Brute-force query          : N^${
+      expBrute.toFixed(3)
+    }   (linear reference ~ 1.0)`,
+  );
+  console.log(
+    `  Mean recall@${K}            : ${(avgRecall * 100).toFixed(2)}%`,
+  );
+  const last = rows[rows.length - 1];
+  assert(
+    st.codeBytesPerVector === Math.ceil(DIM / 32) * 4,
+    "code size is ceil(dim/32) 32-bit words",
+  );
+  assert(
+    st.compressionRatio > 10,
+    `index must be far smaller than Float32 (got ${
+      st.compressionRatio.toFixed(1)
+    }x)`,
+  );
+  assert(
+    expComps < 0.8,
+    `HNSW distance-computation growth must be sub-linear (got N^${
+      expComps.toFixed(3)
+    })`,
+  );
+  assert(
+    avgRecall >= 0.9,
+    `mean recall must be >= 90% (got ${(avgRecall * 100).toFixed(1)}%)`,
+  );
+  assert(
+    last.hnswUs < last.bruteUs,
+    "HNSW must be faster than brute force at the largest N",
+  );
+  assert(
+    last.speedup > 1,
+    `HNSW must be faster than brute force at the largest N (got ${
+      last.speedup.toFixed(1)
+    }x)`,
+  );
+  console.log("\nMemory, sub-linearity, recall and speed-up checks OK");
+  db.close();
 }
 // =============================================================================
 // 4) Scalability is INTRINSIC, not cache-borne
@@ -847,102 +1077,121 @@ function benchmark() {
 // flat band; the log–log growth exponent makes "does not grow with N" precise.
 // =============================================================================
 function testScalabilityWithoutCache() {
-    section("4) Scalability is intrinsic, not cache-borne (cacheSizeMb = 0)");
-    // A small dimension and modest graph degree keep the build cheap — this test
-    // is about the SHAPE of storage-reads vs N, not throughput, so the constants
-    // only need to be large enough for HNSW's structure to hold.
-    const DIM = 64;
-    const db = new VectorDatabase({
-        dbPath: ":memory:",
-        dim: DIM,
-        M: 8,
-        efConstruction: 40,
-        efSearch: 40,
-        seed: 4242,
-        cacheSizeMb: 0, // ALL caches off (page cache + code LRU) — honest reads
-    });
-    const rng = new RNG(20260628);
-    const vec = () => {
-        const v = new Array(DIM);
-        for (let d = 0; d < DIM; d++)
-            v[d] = rng.gauss();
-        return unit(v);
-    };
-    // A fixed set of probes, reused at every checkpoint so the only variable is N.
-    const Q = 40;
-    const probes = [];
-    for (let q = 0; q < Q; q++)
-        probes.push(vec());
-    const checkpoints = [1000, 2000, 4000, 8000]; // 8x range
-    const readsPerQuery = [];
-    let id = 0;
-    for (const cp of checkpoints) {
-        const tb = now();
-        for (; id < cp; id++)
-            db.insert(id, vec());
-        // Mean storage reads over the fixed probe set — the cache-independent cost
-        // of ONE query at this N.
-        let reads = 0;
-        for (const p of probes) {
-            db.query(p, 10);
-            reads += db.lastQueryStorageReads;
-        }
-        readsPerQuery.push(reads / Q);
-        console.log(`  N=${String(cp).padStart(6)}  +${(now() - tb).toFixed(0)}ms  ` +
-            `storage-reads/query ${(reads / Q).toFixed(1)}`);
-    }
-    // Compare the per-query read count at the LARGEST store against the smallest:
-    // if scaling leaned on the cache, the cache-disabled reads would rise with N
-    // (a deeper graph re-read from disk). The contract is that it stays within a
-    // small constant band — work set by the query, not by the corpus. Log–log
-    // growth exponent makes it precise.
-    const lx = checkpoints.map(Math.log);
-    const ly = readsPerQuery.map((y) => Math.log(Math.max(y, 1e-9)));
-    const mx = lx.reduce((a, c) => a + c, 0) / lx.length;
-    const my = ly.reduce((a, c) => a + c, 0) / ly.length;
-    let num = 0, den = 0;
-    for (let i = 0; i < lx.length; i++) {
-        num += (lx[i] - mx) * (ly[i] - my);
-        den += (lx[i] - mx) * (lx[i] - mx);
-    }
-    const exponent = num / den;
-    const first = readsPerQuery[0];
-    const last = readsPerQuery[readsPerQuery.length - 1];
-    console.log(`  reads/query ${first.toFixed(1)} → ${last.toFixed(1)} over ${checkpoints[checkpoints.length - 1] / checkpoints[0]}x N · growth N^${exponent.toFixed(3)}`);
-    // PRIMARY guard — sub-linear in N: an O(1)-per-touch, log-N-touched query has
-    // storage-reads growing like log N (exponent ≈ 0); an implementation forced to
-    // re-read its working set from disk as N grows pushes this toward and past 1.
-    // Well under 0.5 proves the index does not lean on the cache to scale.
-    assert(exponent < 0.5, `cache-disabled storage-reads/query grew as N^${exponent.toFixed(3)} — the index must scale WITHOUT the page cache (reads set by the query's work, not the corpus size)`);
-    // SECONDARY — a flat band: the largest store costs no more than ~2.5x the
-    // smallest per query. Generous against HNSW's genuine log-N growth, strict
-    // enough to fail a regression whose reads track the corpus.
-    assert(last < first * 2.5 + 8, `cache-disabled reads/query climbed ${first.toFixed(1)} → ${last.toFixed(1)} as the store grew — expected a flat band (work set by the query, not the corpus)`);
-    db.close();
-    console.log("\nCache-independent scalability OK");
+  section("4) Scalability is intrinsic, not cache-borne (cacheSizeMb = 0)");
+  // A small dimension and modest graph degree keep the build cheap — this test
+  // is about the SHAPE of storage-reads vs N, not throughput, so the constants
+  // only need to be large enough for HNSW's structure to hold.
+  const DIM = 64;
+  const db = new VectorDatabase({
+    dbPath: ":memory:",
+    dim: DIM,
+    M: 8,
+    efConstruction: 40,
+    efSearch: 40,
+    seed: 4242,
+    cacheSizeMb: 0, // ALL caches off (page cache + code LRU) — honest reads
+  });
+  const rng = new RNG(20260628);
+  const vec = () => {
+    const v = new Array(DIM);
+    for (let d = 0; d < DIM; d++) {
+      v[d] = rng.gauss();
+    }
+    return unit(v);
+  };
+  // A fixed set of probes, reused at every checkpoint so the only variable is N.
+  const Q = 40;
+  const probes = [];
+  for (let q = 0; q < Q; q++) {
+    probes.push(vec());
+  }
+  const checkpoints = [1000, 2000, 4000, 8000]; // 8x range
+  const readsPerQuery = [];
+  let id = 0;
+  for (const cp of checkpoints) {
+    const tb = now();
+    for (; id < cp; id++) {
+      db.insert(id, vec());
+    }
+    // Mean storage reads over the fixed probe set — the cache-independent cost
+    // of ONE query at this N.
+    let reads = 0;
+    for (const p of probes) {
+      db.query(p, 10);
+      reads += db.lastQueryStorageReads;
+    }
+    readsPerQuery.push(reads / Q);
+    console.log(
+      `  N=${String(cp).padStart(6)}  +${(now() - tb).toFixed(0)}ms  ` +
+        `storage-reads/query ${(reads / Q).toFixed(1)}`,
+    );
+  }
+  // Compare the per-query read count at the LARGEST store against the smallest:
+  // if scaling leaned on the cache, the cache-disabled reads would rise with N
+  // (a deeper graph re-read from disk). The contract is that it stays within a
+  // small constant band — work set by the query, not by the corpus. Log–log
+  // growth exponent makes it precise.
+  const lx = checkpoints.map(Math.log);
+  const ly = readsPerQuery.map((y) => Math.log(Math.max(y, 1e-9)));
+  const mx = lx.reduce((a, c) => a + c, 0) / lx.length;
+  const my = ly.reduce((a, c) => a + c, 0) / ly.length;
+  let num = 0, den = 0;
+  for (let i = 0; i < lx.length; i++) {
+    num += (lx[i] - mx) * (ly[i] - my);
+    den += (lx[i] - mx) * (lx[i] - mx);
+  }
+  const exponent = num / den;
+  const first = readsPerQuery[0];
+  const last = readsPerQuery[readsPerQuery.length - 1];
+  console.log(
+    `  reads/query ${first.toFixed(1)} → ${last.toFixed(1)} over ${
+      checkpoints[checkpoints.length - 1] / checkpoints[0]
+    }x N · growth N^${exponent.toFixed(3)}`,
+  );
+  // PRIMARY guard — sub-linear in N: an O(1)-per-touch, log-N-touched query has
+  // storage-reads growing like log N (exponent ≈ 0); an implementation forced to
+  // re-read its working set from disk as N grows pushes this toward and past 1.
+  // Well under 0.5 proves the index does not lean on the cache to scale.
+  assert(
+    exponent < 0.5,
+    `cache-disabled storage-reads/query grew as N^${
+      exponent.toFixed(3)
+    } — the index must scale WITHOUT the page cache (reads set by the query's work, not the corpus size)`,
+  );
+  // SECONDARY — a flat band: the largest store costs no more than ~2.5x the
+  // smallest per query. Generous against HNSW's genuine log-N growth, strict
+  // enough to fail a regression whose reads track the corpus.
+  assert(
+    last < first * 2.5 + 8,
+    `cache-disabled reads/query climbed ${first.toFixed(1)} → ${
+      last.toFixed(1)
+    } as the store grew — expected a flat band (work set by the query, not the corpus)`,
+  );
+  db.close();
+  console.log("\nCache-independent scalability OK");
 }
 // ------------------------------------ main -----------------------------------
 function main() {
-    const start = now();
-    testCrudAndPersistence();
-    testCodeIO();
-    testCosine();
-    testNearDuplicateRecall();
-    testCosFactorBias();
-    testPersistence();
-    testCompact();
-    testScalabilityWithoutCache();
-    benchmark();
-    const dt = ((now() - start) / 1000).toFixed(1);
-    console.log("\n" + "=".repeat(72));
-    console.log(`ALL TESTS PASSED  (${passed} assertions, ${dt}s)`);
-    console.log("=".repeat(72));
+  const start = now();
+  testCrudAndPersistence();
+  testCodeIO();
+  testCosine();
+  testNearDuplicateRecall();
+  testCosFactorBias();
+  testPersistence();
+  testCompact();
+  testScalabilityWithoutCache();
+  benchmark();
+  const dt = ((now() - start) / 1000).toFixed(1);
+  console.log("\n" + "=".repeat(72));
+  console.log(`ALL TESTS PASSED  (${passed} assertions, ${dt}s)`);
+  console.log("=".repeat(72));
 }
 try {
-    main();
-}
-catch (err) {
-    console.error("\n" + String(err && err.stack ? err.stack : err));
-    if (typeof process !== "undefined")
-        process.exitCode = 1;
+  main();
+} catch (err) {
+  console.error("\n" + String(err && err.stack ? err.stack : err));
+  if (typeof process !== "undefined") {
+    process.exitCode = 1;
+  }
 }