@maxgfr/codeindex 2.9.0 → 2.11.0

package/src/engine-cli.ts

@@ -19,6 +19,16 @@ 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 { buildEmbeddingIndex, serializeEmbeddings } from "./embed/index.js";
+import { searchSemantic } from "./embed/search.js";
+import {
+  resolveEmbedEndpoint,
+  buildEndpointIndex,
+  encodeQueryViaEndpoint,
+  probeEndpoint,
+} from "./embed/endpoint.js";
+import { have, sh } from "./util.js";
 
 const HELP = `codeindex engine v${ENGINE_VERSION} — deterministic repo indexing
 
@@ -37,7 +47,18 @@ Commands:
   churn       Per-file git commit counts (JSON; --since <ref> to bound)
   grep        Search: cli.mjs grep <pattern> --repo <dir> (JSON hits)
   search      Keyless BM25 lexical search over symbol names, path segments,
-              markdown headings and summaries: cli.mjs search "<query>" --repo <dir>
+              markdown headings and summaries: cli.mjs search "<query>" --repo <dir>.
+              --semantic fuses in an embedding tier (RRF) — the HTTP endpoint
+              (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model;
+              degrades to lexical (exit 0) when neither is available/reachable
+  embed       Embedding tiers (opt-in). Precedence: endpoint > static model:
+                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 serve    Print (or --run) the docker command that starts the
+                               containerized embedding server (rich tier)
   rules       Architecture rules (forbidden edges, cycles, orphans) validated
               against the link-graph: --config <codeindex.rules.json>; exits 1
               on any error-severity violation (a CI gate)
@@ -65,6 +86,10 @@ Flags:
   --limit <n>         Max results for \`search\` (default 20)
   --no-fuzzy          \`search\`: disable trigram fuzzy fallback for query terms
                       with zero document frequency (default: enabled)
+  --semantic          \`search\`: RRF-fuse an embedding tier with lexical — the
+                      HTTP endpoint if CODEINDEX_EMBED_ENDPOINT is set, else a
+                      local static model (lexical-only when neither is available)
+  --run               \`embed serve\`: run the docker command instead of printing it
   --recall            \`callers\`: recall-oriented binding (issue #7) — relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
@@ -87,13 +112,15 @@ interface CliFlags {
   config?: string; // rules config path
   limit?: number; // search result cap
   fuzzy: boolean; // search: trigram fuzzy fallback for df==0 terms (default true)
+  semantic: boolean; // search: RRF-fuse the static-embedding tier (default false)
   recall?: boolean; // callers: recall-oriented binding
+  run?: boolean; // `embed serve`: actually run the docker command (default: print)
   projectRoot?: string; // scip: override Metadata.project_root
   positional?: string; // e.g. the grep pattern or search query
 }
 
 function parseFlags(args: string[]): CliFlags {
-  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true };
+  const flags: CliFlags = { repo: process.cwd(), include: [], exclude: [], gitignore: true, noAst: false, fuzzy: true, semantic: false };
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     const next = (): string => {
@@ -126,7 +153,9 @@ function parseFlags(args: string[]): CliFlags {
     else if (a === "--config") flags.config = resolve(next());
     else if (a === "--limit") flags.limit = num();
     else if (a === "--no-fuzzy") flags.fuzzy = false;
+    else if (a === "--semantic") flags.semantic = true;
     else if (a === "--recall") flags.recall = true;
+    else if (a === "--run") flags.run = true;
     else if (!a.startsWith("--") && flags.positional === undefined) flags.positional = a;
     else throw new Error(`unknown flag: ${a}`);
   }
@@ -203,7 +232,18 @@ export async function runCli(argv: string[]): Promise<void> {
       cachePath,
       JSON.stringify({ schemaVersion: SCHEMA_VERSION, extractorVersion: EXTRACTOR_VERSION, files }) + "\n",
     );
-    process.stderr.write(`codeindex: ${scan.files.length} files → ${outDir}/graph.json + symbols.json${scan.capped ? " (capped)" : ""}\n`);
+    // Deterministic embeddings sidecar: written next to graph.json ONLY when a
+    // model asset is present (opt-in). Silently skipped otherwise — no model, no
+    // embeddings.bin, no impact on the graph/symbols consumers.
+    let embedNote = "";
+    const modelDir = resolveEmbedModelDir(flags.repo);
+    const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+    if (model) {
+      const index = buildEmbeddingIndex(scan, model);
+      writeFileSync(join(outDir, "embeddings.bin"), serializeEmbeddings(index));
+      embedNote = ` + embeddings.bin (${index.records.length} records, model ${model.modelId})`;
+    }
+    process.stderr.write(`codeindex: ${scan.files.length} files → ${outDir}/graph.json + symbols.json${embedNote}${scan.capped ? " (capped)" : ""}\n`);
   } else if (cmd === "scan") {
     const { scan } = buildIndexArtifacts(flags.repo, scanOptions(flags));
     const summary = {
@@ -238,8 +278,147 @@ export async function runCli(argv: string[]): Promise<void> {
   } else if (cmd === "search") {
     if (!flags.positional) throw new Error('search needs a query: cli.mjs search "<query>" --repo <dir>');
     const scan = scanRepo(flags.repo, scanOptions(flags));
-    const results = searchIndex(scan, flags.positional, { limit: flags.limit, fuzzy: flags.fuzzy });
-    emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+    if (flags.semantic) {
+      const endpoint = resolveEmbedEndpoint();
+      const lexical = (): void => {
+        const results = searchIndex(scan, flags.positional!, { limit: flags.limit, fuzzy: flags.fuzzy });
+        emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+      };
+      if (endpoint) {
+        // Rich tier. The endpoint takes PRECEDENCE over a local static model:
+        // configuring CODEINDEX_EMBED_ENDPOINT is an explicit user intent. An
+        // unreachable/timed-out/malformed endpoint degrades straight to lexical
+        // (a stderr note, exit 0) — NOT to the static model.
+        try {
+          const index = await buildEndpointIndex(scan);
+          const queryVec = await encodeQueryViaEndpoint(flags.positional);
+          const results = searchSemantic(scan, flags.positional, index, { queryVec, limit: flags.limit, fuzzy: flags.fuzzy });
+          emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+        } catch (e) {
+          process.stderr.write(
+            `codeindex: embedding endpoint ${endpoint} unavailable (${e instanceof Error ? e.message : e}) — returning lexical results\n`,
+          );
+          lexical();
+        }
+      } else {
+        const modelDir = resolveEmbedModelDir(flags.repo);
+        const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+        if (!model) {
+          // Degradation: --semantic without a model or endpoint → lexical results
+          // + a stderr note, exit 0. The results shape is a superset of lexical.
+          process.stderr.write(
+            "codeindex: semantic search unavailable (no embedding model or endpoint) — returning lexical results; run `codeindex embed pull` or set CODEINDEX_EMBED_ENDPOINT to enable it\n",
+          );
+          lexical();
+        } else {
+          const index = buildEmbeddingIndex(scan, model);
+          const results = searchSemantic(scan, flags.positional, index, { model, limit: flags.limit, fuzzy: flags.fuzzy });
+          emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+        }
+      }
+    } else {
+      const results = searchIndex(scan, flags.positional, { limit: flags.limit, fuzzy: flags.fuzzy });
+      emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+    }
+  } else if (cmd === "embed") {
+    const sub = flags.positional;
+    const modelDir = resolveEmbedModelDir(flags.repo);
+    if (sub === "status") {
+      const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+      const endpoint = resolveEmbedEndpoint();
+      // Effective mode with precedence: endpoint > static model > none.
+      const mode: "none" | "static" | "endpoint" = endpoint ? "endpoint" : model ? "static" : "none";
+      const status: Record<string, unknown> = {
+        embedVersion: EMBED_VERSION,
+        mode,
+        model: model
+          ? { present: true, dir: modelDir, modelId: model.modelId, dim: model.dim, vocabSize: model.vocabSize }
+          : { present: false },
+        endpoint: endpoint ?? null,
+      };
+      // When an endpoint is configured, actually probe its reachability.
+      if (endpoint) status.endpointReachable = await probeEndpoint(endpoint);
+      emit(JSON.stringify(status, null, 2) + "\n", flags.out);
+    } else if (sub === "serve") {
+      // Convenience only — the LIBRARY never orchestrates docker (engine.ts is
+      // side-effect-free). This lives in the CLI: it prints (or, with --run,
+      // executes) the docker command that starts the embedding server image.
+      const dockerArgs = ["run", "-d", "-p", "8756:8756", "ghcr.io/maxgfr/codeindex-embed:latest"];
+      const oneLiner = `docker ${dockerArgs.join(" ")}`;
+      if (!have("docker")) {
+        process.stderr.write(
+          "codeindex: docker not found on PATH. Install Docker, then run:\n  " + oneLiner + "\n",
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (flags.run) {
+        process.stderr.write(`codeindex: starting embedding server → ${oneLiner}\n`);
+        const res = sh("docker", dockerArgs);
+        if (res.stdout.trim()) process.stdout.write(res.stdout.trim() + "\n"); // container id
+        if (!res.ok) {
+          process.stderr.write(res.stderr || "codeindex: docker run failed\n");
+          process.exitCode = 1;
+          return;
+        }
+        process.stderr.write(
+          "codeindex: server starting on http://localhost:8756 — then:\n" +
+            "  CODEINDEX_EMBED_ENDPOINT=http://localhost:8756 codeindex search \"<query>\" --repo . --semantic\n",
+        );
+      } else {
+        // Print the command for the user to run (default; no side effects).
+        process.stdout.write(oneLiner + "\n");
+        process.stderr.write(
+          "codeindex: run the line above to start the embedding server (or `embed serve --run`), then:\n" +
+            "  CODEINDEX_EMBED_ENDPOINT=http://localhost:8756 codeindex search \"<query>\" --repo . --semantic\n",
+        );
+      }
+    } else if (sub === "build") {
+      if (!flags.out) throw new Error("embed build needs --out <dir>");
+      if (!modelDir) {
+        process.stderr.write("codeindex: no embedding model present — run `codeindex embed pull` first (nothing written)\n");
+        process.exitCode = 1;
+        return;
+      }
+      const model = loadEmbedModel(modelDir)!;
+      mkdirSync(flags.out, { recursive: true });
+      const scan = scanRepo(flags.repo, scanOptions(flags));
+      const index = buildEmbeddingIndex(scan, model);
+      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;
+      }
+      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`);
+        process.exitCode = 1;
+        return;
+      }
+      const body = await res.text();
+      try {
+        JSON.parse(body);
+      } catch {
+        process.stderr.write("codeindex: pull failed — response is not a valid model.json (expected JSON)\n");
+        process.exitCode = 1;
+        return;
+      }
+      writeFileSync(join(destDir, "model.json"), body);
+      process.stderr.write(`codeindex: model written to ${join(destDir, "model.json")}\n`);
+    } else {
+      throw new Error("embed needs a subcommand: status | build | pull | serve");
+    }
   } else if (cmd === "rules") {
     if (!flags.config) throw new Error("rules needs --config <codeindex.rules.json>");
     const rules = parseRules(JSON.parse(readFileSync(flags.config, "utf8")));

package/src/engine.ts

@@ -103,6 +103,39 @@ export type { SearchHit, GrepOptions } from "./grep.js";
 export { searchIndex, subtokens } from "./bm25.js";
 export type { SearchOptions, SearchResult } from "./bm25.js";
 
+// Deterministic static-embedding tier (v2.10.0): a keyless, byte-deterministic
+// semantic search, opt-in by model-asset presence (models NEVER ship in the
+// tarball). EMBED_VERSION is dedicated to the embeddings.bin sidecar and is
+// independent of SCHEMA_VERSION / EXTRACTOR_VERSION.
+export {
+  EMBED_VERSION,
+  resolveEmbedModelDir,
+  hasEmbedModel,
+  loadEmbedModel,
+  resolveEmbedPullUrl,
+} from "./embed/model.js";
+export type { StaticEmbedModel } from "./embed/model.js";
+export { encode, quantize, tokenize, wordpiece, basicTokenize, roundHalfToEven, intDot } from "./embed/encode.js";
+export { buildEmbeddingIndex, serializeEmbeddings, deserializeEmbeddings, embeddingUnits } from "./embed/index.js";
+export type { EmbeddingIndex, EmbeddingRecord, EmbeddingUnit } from "./embed/index.js";
+export { searchSemantic } from "./embed/search.js";
+export type { SemanticSearchOptions, SemanticSearchResult } from "./embed/search.js";
+// HTTP endpoint tier (v2.11.0 — the "rich" tier). The engine is a fetch consumer
+// of a containerized embedding server (CODEINDEX_EMBED_ENDPOINT): float vectors
+// run through the SAME L2+int8 quantize pipeline, then the same integer ranking.
+// Deterministic PER IMAGE DIGEST (not byte-golden). The library never
+// orchestrates docker — `codeindex embed serve` (CLI) only prints/runs it.
+export {
+  embedViaEndpoint,
+  resolveEmbedEndpoint,
+  embedEndpointUrl,
+  healthzUrl,
+  probeEndpoint,
+  encodeQueryViaEndpoint,
+  buildEndpointIndex,
+} from "./embed/endpoint.js";
+export type { EmbedEndpointOptions } from "./embed/endpoint.js";
+
 // Architecture rules: forbidden edges + cycles/orphans builtins (issue #4).
 export { checkRules, parseRules } from "./rules.js";
 export type { ArchRule, ForbiddenEdgeRule, BuiltinRule, RuleSeverity, RuleViolation } from "./rules.js";

package/src/extract/code.ts

@@ -256,12 +256,22 @@ function extractImports(ext: string, content: string): RawRef[] {
 // Barrel re-exports (`export { A, B as C } from './x'`, `export * from './y'`).
 // The line-based lang extractor can't capture multi-name lists, but these ARE
 // the public facade of a module — so list them as exported symbols here.
-function extractReexports(rel: string, content: string): CodeSymbol[] {
+//
+// 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".
+// 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".
+function extractReexports(rel: string, content: string, localSymbols: CodeSymbol[]): CodeSymbol[] {
   if (!JS_TS.has(rel.slice(rel.lastIndexOf(".")))) return [];
   const lang = /\.(ts|tsx|mts|cts)$/.test(rel) ? "typescript" : "javascript";
   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);
 
   const named = /export\s*\{([\s\S]*?)\}\s*(?:from\s*['"]([^'"]+)['"])?\s*;?/g;
   let m: RegExpExecArray | null;
@@ -270,11 +280,13 @@ function extractReexports(rel: string, content: string): CodeSymbol[] {
     for (const part of m[1]!.split(",")) {
       const p = part.trim().replace(/^type\s+/, "");
       const as = /^(\S+)\s+as\s+([A-Za-z_$][\w$]*)$/.exec(p);
+      const orig = as ? as[1]! : p;
       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;
       out.push({
-        name, kind: "reexport", file: rel, line: lineAt(m.index),
+        name, kind: mirroredKind ?? "reexport", file: rel, line: lineAt(m.index),
         signature: from ? `export { ${name} } from "${from}"` : `export { ${name} }`,
         exported: true, lang,
       });
@@ -354,7 +366,7 @@ export function extractCode(rel: string, ext: string, content: string): CodeInfo
   const symbols = (ast ? ast.symbols : extractSymbols(rel, ext, content)).slice(0, 400);
   // Add barrel re-exports the local def didn't already cover.
   const known = new Set(symbols.map((s) => s.name));
-  const reexports = extractReexports(rel, content).filter((s) => !known.has(s.name));
+  const reexports = extractReexports(rel, content, symbols).filter((s) => !known.has(s.name));
   return {
     symbols: [...symbols, ...reexports],
     summary: topDocComment(content),

package/src/mcp.ts

@@ -25,6 +25,10 @@ import { replaceSymbolBody, insertAfterSymbol, insertBeforeSymbol } from "./edit
 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 { searchSemantic } from "./embed/search.js";
+import { resolveEmbedEndpoint, buildEndpointIndex, encodeQueryViaEndpoint, probeEndpoint } from "./embed/endpoint.js";
 
 interface RpcRequest {
   jsonrpc: "2.0";
@@ -266,7 +270,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 — 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`.',
+      '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).',
     inputSchema: {
       type: "object",
       properties: {
@@ -279,10 +283,21 @@ const TOOLS = [
           description:
             "Trigram fuzzy fallback for query terms with zero document frequency (default true)",
         },
+        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.",
+        },
       },
       required: ["repo", "query"],
     },
   },
+  {
+    name: "embed_status",
+    description:
+      "Report the embedding tier: the effective mode (none/static/endpoint; endpoint > static model), the resolved model (opt-in, never shipped in the package) with its modelId/dim, EMBED_VERSION, and the configured HTTP endpoint with its reachability. Use to check whether `search` with semantic:true will fuse embeddings or degrade to lexical.",
+    inputSchema: { type: "object", properties: { ...repoProp }, required: ["repo"] },
+  },
   {
     name: "check_rules",
     description:
@@ -306,7 +321,7 @@ function strArray(v: unknown): string[] | undefined {
   return Array.isArray(v) && v.every((x) => typeof x === "string") && v.length ? (v as string[]) : undefined;
 }
 
-function callTool(name: string, args: Record<string, unknown>): string {
+async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
   const repo = str(args.repo);
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
   const scanOpts = { scope: str(args.scope), include: strArray(args.include), exclude: strArray(args.exclude) };
@@ -440,11 +455,47 @@ function callTool(name: string, args: Record<string, unknown>): string {
   if (name === "search") {
     const query = str(args.query);
     if (!query) throw new Error("`query` is required");
-    const results = searchIndex(scanRepo(repo, scanOpts), query, {
-      limit: typeof args.limit === "number" ? args.limit : undefined,
-      fuzzy: typeof args.fuzzy === "boolean" ? args.fuzzy : undefined,
-    });
-    return JSON.stringify(results, null, 2);
+    const scan = scanRepo(repo, scanOpts);
+    const limit = typeof args.limit === "number" ? args.limit : undefined;
+    const fuzzy = typeof args.fuzzy === "boolean" ? args.fuzzy : undefined;
+    if (args.semantic === true) {
+      const endpoint = resolveEmbedEndpoint();
+      if (endpoint) {
+        // Rich tier — endpoint takes PRECEDENCE over a local static model. An
+        // unreachable/malformed endpoint degrades to lexical (no throw).
+        try {
+          const index = await 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 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);
+      }
+      // Degrade to lexical (opt-in tier not activated) — no throw.
+    }
+    return JSON.stringify(searchIndex(scan, query, { limit, fuzzy }), null, 2);
+  }
+  if (name === "embed_status") {
+    const modelDir = resolveEmbedModelDir(repo);
+    const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+    const endpoint = resolveEmbedEndpoint();
+    const mode: "none" | "static" | "endpoint" = endpoint ? "endpoint" : model ? "static" : "none";
+    const status: Record<string, unknown> = {
+      embedVersion: EMBED_VERSION,
+      mode,
+      model: model
+        ? { present: true, dir: modelDir, modelId: model.modelId, dim: model.dim, vocabSize: model.vocabSize }
+        : { present: false },
+      endpoint: endpoint ?? null,
+    };
+    if (endpoint) status.endpointReachable = await probeEndpoint(endpoint);
+    return JSON.stringify(status, null, 2);
   }
   if (name === "check_rules") {
     const rules = parseRules(args.rules); // throws a descriptive error on a malformed payload
@@ -475,10 +526,10 @@ export async function runMcpServer(): Promise<void> {
     // JSON-RPC 2.0 batch: answer each member (a batching client would
     // otherwise hang forever on a silently dropped array).
     const requests = Array.isArray(parsed) ? (parsed as RpcRequest[]) : [parsed as RpcRequest];
-    for (const req of requests) handle(req);
+    for (const req of requests) await handle(req);
   }
 
-  function handle(req: RpcRequest): void {
+  async function handle(req: RpcRequest): Promise<void> {
     if (req.id === undefined || req.id === null) return; // notification — no response
 
     try {
@@ -500,7 +551,7 @@ export async function runMcpServer(): Promise<void> {
         const name = str(params.name) ?? "";
         const args = (params.arguments ?? {}) as Record<string, unknown>;
         try {
-          const text = callTool(name, args);
+          const text = await callTool(name, args);
           send({ id: req.id, result: { content: [{ type: "text", text }] } });
         } catch (e) {
           send({

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.9.0";
+export const ENGINE_VERSION = "2.11.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
@@ -24,8 +24,11 @@ export const SCHEMA_VERSION = 4;
 // (the immediate receiver of a qualified call, both tiers) and JS/TS export
 // parity with ultradoc (CJS `exports.foo =` / `module.exports = {…}` named
 // exports, `export { a, b as c }` local marking, anonymous `export default`
-// named after the file stem, `export default Foo` marking the declaration).
-export const EXTRACTOR_VERSION = 6;
+// named after the file stem, `export default Foo` marking the declaration);
+// v7 makes an export-alias symbol (`export { b as c }`) mirror the aliased
+// local declaration's own kind (e.g. "function") instead of the generic
+// "reexport" when it resolves in-file.
+export const EXTRACTOR_VERSION = 7;
 
 // How a file is classified. `code` gets symbol/import extraction; `doc` gets
 // link/heading extraction; the rest are catalogued but not deeply parsed.