graph-indexer 2.0.0 → 2.1.0

package/README.md

@@ -23,13 +23,14 @@ Graph Indexer is a local [Model Context Protocol](https://modelcontextprotocol.i
 
 - **Up to 98.2% Token Savings:** Delivers the exact AST chunk needed instead of dumping 1M token context files.
 - **Blast radius before every edit.** `get_call_graph` and `find_references` surface every caller, subclass, and dependency a change would touch, so the agent reasons about impact on code it never opened.
-- **Private by default.** Everything runs locally; the default path makes zero network calls and needs no model — your code never leaves your machine.
-- **One command, any language.** Guided setup wires your editors in seconds, and the zero-dependency lexical engine indexes 14 languages out of the box.
+- **Private by default.** Everything runs locally; the default path makes zero network calls and needs no model — your code never leaves your machine. (The very first index build fetches only the Tree-sitter grammar(s) for languages actually in your repo — see [Language grammars](#language-grammars) — cached from then on; `--sealed` enforces zero network hard.)
+- **One command, any language.** Guided setup wires your editors in seconds, and the lexical engine indexes 14 languages — installing each one's grammar on first use, not bundled, so a fresh `npm install graph-indexer` stays small.
 
 ## 📦 Prerequisites
 
 * **Node.js** 18+ (22+ recommended if you hit >15k chunks for automatic SQLite scaling).
 * **OS:** Agnostic. macOS Apple Silicon required only for the optional MLX GPU acceleration.
+* **Network (first index build only):** installs the Tree-sitter grammar(s) for languages in your repo (a few MB each) — see [Language grammars](#language-grammars). Cached after; fully offline from then on, or pre-install before going air-gapped.
 * **Optional:** Ollama for embeddings, enrichment, and reranking (see [Ollama setup](#ollama-setup)).
 * **Optional:** Python 3.10+ for the MLX embedder (macOS Apple Silicon only).
 
@@ -141,7 +142,7 @@ Before the steps, it scans the repo to pre-select your stack — languages from
 
 It finishes with a grouped summary (created / updated / kept / skipped / warnings), offers to **build the index now**, and prints your next steps.
 
-**Most repos need nothing past step 3's default** — the lexical engine has zero dependencies and works in any language. Step 3 only branches when you decline the defaults:
+**Most repos need nothing past step 3's default** — the lexical engine works in any language, installing that language's grammar on the first index build. Step 3 only branches when you decline the defaults:
 
 - **Storage** — `auto` (in-memory, promoting to SQLite past ~15k chunks), or force in-memory / SQLite.
 - **Embeddings** — `off` (default), `auto`, **Ollama**, **local** (in-process MiniLM, ~25 MB on first index), or **Apple Metal (MLX)** on macOS. Ollama is probed only when you actually pick it; choosing MLX offers to provision its Python venv on the spot.
@@ -165,6 +166,10 @@ Setup also runs non-interactively whenever stdin isn't a TTY, so piping into it
 - **Call graph.** `get_call_graph` returns the callers and callees of a symbol — the *blast radius* of a change — so an agent can see what it might break before editing code it never read.
 - **Backend parity.** The in-memory and SQLite backends share the same ranking core, so they return identical top-5 results for the same query (enforced by `test/sqlite.mjs`).
 
+### Language grammars
+
+Tree-sitter grammars aren't bundled with the package — a fresh `npm install graph-indexer` doesn't download all 14 languages' native bindings, just the ~5 MB core engine. Instead, the first `idx-index` run installs the grammar(s) for whichever languages you actually selected (or, un-narrowed, whatever's detected) into `.graph-indexer/node_modules`, and reuses that cache on every later run — no re-download, no re-build. This works the same way whether graph-indexer is a project dependency, a global install, or run ad hoc via `npx`, because the install target is always your repo's own `.graph-indexer/` directory, not graph-indexer's own location. A platform-incompatible grammar (e.g. a missing native toolchain) is skipped on its own — other languages still install and index normally, the same graceful degradation `npm`'s `optionalDependencies` used to give for free. Under `--sealed`, auto-install is disabled entirely: an unresolvable grammar fails the run with the exact `npm install --prefix .graph-indexer <pkg>@<version>` command to run first, rather than silently shipping a partial index.
+
 ### MCP tools
 
 | Tool | Returns |
@@ -175,11 +180,16 @@ Setup also runs non-interactively whenever stdin isn't a TTY, so piping into it
 | `resolve_symbol` | Exact, case-insensitive symbol lookup by name. |
 | `get_file_skeleton` | The top-level structure (symbols + signatures) of a file. |
 | `get_call_graph` | Callers and callees of a symbol — the blast radius. |
-| `find_references` | Where a symbol is used: callers, subclasses, and type references. |
+| `find_references` | Where a symbol is used: callers, subclasses, and type references. On a `--resolver scip` index, adds a precise cross-file **`resolved`-tier** dimension that disambiguates same-named symbols and recovers references the name heuristics miss. |
 | `find_routes` | HTTP routes mapped to their handler chunks (NestJS, FastAPI/Flask, Spring, Express/Koa). |
 | `get_subgraph` | A bounded connected subgraph around a seed symbol — its callees, high-confidence callers, and type/inheritance users, in one call. |
-| `get_repo_map` | A high-level map of the repository's modules and topology. |
+| `get_repo_map` | A high-level map of the repository's modules and topology. With `--symbol-graph`, also lists the most-central symbols (PageRank). |
 | `list_index_stats` | Index health: chunk/file/symbol/vector counts and the active config. |
+| `tests_for` | The test/spec chunks that exercise a symbol (call or reference it) — which tests to run or update before changing it. |
+| `explain_symbol` | One-call overview of a symbol: signature, callees, callers (blast radius), subclasses/type users, routes it handles, tests, git recency/co-change, and (with `--symbol-graph`) its symbol-centrality rank. |
+| `impact_of_edit` | The precise blast radius of a change: pass the symbols/files you're about to edit → transitively-affected code, the routes that reach it, the tests to run, and git co-change. Most precise with `--symbol-graph`; `precision: 'strict'` follows only provably-unambiguous (`resolved`) edges (best on a `--resolver precise` or `--resolver scip` index). |
+| `trace_taint` | Security: trace untrusted data from a source (request body/query/params, argv/env, stdin) to a dangerous sink (eval/exec, SQL, fs/path, HTML, outbound request) across the call graph — injection-class risks (rce/sqli/xss/path/ssrf) with the source→sink path. JS/TS, Python, Java, Go; heuristic finder, not a verifier. |
+| `find_tainted_sinks` | Security orientation: every dangerous sink grouped by category, each flagged with whether an untrusted source reaches it — map the attack surface, then `trace_taint` a specific one. |
 
 ## Configuration
 
@@ -190,13 +200,20 @@ Everything beyond the lexical default is opt-in. The server, indexer, and daemon
 | Option | Default | When to enable | Cost |
 |--------|---------|----------------|------|
 | `--embeddings` | off | Larger repos where recall matters; lifts success@5 | Requires Ollama or the in-process MiniLM model; slower indexing |
-| `--embed-model qwen3-embedding:4b` | `nomic-embed-text` | Better code recall + symbolic precision | slower indexing; requires Ollama |
+| `--embed-model qwen3-embedding:4b` | `nomic-embed-text` | A code-specialized embedder — lifts agent-style recall on Go (and some code-heavy repos); measure first | slower indexing; requires Ollama; neutral on JS/Python in our tests |
 | `--enrichment` | off | Only useful paired with `--rerank`; alone it regresses | slowest indexing |
 | `--rerank` | off | Go/Python repos with weak semantic recall; regresses JS repos | Requires an Ollama 7B model; adds query latency |
+| `--rerank --rerank-provider cross-encoder` | `generative` | Want a reranker's semantic lift with **no LLM/daemon** — air-gapped, deterministic, fast | Optional `@huggingface/transformers`; smaller lift than the 7B judge |
 | `--use-sqlite` | `auto` | Repos past ~15k chunks or memory-constrained environments | Slightly higher query latency; needs Node 22+ |
 
 For most repos, the default (lexical + stemming, no embeddings) is the right starting point. Enable embeddings when you notice the agent missing chunks it should find. Enable the reranker only on Go or Python repos after measuring whether it helps — it is known to regress JavaScript repositories.
 
+**Reranker providers.** The reranker reorders the over-fetched candidate pool on natural-language queries; three providers are available (`--rerank-provider`):
+
+- **`generative`** (default) — a local LLM judge (Ollama 7B). The strongest reranker in our benchmarks (agent-style semantic rank-1 0.19 → 0.42 across the core suites; no symbolic regression), but it needs a running model and its output is non-deterministic.
+- **`cross-encoder`** — a local MS-MARCO cross-encoder (`Xenova/ms-marco-MiniLM-L-6-v2`, via the optional `@huggingface/transformers`). It scores each (query, candidate) pair and sorts. **Air-gapped, deterministic, and fast** (no Ollama/daemon; the model downloads once). It captures part of the lift — agent-style semantic rank-1 0.19 → 0.26, and notably Go (gin) 0.20 → 0.40 and Python (fastapi) 0.14 → 0.29 — but less than the 7B judge, and like all rerankers it is mixed on JavaScript. Pick it when you want a reranker without an LLM in the loop. Measure on your repo: `npm run test:eval -- --rerank --rerank-provider cross-encoder`.
+- **`late-interaction`** (B4) — a **ColBERT-style multi-vector MaxSim** reranker. It encodes the query into several vectors (the whole query + content sub-units, via the same local embedder) and scores `Σ_qi max_dj cos(qi, dj)` against each candidate's stored document sub-vectors — **no storage blow-up** (it reuses the base/summary/window vectors `--embeddings` already writes), air-gapped, deterministic, parity-safe. **Requires `--embeddings`** (a no-op without it). Measured at production retrieval depth: **helps Go** (gin semantic rank-1 0.00 → 0.40, overall 0.68 → 0.77, no symbolic regression) and **neutral on JavaScript** (express unchanged) — the "helps Go/Python" half of the reranker profile without the JS regression. Approximates true token-level ColBERT with a sentence embedder. Measure on your repo: `npm run test:eval -- --embeddings --rerank --rerank-provider late-interaction`.
+
 ### All CLI flags
 
 | Flag | Default | Effect |
@@ -211,7 +228,19 @@ For most repos, the default (lexical + stemming, no embeddings) is the right sta
 | `--enrich-model <model>` | `qwen2.5-coder:1.5b` | Model used for enrichment. |
 | `--enrich-max <n>` | 500 | Cap on new LLM calls per index run. |
 | `--enrich-concurrency <n>` | 4 | Parallel Ollama requests during enrichment. |
-| `--rerank` | off | Enable the LLM reranker (one call per NL query). |
+| `--rerank` | off | Enable the reranker (reorders the over-fetched pool on NL queries). |
+| `--rerank-provider <generative\|cross-encoder\|late-interaction>` | `generative` | `generative` = local LLM judge; `cross-encoder` = local air-gapped MS-MARCO cross-encoder (optional `@huggingface/transformers`, no Ollama); `late-interaction` = ColBERT-style multi-vector MaxSim over the stored doc vectors (needs `--embeddings`; air-gapped, deterministic, no storage blow-up; measured helps-Go / neutral-JS at production depth). |
+| `--interprocedural` | off | Index-time inter-procedural receiver-type fixpoint: propagate return types along factory call chains so multi-hop receivers resolve in `get_call_graph` / `find_references`. Air-gapped, deterministic; default index byte-identical; search ranking unaffected. |
+| `--symbol-graph` | off | Persist a resolved chunk→chunk symbol graph (edges with kind + confidence) at index time, exposed via `getEdges`. `findCallers`/`findReferers` read it (identical sets, fall back to a scan). Also computes symbol-level centrality (confidence-weighted PageRank over the edges), surfaced by `explain_symbol` and `get_repo_map`. Air-gapped, deterministic; default index byte-identical; search ranking unaffected. |
+| `--taint` | off | Precompute and serialize the taint flow set (C2) at index time, so `trace_taint` / `find_tainted_sinks` answer instantly instead of walking the call graph per query. Computed against the symbol-graph edges when `--symbol-graph` is on (cross-function precision), else `chunk.calls`. Both backends serve byte-identical flows; default index byte-identical; air-gapped. |
+| `--ranker <rrf\|learned>` | `rrf` | Search ranker (D3). `rrf` (default) = the RRF + boost-ladder fusion. `learned` = an opt-in, zero-dependency post-fusion linear re-rank over the RRF score + symbol centrality + resolved/SCIP in-degree + git (best paired with `--symbol-graph`). **Measured ≈neutral on the benchmark** — RRF is the default; the learned ranker is provided for users to retrain on their own repo (`bench/train-ranker.mjs`). Default path byte-identical. |
+| `--learned-sparse` | off | Learn a corpus co-occurrence (PMI) association model (B3) at index time and serialize it, adding a **learned-sparse vocabulary-expansion** channel: NL queries expand into a weighted term set (literal terms + learned associates) fused via RRF, to close lexical-gap misses stemming can't. Zero new dependency, air-gapped, NL-asymmetric (symbolic lookups byte-identical), parity-safe. **Measured net-neutral on the strict benchmark** (does not beat lexical — like BM25F/AST); shipped opt-in for repos with genuine query/code vocabulary mismatch. Default index byte-identical. |
+| `--resolver <heuristic\|precise\|scip>` | `heuristic` | Resolver provider for the symbol graph. `precise` lifts provably-unambiguous edges (sole definition, or a type-pinned receiver) from `high` to a `resolved` tier. `scip` ingests a locally-generated SCIP index (`--scip-index`) and resolves edges by *real cross-file bindings* — promoting confirmed edges to `resolved` **and suppressing the wrong-target fan-out** an ambiguous same-name reference would otherwise emit, **and** adding a precise cross-file **`resolved`-tier** dimension to `find_references` (disambiguates same-named symbols, recovers references the name heuristics miss). Both power `impact_of_edit(precision: 'strict')`. Only meaningful with `--symbol-graph`. |
+| `--scip-index <path>` | — | Path to a SCIP index generated locally by your own toolchain (`scip-typescript`, `scip-python`, `scip-java`, `rust-analyzer --scip`), consumed by `--resolver scip`. Air-gapped (a local file read — sealed-compatible). Files the index doesn't cover fall back to heuristic confidence (never worse); coverage is printed at index time. Accepts the `.scip` protobuf or a SCIP-shaped JSON. |
+| `--sealed [strict\|local]` | off | **Sealed mode** — air-gapped *enforced and verifiable*. `strict` = zero network egress (lexical-only); `local` = loopback only (local LLM/embedders OK, nothing off-box). Fail-closed: refuses to start if any enabled feature would egress beyond the tier, and installs a deny-by-default runtime egress guard. Bare `--sealed` = `strict`. |
+| `--attest` | — | Print the deterministic sealed-mode manifest (tier, providers, egress posture) and exit — an auditor/CI artifact. Add `--sign-key <path>` to print a **cryptographically signed** envelope instead (Ed25519/RSA/EC via `node:crypto`; air-gapped). |
+| `--gen-attestation-key <prefix>` | — | Write an Ed25519 attestation keypair (`<prefix>.key` private, `<prefix>.pub` public) and exit. |
+| `--verify-attestation <file> --pub-key <path>` | — | Verify a signed attestation's signature and report whether it still matches the current effective config (policy drift → non-zero exit). |
 | `--no-git-signals` | (signals on) | Skip collecting local git churn/recency/co-change. |
 | `--git-rank-boost <0..1>` | 0 | Opt-in weight for git recency/churn in ranking (0 = ranking unchanged). |
 | `--llm-provider <ollama\|mlx>` | `ollama` | LLM backend for enrichment, reranking, and HyDE. `mlx` routes calls to a local `mlx_lm.server`. |
@@ -230,8 +259,18 @@ For most repos, the default (lexical + stemming, no embeddings) is the right sta
 | `INDEXER_MLX_BATCH_SIZE` | 32 | Texts per batch sent to the MLX subprocess (raise on large unified memory). |
 | `INDEXER_STORAGE` | `auto` | `auto` \| `memory` \| `sqlite`. |
 | `ENRICH_MODEL` | (unset) | Naming a model enables enrichment and selects it. |
-| `RERANK_MODEL` | (unset) | Naming a model enables the reranker and selects it. |
+| `RERANK_MODEL` | (unset) | Naming a model enables the (generative) reranker and selects it. |
+| `RERANK_PROVIDER` | `generative` | `generative` (LLM judge), `cross-encoder` (local air-gapped), or `late-interaction` (ColBERT-style MaxSim, needs embeddings); setting it enables reranking. |
+| `RERANK_CROSS_ENCODER_MODEL` | `Xenova/ms-marco-MiniLM-L-6-v2` | Cross-encoder model id (downloaded on first use). |
 | `INDEXER_GIT_SIGNALS` | (on) | Set to `off` to skip git-signal collection. |
+| `INDEXER_INTERPROCEDURAL` | (off) | `on` enables the index-time inter-procedural receiver-type fixpoint (`--interprocedural`). |
+| `INDEXER_SYMBOL_GRAPH` | (off) | `on` builds the persistent resolved symbol graph (`--symbol-graph`). |
+| `INDEXER_TAINT` | (off) | `on` precomputes + serializes the taint flow set at index time (`--taint`). |
+| `INDEXER_RANKER` | `rrf` | `learned` enables the opt-in post-fusion learned re-rank (`--ranker`). |
+| `INDEXER_LEARNED_SPARSE` | (off) | `on` learns + serializes the corpus association model for the learned-sparse expansion channel (`--learned-sparse`). |
+| `INDEXER_RESOLVER` | `heuristic` | `precise` enables the precise resolver; `scip` enables the SCIP cross-file resolver (`resolved` edge tier) for the symbol graph (`--resolver`). |
+| `INDEXER_SCIP_INDEX` | (unset) | Path to a locally-generated SCIP index for `--resolver scip` (`--scip-index`). |
+| `INDEXER_SEALED` | (off) | `strict` (or `on`) / `local` enables sealed mode (`--sealed`): fail-closed validation + a runtime egress guard. |
 | `INDEXER_GIT_RANK_BOOST` | 0 | Opt-in git recency/churn ranking weight (0..1). |
 | `INDEXER_LLM_PROVIDER` | `ollama` | LLM backend for enrichment, reranking, and HyDE: `ollama` or `mlx`. |
 | `INDEXER_MLX_LM_HOST` | `http://localhost:8080` | Endpoint for the `mlx_lm.server` when `INDEXER_LLM_PROVIDER=mlx`. |
@@ -257,6 +296,8 @@ Set the backend with `--embed-provider` (or `INDEXER_EMBED_PROVIDER`). `mlx` is
 
 The index records which provider/model built it (in the `code-index.embeddings.bin.meta.json` sidecar) and queries with the same one, so vectors never get mixed across models. Switching providers or the MLX model between builds is detected and triggers a clean re-embed.
 
+**Code-specialized embedding models.** The default `nomic-embed-text` is a general-purpose embedder. Models trained on code — `qwen3-embedding`, `nomic-embed-code`, `jina-embeddings-v2-base-code` — embed code semantics more faithfully and can lift agent-style (natural-language) recall. Select one with `--embed-model <name>` (Ollama); it is stamped into the index meta and queried with the same model so vectors never get mixed. **Measure before adopting** — in our benchmarks `qwen3-embedding` lifted Go (gin) semantic rank-1 0.20 → 0.40 but was neutral on Python (django) and JavaScript (express), and it indexes substantially slower than `nomic-embed-text`. Run `npm run test:eval -- --embeddings` on your own repo to confirm the trade-off. We also evaluated *re-weighting the vector channel upward* for these stronger embedders and found **no measurable recall@5 gain** (it regressed rank-1/symbolic at higher weights) — the existing default weighting already extracts the benefit, so there is no separate "code weight" knob. `jina-embeddings-v2-base-code` remains opt-in only: it helped some fixtures, regressed others, and indexes far slower, so it is never a default.
+
 **macOS Apple Silicon (recommended):**
 
 ```bash
@@ -275,7 +316,7 @@ Every number here is produced by the eval harness on cold, isolated builds — n
 What the measurements say, across 18 real-world fixtures spanning every supported language:
 
 - **The zero-dependency lexical default is the right starting point.** It wins the held-out metric outright on 2 fixtures, and 6 more need only a cheap in-process embedder — so **8 of 18 run with no Ollama and no network**. Most repos never need more.
-- **Symbolic lookups are strong** (mean rank-1 ≈ 0.70). Behavioural, natural-language queries are harder (≈ 0.30 on the default path) — that's where the optional embedding and reranker channels earn their keep.
+- **Symbolic lookups are strong** (mean rank-1 ≈ 0.70). Behavioural, natural-language queries are harder (≈ 0.30 overall (held-out semantic rank-1 0.40 with stemming)) — that's where the optional embedding and reranker channels earn their keep.
 - **Optional features are measured, not assumed.** Dense embeddings lift recall on larger repos; the LLM reranker is language- and repo-dependent (it lifts 8 fixtures but taxes JavaScript and Spring); enrichment helps only where proven (just rust). Setup surfaces each trade-off before you enable it.
 - **Backend parity:** the in-memory and SQLite backends return byte-identical top-5 on all 18 fixtures (gated by `test/sqlite.mjs`).
 
@@ -288,14 +329,16 @@ Per-fixture best configs, 3× spreads, and copy-paste enable flags live in **[do
 | Capability | Strong | Limited |
 |---|---|---|
 | **Call graph** (callers/callees) | resolves on every supported language | Java/Spring is class-granular; SCSS effectively none |
-| **Caller precision** | receiver-aware: TS/JS, Python, C#, Swift, PHP | name-only: Go, Rust, Kotlin, Ruby, Bash, C |
+| **Caller precision** | receiver-aware: TS/JS, Python, C#, Swift, PHP, Java (call-site level — but its call graph is class-granular) | name-only: Go, Rust, Kotlin, Ruby, Bash, C |
 | **Typed `find_references`** | precise: TS/JS, Python · field-precise: C# | heuristic: Java/PHP/Kotlin/Swift/Rust/Go/C · empty: Ruby, Bash, SCSS, dynamic JS/Python |
 
 AST chunking and lexical search cover **every** supported language; only the typed cross-reference channel narrows for dynamic ones.
 
+**Multi-hop receivers (`--interprocedural`).** Caller precision relies on resolving a call's receiver type. Intra-procedurally, graph-indexer already resolves `const r = makeRepo(); r.save()` one hop (reading `makeRepo`'s recorded return type). The opt-in `--interprocedural` flag adds an index-time fixpoint that propagates return types *along factory call chains*, so a receiver whose type comes from a multi-hop or unannotated factory (`makeRepoIndirect()` → `makeRepo()` → `new OrderRepo()`) still resolves to its concrete class — promoting those callers from *name-only* to *high-confidence* in `get_call_graph` / `find_references`. It is air-gapped and deterministic, the result is serialized into the index (both backends identical), and it leaves search ranking and the default index byte-identical. Note: the watch daemon updates one file at a time and does not re-run the whole-program pass, so cross-file chains refresh on the next full `idx-index` (degrading to single-hop until then, never worse).
+
 ### Where it's weakest (honestly)
 
-- Behavioural, natural-language recall on the default path (rank-1 ≈ 0.30) — closing it needs the embedding/reranker channel, not lexical tuning.
+- Behavioural, natural-language recall on the default path (rank-1 ≈ 0.30 overall; held-out semantic rank-1 0.40 — the embedding/reranker channel closes it further) — closing it needs the embedding/reranker channel, not lexical tuning.
 - The hardest fixtures stay below 0.65 held-out success@5 even with the full stack (rails 0.50, rust 0.61).
 - Java/Spring `get_call_graph` reports at class granularity (the god-class split only fires ≥200 lines); SCSS has no meaningful call graph.
 - LLM enrichment without reranking regresses precision — enable it only paired with `--rerank`.

package/SECURITY.md

@@ -36,6 +36,16 @@ shaped by a few deliberate choices:
   from the local cache. Your source code is never sent anywhere — only model weights
   are fetched. For strictly air-gapped installs, set `embedProvider` to `"ollama"` or
   `"off"`, or pre-populate the model cache on a connected machine.
+- **Sealed mode (opt-in, fail-closed enforcement).** For regulated or strictly
+  air-gapped installs, `--sealed strict` (`INDEXER_SEALED`) enforces **zero** network
+  egress (lexical-only), and `--sealed local` permits **loopback only** (a local
+  Ollama/MLX on this box is allowed, nothing leaves it). It is *fail-closed*: the build
+  refuses to start if any enabled feature (embeddings/enrichment/rerank/HyDE) would
+  egress beyond the tier, and it installs a **deny-by-default runtime egress guard** on
+  the in-process network paths (`net`/`tls` sockets, `http(s)`, `fetch`) so even an
+  accidental call is blocked — turning "we don't call out" into "we *can't*."
+  `idx-index --attest` prints a deterministic attestation manifest (optionally
+  Ed25519/RSA-**signed** and CI-verifiable) of the egress posture. See `seal.mjs`.
 - **No code execution.** Source files are parsed into ASTs with Tree-sitter. The
   indexer never imports, evaluates, or runs the code it indexes. The one subprocess
   it spawns is a local, read-only `git log` (see "git signals" below) — never the
@@ -57,6 +67,13 @@ shaped by a few deliberate choices:
   sensitivity as the repository itself and do not commit or share them.
 - **MCP transport.** The server communicates over stdio with the local MCP client
   (your IDE/agent). It does not open a network socket.
+- **Taint analysis is advisory, not a guarantee.** The opt-in `trace_taint` /
+  `find_tainted_sinks` MCP tools statically trace untrusted sources to dangerous sinks
+  over the call graph using pure regex catalogs + graph traversal (no model, no network,
+  read-only). They are a **finder, not a verifier**: they favour precision and miss flows
+  through dynamic dispatch, reflection, ORM/query-builder indirection, and untyped
+  collections — **"0 findings" is not proof of safety.** Use them for orientation, not as
+  a security gate.
 
 ## Operational guidance
 

package/colbert.mjs

@@ -0,0 +1,168 @@
+/**
+ * @file colbert.mjs
+ * @description B4 — ColBERT-style LATE-INTERACTION reranker (multi-vector MaxSim). A third,
+ *              opt-in reranker provider (rerank.provider === 'late-interaction'), sibling to the
+ *              generative judge and the cross-encoder (B2). Where a single-vector dense channel
+ *              pools the query and the document each into ONE vector (losing which part matched
+ *              where), late interaction keeps MULTIPLE vectors per side and scores them with MaxSim:
+ *
+ *                  score(q, d) = Σ_{qi}  max_{dj}  cos(qi, dj)
+ *
+ *              i.e. every query sub-vector finds its best-matching document sub-vector and the hits
+ *              sum — the compositional-query win ColBERT is known for. It reuses the document
+ *              sub-vectors the engine ALREADY stores (the base + `|s` summary + `|wN` window vectors
+ *              of each chunk), so there is **no storage blow-up** — the canonical ColBERT cost. It is
+ *              deployed as a RERANKER over the over-fetched candidate pool (the standard
+ *              retrieve-then-late-interact pattern), so it is a post-retrieval re-order — the default
+ *              ranking is untouched and parity is preserved (both backends read the SAME bin → the
+ *              SAME doc vectors → the SAME MaxSim → the SAME order).
+ *
+ *              AIR-GAPPED / HONEST SCOPE: the query multi-vectors are produced by the SAME local
+ *              embedder the dense channel already uses (no new model, no network). A true ColBERT
+ *              uses a token-level CONTEXTUAL encoder; a general sentence embedder over query
+ *              sub-units only APPROXIMATES that — so this is "late interaction over the existing
+ *              encoder," with a real token-level ColBERT model a clean future drop-in behind
+ *              `encodeMultiVector`. Requires --embeddings (the doc vectors + the embedder); a no-op
+ *              (returns the original order) when either is absent.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import { collectVectorsByKey } from './engine/binary.mjs';
+import { embeddingKeyFor, SUMMARY_VEC_SUFFIX, WINDOW_VEC_SUFFIX, EMBEDDING_MAX_WINDOWS } from './search-core.mjs';
+
+// Query sub-unit extraction is intentionally light (no stemming — surface forms, like the dense
+// channel). A tiny stopword guard keeps function words from spending a query vector slot.
+const STOP = new Set([
+    'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'for', 'on', 'with', 'at', 'by', 'from',
+    'that', 'this', 'is', 'are', 'was', 'were', 'be', 'how', 'what', 'when', 'where', 'which',
+    'who', 'why', 'does', 'do', 'it', 'its', 'into', 'if', 'then', 'there', 'all', 'any',
+]);
+
+/** Cosine similarity of two equal-length vectors (0 when either is degenerate). */
+export function cosine(a, b) {
+    if (!a || !b || a.length !== b.length) return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+    if (na === 0 || nb === 0) return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+/**
+ * MaxSim late-interaction score: Σ over query vectors of the max cosine to any document vector.
+ * Order-independent (a sum of maxes) → no parity dependence on vector ordering.
+ * @param {Float32Array[]} qVecs  query sub-vectors
+ * @param {Float32Array[]} dVecs  document sub-vectors
+ * @returns {number}  0 when either side is empty
+ */
+export function maxSimScore(qVecs, dVecs) {
+    if (!qVecs?.length || !dVecs?.length) return 0;
+    let total = 0;
+    for (const q of qVecs) {
+        let best = -Infinity;
+        for (const d of dVecs) { const s = cosine(q, d); if (s > best) best = s; }
+        if (best > -Infinity) total += best;
+    }
+    return total;
+}
+
+/** The embedding keys that hold a chunk's stored sub-vectors (base + summary + windows). */
+function chunkVectorKeys(chunk) {
+    const vecKey = embeddingKeyFor(chunk);
+    const keys = [vecKey, chunk.content_hash, vecKey + SUMMARY_VEC_SUFFIX];
+    for (let i = 1; i < EMBEDDING_MAX_WINDOWS; i++) keys.push(vecKey + WINDOW_VEC_SUFFIX + i);
+    return { vecKey, keys };
+}
+
+/**
+ * Load each chunk's stored sub-vectors from the shared `.embeddings.bin` in a SINGLE pass (one bin
+ * read per rerank, not per candidate). Identical for both backends (same file, same keys) →
+ * parity-by-construction. @returns {Map<chunkId, Float32Array[]>}
+ */
+export function loadChunkVectors(binPath, chunks) {
+    const meta = new Map();        // chunkId → { vecKey, hash }
+    const allKeys = new Set();
+    for (const c of chunks) {
+        if (!c || !c.content_hash) { meta.set(c?.id, null); continue; }
+        const { vecKey, keys } = chunkVectorKeys(c);
+        meta.set(c.id, { vecKey, hash: c.content_hash });
+        for (const k of keys) allKeys.add(k);
+    }
+    const found = collectVectorsByKey(binPath, allKeys);
+    const out = new Map();
+    for (const [id, m] of meta) {
+        if (!m) { out.set(id, []); continue; }
+        const vecs = [];
+        const base = found.get(m.vecKey) || found.get(m.hash);     // deterministic order: base, summary, windows
+        if (base) vecs.push(base);
+        const s = found.get(m.vecKey + SUMMARY_VEC_SUFFIX); if (s) vecs.push(s);
+        for (let i = 1; i < EMBEDDING_MAX_WINDOWS; i++) { const w = found.get(m.vecKey + WINDOW_VEC_SUFFIX + i); if (w) vecs.push(w); }
+        out.set(id, vecs);
+    }
+    return out;
+}
+
+/**
+ * Encode a query into MULTIPLE vectors (the whole query plus its content sub-units) with the SAME
+ * local embedder the dense channel uses. Best-effort: returns [] on any failure / no embedder.
+ * @param {{embedDocuments?:Function, embedQuery?:Function}} embedder
+ * @param {string} text
+ * @param {object} [opts]
+ * @returns {Promise<Float32Array[]>}
+ */
+export async function encodeMultiVector(embedder, text, { maxVecs = 8 } = {}) {
+    if (!embedder || typeof embedder.embedDocuments !== 'function') return [];
+    const words = String(text).toLowerCase().split(/[\s\W_]+/).filter(Boolean);
+    const units = [];
+    const seen = new Set();
+    for (const w of words) {
+        if (w.length < 3 || STOP.has(w) || seen.has(w)) continue;
+        seen.add(w); units.push(w);
+        if (units.length >= maxVecs - 1) break;
+    }
+    units.unshift(String(text));        // the holistic query vector always leads
+    let vecs;
+    try { vecs = await embedder.embedDocuments(units); }
+    catch { return []; }
+    return (vecs || []).filter(v => v && v.length).map(v => v instanceof Float32Array ? v : new Float32Array(v));
+}
+
+/**
+ * Late-interaction RERANK of the over-fetched pool. Re-orders the top-`topM` by MaxSim of the query
+ * multi-vectors against each candidate's stored doc sub-vectors; the tail is preserved. Best-effort
+ * and never throws: any shortfall (no embedder, <2 candidates with vectors, empty query vectors)
+ * returns the ORIGINAL order, so the channel can only help, never corrupt. Never mutates `r.score`
+ * (protects the downstream git-boost / formatting), exactly like rerankCrossEncoder.
+ *
+ * @param {Array<{chunk:object, score:number}>} results
+ * @param {object} opts
+ * @param {Float32Array[]} opts.qVecs    query multi-vectors (from encodeMultiVector)
+ * @param {string} opts.binPath          the `.embeddings.bin` path (db.embeddingBinPath())
+ * @param {number} [opts.topM]
+ * @returns {Array}
+ */
+export function rerankLateInteraction(results, { qVecs, binPath, topM = 12 } = {}) {
+    const head = results.slice(0, topM);
+    if (head.length < 2 || !qVecs?.length || !binPath) return results;
+    const vecsById = loadChunkVectors(binPath, head.map(r => r.chunk));
+    const scored = head.map((r, i) => {
+        const dVecs = vecsById.get(r.chunk.id) || [];
+        return { i, id: r.chunk.id, s: dVecs.length ? maxSimScore(qVecs, dVecs) : NaN };
+    });
+    // "Can only help, never corrupt": treat no-signal as a shortfall. Re-order only when at least two
+    // candidates carry a FINITE and DISTINCT MaxSim — so all-zero scores (e.g. a dim mismatch making
+    // every cosine 0) or undifferentiated ties fall through to the original order instead of being
+    // scrambled into id-lexicographic order by the tie-break.
+    const finite = scored.filter(x => Number.isFinite(x.s));
+    if (finite.length < 2 || new Set(finite.map(x => x.s)).size < 2) return results;
+    const order = scored
+        // finite MaxSim first (desc); candidates without vectors sink but keep a stable id order
+        .sort((a, b) => {
+            const af = Number.isFinite(a.s), bf = Number.isFinite(b.s);
+            if (af && bf) return (b.s - a.s) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+            if (af) return -1; if (bf) return 1;
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        })
+        .map(x => x.i);
+    return [...order.map(i => head[i]), ...results.slice(topM)];
+}