gitnexus 1.6.5-rc.9 → 1.6.5

package/dist/core/wiki/mermaid-sanitizer.js

@@ -0,0 +1,100 @@
+const MERMAID_FENCE_RE = /```mermaid\s*\n([\s\S]*?)```/g;
+const NODE_LABEL_RE = /(\[[^\]\n]*(?:\\n)[^\]\n]*\]|\{[^}\n]*(?:\\n)[^}\n]*\}|\([^)\n]*(?:\\n)[^)\n]*\))/g;
+const EDGE_LABEL_RE = /\|([^|\n]+)\|/g;
+const UNSAFE_EDGE_LABEL_RE = /[()[\]{}<>]/;
+const UNSAFE_NODE_ID_RE = /[^A-Za-z0-9_-]/;
+const NODE_ID_RE = /^[A-Za-z0-9_.:/()-]+$/;
+const LINE_PREFIX_RE = /^(\s*(?:(?:[-A-Za-z0-9_]+)\s*:\s*)?)(.*)$/;
+const EDGE_RE = /(\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?\|[^|\n]*\|(?:[>|ox])?|\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?|\s*<--+>?\s*)/g;
+export function sanitizeMermaidMarkdown(markdown) {
+    return markdown.replace(MERMAID_FENCE_RE, (_match, diagram) => {
+        return '```mermaid\n' + sanitizeMermaidDiagram(diagram) + '```';
+    });
+}
+export function sanitizeMermaidDiagram(diagram) {
+    const aliases = new Map();
+    let nextAlias = 1;
+    const aliasFor = (id) => {
+        const existing = aliases.get(id);
+        if (existing)
+            return existing;
+        const base = id.replace(/[^A-Za-z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'node';
+        let alias = base;
+        while ([...aliases.values()].includes(alias)) {
+            nextAlias += 1;
+            alias = `${base}_${nextAlias}`;
+        }
+        aliases.set(id, alias);
+        return alias;
+    };
+    return diagram
+        .split('\n')
+        .map((line) => sanitizeMermaidLine(line, aliasFor))
+        .join('\n');
+}
+function sanitizeMermaidLine(line, aliasFor) {
+    let sanitized = replaceLiteralLineBreaksInLabels(line);
+    sanitized = quoteUnsafeEdgeLabels(sanitized);
+    const prefixMatch = sanitized.match(LINE_PREFIX_RE);
+    if (!prefixMatch)
+        return sanitized;
+    const prefix = prefixMatch[1];
+    const body = prefixMatch[2];
+    if (isDirectiveLine(body))
+        return sanitized;
+    const parts = body.split(EDGE_RE);
+    if (parts.length === 1)
+        return sanitized;
+    for (let i = 0; i < parts.length; i += 2) {
+        parts[i] = sanitizeNodeReference(parts[i], aliasFor);
+    }
+    return prefix + parts.join('');
+}
+function replaceLiteralLineBreaksInLabels(line) {
+    return line.replace(NODE_LABEL_RE, (label) => label.replace(/\\n/g, '<br/>'));
+}
+function quoteUnsafeEdgeLabels(line) {
+    return line.replace(EDGE_LABEL_RE, (match, label) => {
+        const trimmed = label.trim();
+        if (!UNSAFE_EDGE_LABEL_RE.test(trimmed))
+            return match;
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return match;
+        }
+        return `|"${escapeMermaidLabel(trimmed)}"|`;
+    });
+}
+function sanitizeNodeReference(segment, aliasFor) {
+    const match = segment.match(/^(\s*)([A-Za-z0-9_.:/()-]+)(.*?)(\s*)$/);
+    if (!match)
+        return segment;
+    const [, leading, id, suffix, trailing] = match;
+    if (!NODE_ID_RE.test(id) || !UNSAFE_NODE_ID_RE.test(id))
+        return segment;
+    const hasInlineLabel = suffix.trim().startsWith('[') || suffix.trim().startsWith('(') || suffix.trim().startsWith('{');
+    if (hasInlineLabel)
+        return `${leading}${aliasFor(id)}${suffix}${trailing}`;
+    return `${leading}${aliasFor(id)}["${escapeMermaidLabel(id)}"]${suffix}${trailing}`;
+}
+function escapeMermaidLabel(label) {
+    return label.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function isDirectiveLine(line) {
+    const trimmed = line.trim();
+    return (trimmed === '' ||
+        trimmed.startsWith('%%') ||
+        trimmed.startsWith('graph ') ||
+        trimmed.startsWith('flowchart ') ||
+        trimmed.startsWith('sequenceDiagram') ||
+        trimmed.startsWith('classDiagram') ||
+        trimmed.startsWith('stateDiagram') ||
+        trimmed.startsWith('erDiagram') ||
+        trimmed.startsWith('journey') ||
+        trimmed.startsWith('gantt') ||
+        trimmed.startsWith('pie ') ||
+        trimmed.startsWith('mindmap') ||
+        trimmed.startsWith('timeline') ||
+        trimmed.startsWith('subgraph ') ||
+        trimmed === 'end');
+}

package/dist/mcp/local/local-backend.js

@@ -634,8 +634,10 @@ export class LocalBackend {
             timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
             timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
         ]);
-        const bm25Results = bm25SearchResult.results;
-        const ftsUsed = bm25SearchResult.ftsUsed;
+        // Guard against undefined results (#1489) — when FTS is entirely
+        // unavailable the search helper may return an unexpected shape.
+        const bm25Results = bm25SearchResult?.results ?? [];
+        const ftsUsed = bm25SearchResult?.ftsUsed ?? false;
         // Merge via reciprocal rank fusion
         timer.start('merge');
         const scoreMap = new Map();
@@ -651,8 +653,9 @@ export class LocalBackend {
                 scoreMap.set(key, { score: rrfScore, data: result });
             }
         }
-        for (let i = 0; i < semanticResults.length; i++) {
-            const result = semanticResults[i];
+        const safeSemanticResults = semanticResults ?? [];
+        for (let i = 0; i < safeSemanticResults.length; i++) {
+            const result = safeSemanticResults[i];
             const key = result.nodeId || result.filePath;
             const rrfScore = 1 / (60 + i);
             const existing = scoreMap.get(key);
@@ -826,7 +829,15 @@ export class LocalBackend {
      * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
      */
     async bm25Search(repo, query, limit) {
-        const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js');
+        let searchFTSFromLbug;
+        try {
+            ({ searchFTSFromLbug } = await import('../../core/search/bm25-index.js'));
+        }
+        catch (err) {
+            // Module import can fail in sandboxed MCP contexts (#1489)
+            logger.warn({ err: err?.message }, 'GitNexus: bm25-index.js import failed — falling back to semantic-only');
+            return { results: [], ftsUsed: false };
+        }
         let ftsResponse;
         try {
             ftsResponse = await searchFTSFromLbug(query, limit, repo.id);
@@ -835,8 +846,10 @@ export class LocalBackend {
             logger.error({ err: err.message }, 'GitNexus: BM25/FTS search failed (FTS indexes may not exist) -');
             return { results: [], ftsUsed: false };
         }
-        const bm25Results = ftsResponse.results;
-        const ftsUsed = ftsResponse.ftsAvailable;
+        // Guard against unexpected response shape (#1489) — ftsResponse.results
+        // could be undefined when the FTS extension is unavailable in the MCP process.
+        const bm25Results = ftsResponse?.results ?? [];
+        const ftsUsed = ftsResponse?.ftsAvailable ?? false;
         const results = [];
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;

package/dist/storage/file-hash.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-file content hashing for incremental DB writeback.
+ *
+ * On every analyze run we compute SHA-256 of every file's content and
+ * store the map in meta.json. The next run compares disk against the
+ * stored map and produces:
+ *   - `changed` — content differs (re-emit DB rows for this file)
+ *   - `added`   — file is new on disk (insert DB rows)
+ *   - `deleted` — file was in last meta but no longer on disk (drop rows)
+ *
+ * The pipeline still parses every file (correctness invariant: cross-file
+ * resolution needs full data). What this enables is a SELECTIVE DB
+ * writeback: instead of wipe-and-reload of the whole graph (~50s of CSV
+ * COPY on a 25K-node repo), we only delete-and-rewrite rows for the
+ * changed/added/deleted set.
+ *
+ * See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
+ * (Option B revision).
+ */
+/**
+ * Compute SHA-256 of a single file. Returns null when the file can't be
+ * read — caller treats that as "no signature, assume changed".
+ */
+export declare const computeFileHash: (absPath: string) => Promise<string | null>;
+/**
+ * Compute SHA-256 hashes for many files in parallel batches. Files that
+ * fail to read are omitted from the result map.
+ */
+export declare const computeFileHashes: (repoPath: string, relPaths: readonly string[]) => Promise<Map<string, string>>;
+/** Result of comparing the current on-disk hashes against stored ones. */
+export interface FileHashDiff {
+    /** Files whose content hash differs from stored. */
+    changed: string[];
+    /** Files in the current scan that weren't in the stored map. */
+    added: string[];
+    /** Files in the stored map that aren't in the current scan. */
+    deleted: string[];
+    /** All files whose DB rows must be replaced (changed ∪ added). */
+    toWrite: string[];
+}
+/**
+ * Diff a current hash map against a previously stored one.
+ *
+ * Sorted output so two runs produce identical diff arrays for the same
+ * changes — useful for stable logging / equivalence checks.
+ */
+export declare const diffFileHashes: (current: ReadonlyMap<string, string>, stored: Readonly<Record<string, string>> | undefined) => FileHashDiff;

package/dist/storage/file-hash.js

@@ -0,0 +1,86 @@
+/**
+ * Per-file content hashing for incremental DB writeback.
+ *
+ * On every analyze run we compute SHA-256 of every file's content and
+ * store the map in meta.json. The next run compares disk against the
+ * stored map and produces:
+ *   - `changed` — content differs (re-emit DB rows for this file)
+ *   - `added`   — file is new on disk (insert DB rows)
+ *   - `deleted` — file was in last meta but no longer on disk (drop rows)
+ *
+ * The pipeline still parses every file (correctness invariant: cross-file
+ * resolution needs full data). What this enables is a SELECTIVE DB
+ * writeback: instead of wipe-and-reload of the whole graph (~50s of CSV
+ * COPY on a 25K-node repo), we only delete-and-rewrite rows for the
+ * changed/added/deleted set.
+ *
+ * See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
+ * (Option B revision).
+ */
+import { createHash } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Compute SHA-256 of a single file. Returns null when the file can't be
+ * read — caller treats that as "no signature, assume changed".
+ */
+export const computeFileHash = async (absPath) => {
+    try {
+        const buf = await fs.readFile(absPath);
+        return createHash('sha256').update(buf).digest('hex');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Compute SHA-256 hashes for many files in parallel batches. Files that
+ * fail to read are omitted from the result map.
+ */
+export const computeFileHashes = async (repoPath, relPaths) => {
+    const out = new Map();
+    const BATCH = 100;
+    for (let i = 0; i < relPaths.length; i += BATCH) {
+        const batch = relPaths.slice(i, i + BATCH);
+        const results = await Promise.all(batch.map(async (rel) => {
+            const h = await computeFileHash(path.join(repoPath, rel));
+            return h ? [rel, h] : null;
+        }));
+        for (const r of results)
+            if (r)
+                out.set(r[0], r[1]);
+    }
+    return out;
+};
+/**
+ * Diff a current hash map against a previously stored one.
+ *
+ * Sorted output so two runs produce identical diff arrays for the same
+ * changes — useful for stable logging / equivalence checks.
+ */
+export const diffFileHashes = (current, stored) => {
+    const storedMap = new Map(stored ? Object.entries(stored) : []);
+    const changed = [];
+    const added = [];
+    for (const [p, h] of current) {
+        const prev = storedMap.get(p);
+        if (prev === undefined)
+            added.push(p);
+        else if (prev !== h)
+            changed.push(p);
+    }
+    const deleted = [];
+    for (const p of storedMap.keys()) {
+        if (!current.has(p))
+            deleted.push(p);
+    }
+    changed.sort();
+    added.sort();
+    deleted.sort();
+    return {
+        changed,
+        added,
+        deleted,
+        toWrite: [...changed, ...added].sort(),
+    };
+};

package/dist/storage/parse-cache.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Chunk-level content-addressed parse cache.
+ *
+ * The pipeline always parses every file (correctness invariant: cross-file
+ * resolution and downstream phases need full graph data). What this cache
+ * does is skip the tree-sitter worker dispatch when a chunk's contents
+ * haven't changed since the last run.
+ *
+ * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
+ * budgets. The cache key is `sha256(joined(filePath:contentHash for each
+ * file in the chunk, sorted))`. A change to a single file invalidates only
+ * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ *
+ * Why not per-file:
+ * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
+ *   Splitting back to per-file would require reworking the worker contract.
+ * - Chunk-level invalidation gives a useful speedup floor (98% on a single
+ *   1-of-50 invalidated chunk) without touching the worker.
+ *
+ * Survives `--force` because it's content-addressed: the same bytes always
+ * produce the same key. `--force` only matters for the LadybugDB writeback;
+ * the cache itself is always safe to reuse.
+ */
+import type { ParseWorkerResult } from '../core/ingestion/workers/parse-worker.js';
+export declare const PARSE_CACHE_VERSION: string;
+/** Runtime view: keyed Map for fast lookup; mutated in place during a run. */
+export interface ParseCache {
+    version: string;
+    entries: Map<string, ParseWorkerResult[]>;
+    /**
+     * Hashes referenced (hit OR miss-and-stored) by the current run.
+     * The parse phase populates this as it processes chunks; the orchestrator
+     * uses it as input to `pruneCache` before saving so entries that no
+     * longer correspond to any chunk in the current scan are discarded.
+     * Transient — never serialized to disk.
+     */
+    usedKeys: Set<string>;
+}
+/** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
+export declare const fileContentHash: (content: Buffer | string) => string;
+/**
+ * Compute the canonical cache key for a chunk's contents.
+ *
+ * `entries` is the list of (filePath, file content hash) for every file
+ * in the chunk. We sort by filePath before hashing so chunks composed of
+ * the same files in different order produce the same key.
+ */
+export declare const computeChunkHash: (entries: Array<{
+    filePath: string;
+    contentHash: string;
+}>) => string;
+/**
+ * Load the parse cache. Returns an empty cache on any failure (missing
+ * file, corrupt JSON, version mismatch). Never throws on a normal load.
+ */
+export declare const loadParseCache: (storagePath: string) => Promise<ParseCache>;
+/**
+ * Persist the cache to disk using a temp directory + rename.
+ *
+ * Writes shards under `${cacheDir}.tmp`, then removes the old `cacheDir` and
+ * renames the temp directory into place. There is a crash window after
+ * `rm(cacheDir)` and before `rename(tmpDir, cacheDir)` where no cache exists;
+ * that is acceptable — `loadParseCache` yields empty and the next run
+ * reparses. This is not a single atomic swap of the whole tree, but avoids
+ * leaving a half-written shard set visible to readers.
+ */
+export declare const saveParseCache: (storagePath: string, cache: ParseCache) => Promise<void>;
+/**
+ * Drop entries whose hashes are not in `usedHashes`. Called at the end
+ * of a run so chunks that no longer correspond to any current chunk
+ * don't keep their stale entries forever.
+ */
+export declare const pruneCache: (cache: ParseCache, usedHashes: ReadonlySet<string>) => number;

package/dist/storage/parse-cache.js

@@ -0,0 +1,253 @@
+/**
+ * Chunk-level content-addressed parse cache.
+ *
+ * The pipeline always parses every file (correctness invariant: cross-file
+ * resolution and downstream phases need full graph data). What this cache
+ * does is skip the tree-sitter worker dispatch when a chunk's contents
+ * haven't changed since the last run.
+ *
+ * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
+ * budgets. The cache key is `sha256(joined(filePath:contentHash for each
+ * file in the chunk, sorted))`. A change to a single file invalidates only
+ * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ *
+ * Why not per-file:
+ * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
+ *   Splitting back to per-file would require reworking the worker contract.
+ * - Chunk-level invalidation gives a useful speedup floor (98% on a single
+ *   1-of-50 invalidated chunk) without touching the worker.
+ *
+ * Survives `--force` because it's content-addressed: the same bytes always
+ * produce the same key. `--force` only matters for the LadybugDB writeback;
+ * the cache itself is always safe to reuse.
+ */
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Cache version composed of:
+ *   - A schema bump knob (`SCHEMA_BUMP`) for hand-controlled invalidation
+ *     when ParseWorkerResult shape or upstream parse semantics change.
+ *   - The current `gitnexus` npm package version, read at module load.
+ *     Any release that ships an updated tree-sitter grammar or revised
+ *     extractor logic implies a version bump in package.json, which
+ *     automatically invalidates the on-disk cache. Without this, a user
+ *     running `npm i -g gitnexus@latest` after a parser-affecting
+ *     release would silently replay pre-upgrade ParseWorkerResults
+ *     against the new graph schema (Bugbot/Claude review on #1479).
+ *
+ * On version mismatch, `loadParseCache` returns an empty cache and the
+ * next save overwrites the on-disk file with the new version baked in.
+ */
+const SCHEMA_BUMP = 1;
+const GITNEXUS_PKG_VERSION = (() => {
+    try {
+        // package.json sits at gitnexus/package.json — two levels up from
+        // gitnexus/src/storage/parse-cache.ts (or its dist/ equivalent).
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            path.join(here, '..', '..', 'package.json'), // src/storage → gitnexus/
+            path.join(here, '..', '..', '..', 'package.json'), // dist/storage → gitnexus/
+        ];
+        const requireCJS = createRequire(import.meta.url);
+        for (const c of candidates) {
+            try {
+                const pkg = requireCJS(c);
+                if (typeof pkg?.version === 'string')
+                    return pkg.version;
+            }
+            catch {
+                /* try next candidate */
+            }
+        }
+    }
+    catch {
+        /* fall through to fallback */
+    }
+    return '0.0.0-unknown';
+})();
+export const PARSE_CACHE_VERSION = `${SCHEMA_BUMP}+${GITNEXUS_PKG_VERSION}`;
+const LEGACY_CACHE_FILENAME = 'parse-cache.json';
+const CACHE_DIRNAME = 'parse-cache';
+const CACHE_INDEX_FILENAME = 'index.json';
+/** Keys on disk always come from `computeChunkHash` — 64-char lowercase hex. */
+const CHUNK_CACHE_KEY_HEX_RE = /^[a-f0-9]{64}$/;
+const isValidChunkCacheKey = (chunkHash) => CHUNK_CACHE_KEY_HEX_RE.test(chunkHash);
+/** SHA-256 hex of a single string or buffer. */
+const sha256Hex = (input) => createHash('sha256')
+    .update(typeof input === 'string' ? Buffer.from(input) : input)
+    .digest('hex');
+/** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
+export const fileContentHash = (content) => sha256Hex(content);
+/**
+ * Compute the canonical cache key for a chunk's contents.
+ *
+ * `entries` is the list of (filePath, file content hash) for every file
+ * in the chunk. We sort by filePath before hashing so chunks composed of
+ * the same files in different order produce the same key.
+ */
+export const computeChunkHash = (entries) => {
+    const sorted = [...entries].sort((a, b) => (a.filePath < b.filePath ? -1 : 1));
+    const joined = sorted.map((e) => `${e.filePath}:${e.contentHash}`).join('\n');
+    return sha256Hex(joined);
+};
+/**
+ * JSON replacer that round-trips Map/Set instances through plain JSON.
+ *
+ * `ParseWorkerResult.parsedFiles[*].scopes[*].typeBindings` is a
+ * `ReadonlyMap<string, TypeRef>`; without this transform it serializes
+ * to `{}` and downstream code that iterates / `.get()`s on it crashes
+ * with "is not iterable". Applied symmetrically by `mapReviver` on
+ * load so the in-memory shape stays Map-typed.
+ */
+const MAP_TAG = '__$mapEntries$__';
+const SET_TAG = '__$setValues$__';
+const mapReplacer = (_key, value) => {
+    if (value instanceof Map)
+        return { [MAP_TAG]: Array.from(value.entries()) };
+    if (value instanceof Set)
+        return { [SET_TAG]: Array.from(value.values()) };
+    return value;
+};
+const mapReviver = (_key, value) => {
+    if (value && typeof value === 'object') {
+        const v = value;
+        if (Array.isArray(v[MAP_TAG]))
+            return new Map(v[MAP_TAG]);
+        if (Array.isArray(v[SET_TAG]))
+            return new Set(v[SET_TAG]);
+    }
+    return value;
+};
+const getLegacyCachePath = (storagePath) => path.join(storagePath, LEGACY_CACHE_FILENAME);
+const getCacheDirPath = (storagePath) => path.join(storagePath, CACHE_DIRNAME);
+const getCacheIndexPath = (storagePath) => path.join(getCacheDirPath(storagePath), CACHE_INDEX_FILENAME);
+const getCacheChunkPath = (storagePath, chunkHash) => path.join(getCacheDirPath(storagePath), `${chunkHash}.json`);
+const loadLegacyParseCache = async (storagePath) => {
+    const cachePath = getLegacyCachePath(storagePath);
+    try {
+        const raw = await fs.readFile(cachePath, 'utf-8');
+        const data = JSON.parse(raw, mapReviver);
+        if (typeof data !== 'object' ||
+            data === null ||
+            data.version !== PARSE_CACHE_VERSION ||
+            typeof data.entries !== 'object' ||
+            data.entries === null) {
+            return emptyCache();
+        }
+        const entries = new Map();
+        for (const [k, v] of Object.entries(data.entries)) {
+            if (Array.isArray(v))
+                entries.set(k, v);
+        }
+        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() };
+    }
+    catch {
+        return emptyCache();
+    }
+};
+const loadShardedParseCache = async (storagePath) => {
+    const indexPath = getCacheIndexPath(storagePath);
+    try {
+        const raw = await fs.readFile(indexPath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (typeof data !== 'object' ||
+            data === null ||
+            data.version !== PARSE_CACHE_VERSION ||
+            !Array.isArray(data.keys)) {
+            return emptyCache();
+        }
+        const entries = new Map();
+        for (const chunkHash of data.keys) {
+            if (typeof chunkHash !== 'string' || !isValidChunkCacheKey(chunkHash))
+                continue;
+            try {
+                const chunkRaw = await fs.readFile(getCacheChunkPath(storagePath, chunkHash), 'utf-8');
+                const chunkData = JSON.parse(chunkRaw, mapReviver);
+                if (Array.isArray(chunkData))
+                    entries.set(chunkHash, chunkData);
+            }
+            catch {
+                /* skip corrupt or missing shard */
+            }
+        }
+        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Load the parse cache. Returns an empty cache on any failure (missing
+ * file, corrupt JSON, version mismatch). Never throws on a normal load.
+ */
+export const loadParseCache = async (storagePath) => {
+    const sharded = await loadShardedParseCache(storagePath);
+    if (sharded)
+        return sharded;
+    return loadLegacyParseCache(storagePath);
+};
+/**
+ * Persist the cache to disk using a temp directory + rename.
+ *
+ * Writes shards under `${cacheDir}.tmp`, then removes the old `cacheDir` and
+ * renames the temp directory into place. There is a crash window after
+ * `rm(cacheDir)` and before `rename(tmpDir, cacheDir)` where no cache exists;
+ * that is acceptable — `loadParseCache` yields empty and the next run
+ * reparses. This is not a single atomic swap of the whole tree, but avoids
+ * leaving a half-written shard set visible to readers.
+ */
+export const saveParseCache = async (storagePath, cache) => {
+    await fs.mkdir(storagePath, { recursive: true });
+    const cacheDir = getCacheDirPath(storagePath);
+    const tmpDir = `${cacheDir}.tmp`;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+    await fs.mkdir(tmpDir, { recursive: true });
+    const keys = [];
+    for (const [chunkHash, chunkResults] of cache.entries) {
+        if (!isValidChunkCacheKey(chunkHash))
+            continue;
+        let payload;
+        try {
+            payload = JSON.stringify(chunkResults, mapReplacer);
+        }
+        catch {
+            // Extremely dense chunks could theoretically exceed string limits; skip
+            // rather than failing the entire save (orchestrator catches save errors).
+            continue;
+        }
+        keys.push(chunkHash);
+        const chunkPath = path.join(tmpDir, `${chunkHash}.json`);
+        await fs.writeFile(chunkPath, payload, 'utf-8');
+    }
+    const index = {
+        version: cache.version,
+        keys,
+    };
+    await fs.writeFile(path.join(tmpDir, CACHE_INDEX_FILENAME), JSON.stringify(index), 'utf-8');
+    await fs.rm(cacheDir, { recursive: true, force: true });
+    await fs.rename(tmpDir, cacheDir);
+    await fs.rm(getLegacyCachePath(storagePath), { force: true });
+};
+/**
+ * Drop entries whose hashes are not in `usedHashes`. Called at the end
+ * of a run so chunks that no longer correspond to any current chunk
+ * don't keep their stale entries forever.
+ */
+export const pruneCache = (cache, usedHashes) => {
+    let removed = 0;
+    for (const k of cache.entries.keys()) {
+        if (!usedHashes.has(k)) {
+            cache.entries.delete(k);
+            removed++;
+        }
+    }
+    return removed;
+};
+const emptyCache = () => ({
+    version: PARSE_CACHE_VERSION,
+    entries: new Map(),
+    usedKeys: new Set(),
+});

package/dist/storage/repo-manager.d.ts

@@ -56,7 +56,38 @@ export interface RepoMeta {
         processes?: number;
         embeddings?: number;
     };
+    /**
+     * Bumped whenever incremental-indexing invariants change in an
+     * incompatible way (delete-and-rewrite logic, subgraph extraction,
+     * graph-wide node handling). On mismatch, runFullAnalysis forces a
+     * full rebuild rather than risk an inconsistent incremental update.
+     */
+    schemaVersion?: number;
+    /**
+     * SHA-256 of every file's content at the time of the last successful
+     * indexing run. The next run computes current hashes and diffs against
+     * this map to determine which files' DB rows must be replaced.
+     * Map keys are repo-relative paths.
+     */
+    fileHashes?: Record<string, string>;
+    /**
+     * Crash-recovery dirty flag. Written to meta.json BEFORE any
+     * destructive DB mutation in an incremental run; cleared on success
+     * by overwriting meta.json. If a run crashes between, the next run
+     * sees the flag and forces a full rebuild — the cheapest path back
+     * to a known-good index.
+     */
+    incrementalInProgress?: {
+        /** When the incremental run started (epoch ms). */
+        startedAt: number;
+        /** Number of files in the writable set, for diagnostic logs. */
+        toWriteCount: number;
+    };
 }
+/**
+ * Bumped whenever incremental-indexing invariants change incompatibly.
+ */
+export declare const INCREMENTAL_SCHEMA_VERSION = 1;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;
@@ -112,7 +143,16 @@ export declare const cleanupOldKuzuFiles: (storagePath: string) => Promise<{
  */
 export declare const loadMeta: (storagePath: string) => Promise<RepoMeta | null>;
 /**
- * Save metadata to storage
+ * Save metadata to storage.
+ *
+ * Atomic via tmp-file + rename (matches `saveParseCache`'s pattern). The
+ * `incrementalInProgress` dirty flag travels through this file — a crash
+ * mid-write would leave a corrupt `meta.json` that the next run's
+ * `loadMeta` would silently treat as "no prior index", losing the dirty
+ * flag and skipping the recovery full-rebuild. Write-and-rename rules
+ * that out: the rename is atomic on POSIX and on Windows (`fs.rename`
+ * on `node:fs/promises` uses `MoveFileEx(REPLACE_EXISTING)`), so either
+ * the old or the new file is observed at every moment.
  */
 export declare const saveMeta: (storagePath: string, meta: RepoMeta) => Promise<void>;
 /**