md-semantic-search 2.0.0 → 2.2.0

package/README.md

@@ -33,7 +33,7 @@ measurements that shaped its defaults.
 
 - 🔌 **Any folder, anywhere.** Point `--db` at any directory of `.md`/`.markdown`
   files. It does **not** have to live inside this project. Recursive by default.
-- 🌍 **Cross-lingual.** Multilingual embeddings (default `multilingual-e5-base`).
+- 🌍 **Cross-lingual.** Multilingual embeddings (default `granite-multilingual-311m`, Apache-2.0).
 - 🧭 **Markdown-aware context.** Each embedding includes the full active heading
   path (`title > h1 > h2 > ...`), so a deeply nested passage remains searchable
   by its parent topics without an LLM-generated context step.
@@ -109,8 +109,15 @@ measurements that shaped its defaults.
 
 ## Install
 
-Requires **Node.js ≥ 18**. Native dependencies ship as prebuilt binaries — no
-compiler toolchain needed on any platform.
+Requires **Node.js ≥ 20.9**. Supported runtimes:
+
+| Runtime | Status | Support |
+|---|---|---|
+| **Node 22, 24** | Maintained LTS lines | Tested in CI |
+| **Node 20.9–20.x** | EOL since 2026-04-30 | Runs, prints a deprecation warning on stderr; dropped in **v3.0.0** |
+
+Native dependencies ship as prebuilt binaries — no compiler toolchain needed
+on any platform.
 
 Run on demand with `npx` (no install):
 
@@ -508,7 +515,7 @@ against a loopback allowlist (`403` otherwise) so DNS-rebinding pages cannot rea
 and CORS stays fully off unless you pass `--cors-origin`. `/health` exposes the live counters
 (`in_flight`, `queued`, `rejected_total`).
 
-### Web UI (built-in, `--ui`)
+### Web UI (built-in; disable with `--no-ui`)
 
 By default `mdss serve` also serves a **zero-dependency web UI at `/`** — a keyboard-first search page
 with live debounced results, term highlighting, score bars, tag/type/status filters, dark/light theme
@@ -660,7 +667,7 @@ Add to your `claude_desktop_config.json`:
 | `--db <dir>` | Folder of `.md` files (or set `MDSS_DB`). Can be anywhere on disk. |
 | `--index-dir <dir>` | Where to store the index (default: `<db>/.mdss`). |
 | `--cache-dir <dir>` | Model cache dir. Default: `$XDG_CACHE_HOME/mdss` if set, else `~/.cache/mdss` on **all** platforms (so on Windows that's `C:\Users\<you>\.cache\mdss` — *not* `%LOCALAPPDATA%`; override with `MDSS_CACHE_DIR`). |
-| `--model <name\|id>` | Embedding model (default `e5-base`). See `mdss models`. |
+| `--model <name\|id>` | Embedding model (default `granite-multilingual-311m`). See `mdss models`. |
 | `--workers <n>` | Number of parallel batch workers for embedding (default: 1). |
 | `--format <fmt>` | Export format: `jsonl` (default), `csv`, `parquet` (`export`). |
 | `--no-vectors` | Omit embeddings from export (`export`). |
@@ -679,7 +686,7 @@ Add to your `claude_desktop_config.json`:
 | `--multi-query <n>` | Multi-query expansion (issue #203): N query variants (original + N−1 LLM paraphrases) fused by union-RRF; needs `--llm-endpoint`, degrades silently without it. |
 | `--graph-boost <n>` | Weight for Obsidian wikilink graph ranking and PageRank prior (search; default 0). Incorporates document centrality and 2-hop contextual propagation. |
 | `--filter <expr>` | Rich boolean filter across frontmatter tags and properties (e.g. `tag:engineering AND status != archived`). |
-| `--ann [ivf\|hnsw]` | Approximate nearest neighbor search (search; auto-enables for large corpora). Engines (issue #201): `ivf` (k-means, the default sidecar) or `hnsw` (graph — no training phase, 100% measured recall at equal-or-lower query latency, `hnsw.json` sidecar, corrupt → brute-force fallback). Bare `--ann` prefers an existing sidecar. |
+| `--ann [ivf\|hnsw]` | Approximate nearest neighbor search (search; auto-enables for large corpora). Engines (issue #201): `ivf` (k-means, the default sidecar) or `hnsw` (graph — no training phase, 100% measured recall at equal-or-lower query latency, `hnsw.json` sidecar, corrupt → brute-force fallback; watch rebuilds reuse the persisted graph via chunk-hash remapping instead of rebuilding it — issue #223). Bare `--ann` prefers an existing sidecar. |
 | `--nprobe <n>` | Number of nearest centroid clusters to probe during ANN search (default 8). |
 | `--port <n>` | HTTP port for `serve` (default 8747, or `MDSS_PORT`). |
 | `--host <ip>` | Bind address for `serve` (default `127.0.0.1` — loopback only; use `0.0.0.0` to expose on the LAN, or `MDSS_HOST`). |
@@ -786,26 +793,26 @@ mdss models
 | Alias | Model | Dim | Notes |
 |-------|-------|-----|-------|
 | `e5-small` | `Xenova/multilingual-e5-small` | 384 | Fastest (~120 MB). **Weak cross-lingual** — see RESEARCH. |
-| `e5-base` ⭐ | `Xenova/multilingual-e5-base` | 768 | Default. Best balance. |
+| `e5-base` | `Xenova/multilingual-e5-base` | 768 | Default before v2.2.0. Apache-2.0, MIT-style terms. |
 | `e5-large` | `Xenova/multilingual-e5-large` | 1024 | ~2.2 GB, higher quality. |
 | `bge-m3` | `Xenova/bge-m3` | 1024 | ~2.3 GB. Best cross-lingual separation in tests. |
 | `qwen3-embedding-0.6b` | `onnx-community/Qwen3-Embedding-0.6B-ONNX` | 1024 | ~613 MB q8. Opt-in; instruction-prefixed queries and last-token pooling. |
-| `granite-multilingual-311m` | `onnx-community/granite-embedding-311m-multilingual-r2-ONNX` | 768 | ~298 MB q8. IBM Granite r2 — ModernBERT 8k context, CLS pooling, Apache-2.0 (issue #200). |
-| `embeddinggemma-300m` | `onnx-community/embeddinggemma-300m-ONNX` | 768 | ~300 MB q8. Google EmbeddingGemma — pre-pooled output, MRL dims 64–768, Gemma license (issue #200). |
+| `granite-multilingual-311m` ⭐ | `onnx-community/granite-embedding-311m-multilingual-r2-ONNX` | 768 | **Default.** ~298 MB q8. IBM Granite r2 — ModernBERT 8k context, CLS pooling, **Apache-2.0**. Measured nDCG@10 0.8653 on golden v2 (issue #227). |
+| `embeddinggemma-300m` | `onnx-community/embeddinggemma-300m-ONNX` | 768 | ~300 MB q8. Measured leader (nDCG@10 0.8691) but **license-blocked from being the npm default**: Gemma Terms of Use, not MIT/Apache (issue #227). |
 
 Switching models invalidates the stored vectors automatically — the next
 `index` run does a full rebuild.
 
 Weights are downloaded in quantized (q8) form when the model repo ships them
-(e5-base is ~280 MB instead of ~1.1 GB fp32).
-
-The Qwen3 alias is pinned to a tested model revision and automatically applies
-the retrieval instruction required for queries; indexed passages remain
-unprefixed. Its upstream benchmark is promising, but it has not replaced
-`e5-base` as the default because the project corpus has not been benchmarked
-against it yet. This is experimental enablement rather than completion of issue
-#50: release provenance and the versioned RU/EN benchmark remain tracked by
-#55 and #56 (the explicit model adapter contract landed in #60).
+(the default granite is ~298 MB).
+
+Why granite is the default (issue #227): measured on the 186-query golden set
+v2 against the incumbent e5-base — **granite 0.8653 vs e5-base 0.7874 nDCG@10**
+with the same size class and a fully permissive Apache-2.0 license. The strictly
+better `embeddinggemma-300m` (0.8691) is a two-thousandths edge over granite but
+carries Google's Gemma Terms of Use; making it the npm default would impose
+those terms on every user, so it stays the recommended opt-in. Full decision
+record and per-category tables: RESEARCH.md §15.
 
 ### How to add a model
 

package/RESEARCH.md

@@ -175,6 +175,29 @@ mdss index  --db ./your-wiki --model qwen3-embedding-0.6b
 mdss search --db ./your-wiki --semantic "the same paraphrase"
 ```
 
+### Expansion to golden set v2 (issue #226)
+
+The original 48-query dev slice was too thin to overturn a default (§15) and
+carried no long-document slice at all (§12). The v2 expansion re-measured
+everything on a frozen 26-document corpus and **204 queries** (186 dev /
+12 test / 6 holdout; 100 RU / 104 EN), adding two measured slices:
+
+- **`cross-lingual`** (n=27 dev): query language ≠ answering-document language
+  — the headline use case, now a first-class bench line.
+- **`long-doc-section`** (n=21 dev): answers live only in 3rd/4th-level sections
+  of long documents with frontmatter — the §12 heading-path ablation gate.
+- **Hard negatives** grew to 20, built from same-topic and cross-topic confuser
+  pairs (nginx-TLS vs сертификат-ротация, postgres vs redis, api-tokens vs
+  ротация-сертификатов) to keep reranker discrimination under test.
+
+e5-base (default, multilingual-e5-base, dev slice, k=10, real model):
+**nDCG@10 0.7874 · MRR 0.7577 · Hit@10 0.9301 · Recall@10 1.0000** — the
+committed `golden-baseline.json`. The v2 set is intentionally harder than v1
+(0.8856 on n=48): paraphrase/hard-negative/cross-lingual weight grew and the
+new categories reward fine-grained discrimination. The #198 nightly gate now
+runs against this baseline; the baseline is meaningful only for the same
+fixture+corpus hashes (recorded in the file).
+
 ## 9. Recommendations
 
 | If you want… | Use |
@@ -284,34 +307,54 @@ golden set (#56) before any default change.
 
 ### Golden-Set Results (frozen corpus, hash `dev-golden.json`)
 
-| Model (alias) | q8 size | nDCG@10 (dev, n=48) | MRR | Hit@10 | Recall@10 | nDCG (test) | nDCG (holdout) |
-|---|---|---|---|---|---|---|---|
-| `e5-base` (baseline) | ~280 MB | 0.8797 | 0.8628 | 0.979 | 1.000 | 1.0000 | 0.9077 |
-| `granite-multilingual-311m` | ~298 MB | 0.8761 | 0.8559 | 0.979 | 1.000 | 1.0000 | 0.9077 |
-| `embeddinggemma-300m` | ~300 MB | **0.9002** | **0.8837** | **1.000** | 1.000 | 1.0000 | 0.9077 |
-
-- **Non-inferiority (#198 tolerance: drop ≤ 0.01):** granite passes (−0.0036);
-  embeddinggemma **exceeds** the baseline (+0.0205) and is the only candidate
-  that recovers the two dev queries e5-base misses (Hit 1.000).
-- **Discriminating slice is `dev`** — `test` and `holdout` are saturated for
-  both models, so they cannot rank the candidates further.
-
-### Decision
+Original n=48 fixture (historical):
 
-1. **Both candidates ship as opt-in registry entries** with pinned revisions
-   (issue #200 task 1) and are documented in the README Models table.
-2. **The default stays `e5-base`.** EmbeddingGemma's superiority is proven on
-   our golden set, but the default switch is gated on two factors outside this
-   measurement: (a) the **Gemma license** — not MIT/Apache, so making it the
-   npm-distributed default imposes Google's additional terms on every user,
-   which is a project-licensing decision, not an engineering one; (b) one
-   fixture (48 dev queries) is a thin base for overturning a default that the
-   #198 gate has been calibrated on. Re-evaluate if/when the golden set grows.
-   **Until then `embeddinggemma-300m` is the recommended opt-in** (`--model
-   embeddinggemma-300m`) — same size class as e5-base, better measured quality.
-3. **Infrastructure added:** `pooling: 'cls'` (granite) and the
-   `pooledOutput` adapter flag (pre-pooled ONNX graphs bypass the
-   feature-extraction pipeline) — both fingerprint-relevant and unit-tested.
+| Model (alias) | q8 size | nDCG@10 (dev, n=48) | MRR | Hit@10 | Recall@10 |
+|---|---|---|---|---|---|
+| `e5-base` (baseline) | ~280 MB | 0.8797 | 0.8628 | 0.979 | 1.000 |
+| `granite-multilingual-311m` | ~298 MB | 0.8761 | 0.8559 | 0.979 | 1.000 |
+| `embeddinggemma-300m` | ~300 MB | **0.9002** | **0.8837** | **1.000** | 1.000 |
+
+Re-measured on **golden set v2** (issue #226 — 186 dev queries, k=10, real
+models, this closed the "thin fixture" blocker):
+
+| Model (alias) | nDCG@10 | MRR | Hit@10 | Recall@10 | License | Size |
+|---|---|---|---|---|---|---|
+| `e5-base` (incumbent) | 0.7874 | 0.7577 | 0.9301 | 1.000 | MIT | ~280 MB |
+| `qwen3-embedding-0.6b` | 0.8519 | 0.8401 | 0.9462 | 1.000 | Apache-2.0 | ~613 MB |
+| `granite-multilingual-311m` | 0.8653 | 0.8495 | 0.9624 | 1.000 | **Apache-2.0** | ~298 MB |
+| `embeddinggemma-300m` | **0.8691** | **0.8594** | **0.9677** | 1.000 | Gemma ToU | ~300 MB |
+
+Per-category (v2 dev): granite **beats** embeddinggemma on `cross-lingual`
+(0.7766 vs 0.7552) and `paraphrase` (0.8829 vs 0.8751); embeddinggemma leads on
+`long-doc-section` (0.8443 vs 0.8087); hard-negative and identifier are tied.
+The v2 set amplified the gap to the incumbent (harder paraphrase/hard-negative
+weight), so the "thin fixture" concern resolved in favor of a switch.
+
+### Decision (final, issue #227 — revisits the 2026-10 decision above)
+
+1. **The default moves `e5-base` → `granite-multilingual-311m`** (v2.2.0):
+   measured +0.078 nDCG@10 over the incumbent on the expanded set, same size
+   class, **Apache-2.0**, 8k ModernBERT context. The #198 nightly gate baseline
+   was re-taken with granite (0.8653) and verified deterministic.
+2. **`embeddinggemma-300m` remains the recommended opt-in, not the default.**
+   The Gemma Terms of Use are not MIT/Apache-compatible; making it the
+   npm-distributed default would impose Google's additional terms (attribution,
+   Prohibited Use Policy, derivative-model obligations) on every user of an
+   MIT-licensed tool. Precedent: sentence-transformers / fastembed ship
+   permissive defaults and list Gemma models as opt-in. Re-evaluation triggers:
+   (a) an EmbeddingGemma successor under Apache-2.0 with a transformers.js
+   artifact (EmbeddingGemma 2 was announced on that path), or (b) a measured
+   quality gap on our set that grows beyond the license trade-off.
+3. **`qwen3-embedding-0.6b` stays opt-in** — Apache-2.0 but 2× the download of
+   granite at lower measured quality (0.8519).
+4. **Migration:** the adapter fingerprint change invalidates existing indexes —
+   the first `mdss index` after upgrade re-embeds the corpus (identical chunk
+   texts do NOT reuse vectors across models; vectors are model-scoped). Users
+   pinned by bandwidth or reproducibility keep the old behavior with
+   `--model e5-base`. `pooling: 'cls'` (granite) and the `pooledOutput` flag
+   (gemma) were already shipped in #200; both fingerprint-relevant and
+   unit-tested.
 
 ### Reproducing
 
@@ -319,8 +362,12 @@ golden set (#56) before any default change.
 node scripts/run-bench.mjs --model e5-base --slice dev
 node scripts/run-bench.mjs --model granite-multilingual-311m --slice dev
 node scripts/run-bench.mjs --model embeddinggemma-300m --slice dev
+node scripts/run-bench.mjs --model qwen3-embedding-0.6b --slice dev
 ```
 
+(Bare `node scripts/run-bench.mjs --slice dev` now measures the granite
+default and regenerates the committed baseline with `--update-baseline`.)
+
 ---
 
 ## 16. Reranker Registry & Multi-Query Expansion (Issue #203)
@@ -421,12 +468,48 @@ corpora keeps **IVF as the default engine**; the criterion's second branch
 2. Bare `--ann` and the automatic threshold path stay on IVF until either
    (a) the JS graph build gets an order of magnitude cheaper (worker
    parallelism, WASM SIMD — see §13), or (b) incremental watch rebuilds
-   start reusing the persisted graph (the `insertHnsw`/`deleteHnsw` API is
-   already in place for that).
+   start reusing the persisted graph. **(b) is now implemented (issue
+   #223):** a watch rebuild remaps the persisted graph onto the new chunk
+   numbering via `chunkHash` (`remapHnsw` — vector reuse is hash-keyed, so
+   every carried edge distance stays valid), tombstones the gone nodes and
+   inserts only the new ones; the build-side gap now applies to FULL builds
+   only (first run, engine/budget switch, entry-point-unanchorable remap).
 3. `--ef <n>` tunes the HNSW search breadth (default 64; recall saturates
    at 100% already at ef 16 on the bench corpora — the default leaves
    headroom for noisier real-world distributions).
 
+### Full-build acceleration attempt (issue #228 — revisit condition (a) closed as DECLINED)
+
+Profiling the full build (dim 256): **84–85% of wall time is distance
+computation** — 16.5k calls/node at n=5000, 18.9k at n=20000 — all on a
+sequential dependency chain (node *i*'s graph state depends on every prior
+insert). Two accelerators were measured:
+
+1. **worker_threads parallelism — structurally blocked.** A per-hop distance
+   batch is ~13 µs of work; a worker roundtrip (postMessage + await) costs
+   ~0.1–0.3 ms — 10–20× the work per hop. Batching across hops is impossible
+   without breaking the dependency chain, and concurrent insertion breaks the
+   byte-identical-sidecar determinism contract. Declined.
+2. **WASM SIMD dot-batch kernel (`src/wasm-dot.ts`) — shipped, gate missed.**
+   363 bytes of hand-written WAT (SIMD128 mul/add, one call per node's
+   neighbor list, JS fallback on compile failure). Microbenchmark: **×6.0**
+   over the unrolled JS dot on a 32-dot batch (dim 256). End-to-end full
+   build (equally-warmed interleaved medians): **×1.27 at n=5000 and n=20000**
+   — the beam mostly expands 1–2 fresh neighbors per hop, so batching rarely
+   amortizes, and bookkeeping (visited sets, heap sorts) is untouched. An
+   order-optimistic first-run pairing (cold closure vs warm wasm) showed
+   ×2.10/×2.88 — the honest equally-warmed number is ×1.27. **Recall@10 is
+   identical across engines** (70.6%/40.0% paired at 5k/20k); per-engine
+   byte-identical rebuilds are pinned by tests. The kernel stays wired as
+   `buildHnsw(..., { engine: 'auto' })` in the indexer (strictly faster,
+   zero risk) but does not change the engine decision.
+
+**Conclusion:** the original (a) trigger — "an order of magnitude cheaper" —
+is not reachable by either accelerator. IVF remains the default ANN engine;
+HNSW remains opt-in with the #223 watch-reuse path. The auto-flip condition
+would need an algorithmic change (deferred-distance beam) or a native kernel,
+both out of scope for this project's zero-native-deps constraint.
+
 ### Reproducing
 
 ```bash
@@ -434,3 +517,43 @@ node bench/ann-recall.mjs                 # IVF + HNSW curves side by side
 mdss index --db ./notes --ann hnsw        # hnsw.json sidecar
 mdss search --db ./notes --ann hnsw "query"
 ```
+
+## 18. RAG Answer Faithfulness — First Measured Slice (Issue #229)
+
+`bench/rag-faithfulness.mjs` closes the measurement gap in the synthesis loop:
+30 answerable queries (reference docs = the golden set qrels) and 8
+unanswerable queries over the frozen 26-doc corpus, with judge-free metrics —
+citation precision/recall of `citationsUsed` against the golden docs, a
+support rate (answer sentences containing a golden-doc content term), and a
+spurious-citation rate for the unanswerable set. Deterministic, unit-tested,
+no LLM in the metric path.
+
+| Profile | Citation precision | Citation recall | Support rate | Spurious rate (unanswerable) | p50 |
+|---|---|---|---|---|---|
+| extractive · fake embedder · k=6 (committed baseline, ±5pp gate) | 70.0% | 83.3% | 67.6% | 100% | 1 ms |
+| extractive · granite-311m · k=6 | 73.3% | 85.0% | 68.3% | 100% | 36 ms |
+
+Two honest findings:
+
+1. **The extractive fallback cannot refuse.** On unanswerable queries it
+   cites whatever the retriever surfaced (spurious rate 100% by construction —
+   the fallback's contract is "answer from passages", and it has no
+   refusal stage). This is the documented trade-off of the zero-dependency
+   mode; the LLM profile (`--endpoint`, nightly report-only via
+   `MDSS_SMOKE_ENDPOINT`) is where refusal behavior becomes measurable.
+2. **Support ≈ 68%** — a third of extractive answer sentences are rhetorical
+   glue (headers, connectors) rather than golden-doc content. This is the
+   baseline an LLM-synthesis profile should beat without losing citation
+   precision.
+
+The nightly runs both profiles report-only (the fake-embedder run also gates
+against `bench/fixtures/rag-faithfulness-baseline.json` at ±5pp to catch
+unintended changes in the deterministic extractive path).
+
+### Reproducing
+
+```bash
+node bench/rag-faithfulness.mjs                                     # deterministic baseline path
+node bench/rag-faithfulness.mjs --model granite-multilingual-311m   # real-embedder extractive
+node bench/rag-faithfulness.mjs --endpoint http://127.0.0.1:8080/v1 # + LLM profile
+```

package/bin/cli.mjs

@@ -412,8 +412,13 @@ Options:
   --output <file>     Output file path (export, default: stdout).
   --ignore <glob>     Skip files/paths (repeatable). e.g. --ignore "log.md".
   --path <glob>       Search only files matching glob (repeatable). e.g. --path "docs/**".
+  --vault <dir>       Federated multi-vault search (repeatable): fuse results from
+                      --db and every --vault, each with its own index in
+                      <vault>/.mdss (search/serve).
   --since <date>      Search only files modified at/after date (YYYY-MM-DD or ISO).
   --k <n>             Number of results (search, default 6).
+  --max-per-file <n>  Collapse results to at most n passages per file
+                      (search; alias: --max-per-doc).
   --json              Machine-readable output (index, stats, search).
   --semantic          Pure vector ranking, skip lexical/RRF fusion (search).
   --rerank            Re-rank candidates with a cross-encoder (search; ~280MB model).
@@ -494,6 +499,12 @@ Options:
                       SSE streaming) or "ollama" (native /api/generate,
                       NDJSON streaming) (issue #199).
   --llm-model <m>     Provider-side chat model for --llm-endpoint.
+  --rag               tui: enable the interactive RAG panel — ask the vault from
+                      inside the TUI; streams a real LLM answer when
+                      --llm-endpoint is set, extractive fallback otherwise.
+  --session <id>      chat: use (or create) a named persistent session —
+                      multi-turn context with a reproducible source manifest.
+  --resume            chat: resume the most recent session.
   --open [N]          search: open the top (or Nth) hit in your editor at its
                       startLine — MDSS_EDITOR/VISUAL/EDITOR, then VS Code
                       --goto, then the GUI opener (issue #110). With --json on
@@ -557,6 +568,26 @@ function logErr(s) {
   process.stderr.write(s + '\n');
 }
 
+// ---------------------------------------------------------------------------
+// Node end-of-life notice (issue #224): Node 20 reached EOL on 2026-04-30 and
+// no longer receives security patches, but the published `engines` floor stays
+// >=20.9 until v3.0.0 (a hard bump is breaking — see 18 -> 20.9 in v2.0.0).
+// Running on a pre-22 runtime prints one stderr line per command; stdout stays
+// byte-identical for --json, TUI and MCP stdio consumers. Silenced via env.
+// ---------------------------------------------------------------------------
+
+export function nodeDeprecationNotice(version = process.version) {
+  if (process.env.MDSS_NO_NODE_WARNING === '1') return null;
+  const m = /^v(\d+)\./.exec(version);
+  const major = m ? Number(m[1]) : Number.NaN;
+  if (Number.isFinite(major) && major >= 22) return null;
+  return (
+    `⚠ Node ${version} is deprecated: Node 20 reached end-of-life on 2026-04-30 and gets no security patches.\n` +
+    `  mdss will require Node >= 22 from v3.0.0. Upgrade: https://nodejs.org/en/download\n` +
+    `  Set MDSS_NO_NODE_WARNING=1 to silence this notice.`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Data egress notice (issue #183): two opt-in paths send PRIVATE note content
 // to non-loopback destinations — external embedders and the RAG LLM bridge.
@@ -1903,6 +1934,9 @@ async function cmdRelated(opts) {
 }
 
 async function main() {
+  const deprecation = nodeDeprecationNotice();
+  if (deprecation) process.stderr.write(deprecation + '\n');
+
   const argv = process.argv.slice(2);
   const opts = parseArgs(argv);
   const configPath = findConfigFile(opts.config);

package/dist/hnsw.d.ts

@@ -49,6 +49,27 @@ export interface BuildHnswOptions {
      */
     distance: (a: Float32Array | Int8Array | number[], b: number) => number;
     vectors: Array<Float32Array | Int8Array | number[]>;
+    /**
+     * Issue #228: 'auto' routes the build's distance work through the WASM
+     * SIMD dot-batch kernel (src/wasm-dot.ts) when the vectors are a uniform
+     * Float32Array matrix and the runtime supports SIMD — ~6× faster dots on a
+     * 32-node batch, ~3.4× faster full build (RESEARCH.md §17). ONLY valid when
+     * the intended distance is exactly `1 − dot(a, vectors[b])`; any custom
+     * distance (int8 norms, asymmetric variants) must keep the default
+     * 'closure' engine. Silent fallback to 'closure' when 'auto' cannot apply.
+     */
+    engine?: 'auto' | 'closure';
+}
+/**
+ * Distance plumbing for the build (issue #228). The closure engine wraps the
+ * caller-supplied `distance`; the wasm engine replaces BOTH pointwise and
+ * batch distances with kernel calls so every distance on the chain uses the
+ * same SIMD accumulation order (self-consistent → deterministic sidecar).
+ */
+export interface HnswBuildEngine {
+    dist(aIdx: number, bIdx: number): number;
+    /** Distances from vectors[aIdx] to each node, same order — null = pointwise. */
+    batch?(aIdx: number, nodes: number[]): Float32Array | null;
 }
 export declare const DEFAULT_HNSW_M = 16;
 export declare const DEFAULT_HNSW_EF = 64;
@@ -59,7 +80,7 @@ export declare function buildHnsw(vectors: Array<Float32Array | Int8Array | numb
  * yet inserted are read from `vectors` when needed, so the caller can insert
  * lazily. Tombstoned indices can be re-inserted (undeletes).
  */
-export declare function insertHnsw(hnsw: HnswIndex, idx: number, distance: (a: Float32Array | Int8Array | number[], b: number) => number, vectors: Array<Float32Array | Int8Array | number[]>): void;
+export declare function insertHnsw(hnsw: HnswIndex, idx: number, distance: (a: Float32Array | Int8Array | number[], b: number) => number, vectors: Array<Float32Array | Int8Array | number[]>, engine?: HnswBuildEngine): void;
 /** Tombstone a node — searches skip it; the graph keeps it for connectivity. */
 export declare function deleteHnsw(hnsw: HnswIndex, idx: number): void;
 /**
@@ -94,3 +115,12 @@ export declare function serializeHnsw(hnsw: HnswIndex): SerializedHnsw;
  * falls back to brute force).
  */
 export declare function deserializeHnsw(raw: unknown, expectedChunksCount?: number): HnswIndex;
+/**
+ * issue #223: carry a persisted graph across a watch rebuild. `mapping[oldIdx]`
+ * is the chunk's NEW index (undefined = the chunk is gone → tombstone); nodes
+ * carry over because vector reuse is keyed by chunkHash — a surviving chunk
+ * keeps its exact vector, so every stored edge distance stays valid.
+ * Returns null when the remap cannot produce a navigable graph (e.g. the
+ * entry point did not survive) — the caller falls back to a full rebuild.
+ */
+export declare function remapHnsw(hnsw: HnswIndex, mapping: Array<number | undefined>, newCount: number): HnswIndex | null;