gitnexus 1.6.13-rc.62 → 1.6.13-rc.64

package/dist/cli/detect-changes-format.js

@@ -1,5 +1,6 @@
 import { t } from './i18n/index.js';
 import { formatSymbolLine } from './format-symbol.js';
+import { formatPathForTerminal } from './format-path.js';
 export function formatDetectChangesResult(result) {
     const payload = (result ?? {});
     if (payload.error)
@@ -14,6 +15,11 @@ export function formatDetectChangesResult(result) {
     const notes = [];
     if (payload.partial)
         notes.push(t('tool.detectChanges.partial'));
+    if (payload.unmapped_files?.length) {
+        notes.push(t('tool.detectChanges.unmappedSource', {
+            files: payload.unmapped_files.map(formatPathForTerminal).join(', '),
+        }));
+    }
     // The plain truncation note reassures that the counts are whole. That is only
     // true when the run did NOT also degrade — `changed_count` sums the batches
     // that succeeded — so the two flags together get a different sentence.

package/dist/cli/format-path.d.ts

@@ -0,0 +1,2 @@
+/** Quote control-bearing paths for terminal output; structured results retain raw paths. */
+export declare const formatPathForTerminal: (filePath: string) => string;

package/dist/cli/format-path.js

@@ -0,0 +1,4 @@
+/** Quote control-bearing paths for terminal output; structured results retain raw paths. */
+export const formatPathForTerminal = (filePath) => /[\u0000-\u001f\u007f-\u009f]/.test(filePath)
+    ? JSON.stringify(filePath).replace(/[\u007f-\u009f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
+    : filePath;

package/dist/cli/i18n/en.d.ts

@@ -106,7 +106,8 @@ export declare const en: {
     readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': 'No changes detected.';
     readonly 'tool.detectChanges.noOverlappingSymbols': 'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.';
-    readonly 'tool.detectChanges.partial': 'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.';
+    readonly 'tool.detectChanges.partial': 'PARTIAL RESULT: changed-symbol or process mapping is incomplete. Do not read this as a clean pre-commit check.';
+    readonly 'tool.detectChanges.unmappedSource': 'No symbols mapped for changed source files: {{files}}. Rebuild the index and inspect the diff; retry alone may not resolve missing or out-of-range symbols.';
     readonly 'tool.detectChanges.truncated': 'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.';
     readonly 'tool.detectChanges.truncatedDegraded': 'LISTING CAPPED: the changed-symbol list was capped. The run also degraded, so the counts are a lower bound, not a total.';
     readonly 'tool.detectChanges.changesSummary': 'Changes: {{files}} files, {{symbols}} symbols';

package/dist/cli/i18n/en.js

@@ -106,7 +106,8 @@ export const en = {
     'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
     'tool.detectChanges.noOverlappingSymbols': 'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.',
-    'tool.detectChanges.partial': 'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.',
+    'tool.detectChanges.partial': 'PARTIAL RESULT: changed-symbol or process mapping is incomplete. Do not read this as a clean pre-commit check.',
+    'tool.detectChanges.unmappedSource': 'No symbols mapped for changed source files: {{files}}. Rebuild the index and inspect the diff; retry alone may not resolve missing or out-of-range symbols.',
     'tool.detectChanges.truncated': 'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.',
     // The reassurance above is only true on its own. When the run also degraded,
     // `changed_count` was summed from the batches that SUCCEEDED, so it is a floor.

package/dist/cli/i18n/resources.d.ts

@@ -107,7 +107,8 @@ export declare const cliResources: {
         readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
         readonly 'tool.detectChanges.noChanges': 'No changes detected.';
         readonly 'tool.detectChanges.noOverlappingSymbols': 'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.';
-        readonly 'tool.detectChanges.partial': 'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.';
+        readonly 'tool.detectChanges.partial': 'PARTIAL RESULT: changed-symbol or process mapping is incomplete. Do not read this as a clean pre-commit check.';
+        readonly 'tool.detectChanges.unmappedSource': 'No symbols mapped for changed source files: {{files}}. Rebuild the index and inspect the diff; retry alone may not resolve missing or out-of-range symbols.';
         readonly 'tool.detectChanges.truncated': 'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.';
         readonly 'tool.detectChanges.truncatedDegraded': 'LISTING CAPPED: the changed-symbol list was capped. The run also degraded, so the counts are a lower bound, not a total.';
         readonly 'tool.detectChanges.changesSummary': 'Changes: {{files}} files, {{symbols}} symbols';
@@ -435,6 +436,7 @@ export declare const cliResources: {
         'tool.detectChanges.noChanges': string;
         'tool.detectChanges.noOverlappingSymbols': string;
         'tool.detectChanges.partial': string;
+        'tool.detectChanges.unmappedSource': string;
         'tool.detectChanges.truncated': string;
         'tool.detectChanges.truncatedDegraded': string;
         'tool.detectChanges.changesSummary': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -107,6 +107,7 @@ export declare const zhCN: {
     'tool.detectChanges.noChanges': string;
     'tool.detectChanges.noOverlappingSymbols': string;
     'tool.detectChanges.partial': string;
+    'tool.detectChanges.unmappedSource': string;
     'tool.detectChanges.truncated': string;
     'tool.detectChanges.truncatedDegraded': string;
     'tool.detectChanges.changesSummary': string;

package/dist/cli/i18n/zh-CN.js

@@ -106,7 +106,8 @@ export const zhCN = {
     'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
     'tool.detectChanges.noChanges': '未检测到变更。',
     'tool.detectChanges.noOverlappingSymbols': 'diff 触及 {{files}} 个文件，但没有索引符号与这些 hunk 重叠 — 并非干净工作区。',
-    'tool.detectChanges.partial': '结果不完整：图查询失败，可能遗漏已变更符号。请勿将其视为通过的提交前检查。',
+    'tool.detectChanges.partial': '结果不完整：变更符号或流程映射不完整。请勿将其视为通过的提交前检查。',
+    'tool.detectChanges.unmappedSource': '变更源码文件未映射到符号：{{files}}。请重建索引并检查 diff；仅重试可能无法解决符号缺失或源码范围不匹配。',
     'tool.detectChanges.truncated': '列表已截断：已变更符号列表被截断，未列出全部变更符号。计数与风险等级仍涵盖全部符号。',
     'tool.detectChanges.truncatedDegraded': '列表已截断：已变更符号列表被截断。本次运行同时不完整，因此计数为下限而非总数。',
     'tool.detectChanges.changesSummary': '变更：{{files}} 个文件，{{symbols}} 个符号',

package/dist/cli/status.js

@@ -16,6 +16,7 @@ import { getFtsDisabledReason, FTS_DISABLED_MESSAGE } from '../core/search/fts-p
 import { detectIndexContentDrift } from '../core/index-content-drift.js';
 import { checkoutIsDirectory, contentRetentionFromMeta, isFullSourceAvailable, } from '../core/content-retention.js';
 import { t } from './i18n/index.js';
+import { formatPathForTerminal as formatDriftPath } from './format-path.js';
 /** How many drifted paths the report names before summarizing the rest. */
 const DRIFT_SAMPLE_LIMIT = 10;
 /**
@@ -50,8 +51,6 @@ const describeContentDrift = (drift) => {
         },
     };
 };
-/** Escape control characters in repo-relative paths before printing. */
-const formatDriftPath = (rel) => /[\u0000-\u001f\u007f]/.test(rel) ? JSON.stringify(rel) : rel;
 const printDriftDetail = (drift) => {
     console.log(t('status.indexContentDrifted', {
         changed: drift.changed.length,

package/dist/core/incremental/write-reconciliation.d.ts

@@ -0,0 +1,23 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+interface IdentityRow {
+    id: string;
+    name: string | null;
+    filePath: string | null;
+    startLine?: number | null;
+    endLine?: number | null;
+}
+/**
+ * Certify the identity fields used by context/impact/detect_changes, including
+ * retained rows. A write-set-only probe misses corruption of an unchanged row.
+ * Scan one label at a time, without path/range predicates: a corrupt field must
+ * not be able to hide its own row. No multi-label scans (#3139), N+1 ID lookups,
+ * source-content copies, or whole-graph row materialization.
+ *
+ * This certifies node identity, not relationships or native storage internals.
+ * Call after COPY/checkpoint and after FTS/embedding/checkpoint, before metadata.
+ */
+export declare function reconcileGraphNodeIdentities(graph: KnowledgeGraph, query: (cypher: string) => Promise<IdentityRow[]>, phase: string): Promise<{
+    nodes: number;
+    tables: number;
+}>;
+export {};

package/dist/core/incremental/write-reconciliation.js

@@ -0,0 +1,80 @@
+import { NODE_TABLES } from '../lbug/schema.js';
+import { sanitizeUTF8 } from '../lbug/csv-generator.js';
+// These layers need a different oracle: folders can outlive their last file,
+// derived nodes may be preserved without recomputation, and PDG can be streamed.
+const EXCLUDED = new Set(['Folder', 'Community', 'Process', 'BasicBlock']);
+const WITHOUT_RANGE = new Set(['File', 'Route', 'Tool']);
+const storedString = (value) => sanitizeUTF8(value || '');
+const storedIdentityField = (node, field) => {
+    const value = node.properties[field];
+    if (field === 'name' || field === 'filePath') {
+        return storedString(value);
+    }
+    if (node.label === 'Destination') {
+        return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    }
+    return value ?? -1;
+};
+/**
+ * Certify the identity fields used by context/impact/detect_changes, including
+ * retained rows. A write-set-only probe misses corruption of an unchanged row.
+ * Scan one label at a time, without path/range predicates: a corrupt field must
+ * not be able to hide its own row. No multi-label scans (#3139), N+1 ID lookups,
+ * source-content copies, or whole-graph row materialization.
+ *
+ * This certifies node identity, not relationships or native storage internals.
+ * Call after COPY/checkpoint and after FTS/embedding/checkpoint, before metadata.
+ */
+export async function reconcileGraphNodeIdentities(graph, query, phase) {
+    const expected = new Map();
+    for (const table of NODE_TABLES) {
+        if (!EXCLUDED.has(table))
+            expected.set(table, new Map());
+    }
+    for (const node of graph.iterNodes()) {
+        const table = expected.get(node.label);
+        if (!table)
+            continue;
+        const id = storedString(node.id);
+        if (!id || table.has(id)) {
+            throw new Error(`Graph identity reconciliation (${phase}): invalid or duplicate ID ${id}`);
+        }
+        table.set(id, node);
+    }
+    let nodes = 0;
+    for (const [table, remaining] of expected) {
+        const fields = WITHOUT_RANGE.has(table)
+            ? ['id', 'name', 'filePath']
+            : ['id', 'name', 'filePath', 'startLine', 'endLine'];
+        const identityFields = fields.slice(1);
+        const fail = (detail, cause) => {
+            throw new Error(`Graph identity reconciliation failed (${phase}, ${table}): ${detail}. ` +
+                'Freshness was not advanced; run `gitnexus analyze --force` to rebuild the graph.', { cause });
+        };
+        let rows;
+        try {
+            rows = await query(`MATCH (n:\`${table}\`) RETURN ${fields.map((f) => `n.${f} AS ${f}`).join(', ')}`);
+        }
+        catch (error) {
+            fail(`could not read identity fields: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+        for (const row of rows) {
+            const node = remaining.get(row.id);
+            if (!node)
+                fail(`unexpected or duplicate ID ${JSON.stringify(row.id)}`);
+            for (const field of identityFields) {
+                const wanted = storedIdentityField(node, field);
+                const actual = field === 'name' || field === 'filePath' ? (row[field] ?? '') : row[field];
+                if (actual !== wanted) {
+                    fail(`${row.id}.${field}: expected ${JSON.stringify(wanted)}, read ${JSON.stringify(actual)}`);
+                }
+            }
+            remaining.delete(row.id);
+            nodes++;
+        }
+        if (remaining.size) {
+            fail(`${remaining.size} missing ID(s), including ${JSON.stringify(remaining.keys().next().value)}`);
+        }
+    }
+    return { nodes, tables: expected.size };
+}

package/dist/core/ingestion/cobol/file-types.d.ts

@@ -0,0 +1,6 @@
+export declare const COBOL_EXTENSIONS: Set<string>;
+export declare const JCL_EXTENSIONS: Set<string>;
+/** Includes COBOL programs and copybooks accepted by ingestion. */
+export declare function isCobolFile(filePath: string): boolean;
+/** Includes job and procedure aliases accepted by JCL ingestion. */
+export declare function isJclFile(filePath: string): boolean;

package/dist/core/ingestion/cobol/file-types.js

@@ -0,0 +1,12 @@
+import path from 'node:path';
+// Keep detection shared without loading the analyze-only language providers.
+export const COBOL_EXTENSIONS = new Set(['.cob', '.cbl', '.cobol', '.cpy', '.copybook']);
+export const JCL_EXTENSIONS = new Set(['.jcl', '.job', '.proc']);
+/** Includes COBOL programs and copybooks accepted by ingestion. */
+export function isCobolFile(filePath) {
+    return COBOL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+/** Includes job and procedure aliases accepted by JCL ingestion. */
+export function isJclFile(filePath) {
+    return JCL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}

package/dist/core/ingestion/cobol-processor.d.ts

@@ -13,6 +13,7 @@
  *   5. Optionally process JCL files for job-step cross-references
  */
 import type { KnowledgeGraph } from '../graph/types.js';
+export { isCobolFile, isJclFile } from './cobol/file-types.js';
 interface CobolFile {
     path: string;
     content: string;
@@ -39,10 +40,6 @@ export interface CobolProcessResult {
     initializes: number;
     arithmeticOps: number;
 }
-/** Returns true if the file is a COBOL or copybook file. */
-export declare function isCobolFile(filePath: string): boolean;
-/** Returns true if the file is a JCL file. */
-export declare function isJclFile(filePath: string): boolean;
 /**
  * Process COBOL and JCL files into the knowledge graph.
  *
@@ -52,4 +49,3 @@ export declare function isJclFile(filePath: string): boolean;
  * @returns Summary of what was extracted
  */
 export declare const processCobol: (graph: KnowledgeGraph, files: CobolFile[], allPathSet: ReadonlySet<string>) => CobolProcessResult;
-export {};

package/dist/core/ingestion/cobol-processor.js

@@ -20,21 +20,13 @@ import { preprocessCobolSource, extractCobolSymbolsWithRegex, } from './cobol/co
 import { expandCopies } from './cobol/cobol-copy-expander.js';
 import { processJclFiles } from './cobol/jcl-processor.js';
 import { resolveCobolCopyTarget } from './languages/cobol/copy-target.js';
+import { COBOL_EXTENSIONS, JCL_EXTENSIONS } from './cobol/file-types.js';
+export { isCobolFile, isJclFile } from './cobol/file-types.js';
 import { logger } from '../logger.js';
 // ---------------------------------------------------------------------------
 // File detection
 // ---------------------------------------------------------------------------
-const COBOL_EXTENSIONS = new Set(['.cob', '.cbl', '.cobol', '.cpy', '.copybook']);
-const JCL_EXTENSIONS = new Set(['.jcl', '.job', '.proc']);
 const COPYBOOK_EXTENSIONS = new Set(['.cpy', '.copybook']);
-/** Returns true if the file is a COBOL or copybook file. */
-export function isCobolFile(filePath) {
-    return COBOL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
-}
-/** Returns true if the file is a JCL file. */
-export function isJclFile(filePath) {
-    return JCL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
-}
 /** Returns true if the file is a COBOL copybook. */
 function isCopybook(filePath) {
     return COPYBOOK_EXTENSIONS.has(path.extname(filePath).toLowerCase());

package/dist/core/ingestion/pipeline-phases/routes.d.ts

@@ -11,6 +11,7 @@
  * @output  routeRegistry, handlerContents
  */
 import type { PipelinePhase } from './types.js';
+export { isTemplateRouteCandidate } from '../utils/template-file.js';
 export interface RouteEntry {
     filePath: string;
     source: string;
@@ -39,6 +40,5 @@ export interface TemplateFetchCall {
     fetchURL: string;
     lineNumber: number;
 }
-export declare const isTemplateRouteCandidate: (filePath: string) => boolean;
 export declare function extractTemplateStaticFetchCalls(filePath: string, content: string, namedRouteUrls?: ReadonlyMap<string, string>): TemplateFetchCall[];
 export declare const routesPhase: PipelinePhase<RoutesOutput>;

package/dist/core/ingestion/pipeline-phases/routes.js

@@ -11,7 +11,7 @@
  * @output  routeRegistry, handlerContents
  */
 import { getPhaseOutput } from './types.js';
-import { isBladeTemplateFilename } from '../../../_shared/index.js';
+import { isTemplateRouteCandidate } from '../utils/template-file.js';
 import { nextjsFileToRouteURL, normalizeFetchURL } from '../route-extractors/nextjs.js';
 import { expoFileToRouteURL } from '../route-extractors/expo.js';
 import { phpFileToRouteURL } from '../route-extractors/php.js';
@@ -25,6 +25,7 @@ import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
+export { isTemplateRouteCandidate } from '../utils/template-file.js';
 const EXPO_NAV_PATTERNS = [
     /router\.(push|replace|navigate)\(\s*['"`]([^'"`]+)['"`]/g,
     /<Link\s+[^>]*href=\s*['"`]([^'"`]+)['"`]/g,
@@ -65,14 +66,6 @@ const TEMPLATE_NAMED_ROUTE_PATTERNS = [
 function hasRouteParameters(routeUrl) {
     return /\{[^}]+\}/.test(routeUrl);
 }
-export const isTemplateRouteCandidate = (filePath) => {
-    const normalized = filePath.replace(/\\/g, '/').toLowerCase();
-    return (normalized.endsWith('.html') ||
-        normalized.endsWith('.htm') ||
-        normalized.endsWith('.ejs') ||
-        normalized.endsWith('.hbs') ||
-        isBladeTemplateFilename(normalized));
-};
 export function extractTemplateStaticFetchCalls(filePath, content, namedRouteUrls = new Map()) {
     const calls = [];
     const seen = new Set();

package/dist/core/ingestion/utils/template-file.d.ts

@@ -0,0 +1,2 @@
+/** Templates whose URLs and fetches can contribute route relationships to the graph. */
+export declare const isTemplateRouteCandidate: (filePath: string) => boolean;

package/dist/core/ingestion/utils/template-file.js

@@ -0,0 +1,10 @@
+import { isBladeTemplateFilename } from '../../../_shared/index.js';
+/** Templates whose URLs and fetches can contribute route relationships to the graph. */
+export const isTemplateRouteCandidate = (filePath) => {
+    const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+    return (normalized.endsWith('.html') ||
+        normalized.endsWith('.htm') ||
+        normalized.endsWith('.ejs') ||
+        normalized.endsWith('.hbs') ||
+        isBladeTemplateFilename(normalized));
+};

package/dist/core/lbug/csv-generator.js

@@ -91,9 +91,14 @@ export const sanitizeUTF8 = (str) => {
 };
 export const escapeCSVField = (value) => {
     if (value === undefined || value === null)
-        return '""';
+        return '';
     let str = String(value);
     str = sanitizeUTF8(str);
+    // Preserve the NULL meaning of absent strings from the 0.18.3 writer.
+    // Newer LadybugDB readers retain a quoted empty field as a STRING value;
+    // it must stay unquoted or unresolved destination addresses can join.
+    if (str.length === 0)
+        return '';
     return `"${str.replace(/"/g, '""')}"`;
 };
 export const escapeCSVNumber = (value, defaultValue = -1) => {

package/dist/core/lbug/lbug-adapter.js

@@ -908,23 +908,59 @@ const doInitLbug = async (dbPath, options = {}) => {
 };
 /**
  * Run a COPY, retrying once with IGNORE_ERRORS=true (which skips row-level
- * errors) on first failure. On a second failure, hand the RAW retry error to
- * `onError` — each call site formats + slices its own message (#2226 F5: node
- * COPY slices to 200 chars and throws; relationship COPY slices to 80 and warns,
- * so the helper must not pre-format and lose that distinction). `onError` may
- * throw to propagate the failure.
+ * errors) on first failure. Log the original failure and native COPY/warning
+ * receipts even when the retry succeeds. Node COPY requires every row; a
+ * skipped-node receipt is a failure. Call sites retain their own message
+ * limits and relationship fallback policy.
  */
-const copyCsvWithRetry = async (targetConn, copyQuery, onError) => {
+const copyCsvWithRetry = async (targetConn, copyQuery, onError, expectedRows) => {
     try {
         await queryAndDrain(targetConn, copyQuery);
     }
-    catch {
+    catch (firstError) {
+        logger.warn({ err: firstError, copyQuery }, 'First COPY failure; retrying with IGNORE_ERRORS=true');
         try {
             const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
-            await queryAndDrain(targetConn, retryQuery);
+            // Keep COPY and its connection-local warning receipt in one critical
+            // section. Only project diagnostics, never skipped_line_or_record: that
+            // column contains source text. Warnings are retained at a bounded native
+            // limit, so their count is a lower bound, not the exact skipped total.
+            const retry = async () => {
+                await drainQueryResult(await targetConn.query('CALL CLEAR_WARNINGS()'));
+                const result = await readQueryRows(await targetConn.query(retryQuery));
+                const warnings = await readQueryRows(await targetConn.query('CALL SHOW_WARNINGS() RETURN message, file_path, line_number'));
+                // The native warning limit can be zero; warning rows alone cannot
+                // prove that every CSV row landed. Node COPY exposes its copied count
+                // in the result receipt even when warning retention is disabled.
+                const countReceipt = result
+                    .map((row) => String(row.result ?? ''))
+                    .map((message) => /^(\d+) tuples have been copied/.exec(message))
+                    .find(Boolean);
+                const copiedRows = countReceipt ? Number(countReceipt[1]) : undefined;
+                logger.warn({
+                    copyQuery,
+                    copyResult: result,
+                    expectedRows,
+                    copiedRows,
+                    skippedRows: expectedRows !== undefined && copiedRows !== undefined
+                        ? Math.max(0, expectedRows - copiedRows)
+                        : undefined,
+                    retainedWarnings: warnings.length,
+                    warningSamples: warnings.slice(0, 5),
+                }, 'COPY retry completed; retained warnings describe skipped rows (a lower bound)');
+                if (expectedRows !== undefined && (copiedRows !== expectedRows || warnings.length > 0)) {
+                    throw new Error(`COPY retry skipped rows or could not verify a complete node load ` +
+                        `(copied ${copiedRows ?? 'unknown'} of ${expectedRows}; ${warnings.length} retained warning(s))`);
+                }
+            };
+            await (isSharedSingletonConn(targetConn) ? withConnLock(retry) : retry());
         }
         catch (retryErr) {
-            onError(retryErr);
+            const firstMessage = firstError instanceof Error ? firstError.message : String(firstError);
+            const retryMessage = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            onError(new Error(`COPY retry failed: ${retryMessage}; first failure: ${firstMessage}`, {
+                cause: retryErr,
+            }));
         }
     }
 };
@@ -992,7 +1028,7 @@ const copyNodeCSVs = async (targetConn, nodeFileEntries, log, totalSteps) => {
             // sizing was calibrated for — name the knob and the mechanism.
             const remedy = bufferPoolExhaustionRemedy(retryMsg);
             throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}${remedy ? ` ${remedy}` : ''}`);
-        });
+        }, rows);
     }
 };
 /**

package/dist/core/run-analyze.js

@@ -24,6 +24,7 @@ import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { logUnresolvedReceiverFiles, summarizeUnresolvedReceivers, } from './ingestion/scope-resolution/unresolved-receivers.js';
 import { summarizeUndecidedSatisfaction } from './ingestion/scope-resolution/undecided-satisfaction.js';
 import { summarizeScopeExtractionFailures } from './ingestion/scope-resolution/scope-extraction-failures.js';
+import { reconcileGraphNodeIdentities } from './incremental/write-reconciliation.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFiles, nodeTablesWithRowsForFiles, snapshotDerivedRelsForFiles, restoreDerivedRels, ensureEmbeddingRowDmlSafe, ensureFtsRowDmlSafe, readIndexCatalogSnapshot, INDEX_CATALOG_UNREADABLE, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, deleteAllAdvisedBy, deleteAllDestinations, deleteSpringAopEvidenceNodes, deleteSpringAutoConfigurationDeclarations, deleteSpringAutoConfigurationSyntheticClasses, queryImportersBatch, loadFTSExtension, wipeLbugDbFiles, LbugWipeError, DELETE_FILES_CHUNK_SIZE, } from './lbug/lbug-adapter.js';
 import { estimateBufferPool, setBufferPoolSizeHint, resolveNativeSafeStorageDir, } from './lbug/lbug-config.js';
@@ -36,7 +37,7 @@ import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSea
 import { getExtensionCapability, getExtensionCapabilities, getFtsCapability, resolveAnalyzeInstallPolicy, } from './lbug/extension-loader.js';
 import { diagnoseExtensionLoad, extractExtensionPath, usesClassifiedLoadRemedy, } from './lbug/extension-load-error.js';
 import { resolveFtsVersionPair } from './lbug/vendored-extension-path.js';
-import { startWalCheckpointDriver, checkpointOnce, } from './lbug/wal-checkpoint-driver.js';
+import { startWalCheckpointDriver, checkpointOnce, isManualCheckpointEnabled, } from './lbug/wal-checkpoint-driver.js';
 import { ftsCrashParkFailureMessage, quarantineSidecarsForDirtyRecovery, inspectLbugSidecars, } from './lbug/sidecar-recovery.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, setShareOptOut, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, ensureStoragePathWritable, isMissingFilesystemError, INDEX_METADATA_FILE, CONTENT_RETENTION_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { ANALYZE_FORCE_STORAGE_REQUIREMENTS, ANALYZE_STORAGE_REQUIREMENTS, defaultStoragePath, requireRegisteredStoragePath, requireStoragePath, resolveStoragePath, } from '../storage/storage-resolver.js';
@@ -2046,7 +2047,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
     // (Bugbot review on PR #1479: a prediction that flipped post-pipeline
     // could skip the embedding cache load and then take the full-rebuild
     // path, silently losing embeddings).
-    const isIncremental = !options.force &&
+    const incrementalEligible = !options.force &&
         !!existingMeta &&
         // Belt and braces, not a second gate: the guard above already set `force`
         // on exactly this condition, and `!options.force` short-circuits before
@@ -2057,6 +2058,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         Object.keys(existingMeta.fileHashes).length > 0 &&
         repoHasGit &&
         allFilePaths.length > 0;
+    // Select a full build before any selective mutation when the operator has
+    // disabled the checkpoint needed to certify an incremental publication.
+    const isIncremental = incrementalEligible && isManualCheckpointEnabled();
+    if (incrementalEligible && !isIncremental) {
+        log('Manual WAL checkpoints are disabled; switching to a full DB write before mutation.');
+    }
     const hashDiff = isIncremental
         ? diffFileHashes(newFileHashes, existingMeta.fileHashes)
         : undefined;
@@ -2287,6 +2294,25 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         // collapse check compares the whole in-memory graph against the whole DB,
         // which is only a like-for-like comparison on a full rebuild.
         let wroteChangedSubgraphOnly = false;
+        const markIncrementalGraphVerification = async () => {
+            if (buildPath !== lbugPath)
+                return;
+            const latest = await loadMeta(metaDir);
+            if (!latest?.incrementalInProgress) {
+                throw new Error('Cannot certify incremental graph without its dirty metadata marker.');
+            }
+            // A failed or aborted identity scan is a graph failure. FTS-only repair
+            // and FTS crash recovery must not clear it while retaining these rows.
+            await saveMeta(metaDir, {
+                ...latest,
+                incrementalInProgress: {
+                    ...latest.incrementalInProgress,
+                    phase: 'graph-reconciliation',
+                    updatedAt: Date.now(),
+                    checkpointSucceeded: false,
+                },
+            });
+        };
         let incrementalFtsRebuildTables;
         if (isIncremental && hashDiff) {
             // ── Incremental DB writeback ───────────────────────────────────
@@ -2335,6 +2361,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             // strict-equality consumer of the diagnostics shape.
             let droppedImporterChunks = 0;
             const saveIncrementalDirtyState = async (phase, extra = {}) => {
+                // Do not stamp live metadata while writing a staging database.
+                if (buildPath !== lbugPath)
+                    return;
                 await saveMeta(metaDir, {
                     ...existingMeta,
                     incrementalInProgress: {
@@ -2995,6 +3024,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             log(`Boundary WAL checkpoint failed on the in-place FTS path (best-effort): ${detail}. ` +
                 'Continuing; recovery will treat the graph-boundary checkpoint as unsuccessful.');
         }
+        if (wroteChangedSubgraphOnly) {
+            await markIncrementalGraphVerification();
+            await reconcileGraphNodeIdentities(pipelineResult.graph, executeQuery, 'post-COPY/checkpoint');
+        }
         if (shouldStampFtsDirtyPhase(ftsWritePlan)) {
             // Lift the prior-meta precondition: a first-ever in-place run (Windows
             // full rebuild, or any in-place incremental) must stamp too. Staging
@@ -3083,6 +3116,8 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
                     : undefined,
             });
+            if (wroteChangedSubgraphOnly)
+                await markIncrementalGraphVerification();
             if (ftsResult.ok) {
                 progress('fts', 90, 'Search indexes ready');
             }
@@ -3127,6 +3162,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 : FTS_UNAVAILABLE_MESSAGE);
             progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
         }
+        if (wroteChangedSubgraphOnly) {
+            // FTS has returned. Later embedding/finalization failures must require
+            // graph recovery, since post-FTS node identities are not yet certified.
+            await markIncrementalGraphVerification();
+        }
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         // Runs on BOTH the full-rebuild path and the incremental path:
         //   - Full rebuild / escalated write: DB was wiped, every cached row
@@ -3909,6 +3949,78 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         // object is fully computed at this point; only its write is deferred.
         // Parse-cache publish waits until after that swap + saveMeta so a failed
         // registerRepo / close / swap cannot replace live shards (#3153).
+        if (wroteChangedSubgraphOnly) {
+            // Registry freshness must not advance either. Include FTS, embedding
+            // restoration and the final WAL drain in the certified boundary.
+            await markIncrementalGraphVerification();
+            await walCheckpointDriver.stop();
+            if (!(await checkpointOnce())) {
+                throw new Error('Graph identity reconciliation failed: final checkpoint could not be verified; run `gitnexus analyze --force`.');
+            }
+            await reconcileGraphNodeIdentities(pipelineResult.graph, executeQuery, 'pre-publish/checkpoint');
+        }
+        // Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
+        await ensureGitNexusIgnored(repoPath, storagePath);
+        // ── Close LadybugDB ──────────────────────────────────────────────
+        // Stop the manual checkpoint driver before closeLbug so its
+        // in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
+        await walCheckpointDriver.stop();
+        // CLI callers (about to process.exit) skip the native close to dodge a
+        // LadybugDB destructor double-free after --pdg writes — closeLbugBeforeExit
+        // CHECKPOINTs for durability then leaves the handles for process exit to
+        // reclaim (#2264). Long-lived callers close for real.
+        //
+        // On Windows a swap must release the build handle before the rename (a
+        // same-process open file can't be renamed), so it forces a real close —
+        // safe because windowsSwapOk excludes --pdg (the #2264 case). POSIX renames
+        // an open file, so it keeps the skip-native-close there.
+        const forceRealCloseForSwap = useAtomicSwap && process.platform === 'win32';
+        await (options.skipNativeCloseOnExit && !forceRealCloseForSwap
+            ? closeLbugBeforeExit()
+            : closeLbug());
+        // #2 atomic publish: the fresh index was built at buildPath (a full rebuild,
+        // or an opt-in atomic incremental that copied the live index in first). Swap
+        // it over the live lbugPath in one rename so an MCP reader that opened
+        // mid-build only ever saw the previous complete index — never a wiped/
+        // half-built file. The close above checkpoint-consolidated buildPath to a
+        // single file (no .wal), so the rename publishes a complete index; a reader
+        // holding the old inode keeps a consistent stale snapshot until the pool
+        // re-opens onto the new one (the pool staleness invalidation). Runs only on
+        // success — a thrown error skips this, leaving the live index intact and the
+        // temp build to be cleared by the next run's wipe.
+        // Only publish if the build actually produced a DB at buildPath. A
+        // degenerate run (empty repo, or a mocked pipeline that never opened the
+        // store) leaves nothing to swap — skip rather than throw ENOENT.
+        const builtDbExists = useAtomicSwap
+            ? await fs.stat(buildPath).then(() => true, () => false)
+            : false;
+        if (useAtomicSwap && builtDbExists) {
+            await retryRename(buildPath, lbugPath);
+            liveIndexMutationStarted = true;
+            // Clear any sidecars orphaned beside the replaced file. A cleanly-closed
+            // prior index has none; a crashed one could, and it would be replay
+            // poison next to the freshly published index. Best-effort.
+            for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
+                await fs.rm(`${lbugPath}${suffix}`, { force: true }).catch(() => { });
+            }
+            // #2614 F4: if the final checkpoint silently failed, the build may still
+            // carry a residual .wal/.shadow under the temp name. MOVE it beside the
+            // published index (not orphan/delete it) so the next open replays the
+            // delta, rather than leaving it under a name LadybugDB never reconciles.
+            for (const suffix of ['.wal', '.shadow']) {
+                await fs.rename(`${buildPath}${suffix}`, `${lbugPath}${suffix}`).catch(() => { });
+            }
+        }
+        // #2614 F1: stamp the freshness metadata now that the index is published.
+        // When meta.indexedAt becomes visible, lbugPath already resolves to the new
+        // inode, so a reader reiniting on the stamp opens the fresh graph rather
+        // than latching on the old one. Leaving the dirty flag set across the swap
+        // is a crash-safety improvement: a failed swap leaves the previous index
+        // live and the next run recovers via the full-rebuild path.
+        await saveMeta(metaDir, meta);
+        // Registry freshness is published only after the graph and its metadata.
+        // A failed close, swap, or metadata save must leave the previous registry
+        // receipt intact, just as it leaves the cache unpublished.
         // Forward the --name alias and the registry-collision bypass bit.
         // `allowDuplicateName` is its own concern — independent from the
         // pipeline `force` above. The CLI maps it from
@@ -3946,8 +4058,6 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 log(`Warning: could not sync the workspace branch label (${e.message}); continuing.`);
             }
         }
-        // Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
-        await ensureGitNexusIgnored(repoPath, storagePath);
         // ── Generate AI context files (best-effort) ───────────────────────
         let aggregatedClusterCount = 0;
         if (pipelineResult.communityResult?.communities) {
@@ -3984,63 +4094,6 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 // Best-effort — don't fail the entire analysis for context file issues
             }
         }
-        // ── Close LadybugDB ──────────────────────────────────────────────
-        // Stop the manual checkpoint driver before closeLbug so its
-        // in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
-        await walCheckpointDriver.stop();
-        // CLI callers (about to process.exit) skip the native close to dodge a
-        // LadybugDB destructor double-free after --pdg writes — closeLbugBeforeExit
-        // CHECKPOINTs for durability then leaves the handles for process exit to
-        // reclaim (#2264). Long-lived callers close for real.
-        //
-        // On Windows a swap must release the build handle before the rename (a
-        // same-process open file can't be renamed), so it forces a real close —
-        // safe because windowsSwapOk excludes --pdg (the #2264 case). POSIX renames
-        // an open file, so it keeps the skip-native-close there.
-        const forceRealCloseForSwap = useAtomicSwap && process.platform === 'win32';
-        await (options.skipNativeCloseOnExit && !forceRealCloseForSwap
-            ? closeLbugBeforeExit()
-            : closeLbug());
-        // #2 atomic publish: the fresh index was built at buildPath (a full rebuild,
-        // or an opt-in atomic incremental that copied the live index in first). Swap
-        // it over the live lbugPath in one rename so an MCP reader that opened
-        // mid-build only ever saw the previous complete index — never a wiped/
-        // half-built file. The close above checkpoint-consolidated buildPath to a
-        // single file (no .wal), so the rename publishes a complete index; a reader
-        // holding the old inode keeps a consistent stale snapshot until the pool
-        // re-opens onto the new one (the pool staleness invalidation). Runs only on
-        // success — a thrown error skips this, leaving the live index intact and the
-        // temp build to be cleared by the next run's wipe.
-        // Only publish if the build actually produced a DB at buildPath. A
-        // degenerate run (empty repo, or a mocked pipeline that never opened the
-        // store) leaves nothing to swap — skip rather than throw ENOENT.
-        const builtDbExists = useAtomicSwap
-            ? await fs.stat(buildPath).then(() => true, () => false)
-            : false;
-        if (useAtomicSwap && builtDbExists) {
-            await retryRename(buildPath, lbugPath);
-            liveIndexMutationStarted = true;
-            // Clear any sidecars orphaned beside the replaced file. A cleanly-closed
-            // prior index has none; a crashed one could, and it would be replay
-            // poison next to the freshly published index. Best-effort.
-            for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
-                await fs.rm(`${lbugPath}${suffix}`, { force: true }).catch(() => { });
-            }
-            // #2614 F4: if the final checkpoint silently failed, the build may still
-            // carry a residual .wal/.shadow under the temp name. MOVE it beside the
-            // published index (not orphan/delete it) so the next open replays the
-            // delta, rather than leaving it under a name LadybugDB never reconciles.
-            for (const suffix of ['.wal', '.shadow']) {
-                await fs.rename(`${buildPath}${suffix}`, `${lbugPath}${suffix}`).catch(() => { });
-            }
-        }
-        // #2614 F1: stamp the freshness metadata now that the index is published.
-        // When meta.indexedAt becomes visible, lbugPath already resolves to the new
-        // inode, so a reader reiniting on the stamp opens the fresh graph rather
-        // than latching on the old one. Leaving the dirty flag set across the swap
-        // is a crash-safety improvement: a failed swap leaves the previous index
-        // live and the next run recovers via the full-rebuild path.
-        await saveMeta(metaDir, meta);
         // Persist the incremental parse cache only after a successful graph
         // publish (#3153). try/catch so a cache-write failure never breaks an
         // otherwise successful indexing run. Prune stale chunk-hash entries first

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

@@ -9,7 +9,7 @@ import { resolveGraphPath } from '../../storage/shared-store.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { createHash } from 'crypto';
-import { scoreImpactRisk, unusedAxesForImpactWalk } from '../../_shared/index.js';
+import { scoreImpactRisk, unusedAxesForImpactWalk, getLanguageFromFilename, } from '../../_shared/index.js';
 import { initLbug, executeQuery, executeParameterized, ensureVectorExtension, closeLbug, isLbugReady, statDbIdentity, dbIdentityChanged, } from '../../core/lbug/pool-adapter.js';
 import { queryClassBeanMetadata } from './bean-metadata.js';
 import { querySpringAopMetadata } from './aop-metadata.js';
@@ -20,8 +20,10 @@ import { shapeQueryProcessAttaches } from './query-process-attaches.js';
 import { LBUG_ID_PROBE_BATCH_SIZE, LBUG_QUERY_BATCH_SIZE } from '../../core/lbug/query-batch.js';
 import { chunk, mapConcurrent } from '../../lib/utils.js';
 import { pathSuffixOf } from './path-predicate.js';
+import { isCobolFile, isJclFile } from '../../core/ingestion/cobol/file-types.js';
 import { toOneBasedLine } from '../../core/ingestion/utils/line-base.js';
 import { isTestFilePath } from '../../core/ingestion/utils/test-file-path.js';
+import { isTemplateRouteCandidate } from '../../core/ingestion/utils/template-file.js';
 import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -188,6 +190,22 @@ function resolveAliasString(canonical, legacy) {
 function nonBlankUid(value) {
     return typeof value === 'string' ? value.trim() || undefined : undefined;
 }
+const SYMBOL_IDENTITY_RECOVERY_SUGGESTION = 'Run gitnexus analyze --force from the affected repository root to rebuild the index.';
+class SymbolIdentityError extends Error {
+    constructor() {
+        super('The index returned an invalid symbol identity. ' + SYMBOL_IDENTITY_RECOVERY_SUGGESTION);
+        this.name = 'SymbolIdentityError';
+    }
+}
+/** Validate database identities before using them as graph traversal anchors. */
+function assertSymbolIdentity(id, expectedUid) {
+    if (typeof id !== 'string' ||
+        !id.trim() ||
+        id.includes('\0') ||
+        (expectedUid !== undefined && id !== expectedUid)) {
+        throw new SymbolIdentityError();
+    }
+}
 const TOOL_STRING_ALIASES = {
     impact: [{ canonical: 'target', aliases: ['name', 'symbol'] }],
     context: [{ canonical: 'file_path', aliases: ['file'] }],
@@ -3560,6 +3578,7 @@ export class LocalBackend {
                 endLine: (r.endLine ?? r[5]),
                 ...(include_content ? { content: (r.content ?? r[6]) } : {}),
             };
+            assertSymbolIdentity(symbol.id, uid);
             // Same LadybugDB label-enrichment as the name-based path: a UID
             // pointing at a Class must still surface `type: 'Class'` so impact's
             // Class/Interface BFS seed fires. No-op when type is already set.
@@ -3681,6 +3700,10 @@ export class LocalBackend {
             endLine: (r.endLine ?? r[5]),
             ...(include_content ? { content: (r.content ?? r[6]) } : {}),
         }));
+        // Reject the whole result before narrowing or scoring: dropping a corrupt
+        // candidate could make an unrelated surviving symbol look unambiguous.
+        for (const candidate of normalized)
+            assertSymbolIdentity(candidate.id);
         // An exact File path wins over anchored suffix candidates. Without this,
         // `lib/a.ts` and `src/lib/a.ts` both score as File candidates and turn an
         // otherwise unambiguous exact target into `ambiguous` (#3084 review P2).
@@ -3810,6 +3833,9 @@ export class LocalBackend {
         }
         catch (err) {
             const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
+            if (err instanceof SymbolIdentityError) {
+                return { error: msg, recoverySuggestion: SYMBOL_IDENTITY_RECOVERY_SUGGESTION };
+            }
             if (isWalCorruptionError(err)) {
                 return {
                     error: msg,
@@ -5193,6 +5219,7 @@ export class LocalBackend {
         // throwaway arrays the size of the row set (40k rows 11.4ms → 4.5ms, 200k
         // rows 71.3ms → 26.6ms).
         const exactlyMatchedPaths = new Set();
+        const mappedPaths = new Set();
         for (const row of symbolRows) {
             if (row.filePath === row.diffPath)
                 exactlyMatchedPaths.add(row.diffPath);
@@ -5204,6 +5231,9 @@ export class LocalBackend {
             const hunks = hunksByPath.get(diffPath) ?? [];
             if (!hunksOverlapRange(hunks, sym.startLine, sym.endLine))
                 continue;
+            // A suffix fallback is a hint, not proof that this is the changed file.
+            if (sym.filePath === diffPath)
+                mappedPaths.add(diffPath);
             if (changedSymbols.has(sym.id))
                 continue;
             changedSymbols.set(sym.id, {
@@ -5214,6 +5244,21 @@ export class LocalBackend {
                 change_type: 'touched',
             });
         }
+        // An empty successful query cannot prove a source diff is safe: its rows
+        // may be missing, outside indexed spans, or not yet indexed. Keep ordinary
+        // docs/config diffs measurable, but withhold a ranked source-risk verdict.
+        const isSourceFile = (file) => getLanguageFromFilename(file) !== null ||
+            isCobolFile(file) ||
+            isJclFile(file) ||
+            isTemplateRouteCandidate(file);
+        const unmappedFiles = [
+            ...new Set(fileDiffs
+                .filter(({ filePath, oldFilePath }) => !mappedPaths.has(filePath) &&
+                (isSourceFile(filePath) || (oldFilePath !== undefined && isSourceFile(oldFilePath))))
+                .map(({ filePath }) => filePath)),
+        ];
+        if (unmappedFiles.length > 0)
+            queryDegraded = true;
         // Find affected processes -- batched queries instead of N+1
         const affectedProcesses = new Map();
         if (changedSymbols.size > 0) {
@@ -5305,8 +5350,9 @@ export class LocalBackend {
             },
             changed_symbols: listedSymbols,
             affected_processes: Array.from(affectedProcesses.values()),
-            // A swallowed query failure makes the counts/risk above incomplete — tell
-            // the caller so the safety gate isn't trusted as a clean result (#2283).
+            ...(unmappedFiles.length > 0 && { unmapped_files: unmappedFiles }),
+            // Failed queries or unmapped source files leave counts/risk incomplete;
+            // the safety gate must not treat that as a clean result (#2283).
             ...(queryDegraded && { partial: true }),
             ...(listedSymbols.length < changedSymbols.size && { truncated: true }),
         };
@@ -5727,8 +5773,14 @@ export class LocalBackend {
         catch (err) {
             // Return structured error instead of crashing (#321)
             const message = (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed';
-            const suggestion = 'The graph query failed — try gitnexus context <symbol> as a fallback';
-            const recoverySuggestion = isWalCorruptionError(err) ? WAL_RECOVERY_SUGGESTION : undefined;
+            const recoverySuggestion = err instanceof SymbolIdentityError
+                ? SYMBOL_IDENTITY_RECOVERY_SUGGESTION
+                : isWalCorruptionError(err)
+                    ? WAL_RECOVERY_SUGGESTION
+                    : undefined;
+            const suggestion = err instanceof SymbolIdentityError
+                ? SYMBOL_IDENTITY_RECOVERY_SUGGESTION
+                : 'The graph query failed — try gitnexus context <symbol> as a fallback';
             if (params.mode === 'pdg') {
                 // Symbol resolution never reached the catch with a resolved symbol (the
                 // throw can originate before/within resolution), so the envelope carries
@@ -7474,6 +7526,7 @@ export class LocalBackend {
                 'METHOD_IMPLEMENTS',
             ];
         try {
+            assertSymbolIdentity(sym.id ?? sym[0], uid);
             // skipPerSymbolEnrichment suppresses ONLY the per-symbol STEP_IN_PROCESS
             // enrichment pass while preserving byDepth. Group-mode cross-repo fan-out
             // may fan across many repos; the per-symbol pass adds up to MAX_CHUNKS

package/dist/mcp/tools.js

@@ -349,7 +349,7 @@ AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ
 GIT WORKTREE SUPPORT: GitNexus automatically detects when the MCP server was launched from inside a linked git worktree and runs git diff against that worktree — no extra parameters needed in the common case. Pass "worktree" explicitly only when the server was started from a different directory than the worktree you are editing (e.g., the server runs from the canonical root but your changes are in a linked worktree at a different path).
 
 Returns: changed symbols, affected processes, and a risk summary.
-- partial: true — a step failed and was swallowed, so the result is incomplete and risk_level is "unknown" instead of a ranked level. Two causes, with different blast radii: the symbol query (or an unparseable diff) degrades everything — changed_symbols, both counts, and the processes derived from them — while a failed process lookup degrades only affected_processes and the risk read off it, leaving the changed-symbol counts sound. changed_count:0 with partial:true is NOT a clean pre-commit check; re-run before treating the diff as safe.
+- partial: true — mapping is incomplete, so risk_level is "unknown" instead of a ranked level. A failed symbol query (or an unparseable diff) degrades changed_symbols, both counts, and derived processes; a failed process lookup degrades only affected_processes and risk, leaving changed-symbol counts sound. unmapped_files lists changed supported source files with no mapped symbols, including source renames without hunks: their symbols may be missing, unindexed, or outside indexed ranges even when every query succeeded. Rebuild the index and inspect those diffs; retry alone may not resolve this state. changed_count:0 with partial:true is NOT a clean pre-commit check.
 - truncated: true — the changed_symbols LISTING was capped for this response. summary.changed_count counts every symbol the run observed: the true total normally, a LOWER BOUND when partial:true. Compare it with the array length rather than trusting the array.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {

package/dist/server/api.js

@@ -424,7 +424,7 @@ const mapGraphRelationshipRow = (row) => ({
     sourceId: row.sourceId,
     targetId: row.targetId,
     confidence: row.confidence,
-    reason: row.reason,
+    reason: row.reason ?? '',
     step: row.step,
 });
 export const streamGraphNdjson = async (res, includeContent = false, signal) => {

package/dist/storage/git.d.ts

@@ -285,6 +285,8 @@ export interface DiffHunk {
 }
 export interface FileDiff {
     filePath: string;
+    /** Decoded pre-rename path; either side can identify a source-file change. */
+    oldFilePath?: string;
     hunks: DiffHunk[];
 }
 /** `parseDiffHunks` plus how many `diff --git` headers could not be decoded. */

package/dist/storage/git.js

@@ -1005,7 +1005,12 @@ export function parseDiffHunksResult(diffOutput) {
                 unparsedGitHeaders++;
             }
         }
-        else if (line.startsWith('rename to ')) {
+        else if (!inHunk && line.startsWith('rename from ')) {
+            const oldFilePath = decodeGitPathToken(line.slice('rename from '.length));
+            if (current && oldFilePath)
+                current.oldFilePath = oldFilePath;
+        }
+        else if (!inHunk && line.startsWith('rename to ')) {
             const filePath = pathFromRenameTo(line);
             if (!filePath)
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.62",
+  "version": "1.6.13-rc.64",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -65,7 +65,7 @@
     "version": "node scripts/sync-plugin-manifests.mjs"
   },
   "dependencies": {
-    "@ladybugdb/core": "0.18.3",
+    "@ladybugdb/core": "0.21.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "busboy": "^1.6.0",

package/vendor/lbug-fts/manifest.json

@@ -1,6 +1,6 @@
 {
-  "coreVersion": "0.18.3",
-  "extensionVersion": "0.18.1",
+  "coreVersion": "0.21.1",
+  "extensionVersion": "0.21.0",
   "filename": "libfts.lbug_extension",
   "officialRepo": "https://extension.ladybugdb.com/",
   "urlTemplate": "{officialRepo}v{extensionVersion}/{upstreamPlatform}/fts/{filename}",

package/vendor/lbug-fts/prebuilds/SHA256SUMS

@@ -1,5 +1,5 @@
-01cf0d4debae1b0c7c182bf78747ee1b148a76667bbaa5bb0cb3cc848998028d  ./win32-x64/libfts.lbug_extension
-4af2602007a4a02d5b18d0b6ecb20b1cc2f493242a915faf7df1c033136107b1  ./linux-arm64/libfts.lbug_extension
-cf687fda0f82bfbe116e775f2f17c39faf45be6300fd1937c2b1afd21142c121  ./linux-x64/libfts.lbug_extension
-d3564c05ec28a0293a5488eaff2c06591624ac01a44af183d8cfacd92a29d785  ./darwin-arm64/libfts.lbug_extension
-d8589c0a91c6667e959da6a81f712f69b330d0563602933da983edeebee60fc6  ./darwin-x64/libfts.lbug_extension
+248332de781a7781f612a55b5397e88f58f1f1ba2a973836ada199eab0f6bf10  ./darwin-arm64/libfts.lbug_extension
+742f2756c2f80bcd1886b6ee0446483038cff0ecf6cf47f698bc6fe855cbaef6  ./linux-x64/libfts.lbug_extension
+7b6132ae6a554e3eeb3c4b0da7e2eb5c483b258b31e848a0e3d6000ac29885ee  ./win32-x64/libfts.lbug_extension
+b8675b086664e3d6742330a517c5b619f0ac10dd094d250f12bef9822a8d5750  ./linux-arm64/libfts.lbug_extension
+c86f427503555a3ccdc55eb66a8d82793a206aac599a6092f7d1d4eb50c21403  ./darwin-x64/libfts.lbug_extension