@maxgfr/codeindex 2.11.1 → 2.12.0

package/docs/MIGRATION.md

@@ -119,7 +119,8 @@ note only) — so wiring it on is safe before an asset exists.
 | **ultrasec** | walker + gitignore + scope + symlink guard | `scanRepo` (`scope`, `gitignore` — its own semantics, ported here) |
 | | per-language defs/imports/calls extraction | `extractCode` (`symbols`/`refs`/`calls`) |
 | | `resolveImport` | `resolveImport` |
-| | `buildGraph` (import+call edges, symbolDefs, callersBySymbol, enclosingSymbol) | `buildGraph` + `resolveCallEdges` + `buildCallerIndex` + `enclosingSymbol` |
+| | `buildGraph` (import+call edges, symbolDefs) | `buildGraph` + `resolveCallEdges` |
+| | `callersBySymbol`, `enclosingSymbol` (raw-recall taint-BFS input) | `buildRawCallerIndex` (issue #8) — every name-matched call site keyed by the raw callee name, no def resolution or gating, `enclosingSymbol` computed per site. `buildCallerIndex` is **NOT** a substitute here: it is def-resolved and gated (language-family filter, JS/TS import gate, same-file self-declaration skip) and will silently drop sites a recall consumer needs. Both are bounded by `FileRecord.calls`'s per-file 512-call cap (dedup by name+line) — a file with more raw call sites than that loses sites upstream of either function. |
 | | keeps | taint source→sink enumeration, external scanners, EPSS/KEV/CVSS, SARIF |
 
 ## Golden-diff adjudication (every migration)

package/docs/SEMANTIC.md

@@ -0,0 +1,242 @@
+# Deterministic static-embedding tier (semantic search)
+
+codeindex's default search is keyless BM25 lexical ranking (see `search`). The
+**semantic tier** (v2.10.0) adds embedding-based retrieval that is still
+**keyless, zero-dependency, and byte-deterministic** — the same doctrine as the
+rest of the engine, and the reason it does *not* use onnxruntime / transformers.js
+(those are threaded and dequantize int8 to fp32 for matmul, so they are never
+byte-stable across architectures).
+
+It is **strictly opt-in by asset presence**, exactly like the tree-sitter
+grammar tier: with no model on disk the engine silently stays lexical.
+
+## Why a *static* embedding model
+
+A static embedding (model2vec / potion style) is a plain lookup table:
+`token → row vector`. There is **no neural forward pass** — "inference" is:
+
+```
+tokenize → gather rows → mean-pool → L2-normalize → int8-quantize
+```
+
+Every step is pure JS and chosen to be byte-identical everywhere:
+
+| step | how determinism is guaranteed |
+|---|---|
+| tokenize | `foldText` (NFKD + strip combining marks) → camelCase/ACRONYM split → lowercase → split on non-alphanumeric |
+| wordpiece | greedy longest-match against the vocab, BERT-style `##` continuations; an unsplittable word → the `[UNK]` row |
+| gather | model rows widen float→double exactly |
+| mean-pool | IEEE-754 double add/div in a fixed token order |
+| L2-norm | division by `sqrt(Σv²)` — `sqrt` is correctly-rounded per IEEE-754 |
+| quantize | `unit × 127`, **round-half-to-even** (not `Math.round`), clamp to `[-127,127]` → int8 |
+
+Ranking is a **pure integer dot product** of int8 vectors. Because the fixed
+`1/127` scale is shared by every vector, for a given query the integer dot
+`Σ q·c` is monotonic with the cosine estimate — no per-vector float scale is
+stored or multiplied, so nothing about ranking can drift between platforms.
+
+**Key insight:** the corpus *and* the query are encoded by the *same* JS encoder,
+so self-consistency is all that is required — fidelity to the original HF
+tokenizer is not. The JS tokenizer deliberately differs from the Python
+reference; that gap is assumed and harmless.
+
+## Activation (opt-in by asset)
+
+Resolution order (`resolveEmbedModelDir`):
+
+1. `CODEINDEX_EMBED_DIR` (explicit override — wins outright)
+2. `<repo>/.codeindex/models/`
+3. `<cwd>/.codeindex/models/`
+
+A directory "has a model" when it contains `model.json`. Nothing found →
+`undefined` → silent lexical degradation. **Models are never in the npm
+tarball** (`package.json` `files` is unchanged; the pack-smoke test asserts no
+`model.json` / `*.safetensors` / `embeddings.bin` ships).
+
+### `model.json` shape
+
+```json
+{
+  "modelId": "…",
+  "dim": 256,
+  "unk": "[UNK]",
+  "vocab": ["[UNK]", "auth", "##token", "..."],
+  "weights": [[0.0, ...], [1.0, ...], ...]
+}
+```
+
+`vocab[i]` is the token whose row is `weights[i]` (length `dim`). Human-authorable
+JSON so a tiny fixture is committable; a real `pull`ed model uses the same shape
+at scale.
+
+### The official asset
+
+`codeindex embed pull` (no env) fetches the published **`embed-model-v1`** GitHub
+release: a conversion of [`minishlab/potion-base-8M`](https://huggingface.co/minishlab/potion-base-8M)
+(revision `bf8b0566…`, **MIT**) — 256-dim, a 27 559-token WordPiece vocab, int8
+rows at one global scale. The download is **sha256-verified** against
+`EMBED_ASSET_SHA256` (`src/embed/model.ts`) before it is written; a mismatch
+fails the pull and writes nothing. The asset is **never** committed to git or
+shipped in the npm tarball — it lives only in the release. Reproduce it
+byte-for-byte with the pinned toolchain in [`scripts/embed-asset/`](../scripts/embed-asset/).
+
+## CLI
+
+```sh
+# Effective mode (none/static/endpoint), model, EMBED_VERSION, endpoint + its
+# reachability (JSON). Precedence: endpoint > static model.
+codeindex embed status --repo <dir>
+
+# Fetch the official static-embedding asset (published as the `embed-model-v1`
+# GitHub release) into CODEINDEX_EMBED_DIR (or <repo>/.codeindex/models/). The
+# built-in default download is sha256-verified before it is written; set
+# CODEINDEX_EMBED_URL to fetch a custom/mirrored model.json instead (un-verified).
+codeindex embed pull --repo <dir>
+
+# Build embeddings.bin from the repo into --out <dir> (static tier only).
+codeindex embed build --repo <dir> --out <dir>
+
+# Print (or --run) the docker command that starts the rich-tier embedding server.
+codeindex embed serve            # prints the one-liner
+codeindex embed serve --run      # runs it (needs docker)
+
+# Search: RRF-fuse an embedding tier + lexical. Degrades to lexical (exit 0)
+# when no tier is available/reachable.
+codeindex search "http client retry" --repo <dir> --semantic
+```
+
+`codeindex index --out <dir>` additionally writes `embeddings.bin` next to
+`graph.json` **iff** a model is present.
+
+## Artifact: `embeddings.bin`
+
+```
+"CIE1"                     4-byte ASCII magic
+uint32 LE header length
+UTF-8 JSON header          { embedVersion, modelId, dim, count, records:[{file,symbol,line}] }
+int8 body                  count × dim signed bytes (row-major)
+```
+
+The header carries **no absolute path and no timestamp**; records follow scan
+order (files sorted by `rel`, symbols in declaration order). Two builds of an
+unchanged repo produce byte-identical `embeddings.bin`. A dedicated
+`EMBED_VERSION` (independent of `SCHEMA_VERSION`) plus `modelId` + `dim` in the
+header invalidate a stale or foreign artifact.
+
+Granularity is **per-symbol** (name + signature + file summary + path segments),
+with a **per-file** fallback record for symbol-less files (docs, config) so
+every file with content is represented.
+
+## Fusion
+
+Semantic and lexical rankings live on incomparable scales (BM25 score vs integer
+dot product), so `searchSemantic` fuses them by **rank** via the shared `rrf`
+helper (k=60) — never a linear score blend. A `SemanticSearchResult` extends the
+lexical `SearchResult` additively with `semanticSymbol` (the corpus symbol whose
+embedding was closest for that file).
+
+## Degradation matrix
+
+| present | behavior |
+|---|---|
+| nothing | BM25 lexical |
+| + fuzzy | BM25 + trigram fallback for `df==0` terms (v2.9.0) |
+| + model asset | RRF-fused deterministic static semantic search |
+| + HTTP endpoint (`CODEINDEX_EMBED_ENDPOINT`) | rich tier — **wins over a static model** (v2.11.0) |
+| `--semantic`, nothing available | lexical + stderr note, **exit 0** |
+| endpoint set but unreachable/timeout | lexical + stderr note, **exit 0** (never falls back to the static model) |
+
+## Library
+
+```ts
+import {
+  resolveEmbedModelDir, loadEmbedModel,
+  buildEmbeddingIndex, serializeEmbeddings, deserializeEmbeddings,
+  searchSemantic, encode, EMBED_VERSION,
+} from "@maxgfr/codeindex";
+
+const model = loadEmbedModel(resolveEmbedModelDir("/repo"));
+if (model) {
+  const scan = scanRepo("/repo");
+  const index = buildEmbeddingIndex(scan, model);        // deterministic
+  const results = searchSemantic(scan, "http retry", index, { model });
+}
+```
+
+`searchSemantic(scan, query, index, opts)` with no `opts.model` (or no index)
+returns the pure lexical ranking — the same silent degradation the CLI uses.
+
+## The rich tier: containerized HTTP embedding endpoint (v2.11.0)
+
+The **rich tier** lets the engine consume a real neural embedding model (e.g.
+all-MiniLM-L6-v2) served by a local container, instead of the static lookup
+table. It is opt-in via one env var:
+
+```sh
+CODEINDEX_EMBED_ENDPOINT=http://localhost:8756 \
+  codeindex search "auth token" --repo . --semantic
+```
+
+### Precedence
+
+`endpoint > static model > none`. Setting `CODEINDEX_EMBED_ENDPOINT` is an
+**explicit** user intent, so it wins over any local `model.json`. `embed status`
+reports the effective `mode`. If the endpoint is defined but
+unreachable/times-out/malformed, the search degrades straight to **lexical**
+(stderr note, exit 0) — it does **not** silently fall back to the static model.
+
+### How the float vectors join the deterministic pipeline
+
+The engine POSTs corpus and query texts to the endpoint, receives **float**
+vectors, then runs them through the **exact same** tail as the static tier —
+`quantize()` in `encode.ts`: L2-normalize → int8 at the fixed `1/127` scale
+(round-half-to-even, clamp). Ranking stays a pure integer dot product. So the
+only tier-specific step is the encoder; fusion and ranking are shared code.
+
+Corpus embeddings for the endpoint tier are built **at search time**
+(`buildEndpointIndex`) and are **never serialized** to `embeddings.bin`: unlike
+the static tier, endpoint vectors are float and provider-dependent, so this tier
+is **deterministic per image digest**, not byte-golden. Pin the digest for
+reproducibility:
+
+```sh
+docker run -d -p 8756:8756 ghcr.io/maxgfr/codeindex-embed@sha256:<digest>
+```
+
+### HTTP protocol (implement your own server)
+
+`CODEINDEX_EMBED_ENDPOINT` is the server **base URL**. The client derives:
+
+| method + path | request | response |
+|---|---|---|
+| `POST {base}/embed` | `{ "texts": ["…", …] }` | `{ "vectors": [[…float…], …] }` (same order, one row per text) |
+| `GET {base}/healthz` | — | `200` (any body) when ready |
+
+Notes: any embedding dimension is accepted (the engine quantizes whatever it
+receives); vectors need not be pre-normalized (the engine L2-normalizes anyway);
+the request times out after `CODEINDEX_EMBED_TIMEOUT_MS` (default 30 000).
+`codeindex embed serve` prints/`--run`s the docker command for the official
+image; the **library never orchestrates docker** (that is CLI-only).
+
+The reference server is `docker/embed/` (transformers.js + all-MiniLM-L6-v2,
+model baked in at build, offline at run, non-root, `:8756`), published to
+`ghcr.io/maxgfr/codeindex-embed` by `.github/workflows/embed-image.yml`.
+
+### Library
+
+```ts
+import {
+  buildEndpointIndex, encodeQueryViaEndpoint, probeEndpoint,
+  searchSemantic, quantize,
+} from "@maxgfr/codeindex";
+
+if (await probeEndpoint("http://localhost:8756")) {
+  const scan = scanRepo("/repo");
+  const index = await buildEndpointIndex(scan);              // float → int8 corpus
+  const queryVec = await encodeQueryViaEndpoint("auth token");
+  const results = searchSemantic(scan, "auth token", index, { queryVec });
+}
+```
+
+`embedViaEndpoint(texts, opts)` is the low-level client (`{ texts }` →
+`{ vectors }`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "Self-contained, deterministic repo-indexing engine: walk + language detection + symbol/import extraction (tree-sitter AST with regex fallback) + import resolution + typed cross-file link-graph + analytics. Ships as a single zero-dependency engine.mjs that consumer tools vendor.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -23,7 +23,8 @@
     "scripts/cli.mjs",
     "scripts/grammars",
     "src",
-    "docs/MIGRATION.md"
+    "docs/MIGRATION.md",
+    "docs/SEMANTIC.md"
   ],
   "engines": {
     "node": ">=18"

package/scripts/engine.d.mts

@@ -1,6 +1,6 @@
-declare const ENGINE_VERSION = "2.11.1";
+declare const ENGINE_VERSION = "2.12.0";
 declare const SCHEMA_VERSION = 4;
-declare const EXTRACTOR_VERSION = 8;
+declare const EXTRACTOR_VERSION = 9;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
 type EdgeKind = "contains" | "doc-link" | "import" | "call" | "use" | "mention";
 type Tier = 0 | 1 | 2;
@@ -337,6 +337,14 @@ type CallerIndex = Map<string, CallerEntry>;
 declare function computeImportPairs(scan: RepoScan): Set<string>;
 declare function buildCallerIndex(scan: RepoScan, importPairs?: Set<string>, opts?: CallerIndexOptions): CallerIndex;
 declare function enclosingSymbol(scan: RepoScan, file: string, line: number): CodeSymbol | undefined;
+interface RawCallerSite {
+    file: string;
+    line: number;
+    receiver?: string;
+    enclosingSymbol?: CodeSymbol;
+}
+type RawCallerIndex = Map<string, RawCallerSite[]>;
+declare function buildRawCallerIndex(scan: RepoScan): RawCallerIndex;
 
 declare function symbolsOverview(scan: RepoScan, rel: string): CodeSymbol[];
 interface SymbolMatch extends CodeSymbol {
@@ -512,7 +520,11 @@ interface StaticEmbedModel {
 declare function resolveEmbedModelDir(repo?: string): string | undefined;
 declare function hasEmbedModel(repo?: string): boolean;
 declare function loadEmbedModel(dir?: string): StaticEmbedModel | undefined;
-declare function resolveEmbedPullUrl(): string | undefined;
+interface EmbedPullTarget {
+    url: string;
+    sha256?: string;
+}
+declare function resolveEmbedPullUrl(): EmbedPullTarget;
 
 declare function basicTokenize(text: string): string[];
 declare function wordpiece(word: string, model: StaticEmbedModel): number[];
@@ -693,4 +705,4 @@ declare function rrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): M
 
 declare function runCli(argv: string[]): Promise<void>;
 
-export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, wordpiece, writeMemory };
+export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractMarkdown, extractSymbols, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, wordpiece, writeMemory };

package/scripts/engine.mjs

@@ -14,9 +14,9 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.11.1";
+    ENGINE_VERSION = "2.12.0";
     SCHEMA_VERSION = 4;
-    EXTRACTOR_VERSION = 8;
+    EXTRACTOR_VERSION = 9;
   }
 });
 
@@ -737,8 +737,8 @@ function extractReexports(rel, content, localSymbols) {
   const out2 = [];
   const seen = /* @__PURE__ */ new Set();
   const lineAt = (idx) => content.slice(0, idx).split(/\r?\n/).length;
-  const localKindOf = /* @__PURE__ */ new Map();
-  for (const s of localSymbols) if (!localKindOf.has(s.name)) localKindOf.set(s.name, s.kind);
+  const localDeclOf = /* @__PURE__ */ new Map();
+  for (const s of localSymbols) if (!localDeclOf.has(s.name)) localDeclOf.set(s.name, s);
   const named = /export\s*\{([\s\S]*?)\}\s*(?:from\s*['"]([^'"]+)['"])?\s*;?/g;
   let m;
   while ((m = named.exec(content)) && out2.length < 60) {
@@ -750,12 +750,13 @@ function extractReexports(rel, content, localSymbols) {
       const name2 = as ? as[2] : p;
       if (!/^[A-Za-z_$][\w$]*$/.test(name2) || name2 === "default" || seen.has(name2)) continue;
       seen.add(name2);
-      const mirroredKind = !from ? localKindOf.get(orig) : void 0;
+      const decl = !from ? localDeclOf.get(orig) : void 0;
       out2.push({
         name: name2,
-        kind: mirroredKind ?? "reexport",
+        kind: decl?.kind ?? "reexport",
         file: rel,
-        line: lineAt(m.index),
+        line: decl ? decl.line : lineAt(m.index),
+        ...decl?.endLine !== void 0 ? { endLine: decl.endLine } : {},
         signature: from ? `export { ${name2} } from "${from}"` : `export { ${name2} }`,
         exported: true,
         lang
@@ -7731,8 +7732,11 @@ function buildCallerIndex(scan2, importPairs, opts = {}) {
 function enclosingSymbol(scan2, file, line) {
   const f = scan2.files.find((x) => x.rel === file);
   if (!f?.symbols.length) return void 0;
+  return enclosingAmong(f.symbols, line);
+}
+function enclosingAmong(symbols, line) {
   let best;
-  for (const s of f.symbols) {
+  for (const s of symbols) {
     if (REFERENCE_KINDS3.has(s.kind)) continue;
     if (s.line > line) continue;
     if (s.endLine !== void 0 && line > s.endLine) continue;
@@ -7742,6 +7746,29 @@ function enclosingSymbol(scan2, file, line) {
   }
   return best;
 }
+function buildRawCallerIndex(scan2) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const f of scan2.files) {
+    if (!f.calls?.length) continue;
+    const symbols = f.symbols.filter((s) => !REFERENCE_KINDS3.has(s.kind));
+    for (const c2 of f.calls) {
+      const site = { file: f.rel, line: c2.line };
+      if (c2.receiver !== void 0) site.receiver = c2.receiver;
+      const enc = enclosingAmong(symbols, c2.line);
+      if (enc) site.enclosingSymbol = enc;
+      let arr = byName.get(c2.name);
+      if (!arr) byName.set(c2.name, arr = []);
+      arr.push(site);
+    }
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const name2 of [...byName.keys()].sort(byStr)) {
+    const sites = byName.get(name2);
+    sites.sort((a, b) => byStr(a.file, b.file) || a.line - b.line);
+    index.set(name2, sites);
+  }
+  return index;
+}
 var REFERENCE_KINDS3;
 var init_callers = __esm({
   "src/callers.ts"() {
@@ -9374,6 +9401,7 @@ var init_bm25 = __esm({
 });
 
 // src/embed/model.ts
+import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
 import { join as join10 } from "path";
 function resolveEmbedModelDir(repo) {
@@ -9419,15 +9447,30 @@ function loadEmbedModel(dir) {
   return { modelId, dim, unk, unkId, vocabSize, vocab: vmap, weights: flat };
 }
 function resolveEmbedPullUrl() {
-  const url = process.env.CODEINDEX_EMBED_URL;
-  return url && url.trim() ? url.trim() : void 0;
+  const env = process.env.CODEINDEX_EMBED_URL;
+  if (env && env.trim()) return { url: env.trim() };
+  return { url: DEFAULT_EMBED_URL, sha256: EMBED_ASSET_SHA256 };
+}
+async function fetchEmbedModel(url, expectedSha256) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
+  const body2 = await res.text();
+  if (expectedSha256) {
+    const got = createHash2("sha256").update(body2).digest("hex");
+    if (got !== expectedSha256) {
+      throw new Error(`sha256 mismatch: expected ${expectedSha256}, got ${got}`);
+    }
+  }
+  return body2;
 }
-var EMBED_VERSION, DEFAULT_EMBED_DIRNAME;
+var EMBED_VERSION, DEFAULT_EMBED_DIRNAME, DEFAULT_EMBED_URL, EMBED_ASSET_SHA256;
 var init_model = __esm({
   "src/embed/model.ts"() {
     "use strict";
     EMBED_VERSION = 1;
     DEFAULT_EMBED_DIRNAME = "models";
+    DEFAULT_EMBED_URL = "https://github.com/maxgfr/codeindex/releases/download/embed-model-v1/model.json";
+    EMBED_ASSET_SHA256 = "163ad053eab4e9a80d421ed4164f32292c83290f02fbbe6fe4b9b1cd6ea18d34";
   }
 });
 
@@ -10129,7 +10172,9 @@ var init_viz = __esm({
 // src/mcp.ts
 var mcp_exports = {};
 __export(mcp_exports, {
-  runMcpServer: () => runMcpServer
+  memoizedEmbeddingIndex: () => memoizedEmbeddingIndex,
+  runMcpServer: () => runMcpServer,
+  scanFingerprint: () => scanFingerprint
 });
 import { createInterface } from "readline";
 function str(v) {
@@ -10138,6 +10183,19 @@ function str(v) {
 function strArray(v) {
   return Array.isArray(v) && v.every((x) => typeof x === "string") && v.length ? v : void 0;
 }
+function errMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function scanFingerprint(scan2) {
+  return sha1(scan2.files.map((f) => `${f.rel}:${f.hash}`).join("\n"));
+}
+async function memoizedEmbeddingIndex(key, build) {
+  const cacheKey = `${key.mode}:${key.identity}:${scanFingerprint(key.scan)}`;
+  if (embeddingIndexCache && embeddingIndexCache.key === cacheKey) return embeddingIndexCache.index;
+  const index = await build();
+  embeddingIndexCache = { key: cacheKey, index };
+  return index;
+}
 async function callTool(name2, args2) {
   const repo = str(args2.repo);
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
@@ -10278,19 +10336,35 @@ async function callTool(name2, args2) {
       const endpoint = resolveEmbedEndpoint();
       if (endpoint) {
         try {
-          const index = await buildEndpointIndex(scan2);
+          const index = await memoizedEmbeddingIndex({ mode: "endpoint", identity: endpoint, scan: scan2 }, () => buildEndpointIndex(scan2));
           const queryVec = await encodeQueryViaEndpoint(query);
-          return JSON.stringify(searchSemantic(scan2, query, index, { queryVec, limit, fuzzy }), null, 2);
-        } catch {
-          return JSON.stringify(searchIndex(scan2, query, { limit, fuzzy }), null, 2);
+          const results2 = searchSemantic(scan2, query, index, { queryVec, limit, fuzzy });
+          return JSON.stringify({ results: results2, tier: "endpoint" }, null, 2);
+        } catch (e) {
+          const results2 = searchIndex(scan2, query, { limit, fuzzy });
+          return JSON.stringify(
+            { results: results2, tier: "lexical", degradedReason: `embedding endpoint failed: ${errMessage(e)}` },
+            null,
+            2
+          );
         }
       }
       const modelDir = resolveEmbedModelDir(repo);
       const model = modelDir ? loadEmbedModel(modelDir) : void 0;
       if (model) {
-        const index = buildEmbeddingIndex(scan2, model);
-        return JSON.stringify(searchSemantic(scan2, query, index, { model, limit, fuzzy }), null, 2);
+        const index = await memoizedEmbeddingIndex(
+          { mode: "static", identity: `${modelDir}#${model.modelId}`, scan: scan2 },
+          () => buildEmbeddingIndex(scan2, model)
+        );
+        const results2 = searchSemantic(scan2, query, index, { model, limit, fuzzy });
+        return JSON.stringify({ results: results2, tier: "static" }, null, 2);
       }
+      const results = searchIndex(scan2, query, { limit, fuzzy });
+      return JSON.stringify(
+        { results, tier: "lexical", degradedReason: "no embedding endpoint or static model configured \u2014 see embed_status" },
+        null,
+        2
+      );
     }
     return JSON.stringify(searchIndex(scan2, query, { limit, fuzzy }), null, 2);
   }
@@ -10371,7 +10445,7 @@ async function runMcpServer() {
     }
   }
 }
-var repoProp, scopeProps, TOOLS;
+var repoProp, scopeProps, TOOLS, embeddingIndexCache;
 var init_mcp = __esm({
   "src/mcp.ts"() {
     "use strict";
@@ -10398,6 +10472,7 @@ var init_mcp = __esm({
     init_embed();
     init_search();
     init_endpoint();
+    init_hash();
     repoProp = { repo: { type: "string", description: "Absolute path to the repository root" } };
     scopeProps = {
       scope: { type: "string", description: "Restrict to one directory (repo-relative)" },
@@ -10610,7 +10685,7 @@ var init_mcp = __esm({
       },
       {
         name: "search",
-        description: 'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings by default \u2014 deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`. Set `semantic: true` to RRF-fuse the deterministic static-embedding tier when a model asset is present (degrades to lexical otherwise \u2014 see embed_status).',
+        description: 'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings by default \u2014 deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`. Set `semantic: true` to RRF-fuse an embedding tier (HTTP endpoint, else a local static model) with lexical \u2014 the response then wraps the ranked list as `{ results, tier, degradedReason? }`, `tier` being "endpoint"/"static" when fusion happened or "lexical" (with `degradedReason`) when it did not (see embed_status). Without `semantic`, the response is the bare ranked array, unchanged.',
         inputSchema: {
           type: "object",
           properties: {
@@ -10624,7 +10699,7 @@ var init_mcp = __esm({
             },
             semantic: {
               type: "boolean",
-              description: "RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. Degrades silently to lexical-only when neither is available/reachable \u2014 see embed_status."
+              description: 'RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. The response reports the effective tier as a top-level `tier` field ("endpoint"/"static" on success, "lexical" plus `degradedReason` when neither is available/reachable) instead of degrading silently \u2014 see embed_status.'
             }
           },
           required: ["repo", "query"]
@@ -11116,8 +11191,9 @@ Commands:
                 embed status   Effective mode (none/static/endpoint), model +
                                EMBED_VERSION, and endpoint reachability (JSON)
                 embed build    Write embeddings.bin into --out <dir> (static tier)
-                embed pull     Fetch the model asset into CODEINDEX_EMBED_DIR (or
-                               <repo>/.codeindex/models/) \u2014 needs CODEINDEX_EMBED_URL
+                embed pull     Fetch the official model asset into CODEINDEX_EMBED_DIR
+                               (or <repo>/.codeindex/models/); sha256-verified. Override
+                               the source with CODEINDEX_EMBED_URL
                 embed serve    Print (or --run) the docker command that starts the
                                containerized embedding server (rich tier)
   rules       Architecture rules (forbidden edges, cycles, orphans) validated
@@ -11397,26 +11473,20 @@ async function runCli(argv) {
       process.stderr.write(`codeindex: ${index.records.length} embedding records \u2192 ${flags2.out}/embeddings.bin (model ${model.modelId})
 `);
     } else if (sub === "pull") {
-      const url = resolveEmbedPullUrl();
-      if (!url) {
-        process.stderr.write(
-          "codeindex: no model URL configured. The official static-embedding asset is not published yet.\nSet CODEINDEX_EMBED_URL to a model.json URL (optionally CODEINDEX_EMBED_DIR as the destination), then re-run `codeindex embed pull`.\n"
-        );
-        process.exitCode = 1;
-        return;
-      }
+      const { url, sha256 } = resolveEmbedPullUrl();
       const destDir = process.env.CODEINDEX_EMBED_DIR ?? join12(flags2.repo, ".codeindex", "models");
       mkdirSync2(destDir, { recursive: true });
       process.stderr.write(`codeindex: fetching model from ${url} \u2192 ${join12(destDir, "model.json")}
 `);
-      const res = await fetch(url);
-      if (!res.ok) {
-        process.stderr.write(`codeindex: pull failed \u2014 HTTP ${res.status} from ${url}
+      let body2;
+      try {
+        body2 = await fetchEmbedModel(url, sha256);
+      } catch (e) {
+        process.stderr.write(`codeindex: pull failed \u2014 ${e instanceof Error ? e.message : String(e)} (nothing written)
 `);
         process.exitCode = 1;
         return;
       }
-      const body2 = await res.text();
       try {
         JSON.parse(body2);
       } catch {
@@ -11508,6 +11578,7 @@ export {
   buildGraph,
   buildIndexArtifacts,
   buildModules,
+  buildRawCallerIndex,
   buildResolveContext,
   buildSymbolIndex,
   byKey,

package/src/embed/model.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -20,12 +21,24 @@ import { join } from "node:path";
 // graph.json / symbols.json consumers.
 export const EMBED_VERSION = 1;
 
-// The default model-name a `pull` writes and a `status` reports. The real asset
-// URL is intentionally NOT hard-coded yet (see resolveEmbedPullUrl): the asset
-// is unpublished, so `pull` fails cleanly asking for CODEINDEX_EMBED_URL rather
-// than fetching a phantom.
+// The default sub-directory a `pull` writes into and a `status` reports.
 export const DEFAULT_EMBED_DIRNAME = "models";
 
+// The official static-embedding asset, published as the dedicated GitHub release
+// `embed-model-v1` (tag deliberately outside the `v<semver>` semantic-release
+// namespace, so publishing it triggers no CI). `pull` uses this when
+// CODEINDEX_EMBED_URL is unset. Reproduce the asset byte-for-byte with the pinned
+// toolchain in scripts/embed-asset/.
+export const DEFAULT_EMBED_URL =
+  "https://github.com/maxgfr/codeindex/releases/download/embed-model-v1/model.json";
+
+// sha256 of the published model.json. `pull` verifies the downloaded bytes
+// against this ONLY when it fetched the built-in default (a custom
+// CODEINDEX_EMBED_URL is the user's own mirror and keeps the un-verified
+// behavior). Regenerate alongside DEFAULT_EMBED_URL when re-cutting the asset:
+// `shasum -a 256 model.json`.
+export const EMBED_ASSET_SHA256 = "163ad053eab4e9a80d421ed4164f32292c83290f02fbbe6fe4b9b1cd6ea18d34";
+
 // A loaded static-embedding model. `vocab` maps a wordpiece token to its row
 // index; `weights` is the flat row-major (vocabSize × dim) matrix as IEEE-754
 // doubles (float rows widen to double exactly, so mean-pool stays deterministic).
@@ -107,11 +120,37 @@ export function loadEmbedModel(dir?: string): StaticEmbedModel | undefined {
   return { modelId, dim, unk, unkId, vocabSize, vocab: vmap, weights: flat };
 }
 
-// Resolve the URL `embed pull` fetches from. The official asset is not published
-// yet, so there is no built-in default: the user must point CODEINDEX_EMBED_URL
-// at a model.json (or a directory serving one). Returns undefined when unset —
-// the caller turns that into a clean, actionable failure, never a crash.
-export function resolveEmbedPullUrl(): string | undefined {
-  const url = process.env.CODEINDEX_EMBED_URL;
-  return url && url.trim() ? url.trim() : undefined;
+// What `embed pull` fetches, and whether to verify it. CODEINDEX_EMBED_URL wins
+// outright (the user's explicit override / private mirror) and carries NO
+// sha256, so a custom asset keeps the current un-verified behavior. With no env,
+// we fall back to the built-in official asset AND its pinned sha256, so `pull`
+// can prove integrity of the default download.
+export interface EmbedPullTarget {
+  url: string;
+  sha256?: string; // present only for the built-in default → verify
+}
+
+export function resolveEmbedPullUrl(): EmbedPullTarget {
+  const env = process.env.CODEINDEX_EMBED_URL;
+  if (env && env.trim()) return { url: env.trim() };
+  return { url: DEFAULT_EMBED_URL, sha256: EMBED_ASSET_SHA256 };
+}
+
+// Fetch a model.json body over HTTP, following redirects (GitHub release assets
+// 302 to a CDN — native fetch follows by default). When `expectedSha256` is
+// given, the downloaded bytes are hashed and MUST match or this throws with a
+// clear message and returns nothing — so a corrupt/tampered default asset never
+// gets written. A non-2xx response also throws. Verification and I/O are split
+// from the CLI so both the success and the sha-mismatch paths are unit-testable.
+export async function fetchEmbedModel(url: string, expectedSha256?: string): Promise<string> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
+  const body = await res.text();
+  if (expectedSha256) {
+    const got = createHash("sha256").update(body).digest("hex");
+    if (got !== expectedSha256) {
+      throw new Error(`sha256 mismatch: expected ${expectedSha256}, got ${got}`);
+    }
+  }
+  return body;
 }

package/src/engine-cli.ts

@@ -19,7 +19,7 @@ import { symbolComplexity, riskHotspots } from "./complexity.js";
 import { renderMermaid } from "./viz.js";
 import { searchIndex } from "./bm25.js";
 import { checkRules, parseRules } from "./rules.js";
-import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, resolveEmbedPullUrl } from "./embed/model.js";
+import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, resolveEmbedPullUrl, fetchEmbedModel } from "./embed/model.js";
 import { buildEmbeddingIndex, serializeEmbeddings } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
 import {
@@ -55,8 +55,9 @@ Commands:
                 embed status   Effective mode (none/static/endpoint), model +
                                EMBED_VERSION, and endpoint reachability (JSON)
                 embed build    Write embeddings.bin into --out <dir> (static tier)
-                embed pull     Fetch the model asset into CODEINDEX_EMBED_DIR (or
-                               <repo>/.codeindex/models/) — needs CODEINDEX_EMBED_URL
+                embed pull     Fetch the official model asset into CODEINDEX_EMBED_DIR
+                               (or <repo>/.codeindex/models/); sha256-verified. Override
+                               the source with CODEINDEX_EMBED_URL
                 embed serve    Print (or --run) the docker command that starts the
                                containerized embedding server (rich tier)
   rules       Architecture rules (forbidden edges, cycles, orphans) validated
@@ -387,26 +388,21 @@ export async function runCli(argv: string[]): Promise<void> {
       writeFileSync(join(flags.out, "embeddings.bin"), serializeEmbeddings(index));
       process.stderr.write(`codeindex: ${index.records.length} embedding records → ${flags.out}/embeddings.bin (model ${model.modelId})\n`);
     } else if (sub === "pull") {
-      const url = resolveEmbedPullUrl();
-      if (!url) {
-        // Clean, actionable failure — the official asset is not published yet.
-        process.stderr.write(
-          "codeindex: no model URL configured. The official static-embedding asset is not published yet.\n" +
-            "Set CODEINDEX_EMBED_URL to a model.json URL (optionally CODEINDEX_EMBED_DIR as the destination), then re-run `codeindex embed pull`.\n",
-        );
-        process.exitCode = 1;
-        return;
-      }
+      // Default: the official published asset + its pinned sha256. A user-set
+      // CODEINDEX_EMBED_URL overrides both (mirror/custom model, no verification).
+      const { url, sha256 } = resolveEmbedPullUrl();
       const destDir = process.env.CODEINDEX_EMBED_DIR ?? join(flags.repo, ".codeindex", "models");
       mkdirSync(destDir, { recursive: true });
       process.stderr.write(`codeindex: fetching model from ${url} → ${join(destDir, "model.json")}\n`);
-      const res = await fetch(url);
-      if (!res.ok) {
-        process.stderr.write(`codeindex: pull failed — HTTP ${res.status} from ${url}\n`);
+      let body: string;
+      try {
+        // Follows redirects (GitHub → CDN) and verifies sha256 for the default asset.
+        body = await fetchEmbedModel(url, sha256);
+      } catch (e) {
+        process.stderr.write(`codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`);
         process.exitCode = 1;
         return;
       }
-      const body = await res.text();
       try {
         JSON.parse(body);
       } catch {

package/src/engine.ts

@@ -55,7 +55,7 @@ export { buildModules, isTestFile, tierForPath } from "./modules.js";
 export type { ModuleInfo } from "./modules.js";
 export { buildGraph, uniqueSymbolDefs } from "./graph.js";
 export { resolveCallEdges } from "./calls.js";
-export { buildCallerIndex, enclosingSymbol, computeImportPairs } from "./callers.js";
+export { buildCallerIndex, buildRawCallerIndex, enclosingSymbol, computeImportPairs } from "./callers.js";
 export { symbolsOverview, findSymbol, findReferences } from "./query.js";
 export { resolveUniqueSymbol, replaceSymbolBody, insertAfterSymbol, insertBeforeSymbol } from "./edit.js";
 export type { EditResult } from "./edit.js";
@@ -143,6 +143,10 @@ export type { ArchRule, ForbiddenEdgeRule, BuiltinRule, RuleSeverity, RuleViolat
 // Caller-index recall mode (issue #7) — options for buildCallerIndex above.
 export type { CallerIndexOptions } from "./callers.js";
 
+// Raw-recall caller index (issue #8) — ungated, def-resolution-free companion
+// to buildCallerIndex above; see its JSDoc in callers.ts for the contract.
+export type { RawCallerIndex, RawCallerSite } from "./callers.js";
+
 // Behavioral analytics (git-history mining) + the token-budgeted repo map.
 export { changeCoupling, rankHotspots } from "./coupling.js";
 export type { ChangeCoupling, CouplingOptions, Hotspot } from "./coupling.js";

package/src/lang/common.ts

@@ -75,11 +75,14 @@ const REEXPORT_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".m
 //
 // An ALIAS with no `from` clause (`export { b as c }`) renames an in-file
 // declaration — `localSymbols` (already extracted by the AST or regex tier)
-// lets us resolve `b` and mirror ITS kind onto `c` (e.g. "function"), so the
-// alias reads as the real symbol it is rather than the generic "reexport".
+// lets us resolve `b` and mirror ITS kind, declaration line, and endLine (AST
+// tier only) onto `c` (e.g. "function" at b's own line), so the alias reads
+// as the real symbol it is — citeable at its actual declaration — rather than
+// the generic "reexport" pinned to the export statement's line.
 // A true cross-module re-export (`export { b as c } from "./mod"`) has no
 // local `b` to resolve — and an alias the local pass genuinely can't see
-// (destructured/ambient/etc.) falls back the same way — both keep "reexport".
+// (destructured/ambient/etc.) falls back the same way — both keep "reexport"
+// and cite the export statement's own line, the only line they have.
 //
 // Shared by extractCode (extract/code.ts) AND the standalone extractSymbols
 // (lang/registry.ts) — ultradoc and other direct extractSymbols consumers hit
@@ -92,8 +95,11 @@ export function extractReexports(rel: string, content: string, localSymbols: Cod
   const out: CodeSymbol[] = [];
   const seen = new Set<string>();
   const lineAt = (idx: number): number => content.slice(0, idx).split(/\r?\n/).length;
-  const localKindOf = new Map<string, string>();
-  for (const s of localSymbols) if (!localKindOf.has(s.name)) localKindOf.set(s.name, s.kind);
+  // Keyed on the whole CodeSymbol (not just kind) so the alias branch below
+  // can also cite the resolved declaration's own line/endLine, not just mirror
+  // its kind.
+  const localDeclOf = new Map<string, CodeSymbol>();
+  for (const s of localSymbols) if (!localDeclOf.has(s.name)) localDeclOf.set(s.name, s);
 
   const named = /export\s*\{([\s\S]*?)\}\s*(?:from\s*['"]([^'"]+)['"])?\s*;?/g;
   let m: RegExpExecArray | null;
@@ -106,9 +112,14 @@ export function extractReexports(rel: string, content: string, localSymbols: Cod
       const name = as ? as[2]! : p;
       if (!/^[A-Za-z_$][\w$]*$/.test(name) || name === "default" || seen.has(name)) continue;
       seen.add(name);
-      const mirroredKind = !from ? localKindOf.get(orig) : undefined;
+      // A resolved decl means this is a same-file alias: cite ITS line (and
+      // endLine, when the AST tier populated one) rather than the export
+      // statement's — an unresolved alias or a `from`-clause re-export has no
+      // local declaration to point at, so it keeps lineAt(m.index) below.
+      const decl = !from ? localDeclOf.get(orig) : undefined;
       out.push({
-        name, kind: mirroredKind ?? "reexport", file: rel, line: lineAt(m.index),
+        name, kind: decl?.kind ?? "reexport", file: rel, line: decl ? decl.line : lineAt(m.index),
+        ...(decl?.endLine !== undefined ? { endLine: decl.endLine } : {}),
         signature: from ? `export { ${name} } from "${from}"` : `export { ${name} }`,
         exported: true, lang,
       });

package/src/mcp.ts

@@ -10,7 +10,7 @@ import { ENGINE_VERSION } from "./types.js";
 import { ensureGrammars, allGrammarKeys } from "./ast/loader.js";
 import { buildIndexArtifacts } from "./pipeline.js";
 import { renderGraphJson } from "./render/graph-json.js";
-import { scanRepo } from "./scan.js";
+import { scanRepo, type RepoScan } from "./scan.js";
 import { buildCallerIndex } from "./callers.js";
 import { detectWorkspaces } from "./workspaces.js";
 import { gitChurn } from "./git.js";
@@ -26,9 +26,10 @@ import { writeMemory, readMemory, deleteMemory, listMemories } from "./memory.js
 import { searchIndex } from "./bm25.js";
 import { checkRules, parseRules } from "./rules.js";
 import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel } from "./embed/model.js";
-import { buildEmbeddingIndex } from "./embed/index.js";
+import { buildEmbeddingIndex, type EmbeddingIndex } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
 import { resolveEmbedEndpoint, buildEndpointIndex, encodeQueryViaEndpoint, probeEndpoint } from "./embed/endpoint.js";
+import { sha1 } from "./hash.js";
 
 interface RpcRequest {
   jsonrpc: "2.0";
@@ -270,7 +271,7 @@ const TOOLS = [
   {
     name: "search",
     description:
-      'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings by default — deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`. Set `semantic: true` to RRF-fuse the deterministic static-embedding tier when a model asset is present (degrades to lexical otherwise — see embed_status).',
+      'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings by default — deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`. Set `semantic: true` to RRF-fuse an embedding tier (HTTP endpoint, else a local static model) with lexical — the response then wraps the ranked list as `{ results, tier, degradedReason? }`, `tier` being "endpoint"/"static" when fusion happened or "lexical" (with `degradedReason`) when it did not (see embed_status). Without `semantic`, the response is the bare ranked array, unchanged.',
     inputSchema: {
       type: "object",
       properties: {
@@ -286,7 +287,7 @@ const TOOLS = [
         semantic: {
           type: "boolean",
           description:
-            "RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. Degrades silently to lexical-only when neither is available/reachable — see embed_status.",
+            'RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. The response reports the effective tier as a top-level `tier` field ("endpoint"/"static" on success, "lexical" plus `degradedReason` when neither is available/reachable) instead of degrading silently — see embed_status.',
         },
       },
       required: ["repo", "query"],
@@ -320,6 +321,50 @@ function str(v: unknown): string | undefined {
 function strArray(v: unknown): string[] | undefined {
   return Array.isArray(v) && v.every((x) => typeof x === "string") && v.length ? (v as string[]) : undefined;
 }
+function errMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// --- embedding index memoization --------------------------------------------
+// The MCP server process is long-lived, but every `search` call used to redo
+// the FULL corpus embedding build — N `buildEndpointIndex` HTTP round-trips,
+// or a full `buildEmbeddingIndex` re-encode pass — even when nothing in the
+// repo changed between requests. Memoize the last build behind a fingerprint
+// of the scan contents plus the tier's identity, so an unchanged repo reuses
+// the cached index and any file add/edit/remove (or a switch of endpoint/model)
+// still rebuilds. RepoScan carries no fingerprint of its own (checked
+// scan.ts/types.ts) — every FileRecord already carries a content hash, so
+// hashing the (rel, hash) pairs is the staleness oracle scan.ts itself uses.
+export function scanFingerprint(scan: RepoScan): string {
+  return sha1(scan.files.map((f) => `${f.rel}:${f.hash}`).join("\n"));
+}
+
+export interface EmbeddingIndexCacheKey {
+  mode: "endpoint" | "static";
+  // Distinguishes cache entries across configs sharing the same scan: the
+  // endpoint URL, or the model dir + modelId for the static tier.
+  identity: string;
+  scan: RepoScan;
+}
+
+// A SINGLE entry — never an unbounded map — holding the most recent build.
+let embeddingIndexCache: { key: string; index: EmbeddingIndex } | undefined;
+
+// Reuse the cached index when (mode, identity, scanFingerprint) matches the
+// last build; otherwise call `build` and cache its result. A failed build is
+// NEVER cached (matches today's per-call error behavior: the next request
+// retries from scratch, and a still-valid previous entry — under a different
+// key — is left untouched).
+export async function memoizedEmbeddingIndex(
+  key: EmbeddingIndexCacheKey,
+  build: () => Promise<EmbeddingIndex> | EmbeddingIndex,
+): Promise<EmbeddingIndex> {
+  const cacheKey = `${key.mode}:${key.identity}:${scanFingerprint(key.scan)}`;
+  if (embeddingIndexCache && embeddingIndexCache.key === cacheKey) return embeddingIndexCache.index;
+  const index = await build();
+  embeddingIndexCache = { key: cacheKey, index };
+  return index;
+}
 
 async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
   const repo = str(args.repo);
@@ -459,25 +504,49 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<st
     const limit = typeof args.limit === "number" ? args.limit : undefined;
     const fuzzy = typeof args.fuzzy === "boolean" ? args.fuzzy : undefined;
     if (args.semantic === true) {
+      // semantic:true changes the response SHAPE (wraps the ranked list with a
+      // `tier`/`degradedReason?`) so a caller can tell "fusion happened" apart
+      // from "degraded to lexical" — see the `search` tool description. This
+      // branch is the ONLY place that shape appears; plain lexical search below
+      // stays the bare array, byte-compat for existing consumers.
       const endpoint = resolveEmbedEndpoint();
       if (endpoint) {
         // Rich tier — endpoint takes PRECEDENCE over a local static model. An
-        // unreachable/malformed endpoint degrades to lexical (no throw).
+        // unreachable/malformed endpoint degrades to lexical, now with a reason.
+        // The corpus index is memoized per (endpoint, scan state) — the query
+        // itself is always re-encoded fresh (it differs per call).
         try {
-          const index = await buildEndpointIndex(scan);
+          const index = await memoizedEmbeddingIndex({ mode: "endpoint", identity: endpoint, scan }, () => buildEndpointIndex(scan));
           const queryVec = await encodeQueryViaEndpoint(query);
-          return JSON.stringify(searchSemantic(scan, query, index, { queryVec, limit, fuzzy }), null, 2);
-        } catch {
-          return JSON.stringify(searchIndex(scan, query, { limit, fuzzy }), null, 2);
+          const results = searchSemantic(scan, query, index, { queryVec, limit, fuzzy });
+          return JSON.stringify({ results, tier: "endpoint" }, null, 2);
+        } catch (e) {
+          const results = searchIndex(scan, query, { limit, fuzzy });
+          return JSON.stringify(
+            { results, tier: "lexical", degradedReason: `embedding endpoint failed: ${errMessage(e)}` },
+            null,
+            2,
+          );
         }
       }
       const modelDir = resolveEmbedModelDir(repo);
       const model = modelDir ? loadEmbedModel(modelDir) : undefined;
       if (model) {
-        const index = buildEmbeddingIndex(scan, model);
-        return JSON.stringify(searchSemantic(scan, query, index, { model, limit, fuzzy }), null, 2);
+        const index = await memoizedEmbeddingIndex(
+          { mode: "static", identity: `${modelDir}#${model.modelId}`, scan },
+          () => buildEmbeddingIndex(scan, model),
+        );
+        const results = searchSemantic(scan, query, index, { model, limit, fuzzy });
+        return JSON.stringify({ results, tier: "static" }, null, 2);
       }
-      // Degrade to lexical (opt-in tier not activated) — no throw.
+      // Opt-in tier not activated (no endpoint, no model asset) — degrade to
+      // lexical with a reason instead of failing silently.
+      const results = searchIndex(scan, query, { limit, fuzzy });
+      return JSON.stringify(
+        { results, tier: "lexical", degradedReason: "no embedding endpoint or static model configured — see embed_status" },
+        null,
+        2,
+      );
     }
     return JSON.stringify(searchIndex(scan, query, { limit, fuzzy }), null, 2);
   }

package/src/types.ts

@@ -1,7 +1,7 @@
 // Single source of truth for the engine version the bundle reports. Kept in
 // lockstep with package.json by the release pipeline. Do not edit by hand
 // outside a release.
-export const ENGINE_VERSION = "2.11.1";
+export const ENGINE_VERSION = "2.12.0";
 
 // Bumped whenever the on-disk artifact shape changes, so a consumer can reject
 // an index written by an incompatible engine instead of misreading it. The
@@ -30,9 +30,15 @@ export const SCHEMA_VERSION = 4;
 // "reexport" when it resolves in-file. v8 fixes the C/C++ regex tier
 // reporting a function DEFINITION as a call to itself (`void load(void) {`
 // yielding a spurious call `load@<defline>`, found during the ultrasec
-// consumer migration) by excluding call candidates whose name+line match one
-// of the file's own extracted symbols.
-export const EXTRACTOR_VERSION = 8;
+// consumer migration) by excluding, from call candidates, only the
+// definition's own token on its definition line — not every occurrence of
+// that name+line pair, which would also drop genuine same-line calls (dense
+// one-liners packing several definitions, one-line recursion); v9 makes a
+// resolved export-alias symbol also cite the original declaration's own line
+// (and endLine, when the AST tier populated one) instead of the export
+// statement's line — a citation-precision fix (issue #9) for consumers
+// (ultradoc) that use file:line as evidence.
+export const EXTRACTOR_VERSION = 9;
 
 // How a file is classified. `code` gets symbol/import extraction; `doc` gets
 // link/heading extraction; the rest are catalogued but not deeply parsed.