gitnexus 1.6.8-rc.8 → 1.6.8

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

@@ -27,7 +27,41 @@ import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
-import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from '../tools.js';
+import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
+import { findImportCycles } from '../../core/graph/import-cycles.js';
+import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
+import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
+import { EXTENSIONS } from '../../core/ingestion/import-resolvers/utils.js';
+import { fnLineOf, isPdgDegradedLayerStatus, makePdgImpactErrorResult, makePdgLayerDegradedResult, pdgLayerStatus, pdgStampForMode, runImpactPDG, validateImpactMode, pdgBridgeEvidenceForImpact, betterBridgeEvidence, composeUnifiedPdgImpactResult, splitCalleeIds, } from './pdg-impact.js';
+/** Real source-file extensions (`.ts`, `.py`, …) from the resolver's list,
+ *  excluding the empty entry and the `/index.*` forms — used to decide whether
+ *  an `explain` target is a file path vs a (possibly dotted) symbol name. */
+const SOURCE_FILE_EXTENSIONS = EXTENSIONS.filter((e) => e.startsWith('.') && !e.includes('/'));
+/** A target is path-ish if it has a path separator or ends in a known source
+ *  extension. A bare dotted symbol (`UserController.create`) is NOT path-ish. */
+function looksLikeFilePath(target) {
+    if (/[\\/]/.test(target))
+        return true;
+    const lower = target.toLowerCase();
+    return SOURCE_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Resolve a string tool param from its canonical name or legacy alias (#2175).
+ * Returns the first NON-BLANK string of [canonical, legacy] — the canonical (new)
+ * name is preferred when it carries a real value, otherwise the legacy value is used.
+ * A blank/whitespace new value therefore does NOT clobber a valid legacy value (e.g. a
+ * gradually-migrating client that always emits the new key, blank when unset). A
+ * non-string value (the MCP envelope is not schema-validated, so clients can send any
+ * JSON type) and an all-blank input resolve to `undefined`, so the caller returns a
+ * friendly required-param error instead of throwing `TypeError` on `.trim()`.
+ */
+function resolveAliasString(canonical, legacy) {
+    for (const value of [canonical, legacy]) {
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -1015,6 +1049,15 @@ export class LocalBackend {
             return this.handleGroupTool(method, params || {});
         }
         const p = params && typeof params === 'object' ? params : {};
+        // #2175: Claude Code drops a tool-call argument named exactly "query", so the
+        // query/cypher tools advertise "search_query"/"statement" while still accepting the
+        // legacy "query" key for backward compat. The alias is resolved with `?? ` (new name
+        // wins) at every consumer site rather than by mutating params here, so precedence is
+        // uniform and there is no hidden mutation: query()/cypher() read it directly, the
+        // legacy "search" alias routes through query(), and the cross-repo group-forward
+        // resolves it self-contained in callToolAtGroupRepo. This is permanent compatibility
+        // — third-party MCP clients may legitimately send "query", so the alias is not slated
+        // for removal even if Claude Code's argument handling later changes.
         if ((method === 'impact' || method === 'query' || method === 'context') &&
             typeof p.repo === 'string' &&
             p.repo.startsWith('@')) {
@@ -1033,10 +1076,16 @@ export class LocalBackend {
             }
             case 'context':
                 return this.context(repo, params);
+            case 'explain':
+                return this.explain(repo, params);
+            case 'pdg_query':
+                return this.pdgQuery(repo, params);
             case 'impact':
                 return this.impact(repo, params);
             case 'detect_changes':
                 return this.detectChanges(repo, params);
+            case 'check':
+                return this.check(repo, params);
             case 'rename':
                 return this.rename(repo, params);
             // Legacy aliases for backwards compatibility
@@ -1054,11 +1103,44 @@ export class LocalBackend {
                 return this.toolMap(repo, params);
             case 'api_impact':
                 return this.apiImpact(repo, params);
+            case 'trace':
+                return this.trace(repo, params);
             default:
                 throw new Error(`Unknown tool: ${method}`);
         }
     }
     // ─── Tool Implementations ────────────────────────────────────────
+    /** Check repository graph invariants that are suitable for CI gating. */
+    async check(repo, params) {
+        if (params?.cycles === false) {
+            return { error: 'No checks selected. Set "cycles" to true.' };
+        }
+        await this.ensureInitialized(repo);
+        const rowLimit = 100_001;
+        const rows = await executeParameterized(repo.lbugPath, `MATCH (source:File)-[r:CodeRelation]->(target:File)
+       WHERE r.type = 'IMPORTS'
+         AND (r.reason IS NULL OR (
+           r.reason <> 'swift-scope: implicit module visibility'
+           AND r.reason <> 'markdown-link'
+         ))
+       RETURN source.filePath AS source, target.filePath AS target
+       LIMIT ${rowLimit}`, {});
+        if (rows.length === rowLimit) {
+            return {
+                error: `Import graph exceeds the ${rowLimit - 1} edge safety limit.`,
+                truncated: true,
+            };
+        }
+        const cycles = findImportCycles(rows.map((row) => ({
+            source: String(row.source ?? row[0] ?? ''),
+            target: String(row.target ?? row[1] ?? ''),
+        })));
+        return {
+            status: cycles.length === 0 ? 'clean' : 'cycles_found',
+            cycleCount: cycles.length,
+            cycles: cycles.map((files) => ({ files })),
+        };
+    }
     /**
      * Query tool — process-grouped search.
      *
@@ -1068,14 +1150,18 @@ export class LocalBackend {
      * 4. Return: { processes, process_symbols, definitions }
      */
     async query(repo, params) {
-        if (!params.query?.trim()) {
-            return { error: 'query parameter is required and cannot be empty.' };
+        // #2175: each consumer resolves the search_query/query alias itself (there is no
+        // chokepoint mutation in callTool). This also serves the GroupService port, which
+        // reaches query() carrying only the legacy `query` key.
+        const rawQuery = resolveAliasString(params.search_query, params.query);
+        if (!rawQuery?.trim()) {
+            return { error: 'search_query (or legacy query) parameter is required and cannot be empty.' };
         }
         await this.ensureInitialized(repo);
         const processLimit = params.limit || 5;
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
-        const searchQuery = params.query.trim();
+        const searchQuery = rawQuery.trim();
         // Per-phase timing instrumentation (#553). Records wall time for each
         // observable sub-step of the search pipeline so production latency can
         // be aggregated offline for Pareto analysis and bottleneck detection.
@@ -1389,9 +1475,15 @@ export class LocalBackend {
               WHERE n.id IN $nodeIds
               RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
             `, { nodeIds })
-                    : await executeParameterized(repo.lbugPath, `
+                    : await executeParameterized(repo.lbugPath, 
+                    // Same BasicBlock exclusion as detect_changes (#2082 U7): on a
+                    // --pdg index a function-heavy file has far more BasicBlock rows
+                    // than symbols, so an unfiltered LIMIT 3 would surface nameless
+                    // substrate rows and displace the real symbols.
+                    `
               MATCH (n)
               WHERE n.filePath = $filePath
+                AND NOT n.id STARTS WITH 'BasicBlock:'
               RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
               LIMIT 3
             `, { filePath: fullPath });
@@ -1546,7 +1638,10 @@ export class LocalBackend {
         const repo = await this.resolveRepo(repoName);
         return this.cypher(repo, { query, params });
     }
-    async cypher(repo, request) {
+    async cypher(repo, 
+    // #2175: "statement" is the advertised param; "query" is the legacy alias,
+    // still accepted (and the field the internal executeCypher() passes). New wins.
+    request) {
         await this.ensureInitialized(repo);
         if (!isLbugReady(repo.lbugPath)) {
             return { error: 'LadybugDB not ready. Index may be corrupted.' };
@@ -1556,8 +1651,14 @@ export class LocalBackend {
                 error: '"params" must be a plain object with scalar values (string/number/boolean/null).',
             };
         }
+        const cypherText = resolveAliasString(request.statement, request.query) ?? '';
+        if (!cypherText.trim()) {
+            // Mirror query()'s friendly required-param error instead of letting an empty
+            // string fall through to a raw LadybugDB prepare error (#2175 review).
+            return { error: 'statement (or legacy query) parameter is required and cannot be empty.' };
+        }
         try {
-            const result = await executeParameterized(repo.lbugPath, request.query, request.params ?? {});
+            const result = await executeParameterized(repo.lbugPath, cypherText, request.params ?? {});
             return result;
         }
         catch (err) {
@@ -2207,6 +2308,510 @@ export class LocalBackend {
             })),
         };
     }
+    /**
+     * Resolve a `target` (file path OR symbol/function name) into a BasicBlock
+     * SOURCE-block anchor, shared by `explain` (TAINTED) and `pdg_query`
+     * (CDG/REACHING_DEF) — both reconstruct the symbol↔block join the same way
+     * (there is no Function→BasicBlock edge). #2188 review: extracted from two
+     * near-identical copies that had DRIFTED — `_explainImpl` used a 0-based,
+     * un-widened span window that dropped a function's final-line block and could
+     * leak a neighbor's line-above block; this single resolver applies the correct
+     * `[symStart+1, symEnd+1]` window (1-based BasicBlock startLine vs 0-based
+     * symbol span) to BOTH callers.
+     *
+     * Returns a BARE `anchorClause` (no leading `AND`) so each caller composes its
+     * own `WHERE`; `early` carries the not-found/ambiguous payload (caller returns
+     * it verbatim). `target` / symbol names flow only through `queryParams` bind
+     * params — never interpolated into Cypher.
+     */
+    async resolveBlockAnchor(repo, target, toolName) {
+        if (looksLikeFilePath(target)) {
+            return {
+                anchorClause: '(a.id STARTS WITH $idPrefix OR a.filePath = $targetPath OR a.filePath ENDS WITH $targetSuffix)',
+                queryParams: {
+                    idPrefix: `BasicBlock:${target}:`,
+                    targetPath: target,
+                    targetSuffix: `/${target}`,
+                },
+                anchor: { file: target },
+            };
+        }
+        const outcome = await this.resolveSymbolCandidates(repo, { name: target }, {});
+        if (outcome.kind === 'not_found') {
+            return {
+                anchorClause: '',
+                queryParams: {},
+                anchor: { file: '' },
+                early: { error: `Symbol '${target}' not found` },
+            };
+        }
+        if (outcome.kind === 'ambiguous') {
+            return {
+                anchorClause: '',
+                queryParams: {},
+                anchor: { file: '' },
+                early: {
+                    status: 'ambiguous',
+                    message: `Found ${outcome.candidates.length} symbols matching '${target}'. Re-call ${toolName} with the file path, or disambiguate via context() first.`,
+                    candidates: outcome.candidates.map((c) => ({
+                        uid: c.id,
+                        name: c.name,
+                        kind: c.type,
+                        filePath: c.filePath,
+                        line: c.startLine,
+                        score: Number(c.score.toFixed(2)),
+                    })),
+                },
+            };
+        }
+        const sym = outcome.symbol;
+        const idPrefix = `BasicBlock:${sym.filePath}:`;
+        if (typeof sym.startLine === 'number' &&
+            typeof sym.endLine === 'number' &&
+            sym.endLine >= sym.startLine) {
+            // BasicBlock startLine is 1-based; the symbol span is 0-based. Shift BOTH
+            // bounds +1 so the window is the function's true block span: the lower +1
+            // excludes a neighbor's block on the line directly above, the upper +1
+            // keeps a guard/def/use on the final line (#2188 review).
+            return {
+                anchorClause: 'a.id STARTS WITH $idPrefix AND a.startLine >= $symStart AND a.startLine <= $symEnd',
+                queryParams: { idPrefix, symStart: sym.startLine + 1, symEnd: sym.endLine + 1 },
+                anchor: {
+                    file: sym.filePath,
+                    symbol: sym.name,
+                    startLine: sym.startLine,
+                    endLine: sym.endLine,
+                },
+            };
+        }
+        // No usable span — degrade to the file-level filter (documented).
+        return {
+            anchorClause: 'a.id STARTS WITH $idPrefix',
+            queryParams: { idPrefix },
+            anchor: { file: sym.filePath, symbol: sym.name },
+        };
+    }
+    /**
+     * Explain tool (#2083 M3 U6) — persisted taint-finding explanation.
+     * WAL-aware wrapper mirroring `context`.
+     */
+    async explain(repo, params) {
+        try {
+            return await this._explainImpl(repo, params);
+        }
+        catch (err) {
+            const msg = (err instanceof Error ? err.message : String(err)) || 'Explain query failed';
+            if (isWalCorruptionError(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Taint findings are persisted as `TAINTED` rows in CodeRelation whose
+     * endpoints are BOTH BasicBlock nodes — the label anchor restricts every
+     * query here to the BasicBlock→BasicBlock partition of the rel table
+     * (which holds only the sparse, per-function-capped pdg layers), never a
+     * global symbol-space scan (the S1 verdict; LadybugDB has no rel-property
+     * index, so the label anchor IS the bound).
+     *
+     * Anchoring granularity:
+     * - file target → BasicBlock id prefix (`BasicBlock:<filePath>:` — the
+     *   shared `basicBlockId` template) with an exact-or-suffix path match so
+     *   `vuln.ts` finds `src/vuln.ts`.
+     * - symbol target → resolved via `resolveSymbolCandidates` (the context()
+     *   path: ambiguous ⇒ ranked candidates, unknown ⇒ not-found), then the
+     *   file id-prefix PLUS source-block startLine within the symbol's
+     *   [startLine, endLine] span. Findings are intra-procedural, so filtering
+     *   the SOURCE endpoint is sufficient — both endpoints share the function.
+     *   Symbols without a line span degrade to the file-level filter.
+     *
+     * The per-finding `sinkKind` and hop path decode from the persisted
+     * `reason` via the SHARED `taint/path-codec.ts` (the U4 write path encodes
+     * with the same module — `;<kind>` header + ordered `variable:line` hops).
+     */
+    async _explainImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        const rawLimit = params.limit ?? EXPLAIN_DEFAULT_LIMIT;
+        if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > EXPLAIN_MAX_LIMIT) {
+            return {
+                error: `Invalid "limit": expected an integer in [1, ${EXPLAIN_MAX_LIMIT}], got ${JSON.stringify(params.limit)}.`,
+            };
+        }
+        const limit = rawLimit;
+        const NO_TAINT_NOTE = 'no taint layer — run gitnexus analyze --pdg to record taint findings for this repo';
+        // Cheap meta probe: the TAINT layer exists iff the pdg stamp carries a
+        // `taintModelVersion` (the field M3 added). An M1/M2-era `--pdg` index has
+        // `meta.pdg` defined but no taintModelVersion — BasicBlock/REACHING_DEF
+        // exist, zero TAINTED rows do — so it must surface the no-taint-layer hint,
+        // not the generic "analyzed, nothing found" note. An unreadable meta (e.g.
+        // a seeded test DB) falls through to the row-existence probe below.
+        let pdgStamped;
+        try {
+            const meta = await loadMeta(path.dirname(repo.lbugPath));
+            if (meta)
+                pdgStamped = meta.pdg?.taintModelVersion !== undefined;
+        }
+        catch {
+            /* meta unreadable — decide from the DB below */
+        }
+        if (pdgStamped === false) {
+            return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+        }
+        // Resolve the optional anchor into a WHERE clause on the SOURCE block.
+        const target = typeof params.target === 'string' ? params.target.trim() : '';
+        let anchorClause = '';
+        let queryParams = {};
+        let anchor;
+        // Bounded by construction: the BasicBlock→BasicBlock partition holds only
+        // the sparse pdg layers, TAINTED rows are per-function-capped at analyze
+        // time, and the page is LIMIT-bounded (the limit is a validated integer —
+        // interpolated because LadybugDB does not parameterize LIMIT).
+        const runAnchoredQuery = async () => {
+            const matchClause = `
+      MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock)
+      WHERE r.type = 'TAINTED'${anchorClause ? ` AND ${anchorClause}` : ''}`;
+            const [qRows, countRows] = await Promise.all([
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN a.id AS sourceBlockId, a.filePath AS file, a.startLine AS sourceStart,
+             b.startLine AS sinkStart, r.reason AS reason, b.id AS sinkBlockId
+      ORDER BY sourceBlockId, sinkBlockId, reason
+      LIMIT ${limit}`, queryParams),
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN COUNT(*) AS total`, queryParams),
+            ]);
+            return {
+                rows: qRows,
+                totalFindings: Number(countRows[0]?.total ?? countRows[0]?.[0] ?? 0),
+            };
+        };
+        if (target) {
+            // Shared symbol↔block anchor resolver (#2188): file id-prefix OR symbol
+            // span, with the corrected [symStart+1, symEnd+1] window. A bare/dotted
+            // symbol name resolves as a symbol rather than silently file-anchoring.
+            const resolved = await this.resolveBlockAnchor(repo, target, 'explain');
+            if (resolved.early)
+                return resolved.early;
+            anchorClause = resolved.anchorClause;
+            queryParams = resolved.queryParams;
+            anchor = resolved.anchor;
+        }
+        const { rows, totalFindings } = await runAnchoredQuery();
+        // M4 (#2084 U7): cross-function findings ride TAINT_PATH edges (Function/
+        // Method → Function/Method), separate from the intra-procedural TAINTED
+        // BasicBlock rows above. Enumerate them too so `explain` is the discovery
+        // surface for interprocedural flows (TAINT_PATH stays out of
+        // VALID_RELATION_TYPES + the web schema, like TAINTED). File-anchored:
+        // filter on the source function's file; symbol-anchored: either endpoint
+        // matches the symbol name; anchorless: all (bounded by LIMIT). Computed
+        // BEFORE the no-taint early returns — a repo with ONLY cross-function
+        // findings (no intra-procedural TAINTED rows) must not look empty.
+        const runInterprocQuery = async () => {
+            const where = [`r.type = 'TAINT_PATH'`];
+            const p = {};
+            if (anchor?.symbol) {
+                where.push('(a.name = $ipSym OR b.name = $ipSym)');
+                p.ipSym = anchor.symbol;
+            }
+            else if (anchor?.file) {
+                // Match EITHER endpoint's file — a cross-function flow anchored on the
+                // SINK's file (b) is as relevant as one anchored on the source's (a).
+                where.push('(a.filePath = $ipFile OR a.filePath ENDS WITH $ipSuffix OR ' +
+                    'b.filePath = $ipFile OR b.filePath ENDS WITH $ipSuffix)');
+                p.ipFile = anchor.file;
+                p.ipSuffix = `/${anchor.file}`;
+            }
+            const matchClause = `MATCH (a)-[r:CodeRelation]->(b)\n      WHERE ${where.join(' AND ')}`;
+            // Page query + a separate COUNT (#2084 review P2-4): the page is
+            // LIMIT-capped, so its row count cannot stand in for the true total —
+            // run a COUNT with the same WHERE (no LIMIT) like the intra layer does.
+            const [ipRows, ipCountRows] = await Promise.all([
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN a.filePath AS file, a.name AS sourceFn, a.startLine AS sourceLine,
+             b.name AS sinkFn, b.startLine AS sinkLine, r.reason AS reason
+      ORDER BY sourceFn, sinkFn, reason
+      LIMIT ${limit}`, p),
+                executeParameterized(repo.lbugPath, `${matchClause}\n      RETURN COUNT(*) AS total`, p),
+            ]);
+            const total = Number(ipCountRows[0]?.total ?? ipCountRows[0]?.[0] ?? 0);
+            const findings = ipRows.map((r) => {
+                const decoded = decodeTaintPath(r.reason ?? r[5]);
+                const hops = decoded.ok
+                    ? decoded.hops.map((h) => ({ function: h.variable, line: h.line }))
+                    : [];
+                return {
+                    interprocedural: true,
+                    file: String(r.file ?? r[0] ?? ''),
+                    sinkKind: decoded.ok ? (decoded.kind ?? 'unknown') : 'unknown',
+                    source: { function: String(r.sourceFn ?? r[1] ?? ''), line: r.sourceLine ?? r[2] },
+                    sink: { function: String(r.sinkFn ?? r[3] ?? ''), line: r.sinkLine ?? r[4] },
+                    hops,
+                    ...(decoded.ok && decoded.truncated ? { pathIncomplete: true } : {}),
+                };
+            });
+            return { findings, total };
+        };
+        const { findings: interprocFindings, total: interprocTotal } = await runInterprocQuery();
+        if (totalFindings === 0 &&
+            interprocFindings.length === 0 &&
+            pdgStamped === undefined &&
+            !target) {
+            // Meta was unreadable and the repo-wide enumerate (both layers) found
+            // nothing — the counts above WERE the existence probe; surface the hint.
+            return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+        }
+        if (totalFindings === 0 &&
+            interprocFindings.length === 0 &&
+            pdgStamped === undefined &&
+            target) {
+            // Anchored miss with unreadable meta: one extra bounded probe decides
+            // "no findings for this anchor" vs "no taint layer at all". Probe BOTH
+            // intra (TAINTED) and inter (TAINT_PATH) existence.
+            const probe = await executeParameterized(repo.lbugPath, `MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock) WHERE r.type = 'TAINTED' RETURN r.reason AS reason LIMIT 1`, {});
+            const ipProbe = probe.length === 0
+                ? await executeParameterized(repo.lbugPath, `MATCH (a)-[r:CodeRelation]->(b) WHERE r.type = 'TAINT_PATH' RETURN r.reason AS reason LIMIT 1`, {})
+                : [];
+            if (probe.length === 0 && ipProbe.length === 0) {
+                return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+            }
+        }
+        const findings = rows.map((r) => {
+            const sourceBlockId = String(r.sourceBlockId ?? r[0] ?? '');
+            const file = String(r.file ?? r[1] ?? '');
+            const sourceStart = (r.sourceStart ?? r[2]);
+            const sinkStart = (r.sinkStart ?? r[3]);
+            const reason = r.reason ?? r[4];
+            // basicBlockId = `BasicBlock:<filePath>:<fnLine>:<fnCol>:<blockIdx>` —
+            // split from the RIGHT (the filePath may itself contain ':').
+            const idParts = sourceBlockId.split(':');
+            const fnLine = Number(idParts[idParts.length - 3]);
+            const decoded = decodeTaintPath(reason);
+            if (!decoded.ok) {
+                // Unreadable reason (foreign/corrupt row): surface the finding's
+                // existence with its block anchors, never throw.
+                return {
+                    file,
+                    ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                    sinkKind: 'unknown',
+                    source: { line: sourceStart },
+                    sink: { line: sinkStart },
+                    hops: [],
+                    pathIncomplete: true,
+                };
+            }
+            const hops = decoded.hops.map((h) => ({
+                variable: h.variable,
+                line: h.line,
+                ...(h.viaCall ? { viaCall: true } : {}),
+            }));
+            const first = hops[0];
+            const last = hops[hops.length - 1];
+            return {
+                file,
+                ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                sinkKind: decoded.kind ?? 'unknown',
+                source: first ? { variable: first.variable, line: first.line } : { line: sourceStart },
+                sink: { line: last?.line ?? sinkStart },
+                hops,
+                ...(decoded.truncated ? { pathIncomplete: true } : {}),
+            };
+        });
+        // Combine both layers and re-apply the page LIMIT to the union — each
+        // layer was queried with its own LIMIT, so the union can hold up to 2×;
+        // cap it so `findings.length` honours the caller's `limit`. `truncated`
+        // reflects EITHER layer overflowing OR the union being trimmed here, and
+        // `totalFindings` counts both layers' matched rows (the intra COUNT plus
+        // the interproc rows returned — interproc has no separate COUNT, so a
+        // capped interproc layer is reflected via `truncated`, never undercounted
+        // into a false "complete" signal). Review: code-review #2/#4 (explain
+        // accounting + sink-file anchoring) — both layers now accounted.
+        const combined = [...findings, ...interprocFindings];
+        const pageFindings = combined.length > limit ? combined.slice(0, limit) : combined;
+        // Truncated iff EITHER layer overflowed its own LIMIT (strict `>` — exactly
+        // `limit` rows is not truncated), OR the combined union was trimmed to the
+        // page (#2084 review P2-4). `totalFindings` uses the interproc COUNT, not
+        // the capped slice length, so it never undercounts.
+        const truncated = totalFindings > findings.length ||
+            interprocTotal > interprocFindings.length ||
+            combined.length > pageFindings.length;
+        return {
+            ...(anchor ? { anchor } : {}),
+            findings: pageFindings,
+            totalFindings: totalFindings + interprocTotal,
+            ...(truncated ? { truncated: true } : {}),
+            note: 'Intra-procedural (TAINTED, statement hops) AND cross-function (TAINT_PATH, function hops, `interprocedural: true`) flows are modeled. Closure/callback, property/field, and implicit flows are NOT modeled; absence of a finding is not proof of safety. Cross-function findings are context-insensitive and may over-attribute among same-named callees. SANITIZES (kill) edges are queryable via cypher.',
+        };
+    }
+    async pdgQuery(repo, params) {
+        try {
+            return await this._pdgQueryImpl(repo, params);
+        }
+        catch (err) {
+            const msg = (err instanceof Error ? err.message : String(err)) || 'pdg_query failed';
+            if (isWalCorruptionError(err)) {
+                return { error: msg, recoverySuggestion: WAL_RECOVERY_SUGGESTION };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Query the persisted PDG (#2086 M6) — the control/data-dependence analog of
+     * `explain`. `controls` reads CDG ("under what condition does X run?", branch
+     * sense 'T'|'F' in `reason`); `flows` reads REACHING_DEF (def→use, variable
+     * name in `reason`). Intra-procedural, basic-block granular.
+     *
+     * Bounded by construction: the BasicBlock→BasicBlock partition holds only the
+     * sparse, per-function-capped pdg layers, the query is anchored to one file/
+     * symbol, and the page is LIMIT-bounded (validated integer, interpolated
+     * because LadybugDB does not parameterize LIMIT). LadybugDB has no rel-
+     * property index, so the anchor IS the bound — there is no anchorless mode.
+     *
+     * Symbol↔block join: there is no Function→BasicBlock edge; the SOURCE block
+     * (`a` — controller for CDG, def for REACHING_DEF) is filtered by the
+     * BasicBlock id-prefix (`basicBlockId` template) plus its `startLine` within
+     * the symbol's span. BasicBlock `startLine` is 1-based while symbol-node
+     * `startLine`/`endLine` are 0-based, so BOTH bounds are shifted +1
+     * (`[symStart+1, symEnd+1]`) onto the block basis: the upper +1 keeps a
+     * guard/def/use on the function's final line, and the lower +1 excludes an
+     * adjacent function's block on the line directly above (#2188 review). Both
+     * endpoints share the function (intra-procedural), so filtering the source
+     * endpoint suffices.
+     */
+    async _pdgQueryImpl(repo, params = {}) {
+        await this.ensureInitialized(repo);
+        // Mode validation — the JSON-schema enum is advisory for MCP clients, so
+        // the backend enforces it (an unhandled mode would otherwise fall through).
+        const mode = params.mode;
+        if (mode !== 'controls' && mode !== 'flows') {
+            return {
+                error: `Invalid "mode": expected "controls" or "flows", got ${JSON.stringify(params.mode)}.`,
+            };
+        }
+        const rawLimit = params.limit ?? PDG_QUERY_DEFAULT_LIMIT;
+        if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > PDG_QUERY_MAX_LIMIT) {
+            return {
+                error: `Invalid "limit": expected an integer in [1, ${PDG_QUERY_MAX_LIMIT}], got ${JSON.stringify(params.limit)}.`,
+            };
+        }
+        const limit = rawLimit;
+        // PDG queries are always anchored (no rel-property index ⇒ an unanchored
+        // basic-block path scan is unbounded). `target` is required.
+        const target = typeof params.target === 'string' ? params.target.trim() : '';
+        if (!target) {
+            return {
+                error: 'pdg_query requires a "target" (a file path or symbol/function name) — PDG queries are always anchored.',
+            };
+        }
+        const edgeType = mode === 'controls' ? 'CDG' : 'REACHING_DEF';
+        // Definitive: the meta stamp says this layer was never recorded.
+        const NO_PDG_NOTE = `no PDG layer — run gitnexus analyze --pdg to record ${edgeType} edges for this repo`;
+        // Inconclusive: meta is unreadable AND a global probe found zero rows of this
+        // edge type — but a genuinely edge-free layer (all-linear functions) looks
+        // identical to a missing one, so don't assert absence (#2188 review).
+        const PDG_LAYER_UNKNOWN_NOTE = `no ${edgeType} edges found for this target; PDG layer status unknown — was this repo indexed with gitnexus analyze --pdg?`;
+        // Cheap meta probe: the layer exists iff the pdg stamp carries the
+        // mode-relevant cap (maxCdgEdgesPerFunction for CDG, maxReachingDef…
+        // for REACHING_DEF). Absent ⇒ the no-layer hint without a DB scan.
+        // `pdgStampForMode` is the shared meta read (the both-caps `pdgLayerStatus`
+        // helper consumes the same underlying read for impact); here we project it
+        // down to this one mode's cap, preserving the tri-state `boolean | undefined`
+        // contract byte-for-byte: `false` ⇒ definitive no-layer (short-circuit
+        // below), `true` ⇒ proceed, `undefined` ⇒ meta unreadable, defer to the
+        // post-anchored-query probe (Feasibility Issue 4).
+        const pdgStamped = await pdgStampForMode(repo.lbugPath, mode);
+        if (pdgStamped === false) {
+            return { mode, results: [], total: 0, note: NO_PDG_NOTE };
+        }
+        // Resolve the anchor on the SOURCE block via the shared resolver also used
+        // by explain (#2188): file id-prefix OR symbol span on the corrected
+        // [symStart+1, symEnd+1] window. `target` is required, so the early cases
+        // (not-found/ambiguous) return here and `anchor`/`anchorClause` are always
+        // set below (anchor stays non-optional — no `| undefined` — #2188 CodeQL).
+        const resolved = await this.resolveBlockAnchor(repo, target, 'pdg_query');
+        if (resolved.early)
+            return resolved.early;
+        const { anchorClause, anchor } = resolved;
+        const queryParams = resolved.queryParams;
+        // Optional variable filter (flows mode) — REACHING_DEF stores the variable
+        // name in `reason`. FU-B-2 prefixes the name with a `<name>|1:<def>:<use>`
+        // annotation (name FIRST), so match BOTH a legacy bare-name reason (`=`) AND
+        // an annotated one (`STARTS WITH <name>|`). Source identifiers never contain
+        // `|`, so the `<name>|` prefix is exact (it cannot collide with a longer name
+        // — `ab|…` is not a prefix of `abc|…`).
+        let reasonClause = '';
+        if (mode === 'flows' && typeof params.variable === 'string' && params.variable.trim()) {
+            reasonClause = ' AND (r.reason = $variable OR r.reason STARTS WITH $variablePrefix)';
+            const variable = params.variable.trim();
+            queryParams.variable = variable;
+            queryParams.variablePrefix = `${variable}|`;
+        }
+        // edgeType is a hardcoded per-mode literal (never user input); `target` /
+        // `variable` flow only through bind params (no Cypher interpolation).
+        const matchClause = `
+      MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock)
+      WHERE r.type = '${edgeType}' AND ${anchorClause}${reasonClause}`;
+        const [rows, countRows] = await Promise.all([
+            executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN a.id AS srcId, a.startLine AS srcLine, b.startLine AS dstLine, b.text AS dstText, r.reason AS reason
+      ORDER BY srcId, dstLine, reason
+      LIMIT ${limit}`, queryParams),
+            executeParameterized(repo.lbugPath, `${matchClause}\n      RETURN COUNT(*) AS total`, queryParams),
+        ]);
+        const total = Number(countRows[0]?.total ?? countRows[0]?.[0] ?? 0);
+        // Unreadable meta + anchored miss: one bounded probe distinguishes "no rows
+        // for this anchor" from "no rows of this edge type at all". With meta
+        // unreadable we cannot tell a missing layer from an edge-free one, so the
+        // note is the inconclusive "status unknown" form, not the definitive
+        // NO_PDG_NOTE (which is reserved for the meta-stamped absence above).
+        if (total === 0 && pdgStamped === undefined) {
+            const probe = await executeParameterized(repo.lbugPath, `MATCH (:BasicBlock)-[r:CodeRelation]->(:BasicBlock) WHERE r.type = '${edgeType}' RETURN r.reason AS reason LIMIT 1`, {});
+            if (probe.length === 0)
+                return { mode, results: [], total: 0, note: PDG_LAYER_UNKNOWN_NOTE };
+        }
+        // basicBlockId = `BasicBlock:<filePath>:<fnLine>:<fnCol>:<blockIdx>` — split
+        // from the RIGHT (filePath may contain ':'). Shared module-scope `fnLineOf`.
+        const results = mode === 'controls'
+            ? rows.map((r) => {
+                const fnLine = fnLineOf(String(r.srcId ?? r[0] ?? ''));
+                const dstText = String(r.dstText ?? r[3] ?? '');
+                // A CDG edge into an early-exit block is a guard clause (subsumes
+                // #559): the controller predicate gates the dependent via `label`.
+                const isGuardExit = /^\s*(return|throw|continue|break)\b/.test(dstText);
+                return {
+                    ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                    controller: { line: (r.srcLine ?? r[1]) },
+                    dependent: { line: (r.dstLine ?? r[2]), text: dstText },
+                    label: String(r.reason ?? r[4] ?? ''),
+                    ...(isGuardExit ? { guard: true } : {}),
+                };
+            })
+            : rows.map((r) => {
+                const fnLine = fnLineOf(String(r.srcId ?? r[0] ?? ''));
+                // FU-B-2: REACHING_DEF `reason` is `<name>` (legacy) or
+                // `<name>|1:<defLine>:<useLine>` — decode to surface the bare
+                // variable name, not the encoded annotation.
+                const variable = decodeReachingDefReason(r.reason ?? r[4] ?? '').name;
+                return {
+                    ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                    variable,
+                    def: { line: (r.srcLine ?? r[1]) },
+                    use: {
+                        line: (r.dstLine ?? r[2]),
+                        text: String(r.dstText ?? r[3] ?? ''),
+                    },
+                };
+            });
+        return {
+            mode,
+            anchor,
+            results,
+            total,
+            ...(total > results.length ? { truncated: true } : {}),
+        };
+    }
     /**
      * Legacy explore — kept for backwards compatibility with resources.ts.
      * Routes cluster/process types to direct graph queries.
@@ -2402,8 +3007,20 @@ export class LocalBackend {
                 queryParams[`hunkStart${i}`] = hunk.startLine;
                 queryParams[`hunkEnd${i}`] = hunk.endLine;
             });
+            // Exclude BasicBlock rows by id prefix: on a --pdg index every edited
+            // function otherwise contributes N nameless BasicBlock pseudo-"symbols"
+            // (they carry filePath/start/end but no name), inflating changed_count
+            // and risk level with rows no consumer can act on (#2082 U7). Blocks
+            // are implementation substrate, not symbols — the owning Function row
+            // already represents the change. The id prefix (`BasicBlock:<file>:…`,
+            // cfg/emit.ts basicBlockId) beats a label predicate (`labels(n)[0]` is
+            // known to come back empty for several node types — see
+            // enrichCandidateLabels) AND beats `n.name IS NOT NULL` (which would
+            // also drop legitimate symbols whose name loaded as NULL, e.g.
+            // quoted-empty CSV fields for anonymous constructs).
             const symbolQuery = `
         MATCH (n) WHERE n.filePath ENDS WITH $filePath
+          AND NOT n.id STARTS WITH 'BasicBlock:'
           AND n.startLine IS NOT NULL AND n.endLine IS NOT NULL
           AND (${overlapConditions})
         RETURN n.id AS id, n.name AS name, labels(n)[0] AS type,
@@ -2648,26 +3265,317 @@ export class LocalBackend {
             applied: !dry_run,
         };
     }
+    async trace(repo, params) {
+        try {
+            return await this._traceImpl(repo, params);
+        }
+        catch (err) {
+            return {
+                status: 'error',
+                error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed',
+                from: { name: params.from },
+                to: { name: params.to },
+                suggestion: 'The graph query failed — try gitnexus context <symbol> to see connections, ' +
+                    'or check if an interface bridges them.',
+                ...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
+            };
+        }
+    }
+    async _traceImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        // resolveSymbolCandidates feeds `from`/`to` into string operations
+        // (e.g. name.includes), so a non-string param would surface a low-level
+        // "x.includes is not a function". Reject it with a clear message instead.
+        const isStringOrAbsent = (v) => v === undefined || typeof v === 'string';
+        if (!isStringOrAbsent(params.from) ||
+            !isStringOrAbsent(params.to) ||
+            !isStringOrAbsent(params.from_uid) ||
+            !isStringOrAbsent(params.to_uid)) {
+            return {
+                status: 'error',
+                error: "'from', 'to', and their *_uid variants must be strings.",
+                suggestion: 'Pass symbol names or UIDs as strings, e.g. trace from="A" to="B".',
+            };
+        }
+        const fromOutcome = await this.resolveSymbolCandidates(repo, { uid: params.from_uid, name: params.from }, { file_path: params.from_file });
+        if (fromOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Source symbol '${params.from_uid ?? params.from}' not found.`,
+                suggestion: 'Check the symbol name or use --from-uid for zero-ambiguity.',
+            };
+        }
+        if (fromOutcome.kind === 'ambiguous') {
+            return {
+                status: 'ambiguous',
+                role: 'from',
+                message: `Found ${fromOutcome.candidates.length} symbols matching '${params.from}'. Disambiguate with --from-uid.`,
+                candidates: fromOutcome.candidates,
+            };
+        }
+        const toOutcome = await this.resolveSymbolCandidates(repo, { uid: params.to_uid, name: params.to }, { file_path: params.to_file });
+        if (toOutcome.kind === 'not_found') {
+            return {
+                status: 'not_found',
+                error: `Target symbol '${params.to_uid ?? params.to}' not found.`,
+                suggestion: 'Check the symbol name or use --to-uid for zero-ambiguity.',
+            };
+        }
+        if (toOutcome.kind === 'ambiguous') {
+            return {
+                status: 'ambiguous',
+                role: 'to',
+                message: `Found ${toOutcome.candidates.length} symbols matching '${params.to}'. Disambiguate with --to-uid.`,
+                candidates: toOutcome.candidates,
+            };
+        }
+        const fromSym = fromOutcome.symbol;
+        const toSym = toOutcome.symbol;
+        if (fromSym.id === toSym.id) {
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: 0,
+                hops: [{ name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine }],
+                edges: [],
+            };
+        }
+        // Sanitize maxDepth at the real boundary: the MCP inputSchema's
+        // minimum/maximum is advisory only (callTool is reachable directly), so a
+        // caller can pass 0, a negative, NaN, or a non-integer. `??` does NOT
+        // recover 0/NaN, and Math.min has no lower bound — left unguarded, any of
+        // those makes the BFS loop run zero iterations and return a false no_path.
+        const DEFAULT_TRACE_DEPTH = 10;
+        const MAX_TRACE_DEPTH = 30;
+        const requestedDepth = Number.isInteger(params.maxDepth) && params.maxDepth > 0
+            ? params.maxDepth
+            : DEFAULT_TRACE_DEPTH;
+        const maxDepth = Math.min(requestedDepth, MAX_TRACE_DEPTH);
+        const includeTests = params.includeTests ?? false;
+        // Traversal vocabulary: CALLS for actual calls, HAS_METHOD so a class-rooted
+        // trace can descend into its methods. Not "calls only" — per-hop edge type is
+        // surfaced in edges[] so containment hops stay distinguishable.
+        const TRAVERSAL_EDGE_TYPES = ['CALLS', 'HAS_METHOD'];
+        // Bound the traversal so a high-fanout hub (a logger/util reached by many
+        // symbols) can't materialize an unbounded frontier. Per-level rows are
+        // capped and the total visited set is capped; either cap sets `truncated`
+        // so a resulting no_path is never reported as if the graph was exhausted.
+        const PER_NODE_FANOUT_CAP = 200;
+        const ABS_ROW_CAP = 5000;
+        const MAX_VISITED = 50000;
+        let truncated = false;
+        const visited = new Set([fromSym.id]);
+        let frontier = [fromSym.id];
+        const parent = new Map();
+        let found = false;
+        // The last node discovered at the deepest reached level — surfaced as
+        // `furthest` in the no_path response to hint where the chain breaks.
+        let lastReached = null;
+        let reachedDepth = 0;
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0 && !found; depth++) {
+            const nextFrontier = [];
+            // LadybugDB/Kuzu does not support a parameterized LIMIT, so the cap is
+            // interpolated (it is a derived integer, not user input).
+            const rowCap = Math.min(frontier.length * PER_NODE_FANOUT_CAP, ABS_ROW_CAP);
+            const rows = await executeParameterized(repo.lbugPath, `MATCH (n)-[r:CodeRelation]->(m)
+         WHERE n.id IN $frontierIds AND r.type IN $edgeTypes
+         RETURN n.id AS sourceId, m.id AS id, m.name AS name, labels(m)[0] AS type,
+                m.filePath AS filePath, m.startLine AS startLine,
+                r.type AS edgeType, r.confidence AS confidence
+         LIMIT ${rowCap}`, { frontierIds: frontier, edgeTypes: TRAVERSAL_EDGE_TYPES });
+            // A clipped level may have dropped a node that lies on the only shortest
+            // path, so any subsequent no_path is not authoritative.
+            if (rows.length >= rowCap)
+                truncated = true;
+            for (const row of rows) {
+                // Decode once. The `?? row[N]` fallback handles LadybugDB tuple-mode
+                // returns; the positional indices mirror the RETURN column order above.
+                const nodeId = (row.id ?? row[1]);
+                const sourceId = (row.sourceId ?? row[0]);
+                const name = (row.name ?? row[2]);
+                const filePath = (row.filePath ?? row[4]);
+                const startLine = (row.startLine ?? row[5]);
+                const edgeType = (row.edgeType ?? row[6]);
+                const storedConfidence = row.confidence ?? row[7];
+                const confidence = typeof storedConfidence === 'number' && storedConfidence > 0
+                    ? storedConfidence
+                    : confidenceForRelType(edgeType);
+                // Match the explicitly-requested target before the test-file filter.
+                // resolveSymbolCandidates does not exclude test-file symbols, so a
+                // target (or a required hop) that lives in a test file would otherwise
+                // be dropped by the includeTests guard below and produce a false
+                // no_path even when a direct edge exists.
+                if (nodeId === toSym.id) {
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    found = true;
+                    break;
+                }
+                // Skip non-target nodes that live in test files unless includeTests.
+                if (!includeTests && isTestFilePath(filePath))
+                    continue;
+                if (!visited.has(nodeId)) {
+                    visited.add(nodeId);
+                    parent.set(nodeId, { from: sourceId, name, filePath, startLine, edgeType, confidence });
+                    nextFrontier.push(nodeId);
+                    lastReached = { name, filePath, startLine };
+                    reachedDepth = depth;
+                }
+            }
+            frontier = nextFrontier;
+            if (visited.size >= MAX_VISITED) {
+                truncated = true;
+                break;
+            }
+        }
+        if (found) {
+            const path = [];
+            const edges = [];
+            let current = toSym.id;
+            while (current !== fromSym.id) {
+                const info = parent.get(current);
+                path.unshift({ name: info.name, filePath: info.filePath, startLine: info.startLine });
+                edges.unshift({ relType: info.edgeType, confidence: info.confidence });
+                current = info.from;
+            }
+            path.unshift({
+                name: fromSym.name,
+                filePath: fromSym.filePath,
+                startLine: fromSym.startLine,
+            });
+            return {
+                status: 'ok',
+                from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+                to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+                hopCount: edges.length,
+                hops: path,
+                edges,
+            };
+        }
+        return {
+            status: 'no_path',
+            from: { name: fromSym.name, filePath: fromSym.filePath, startLine: fromSym.startLine },
+            to: { name: toSym.name, filePath: toSym.filePath, startLine: toSym.startLine },
+            furthest: lastReached ? { ...lastReached, depth: reachedDepth } : null,
+            ...(truncated ? { truncated: true } : {}),
+            suggestion: truncated
+                ? 'Search was truncated at a traversal cap before exhausting the graph — a path ' +
+                    'may still exist. Narrow the search (a lower --depth, or trace from a more ' +
+                    'specific symbol), or use gitnexus context <symbol> to inspect connections.'
+                : 'No directed path found. The call chain likely breaks at dynamic dispatch, ' +
+                    'reflection, or an external API boundary. Try gitnexus context <symbol> to see ' +
+                    "both symbols' connections, or check if an interface/abstraction bridges them.",
+        };
+    }
     async impact(repo, params) {
         try {
             return await this._impactImpl(repo, params);
         }
         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;
+            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
+                // the partial-but-typed target — typed as PdgImpactTarget so the partial
+                // is type-checked, not an inline literal in a Promise<any> hole.
+                const target = { name: params.target };
+                const pdgErr = makePdgImpactErrorResult({
+                    mode: 'pdg',
+                    error: message,
+                    target,
+                    direction: params.direction,
+                    suggestion,
+                    recoverySuggestion,
+                });
+                return pdgErr;
+            }
             return {
-                error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed',
+                error: message,
                 target: { name: params.target },
                 direction: params.direction,
                 impactedCount: 0,
                 risk: 'UNKNOWN',
-                suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
-                ...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
+                suggestion,
+                ...(recoverySuggestion ? { recoverySuggestion } : {}),
             };
         }
     }
     async _impactImpl(repo, params) {
         await this.ensureInitialized(repo);
         const { target, direction } = params;
+        // ── Dispatch order (KTD5) ──────────────────────────────────────────
+        // (1) Validate `mode`. Absent/'callgraph' → unchanged path; 'pdg' → the
+        // intra-procedural PDG engine; anything else → hard error.
+        // This MUST come before resolveSymbolCandidates so the ambiguous branch can
+        // fork on the validated mode and never run the callgraph fan-out under pdg.
+        const modeResult = validateImpactMode(params.mode);
+        if ('error' in modeResult) {
+            return {
+                error: modeResult.error,
+                target: { name: target },
+                direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+            };
+        }
+        const mode = modeResult.mode;
+        // `line` is a PDG-only statement anchor. Reject it on the callgraph path
+        // rather than silently ignore (the symbol→symbol BFS has no statement notion).
+        if (params.line !== undefined && mode !== 'pdg') {
+            return {
+                error: `Parameter 'line' is only supported with mode:'pdg' (it anchors the dependence slice on a statement). Remove it or set mode:'pdg'.`,
+                target: { name: params.target },
+                direction: params.direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+            };
+        }
+        // A provided `line` must be a positive integer.
+        if (params.line !== undefined &&
+            (!Number.isInteger(params.line) || params.line < 1)) {
+            // Line param fails validation before target resolution → partial-but-typed
+            // target on the pdg path (typed PdgImpactTarget, not an inline literal).
+            const badLineTarget = { name: params.target };
+            return mode === 'pdg'
+                ? makePdgImpactErrorResult({
+                    mode: 'pdg',
+                    error: `Parameter 'line' must be a positive integer (1-based source line), got ${JSON.stringify(params.line)}.`,
+                    target: badLineTarget,
+                    direction: params.direction,
+                })
+                : {
+                    error: `Parameter 'line' must be a positive integer (1-based source line), got ${JSON.stringify(params.line)}.`,
+                    target: { name: params.target },
+                    direction: params.direction,
+                    impactedCount: 0,
+                    risk: 'UNKNOWN',
+                };
+        }
+        if (mode === 'pdg') {
+            // PDG mode is now unified inside a single repo: it combines the local
+            // CDG/RD statement slice with the same inter-symbol reach used for the
+            // option-driven comparison path. Cross-repo fan-out remains a callgraph
+            // feature, so crossDepth is still a loud error rather than a silent ignore.
+            const incompatible = [];
+            if (params.crossDepth !== undefined)
+                incompatible.push('crossDepth');
+            if (incompatible.length > 0) {
+                // crossDepth is rejected before target resolution → partial-but-typed
+                // target (typed PdgImpactTarget).
+                const crossDepthTarget = { name: target };
+                const pdgErr = makePdgImpactErrorResult({
+                    mode: 'pdg',
+                    error: `Parameter(s) ${incompatible.join(', ')} are not supported with mode:'pdg' ` +
+                        `(single-repo PDG impact). Remove them or use mode:'callgraph' for cross-repo fan-out.`,
+                    target: crossDepthTarget,
+                    direction,
+                });
+                return pdgErr;
+            }
+        }
         const maxDepth = params.maxDepth || 3;
         // Map legacy relation type names before filtering (backward compat for OVERRIDES → METHOD_OVERRIDES)
         const mappedRelTypes = params.relationTypes?.flatMap((t) => t === 'OVERRIDES' ? ['OVERRIDES', 'METHOD_OVERRIDES'] : [t]);
@@ -2710,15 +3618,64 @@ export class LocalBackend {
         const outcome = await this.resolveSymbolCandidates(repo, { uid: params.target_uid, name: target }, { file_path: params.file_path, kind: params.kind });
         if (outcome.kind === 'not_found') {
             const missing = params.target_uid ?? target;
-            return {
-                error: `Target '${missing}' not found`,
-                target: { name: target },
-                direction,
-                impactedCount: 0,
-                risk: 'UNKNOWN',
-            };
+            // not_found = no resolved symbol, so the envelope keeps the partial-but-
+            // typed target (typed PdgImpactTarget — there is no id/type/filePath yet).
+            const notFoundTarget = { name: target };
+            return mode === 'pdg'
+                ? makePdgImpactErrorResult({
+                    mode: 'pdg',
+                    error: `Target '${missing}' not found`,
+                    target: notFoundTarget,
+                    direction,
+                })
+                : {
+                    error: `Target '${missing}' not found`,
+                    target: { name: target },
+                    direction,
+                    impactedCount: 0,
+                    risk: 'UNKNOWN',
+                };
         }
         if (outcome.kind === 'ambiguous') {
+            // Shared truncation cap for the ambiguous candidate list — both the pdg
+            // branch (shows candidates) and the callgraph branch (probes candidates)
+            // bound to this many.
+            const AMBIGUOUS_MAX_CANDIDATES = 6;
+            // KTD5 ambiguous trap — under mode:'pdg' we MUST NOT fall into the
+            // callgraph fan-out below: it runs `_runImpactBFS` per candidate, which
+            // would silently execute the call-graph engine under a `pdg` call (the
+            // exact silent fallback KTD5 forbids). For U1 the pdg ambiguous path
+            // returns the candidate list WITHOUT any callgraph probe; the full pdg
+            // ambiguous handling (per-candidate PDG summaries / ranking) lands in U4.
+            if (mode === 'pdg') {
+                const truncated = outcome.candidates.length > AMBIGUOUS_MAX_CANDIDATES;
+                const shown = outcome.candidates.slice(0, AMBIGUOUS_MAX_CANDIDATES);
+                return {
+                    status: 'ambiguous',
+                    mode,
+                    message: `Found ${outcome.candidates.length} symbols matching '${target}'` +
+                        (truncated ? ` (showing ${shown.length} of ${outcome.candidates.length})` : '') +
+                        `. Disambiguate with target_uid (or file_path/kind) for a single ` +
+                        `authoritative PDG result.`,
+                    target: { name: target },
+                    direction,
+                    totalCandidates: outcome.candidates.length,
+                    // No single resolved symbol → impactedCount stays 0 / risk UNKNOWN
+                    // (UNKNOWN must never read as "safe to refactor"). No callgraph
+                    // fan-out runs, so there is no per-candidate blast radius here yet.
+                    impactedCount: 0,
+                    risk: 'UNKNOWN',
+                    ...(truncated && { candidatesTruncated: true }),
+                    candidates: shown.map((c) => ({
+                        uid: c.id,
+                        name: c.name,
+                        kind: c.type,
+                        filePath: c.filePath,
+                        line: c.startLine,
+                        score: Number(c.score.toFixed(2)),
+                    })),
+                };
+            }
             // #2129 — a bare name that collides with several symbols must NOT report a
             // bare `impactedCount: 0`. The real blast radius lives under whichever
             // candidate the caller meant; a flat zero here is precisely the silent
@@ -2728,7 +3685,6 @@ export class LocalBackend {
             // summary-only BFS per candidate so each one's true count + risk is
             // visible, and surface the maximum at the top level so the headline can
             // never read as "safe to refactor". Candidates arrive sorted by score.
-            const AMBIGUOUS_MAX_CANDIDATES = 6;
             const probed = outcome.candidates.slice(0, AMBIGUOUS_MAX_CANDIDATES);
             // `partialProbe` is intentionally a SECOND incompleteness flag, distinct
             // from the traversal-interrupted `partial` flag used elsewhere: it means
@@ -2822,13 +3778,127 @@ export class LocalBackend {
             id: outcome.symbol.id,
             name: outcome.symbol.name,
             filePath: outcome.symbol.filePath,
+            // Carry the resolved span so the PDG seed anchors on THIS symbol directly,
+            // without re-resolving its (possibly ambiguous) name (FIX 1).
+            startLine: outcome.symbol.startLine,
+            endLine: outcome.symbol.endLine,
         };
         const symType = outcome.resolvedLabel || outcome.symbol.type || '';
+        // (2) PDG-layer presence probe (U2, KTD7) — the four-state degradation
+        // contract after target resolution, before traversal. A repo never analyzed
+        // with `--pdg` (no-layer), one with only a partial layer (sub-layer-missing
+        // — impact needs BOTH CDG and REACHING_DEF), or one whose meta is unreadable
+        // (unknown) each returns a distinct guidance note here rather than a
+        // confusing empty blast radius. Resolve first so target-known degraded
+        // responses keep the same id/type/filePath envelope as successful PDG
+        // responses; only `ready` falls through to traversal.
+        // Hoisted so the (4) traversal branch can read `layer.hasCallSummary` (FU-C):
+        // the same single meta-stamp probe serves both the degradation gate and the
+        // ascent-availability note — no second probe.
+        let layer;
+        if (mode === 'pdg') {
+            layer = await pdgLayerStatus({
+                lbugPath: repo.lbugPath,
+                executeParameterized,
+            });
+            if (isPdgDegradedLayerStatus(layer)) {
+                // Degradation occurs AFTER target resolution → thread the FULL typed
+                // envelope ({ id, name, type, filePath }) so degraded responses keep the
+                // same target shape as a successful PDG result (typed PdgImpactTarget).
+                const degradedTarget = {
+                    id: sym.id,
+                    name: sym.name,
+                    type: symType || 'Function',
+                    filePath: sym.filePath,
+                };
+                return makePdgLayerDegradedResult({
+                    mode,
+                    layer,
+                    target: degradedTarget,
+                    direction,
+                });
+            }
+        }
         const effectiveRelationTypes = (symType === 'Class' || symType === 'Interface') &&
             !hasExplicitRelationTypes &&
             !relationTypes.includes('ACCESSES')
             ? [...relationTypes, 'ACCESSES']
             : relationTypes;
+        // (4) single → route the resolved symbol to the engine selected by `mode`.
+        if (mode === 'pdg') {
+            const pdgResult = await this._runImpactPDG({
+                repo,
+                sym,
+                symType,
+                direction,
+                maxDepth,
+                line: params.line,
+                limit: Number.isFinite(params.limit) ? params.limit : 100,
+                // KTD2 extraction-seam discipline: hand the engine its DB dependency
+                // explicitly rather than `this.`-binding it. LocalBackend owns repo
+                // lifecycle; `pdg-impact.ts` owns traversal/projection.
+                executeParameterized,
+                // FU-C: thread the CALL_SUMMARY layer presence read above (meta stamp) so
+                // the engine notes "no return-value ascent (re-index)" on a pre-FU-C (v3)
+                // index. `layer.hasCallSummary` is set on every meta-readable state.
+                callSummaryAvailable: layer?.hasCallSummary === true,
+            });
+            // Statement-precise inter-procedural reach: a first-hop callee is "proven"
+            // iff it is invoked in a block of the criterion's dependence slice. The
+            // slice = the seed block(s) (the changed line itself) UNION the dependent
+            // reachable blocks — both carry the leaf callee names they call
+            // (`BasicBlock.callees`). The seed block is included because a callee
+            // invoked directly on the changed line is the most-directly-impacted one,
+            // yet `reachableBlocks` excludes the seed by the seed-minus-reachable
+            // convention. Upstream seeds carry no discriminating slice, so the bridge
+            // falls back to preserving callgraph reach.
+            // `_runImpactPDG` returns the PdgImpactResult union; only the success/empty
+            // slice results carry intraReachableBlocks/seedBlocks (degraded and error
+            // results do not). Narrow via the same discriminant the composer uses, then
+            // read the typed string[] slices — no `as any`.
+            const sliceResult = 'error' in pdgResult || 'pdgLayer' in pdgResult ? null : pdgResult;
+            // FIX 6: key the "first-hop proven" set on the INTRA-procedural slice only
+            // (seed ∪ intra-reachable), NOT `reachableBlocks` — which the U1 descent now
+            // EXPANDS with inter-procedurally-reached callee blocks. Using the expanded
+            // superset would mark transitively-reached (2+ hop) callgraph targets as
+            // first-hop "proven", silently shifting the established statementPrecision
+            // semantics. The interproc-reached blocks are routed into the statement
+            // slice / block→symbol projection inside `_runImpactPDG` only.
+            const intraReachableBlocks = sliceResult?.intraReachableBlocks ?? [];
+            const seedBlocks = sliceResult?.seedBlocks ?? [];
+            const sliceBlocks = [...seedBlocks, ...intraReachableBlocks];
+            const sliceCalleeNames = direction === 'downstream' && sliceBlocks.length > 0
+                ? await this.calleesOfBlocks(repo, sliceBlocks)
+                : new Set();
+            // Resolved-id slice set (sound primary key, KTD3): unioned from the SAME
+            // seed ∪ reachable block set as the names — so a callee invoked only on the
+            // seeded line is still provable by id. Absent on a pre-v3 index (no
+            // `calleeIds` column) → empty → the bridge falls back to the leaf-name match.
+            const sliceCalleeIds = direction === 'downstream' && sliceBlocks.length > 0
+                ? await this.calleeIdsOfBlocks(repo, sliceBlocks)
+                : new Set();
+            // Build the bridge when EITHER the name fallback or the id key has signal —
+            // an id-only index (names empty but ids present) must still seed the bridge.
+            const pdgBridge = sliceCalleeNames.size > 0 || sliceCalleeIds.size > 0
+                ? { sliceCalleeNames, sliceCalleeIds }
+                : undefined;
+            try {
+                const interproceduralResult = await this._runImpactBFS(repo, sym, symType, direction, {
+                    maxDepth,
+                    relationTypes: effectiveRelationTypes,
+                    includeTests,
+                    minConfidence,
+                    limit: Number.isFinite(params.limit) ? params.limit : 100,
+                    offset: Number.isFinite(params.offset) ? params.offset : 0,
+                    pdgBridge,
+                });
+                return composeUnifiedPdgImpactResult(pdgResult, interproceduralResult);
+            }
+            catch (e) {
+                logQueryError('impact:pdg-interprocedural-reach', e);
+                return composeUnifiedPdgImpactResult(pdgResult, null, e);
+            }
+        }
         return this._runImpactBFS(repo, sym, symType, direction, {
             maxDepth,
             relationTypes: effectiveRelationTypes,
@@ -2839,6 +3909,79 @@ export class LocalBackend {
             summaryOnly: params.summaryOnly,
         });
     }
+    /**
+     * Union of the leaf callee names invoked across a set of dependence-slice
+     * blocks (`BasicBlock.callees`, space-joined at emit). Drives statement-precise
+     * inter-procedural evidence: a first-hop callee reached from the criterion is
+     * "proven" (callgraph-bridge) iff its name is in this set, else unproven-bridge.
+     * Empty when the slice blocks call nothing or carry no harvested callees
+     * (non-TS/JS or synthetic ENTRY/EXIT blocks) — the bridge then preserves
+     * callgraph reach. A query failure is logged and degrades to empty (no proof),
+     * never throws (the inter-procedural reach is still returned).
+     */
+    async calleesOfBlocks(repo, blockIds) {
+        const names = new Set();
+        if (blockIds.length === 0)
+            return names;
+        try {
+            const rows = await executeParameterized(repo.lbugPath, `MATCH (b:BasicBlock) WHERE b.id IN $ids RETURN b.callees AS callees`, { ids: blockIds });
+            for (const r of rows) {
+                const raw = String(r.callees ?? r[0] ?? '');
+                for (const n of raw.split(' '))
+                    if (n)
+                        names.add(n);
+            }
+        }
+        catch (e) {
+            logQueryError('impact:pdg-slice-callees', e);
+        }
+        return names;
+    }
+    /**
+     * Union of the RESOLVED callee symbol ids invoked across a set of
+     * dependence-slice blocks (`BasicBlock.calleeIds`, space-joined at emit —
+     * sibling of `callees`). This is the SOUND key the bridge prefers: a first-hop
+     * callee is proven statement-precise iff its resolved id is in this set, which
+     * eliminates the same-leaf-name collision (false-positive) and import-alias
+     * (false-negative) the name set cannot distinguish. Empty when the slice blocks
+     * carry no captured ids (pre-v3 index without the `calleeIds` column, or
+     * non-overloading/synthetic blocks) — the bridge then falls back to the
+     * leaf-name match per U5. A query failure is logged and degrades to empty (no
+     * proof), never throws (the inter-procedural reach is still returned). Mirrors
+     * `calleesOfBlocks` exactly — same shape, same swallow-on-error contract.
+     */
+    async calleeIdsOfBlocks(repo, blockIds) {
+        const ids = new Set();
+        if (blockIds.length === 0)
+            return ids;
+        try {
+            const rows = await executeParameterized(repo.lbugPath, `MATCH (b:BasicBlock) WHERE b.id IN $ids RETURN b.calleeIds AS calleeIds`, { ids: blockIds });
+            for (const r of rows) {
+                // Shared split-and-drop-sentinel logic (`splitCalleeIds`) so this bridge
+                // key and the inter-procedural descent cannot diverge. The sentinel marks
+                // a capped block (handled by the names-sentinel check in the bridge) and
+                // is not a resolved symbol id, so it never enters the `has(realId)` set.
+                for (const id of splitCalleeIds(r.calleeIds ?? r[0]))
+                    ids.add(id);
+            }
+        }
+        catch (e) {
+            logQueryError('impact:pdg-slice-callee-ids', e);
+        }
+        return ids;
+    }
+    /**
+     * Delegates the PDG impact engine to `pdg-impact.ts`.
+     *
+     * The private method remains as the LocalBackend dispatch seam so existing
+     * tests can keep asserting that `mode:'pdg'` routes through the PDG
+     * statement engine before LocalBackend attaches interprocedural symbol reach.
+     * The traversal/projection/result assembly lives in the extracted helper
+     * module.
+     */
+    async _runImpactPDG(deps) {
+        return runImpactPDG(deps);
+    }
     /**
      * #1858 — epistemic lower-bound detection.
      *
@@ -2972,6 +4115,7 @@ export class LocalBackend {
             : this.computeEpistemicBoundary(repo, symId, symType, (sym.name || sym[1]));
         const impacted = [];
         const visited = new Set([symId]);
+        const pdgBridgeEvidenceById = new Map();
         let frontier = [symId];
         let traversalComplete = true;
         // Fix #480: For Java (and other JVM) Class/Interface nodes, CALLS edges
@@ -3049,10 +4193,31 @@ export class LocalBackend {
                     ...(safeMinConfidence > 0 ? { minConfidence: safeMinConfidence } : {}),
                 });
                 for (const rel of related) {
+                    const sourceId = String(rel.sourceId ?? rel[0] ?? '');
                     const relId = rel.id || rel[1];
                     const filePath = rel.filePath || rel[4] || '';
                     if (!includeTests && isTestFilePath(filePath))
                         continue;
+                    // Bridge evidence is computed for EVERY edge (not just the first to
+                    // reach a node) and the strongest verdict across all parents is kept
+                    // (`callgraph-bridge` wins). This makes a diamond-reachable node's
+                    // proven/unproven label order-independent of DB row iteration; the
+                    // final label is stamped onto the impacted items after the depth loop.
+                    if (opts.pdgBridge) {
+                        const ev = pdgBridgeEvidenceForImpact({
+                            bridge: opts.pdgBridge,
+                            depth,
+                            calleeName: rel.name || rel[2],
+                            // Sound primary key (KTD3): the reached callee's RESOLVED id — the
+                            // same `relId` (`rel.id`) the BFS keys its visited/frontier sets on,
+                            // which equals the CALLS targetId captured into `BasicBlock.calleeIds`.
+                            // The bridge proves by id ∈ `sliceCalleeIds` first, falling back to
+                            // `calleeName` only when ids are absent or the block is capped.
+                            calleeId: relId,
+                            inherited: pdgBridgeEvidenceById.get(sourceId),
+                        });
+                        pdgBridgeEvidenceById.set(String(relId), betterBridgeEvidence(pdgBridgeEvidenceById.get(String(relId)), ev));
+                    }
                     if (!visited.has(relId)) {
                         visited.add(relId);
                         nextFrontier.push(relId);
@@ -3063,6 +4228,8 @@ export class LocalBackend {
                         const effectiveConfidence = typeof storedConfidence === 'number' && storedConfidence > 0
                             ? storedConfidence
                             : confidenceForRelType(relationType);
+                        // pdgEvidence is stamped after the depth loop from the finalized,
+                        // order-independent pdgBridgeEvidenceById map.
                         impacted.push({
                             depth,
                             id: relId,
@@ -3084,6 +4251,18 @@ export class LocalBackend {
             }
             frontier = nextFrontier;
         }
+        // Stamp the finalized, order-independent bridge evidence (strongest across
+        // all parents) onto each impacted item. Deferred from the BFS loop so a
+        // diamond-reachable node reflects a proven parent regardless of visit order.
+        if (opts.pdgBridge) {
+            for (const item of impacted) {
+                const ev = pdgBridgeEvidenceById.get(String(item.id));
+                if (ev) {
+                    item.pdgEvidence = ev.evidence;
+                    item.pdgBridgeBasis = ev.basis;
+                }
+            }
+        }
         const grouped = {};
         for (const item of impacted) {
             if (!grouped[item.depth])
@@ -3577,6 +4756,30 @@ export class LocalBackend {
             return { error: resolved.error };
         const svc = this.getGroupService();
         if (method === 'impact') {
+            // KTD5/KTD12 — validate `mode` at the group-forward boundary too (the
+            // JSON-schema enum is advisory). An invalid mode errors; `mode:'pdg'` is
+            // rejected for @group targets because PDG impact is single-repo and
+            // intra-procedural — there is no cross-repo dependence graph to walk.
+            // Rejecting here (before groupImpact) is the KTD12 @group hard error.
+            const groupModeResult = validateImpactMode(params.mode);
+            if ('error' in groupModeResult)
+                return { error: groupModeResult.error };
+            if (groupModeResult.mode === 'pdg') {
+                // @group reject: no single-repo symbol is ever resolved on the group path,
+                // so the envelope carries the partial-but-typed target (PdgImpactTarget).
+                // Routed through the typed builder so this exit is a PdgImpactResult union
+                // member, never a bare { error } object.
+                const groupRejectTarget = { name: String(params.target ?? '') };
+                const pdgErr = makePdgImpactErrorResult({
+                    mode: 'pdg',
+                    error: "mode:'pdg' is not supported for @group targets — PDG impact is " +
+                        'single-repo and intra-procedural. Run pdg impact against an ' +
+                        'individual indexed repository instead.',
+                    target: groupRejectTarget,
+                    direction: (params.direction === 'downstream' ? 'downstream' : 'upstream'),
+                });
+                return pdgErr;
+            }
             const impactArgs = {
                 name: groupName,
                 repo: resolved.repoPath,
@@ -3609,7 +4812,10 @@ export class LocalBackend {
         if (method === 'query') {
             const queryArgs = {
                 name: groupName,
-                query: params.query,
+                // #2175: resolve the search_query alias here (new name wins, same rule as the
+                // local query() handler) so the group path is self-contained and does not depend
+                // on params being normalized upstream. groupQuery() reads `query`.
+                query: resolveAliasString(params.search_query, params.query),
             };
             if (typeof params.task_context === 'string')
                 queryArgs.task_context = params.task_context;