md-semantic-search 2.1.0 → 2.2.1

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`). |
@@ -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)
@@ -431,6 +478,38 @@ corpora keeps **IVF as the default engine**; the criterion's second branch
    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
@@ -438,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;
 /**

package/dist/hnsw.js

@@ -10,6 +10,7 @@
  * work unchanged. Deleted nodes are tombstones — searches skip them, which
  * is what lets the incremental watch rebuild reuse a persisted graph.
  */
+import { createWasmDotEngine } from './wasm-dot.js';
 /** Deterministic PRNG for level assignment (same family as ivf.ts). */
 function mulberry32(seed) {
     let s = seed >>> 0;
@@ -33,17 +34,78 @@ export function buildHnsw(vectors, options) {
         neighbors: [],
         deleted: new Set(),
     };
+    let engine;
+    if (options.engine === 'auto') {
+        engine = createWasmBuildEngine(vectors) ?? undefined;
+        // undefined → SIMD unavailable or non-uniform vectors: closure engine, silently.
+    }
     for (let i = 0; i < vectors.length; i++)
-        insertHnsw(hnsw, i, options.distance, options.vectors);
+        insertHnsw(hnsw, i, options.distance, options.vectors, engine);
     return hnsw;
 }
+/**
+ * Issue #228: wasm-backed build engine for uniform Float32Array matrices.
+ * Returns null whenever the fast path cannot apply — the caller then keeps
+ * the caller-supplied closure (identical semantics, JS arithmetic).
+ */
+function createWasmBuildEngine(vectors) {
+    for (const v of vectors) {
+        if (!(v instanceof Float32Array))
+            return null;
+    }
+    const wasmEngine = createWasmDotEngine(vectors);
+    if (!wasmEngine)
+        return null;
+    // Hybrid distance plumbing (measured, issue #228): BATCHES (a whole node's
+    // neighbor list — the 85% cost center) go through the SIMD kernel; pointwise
+    // calls (greedy descent, singleton scans, heuristic pairwise) stay on the
+    // plain JS dot — a 1-row wasm call pays call overhead exceeding the work.
+    // Both paths are IEEE f32 with fixed orders, so the build stays
+    // deterministic; recall is insensitive to the last-ulp difference (measured
+    // identical across engines in bench/ann-recall.mjs and the #228 tests).
+    const f32Vectors = vectors;
+    return {
+        dist: (a, b) => 1 - jsDotF32(f32Vectors[a], f32Vectors[b]),
+        batch: (aIdx, nodes) => {
+            const dots = wasmEngine.batch(aIdx, nodes);
+            const out = new Float32Array(dots.length);
+            for (let j = 0; j < dots.length; j++)
+                out[j] = 1 - dots[j];
+            return out;
+        },
+    };
+}
+function jsDotF32(a, b) {
+    let s = 0;
+    const n = a.length;
+    const limit = n - 7;
+    let i = 0;
+    let s0 = 0, s1 = 0, s2 = 0, s3 = 0, s4 = 0, s5 = 0, s6 = 0, s7 = 0;
+    while (i < limit) {
+        s0 += a[i] * b[i];
+        s1 += a[i + 1] * b[i + 1];
+        s2 += a[i + 2] * b[i + 2];
+        s3 += a[i + 3] * b[i + 3];
+        s4 += a[i + 4] * b[i + 4];
+        s5 += a[i + 5] * b[i + 5];
+        s6 += a[i + 6] * b[i + 6];
+        s7 += a[i + 7] * b[i + 7];
+        i += 8;
+    }
+    s = s0 + s1 + (s2 + s3) + (s4 + s5) + (s6 + s7);
+    while (i < n) {
+        s += a[i] * b[i];
+        i++;
+    }
+    return s;
+}
 /**
  * Insert node `idx` (vector index) into the graph. Incremental — new indices
  * attach to the existing structure without a rebuild; vectors for nodes NOT
  * yet inserted are read from `vectors` when needed, so the caller can insert
  * lazily. Tombstoned indices can be re-inserted (undeletes).
  */
-export function insertHnsw(hnsw, idx, distance, vectors) {
+export function insertHnsw(hnsw, idx, distance, vectors, engine) {
     const vec = vectors[idx];
     if (!vec)
         throw new Error(`hnsw insert: no vector at index ${idx}`);
@@ -64,7 +126,14 @@ export function insertHnsw(hnsw, idx, distance, vectors) {
         hnsw.maxLevel = level;
         return;
     }
-    const qDist = (node) => distance(vec, node);
+    // Issue #228: with a build engine, all pointwise distances go through
+    // dist(aIdx, bIdx) so the whole chain shares one arithmetic order; the
+    // per-neighbor scan uses engine.batch when available (one wasm call per
+    // node's neighbor list instead of one JS call per distance).
+    const dist = engine
+        ? (aIdx, bIdx) => engine.dist(aIdx, bIdx)
+        : (aIdx, bIdx) => distance(vectors[aIdx], bIdx);
+    const qDist = (node) => dist(idx, node);
     // 1. Greedy descent through layers above the node's level
     let ep = hnsw.entryPoint;
     let epDist = qDist(ep);
@@ -83,10 +152,12 @@ export function insertHnsw(hnsw, idx, distance, vectors) {
         }
     }
     // 2. Insert on each layer from min(level, maxLevel) down to 0
-    const pairwise = (a, b) => distance(vectors[a], b);
+    const pairwise = engine
+        ? (a, b) => engine.dist(a, b)
+        : (a, b) => distance(vectors[a], b);
     for (let l = Math.min(level, hnsw.maxLevel); l >= 0; l--) {
         const efC = Math.max(M0, DEFAULT_HNSW_EF);
-        const candidates = searchLayer(hnsw, qDist, ep, epDist, l, efC);
+        const candidates = searchLayer(hnsw, qDist, ep, epDist, l, efC, engine?.batch, idx);
         const cap = l === 0 ? M0 : M;
         // Algorithm 4: diversity-aware neighbor selection keeps the graph
         // navigable — a candidate is skipped only when it is CLOSER to an
@@ -121,7 +192,10 @@ export function deleteHnsw(hnsw, idx) {
         hnsw.deleted.add(idx);
 }
 /** ef-search one layer, returning the closest `ef` live candidates (closest first). */
-function searchLayer(hnsw, qDist, ep, epDist, layer, ef) {
+function searchLayer(hnsw, qDist, ep, epDist, layer, ef, 
+// issue #228: when present, the unvisited neighbors of each expanded node
+// are measured in ONE batched call (same order → same heap evolution).
+batch, aIdx) {
     const visited = new Set([ep]);
     // max-heap by dist via simple sorted insertion (candidate lists are small)
     const candidates = [{ node: ep, dist: epDist }];
@@ -131,11 +205,19 @@ function searchLayer(hnsw, qDist, ep, epDist, layer, ef) {
         const worst = results.length >= ef ? results[results.length - 1].dist : Infinity;
         if (current.dist > worst)
             break;
-        for (const nb of hnsw.neighbors[current.node][layer] ?? []) {
-            if (visited.has(nb))
-                continue;
+        const neighborList = hnsw.neighbors[current.node][layer] ?? [];
+        const fresh = [];
+        for (const nb of neighborList) {
+            if (!visited.has(nb))
+                fresh.push(nb);
+        }
+        let dists = null;
+        if (fresh.length > 1 && batch && aIdx !== undefined)
+            dists = batch(aIdx, fresh);
+        for (let j = 0; j < fresh.length; j++) {
+            const nb = fresh[j];
             visited.add(nb);
-            const d = qDist(nb);
+            const d = dists ? dists[j] : qDist(nb);
             const worstNow = results.length >= ef ? results[results.length - 1].dist : Infinity;
             if (d < worstNow || results.length < ef) {
                 candidates.push({ node: nb, dist: d });

package/dist/indexer.js

@@ -524,7 +524,11 @@ async function _buildIndexInner({ db, indexDir, cacheDir, modelName, dimensions,
                 }
             }
             if (!hnswIndex) {
-                hnswIndex = buildHnsw(rawVecs, { vectors: rawVecs, distance: hnswDistance(rawVecs) });
+                // issue #228: 'auto' routes the full build through the WASM SIMD
+                // dot-batch kernel when the vectors are a uniform Float32Array matrix
+                // (the hnswDistance closure below is exactly 1 − dot, so semantics
+                // match); otherwise buildHnsw silently keeps the closure path.
+                hnswIndex = buildHnsw(rawVecs, { vectors: rawVecs, distance: hnswDistance(rawVecs), engine: 'auto' });
             }
             atomicWrite(hnswPath, JSON.stringify(serializeHnsw(hnswIndex)));
             if (fs.existsSync(ivfPath)) {

package/dist/models.d.ts

@@ -24,7 +24,7 @@ export interface ModelAdapter {
     unknownAdapter?: boolean;
 }
 export declare const MODELS: Record<string, ModelAdapter>;
-export declare const DEFAULT_MODEL = "e5-base";
+export declare const DEFAULT_MODEL = "granite-multilingual-311m";
 export declare const POOLING: Pooling[];
 export declare function normalizeAdapter(raw: Partial<ModelAdapter> | ModelAdapter): ModelAdapter;
 export declare function resolveModel(name?: string | Partial<ModelAdapter> | ModelAdapter | null, chosenDim?: number): ModelAdapter;

package/dist/models.js

@@ -27,7 +27,7 @@ export const MODELS = {
         dtype: 'q8',
         maxTokens: 512,
         family: 'e5',
-        note: 'Default. ~280MB. Solid multilingual + cross-lingual balance.',
+        note: 'Pre-2.2.0 default. ~280MB. Solid multilingual + cross-lingual balance.',
     },
     'e5-large': {
         id: 'Xenova/multilingual-e5-large',
@@ -102,7 +102,12 @@ export const MODELS = {
         note: '~300 MB q8. Google EmbeddingGemma, pre-pooled sentence_embedding output, MRL. Gemma license (not MIT/Apache). Issue #200.',
     },
 };
-export const DEFAULT_MODEL = 'e5-base';
+// Issue #227: granite-multilingual-311m is the default — Apache-2.0 (the
+// measured leader embeddinggemma-300m is license-blocked from being an npm
+// default by the Gemma Terms of Use) and measured +0.078 nDCG@10 over e5-base
+// on the 186-query golden set v2 (RESEARCH.md §15). Same size class (~298 MB
+// q8), 8k ModernBERT context. e5-base stays a registered alias.
+export const DEFAULT_MODEL = 'granite-multilingual-311m';
 export const POOLING = ['mean', 'last_token', 'none', 'cls'];
 const POOLING_SET = new Set(POOLING);
 const aliasByRepoId = new Map();

package/dist/wasm-dot.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WASM SIMD128 dot-product engine for the HNSW graph build (issue #228).
+ *
+ * The build's cost profile is ~85% distance computation (measured: 16.5k
+ * distance calls per node at n=5000, dim=256; RESEARCH.md §17), and those
+ * calls sit on a sequential dependency chain — worker_threads parallelism is
+ * structurally blocked (per-insert graph state + the byte-identical-sidecar
+ * determinism contract). The achievable lever is making each dot faster:
+ * this module batches f32 dot products into ONE WebAssembly call
+ * (`dot_batch`: N row indices → N dot products against a shared query row)
+ * with a SIMD128 mul/add inner loop — measured ~6× over the unrolled JS dot
+ * at dim=256 on a 32-dot batch.
+ *
+ * Zero native dependencies: the module is 363 bytes of hand-written WAT
+ * compiled once via wabt and embedded below (source of record:
+ * bench/ann-recall.mjs history + RESEARCH.md §17). Compile failure (no SIMD
+ * in the runtime) degrades to `null` and the caller keeps the JS closure path.
+ *
+ * Determinism: all arithmetic is IEEE f32 with a fixed lane order — repeated
+ * builds on the same corpus produce a byte-identical sidecar per engine. The
+ * SIMD accumulation order differs from the JS closure path in the last ulp,
+ * so the two engines are each self-consistent but not cross-identical; the
+ * sidecar records which engine built it (same engine → same bytes).
+ */
+export interface WasmDotEngine {
+    /** dot(vectors[a], vectors[b]) — one-row batch, same arithmetic as batch(). */
+    point(aIdx: number, bIdx: number): number;
+    /** result[j] = dot(vectors[aIdx], vectors[nodes[j]]) — a view into wasm memory, valid until the next call. */
+    batch(aIdx: number, nodes: number[]): Float32Array;
+    readonly dim: number;
+}
+/**
+ * Build the engine over a uniform Float32Array matrix. Returns null when the
+ * runtime cannot compile the SIMD module (then callers keep the JS path).
+ */
+export declare function createWasmDotEngine(vectors: Array<Float32Array>): WasmDotEngine | null;

package/dist/wasm-dot.js

@@ -0,0 +1,106 @@
+/**
+ * WASM SIMD128 dot-product engine for the HNSW graph build (issue #228).
+ *
+ * The build's cost profile is ~85% distance computation (measured: 16.5k
+ * distance calls per node at n=5000, dim=256; RESEARCH.md §17), and those
+ * calls sit on a sequential dependency chain — worker_threads parallelism is
+ * structurally blocked (per-insert graph state + the byte-identical-sidecar
+ * determinism contract). The achievable lever is making each dot faster:
+ * this module batches f32 dot products into ONE WebAssembly call
+ * (`dot_batch`: N row indices → N dot products against a shared query row)
+ * with a SIMD128 mul/add inner loop — measured ~6× over the unrolled JS dot
+ * at dim=256 on a 32-dot batch.
+ *
+ * Zero native dependencies: the module is 363 bytes of hand-written WAT
+ * compiled once via wabt and embedded below (source of record:
+ * bench/ann-recall.mjs history + RESEARCH.md §17). Compile failure (no SIMD
+ * in the runtime) degrades to `null` and the caller keeps the JS closure path.
+ *
+ * Determinism: all arithmetic is IEEE f32 with a fixed lane order — repeated
+ * builds on the same corpus produce a byte-identical sidecar per engine. The
+ * SIMD accumulation order differs from the JS closure path in the last ulp,
+ * so the two engines are each self-consistent but not cross-identical; the
+ * sidecar records which engine built it (same engine → same bytes).
+ */
+/** The compiled `dot_batch` module (see module docstring for provenance). */
+const KERNEL_B64 = 'AGFzbQEAAAABCQFgBX9/f39/AAMCAQAFAwEAAQcTAgNtZW0CAAlkb3RfYmF0Y2gAAAq3AgG0AgQCfwF9An8EeyADQQRsIQlBACEF' +
+    'AkADQCAFIAJODQEgASAFQQRsaigCACAJbCEG/QwAAAAAAAAAAAAAAAAAAAAAIQr9DAAAAAAAAAAAAAAAAAAAAAAhC/0MAAAAAAAAA' +
+    'AAAAAAAAAAAACEM/QwAAAAAAAAAAAAAAAAAAAAAIQ1DAAAAACEHQQAhCAJAA0AgCEEQaiAJSg0BIAogACAIav0AAgAgBiAIav0A' +
+    'AgD95gH95AEhCiAIQRBqIQgMAAsLAkADQCAIIAlODQEgByAAIAhqKgIAIAYgCGoqAgCUkiEHIAhBBGohCAwACwsgBCAFQQRsaiAK' +
+    '/R8AIAr9HwGSIAr9HwIgCv0fA5KSIAcgC/0fACAL/R8BkiAL/R8CIAv9HwOSkpKSOAIAIAVBAWohBQwACwsL';
+/** Max nodes per batch call — HNSW neighbor lists cap at M0 = 2*M ≤ 64. */
+const MAX_BATCH = 64;
+/**
+ * Build the engine over a uniform Float32Array matrix. Returns null when the
+ * runtime cannot compile the SIMD module (then callers keep the JS path).
+ */
+export function createWasmDotEngine(vectors) {
+    if (vectors.length === 0)
+        return null;
+    const dim = vectors[0].length;
+    if (dim === 0)
+        return null;
+    for (const v of vectors) {
+        if (!(v instanceof Float32Array) || v.length !== dim)
+            return null;
+    }
+    let kernelBuffer;
+    try {
+        const bin = Buffer.from(KERNEL_B64, 'base64');
+        kernelBuffer = new ArrayBuffer(bin.byteLength);
+        new Uint8Array(kernelBuffer).set(bin);
+        if (bin.byteLength === 0)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let instance;
+    try {
+        instance = new WebAssembly.Instance(new WebAssembly.Module(kernelBuffer), {});
+    }
+    catch {
+        return null; // no SIMD support — caller falls back to the JS closure path
+    }
+    const exp = instance.exports;
+    const mem = exp.mem;
+    // Linear memory layout: [vectors row-major][idx scratch u32 × MAX_BATCH][out f32 × MAX_BATCH]
+    const vecBytes = vectors.length * dim * 4;
+    const idxByte = vecBytes;
+    const outByte = idxByte + MAX_BATCH * 4;
+    const needBytes = outByte + MAX_BATCH * 4 + 4096;
+    const pages = Math.ceil(needBytes / 65536);
+    try {
+        if (mem.buffer.byteLength < needBytes)
+            mem.grow(pages);
+    }
+    catch {
+        return null;
+    }
+    // Views are created AFTER the final grow — growing detaches old buffers.
+    const f32 = new Float32Array(mem.buffer);
+    const u32 = new Uint32Array(mem.buffer);
+    for (let i = 0; i < vectors.length; i++)
+        f32.set(vectors[i], i * dim);
+    const qByteOf = (aIdx) => {
+        if (!Number.isSafeInteger(aIdx) || aIdx < 0 || aIdx >= vectors.length) {
+            throw new Error(`wasm-dot: row index out of range: ${aIdx}`);
+        }
+        return aIdx * dim * 4;
+    };
+    return {
+        dim,
+        point(aIdx, bIdx) {
+            u32[idxByte >> 2] = bIdx;
+            exp.dot_batch(qByteOf(aIdx), idxByte, 1, dim, outByte);
+            return f32[outByte >> 2];
+        },
+        batch(aIdx, nodes) {
+            const n = Math.min(nodes.length, MAX_BATCH);
+            for (let j = 0; j < n; j++)
+                u32[(idxByte >> 2) + j] = nodes[j];
+            exp.dot_batch(qByteOf(aIdx), idxByte, n, dim, outByte);
+            return f32.subarray(outByte >> 2, (outByte >> 2) + n);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-semantic-search",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Local, private semantic (vector) search over any folder of Markdown files. Finds passages by meaning — cross-lingual — using transformers.js. No API keys, no cloud, no vector database.",
   "type": "module",
   "main": "./dist/index.js",

package/src/hnsw.ts

@@ -11,6 +11,8 @@
  * is what lets the incremental watch rebuild reuse a persisted graph.
  */
 
+import { createWasmDotEngine } from './wasm-dot.js';
+
 /** Deterministic PRNG for level assignment (same family as ivf.ts). */
 function mulberry32(seed: number): () => number {
   let s = seed >>> 0;
@@ -63,6 +65,28 @@ 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 const DEFAULT_HNSW_M = 16;
@@ -82,10 +106,70 @@ export function buildHnsw(
     neighbors: [],
     deleted: new Set(),
   };
-  for (let i = 0; i < vectors.length; i++) insertHnsw(hnsw, i, options.distance, options.vectors);
+  let engine: HnswBuildEngine | undefined;
+  if (options.engine === 'auto') {
+    engine = createWasmBuildEngine(vectors) ?? undefined;
+    // undefined → SIMD unavailable or non-uniform vectors: closure engine, silently.
+  }
+  for (let i = 0; i < vectors.length; i++) insertHnsw(hnsw, i, options.distance, options.vectors, engine);
   return hnsw;
 }
 
+/**
+ * Issue #228: wasm-backed build engine for uniform Float32Array matrices.
+ * Returns null whenever the fast path cannot apply — the caller then keeps
+ * the caller-supplied closure (identical semantics, JS arithmetic).
+ */
+function createWasmBuildEngine(vectors: Array<Float32Array | Int8Array | number[]>): HnswBuildEngine | null {
+  for (const v of vectors) {
+    if (!(v instanceof Float32Array)) return null;
+  }
+  const wasmEngine = createWasmDotEngine(vectors as Array<Float32Array>);
+  if (!wasmEngine) return null;
+  // Hybrid distance plumbing (measured, issue #228): BATCHES (a whole node's
+  // neighbor list — the 85% cost center) go through the SIMD kernel; pointwise
+  // calls (greedy descent, singleton scans, heuristic pairwise) stay on the
+  // plain JS dot — a 1-row wasm call pays call overhead exceeding the work.
+  // Both paths are IEEE f32 with fixed orders, so the build stays
+  // deterministic; recall is insensitive to the last-ulp difference (measured
+  // identical across engines in bench/ann-recall.mjs and the #228 tests).
+  const f32Vectors = vectors as Array<Float32Array>;
+  return {
+    dist: (a, b) => 1 - jsDotF32(f32Vectors[a], f32Vectors[b]),
+    batch: (aIdx, nodes) => {
+      const dots = wasmEngine.batch(aIdx, nodes);
+      const out = new Float32Array(dots.length);
+      for (let j = 0; j < dots.length; j++) out[j] = 1 - dots[j];
+      return out;
+    },
+  };
+}
+
+function jsDotF32(a: Float32Array, b: Float32Array): number {
+  let s = 0;
+  const n = a.length;
+  const limit = n - 7;
+  let i = 0;
+  let s0 = 0, s1 = 0, s2 = 0, s3 = 0, s4 = 0, s5 = 0, s6 = 0, s7 = 0;
+  while (i < limit) {
+    s0 += a[i] * b[i];
+    s1 += a[i + 1] * b[i + 1];
+    s2 += a[i + 2] * b[i + 2];
+    s3 += a[i + 3] * b[i + 3];
+    s4 += a[i + 4] * b[i + 4];
+    s5 += a[i + 5] * b[i + 5];
+    s6 += a[i + 6] * b[i + 6];
+    s7 += a[i + 7] * b[i + 7];
+    i += 8;
+  }
+  s = s0 + s1 + (s2 + s3) + (s4 + s5) + (s6 + s7);
+  while (i < n) {
+    s += a[i] * b[i];
+    i++;
+  }
+  return s;
+}
+
 /**
  * Insert node `idx` (vector index) into the graph. Incremental — new indices
  * attach to the existing structure without a rebuild; vectors for nodes NOT
@@ -96,7 +180,8 @@ export function insertHnsw(
   hnsw: HnswIndex,
   idx: number,
   distance: (a: Float32Array | Int8Array | number[], b: number) => number,
-  vectors: Array<Float32Array | Int8Array | number[]>
+  vectors: Array<Float32Array | Int8Array | number[]>,
+  engine?: HnswBuildEngine
 ): void {
   const vec = vectors[idx];
   if (!vec) throw new Error(`hnsw insert: no vector at index ${idx}`);
@@ -121,7 +206,14 @@ export function insertHnsw(
     return;
   }
 
-  const qDist = (node: number) => distance(vec, node);
+  // Issue #228: with a build engine, all pointwise distances go through
+  // dist(aIdx, bIdx) so the whole chain shares one arithmetic order; the
+  // per-neighbor scan uses engine.batch when available (one wasm call per
+  // node's neighbor list instead of one JS call per distance).
+  const dist = engine
+    ? (aIdx: number, bIdx: number) => engine.dist(aIdx, bIdx)
+    : (aIdx: number, bIdx: number) => distance(vectors[aIdx], bIdx);
+  const qDist = (node: number) => dist(idx, node);
 
   // 1. Greedy descent through layers above the node's level
   let ep = hnsw.entryPoint;
@@ -142,10 +234,12 @@ export function insertHnsw(
   }
 
   // 2. Insert on each layer from min(level, maxLevel) down to 0
-  const pairwise = (a: number, b: number) => distance(vectors[a], b);
+  const pairwise = engine
+    ? (a: number, b: number) => engine.dist(a, b)
+    : (a: number, b: number) => distance(vectors[a], b);
   for (let l = Math.min(level, hnsw.maxLevel); l >= 0; l--) {
     const efC = Math.max(M0, DEFAULT_HNSW_EF);
-    const candidates = searchLayer(hnsw, qDist, ep, epDist, l, efC);
+    const candidates = searchLayer(hnsw, qDist, ep, epDist, l, efC, engine?.batch, idx);
     const cap = l === 0 ? M0 : M;
     // Algorithm 4: diversity-aware neighbor selection keeps the graph
     // navigable — a candidate is skipped only when it is CLOSER to an
@@ -191,7 +285,11 @@ function searchLayer(
   ep: number,
   epDist: number,
   layer: number,
-  ef: number
+  ef: number,
+  // issue #228: when present, the unvisited neighbors of each expanded node
+  // are measured in ONE batched call (same order → same heap evolution).
+  batch?: (aIdx: number, nodes: number[]) => Float32Array | null,
+  aIdx?: number
 ): Array<{ node: number; dist: number }> {
   const visited = new Set<number>([ep]);
   // max-heap by dist via simple sorted insertion (candidate lists are small)
@@ -204,10 +302,17 @@ function searchLayer(
     const worst = results.length >= ef ? results[results.length - 1].dist : Infinity;
     if (current.dist > worst) break;
 
-    for (const nb of hnsw.neighbors[current.node][layer] ?? []) {
-      if (visited.has(nb)) continue;
+    const neighborList = hnsw.neighbors[current.node][layer] ?? [];
+    const fresh: number[] = [];
+    for (const nb of neighborList) {
+      if (!visited.has(nb)) fresh.push(nb);
+    }
+    let dists: Float32Array | null = null;
+    if (fresh.length > 1 && batch && aIdx !== undefined) dists = batch(aIdx, fresh);
+    for (let j = 0; j < fresh.length; j++) {
+      const nb = fresh[j];
       visited.add(nb);
-      const d = qDist(nb);
+      const d = dists ? dists[j] : qDist(nb);
       const worstNow = results.length >= ef ? results[results.length - 1].dist : Infinity;
       if (d < worstNow || results.length < ef) {
         candidates.push({ node: nb, dist: d });

package/src/indexer.ts

@@ -701,7 +701,11 @@ async function _buildIndexInner({
         }
       }
       if (!hnswIndex) {
-        hnswIndex = buildHnsw(rawVecs, { vectors: rawVecs, distance: hnswDistance(rawVecs) });
+        // issue #228: 'auto' routes the full build through the WASM SIMD
+        // dot-batch kernel when the vectors are a uniform Float32Array matrix
+        // (the hnswDistance closure below is exactly 1 − dot, so semantics
+        // match); otherwise buildHnsw silently keeps the closure path.
+        hnswIndex = buildHnsw(rawVecs, { vectors: rawVecs, distance: hnswDistance(rawVecs), engine: 'auto' });
       }
       atomicWrite(hnswPath, JSON.stringify(serializeHnsw(hnswIndex)));
       if (fs.existsSync(ivfPath)) {

package/src/models.ts

@@ -55,7 +55,7 @@ export const MODELS: Record<string, ModelAdapter> = {
     dtype: 'q8',
     maxTokens: 512,
     family: 'e5',
-    note: 'Default. ~280MB. Solid multilingual + cross-lingual balance.',
+    note: 'Pre-2.2.0 default. ~280MB. Solid multilingual + cross-lingual balance.',
   },
   'e5-large': {
     id: 'Xenova/multilingual-e5-large',
@@ -131,7 +131,12 @@ export const MODELS: Record<string, ModelAdapter> = {
   },
 };
 
-export const DEFAULT_MODEL = 'e5-base';
+// Issue #227: granite-multilingual-311m is the default — Apache-2.0 (the
+// measured leader embeddinggemma-300m is license-blocked from being an npm
+// default by the Gemma Terms of Use) and measured +0.078 nDCG@10 over e5-base
+// on the 186-query golden set v2 (RESEARCH.md §15). Same size class (~298 MB
+// q8), 8k ModernBERT context. e5-base stays a registered alias.
+export const DEFAULT_MODEL = 'granite-multilingual-311m';
 export const POOLING: Pooling[] = ['mean', 'last_token', 'none', 'cls'];
 const POOLING_SET = new Set<string>(POOLING);
 

package/src/wasm-dot.ts

@@ -0,0 +1,115 @@
+/**
+ * WASM SIMD128 dot-product engine for the HNSW graph build (issue #228).
+ *
+ * The build's cost profile is ~85% distance computation (measured: 16.5k
+ * distance calls per node at n=5000, dim=256; RESEARCH.md §17), and those
+ * calls sit on a sequential dependency chain — worker_threads parallelism is
+ * structurally blocked (per-insert graph state + the byte-identical-sidecar
+ * determinism contract). The achievable lever is making each dot faster:
+ * this module batches f32 dot products into ONE WebAssembly call
+ * (`dot_batch`: N row indices → N dot products against a shared query row)
+ * with a SIMD128 mul/add inner loop — measured ~6× over the unrolled JS dot
+ * at dim=256 on a 32-dot batch.
+ *
+ * Zero native dependencies: the module is 363 bytes of hand-written WAT
+ * compiled once via wabt and embedded below (source of record:
+ * bench/ann-recall.mjs history + RESEARCH.md §17). Compile failure (no SIMD
+ * in the runtime) degrades to `null` and the caller keeps the JS closure path.
+ *
+ * Determinism: all arithmetic is IEEE f32 with a fixed lane order — repeated
+ * builds on the same corpus produce a byte-identical sidecar per engine. The
+ * SIMD accumulation order differs from the JS closure path in the last ulp,
+ * so the two engines are each self-consistent but not cross-identical; the
+ * sidecar records which engine built it (same engine → same bytes).
+ */
+
+/** The compiled `dot_batch` module (see module docstring for provenance). */
+const KERNEL_B64 =
+  'AGFzbQEAAAABCQFgBX9/f39/AAMCAQAFAwEAAQcTAgNtZW0CAAlkb3RfYmF0Y2gAAAq3AgG0AgQCfwF9An8EeyADQQRsIQlBACEF' +
+  'AkADQCAFIAJODQEgASAFQQRsaigCACAJbCEG/QwAAAAAAAAAAAAAAAAAAAAAIQr9DAAAAAAAAAAAAAAAAAAAAAAhC/0MAAAAAAAAA' +
+  'AAAAAAAAAAAACEM/QwAAAAAAAAAAAAAAAAAAAAAIQ1DAAAAACEHQQAhCAJAA0AgCEEQaiAJSg0BIAogACAIav0AAgAgBiAIav0A' +
+  'AgD95gH95AEhCiAIQRBqIQgMAAsLAkADQCAIIAlODQEgByAAIAhqKgIAIAYgCGoqAgCUkiEHIAhBBGohCAwACwsgBCAFQQRsaiAK' +
+  '/R8AIAr9HwGSIAr9HwIgCv0fA5KSIAcgC/0fACAL/R8BkiAL/R8CIAv9HwOSkpKSOAIAIAVBAWohBQwACwsL';
+
+export interface WasmDotEngine {
+  /** dot(vectors[a], vectors[b]) — one-row batch, same arithmetic as batch(). */
+  point(aIdx: number, bIdx: number): number;
+  /** result[j] = dot(vectors[aIdx], vectors[nodes[j]]) — a view into wasm memory, valid until the next call. */
+  batch(aIdx: number, nodes: number[]): Float32Array;
+  readonly dim: number;
+}
+
+/** Max nodes per batch call — HNSW neighbor lists cap at M0 = 2*M ≤ 64. */
+const MAX_BATCH = 64;
+
+/**
+ * Build the engine over a uniform Float32Array matrix. Returns null when the
+ * runtime cannot compile the SIMD module (then callers keep the JS path).
+ */
+export function createWasmDotEngine(vectors: Array<Float32Array>): WasmDotEngine | null {
+  if (vectors.length === 0) return null;
+  const dim = vectors[0].length;
+  if (dim === 0) return null;
+  for (const v of vectors) {
+    if (!(v instanceof Float32Array) || v.length !== dim) return null;
+  }
+
+  let kernelBuffer: ArrayBuffer;
+  try {
+    const bin = Buffer.from(KERNEL_B64, 'base64');
+    kernelBuffer = new ArrayBuffer(bin.byteLength);
+    new Uint8Array(kernelBuffer).set(bin);
+    if (bin.byteLength === 0) return null;
+  } catch {
+    return null;
+  }
+  let instance: WebAssembly.Instance;
+  try {
+    instance = new WebAssembly.Instance(new WebAssembly.Module(kernelBuffer), {});
+  } catch {
+    return null; // no SIMD support — caller falls back to the JS closure path
+  }
+  const exp = instance.exports as unknown as {
+    mem: WebAssembly.Memory;
+    dot_batch: (q: number, idx: number, n: number, dim: number, out: number) => void;
+  };
+  const mem = exp.mem;
+
+  // Linear memory layout: [vectors row-major][idx scratch u32 × MAX_BATCH][out f32 × MAX_BATCH]
+  const vecBytes = vectors.length * dim * 4;
+  const idxByte = vecBytes;
+  const outByte = idxByte + MAX_BATCH * 4;
+  const needBytes = outByte + MAX_BATCH * 4 + 4096;
+  const pages = Math.ceil(needBytes / 65536);
+  try {
+    if (mem.buffer.byteLength < needBytes) mem.grow(pages);
+  } catch {
+    return null;
+  }
+  // Views are created AFTER the final grow — growing detaches old buffers.
+  const f32 = new Float32Array(mem.buffer);
+  const u32 = new Uint32Array(mem.buffer);
+  for (let i = 0; i < vectors.length; i++) f32.set(vectors[i], i * dim);
+
+  const qByteOf = (aIdx: number) => {
+    if (!Number.isSafeInteger(aIdx) || aIdx < 0 || aIdx >= vectors.length) {
+      throw new Error(`wasm-dot: row index out of range: ${aIdx}`);
+    }
+    return aIdx * dim * 4;
+  };
+
+  return {
+    dim,
+    point(aIdx: number, bIdx: number): number {
+      u32[idxByte >> 2] = bIdx;
+      exp.dot_batch(qByteOf(aIdx), idxByte, 1, dim, outByte);
+      return f32[outByte >> 2];
+    },
+    batch(aIdx: number, nodes: number[]): Float32Array {
+      const n = Math.min(nodes.length, MAX_BATCH);
+      for (let j = 0; j < n; j++) u32[(idxByte >> 2) + j] = nodes[j];
+      exp.dot_batch(qByteOf(aIdx), idxByte, n, dim, outByte);
+      return f32.subarray(outByte >> 2, (outByte >> 2) + n);
+    },
+  };
+}