@hviana/sema 0.1.0

package/src/mind/types.ts

@@ -0,0 +1,281 @@
+// types.ts — all interfaces, types, and free functions for the mind.
+//
+// GraphSearchHost is defined first (minimal imports) so GraphSearch can import
+// it without pulling in the full MindContext.
+
+import type { Vec } from "../vec.js";
+import type { Sema } from "../sema.js";
+import type { BoundedMap, Store } from "../store.js";
+import type { Space } from "../sema.js";
+import type { Alphabet } from "../alphabet.js";
+import type { MindConfig } from "../config.js";
+import type {
+  ComputedResult,
+  DerivationItem,
+  DerivationStep,
+  GraphSearch,
+  Leaf,
+  Seg,
+  Site,
+} from "./graph-search.js";
+import type { Rationale } from "./rationale.js";
+import type { FoldPyramid, Grid } from "../geometry.js";
+import { concatBytes } from "../bytes.js";
+import { dominates } from "../geometry.js";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PUBLIC TYPES (exported from the package)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type Input = string | Uint8Array | Grid | Grid[];
+
+// NOTE: the public `Response` interface lives in mind/mind.ts (it carries the
+// `provenance` read-out).  A second copy briefly lived here and drifted —
+// keep exactly one definition.
+
+// ═══════════════════════════════════════════════════════════════════════════
+// GraphSearchHost — the contract GraphSearch needs (no closures)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** The host capabilities GraphSearch consults during a cover.  MindContext
+ *  extends this so the Mind can pass itself as the host. */
+export interface GraphSearchHost {
+  resolve(bytes: Uint8Array): number | null;
+  recogniseSpan?(bytes: Uint8Array): {
+    sites: ReadonlyArray<Site>;
+    leaves: ReadonlyArray<Leaf>;
+    splits: ReadonlySet<number>;
+  };
+  chooseNext?(node: number): number | undefined;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INTERNAL TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface Recognition {
+  /** Forms that can lead somewhere — they have an edge or a halo. */
+  sites: Site[];
+  /** The query's perceived leaves (the search's covering axioms). */
+  leaves: Leaf[];
+  /** Sub-leaf positions where a form boundary falls between leaf edges. */
+  splits: Set<number>;
+}
+
+/** How the consensus climb weights a region's Document-Frequency reach. */
+export type DFMode = "inverse" | "direct" | "combined";
+
+/** One POINT OF ATTENTION the consensus climb resolved. */
+export interface Attention {
+  /** The learnt context this point resolves to. */
+  anchor: number;
+  /** IDF-weighted consensus vote — the strength that orders points. */
+  vote: number;
+  /** The union of the query byte-spans whose evidence supports this point. */
+  start: number;
+  end: number;
+}
+
+/** Both read-outs of one consensus climb. */
+export interface AttentionRead {
+  roots: Attention[];
+  ranked: Attention[];
+}
+
+/** A positioned region of a byte stream paired with its gist. */
+export interface Segment {
+  start: number;
+  end: number;
+  v: Vec;
+}
+
+/** A region of the query's perceived tree for the consensus climb. */
+export interface Region {
+  v: Vec;
+  start: number;
+  end: number;
+  chunk: boolean;
+  /** Whether the region's bytes resolve to a KNOWN node (content-addressed,
+   *  exact).  Exact regions vote with full weight; approximate ones pay the
+   *  contrastive margin (see voteRegions) — under the linear fold a raw
+   *  resonance score is byte-overlap, evidence only in excess of its best
+   *  rival conclusion. */
+  known: boolean;
+}
+
+/** Per-region vote data from the consensus climb's resonance pass. */
+export interface RegionVote {
+  start: number;
+  end: number;
+  canonicalFailed: boolean;
+  roots: readonly number[];
+  w: number;
+  wFocus: number;
+}
+
+/** The edge-bearing contexts reached by climbing from a node, plus saturation info. */
+export interface AncestorReach {
+  roots: number[];
+  contextsReached: number;
+  saturated: boolean;
+}
+
+/** Saturated-interval information for the noise-drop gate. */
+export interface SaturationInfo {
+  leadingEnd: number;
+  hasLeading: boolean;
+  intervals: Array<{ start: number; end: number }>;
+}
+
+/** The items of poolVotes' deduction system. */
+export type AItem =
+  | { kind: "region"; ri: number }
+  | { kind: "anchor"; id: number }
+  | { kind: "anchorFocus"; id: number };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MindContext — bundles all state the mind's functions need
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface MindContext extends GraphSearchHost {
+  store: Store;
+  space: Space;
+  alphabet: Alphabet;
+  cfg: MindConfig;
+  search: GraphSearch;
+  trace: Rationale | null;
+  climbMemo: WeakMap<Uint8Array, Map<string, AttentionRead>> | null;
+  /** Per-response memo of {@link recognise} keyed by the byte-array OBJECT
+   *  (think, articulate, and the post-grounding pre-consume all recognise the
+   *  same query/answer objects).  Valid because the store is read-only while
+   *  a response is in flight; bypassed when a trace is attached so every
+   *  recognise still emits its rationale step.  Null outside respond(). */
+  recogniseMemo: WeakMap<Uint8Array, Recognition> | null;
+  /** Per-response memo of {@link perceive} keyed by the byte-array OBJECT —
+   *  the GENERAL memo the result-level ones (recogniseMemo, climbMemo,
+   *  _gistCache) each partially compensate for: resolve(), gistOf(), and
+   *  every mechanism's re-perception of the same query/answer object hit it
+   *  (a reason hop used to fold the same answer three times).  Valid because
+   *  the store is read-only while a response is in flight and perception is
+   *  a pure function of bytes; only inference-shaped calls (plain Uint8Array,
+   *  no leafAt/lookup capabilities) are memoised, so the deposit path never
+   *  sees it.  Keyed by CONTENT (latin1 of the bytes), not object identity —
+   *  mechanisms materialise the same span in fresh subarrays constantly
+   *  (measured on a trained store: 46% of one response's perceptions were
+   *  byte-identical repeats an identity key missed).  NOT bypassed under
+   *  trace — perception emits no rationale steps, so there is nothing a memo
+   *  hit could swallow.  Null outside respond(). */
+  perceiveMemo: Map<string, Sema> | null;
+  _edgeGuide: Vec | null;
+  _edgeChoice: Map<number, number>;
+  _prevSeen: Set<number> | null;
+  /** Session cache of node-id → perceived gist, for candidate scoring
+   *  ({@link chooseAmong} in the reverse projection's recall path re-gists up to
+   *  √N contexts per pick — the measured bottleneck there).  `chooseNext` does
+   *  NOT use this cache; forward-edge disambiguation uses prevOf counts
+   *  (distributional evidence) instead of gist comparison, because for short
+   *  answer candidates the gist is dominated by accidental byte-pattern
+   *  correlations.  A node's bytes are immutable and perception is a pure
+   *  function of bytes, so an entry stays valid for the store's lifetime —
+   *  never invalidated.  Bounded LRU (byte-sized); a miss only re-perceives,
+   *  never a correctness risk. */
+  _gistCache: BoundedMap<number, Vec>;
+  /** DEPOSIT-path stable-prefix tree cache: content key (latin1) of a
+   *  deposited input → its plain-fold level PYRAMID, so the NEXT deposit
+   *  whose prefix it is (a conversation's accumulated context) reuses every
+   *  full aligned block and refolds only the right edge of each level —
+   *  O(turn) per deposit instead of O(context), with the tree BIT-IDENTICAL
+   *  to a from-scratch fold (see FoldPyramid).  Purely a performance cache.
+   *  Entry-count bounded (a pyramid is ~KB/byte of content; only the few
+   *  live conversation chains matter). */
+  _depositTrees: BoundedMap<string, FoldPyramid>;
+  /** The byte lengths present in {@link _depositTrees} — the candidate
+   *  prefix lengths probed (longest first).  Drifts on eviction (a stale
+   *  length only costs a miss); cleared with the map when it outgrows the
+   *  probe budget. */
+  _depositLens: Set<number>;
+  /** Mind-lifetime intern memo by NODE IDENTITY: perceived-tree node → its
+   *  content-addressed id.  Valid forever (ids are permanent, Sema nodes
+   *  immutable); WeakMap, so entries live exactly as long as the pyramid
+   *  cache keeps the shared subtrees alive.  Lets internTreeIds skip whole
+   *  shared subtrees and indexSubSpans keep its seenBefore window skip. */
+  _internIds: WeakMap<Sema, number>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FREE FUNCTIONS (pure, no state)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Read a whole node's bytes. */
+export const ALL = 0x7fffffff;
+
+/** Splice every chosen span in order — the whole cover as one byte string. */
+export function spliceAll(segs: Seg[]): Uint8Array | null {
+  if (!segs.some((s) => s.rec)) return null;
+  return concatBytes(segs.map((s) => s.bytes));
+}
+
+/** Lift the answer out of the cover for think: the recognised region, free of
+ *  the asker's surrounding (unrecognised) framing. */
+export function liftAnswer(segs: Seg[], queryLen: number): Uint8Array | null {
+  const recognised: number[] = [];
+  for (let k = 0; k < segs.length; k++) if (segs[k].rec) recognised.push(k);
+  if (recognised.length === 0) return null;
+
+  if (recognised.length === 1) {
+    const s = segs[recognised[0]];
+    if (dominates(s.j - s.i, queryLen)) {
+      return concatBytes(segs.map((x) => x.bytes));
+    }
+    return s.bytes;
+  }
+  const lo = recognised[0];
+  const hi = recognised[recognised.length - 1];
+  return concatBytes(segs.slice(lo, hi + 1).map((x) => x.bytes));
+}
+
+/** The CHANGED NODES of a freshly-perceived `tree` against the node ids a previous
+ *  tracked deposit interned (`prevSeen`). */
+export function changedNodes(
+  tree: Sema,
+  ids: Map<Sema, number>,
+  prevSeen: Set<number>,
+): Sema[] {
+  const newCount = new Map<Sema, number>();
+  const count = (n: Sema): number => {
+    const memo = newCount.get(n);
+    if (memo !== undefined) return memo;
+    const id = ids.get(n);
+    // PRUNE: a node whose id the previous deposit already interned is old,
+    // and content addressing makes that transitive — the same id names the
+    // same content, so every descendant was interned then too.  The whole
+    // subtree counts 0 without walking it; with the pyramid fold sharing a
+    // conversation's prefix subtree, this is what keeps the changed-nodes
+    // read O(new nodes) instead of O(context).  (A node internTreeIds
+    // memo-skipped has an id here exactly when it is such a shared root.)
+    if (id !== undefined && prevSeen.has(id)) {
+      newCount.set(n, 0);
+      return 0;
+    }
+    let c = 1; // reachable only when NOT pruned above ⇒ this node is new
+    if (n.kids) { for (const k of n.kids) c += count(k); }
+    newCount.set(n, c);
+    return c;
+  };
+  const total = count(tree);
+  if (total === 0) return [tree];
+
+  let n = tree;
+  for (;;) {
+    if (n.kids === null) return [n];
+    let holder: Sema | null = null;
+    for (const k of n.kids) {
+      if (newCount.get(k)! === total) {
+        holder = k;
+        break;
+      }
+    }
+    if (holder === null) return [n];
+    n = holder;
+  }
+}

package/src/rabitq-hnsw/README.md

@@ -0,0 +1,303 @@
+# rabitq-hnsw
+
+A small, well-organised TypeScript library for **approximate nearest-neighbour
+search** using **HNSW** (Hierarchical Navigable Small World graphs) over **1-bit
+RaBitQ codes**, with **cosine** distance. The entire index lives in **SQLite** —
+the durable copy of every code and link is on disk, resident memory is bounded
+by one capped memory budget (never the whole collection), and the index survives
+process restarts.
+
+The vectors are stored **only** as 1-bit RaBitQ codes — the original vectors are
+never kept — so the index is both fast _and_ tiny on disk:
+
+```
+a 256-d vector:
+  Float32             : 256 × 4 bytes = 1024 bytes
+  RaBitQ 1-bit (code) : 256 × 1 bit   = 32 bytes      (32× smaller)
+```
+
+The code _is_ the entire per-vector representation — no norms, multipliers, or
+popcounts are stored alongside it. A 1-bit code is therefore a first-class
+value: `get` returns the bare code, and `insert`, `update`, and `query` all
+accept either a raw vector or a code — detected by length, so the same call
+works for a `Uint32Array` or a plain `number[]`.
+
+Highlights:
+
+- Faithful HNSW: probabilistic level assignment, greedy layer descent, the
+  `SEARCH-LAYER` routine and the neighbour-selection **heuristic** (Algorithm
+  4), bidirectional edges with pruning, dynamic entry point.
+- **Quantize-first build**: a vector is encoded to its 1-bit code immediately,
+  and the graph is built entirely from codes (`XOR` + `popcount`). Queries still
+  use the accurate full-precision estimator. There is **no exact re-ranking step
+  and no original-vector storage**.
+- `compact()` reclaims deleted/updated space with a **graph-preserving splice**:
+  live nodes keep their internal ids and wiring, and each dead neighbour is
+  replaced by its own live neighbours (a 1-hop bridge). Codes are copied
+  verbatim — nothing is re-quantised — so compaction never loses precision, and
+  it runs as one streaming pass instead of a full O(N·ef·log N) rebuild.
+- At query time each distance is a handful of byte lookups in a small per-query
+  table (no popcounts).
+- **Truly sub-linear** query work (≈ `O(log N)`), demonstrated by the
+  test/benchmark.
+- Vector **CRUD** keyed by integer external ids. `get` returns the stored 1-bit
+  code, which can be fed straight back into `insert`, `update`, or `query`.
+- **Bounded RAM footprint**: codes and adjacency lists live in SQLite tables and
+  are read/written on demand. The only resident state is one BOUNDED budget,
+  `cacheSizeMb`, shared by SQLite's page cache and a derived immutable-code LRU
+  — both capped, so the index can grow to millions of vectors without resident
+  memory growing with it.
+- **Scalability is cache-independent**: the caches are pure speed layers.
+  Correctness and the per-operation _storage-read_ count are identical with the
+  budget off (`cacheSizeMb: 0`). `lastQueryStorageReads` exposes that honest,
+  cache-independent cost — it is set by the work a query does (the nodes it
+  visits, ~log N), never by the collection size — so a poor access pattern can
+  never hide behind a warm cache.
+- Reopening the same `dbPath` restores the exact configuration (the rotation is
+  regenerated from the persisted seed), so codes already on disk remain valid
+  across process restarts.
+- **`node:sqlite`** is the only runtime dependency — no native add-ons.
+
+## Install / run
+
+```bash
+npm install          # installs dev tooling (typescript, tsx, @types/node)
+npm test             # the single test file: CRUD, memory, recall + sub-linearity benchmark
+npm run example      # runs examples/quickstart.ts
+npm run typecheck    # tsc --noEmit
+```
+
+No build step is required to use or test the library — `tsx` runs the TypeScript
+directly. Requires Node.js ≥ 22.5 (for `node:sqlite`).
+
+## Usage
+
+```ts
+import { VectorDatabase } from "./src/index";
+
+// dbPath is required — use ":memory:" for a transient index
+const db = new VectorDatabase({
+  dbPath: ":memory:",
+  dim: 256,
+  M: 16,
+  efConstruction: 200,
+});
+
+// CREATE — associate a vector with an integer id (encoded to 1-bit code immediately)
+db.insert(42, embedding); // embedding: number[] | Float32Array of length dim
+
+// BULK CREATE/UPDATE — one transaction around the whole batch (far fewer fsyncs
+// on disk; the graph and its result are identical to the per-item path).
+db.upsertMany([{ id: 1, vector: v1 }, { id: 2, vector: v2 }]);
+
+// READ — returns the stored 1-bit code (NOT the original vector)
+const code = db.get(42); // -> Uint32Array (codeWords words) | null
+
+// A code is the whole representation: insert / update / query all accept one too,
+// detected by length (codeWords vs dim) — works for Uint32Array or a number[].
+db.insert(999, code!); // store an existing code under a new id
+db.query(code!, 10); // search by code (sign-bit / cosine distance)
+db.update(7, db.get(9)!); // move id-7 onto id-9's code
+
+// UPDATE / DELETE with raw vectors
+db.update(42, newEmbedding);
+db.delete(42); // -> boolean
+
+// COMPACT — reclaim space from deleted/updated vectors (lossless rebuild)
+db.physicalSize; // physical nodes incl. tombstones
+if (db.physicalSize > db.size * 1.5) db.compact();
+
+// SEARCH — k nearest neighbours (ids + estimated cosine distances)
+const hits = db.query(queryVector, 10); // -> [{ id, distance }, ...]
+db.query(queryVector, 10, { ef: 200 }); // override efSearch per query
+
+// MEMORY — per-vector storage footprint vs a Float32 baseline
+db.storage; // { float32BytesPerVector, codeBytesPerVector, bytesPerVector, compressionRatio }
+
+// PERSIST — just reference the same path again; the SQLite file IS the database
+db.close();
+const db2 = new VectorDatabase({ dbPath: "vectors.db" }); // reopens, exact same state
+
+// Transient in-memory index
+const mem = new VectorDatabase({ dbPath: ":memory:", dim: 256 });
+// ... use, then close — data is discarded
+mem.close();
+```
+
+Distance is **cosine**. Options: `efSearch`, `queryBits` (query
+scalar-quantisation bits, default 4), `rotationRounds` (default 3), `seed`, an
+optional `centroid` the vectors are centered by before quantisation, and the one
+bounded memory knob `cacheSizeMb` (default 64) — it sizes SQLite's page cache
+and the derived immutable-code LRU together. A pure speed enhancement: pass 0 to
+disable all caching, which changes neither results nor the per-operation
+storage-read count.
+
+## How it works
+
+**RaBitQ (1-bit).** Each vector is centered by an optional centroid, normalised,
+rotated by a fast random orthogonal transform (random sign flips +
+Walsh–Hadamard, `O(D log D)`), and reduced to one sign bit per padded dimension.
+The packed sign bits are the **only** thing kept per vector. The random rotation
+makes the quantisation error essentially uniform across vectors, so the cosine
+estimate needs only a single fixed scale rather than any per-vector correction.
+
+**Two estimators, both on codes.**
+
+- _query → code_ (accurate): RaBitQ's inner-product estimator between a
+  **full-precision** vector and a stored 1-bit code. The query is
+  scalar-quantised to `queryBits` bits, and the only data-dependent quantity in
+  the estimate is the dot product of the code's sign bits with the quantised
+  query — which is exactly **the sum of the quantised query values at the
+  coordinates where the code bit is 1**. So at query time we build one small
+  per-query **byte lookup table** (`paddedDim/8 × 256`, ≈8 KB, L1-resident) and
+  each distance is just `paddedDim/8` table lookups over the code's bytes — e.g.
+  32 lookups for a 256-d vector, no popcounts at all.
+- _code → code_ (coarse): the distance between two stored codes from their
+  Hamming distance, `cos ≈ 1 − 2·hamming/D` (`XOR` + `popcount`). Both sides are
+  1-bit. **The entire build runs on this estimator** — finding a new node's
+  neighbours and pruning lists — so insertion needs nothing but the code (one
+  rotation at encode time, then cheap popcounts), and a rebuild from codes is a
+  faithful HNSW construction.
+
+**HNSW.** A multi-layer navigable graph. Levels are drawn from
+`⌊-ln(U)·(1/ln M)⌋`; the search descends greedily through the upper layers and
+runs an `ef`-bounded best-first search at layer 0. New nodes connect to `M`
+neighbours chosen by the diversity heuristic, with neighbour lists pruned back
+to `2M` at layer 0. Insertion searches the graph with the new node's **code**;
+queries search it with the **full-precision** estimator. There is no exact
+re-ranking — the top-k is taken directly from the codes, which keeps query work
+tiny and sub-linear.
+
+**SQLite-native graph.** Codes live in the `nodes` table (one BLOB per row,
+indexed by integer primary key); adjacency lists live in the `links` table
+(`WITHOUT ROWID`, clustered on `(node, layer)`) so a neighbour-list fetch — the
+hot path of search — is a single B-tree descent landing on an inline BLOB.
+Global state (entry point, max level, counts, RNG state) and the quantizer
+configuration (dim, seed, centroid, etc.) are in a single-row `meta` table.
+There is no separate load/save step: the SQLite file **is** the database.
+
+**Performance details.** WAL journal mode with NORMAL synchronous for
+crash-safe, fast writes; a page cache sized by `cacheSizeMb` (with mmap tied to
+it) for zero-copy reads of hot pages; a per-_operation_ working set (the records
+the current insert/query is actively comparing, bounded by `efConstruction` /
+`efSearch`, cleared between operations and never the collection size) so within
+one op each touched node is read once; visited tracking and binary heaps on
+parallel arrays with no per-candidate object allocation in the build/search hot
+paths. The `compact()` operation streams the live rows into fresh tables
+(preserving internal ids, splicing dead neighbours out of the adjacency lists)
+in batched transactions — the WAL stays bounded by the batch, never the table —
+then swaps the tables atomically and `VACUUM`s the freed pages back to the
+filesystem.
+
+**The immutable-code LRU.** A node's 1-bit code never changes once written, yet
+building and searching the graph re-read the same hub nodes across operations —
+and on clustered data consecutive inserts touch overlapping neighbourhoods, so a
+code is fetched again and again. Each fetch is a SQLite point-query that decodes
+the row and copies the BLOB (≈1.4 µs even when the page is already cached — the
+cost is the statement, not disk I/O), while the distance it feeds is ≈0.04 µs.
+So a **bounded LRU of decoded `NodeRec`s** (keyed by internal id) serves a
+repeatedly-touched code from RAM and skips both the query and the copy. Two
+properties keep it honest:
+
+- It is a **latency layer only.** `lastQueryStorageReads` (and the underlying
+  `Store.reads`) counts SQLite fall-throughs — cache MISSES — so the
+  per-operation storage-read count, the cache-independent scalability witness,
+  is identical whether the cache is full or off. The index's _scaling_ never
+  depends on it; only the wall-clock constant does.
+- It has **no separate knob.** Its entry capacity is DERIVED from the one memory
+  budget, `cacheSizeMb`, and the actual per-`NodeRec` byte cost (code + fixed
+  fields + Map overhead), so it shares that budget and resident memory is capped
+  regardless of collection size — it never grows into "the whole index in RAM".
+  On a clustered build even a modest budget captures essentially all the
+  locality, so it buys the speed-up without scaling with N.
+
+Two refinements share the same budget and the same honesty rules (hits are never
+counted as reads; correctness never depends on them):
+
+- **Upper-layer pinning.** Every insert and query descends from the entry point
+  through the upper layers before fanning out on layer 0, so level ≥ 1 nodes (a
+  1/M fraction of the collection) are touched by every operation — yet layer-0
+  fan-out traffic keeps evicting them from a plain LRU. Their codes pin into a
+  section capped at half the budget that layer-0 traffic cannot evict, keeping
+  the descent RAM-resident however far the collection outgrows the budget.
+- **A decoded neighbour-list LRU.** Hub adjacency lists are re-read across
+  consecutive operations just like hub codes; a bounded LRU (a quarter of the
+  budget) serves the decoded list, written through on every `setNeighbors` so a
+  hit always equals a fresh row read, and dropped at compaction.
+
+The cache stays correct because the only mutable fields — the tombstone flag and
+external id — are updated in place on the cached record by `tombstone()`, and
+the whole cache is dropped at compaction (whose table swap invalidates any
+cached row). A miss only repeats work, never changes a result. `cacheSizeMb: 0`
+disables it (along with the page cache), which the tests use to measure the
+honest read count.
+
+Deletes (and the old version after an `update`) are tombstones: still routed
+through for navigation, never returned. `compact()` splices them out of the
+graph (each dead neighbour replaced by its own live neighbours) and drops their
+rows; codes are copied untouched — no original vectors needed, no precision
+lost.
+
+## Accuracy trade-off
+
+1-bit codes are extremely compact but lossy: the index reliably finds the right
+_neighbourhood_, but it cannot perfectly resolve the order of points that are
+all roughly equidistant from the query. So recall is high when the true
+neighbours are **separable** (the regime where ANN is meaningful —
+near-duplicate retrieval, clustered embeddings, etc.) and lower inside a dense,
+ambiguous cluster. The classic way to recover exact ordering is to re-rank the
+top candidates with the original vectors; this build intentionally omits that to
+maximise speed and minimise memory.
+
+## Benchmark (from `npm test`)
+
+`dim = 256`, well-separated groups of 10 near-duplicates, 200 queries, `k = 10`,
+`efSearch = 150`. Representative run (disk-backed, SQLite):
+
+```
+Per-vector storage (vector payload only, excludes the HNSW graph):
+  Float32 baseline     : 1024 B
+  1-bit RaBitQ code    : 32 B   (32.0x smaller)
+  code (kept)          : 32 B   (32.0x smaller overall)
+  payload at N=32000   : Float32 31.25 MB  vs  index 0.98 MB
+
+     N | HNSW q (us) | dist comps | Brute q (us) | recall@10 | speedup
+-------+-------------+------------+--------------+-----------+--------
+  1000 |      1930.3 |        863 |        308.2 |    100.0% |    0.2x
+  2000 |      3142.8 |       1298 |        549.6 |    100.0% |    0.2x
+  4000 |      3763.7 |       1723 |       1073.3 |    100.0% |    0.3x
+  8000 |      4603.3 |       2165 |       2186.0 |    100.0% |    0.5x
+ 16000 |      5315.8 |       2440 |       4398.0 |    100.0% |    0.8x
+ 32000 |      6058.2 |       2668 |       8886.4 |    100.0% |    1.5x
+
+Empirical scaling over a 32x increase in N  (work ~ N^exponent):
+  HNSW distance computations : N^0.320   <- sub-linear (target < 1)
+  Brute-force query          : N^0.831   (linear reference ~ 1.0)
+  Mean recall@10            : 100.00%
+```
+
+The distance-computation count is a deterministic, machine-independent measure
+of work: it grows sub-linearly (≈ `N^0.32`, near-logarithmic) while the
+brute-force baseline grows near-linearly. The per-query latency is higher than a
+purely in-RAM index (the SQLite round-trips add ~constant overhead), but it
+**scales** — at 32,000 vectors the disk-backed HNSW is already 1.5× faster than
+brute force, and the gap widens as N grows (brute is `O(N)` per query; HNSW is
+`O(log N)`). The test asserts the 32× storage compression, the sub-linear
+exponent, perfect recall, and the speed-up over brute force.
+
+## Layout
+
+```
+src/
+  prng.ts       deterministic seedable RNG (mulberry32)
+  heap.ts       binary heap on parallel arrays
+  rabitq.ts     1-bit RaBitQ quantizer + fast rotation + query/code estimators
+  store.ts      SQLite-backed graph storage: codes, adjacency, meta, compaction
+  hnsw.ts       HNSW graph over codes (build, search, delete, compact)
+  database.ts   VectorDatabase: CRUD, external ids, storage stats
+  index.ts      public exports
+test/
+  hnsw.test.ts  the single test file (correctness + memory + benchmark)
+examples/
+  quickstart.ts
+```