codedeep-mcp 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ An MCP server that gives AI coding agents structural understanding of codebases.
 
 **One tool call replaces 5-10 Grep-Read cycles.**
 
-codedeep-mcp parses your code with [tree-sitter](https://tree-sitter.github.io/tree-sitter/), builds a symbol index, and exposes 6 tools over the [Model Context Protocol](https://modelcontextprotocol.io/) that answer structural questions directly: find symbols, trace callers, assess blast radius, search by structure.
+codedeep-mcp parses your code with [tree-sitter](https://tree-sitter.github.io/tree-sitter/), builds a symbol index, and exposes 9 tools over the [Model Context Protocol](https://modelcontextprotocol.io/): 6 read-only structural tools that answer questions directly (find symbols, trace callers, assess blast radius, search by structure) plus a 3-tool agent-curated knowledge layer (`remember` / `recall` / `forget`) whose notes are **staleness-tracked** against your source — when anchored code changes, the note is flagged instead of rotting silently.
 
 ## Why
 
@@ -32,6 +32,9 @@ codedeep-mcp solves this by parsing code into symbols and relationships, then an
 | `find_references` | Cross-file usage search | Who calls this function, and from where? |
 | `impact` | Depth-N blast radius | Transitive upstream callers, grouped by hop |
 | `search_structure` | Keyword and structural search | Find by name/signature (all languages), or AST pattern (TS/JS) |
+| `remember` | Store a durable, anchored note | Cross-file invariants, footguns, decisions — anchored to files/symbols |
+| `recall` | Retrieve notes with freshness | Each note tagged ✓ fresh / ⚠ stale by re-checking its anchors |
+| `forget` | Delete a note | Remove superseded or wrong knowledge |
 
 ## Quick Start
 
@@ -63,7 +66,6 @@ Any MCP client that supports stdio transport works. Configure it to run `npx cod
 Your Code  ──>  tree-sitter (parse)  ──>  In-Memory Index  ──>  MCP Tools
                                                │
                                           Git (optional)
-                                          LSP (planned)
 ```
 
 **Structural index (always, instant):**
@@ -83,10 +85,22 @@ Commit frequency identifies hotspot files; co-change analysis reveals
 behavioral coupling (files that change together); and a risk score
 (churn × coupling × complexity) ranks the most change-prone, tangled hubs.
 
-**Planned — LSP semantic tier:**
-LSP integration (tsserver, pyright, gopls, …) for compiler-precise
-cross-file references and type info is designed but **not yet shipped** —
-cross-file edges today are AST name-matches.
+**Agent-curated knowledge layer (staleness-tracked):**
+`remember` anchors durable notes to files/symbols and snapshots a content
+baseline; `recall` re-checks each anchor against the current source and tags
+every note ✓ fresh / ⚠ stale / ✗ missing — so an agent's accumulated knowledge
+is verified at read time instead of rotting silently. Anchored notes also
+surface **inline**: `get_context` renders the notes anchored to the symbol or
+file being read (staleness-checked, budget-capped), and `overview` reports how
+much knowledge is stored — the agent meets its own notes where it's already
+looking, without having to ask. Notes are stored in the local `.codedeep`
+cache, never written into your source.
+
+**Honest confidence, by design:**
+Cross-file edges are AST-derived name-matches with confidence tiers, not
+compiler-verified references — every approximate row is tagged (e.g.
+`[name match, unverified]`, `[behavioral]`) so an agent knows what to
+trust and what to verify before asserting.
 
 ## Example
 
@@ -139,8 +153,9 @@ cyclomatic + cognitive complexity:
 TypeScript / JS · Python · Java · Go · Rust · Swift · Kotlin · Dart · C# ·
 PHP · Ruby · C++ · C · Objective-C
 
-A planned LSP tier (see *How It Works*) will add compiler-precise cross-file
-resolution per language.
+Cross-file references are AST name-matches with per-row confidence tags (see
+*How It Works*) — precision-tuned per language against real-repo corpora with
+an explicit 0-wrong-kind-edge goal.
 
 ## Configuration
 

package/dist/config.js

@@ -3,7 +3,7 @@ import { constants as fsConstants, readFileSync } from 'node:fs';
 import { access, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { toPosix } from './indexer/scanner.js';
+import { toPosix } from './fs-util.js';
 import { errMsg, log } from './logger.js';
 const DEFAULT_EXCLUDES = [
     'node_modules',

package/dist/fs-util.js

@@ -0,0 +1,48 @@
+// Neutral filesystem helpers with no layer above them: used by the indexer
+// (scanner/pipeline/watcher), config resolution, the tools layer, AND the
+// notes layer. They live here — not in tools/common.ts or indexer/scanner.ts —
+// so lower layers (notes/, config.ts) never import from a higher one just to
+// read a file or normalize a separator.
+import { promises as fs } from 'node:fs';
+import { join, sep } from 'node:path';
+export function toPosix(p) {
+    return sep === '/' ? p : p.split(sep).join('/');
+}
+// projectRoot is fixed for the process lifetime, so its realpath is too —
+// caching it spares one syscall per safeReadIndexedFile call (pattern
+// scans call this once per candidate file).
+const realRootCache = new Map();
+async function realProjectRoot(projectRoot) {
+    let cached = realRootCache.get(projectRoot);
+    if (cached === undefined) {
+        cached = await fs.realpath(projectRoot);
+        realRootCache.set(projectRoot, cached);
+    }
+    return cached;
+}
+// Re-check scanner admission rules at read time so stale on-disk
+// state (symlink-swap, growth past cap, became-directory) can't
+// bypass the indexer's contract.
+export async function safeReadIndexedFile(relPath, config) {
+    const abs = join(config.projectRoot, relPath);
+    const stats = await fs.lstat(abs);
+    if (stats.isSymbolicLink()) {
+        throw new Error('refusing to follow symlink');
+    }
+    if (!stats.isFile()) {
+        throw new Error('not a regular file');
+    }
+    if (stats.size > config.maxFileSize) {
+        throw new Error(`exceeds maxFileSize (${stats.size} > ${config.maxFileSize})`);
+    }
+    // lstat only checks the final component. Resolve parent-directory
+    // symlinks so a swap higher up in the path can't escape projectRoot.
+    const [real, realRoot] = await Promise.all([
+        fs.realpath(abs),
+        realProjectRoot(config.projectRoot),
+    ]);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new Error('path escapes project root');
+    }
+    return fs.readFile(abs, 'utf8');
+}

package/dist/git/git-service.js

@@ -53,6 +53,7 @@ export class GitService {
     generationValue = 0;
     branchMemo = null;
     recentMemo = new Map();
+    headMemo = null;
     // Single-flight: a refresh requested while one is running coalesces
     // into exactly one trailing rerun.
     inFlight = null;
@@ -333,6 +334,7 @@ export class GitService {
         this.generationValue++;
         this.branchMemo = null;
         this.recentMemo.clear();
+        this.headMemo = null; // per-generation like its siblings; clear on HEAD move
     }
     async branchSummary() {
         if (this.closed)
@@ -557,6 +559,31 @@ export class GitService {
         this.recentMemo.set(memoKey, { gen, value });
         return value;
     }
+    // Short HEAD sha at the current generation, or null off-git / on transient
+    // failure. Used by `remember` to stamp a note's provenance ("noted at commit
+    // X"). Generation-memoized like recentCommits/branchSummary, so a HEAD move
+    // (the logs/HEAD watcher bumps the generation) invalidates it. Never throws.
+    async currentHead() {
+        if (this.closed)
+            return null;
+        this.maybeRetryStartup();
+        if (this.stateValue !== 'ready')
+            return null;
+        if (this.headMemo && this.headMemo.gen === this.generationValue) {
+            return this.headMemo.value;
+        }
+        const gen = this.generationValue;
+        const { out } = await this.probe(['rev-parse', '--short', 'HEAD'], {
+            timeoutMs: QUICK_TIMEOUT_MS,
+        });
+        // null = unborn HEAD or a transient failure: return null WITHOUT memoizing
+        // so the next call retries (mirrors recentCommits).
+        if (out === null)
+            return null;
+        const value = out.trim().length > 0 ? out.trim() : null;
+        this.headMemo = { gen, value };
+        return value;
+    }
     // Shutdown: kill in-flight children, never await the analysis — the
     // 10s shutdown watchdog must not ride on a git subprocess.
     close() {

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { join } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig, resolveCacheDir } from "./config.js";
 import { GitService } from "./git/git-service.js";
@@ -6,6 +7,7 @@ import { CodeIndex } from "./indexer/code-index.js";
 import { Indexer } from "./indexer/pipeline.js";
 import { Watcher } from "./indexer/watcher.js";
 import { errMsg, log } from "./logger.js";
+import { NoteStore } from "./notes/note-store.js";
 import { createServer } from "./server.js";
 let initial;
 try {
@@ -64,6 +66,18 @@ if (config.watch) {
 // .catch makes the chain unrejectable — one line, one error path.
 const git = new GitService(config, index, indexer.cachePath);
 void indexingPromise.catch(() => { }).then(() => git.start());
+// The note store is independent of the code index (notes are primary,
+// non-rebuildable user data, NOT derived from source), so it survives every
+// index invalidation. It sits next to index.json under the resolved cacheDir,
+// inheriting the read-only-root ~/.cache fallback and the `.codedeep` scanner
+// exclude. Write-through saves on each remember/forget mean no shutdown flush is
+// needed. load() is FIRE-AND-FORGET (like git.start below): it never throws
+// (quarantines on corruption) and is memoized, and every note tool re-awaits it
+// before acting — so we must NOT block server.connect (and the 6 structural
+// tools that never touch notes) on note-store disk I/O, which can be slow on a
+// networked cacheDir or one cluttered with stale .tmp/.bak entries.
+const notes = new NoteStore(join(config.cacheDir, "notes.json"), config.projectRoot);
+void notes.load();
 // Flush-on-shutdown — the watcher's per-flush saves bound the loss window,
 // but exiting between flushes shouldn't discard the last debounce batch.
 // watcher.close() drains that batch and persists through its normal save
@@ -134,5 +148,5 @@ process.on("SIGTERM", () => shutdown("SIGTERM received", false, true));
 // exits with the last debounce batch unflushed and unsaved.
 process.stdin.once("end", () => shutdown("stdin closed", true));
 process.stdin.once("close", () => shutdown("stdin closed", true));
-const server = createServer({ index, indexer, config, git });
+const server = createServer({ index, indexer, config, git, notes });
 await server.connect(new StdioServerTransport());

package/dist/indexer/code-index.js

@@ -273,8 +273,8 @@ const DEFAULT_RISK_HOTSPOTS = 10; // rows returned by getRiskHotspots
 // and inheritance-blind by construction, so an empty/shallow tree is a blind
 // spot, not an "all clear".
 const CALLER_TREE_LIMITATIONS = Object.freeze([
-    'Upstream callers only — cross-file callees (downstream) are not traversed (LSP, Phase 2).',
-    'Inheritance/override edges are not modeled, so virtual-dispatch callers may be missing (LSP, Phase 2).',
+    'Upstream callers only — cross-file callees (downstream) are not traversed.',
+    'Inheritance/override edges are not modeled, so virtual-dispatch callers may be missing.',
     'Edges are heuristic AST name-matches, not compiler-verified; confidence is ordinal, not probabilistic.',
 ]);
 export const zeroSymbolsByKind = () => ({
@@ -335,21 +335,58 @@ export class CodeIndex {
         this.fileByPath.set(file.path, file);
         this.importsByFile.set(file.path, [...imports]);
         this.symbolsByFile.set(file.path, [...symbols]);
+        const ownIds = new Set();
         for (const sym of symbols) {
+            ownIds.add(sym.id);
             this.symbolById.set(sym.id, sym);
             pushOrInit(this.symbolsByName, sym.name, sym);
         }
-        this.referencesBySourceFile.set(file.path, [...references]);
+        // The id-keyed adjacency admits SAME-FILE edges only — enforced here, at
+        // the site where LIVE-EXTRACTED edges enter the maps, not just by
+        // extractor convention. (load() is the OTHER entry site: it restores
+        // persisted adjacency verbatim, trusting that the cache was written from
+        // maps this gate already filtered — a hand-edited cache bypasses it, and
+        // corrupt caches are deleted, not repaired.) removeFileInternal's prune
+        // relies on this invariant (it deletes only the removed file's own keys;
+        // a cross-file edge — on EITHER endpoint — would leave dangling ids in
+        // another file's sets and inflate fan-in/fan-out). A violating ref is
+        // DEMOTED WHOLESALE, not just skipped: its foreign endpoint ids are
+        // nulled before it enters the name-keyed stores, so every query surface
+        // agrees it is an unresolved name match (a kept ids-intact copy would
+        // read as top-tier 'resolved' in find_references while being absent from
+        // fan-in/fan-out — two surfaces disagreeing about the same edge). If a
+        // future resolver produces cross-file edges, they surface as these
+        // demoted name-keyed refs plus this warn — the deliberate signal to
+        // design the cross-file story properly.
+        let crossFileEdges = 0;
+        const admitted = [];
         for (const ref of references) {
-            pushOrInit(this.referencesByTargetName, ref.targetName, ref);
+            let stored = ref;
+            if ((ref.sourceId !== null && !ownIds.has(ref.sourceId)) ||
+                (ref.targetId !== null && !ownIds.has(ref.targetId))) {
+                crossFileEdges++;
+                stored = {
+                    ...ref,
+                    sourceId: ref.sourceId !== null && ownIds.has(ref.sourceId) ? ref.sourceId : null,
+                    targetId: ref.targetId !== null && ownIds.has(ref.targetId) ? ref.targetId : null,
+                };
+            }
+            admitted.push(stored);
+            pushOrInit(this.referencesByTargetName, stored.targetName, stored);
             // Module-level calls (sourceId=null) and cross-file unresolved refs
             // (targetId=null) skip the id-keyed adjacency; they're queried by name
             // via referencesByTargetName.
-            if (ref.sourceId && ref.targetId) {
-                addAdjacency(this.callees, ref.sourceId, ref.targetId);
-                addAdjacency(this.callers, ref.targetId, ref.sourceId);
+            if (stored.sourceId && stored.targetId) {
+                addAdjacency(this.callees, stored.sourceId, stored.targetId);
+                addAdjacency(this.callers, stored.targetId, stored.sourceId);
             }
         }
+        this.referencesBySourceFile.set(file.path, admitted);
+        if (crossFileEdges > 0) {
+            log.warn(`CodeIndex.addFile: ${file.path} carried ${crossFileEdges} reference(s) ` +
+                `with a non-same-file endpoint id; demoted to unresolved name matches ` +
+                `(id-keyed adjacency is same-file by invariant — see removeFileInternal)`);
+        }
         this.namesDirty = true;
         this.callerCountsDirty = true;
         this.aliasIndexDirty = true;
@@ -382,12 +419,20 @@ export class CodeIndex {
             else
                 this.symbolsByName.set(sym.name, filtered);
         }
+        // Deleting each id's own key fully prunes the adjacency maps: id-keyed
+        // edges are SAME-FILE by construction (resolveCalls builds its nameToId/
+        // typeNameToId/methodsByClass maps from the one file's symbols — a non-null
+        // targetId can only point within the file; cross-file refs are stored
+        // name-keyed with targetId=null), so no OTHER file's set can contain this
+        // file's ids. A whole-map sweep here would be a provable no-op that scales
+        // the watcher's re-index hot path with total repo size. The invariant is
+        // ENFORCED at the edge-entry site (addFile's ownIds gate above) and pinned
+        // by extractor.test.ts's "resolved references always target the SAME
+        // file's symbols" property test.
         for (const id of deletedIds) {
             this.callees.delete(id);
             this.callers.delete(id);
         }
-        pruneAdjacency(this.callers, deletedIds);
-        pruneAdjacency(this.callees, deletedIds);
         const refsFromFile = this.referencesBySourceFile.get(path);
         if (refsFromFile) {
             // Group by targetName so each by-name list is filtered once even when
@@ -1608,7 +1653,8 @@ export function isCallerOf(ref, target) {
             posix.dirname(ref.file) === posix.dirname(target.file);
         // Self-receiver refs (extractor-determined: TS `this` node, Python
         // self/cls) that extract-time resolution did NOT bind to a sibling
-        // method can only target an inherited method — LSP territory. An
+        // method can only target an inherited method — inheritance is not
+        // modeled, so claiming the edge would be confidently wrong. An
         // ordinary receiver merely NAMED `self` is not affected.
         if (isMember && ref.selfReceiver)
             return false;
@@ -1654,14 +1700,27 @@ export function isClassMember(s) {
 // counting impact.ts renders ("N callers across D depths (F files)"), shared so
 // impact and the risk surface never diverge — and deduped, unlike
 // CallerTreeResult.totalNodes which double-counts DAG diamonds.
-export function countDistinctCallers(root) {
-    const callers = new Set();
+export function countDistinctCallers(root, withTiers = false) {
+    const callerKeys = new Set();
+    // `strongest` (best edge per caller) is only built when the caller wants the
+    // tier breakdown; the scalar blast-radius path skips the per-node strength
+    // tracking + final bucketing loop entirely. Keyed identically to callerKeys,
+    // so the per-tier counts sum to `callers`. A caller reachable via a resolved
+    // path is at least that trustworthy, hence "strongest".
+    const strongest = withTiers ? new Map() : null;
     const files = new Set();
     const depths = new Set();
     let depthCapped = false;
     const walk = (node) => {
         for (const child of node.children) {
-            callers.add(child.symbolId ?? `m:${child.file}:${child.line}`);
+            const key = child.symbolId ?? `m:${child.file}:${child.line}`;
+            callerKeys.add(key);
+            if (strongest) {
+                const prev = strongest.get(key);
+                if (prev === undefined || STRENGTH_RANK[child.strength] > STRENGTH_RANK[prev]) {
+                    strongest.set(key, child.strength);
+                }
+            }
             files.add(child.file);
             depths.add(child.depth);
             if (child.depthCapped)
@@ -1670,7 +1729,25 @@ export function countDistinctCallers(root) {
         }
     };
     walk(root);
-    return { callers: callers.size, files: files.size, depths: depths.size, depthCapped };
+    const counts = {
+        callers: callerKeys.size,
+        files: files.size,
+        depths: depths.size,
+        depthCapped,
+    };
+    if (strongest) {
+        const tiers = { structural: 0, nameMatch: 0, weakMember: 0 };
+        for (const strength of strongest.values()) {
+            if (strength === 'resolved')
+                tiers.structural += 1;
+            else if (strength === 'weak-member')
+                tiers.weakMember += 1;
+            else
+                tiers.nameMatch += 1;
+        }
+        counts.tiers = tiers;
+    }
+    return counts;
 }
 // True when `imports` brings `name` into scope as a value binding the bare
 // call site could resolve to (named import, alias, or wildcard). Shared by
@@ -1724,14 +1801,6 @@ function addAdjacency(map, key, value) {
     }
     set.add(value);
 }
-function pruneAdjacency(map, deleted) {
-    for (const [key, set] of map) {
-        for (const id of deleted)
-            set.delete(id);
-        if (set.size === 0)
-            map.delete(key);
-    }
-}
 function adjacencyToEntries(map) {
     const out = [];
     for (const [k, set] of map)

package/dist/indexer/parser.js

@@ -27,7 +27,82 @@ const LANG_TO_WASM = {
     objc: 'tree-sitter-objc.wasm',
 };
 const parsers = new Map();
-let initPromise = null;
+// Split memoization: the tree-sitter WASM runtime loads once (coreInit);
+// each language's grammar loads on demand (langLoads) — a repo that is pure
+// Python must not pay the ~95MB RSS floor of all 16 grammars. Rejections
+// self-reset (a transient EMFILE must not disable a language for the
+// process lifetime).
+let coreInit = null;
+const langLoads = new Map();
+// A grammar load is retried IN PLACE with a short backoff before the promise
+// rejects: transient failures (an EMFILE storm during the WASM read) clear in
+// milliseconds, and retrying HERE — at the altitude where the failure lives —
+// protects every caller identically (startup bulk scan, watcher single-file,
+// pattern-mode validation) with no per-path retry bookkeeping anywhere else.
+// (A per-path retry queue in the watcher was tried and removed: it could not
+// cover the startup path, swallowed edits landing mid-budget, and its counters
+// leaked across interleaved outcomes.) A failure that survives the attempts is
+// treated as durable (corrupt/missing .wasm — needs user action); langLoads
+// still self-resets, so a LATER call (next fs event / rescan / restart) probes
+// again rather than latching the language off forever.
+const GRAMMAR_LOAD_ATTEMPTS = 3;
+const GRAMMAR_RETRY_BASE_MS = 50;
+// After a full attempt budget fails, further ensures for that language FAIL
+// FAST for this window instead of re-running the backoff sequence. Without
+// it, the memo's self-reset composes badly with the serial batch path: a
+// permanently corrupt .wasm would cost ~150ms of backoff PER FILE of that
+// language (5,000 files ≈ 12+ minutes of stall inside one indexAll). With
+// it, a batch sweeps at full speed (~one backoff sequence per TTL window)
+// while a later probe — the next fs event / rescan after the window — still
+// retries fresh, so the language is never latched off.
+const GRAMMAR_FAILURE_TTL_MS = 5_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const langFailures = new Map();
+function ensureLanguage(lang) {
+    const wasm = LANG_TO_WASM[lang];
+    // Unknown/unsupported names are a no-op here (the scanner emits 'unknown'
+    // for unrecognized extensions); parseFile still warns when asked to parse one.
+    if (!wasm)
+        return Promise.resolve();
+    let p = langLoads.get(lang);
+    if (!p) {
+        const recent = langFailures.get(lang);
+        if (recent !== undefined) {
+            if (Date.now() - recent.at < GRAMMAR_FAILURE_TTL_MS) {
+                return Promise.reject(recent.err); // fail fast inside the TTL window
+            }
+            langFailures.delete(lang); // window over → probe again for real
+        }
+        p = (async () => {
+            let lastErr;
+            for (let attempt = 1; attempt <= GRAMMAR_LOAD_ATTEMPTS; attempt++) {
+                try {
+                    const language = await Language.load(path.join(grammarsDir, wasm));
+                    const parser = new Parser();
+                    parser.setLanguage(language);
+                    parsers.set(lang, parser);
+                    langFailures.delete(lang);
+                    return;
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (attempt < GRAMMAR_LOAD_ATTEMPTS) {
+                        await delay(GRAMMAR_RETRY_BASE_MS * attempt);
+                    }
+                }
+            }
+            langFailures.set(lang, { at: Date.now(), err: lastErr });
+            throw lastErr;
+        })();
+        p.catch(() => {
+            langLoads.delete(lang); // durable failure → a later call probes again
+        });
+        langLoads.set(lang, p);
+    }
+    return p;
+}
 // Conditional-compilation directive lines (#if / #elseif / #else / #endif).
 // `m` matches ^/$ per line; without `s`, `.*` stays within one line.
 const SWIFT_DIRECTIVE_LINE = /^[ \t]*#(?:if|elseif|else|endif)\b.*$/gm;
@@ -88,39 +163,39 @@ function countParseErrors(root) {
     }
     return count;
 }
-export function initParser() {
-    if (!initPromise) {
-        initPromise = (async () => {
-            await Parser.init();
-            const loaded = await Promise.all(Object.entries(LANG_TO_WASM).map(async ([lang, wasm]) => {
-                const language = await Language.load(path.join(grammarsDir, wasm));
-                const parser = new Parser();
-                parser.setLanguage(language);
-                return [lang, parser];
-            }));
-            for (const [lang, parser] of loaded) {
-                parsers.set(lang, parser);
-            }
-        })();
+// Initialize the runtime and load grammars. With `languages`, loads ONLY those
+// grammars (the pipeline passes the scan-found set, so a repo pays memory for
+// exactly the languages it contains); with no argument, loads ALL grammars
+// (test harnesses and callers that can't know the set up front). Idempotent
+// and incremental: each grammar loads at most once, and later calls with new
+// languages top up what's already loaded.
+export async function initParser(languages) {
+    if (!coreInit) {
+        coreInit = Parser.init();
         // A cached rejection would otherwise disable parsing (and pattern
-        // validation) for the process lifetime after one transient failure
-        // (EMFILE during the WASM reads) — reset so the next call retries.
-        initPromise.catch(() => {
-            initPromise = null;
+        // validation) for the process lifetime after one transient failure —
+        // reset so the next call retries.
+        coreInit.catch(() => {
+            coreInit = null;
         });
     }
-    return initPromise;
+    await coreInit;
+    const langs = languages ? [...new Set(languages)] : Object.keys(LANG_TO_WASM);
+    await Promise.all(langs.map(ensureLanguage));
 }
 // The returned Tree holds WASM memory; callers must call `tree.delete()` when
 // finished — JS GC won't free it.
 export function parseFile(content, language) {
-    if (parsers.size === 0) {
-        throw new Error('parser not initialized; call initParser() first');
-    }
     const parser = parsers.get(language);
     if (!parser) {
-        log.warn(`parseFile: unsupported language "${language}"`);
-        return null;
+        if (!(language in LANG_TO_WASM)) {
+            log.warn(`parseFile: unsupported language "${language}"`);
+            return null;
+        }
+        // Supported but not loaded — a caller-ordering bug (every parse path must
+        // initParser([language]) first). Throw loudly (the pipeline catches and
+        // warns per file) rather than silently skipping the file.
+        throw new Error(`parser not initialized for "${language}"; call initParser(["${language}"]) first`);
     }
     let tree = parser.parse(content);
     if (!tree) {