micro-models-agent 2.11.0 → 2.12.0

package/dist/modules/hallucination/factual.js

@@ -1,8 +1,10 @@
+// Фактическая проверка: упомянутые в ответе пути файлов против диска и индекса.
 import { existsSync, readdirSync } from "fs";
 import { resolve, isAbsolute, join } from "path";
 import { t } from "../../i18n/index";
 import { extractFileLikeTokens, stripUrls } from "./js-identifiers";
-/** Generated/cached dirs to skip when scanning for bare file names. */
+import { HALLUCINATION_NAME_CACHE_TTL_MS, HALLUCINATION_RESCAN_COOLDOWN_MS, } from "../../config/timeouts";
+/** Генерированные/кэшированные каталоги — пропускаем при поиске голых имён. */
 const IGNORED_DIRS = new Set([
     "node_modules",
     ".git",
@@ -12,26 +14,30 @@ const IGNORED_DIRS = new Set([
     ".mma",
     "_testing",
 ]);
+/** Проверка фактов: упомянутые файлы существуют на диске/в индексе, иначе warn. */
 export class FactualCheck {
     baseDir;
     nameCache = null;
     nameCacheTime = 0;
     lastRescan = 0;
-    static NAME_CACHE_TTL_MS = 5_000;
-    static RESCAN_COOLDOWN_MS = 2_000;
+    static NAME_CACHE_TTL_MS = HALLUCINATION_NAME_CACHE_TTL_MS;
+    static RESCAN_COOLDOWN_MS = HALLUCINATION_RESCAN_COOLDOWN_MS;
     static MAX_INDEXED_FILES = 20_000;
-    /** Files known from compaction summaries — survive context resets. */
+    /** Файлы, известные из сводок компакции — переживают сбросы контекста. */
     knownFiles = new Set();
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
-    /** Add file paths known from compaction summaries. These are checked
-     *  before the filesystem scan so bare filenames from compacted turns
-     *  are recognized even when the directory is in IGNORED_DIRS. */
+    /** Добавляет пути, известные из сводок компакции. Проверяются раньше скана ФС:
+     *  голые имена из уплотнённых ходов узнаются, даже если каталог в IGNORED_DIRS. */
     addKnownFiles(files) {
         for (const f of files)
             this.knownFiles.add(f);
     }
+    /**
+     * Валидирует пути файлов в ответе: warn со списком отсутствующих, иначе pass.
+     * @param response текст ответа модели; @param deletedFiles уже удалённые (не флагуются).
+     */
     validate(response, deletedFiles) {
         const filePaths = this.extractFilePaths(response);
         if (filePaths.length === 0)
@@ -58,13 +64,13 @@ export class FactualCheck {
         return { status: "pass" };
     }
     /**
-     * Bare filenames ("bikes.json") and relative paths ("src/data/bikes.json")
-     * both land on the project tree. Absolute paths are checked as-is.
+     * Голые имена ("bikes.json") и относительные пути ("src/data/bikes.json")
+     * садятся на дерево проекта. Абсолютные проверяются как есть.
      */
     pathExists(fp) {
         if (isAbsolute(fp))
             return existsSync(fp);
-        // Check known files from compaction summaries first
+        // Сначала известные файлы из сводок компакции
         if (this.knownFiles.has(fp))
             return true;
         for (const cand of this.dotfileVariants(fp)) {
@@ -73,33 +79,32 @@ export class FactualCheck {
             if (existsSync(resolve(this.baseDir, cand)))
                 return true;
         }
-        // "foo.json" has no directory part — treat it as a bare name that may
-        // live anywhere under baseDir (e.g. src/data/bikes.json). Resolving it
-        // against the workspace root alone produced false "unknown file" warnings.
+        // "foo.json" без каталога — голое имя, которое может жить где угодно под
+        // baseDir (напр. src/data/bikes.json). Резолв только от корня давал ложные
+        // "unknown file".
         if (!fp.includes("/") && !fp.includes("\\")) {
             return this.bareNameExists(fp);
         }
         return false;
     }
     /**
-     * The token regex cannot anchor a leading dot (`\b` never matches between a
-     * non-word char and `.`), so dotfiles (.prettierrc.json, .env, …) are
-     * extracted as "prettierrc.json". Try the dot-prefixed basename too before
-     * declaring the file missing. "src/config.json" also yields
-     * "src/.config.json". For paths like "mma/index-cache.json", also try
-     * ".mma/index-cache.json" (dot-prefixed parent directories).
+     * Токен-regex не якорит ведущую точку (`\b` не матчится между не-словом и
+     * `.`), поэтому дотфайлы (.prettierrc.json, .env, …) извлекаются как
+     * "prettierrc.json". Перед вердиктом "нет файла" пробуем basename с точкой,
+     * "src/config.json" даёт и "src/.config.json", а "mma/index-cache.json" —
+     * и ".mma/index-cache.json" (родители с точкой).
      */
     dotfileVariants(fp) {
         const variants = [fp];
         const sep = fp.includes("\\") ? "\\" : "/";
         const parts = fp.split(sep);
-        // Try dot-prefixing the basename (existing logic)
+        // Пробуем basename с точкой (старая логика)
         const base = parts[parts.length - 1];
         if (!base.startsWith(".")) {
             const withDotBase = [...parts.slice(0, -1), `.${base}`].join(sep);
             variants.push(withDotBase);
         }
-        // Try dot-prefixing each parent directory component
+        // Пробуем точку на каждом родительском компоненте
         for (let i = 0; i < parts.length - 1; i++) {
             if (!parts[i].startsWith(".")) {
                 const dotted = [...parts.slice(0, i), `.${parts[i]}`, ...parts.slice(i + 1)].join(sep);
@@ -115,15 +120,27 @@ export class FactualCheck {
                 return true;
             if (this.indexHas(cand))
                 return true;
-            // Check known files — a bare name may match a full path from compaction
+            // Известные файлы: голое имя может совпасть с полным путём из компакции
             for (const known of this.knownFiles) {
                 if (known.endsWith(`/${cand}`) || known.endsWith(`\\${cand}`) || known === cand) {
                     return true;
                 }
             }
         }
-        // A write_file from this session may have created the file after the
-        // index was built. Do a one-off rescan (rate-limited) before warning.
+        // Имя файла может содержать пробел: «отчёт 1.txt» извлекается токеном
+        // «1.txt». Прежде чем объявлять файл отсутствующим, проверяем, не
+        // заканчивается ли какое-то известное имя на « 1.txt».
+        const spaceName = ` ${name}`;
+        for (const known of this.knownFiles) {
+            if (known.endsWith(spaceName))
+                return true;
+        }
+        for (const key of this.getNameIndex().keys()) {
+            if (key.endsWith(spaceName))
+                return true;
+        }
+        // write_file текущей сессии мог создать файл после сборки индекса.
+        // Перед warn — разовый рескан (rate-limited).
         const now = Date.now();
         if (now - this.lastRescan < FactualCheck.RESCAN_COOLDOWN_MS)
             return false;
@@ -136,8 +153,8 @@ export class FactualCheck {
         return (this.getNameIndex().get(name)?.length ?? 0) > 0;
     }
     /**
-     * Basename → paths index, rebuilt every NAME_CACHE_TTL_MS so newly created
-     * files (write_file) are picked up without a full scan on every response.
+     * Индекс basename → пути, пересборка каждые NAME_CACHE_TTL_MS, чтобы новые
+     * файлы (write_file) подхватывались без полного скана на каждый ответ.
      */
     getNameIndex() {
         const now = Date.now();

package/dist/modules/hallucination/index.js

@@ -1,3 +1,4 @@
+// Детектор галлюцинаций: реэкспорт проверок (консистентность, уверенность, факты, LLM-судья).
 export { HallucinationDetector } from "./detector";
 export { ConsistencyCheck } from "./consistency";
 export { ConfidenceCheck } from "./confidence";

package/dist/modules/hallucination/js-identifiers.js

@@ -1,19 +1,19 @@
 /**
- * JS/TS global identifiers whose member access (`process.env`, `console.log`,
- * `Math.max`) looks like a file path to `\b[\w./\\-]+\.[a-z]+\b`-style regexes
- * but is code, not a file. Shared by the hallucination factual check and the
- * execution auditor so both stop flagging member access as "missing files".
+ * JS/TS-глобалы, чей member access (`process.env`, `console.log`, `Math.max`)
+ * похож на путь к файлу для `\b[\w./\\-]+\.[a-z]+\b`-regex'ов, но является
+ * кодом, а не файлом. Общий для фактической проверки галлюцинаций и аудитора
+ * исполнения — оба перестают флаговать member access как "потерянные файлы".
  *
- * Also home of the shared "is this token actually a file?" filter
- * (`isFilePathLike` / `extractFileLikeTokens` / `stripUrls`) so the two
- * extractors cannot drift apart again (observed: auditor treated a URL
- * hostname `whom-pointing-jewel-maine.trycloudflare.com` in a plan step as a
- * missing file while the factual check correctly ignored it).
+ * Здесь же общий фильтр "этот токен вообще файл?"
+ * (`isFilePathLike` / `extractFileLikeTokens` / `stripUrls`), чтобы два
+ * экстрактора не расходились (было: аудитор считал hostname URL
+ * `whom-pointing-jewel-maine.trycloudflare.com` в шаге плана потерянным
+ * файлом, а фактическая проверка корректно игнорировала).
  *
- * Bare `word.ext` tokens are gated on an allow-list of real file extensions
- * (`FILE_EXTENSIONS`) instead of a deny-list of TLDs — a domain in any present
- * or future TLD (`Gismeteo.by`, `weather.com`, `example.xyz`) can never be
- * mistaken for a file, and no TLD list needs maintaining.
+ * Голые токены `word.ext` гейтятся allow-list'ом реальных расширений
+ * (`FILE_EXTENSIONS`), а не deny-list'ом TLD — домен в любом нынешнем или
+ * будущем TLD (`Gismeteo.by`, `weather.com`, `example.xyz`) никогда не
+ * спутается с файлом, и список TLD вести не нужно.
  */
 const JS_GLOBALS = new Set([
     "process",
@@ -72,9 +72,9 @@ const JS_GLOBALS = new Set([
     "node",
 ]);
 /**
- * True when `candidate` starts with a known JS/TS global followed by a dot
- * (`process.env`, `console.log`, `process.env.NODE` partial matches from
- * `\b[\w./\\-]+\.[a-z]+`-style regexes) — member access, not a file path.
+ * True, если `candidate` начинается с известного JS/TS-глобала и точки
+ * (`process.env`, `console.log`, частичные совпадения `process.env.NODE`
+ * от `\b[\w./\\-]+\.[a-z]+`-regex'ов) — member access, не путь к файлу.
  */
 export function isJsMemberAccess(candidate) {
     const lower = candidate.toLowerCase();
@@ -82,16 +82,16 @@ export function isJsMemberAccess(candidate) {
     return m !== null && JS_GLOBALS.has(m[1]);
 }
 /**
- * File extensions that make a bare `word.ext` token a plausible file path.
+ * Расширения, делающие голый токен `word.ext` похожим на путь к файлу.
  *
- * An allow-list, deliberately: enumerating everything that is NOT a file (TLDs,
- * brand names, …) is a brittle heuristic that can never be complete. Instead a
- * bare `word.ext` is only treated as a file when its extension is a known one —
- * so `Gismeteo.by`, `weather.com`, or any future TLD is never flagged, while a
- * genuine `config.json` / `helper.ts` still is.
+ * Allow-list осознанно: перечислять всё, что НЕ файл (TLD, бренды, …) —
+ * хрупкая эвристика, которая никогда не полна. Вместо этого голый `word.ext`
+ * считается файлом только при известном расширении — так `Gismeteo.by`,
+ * `weather.com` и любой будущий TLD не флагуются, а настоящие
+ * `config.json` / `helper.ts` — да.
  */
 const FILE_EXTENSIONS = new Set([
-    // source / code
+    // исходники / код
     "ts",
     "tsx",
     "js",
@@ -131,7 +131,7 @@ const FILE_EXTENSIONS = new Set([
     "vue",
     "svelte",
     "dart",
-    // config / data / docs
+    // конфиги / данные / доки
     "json",
     "jsonc",
     "json5",
@@ -143,6 +143,7 @@ const FILE_EXTENSIONS = new Set([
     "conf",
     "env",
     "xml",
+    "drawio",
     "html",
     "htm",
     "md",
@@ -162,7 +163,7 @@ const FILE_EXTENSIONS = new Set([
     "scss",
     "sass",
     "less",
-    // assets / binary
+    // ассеты / бинарники
     "svg",
     "png",
     "jpg",
@@ -198,7 +199,7 @@ const FILE_EXTENSIONS = new Set([
     "a",
     "dylib",
 ]);
-/** Well-known runtime/library names that end in .js/.ts but are NOT files. */
+/** Известные рантаймы/библиотеки на .js/.ts, которые НЕ файлы. */
 const TECH_NAMES = new Set([
     "node.js",
     "react.js",
@@ -213,12 +214,12 @@ const TECH_NAMES = new Set([
 ]);
 const FILE_TOKEN_RE = /\b(?:[a-zA-Z]:[\\/])?[\w./\\-]+\.[a-z]{1,6}\b/gi;
 /**
- * True when `candidate` is a plausible file path token: for a path with a
- * directory separator the last segment must carry a non-empty stem before the
- * extension (extension-only segments like `tsx/.ts` are rejected), while a bare
- * `word.ext` is only a file when its extension is a known file extension (so
- * domains like `Gismeteo.by` / `weather.com` are never files). JS member access
- * (`process.env`) and technology names (`node.js`) are never files.
+ * True, если `candidate` — правдоподобный токен пути: у пути с разделителем
+ * последний сегмент обязан нести непустой stem перед расширением (сегменты
+ * только из расширения вроде `tsx/.ts` отбрасываются), а голый `word.ext` —
+ * файл только при известном расширении (домены `Gismeteo.by` / `weather.com`
+ * — никогда файлы). JS member access (`process.env`) и техно-имена
+ * (`node.js`) — никогда файлы.
  */
 export function isFilePathLike(s) {
     const lower = s.toLowerCase();
@@ -232,12 +233,11 @@ export function isFilePathLike(s) {
             return false;
         return FILE_EXTENSIONS.has(ext);
     }
-    // Tokens with a directory separator: require the LAST segment to carry a
-    // real file name (a non-empty stem before the extension). Otherwise an
-    // extension-only segment like "tsx/.ts" (from ".tsx/.ts" in a step
-    // description) or a dotfile ("src/.env") is misread as a file and the plan
-    // deliverable gate demands "create tsx/.ts" (observed in ses_mstda6uo:
-    // step "Проверить что остались только .tsx/.ts файлы").
+    // Токены с разделителем: требуем у ПОСЛЕДНЕГО сегмента настоящее имя
+    // (непустой stem перед расширением). Иначе сегмент только из расширения
+    // вроде "tsx/.ts" (из ".tsx/.ts" в описании шага) или дотфайл ("src/.env")
+    // читается как файл, и deliverable-gate требует "создать tsx/.ts"
+    // (было в ses_mstda6uo: шаг "Проверить что остались только .tsx/.ts файлы").
     const last = s.split(/[\\/]/).pop() ?? "";
     const lastDot = last.lastIndexOf(".");
     if (lastDot <= 0)
@@ -245,18 +245,17 @@ export function isFilePathLike(s) {
     return true;
 }
 /**
- * Extract deduplicated file-like tokens from free text. Bare `word.ext` tokens
- * are filtered through `isFilePathLike` (allow-list of real file extensions, so
- * hostnames/TLDs like `whom-pointing-jewel-maine.trycloudflare.com` or
- * `Gismeteo.by` never survive); URLs are stripped first so
- * `https://host/repo.git` never survives as a "file".
+ * Извлекает дедуплицированные файлоподобные токены из свободного текста.
+ * Голые `word.ext` фильтруются через `isFilePathLike` (allow-list реальных
+ * расширений — хосты/TLD вроде `whom-pointing-jewel-maine.trycloudflare.com`
+ * или `Gismeteo.by` не выживают); URL вырезаются заранее, чтобы
+ * `https://host/repo.git` не выжил как "файл".
  */
 export function extractFileLikeTokens(text) {
     const matches = text.match(FILE_TOKEN_RE) || [];
     return [...new Set(matches.filter(isFilePathLike))];
 }
-/** Remove URL tokens (scheme://… up to whitespace/quote) so they are never
- *  parsed as file paths. */
+/** Вырезает URL (scheme://… до пробела/кавычки), чтобы они не парсились как пути. */
 export function stripUrls(text) {
     return text.replace(/\bhttps?:\/\/[^\s"'<>]+/gi, " ");
 }

package/dist/modules/hallucination/llm-judge.js

@@ -1,21 +1,24 @@
+// LLM-судья консистентности: противоречит ли новый ответ ранним решениям.
 import { t } from "../../i18n/index";
-const JUDGE_TIMEOUT_MS = 15000;
+import { HALLUCINATION_JUDGE_TIMEOUT_MS as JUDGE_TIMEOUT_MS } from "../../config/timeouts";
 const MAX_DECISIONS_SHOWN = 6;
 const MAX_RESPONSE_CHARS = 2000;
 /**
- * LLM-as-judge consistency check. Asks a model whether the agent's latest
- * response contradicts any of its earlier decisions — replacing the fragile
- * word-matching heuristic that only caught exact substring reversals.
+ * Консистентность через LLM-судью. Спрашивает модель, противоречит ли свежий
+ * ответ агента его ранним решениям — вместо хрупкой эвристики совпадения слов,
+ * ловившей только дословные развороты.
  *
- * Fast path: when no decisions are tracked, returns pass without any LLM call.
- * Any judge failure (timeout, provider error, unparseable verdict) degrades to
- * pass so the agent loop is never blocked by the judge.
+ * Быстрый путь: нет отслеживаемых решений — pass без LLM-вызова.
+ * Любой сбой судьи (таймаут, ошибка провайдера, непарсящийся вердикт) —
+ * деградация в pass, чтобы цикл агента не блокировался судьёй.
  */
+/** LLM-судья: проверяет новый ответ на противоречие ранним решениям. */
 export class LLMJudge {
     provider;
     constructor(provider) {
         this.provider = provider;
     }
+    /** Валидирует ответ против решений: warn при противоречии, иначе pass (сбои — тоже pass). */
     async validate(response, consistency) {
         const decisions = consistency.getDecisions();
         if (decisions.length === 0) {
@@ -54,6 +57,7 @@ Reply with ONLY valid JSON, no other text:
             return { status: "pass" };
         }
     }
+    /** Один запрос к судье со сбором текстовых чанков. */
     async askJudge(messages) {
         let text = "";
         const controller = new AbortController();
@@ -66,8 +70,8 @@ Reply with ONLY valid JSON, no other text:
             }
             return text;
         })();
-        // The timeout can settle the race while the background stream is still
-        // running; its later rejection must not surface as an unhandled rejection.
+        // Таймаут может завершить гонку, пока фоновый стрим ещё идёт;
+        // его позднее rejection не должно всплыть как unhandled rejection.
         consume.catch(() => { });
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => {
@@ -81,11 +85,12 @@ Reply with ONLY valid JSON, no other text:
         finally {
             if (timer)
                 clearTimeout(timer);
-            // Abort the background stream on the success path too, so a judge that
-            // resolved early never keeps streaming in the background.
+            // Абортим фоновый стрим и на успешном пути, чтобы рано завершившийся
+            // судья не продолжал стримить в фоне.
             controller.abort();
         }
     }
+    /** Парсит вердикт: строгий JSON → терпимый разбор, иначе "не противоречит". */
     parseVerdict(text) {
         const block = text.match(/\{[\s\S]*\}/);
         if (block) {
@@ -99,7 +104,7 @@ Reply with ONLY valid JSON, no other text:
                 }
             }
             catch {
-                // fall through to lenient parsing
+                // Не парсится строго — ниже терпимый разбор
             }
         }
         const lower = text.toLowerCase();

package/dist/modules/hallucination/success-claim.js

@@ -0,0 +1,59 @@
+/**
+ * Проверка заявлений об успехе (ses_muih0ah5): модель объявила "MMA 2.8.0
+ * опубликован", а её же тулы показывали `latest: 2.5.0` и 404 на тарболле
+ * 2.8.0. Factual-check валидирует только пути файлов, так что сильное
+ * заявление об успехе вразрез со свежими доказательствами прошло молча.
+ *
+ * Полностью детерминирована (regex + флаги успеха тулов, без LLM): сильное
+ * заявление о завершении + сигналы ошибок в свежих выводах тулов + отсутствие
+ * хеджирования в ответе = противоречие. Точность осознанно смещена в recall —
+ * ложное срабатывание стоит одну ограниченную re-check итерацию
+ * (MAX_CLAIM_CHECK_RETRIES), пропуск — статус-кво.
+ */
+/**
+ * Помощник границ слов. `\b`/`\w` в JS — только ASCII, поэтому кириллические
+ * окончания (опубликован**а**, ошибк**а**) их не матчат — границы выписаны явно
+ * для обоих алфавитов. Lookbehind поддерживают все рантаймы MMA (Node ≥20, Bun).
+ */
+const WORD = "A-Za-zА-Яа-яЁё0-9_";
+const wb = (body) => new RegExp(`(?<![${WORD}])(?:${body})(?![${WORD}])`, "i");
+/** Сильные, нехеджированные заявления о завершении (любая локаль агента). */
+const SUCCESS_CLAIM_RE = wb("published|опубликован[а-яё]*|задеплоен[а-яё]*|deployed|shipped|готово|выполнено|завершен[а-яё]*|успешно|success(?:ful(?:ly)?)?|done|completed?|finished|все сделано|всё сделано");
+/** Ответ уже хеджирован — модель учла неопределённость, пропускаем. */
+const HEDGE_RE = wb("may take|being processed|processing|staged|propagat[a-z]*|in progress|shortly|soon|will appear|несколько минут|обрабатывается|застейджен[а-яё]*|подожд[а-яё]*|проверь[а-яё]* позже|появится|пропагир[а-яё]*|кэш[а-яё]*|cach[a-z]*|обычно|typically");
+/** Сигналы ошибок в выводе тулов (узко: коды + явные фейлы). */
+const FAILURE_SIGNAL_RE = new RegExp(`${wb("404|409|40[03]|50\\d|failed|failure|not found|ERR_[A-Z_]+|E(?:404|409|ACCES|PERM|CONNREFUSED|TIMED?OUT)|conflict|denied|ошибка|ошибк[а-яё]*|не найден[а-яё]*|не удалось|отклонено").source}|✗|⛔`, "i");
+const EVIDENCE_WINDOW = 10;
+const EVIDENCE_TEXT_CAP = 400;
+const SNIPPET_MAX_CHARS = 160;
+/**
+ * Возвращает противоречащее доказательство, или null если ответ в порядке:
+ * нет заявления об успехе, есть хеджирование, или нет сигналов ошибок в свежих тулах.
+ */
+export function checkSuccessClaim(response, tools) {
+    if (!response || !SUCCESS_CLAIM_RE.test(response))
+        return null;
+    if (HEDGE_RE.test(response))
+        return null;
+    const recent = tools.filter((t) => t.text?.trim()).slice(-EVIDENCE_WINDOW);
+    // Свежайшее противоречие первым — цитируется самое актуальное доказательство.
+    for (let i = recent.length - 1; i >= 0; i--) {
+        const entry = recent[i];
+        const text = entry.text.slice(0, EVIDENCE_TEXT_CAP);
+        if (entry.ok === false || FAILURE_SIGNAL_RE.test(text)) {
+            const firstLine = text
+                .split("\n")
+                .map((l) => l.trim())
+                .find((l) => l.length > 0);
+            if (!firstLine)
+                continue;
+            return {
+                tool: entry.name || "tool",
+                snippet: firstLine.length > SNIPPET_MAX_CHARS
+                    ? `${firstLine.slice(0, SNIPPET_MAX_CHARS - 1)}…`
+                    : firstLine,
+            };
+        }
+    }
+    return null;
+}

package/dist/modules/indexer/cache.js

@@ -1,31 +1,64 @@
+// Дисковый кэш индекса проекта: envelope с версией, root и сигнатурой дерева.
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
+/**
+ * Инкремент при смене envelope или формы `IndexResult`: кэши старого MMA
+ * считаются протухшими и перестраиваются.
+ */
+/** Версия схемы кэша индекса. */
+export const CACHE_VERSION = 2;
+/** Дисковый кэш индекса с валидацией версии/root/сигнатуры. */
 export class IndexCache {
     cachePath;
     cache = null;
-    constructor(cacheDir) {
+    root;
+    signature;
+    constructor(cacheDir, opts = {}) {
         this.cachePath = join(cacheDir, "index-cache.json");
+        this.root = opts.root;
+        this.signature = opts.signature;
     }
+    /**
+     * Возвращает кэшированный индекс, только если он описывает текущее дерево.
+     * Отвергает кэш при расхождении версии схемы, сохранённого `root` или
+     * `signature`; легаси-кэш (сырой `IndexResult` без envelope) считается
+     * протухшим. Вызывающие на `null` делают полный обход.
+     */
     load() {
         if (this.cache)
             return this.cache;
         if (!existsSync(this.cachePath))
             return null;
         try {
-            this.cache = JSON.parse(readFileSync(this.cachePath, "utf-8"));
+            const parsed = JSON.parse(readFileSync(this.cachePath, "utf-8"));
+            if (parsed.version !== CACHE_VERSION || !parsed.result)
+                return null;
+            if (this.root !== undefined && parsed.root !== this.root)
+                return null;
+            if (this.signature && parsed.signature !== this.currentSignature())
+                return null;
+            this.cache = parsed.result;
             return this.cache;
         }
         catch {
             return null;
         }
     }
+    /** Сохраняет результат индекса в кэш (память + диск). */
     save(result) {
         this.cache = result;
+        const envelope = {
+            version: CACHE_VERSION,
+            root: this.root ?? "",
+            signature: this.currentSignature(),
+            result,
+        };
         const dir = join(this.cachePath, "..");
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        writeFileSync(this.cachePath, JSON.stringify(result), "utf-8");
+        writeFileSync(this.cachePath, JSON.stringify(envelope), "utf-8");
     }
+    /** Инвалидирует кэш (память + дисковый файл). */
     invalidate() {
         this.cache = null;
         if (existsSync(this.cachePath)) {
@@ -33,8 +66,23 @@ export class IndexCache {
                 rmSync(this.cachePath);
             }
             catch {
-                /* ignore */
+                /* best-effort очистка */
             }
         }
     }
+    /**
+     * Считает сигнатуру дерева защищённо: нечитаемое дерево даёт пустую строку,
+     * которая не совпадёт с сохранённой успешным обходом — битое дерево
+     * инвалидирует кэш, а не вызывает доверие к нему.
+     */
+    currentSignature() {
+        if (!this.signature)
+            return "";
+        try {
+            return this.signature();
+        }
+        catch {
+            return "";
+        }
+    }
 }

package/dist/modules/indexer/index.js

@@ -1,3 +1,4 @@
+// Индекс проекта: реэкспорт вокера, кэша и модуля карты проекта.
 export { Indexer } from "./walker";
 export { IndexCache } from "./cache";
 export { IndexerModule } from "./module";

package/dist/modules/indexer/map-command.js

@@ -1,8 +1,7 @@
 import { t } from "../../i18n/index";
 /**
- * Shared implementation of the project-map command used by both `mma map`
- * (CLI) and `/map` (REPL): summary (the exact text injected into the system
- * prompt), refresh, and find.
+ * Общая реализация команды карты проекта для `mma map` (CLI) и `/map` (REPL):
+ * summary (точный текст из системного промпта), refresh и find.
  */
 export async function runMapAction(module, action, query) {
     const summary = async () => {
@@ -28,7 +27,6 @@ export async function runMapAction(module, action, query) {
             await module.buildIndex();
             return { ok: true, output: module.formatFind(q) };
         }
-        case "summary":
         default:
             return summary();
     }