@maxgfr/codeindex 2.14.0 → 2.16.0

package/README.md

@@ -17,7 +17,7 @@ engine as a single file instead of taking an npm dependency.
   and count caps (`capped` flag, never silent truncation), symlink-cycle guard.
 - **Scan** every file into a `FileRecord`: classification, language, symbols,
   imports, headings, hashes — with an incremental cache fastpath.
-- **Extract symbols** via tree-sitter (10 languages, when the wasm sidecar is
+- **Extract symbols** via tree-sitter (13 languages, when the wasm sidecar is
   present) or per-language regex rules (15 languages, always available).
 - **Resolve imports** across languages: tsconfig paths, package `exports`,
   go.mod, Cargo, Java packages, PSR-4, C# namespaces.

package/docs/MIGRATION.md

@@ -220,6 +220,58 @@ surface is additive (semver-minor).
   `resolveGrammarsPullTarget`, `fetchGrammarsTarball`, `fetchExpectedSha256`,
   `extractGrammarsTarball`, `GrammarsPullTarget`.
 
+## v2.15.0 — MCP serves from a persisted index (additive, no re-pin required)
+
+Pure fastpath, MCP-only: on the **first** tool call for a repo the long-lived
+server seeds its session from a committed `.codeindex/` index (written by
+`codeindex index`) instead of doing every step cold. Served tool responses stay
+**byte-identical** to a cold-process build on the same repo state, so **no
+re-pin is required** and no consumer needs to act. `SCHEMA_VERSION` /
+`EMBED_VERSION` / `EXTRACTOR_VERSION` are untouched, the public API is unchanged
+(**no new exports** — the preload is entirely internal to `mcp.ts`), and a repo
+with no `.codeindex/` behaves exactly as before.
+
+- **Scan seed from `cache.json`.** `getScan`'s first touch reads
+  `.codeindex/cache.json` and re-expresses its per-file records as the session
+  `cache`, so scan.ts's stat fastpath / exact content-hash reuse rebuilds the
+  `RepoScan` value-identically to a cold scan (the T3/T4 determinism the CLI's
+  `index` fastpath already relies on) without a read + hash + extraction per
+  unchanged file. Records are only trusted when the cache's
+  `(schemaVersion, extractorVersion)` match this engine — the same gate the CLI
+  applies — otherwise the whole cache is discarded and the scan runs cold. A
+  file whose content drifted since `cache.json` is re-read/extracted here exactly
+  as a cold scan would, so the scan stays correct and only the derived freshness
+  flags differ (they never feed artifacts).
+- **Artifact preload from `graph.json` / `symbols.json` — gated by the T4
+  oracle.** Only when the **exact** T4 freshness guard holds does the session
+  deserialize the on-disk artifacts straight in, skipping the whole downstream
+  pipeline (`buildArtifactsFromScan`) for the first
+  `graph`/`symbols`/`mermaid`/`repo_map`/`check_rules` call. The guard is the one
+  the CLI `index` fastpath uses to prove the on-disk bytes equal a fresh build:
+  `scan.contentUnchanged` **and** `cache.json`'s `engineVersion === ENGINE_VERSION`
+  **and** its `commit === scan.commit` **and**
+  `sha1(graph.json) === meta.graphSha1` **and**
+  `sha1(symbols.json) === meta.symbolsSha1`. When it holds, the on-disk
+  `graph.json`/`symbols.json` are byte-equal to `buildArtifactsFromScan(scan)` run
+  here, so deserializing them equals rebuilding.
+- **Deserialize is `JSON.parse`, not a new codec — no new exports.** `Graph` and
+  `SymbolIndex` are pure JSON POJOs (no `Map`/`Set`/typed fields), so
+  `JSON.parse` is a lossless round-trip and a `schemaVersion` assert is the only
+  reconstruction needed. `renderGraphJson` re-sorts `graph.languages` anyway, so
+  render→parse→render reproduces the same bytes (numbers reproduce their
+  shortest-round-trip form, absent optionals stay absent, V8's integer-key
+  hoisting is identical). No (de)serializer was added to the barrel; the preload
+  helpers are private to `mcp.ts`.
+- **Fallback is today's build-on-demand path, EXACTLY — never a throw.** No
+  `.codeindex/`, a `(schemaVersion, extractorVersion)` mismatch, a stale scan, a
+  version/commit/sha mismatch, or a missing/corrupt/partial/tampered
+  `graph.json`/`symbols.json` each returns `undefined` and falls through to a
+  fresh `scanRepo` / `buildArtifactsFromScan`. So the preload self-heals on
+  corruption and a deleted or truncated artifact never crashes the session — the
+  worst case is the cold cost the server paid before this release. The embed
+  sidecar keeps its own memoization path (the graph/symbols shas are all the
+  guard checks).
+
 ## Typical mapping (what to replace with what)
 
 What a consumer usually deletes from its own codebase, and the engine export

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.14.0",
+  "version": "2.16.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",

package/scripts/engine.d.mts

@@ -1,4 +1,4 @@
-declare const ENGINE_VERSION = "2.14.0";
+declare const ENGINE_VERSION = "2.16.0";
 declare const SCHEMA_VERSION = 4;
 declare const EXTRACTOR_VERSION = 10;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
@@ -255,7 +255,7 @@ declare function extractAst(rel: string, ext: string, content: string, opts?: {
     maxCalls?: number;
 }): AstResult | undefined;
 
-declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.14.0/grammars-2.14.0.tar.gz";
+declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.16.0/grammars-2.16.0.tar.gz";
 interface GrammarsPullTarget {
     url: string;
     sha256Url?: string;
@@ -265,6 +265,38 @@ declare function fetchGrammarsTarball(url: string, expectedSha256?: string): Pro
 declare function fetchExpectedSha256(url: string): Promise<string>;
 declare function extractTarInto(rawTar: Uint8Array, destDir: string): string[];
 declare function extractGrammarsTarball(bytes: Uint8Array, destDir: string): string[];
+interface GrammarsPullResult {
+    ok: boolean;
+    status: "up-to-date" | "pulled" | "failed";
+    cacheDir: string;
+    /** One human-readable line; the CLI writes it to stderr, a library caller may log or drop it. */
+    message: string;
+}
+declare function pullGrammars(cacheDir: string, opts?: {
+    onNote?: (msg: string) => void;
+}): Promise<GrammarsPullResult>;
+
+interface WarmGrammarsResult {
+    /** Tier AFTER the warm-up (a successful pull moves "none" → "cache"). */
+    tier: GrammarsTierName;
+    /** True when at least one requested grammar is loaded ⇒ the AST tier is live. */
+    ready: boolean;
+    /** True when this call populated the shared cache over the network. */
+    pulled: boolean;
+    /** Everything written to `onNote`, in order — so a caller can persist the trail in its run artifacts. */
+    notes: string[];
+}
+interface WarmGrammarsOptions {
+    /** Grammars to load. Default: every shipped grammar. Narrow it with `grammarKeysForExts` when the repo's languages are known. */
+    keys?: Iterable<string>;
+    /** Fetch the wasms into the shared cache when nothing is resolvable. Default true; `CODEINDEX_NO_GRAMMARS_PULL=1` forces false. */
+    pull?: boolean;
+    /** Prefix for the diagnostics ("ultrasec: …"). Default "codeindex". */
+    label?: string;
+    /** Where diagnostics go. Default: process.stderr. Pass a sink to keep stdout/stderr clean. */
+    onNote?: (msg: string) => void;
+}
+declare function warmGrammars(opts?: WarmGrammarsOptions): Promise<WarmGrammarsResult>;
 
 type Resolution = {
     kind: "resolved";
@@ -747,4 +779,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_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, 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, buildArtifactsFromScan, 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, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, 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, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, 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_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullResult, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, 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 WarmGrammarsOptions, type WarmGrammarsResult, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildArtifactsFromScan, 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, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, pullGrammars, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, warmGrammars, wordpiece, writeMemory };

package/scripts/engine.mjs

@@ -14,7 +14,7 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.14.0";
+    ENGINE_VERSION = "2.16.0";
     SCHEMA_VERSION = 4;
     EXTRACTOR_VERSION = 10;
   }
@@ -8259,7 +8259,7 @@ var init_query = __esm({
 });
 
 // src/edit.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { join as join9 } from "path";
 function resolveUniqueSymbol(scan2, namePath, file) {
   let matches = findSymbol(scan2, namePath);
@@ -8273,7 +8273,7 @@ function resolveUniqueSymbol(scan2, namePath, file) {
   throw new Error(`"${namePath}" is ambiguous (${matches.length} matches: ${list}) \u2014 qualify with \`file\` or a Parent/name path`);
 }
 function readLines(abs) {
-  return readFileSync3(abs, "utf8").split("\n");
+  return readFileSync4(abs, "utf8").split("\n");
 }
 function replaceSymbolBody(scan2, namePath, body2, file) {
   const sym = resolveUniqueSymbol(scan2, namePath, file);
@@ -8317,7 +8317,7 @@ var init_edit = __esm({
 });
 
 // src/memory.ts
-import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync4, rmSync, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync5, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname3, join as join10 } from "path";
 function sanitize(name2) {
   const clean = name2.replace(/^mem:/, "").replace(/\.md$/, "");
@@ -8342,7 +8342,7 @@ function writeMemory(repo, name2, content) {
 }
 function readMemory(repo, name2) {
   try {
-    return readFileSync4(memoryPath(repo, name2), "utf8");
+    return readFileSync5(memoryPath(repo, name2), "utf8");
   } catch {
     return void 0;
   }
@@ -8354,7 +8354,7 @@ function deleteMemory(repo, name2) {
   } catch {
     return false;
   }
-  rmSync(path);
+  rmSync2(path);
   return true;
 }
 function listMemories(repo) {
@@ -8384,7 +8384,7 @@ var init_memory = __esm({
 });
 
 // src/workspaces.ts
-import { existsSync as existsSync2, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { existsSync as existsSync3, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
 import { join as join11 } from "path";
 function readJson(path, label, warnings) {
   const raw = readText(path);
@@ -8437,7 +8437,7 @@ function wsGlobToRegExp(pat) {
 }
 function probeNodePkg(root, dir, kind, warnings) {
   const path = join11(root, dir, "package.json");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const manifest = `${dir}/package.json`;
   const pkg = readJson(path, manifest, warnings);
   const out2 = {
@@ -8451,7 +8451,7 @@ function probeNodePkg(root, dir, kind, warnings) {
 }
 function probeCargo(root, dir) {
   const path = join11(root, dir, "Cargo.toml");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const body2 = tomlSectionBody(readText(path), "package");
   const out2 = {
     name: tomlString(body2, "name") ?? dir,
@@ -8465,18 +8465,18 @@ function probeCargo(root, dir) {
 }
 function probeGoMod(root, dir) {
   const path = join11(root, dir, "go.mod");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const name2 = readText(path).match(/^module\s+(\S+)/m)?.[1] ?? dir;
   return { name: name2, dir, kind: "go", manifest: `${dir}/go.mod` };
 }
 function probeMaven(root, dir) {
   const path = join11(root, dir, "pom.xml");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   return { name: ownArtifactId(readText(path)) ?? dir, dir, kind: "maven", manifest: `${dir}/pom.xml` };
 }
 function probePyproject(root, dir) {
   const path = join11(root, dir, "pyproject.toml");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const toml = readText(path);
   const project = tomlSectionBody(toml, "project");
   const poetry = tomlSectionBody(toml, "tool.poetry");
@@ -8492,7 +8492,7 @@ function probePyproject(root, dir) {
 }
 function probeComposer(root, dir, warnings) {
   const path = join11(root, dir, "composer.json");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const manifest = `${dir}/composer.json`;
   const pkg = readJson(path, manifest, warnings);
   const out2 = {
@@ -8506,7 +8506,7 @@ function probeComposer(root, dir, warnings) {
 }
 function probeNxProject(root, dir, warnings) {
   const path = join11(root, dir, "project.json");
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   const manifest = `${dir}/project.json`;
   const proj = readJson(path, manifest, warnings);
   return {
@@ -8518,7 +8518,7 @@ function probeNxProject(root, dir, warnings) {
 }
 function probeGradle(root, dir) {
   for (const f of ["build.gradle", "build.gradle.kts"]) {
-    if (existsSync2(join11(root, dir, f))) {
+    if (existsSync3(join11(root, dir, f))) {
       return { name: dir, dir, kind: "gradle", manifest: `${dir}/${f}` };
     }
   }
@@ -9565,7 +9565,7 @@ var init_grep = __esm({
 
 // src/embed/model.ts
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
 import { join as join13 } from "path";
 function resolveEmbedModelDir(repo) {
   const env = process.env.CODEINDEX_EMBED_DIR;
@@ -9574,7 +9574,7 @@ function resolveEmbedModelDir(repo) {
   if (repo) candidates.push(join13(repo, ".codeindex", DEFAULT_EMBED_DIRNAME));
   candidates.push(join13(process.cwd(), ".codeindex", DEFAULT_EMBED_DIRNAME));
   for (const c2 of candidates) {
-    if (existsSync3(join13(c2, "model.json"))) return c2;
+    if (existsSync4(join13(c2, "model.json"))) return c2;
   }
   return void 0;
 }
@@ -9608,8 +9608,8 @@ function parseEmbedModel(raw, source) {
 function loadEmbedModel(dir) {
   if (!dir) return void 0;
   const path = join13(dir, "model.json");
-  if (!existsSync3(path)) return void 0;
-  const raw = JSON.parse(readFileSync5(path, "utf8"));
+  if (!existsSync4(path)) return void 0;
+  const raw = JSON.parse(readFileSync6(path, "utf8"));
   return parseEmbedModel(raw, path);
 }
 function resolveEmbedPullUrl() {
@@ -10303,7 +10303,7 @@ __export(mcp_exports, {
   toCacheMap: () => toCacheMap,
   warmGrammarsForRepo: () => warmGrammarsForRepo
 });
-import { statSync as statSync4 } from "fs";
+import { readFileSync as readFileSync7, statSync as statSync4 } from "fs";
 import { join as join14 } from "path";
 import { createInterface } from "readline";
 function str(v) {
@@ -10357,6 +10357,57 @@ function toCacheMap(scan2) {
   for (const f of scan2.files) m.set(f.rel, { hash: f.hash, record: f, size: f.size, mtimeMs: scan2.mtimes.get(f.rel) });
   return m;
 }
+function readPersistedIndex(repo) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync7(join14(repo, ".codeindex", "cache.json"), "utf8"));
+  } catch {
+    return void 0;
+  }
+  if (!parsed || parsed.schemaVersion !== SCHEMA_VERSION || parsed.extractorVersion !== EXTRACTOR_VERSION || !parsed.files) {
+    return void 0;
+  }
+  const cacheMap = new Map(Object.entries(parsed.files));
+  const meta = {
+    engineVersion: parsed.engineVersion,
+    commit: parsed.commit,
+    graphSha1: parsed.graphSha1,
+    symbolsSha1: parsed.symbolsSha1
+  };
+  return { cacheMap, meta };
+}
+function preloadArtifacts(repo, scan2, meta) {
+  if (!scan2.contentUnchanged || meta.engineVersion !== ENGINE_VERSION || meta.commit !== scan2.commit || meta.graphSha1 === void 0 || meta.symbolsSha1 === void 0) {
+    return void 0;
+  }
+  const dir = join14(repo, ".codeindex");
+  let graphBytes;
+  let symbolsBytes;
+  try {
+    graphBytes = readFileSync7(join14(dir, "graph.json"));
+    symbolsBytes = readFileSync7(join14(dir, "symbols.json"));
+  } catch {
+    return void 0;
+  }
+  if (sha1(graphBytes) !== meta.graphSha1 || sha1(symbolsBytes) !== meta.symbolsSha1) {
+    return void 0;
+  }
+  try {
+    const graph = JSON.parse(graphBytes.toString("utf8"));
+    const symbols = JSON.parse(symbolsBytes.toString("utf8"));
+    if (graph.schemaVersion !== SCHEMA_VERSION || symbols.schemaVersion !== SCHEMA_VERSION) return void 0;
+    return { scan: scan2, graph, symbols };
+  } catch {
+    return void 0;
+  }
+}
+function preloadSession(repo, opts) {
+  const persisted = readPersistedIndex(repo);
+  if (!persisted) return void 0;
+  const scan2 = scanRepo(repo, { ...opts, cache: persisted.cacheMap });
+  const arts = preloadArtifacts(repo, scan2, persisted.meta);
+  return { scan: scan2, cacheMap: toCacheMap(scan2), arts };
+}
 function getScan(repo, opts = {}) {
   const key = sessionKey(repo, opts);
   if (sessionCache && sessionCache.key === key) {
@@ -10369,6 +10420,11 @@ function getScan(repo, opts = {}) {
     sessionCache = { key, scan: fresh, cacheMap: toCacheMap(fresh) };
     return fresh;
   }
+  const preloaded = preloadSession(repo, opts);
+  if (preloaded) {
+    sessionCache = { key, scan: preloaded.scan, cacheMap: preloaded.cacheMap, arts: preloaded.arts };
+    return preloaded.scan;
+  }
   const scan2 = scanRepo(repo, opts);
   sessionCache = { key, scan: scan2, cacheMap: toCacheMap(scan2) };
   return scan2;
@@ -11074,8 +11130,8 @@ init_loader();
 // src/ast/grammars-pull.ts
 init_types();
 import { createHash as createHash2 } from "crypto";
-import { mkdirSync, writeFileSync } from "fs";
-import { dirname as dirname2, resolve, sep as sep2 } from "path";
+import { existsSync as existsSync2, mkdirSync, mkdtempSync, readFileSync as readFileSync3, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname as dirname2, join as join3, resolve, sep as sep2 } from "path";
 import { gunzipSync } from "zlib";
 var DEFAULT_GRAMMARS_URL = `https://github.com/maxgfr/codeindex/releases/download/v${ENGINE_VERSION}/grammars-${ENGINE_VERSION}.tar.gz`;
 function resolveGrammarsPullTarget() {
@@ -11167,6 +11223,109 @@ function extractGrammarsTarball(bytes, destDir) {
   const raw = b.length >= 2 && b[0] === 31 && b[1] === 139 ? gunzipSync(b) : b;
   return extractTarInto(raw, destDir);
 }
+async function pullGrammars(cacheDir, opts = {}) {
+  const note = opts.onNote ?? (() => {
+  });
+  const target = resolveGrammarsPullTarget();
+  let expected;
+  if (target.sha256Url) {
+    try {
+      expected = await fetchExpectedSha256(target.sha256Url);
+    } catch (e) {
+      note(`codeindex: could not fetch checksum (${e instanceof Error ? e.message : String(e)}) \u2014 proceeding unverified
+`);
+    }
+  }
+  const runtime = join3(cacheDir, "web-tree-sitter.wasm");
+  const markerPath = join3(dirname2(cacheDir), `${ENGINE_VERSION}.sha256`);
+  if (existsSync2(runtime) && expected && existsSync2(markerPath)) {
+    let marker = "";
+    try {
+      marker = readFileSync3(markerPath, "utf8").trim();
+    } catch {
+    }
+    if (marker === expected) {
+      return { ok: true, status: "up-to-date", cacheDir, message: `codeindex: grammars already present at ${cacheDir} (up to date)
+` };
+    }
+  }
+  note(`codeindex: fetching grammars from ${target.url} \u2192 ${cacheDir}
+`);
+  let bytes;
+  try {
+    bytes = await fetchGrammarsTarball(target.url, expected);
+  } catch (e) {
+    return {
+      ok: false,
+      status: "failed",
+      cacheDir,
+      message: `codeindex: pull failed \u2014 ${e instanceof Error ? e.message : String(e)} (nothing written)
+`
+    };
+  }
+  let tmp;
+  try {
+    mkdirSync(dirname2(cacheDir), { recursive: true });
+    tmp = mkdtempSync(join3(dirname2(cacheDir), ".grammars-tmp-"));
+    extractGrammarsTarball(bytes, tmp);
+    if (!existsSync2(join3(tmp, "web-tree-sitter.wasm"))) {
+      throw new Error("archive is missing web-tree-sitter.wasm");
+    }
+    if (existsSync2(cacheDir)) rmSync(cacheDir, { recursive: true, force: true });
+    renameSync(tmp, cacheDir);
+    tmp = void 0;
+    if (expected) writeFileSync(markerPath, expected + "\n");
+  } catch (e) {
+    if (tmp) {
+      try {
+        rmSync(tmp, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    return {
+      ok: false,
+      status: "failed",
+      cacheDir,
+      message: `codeindex: pull failed \u2014 ${e instanceof Error ? e.message : String(e)} (nothing written)
+`
+    };
+  }
+  return { ok: true, status: "pulled", cacheDir, message: `codeindex: grammars extracted \u2192 ${cacheDir}
+` };
+}
+
+// src/ast/warm.ts
+init_loader();
+async function warmGrammars(opts = {}) {
+  const label = opts.label ?? "codeindex";
+  const notes = [];
+  const note = (msg) => {
+    notes.push(msg);
+    if (opts.onNote) opts.onNote(msg);
+    else process.stderr.write(msg);
+  };
+  const noPull = process.env.CODEINDEX_NO_GRAMMARS_PULL;
+  const mayPull = (opts.pull ?? true) && !(noPull && noPull.trim() && noPull !== "0");
+  const keys = [...opts.keys ?? allGrammarKeys()];
+  let pulled = false;
+  if (resolveGrammarsTier().tier === "none" && mayPull) {
+    note(`${label}: tree-sitter grammars not found locally \u2014 pulling them into the shared cache (once per machine)\u2026
+`);
+    const res = await pullGrammars(sharedGrammarsCacheDir(), { onNote: note });
+    note(res.message);
+    pulled = res.ok && res.status === "pulled";
+  }
+  await ensureGrammars(keys);
+  const tier = resolveGrammarsTier().tier;
+  const ready = keys.some((k) => grammarReady(k));
+  if (!ready) {
+    note(
+      `${label}: no tree-sitter grammars available (offline?) \u2014 extracting with the regex tier, so symbols and call sites are less precise. Run \`codeindex grammars pull\` once online to enable AST precision.
+`
+    );
+  }
+  return { tier, ready, pulled, notes };
+}
 
 // src/engine.ts
 init_resolve();
@@ -11450,8 +11609,8 @@ init_util();
 init_types();
 init_types();
 init_loader();
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync6, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname4, join as join15, resolve as resolve2 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { join as join15, resolve as resolve2 } from "path";
 init_pipeline();
 init_hash();
 init_graph_json();
@@ -11631,7 +11790,7 @@ async function runCli(argv) {
     return;
   }
   const flags2 = parseFlags(rest);
-  if (!existsSync4(flags2.repo)) throw new Error(`--repo path does not exist: ${flags2.repo}`);
+  if (!existsSync5(flags2.repo)) throw new Error(`--repo path does not exist: ${flags2.repo}`);
   const scans = !SCANLESS_COMMANDS.has(cmd) && !(cmd === "embed" && flags2.positional !== "build");
   let precomputedWalk;
   if (scans && !flags2.noAst) {
@@ -11651,7 +11810,7 @@ async function runCli(argv) {
     let cache;
     let meta = {};
     try {
-      const parsed = JSON.parse(readFileSync6(cachePath, "utf8"));
+      const parsed = JSON.parse(readFileSync8(cachePath, "utf8"));
       if (parsed.schemaVersion === SCHEMA_VERSION && parsed.extractorVersion === EXTRACTOR_VERSION) {
         cache = new Map(Object.entries(parsed.files));
         meta = {
@@ -11672,7 +11831,7 @@ async function runCli(argv) {
     const embedPath = join15(outDir, "embeddings.bin");
     const artifactSha = (path) => {
       try {
-        return sha1(readFileSync6(path));
+        return sha1(readFileSync8(path));
       } catch {
         return void 0;
       }
@@ -11892,7 +12051,7 @@ async function runCli(argv) {
     const cacheDir = sharedGrammarsCacheDir();
     if (sub === "status") {
       const info2 = resolveGrammarsTier();
-      const runtimePresent = info2.dir ? existsSync4(join15(info2.dir, "web-tree-sitter.wasm")) : false;
+      const runtimePresent = info2.dir ? existsSync5(join15(info2.dir, "web-tree-sitter.wasm")) : false;
       const target = resolveGrammarsPullTarget();
       const status = {
         engineVersion: ENGINE_VERSION,
@@ -11905,77 +12064,15 @@ async function runCli(argv) {
       };
       emit(JSON.stringify(status, null, 2) + "\n", flags2.out);
     } else if (sub === "pull") {
-      const target = resolveGrammarsPullTarget();
-      let expected;
-      if (target.sha256Url) {
-        try {
-          expected = await fetchExpectedSha256(target.sha256Url);
-        } catch (e) {
-          process.stderr.write(
-            `codeindex: could not fetch checksum (${e instanceof Error ? e.message : String(e)}) \u2014 proceeding unverified
-`
-          );
-        }
-      }
-      const runtime = join15(cacheDir, "web-tree-sitter.wasm");
-      const markerPath = join15(dirname4(cacheDir), `${ENGINE_VERSION}.sha256`);
-      if (existsSync4(runtime) && expected && existsSync4(markerPath)) {
-        let marker = "";
-        try {
-          marker = readFileSync6(markerPath, "utf8").trim();
-        } catch {
-        }
-        if (marker === expected) {
-          process.stderr.write(`codeindex: grammars already present at ${cacheDir} (up to date)
-`);
-          return;
-        }
-      }
-      process.stderr.write(`codeindex: fetching grammars from ${target.url} \u2192 ${cacheDir}
-`);
-      let bytes;
-      try {
-        bytes = await fetchGrammarsTarball(target.url, expected);
-      } catch (e) {
-        process.stderr.write(`codeindex: pull failed \u2014 ${e instanceof Error ? e.message : String(e)} (nothing written)
-`);
-        process.exitCode = 1;
-        return;
-      }
-      let tmp;
-      try {
-        mkdirSync3(dirname4(cacheDir), { recursive: true });
-        tmp = mkdtempSync(join15(dirname4(cacheDir), ".grammars-tmp-"));
-        extractGrammarsTarball(bytes, tmp);
-        if (!existsSync4(join15(tmp, "web-tree-sitter.wasm"))) {
-          throw new Error("archive is missing web-tree-sitter.wasm");
-        }
-        if (existsSync4(cacheDir)) rmSync2(cacheDir, { recursive: true, force: true });
-        renameSync(tmp, cacheDir);
-        tmp = void 0;
-        if (expected) writeFileSync4(markerPath, expected + "\n");
-      } catch (e) {
-        if (tmp) {
-          try {
-            rmSync2(tmp, { recursive: true, force: true });
-          } catch {
-          }
-        }
-        process.stderr.write(
-          `codeindex: pull failed \u2014 ${e instanceof Error ? e.message : String(e)} (nothing written)
-`
-        );
-        process.exitCode = 1;
-        return;
-      }
-      process.stderr.write(`codeindex: grammars extracted \u2192 ${cacheDir}
-`);
+      const res = await pullGrammars(cacheDir, { onNote: (m) => process.stderr.write(m) });
+      process.stderr.write(res.message);
+      if (!res.ok) process.exitCode = 1;
     } else {
       throw new Error("grammars needs a subcommand: status | pull");
     }
   } else if (cmd === "rules") {
     if (!flags2.config) throw new Error("rules needs --config <codeindex.rules.json>");
-    const rules = parseRules(JSON.parse(readFileSync6(flags2.config, "utf8")));
+    const rules = parseRules(JSON.parse(readFileSync8(flags2.config, "utf8")));
     const { graph } = buildIndexArtifacts(flags2.repo, scanOptions(flags2, precomputedWalk));
     const violations = checkRules(graph, rules);
     const errors = violations.filter((v) => v.severity === "error").length;
@@ -12126,6 +12223,7 @@ export {
   parseGitignore,
   parseRules,
   probeEndpoint,
+  pullGrammars,
   quantize,
   rankHotspots,
   rankedKeywords,
@@ -12172,6 +12270,7 @@ export {
   untestedModules,
   untrackedFiles,
   walk,
+  warmGrammars,
   wordpiece,
   writeMemory
 };

package/src/ast/grammars-pull.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { gunzipSync } from "node:zlib";
 import { ENGINE_VERSION } from "../types.js";
@@ -176,3 +176,97 @@ export function extractGrammarsTarball(bytes: Uint8Array, destDir: string): stri
   const raw = b.length >= 2 && b[0] === 0x1f && b[1] === 0x8b ? gunzipSync(b) : b;
   return extractTarInto(raw, destDir);
 }
+
+// What a pull did. `status` distinguishes the three terminal states so a caller
+// can react without parsing prose: nothing to do, wasms installed, or failed
+// (and on failure NOTHING was written — the cache is exactly as it was).
+export interface GrammarsPullResult {
+  ok: boolean;
+  status: "up-to-date" | "pulled" | "failed";
+  cacheDir: string;
+  /** One human-readable line; the CLI writes it to stderr, a library caller may log or drop it. */
+  message: string;
+}
+
+// The whole `grammars pull` mechanic — resolve target, fetch the sha256 sidecar,
+// skip when the cache already holds that exact digest, download, then install
+// ATOMICALLY (extract into a tmp sibling, verify the runtime wasm landed, swap
+// by rename). Extracted from the CLI so `warmGrammars` and `codeindex grammars
+// pull` share ONE implementation: the CLI maps the result onto stderr +
+// process.exitCode, the warm path folds it into its own report.
+//
+// NEVER throws: every failure becomes `{ ok: false, status: "failed" }` with a
+// message, because both callers must survive an offline machine — the engine
+// simply stays on the regex tier. `onNote` receives progress lines (checksum
+// degradation, download start) that are not the terminal message.
+export async function pullGrammars(
+  cacheDir: string,
+  opts: { onNote?: (msg: string) => void } = {},
+): Promise<GrammarsPullResult> {
+  const note = opts.onNote ?? (() => {});
+  const target = resolveGrammarsPullTarget();
+  let expected: string | undefined;
+  if (target.sha256Url) {
+    try {
+      expected = await fetchExpectedSha256(target.sha256Url);
+    } catch (e) {
+      note(`codeindex: could not fetch checksum (${e instanceof Error ? e.message : String(e)}) — proceeding unverified\n`);
+    }
+  }
+  // Idempotent: the marker sibling records the digest of the tarball that
+  // populated cacheDir. Runtime wasm present AND marker === freshly-fetched
+  // digest ⇒ already up to date, skip the ~22 MB download.
+  const runtime = join(cacheDir, "web-tree-sitter.wasm");
+  const markerPath = join(dirname(cacheDir), `${ENGINE_VERSION}.sha256`);
+  if (existsSync(runtime) && expected && existsSync(markerPath)) {
+    let marker = "";
+    try {
+      marker = readFileSync(markerPath, "utf8").trim();
+    } catch {
+      // unreadable marker → fall through and re-pull
+    }
+    if (marker === expected) {
+      return { ok: true, status: "up-to-date", cacheDir, message: `codeindex: grammars already present at ${cacheDir} (up to date)\n` };
+    }
+  }
+  note(`codeindex: fetching grammars from ${target.url} → ${cacheDir}\n`);
+  let bytes: Uint8Array;
+  try {
+    bytes = await fetchGrammarsTarball(target.url, expected);
+  } catch (e) {
+    return {
+      ok: false,
+      status: "failed",
+      cacheDir,
+      message: `codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`,
+    };
+  }
+  let tmp: string | undefined;
+  try {
+    mkdirSync(dirname(cacheDir), { recursive: true });
+    tmp = mkdtempSync(join(dirname(cacheDir), ".grammars-tmp-"));
+    extractGrammarsTarball(bytes, tmp);
+    if (!existsSync(join(tmp, "web-tree-sitter.wasm"))) {
+      throw new Error("archive is missing web-tree-sitter.wasm");
+    }
+    if (existsSync(cacheDir)) rmSync(cacheDir, { recursive: true, force: true });
+    renameSync(tmp, cacheDir);
+    tmp = undefined;
+    if (expected) writeFileSync(markerPath, expected + "\n");
+  } catch (e) {
+    if (tmp) {
+      try {
+        rmSync(tmp, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    return {
+      ok: false,
+      status: "failed",
+      cacheDir,
+      message: `codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`,
+    };
+  }
+  return { ok: true, status: "pulled", cacheDir, message: `codeindex: grammars extracted → ${cacheDir}\n` };
+}

package/src/ast/warm.ts

@@ -0,0 +1,74 @@
+import { allGrammarKeys, ensureGrammars, grammarReady, resolveGrammarsTier, sharedGrammarsCacheDir } from "./loader.js";
+import type { GrammarsTierName } from "./loader.js";
+import { pullGrammars } from "./grammars-pull.js";
+
+// The one-call AST warm-up every consumer needs, and which every consumer but
+// ultraindex was missing.
+//
+// WHY THIS EXISTS. Extraction is AST-preferred with a regex fallback
+// (src/extract/code.ts), but `extractAst` returns undefined unless
+// `grammarReady(key)` — and that is only true after an `await ensureGrammars()`.
+// `scanRepo` is deliberately synchronous, so it CANNOT warm anything itself.
+// A consumer that never awaits the warm-up therefore runs on the regex tier
+// forever, on every machine, no matter what the grammar cache holds — silently,
+// since the fallback is by design invisible. That is a capability quietly left
+// on the table, not a crash, which is exactly why it survived unnoticed.
+//
+// So: call this ONCE at your CLI entry, before the synchronous pipeline. It is
+// idempotent, offline-safe, and never throws.
+export interface WarmGrammarsResult {
+  /** Tier AFTER the warm-up (a successful pull moves "none" → "cache"). */
+  tier: GrammarsTierName;
+  /** True when at least one requested grammar is loaded ⇒ the AST tier is live. */
+  ready: boolean;
+  /** True when this call populated the shared cache over the network. */
+  pulled: boolean;
+  /** Everything written to `onNote`, in order — so a caller can persist the trail in its run artifacts. */
+  notes: string[];
+}
+
+export interface WarmGrammarsOptions {
+  /** Grammars to load. Default: every shipped grammar. Narrow it with `grammarKeysForExts` when the repo's languages are known. */
+  keys?: Iterable<string>;
+  /** Fetch the wasms into the shared cache when nothing is resolvable. Default true; `CODEINDEX_NO_GRAMMARS_PULL=1` forces false. */
+  pull?: boolean;
+  /** Prefix for the diagnostics ("ultrasec: …"). Default "codeindex". */
+  label?: string;
+  /** Where diagnostics go. Default: process.stderr. Pass a sink to keep stdout/stderr clean. */
+  onNote?: (msg: string) => void;
+}
+
+export async function warmGrammars(opts: WarmGrammarsOptions = {}): Promise<WarmGrammarsResult> {
+  const label = opts.label ?? "codeindex";
+  const notes: string[] = [];
+  const note = (msg: string): void => {
+    notes.push(msg);
+    if (opts.onNote) opts.onNote(msg);
+    else process.stderr.write(msg);
+  };
+  const noPull = process.env.CODEINDEX_NO_GRAMMARS_PULL;
+  const mayPull = (opts.pull ?? true) && !(noPull && noPull.trim() && noPull !== "0");
+  const keys = [...(opts.keys ?? allGrammarKeys())];
+
+  let pulled = false;
+  if (resolveGrammarsTier().tier === "none" && mayPull) {
+    note(`${label}: tree-sitter grammars not found locally — pulling them into the shared cache (once per machine)…\n`);
+    const res = await pullGrammars(sharedGrammarsCacheDir(), { onNote: note });
+    note(res.message);
+    pulled = res.ok && res.status === "pulled";
+  }
+
+  await ensureGrammars(keys);
+
+  const tier = resolveGrammarsTier().tier;
+  const ready = keys.some((k) => grammarReady(k));
+  if (!ready) {
+    // Never silent: a degraded run must say so, and stay a SUCCESSFUL run —
+    // the regex tier still produces a complete, searchable result.
+    note(
+      `${label}: no tree-sitter grammars available (offline?) — extracting with the regex tier, so symbols and call sites are less precise. ` +
+        "Run `codeindex grammars pull` once online to enable AST precision.\n",
+    );
+  }
+  return { tier, ready, pulled, notes };
+}

package/src/engine-cli.ts

@@ -3,12 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { SCHEMA_VERSION, EXTRACTOR_VERSION, type FileRecord } from "./types.js";
 import { ENGINE_VERSION } from "./types.js";
 import { ensureGrammars, grammarKeysForExts, resolveGrammarsTier, sharedGrammarsCacheDir } from "./ast/loader.js";
-import {
-  resolveGrammarsPullTarget,
-  fetchGrammarsTarball,
-  fetchExpectedSha256,
-  extractGrammarsTarball,
-} from "./ast/grammars-pull.js";
+import { resolveGrammarsPullTarget, pullGrammars } from "./ast/grammars-pull.js";
 import { buildIndexArtifacts, buildArtifactsFromScan, type BuildIndexOptions } from "./pipeline.js";
 import { sha1 } from "./hash.js";
 import { renderGraphJson } from "./render/graph-json.js";
@@ -593,81 +588,14 @@ export async function runCli(argv: string[]): Promise<void> {
       };
       emit(JSON.stringify(status, null, 2) + "\n", flags.out);
     } else if (sub === "pull") {
-      // Default: the official per-release asset + its `.sha256` sidecar. A
-      // user-set CODEINDEX_GRAMMARS_URL overrides both (mirror/custom, no
-      // verification). Fetch the expected digest from the sidecar first; a
-      // missing sidecar degrades to an unverified pull with a note (never fatal).
-      const target = resolveGrammarsPullTarget();
-      let expected: string | undefined;
-      if (target.sha256Url) {
-        try {
-          expected = await fetchExpectedSha256(target.sha256Url);
-        } catch (e) {
-          process.stderr.write(
-            `codeindex: could not fetch checksum (${e instanceof Error ? e.message : String(e)}) — proceeding unverified\n`,
-          );
-        }
-      }
-      // Idempotent: the marker sibling records the digest of the tarball that
-      // populated cacheDir. If the runtime wasm is present AND the marker matches
-      // the freshly-fetched digest, the cache is already up to date — skip the
-      // ~22 MB download entirely. (Keeps cacheDir itself byte-identical to the
-      // tarball; the marker lives next to it, never inside it.)
-      const runtime = join(cacheDir, "web-tree-sitter.wasm");
-      const markerPath = join(dirname(cacheDir), `${ENGINE_VERSION}.sha256`);
-      if (existsSync(runtime) && expected && existsSync(markerPath)) {
-        let marker = "";
-        try {
-          marker = readFileSync(markerPath, "utf8").trim();
-        } catch {
-          // unreadable marker → fall through and re-pull
-        }
-        if (marker === expected) {
-          process.stderr.write(`codeindex: grammars already present at ${cacheDir} (up to date)\n`);
-          return;
-        }
-      }
-      process.stderr.write(`codeindex: fetching grammars from ${target.url} → ${cacheDir}\n`);
-      let bytes: Uint8Array;
-      try {
-        // Follows redirects (GitHub → CDN) and verifies sha256 when known.
-        bytes = await fetchGrammarsTarball(target.url, expected);
-      } catch (e) {
-        process.stderr.write(`codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`);
-        process.exitCode = 1;
-        return;
-      }
-      // Atomic install: extract into a tmp dir SIBLING to cacheDir (same
-      // filesystem → rename is atomic), sanity-check the runtime wasm landed,
-      // then swap it into place. A failure at any step discards the tmp dir and
-      // leaves any existing cache untouched — a half-populated cache never shows.
-      let tmp: string | undefined;
-      try {
-        mkdirSync(dirname(cacheDir), { recursive: true });
-        tmp = mkdtempSync(join(dirname(cacheDir), ".grammars-tmp-"));
-        extractGrammarsTarball(bytes, tmp);
-        if (!existsSync(join(tmp, "web-tree-sitter.wasm"))) {
-          throw new Error("archive is missing web-tree-sitter.wasm");
-        }
-        if (existsSync(cacheDir)) rmSync(cacheDir, { recursive: true, force: true });
-        renameSync(tmp, cacheDir);
-        tmp = undefined;
-        if (expected) writeFileSync(markerPath, expected + "\n");
-      } catch (e) {
-        if (tmp) {
-          try {
-            rmSync(tmp, { recursive: true, force: true });
-          } catch {
-            // best-effort cleanup
-          }
-        }
-        process.stderr.write(
-          `codeindex: pull failed — ${e instanceof Error ? e.message : String(e)} (nothing written)\n`,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      process.stderr.write(`codeindex: grammars extracted → ${cacheDir}\n`);
+      // The mechanic itself (sidecar checksum, idempotent skip, atomic install)
+      // lives in pullGrammars — shared verbatim with warmGrammars, so the CLI
+      // and the library warm-up can never drift apart. Here we only map its
+      // result onto the CLI contract: progress notes and the terminal message to
+      // stderr, non-zero exit on failure (which wrote nothing).
+      const res = await pullGrammars(cacheDir, { onNote: (m) => process.stderr.write(m) });
+      process.stderr.write(res.message);
+      if (!res.ok) process.exitCode = 1;
     } else {
       throw new Error("grammars needs a subcommand: status | pull");
     }

package/src/engine.ts

@@ -60,8 +60,14 @@ export {
   fetchExpectedSha256,
   extractTarInto,
   extractGrammarsTarball,
+  pullGrammars,
 } from "./ast/grammars-pull.js";
-export type { GrammarsPullTarget } from "./ast/grammars-pull.js";
+export type { GrammarsPullTarget, GrammarsPullResult } from "./ast/grammars-pull.js";
+// The one-call AST warm-up for consumers. `scanRepo` is synchronous and cannot
+// warm the grammars itself, so a consumer that never awaits this stays on the
+// regex tier forever — silently. Call it once at the CLI entry.
+export { warmGrammars } from "./ast/warm.js";
+export type { WarmGrammarsResult, WarmGrammarsOptions } from "./ast/warm.js";
 
 // Resolution + modules + graph tier.
 export { buildResolveContext, resolveImport, resolveDocLink } from "./resolve.js";

package/src/mcp.ts

@@ -5,10 +5,10 @@
 // `repo` path and returns JSON text content.
 //
 // Register in an MCP client as:  node scripts/engine.mjs mcp
-import { statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
-import { ENGINE_VERSION, type FileRecord } from "./types.js";
+import { ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION, type FileRecord, type Graph, type SymbolIndex } from "./types.js";
 import { ensureGrammars, grammarKeysForExts } from "./ast/loader.js";
 import { buildArtifactsFromScan, type IndexArtifacts } from "./pipeline.js";
 import { renderGraphJson } from "./render/graph-json.js";
@@ -419,7 +419,8 @@ export function memoizedEmbedModel(modelDir: string): StaticEmbedModel | undefin
 // and a caller-supplied stale walk would desynchronize the freshness oracle.
 export type SessionScanOptions = Omit<ScanOptions, "cache" | "precomputedWalk">;
 
-type SessionCacheMap = Map<string, { hash: string; record: FileRecord; size?: number; mtimeMs?: number }>;
+type SessionCacheEntry = { hash: string; record: FileRecord; size?: number; mtimeMs?: number };
+type SessionCacheMap = Map<string, SessionCacheEntry>;
 
 // A SINGLE entry — never an unbounded map — holding the most recent scan.
 let sessionCache:
@@ -457,6 +458,128 @@ export function toCacheMap(scan: RepoScan): SessionCacheMap {
   return m;
 }
 
+// --- persisted-index preload -------------------------------------------------
+// On the FIRST tool call for a repo, a committed .codeindex/ index (written by
+// `codeindex index`) lets the session skip work TWO ways. cache.json seeds the
+// session scan, so every unchanged file takes scan.ts's stat fastpath instead
+// of a read + hash + extraction; and — only when the T4 freshness guard holds —
+// the persisted graph.json/symbols.json are deserialized straight into the
+// session, so the first graph/symbols/mermaid/repo_map/check_rules call skips
+// the whole downstream pipeline (buildArtifactsFromScan). Both are pure
+// optimizations: the seeded scan's reused records are value-identical to a cold
+// scan's (T3/T4 determinism), and the guard is the SAME oracle the CLI's index
+// fastpath uses to prove the on-disk artifacts equal a fresh build here. Absent,
+// stale, corrupt, or any version/commit/sha mismatch → every step falls back to
+// today's cold path EXACTLY (a fresh scanRepo / buildArtifactsFromScan), never a
+// throw.
+
+// ADDITIVE cache.json meta describing the artifacts a prior `index` run wrote
+// (see engine-cli.ts's CacheMeta). Old caches lacking these keys simply never
+// pass the guard below — their per-file records are still reused to seed the
+// scan. Only the graph/symbols shas matter here; the embed sidecar has its own
+// memoization path.
+interface PersistedMeta {
+  engineVersion?: string;
+  commit?: string;
+  graphSha1?: string;
+  symbolsSha1?: string;
+}
+
+// Read <repo>/.codeindex/cache.json into the (cacheMap, meta) the preload needs.
+// Per-file records are reusable ONLY when (schemaVersion, extractorVersion)
+// match this engine — the exact gate the CLI applies before trusting a cache —
+// otherwise the whole cache is discarded (cold scan). Any read/parse failure (no
+// index yet, unreadable, malformed) returns undefined: the cold path.
+function readPersistedIndex(repo: string): { cacheMap: SessionCacheMap; meta: PersistedMeta } | undefined {
+  let parsed:
+    | ({ schemaVersion?: number; extractorVersion?: number; files?: Record<string, SessionCacheEntry> } & PersistedMeta)
+    | undefined;
+  try {
+    parsed = JSON.parse(readFileSync(join(repo, ".codeindex", "cache.json"), "utf8")) as typeof parsed;
+  } catch {
+    return undefined;
+  }
+  if (!parsed || parsed.schemaVersion !== SCHEMA_VERSION || parsed.extractorVersion !== EXTRACTOR_VERSION || !parsed.files) {
+    return undefined;
+  }
+  const cacheMap: SessionCacheMap = new Map(Object.entries(parsed.files));
+  const meta: PersistedMeta = {
+    engineVersion: parsed.engineVersion,
+    commit: parsed.commit,
+    graphSha1: parsed.graphSha1,
+    symbolsSha1: parsed.symbolsSha1,
+  };
+  return { cacheMap, meta };
+}
+
+// The T4 freshness guard, applied to a session scan seeded from cache.json:
+// contentUnchanged proves this scan's records are the ones that built the
+// on-disk artifacts; engineVersion pins the version stamp graph.json embeds and
+// commit the HEAD it embeds; the sha checks prove the on-disk bytes ARE that
+// build's output. All true ⇒ graph.json/symbols.json are byte-equal to
+// buildArtifactsFromScan(scan) run here, so deserialize them instead of
+// rebuilding. Graph/SymbolIndex are pure JSON POJOs (no Map/Set/typed fields),
+// so JSON.parse is a lossless round-trip — a schemaVersion assert is the only
+// reconstruction needed (see the round-trip test). ANY failure — a stale scan,
+// a version/commit/sha mismatch, a missing/corrupt/partial artifact, an
+// unexpected schemaVersion — returns undefined so the caller rebuilds. NEVER
+// throws (a corrupt artifact must degrade, not crash the session).
+function preloadArtifacts(repo: string, scan: RepoScan, meta: PersistedMeta): IndexArtifacts | undefined {
+  if (
+    !scan.contentUnchanged ||
+    meta.engineVersion !== ENGINE_VERSION ||
+    meta.commit !== scan.commit ||
+    meta.graphSha1 === undefined ||
+    meta.symbolsSha1 === undefined
+  ) {
+    return undefined;
+  }
+  const dir = join(repo, ".codeindex");
+  let graphBytes: Buffer;
+  let symbolsBytes: Buffer;
+  try {
+    graphBytes = readFileSync(join(dir, "graph.json"));
+    symbolsBytes = readFileSync(join(dir, "symbols.json"));
+  } catch {
+    return undefined; // a sha'd artifact went missing since cache.json — rebuild
+  }
+  // sha over the raw bytes; sha1(string) hashes the same UTF-8 bytes writeFileSync
+  // put on disk, so this equals the meta sha the CLI computed over the render.
+  if (sha1(graphBytes) !== meta.graphSha1 || sha1(symbolsBytes) !== meta.symbolsSha1) {
+    return undefined; // tampered / partial / corrupt on-disk bytes — rebuild
+  }
+  try {
+    const graph = JSON.parse(graphBytes.toString("utf8")) as Graph;
+    const symbols = JSON.parse(symbolsBytes.toString("utf8")) as SymbolIndex;
+    if (graph.schemaVersion !== SCHEMA_VERSION || symbols.schemaVersion !== SCHEMA_VERSION) return undefined;
+    return { scan, graph, symbols };
+  } catch {
+    // Unreachable once the shas matched (the bytes are valid JSON this engine
+    // wrote), but the contract is "never throw" — degrade to a rebuild.
+    return undefined;
+  }
+}
+
+// First-touch preload: seed the session scan from cache.json and, when the guard
+// holds, the artifacts from graph.json/symbols.json. undefined ⇒ no persisted
+// index ⇒ the caller takes the cold scanRepo path unchanged.
+function preloadSession(
+  repo: string,
+  opts: SessionScanOptions,
+): { scan: RepoScan; cacheMap: SessionCacheMap; arts?: IndexArtifacts } | undefined {
+  const persisted = readPersistedIndex(repo);
+  if (!persisted) return undefined;
+  // Seed the scan from the persisted records — scan.ts's stat fastpath + exact
+  // content-hash reuse make this value-identical to a cold scan (T3/T4), only
+  // cheaper, and it computes the contentUnchanged the artifact guard reads. When
+  // the on-disk content drifted from cache.json, changed files are re-read/
+  // extracted here exactly as a cold scan would, so the scan stays correct and
+  // the guard simply fails (arts undefined → rebuild on demand).
+  const scan = scanRepo(repo, { ...opts, cache: persisted.cacheMap });
+  const arts = preloadArtifacts(repo, scan, persisted.meta);
+  return { scan, cacheMap: toCacheMap(scan), arts };
+}
+
 // The memoizing replacement for scanRepo inside callTool. Exported for tests.
 export function getScan(repo: string, opts: SessionScanOptions = {}): RepoScan {
   const key = sessionKey(repo, opts);
@@ -486,6 +609,15 @@ export function getScan(repo: string, opts: SessionScanOptions = {}): RepoScan {
     sessionCache = { key, scan: fresh, cacheMap: toCacheMap(fresh) };
     return fresh;
   }
+  // First touch of this (repo, opts): try the persisted-index preload before a
+  // cold scan. A present, version-compatible .codeindex/cache.json seeds the
+  // scan (and, when the guard holds, the artifacts); absent it, fall through to
+  // the cold path EXACTLY as before.
+  const preloaded = preloadSession(repo, opts);
+  if (preloaded) {
+    sessionCache = { key, scan: preloaded.scan, cacheMap: preloaded.cacheMap, arts: preloaded.arts };
+    return preloaded.scan;
+  }
   const scan = scanRepo(repo, opts);
   sessionCache = { key, scan, cacheMap: toCacheMap(scan) };
   return scan;

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.14.0";
+export const ENGINE_VERSION = "2.16.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