gitnexus 1.6.8-rc.55 → 1.6.8-rc.57

package/dist/_shared/graph/types.d.ts

@@ -46,6 +46,9 @@ export type NodeProperties = {
     errorKeys?: string[];
     middleware?: string[];
     text?: string;
+    /** BasicBlock: space-joined leaf callee names invoked in the block — the
+     *  statement-precise inter-procedural reach substrate for impact mode. */
+    callees?: string;
     [key: string]: unknown;
 };
 export type RelationshipType = 'CONTAINS' | 'CALLS' | 'INHERITS' | 'METHOD_OVERRIDES' | 'METHOD_IMPLEMENTS' | 'IMPORTS' | 'USES' | 'DEFINES' | 'DECORATES' | 'IMPLEMENTS' | 'EXTENDS' | 'HAS_METHOD' | 'HAS_PROPERTY' | 'ACCESSES' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'HANDLES_ROUTE' | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES'
@@ -93,7 +96,20 @@ export type RelationshipType = 'CONTAINS' | 'CALLS' | 'INHERITS' | 'METHOD_OVERR
  *  removing it later is a breaking schema change — and it is deliberately
  *  excluded from `VALID_RELATION_TYPES` so it never enters impact-style
  *  symbol-space traversal (same posture as the taint substrate edges). */
- | 'POST_DOMINATE';
+ | 'POST_DOMINATE'
+/** Per-callee dependence SUMMARY edge (PDG FU-C): a self-loop on a
+ *  Function/Method/Constructor node carrying that callee's RETURN-VALUE
+ *  ASCENT — which formal-parameter indices flow to the function's return
+ *  value, encoded as a versioned bitset in the relation's existing `reason`
+ *  column (the same single-channel pattern `CFG`/`REACHING_DEF`/`CDG` use,
+ *  since the lone `CodeRelation` table has no dedicated label column). A
+ *  later consumer phase lets an interprocedural slice ascend a callee's
+ *  return effect into the caller continuation. Like the taint substrate
+ *  edges it is an internal PDG-engine edge: deliberately EXCLUDED from
+ *  `VALID_RELATION_TYPES` and the web schema so it never leaks into
+ *  callgraph-style impact/relationship surfaces. Emitted only under `--pdg`;
+ *  a default analyze emits zero. */
+ | 'CALL_SUMMARY';
 export interface GraphNode {
     id: string;
     label: NodeLabel;

package/dist/_shared/graph/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"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"}

package/dist/cli/ai-context.js

@@ -120,7 +120,9 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.${hasPdg
+        ? ` For unified PDG impact, add \`mode: "pdg"\` with optional \`line: <N>\` — it returns statement-level \`affectedStatements\` over CDG + REACHING_DEF and inter-procedural symbols in \`interproceduralByDepth\`/\`byDepth\`; no-layer/degraded PDG results are UNKNOWN-risk notes (\`--pdg\` layer).`
+        : ''}
 - **MUST run \`detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
 - When exploring unfamiliar code, use \`query({search_query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.

package/dist/cli/eval-server.d.ts

@@ -50,5 +50,13 @@ export declare function formatListReposResult(result: {
     repositories: RepoListing[];
     pagination?: ListReposPagination;
 }): string;
+export declare function getNextStepHint(toolName: string, result?: any): string;
 export declare function evalServerCommand(options?: EvalServerOptions): Promise<void>;
+/**
+ * Tools the eval-server exposes over HTTP — the read-only query surface the
+ * banner advertises. `LocalBackend.callTool` ALSO dispatches write-side / heavier
+ * tools (rename, shape_check, tool_map, …); the allowlist keeps a stray
+ * `POST /tool/<name>` from reaching those through this Docker/eval-harness server.
+ */
+export declare const EVAL_SERVER_TOOLS: ReadonlySet<string>;
 export declare const MAX_BODY_SIZE: number;

package/dist/cli/eval-server.js

@@ -29,6 +29,7 @@
  *   POST /shutdown     — Graceful shutdown.
  */
 import http from 'http';
+import crypto from 'node:crypto';
 import { isIPv4, isIPv6 } from 'node:net';
 import { writeSync } from 'node:fs';
 import { LocalBackend, } from '../mcp/local/local-backend.js';
@@ -146,6 +147,14 @@ export function formatContextResult(result) {
     }
     return lines.join('\n').trim();
 }
+function formatTruncationSuffix(result) {
+    const label = Array.isArray(result.truncatedByReasons)
+        ? result.truncatedByReasons.join(', ')
+        : typeof result.truncatedBy === 'string'
+            ? result.truncatedBy
+            : '';
+    return label ? ` (by ${label})` : '';
+}
 export function formatImpactResult(result) {
     if (result.error) {
         const suggestion = result.suggestion ? `\nSuggestion: ${result.suggestion}` : '';
@@ -160,6 +169,25 @@ export function formatImpactResult(result) {
     // mirroring formatContextResult, so the real impact under whichever symbol the
     // caller meant is visible on the text surface, not just in the JSON.
     if (result.status === 'ambiguous') {
+        if (result.mode === 'pdg') {
+            const shown = result.candidates?.length ?? 0;
+            const totalCandidates = result.totalCandidates ?? shown;
+            const countPhrase = totalCandidates > shown
+                ? `${totalCandidates} symbols (showing ${shown})`
+                : `${totalCandidates} symbols`;
+            const lines = [
+                `${target?.name || '?'}: AMBIGUOUS — ${countPhrase} share this name. ` +
+                    `PDG impact was not computed until the target is disambiguated. ` +
+                    `Use --uid, file_path, or kind for one authoritative PDG result.`,
+            ];
+            if (result.message)
+                lines.push(String(result.message));
+            for (const c of result.candidates || []) {
+                const score = typeof c.score === 'number' ? ` score ${c.score}` : '';
+                lines.push(`  ${c.kind} ${c.name} → ${c.filePath}:${c.line || '?'}${score}  (uid: ${c.uid})`);
+            }
+            return lines.join('\n');
+        }
         // #2129 review F11 — report the FULL match count (`totalCandidates`), not the
         // truncated `candidates[]` length; note when the candidate list is capped.
         const shown = result.candidates?.length ?? 0;
@@ -180,6 +208,176 @@ export function formatImpactResult(result) {
         }
         return lines.join('\n');
     }
+    // ─── PDG mode (mode:'pdg') ────────────────────────────────────────────
+    // KTD8 presentation half. PDG results are intra-procedural Program
+    // Dependence Graph blast radii: the single collapsed `byDepth[1]` bucket
+    // has NO call-hop depth meaning (block-hops ≠ call-hops), so we must NOT
+    // reuse the callgraph "depth N / WILL BREAK (direct)" framing, the
+    // callgraph DI/dynamic-dispatch lower-bound copy, or the confident
+    // "isolated" zero. A degraded / no-body PDG result is INCONCLUSIVE, not
+    // safe-to-refactor — it gets the explicit caveat + remediation, never an
+    // empty blast radius. Detect on `mode:'pdg'` (every PDG return path —
+    // findings, degradation, no-body, no-dependence — carries it). Ambiguous
+    // PDG results carry `status:'ambiguous'` and are handled above; they never
+    // reach here.
+    if (result.mode === 'pdg') {
+        const name = target?.name || '?';
+        const appendPdgInterproceduralSymbols = (lines) => {
+            const byDepth = result.interproceduralByDepth || result.pdgInterprocedural?.byDepth || result.byDepth || {};
+            const byDepthCounts = result.interproceduralByDepthCounts ||
+                result.pdgInterprocedural?.byDepthCounts ||
+                result.byDepthCounts ||
+                {};
+            const depthKeys = Array.from(new Set([...Object.keys(byDepthCounts), ...Object.keys(byDepth)]))
+                .map((d) => Number(d))
+                .filter((d) => Number.isFinite(d))
+                .sort((a, b) => a - b);
+            const hasReach = depthKeys.some((depth) => {
+                const items = byDepth[depth] || byDepth[String(depth)] || [];
+                const count = byDepthCounts[depth] ?? byDepthCounts[String(depth)] ?? items.length;
+                return count > 0;
+            });
+            if (!hasReach)
+                return false;
+            const totalSymbols = result.pdgInterprocedural?.impactedCount ??
+                (typeof result.impactedCount === 'number' ? result.impactedCount : 0);
+            lines.push('');
+            lines.push(`Inter-procedural symbol reach (${totalSymbols}):`);
+            for (const depth of depthKeys) {
+                const items = byDepth[depth] || byDepth[String(depth)] || [];
+                const count = byDepthCounts[depth] ?? byDepthCounts[String(depth)] ?? items.length;
+                if (count <= 0)
+                    continue;
+                lines.push(`  d=${depth} (${count})`);
+                const shown = Math.min(items.length, 12);
+                for (const item of items.slice(0, shown)) {
+                    const flags = [];
+                    if (item.unresolved)
+                        flags.push('unresolved');
+                    if (item.ambiguous)
+                        flags.push('ambiguous');
+                    const flagStr = flags.length ? ` [${flags.join(', ')}]` : '';
+                    lines.push(`    ${item.type || ''} ${item.name} → ${item.filePath}${flagStr}`);
+                }
+                if (count > shown)
+                    lines.push(`    ... and ${count - shown} more`);
+            }
+            return true;
+        };
+        // (1) Degradation — the PDG layer (or a sub-layer) is absent/unreadable.
+        // `pdgLayer` is the non-'ready' state from `pdgLayerStatus`. Print the
+        // honest remediation, NOT a zero/empty blast radius.
+        if (result.pdgLayer) {
+            const subLayer = result.missingSubLayer
+                ? ` (missing sub-layer: ${result.missingSubLayer})`
+                : '';
+            return (`${name}: PDG impact unavailable — the index has no usable PDG layer ` +
+                `[${result.pdgLayer}]${subLayer}. This is NOT "no impact". ` +
+                `Re-index with \`gitnexus analyze --pdg\` to build the control/data ` +
+                `dependence layer, or use \`--mode callgraph\` for the call-graph blast radius.` +
+                (result.note ? `\n${result.note}` : ''));
+        }
+        // (2) No-body symbol (KTD6) — interface / type alias / abstract / ambient
+        // member / one-line declaration with no CFG. Show the caveat, never
+        // "isolated / no dependencies".
+        if (result.epistemic === 'no-pdg-body') {
+            const noBodyLines = [
+                `${name}: local PDG slice not applicable to this symbol — it has no PDG body ` +
+                    `(no control/data dependence edges; e.g. an interface, type alias, ` +
+                    `abstract/ambient member, or a one-line declaration). This is NOT a ` +
+                    `confident "no impact".`,
+            ];
+            appendPdgInterproceduralSymbols(noBodyLines);
+            if (result.note)
+                noBodyLines.push(result.note);
+            return noBodyLines.join('\n');
+        }
+        // (2b) STATEMENT-ANCHORED SLICE (mode:'pdg' + line). When `criterionLine` is
+        // present the result is a statement slice: the seeded line plus the list of
+        // dependent statements (`affectedStatements: {line,filePath,text}[]`). Render
+        // those statements directly — this IS the useful output of statement mode —
+        // rather than the symbol-projection bucket below. Empty cases:
+        //   - `pdg-no-block-at-line`: the line is blank / a comment / outside the
+        //     body (no statement block) — print the steering note.
+        //   - empty `affectedStatements` with `pdg-intra-procedural`: the line has no
+        //     dependents in this direction — print the steering note.
+        // Each non-empty case also surfaces truncation honestly.
+        if (typeof result.criterionLine === 'number') {
+            const slice = Array.isArray(result.affectedStatements)
+                ? result.affectedStatements
+                : [];
+            const count = typeof result.affectedStatementCount === 'number'
+                ? result.affectedStatementCount
+                : slice.length;
+            // File anchor for the heading — the seeded statement's file (every slice
+            // statement shares the function's file). Fall back to the target's file.
+            const anchorFile = slice[0]?.filePath || target?.filePath || name;
+            if (count === 0 || slice.length === 0) {
+                // No statement block at the line, or no dependents in this direction.
+                // Print the honest note (pdg-no-block-at-line or the no-dependence note)
+                // verbatim — never an empty "isolated" headline.
+                const emptySliceLines = [
+                    `No statements ${direction}-dependent on ${anchorFile}:${result.criterionLine}.`,
+                ];
+                if (result.truncated) {
+                    const by = formatTruncationSuffix(result);
+                    emptySliceLines.push(`⚠️  Truncated${by} — the dependence slice was bounded; deeper PDG-dependent statements may exist.`);
+                }
+                appendPdgInterproceduralSymbols(emptySliceLines);
+                if (result.note)
+                    emptySliceLines.push(result.note);
+                return emptySliceLines.join('\n');
+            }
+            const slLines = [];
+            slLines.push(`Statements ${direction}-dependent on ${anchorFile}:${result.criterionLine} (${count}):`);
+            for (const s of slice) {
+                const text = typeof s.text === 'string' ? s.text : '';
+                slLines.push(`  L${s.line}: ${text}`);
+            }
+            // Truncation honesty — the slice may be a lower bound (depth or per-step
+            // LIMIT bound). Surface it the same way the symbol render does.
+            if (result.truncated) {
+                const by = formatTruncationSuffix(result);
+                slLines.push(`⚠️  Truncated${by} — the dependence slice was bounded; deeper PDG-dependent statements may exist.`);
+            }
+            appendPdgInterproceduralSymbols(slLines);
+            if (result.note) {
+                slLines.push('');
+                slLines.push(`ℹ️  ${result.note}`);
+            }
+            return slLines.join('\n').trim();
+        }
+        const pdgLines = [];
+        if (!appendPdgInterproceduralSymbols(pdgLines)) {
+            pdgLines.push(`${name} (${direction}): no inter-procedural symbols reached. ` +
+                `The local PDG statement slice may still report affectedStatements when seeded with line:<N>.`);
+        }
+        // The assembled note carries the local-PDG framing plus the unified
+        // inter-procedural symbol-reach contract; surface it verbatim so the CLI
+        // reader sees the same honesty the JSON consumer does.
+        if (result.note) {
+            pdgLines.push('');
+            pdgLines.push(`ℹ️  ${result.note}`);
+        }
+        else {
+            pdgLines.push('');
+            pdgLines.push('ℹ️  Program Dependence Graph result — statement reach is reported in affectedStatements and inter-procedural symbol reach in interproceduralByDepth/byDepth.');
+        }
+        // Honest incompleteness signals (block-attribution + truncation).
+        if (result.ambiguousProjectionCount > 0) {
+            pdgLines.push(`⚠️  ${result.ambiguousProjectionCount} block(s) could not be attributed to a ` +
+                `unique owning symbol (same-line functions) — all colliding symbols are shown.`);
+        }
+        if (result.unresolvedBlockCount > 0) {
+            pdgLines.push(`⚠️  ${result.unresolvedBlockCount} dependence block(s) map to no owning ` +
+                `Function/Method/Constructor (top-level statement / closure) — surfaced under their file.`);
+        }
+        if (result.truncated) {
+            const by = formatTruncationSuffix(result);
+            pdgLines.push(`⚠️  Truncated${by} — the dependence traversal was bounded; deeper PDG impacts may exist.`);
+        }
+        return pdgLines.join('\n').trim();
+    }
     if (total === 0) {
         // #1858 — "isolated" is a confident claim. If an interface / indirection
         // boundary is on the path, the true count is a lower bound, not zero;
@@ -317,13 +515,20 @@ function formatToolResult(toolName, result) {
 // ─── Next-Step Hints ──────────────────────────────────────────────────
 // Guide the agent to the logical next tool call.
 // Critical for tool chaining: query → context → impact → fix.
-function getNextStepHint(toolName) {
+export function getNextStepHint(toolName, result) {
     switch (toolName) {
         case 'query':
             return '\n---\nNext: Pick a symbol above and run gitnexus-context "<name>" to see all its callers, callees, and execution flows.';
         case 'context':
             return '\n---\nNext: To check what breaks if you change this, run gitnexus-impact "<name>" upstream';
         case 'impact':
+            if (result?.error ||
+                result?.status === 'ambiguous' ||
+                result?.mode === 'pdg' ||
+                result?.pdgLayer ||
+                typeof result?.criterionLine === 'number') {
+                return '';
+            }
             return '\n---\nNext: Review d=1 items first (WILL BREAK). Read the source with cat to understand the code, then make your fix.';
         case 'cypher':
             return '\n---\nNext: To explore a result symbol in depth, run gitnexus-context "<name>"';
@@ -376,6 +581,13 @@ export async function evalServerCommand(options) {
             process.exit(0);
         }, idleTimeoutSec * 1000);
     }
+    // Startup-generated shutdown token: a `POST /shutdown` must present it in the
+    // X-Shutdown-Token header. The local agent that launches the server reads it
+    // from the GITNEXUS_EVAL_SERVER_SHUTDOWN_TOKEN line on fd 1 (next to the READY
+    // signal); a client on another VM under `--host 0.0.0.0` cannot guess it, so it
+    // can no longer kill the server. (SIGINT/SIGTERM and the idle timeout still
+    // shut down locally without a token.)
+    const shutdownToken = crypto.randomBytes(24).toString('hex');
     const server = http.createServer(async (req, res) => {
         resetIdleTimer();
         try {
@@ -388,6 +600,12 @@ export async function evalServerCommand(options) {
             }
             // Shutdown
             if (req.method === 'POST' && req.url === '/shutdown') {
+                if (req.headers['x-shutdown-token'] !== shutdownToken) {
+                    res.setHeader('Content-Type', 'application/json');
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ error: 'forbidden: missing or invalid X-Shutdown-Token' }));
+                    return;
+                }
                 res.setHeader('Content-Type', 'application/json');
                 res.writeHead(200);
                 res.end(JSON.stringify({ status: 'shutting_down' }));
@@ -402,6 +620,12 @@ export async function evalServerCommand(options) {
             const toolMatch = req.url?.match(/^\/tool\/(\w+)$/);
             if (req.method === 'POST' && toolMatch) {
                 const toolName = toolMatch[1];
+                if (!EVAL_SERVER_TOOLS.has(toolName)) {
+                    res.setHeader('Content-Type', 'text/plain');
+                    res.writeHead(400);
+                    res.end(`Error: unsupported tool '${toolName}'. Supported: ${[...EVAL_SERVER_TOOLS].sort().join(', ')}`);
+                    return;
+                }
                 const body = await readBody(req);
                 let args = {};
                 if (body.trim()) {
@@ -418,7 +642,7 @@ export async function evalServerCommand(options) {
                 // Call tool, format result as text, append next-step hint
                 const result = await backend.callTool(toolName, args);
                 const formatted = formatToolResult(toolName, result);
-                const hint = getNextStepHint(toolName);
+                const hint = getNextStepHint(toolName, result);
                 res.setHeader('Content-Type', 'text/plain');
                 res.writeHead(200);
                 res.end(formatted + hint);
@@ -518,6 +742,8 @@ export async function evalServerCommand(options) {
         try {
             // Use fd 1 directly — LadybugDB captures process.stdout (#324)
             writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${displayHost}:${boundPort}\n`);
+            // The launching agent reads this to authorize POST /shutdown.
+            writeSync(1, `GITNEXUS_EVAL_SERVER_SHUTDOWN_TOKEN:${shutdownToken}\n`);
         }
         catch {
             // stdout may not be available (e.g., broken pipe)
@@ -533,6 +759,20 @@ export async function evalServerCommand(options) {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+/**
+ * Tools the eval-server exposes over HTTP — the read-only query surface the
+ * banner advertises. `LocalBackend.callTool` ALSO dispatches write-side / heavier
+ * tools (rename, shape_check, tool_map, …); the allowlist keeps a stray
+ * `POST /tool/<name>` from reaching those through this Docker/eval-harness server.
+ */
+export const EVAL_SERVER_TOOLS = new Set([
+    'query',
+    'context',
+    'impact',
+    'cypher',
+    'detect_changes',
+    'list_repos',
+]);
 export const MAX_BODY_SIZE = 1024 * 1024; // 1MB
 function readBody(req) {
     return new Promise((resolve, reject) => {

package/dist/cli/index.js

@@ -224,6 +224,8 @@ program
     .command('impact [target]')
     .description('Blast radius analysis: what breaks if you change a symbol')
     .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
+    .option('--mode <mode>', 'Engine: callgraph (default) or pdg (opt-in, intra-procedural; needs analyze --pdg)', 'callgraph')
+    .option('--line <number>', '1-based source line — PDG-only statement anchor (--mode pdg): slice the dependence from the statement at this line and show what depends on it')
     .option('-r, --repo <name>', 'Target repository')
     .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')

package/dist/cli/tool.d.ts

@@ -31,6 +31,8 @@ export declare function contextCommand(name: string, options?: {
 }): Promise<void>;
 export declare function impactCommand(target?: string, options?: {
     direction?: string;
+    mode?: string;
+    line?: string;
     repo?: string;
     branch?: string;
     uid?: string;

package/dist/cli/tool.js

@@ -120,12 +120,23 @@ export async function impactCommand(target, options) {
         const rawOffset = parseInt(options?.offset ?? '', 10);
         const parsedLimit = Number.isFinite(rawLimit) ? rawLimit : undefined;
         const parsedOffset = Number.isFinite(rawOffset) ? rawOffset : undefined;
+        // `--line` is a PDG-only statement anchor (1-based source line). Parse it to
+        // an integer when provided and thread it ONLY when present, so the backend's
+        // line-without-pdg / non-positive-integer validation fires on the real value
+        // rather than on a silently-dropped flag. A non-numeric `--line` parses to
+        // NaN, which the backend rejects as a non-positive integer (loud, not silent).
+        const parsedLine = options?.line !== undefined ? parseInt(options.line, 10) : undefined;
         const result = await backend.callTool('impact', {
             target: target || undefined,
             target_uid: options?.uid,
             file_path: options?.file,
             kind: options?.kind,
             direction: options?.direction || 'upstream',
+            // Forward the engine selector; backend validates the enum (callgraph/pdg)
+            // and treats the default 'callgraph' identically to an omitted mode.
+            mode: options?.mode,
+            // PDG-only statement anchor — forwarded only when --line was given.
+            ...(parsedLine !== undefined ? { line: parsedLine } : {}),
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
             repo: options?.repo,

package/dist/core/group/cross-impact.d.ts

@@ -2,7 +2,7 @@
  * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
  * All bridge Cypher for this feature lives in this module.
  */
-import type { GroupImpactResult } from './types.js';
+import type { CrossRepoImpact, GroupImpactResult } from './types.js';
 import type { GroupToolPort } from './service.js';
 /** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
 export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
@@ -79,6 +79,7 @@ export declare function collectImpactSymbolUids(local: unknown, servicePrefix: s
     uids: string[];
     targetFilePath?: string;
 };
+export declare function mergeRisk(localRisk: string, cross: CrossRepoImpact[]): string;
 export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
     error: string;
 }>;

package/dist/core/group/cross-impact.js

@@ -251,7 +251,11 @@ function extractProcessNames(impact) {
         return [];
     return o.affected_processes.map((p) => String(p.name ?? '')).filter(Boolean);
 }
-function mergeRisk(localRisk, cross) {
+// Exported so the U4 PDG-result interchangeability contract (KTD8) can assert
+// permanently that a PDG `risk:'UNKNOWN'` never coalesces to a confident `LOW`.
+// No behavior change — `'UNKNOWN'` was already handled correctly at the
+// `(localRisk === 'LOW' || localRisk === 'UNKNOWN')` branch below.
+export function mergeRisk(localRisk, cross) {
     const highConf = cross.some((c) => c.contract.confidence >= 0.85);
     if (localRisk === 'CRITICAL')
         return 'CRITICAL';

package/dist/core/group/extractors/http-route-extractor.d.ts

@@ -1,5 +1,29 @@
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.js';
+/**
+ * Language-agnostic orchestrator for HTTP route (provider + consumer)
+ * contract extraction. Two strategies, in order of preference per role:
+ *
+ * 1. **Graph-assisted (Strategy A)** — if a per-repo LadybugDB executor
+ *    is available, read `HANDLES_ROUTE` / `FETCHES` Cypher edges that
+ *    the ingestion pipeline already produced via tree-sitter. This is
+ *    the preferred path because the graph has richer symbol metadata
+ *    (real uids, class/method structure, etc.).
+ *
+ * 2. **Source-scan supplement (Strategy B)** — parse files directly with
+ *    the per-language plugin registry in `./http-patterns/`. Used to
+ *    fill gaps when graph extraction only covers part of a polyglot repo
+ *    (e.g. Java graph routes plus Go source-scan routes). Graph entries
+ *    remain authoritative for duplicate contract IDs because they carry
+ *    richer symbol metadata. Each plugin owns its tree-sitter grammar
+ *    and query sources — this orchestrator imports NO grammars or query
+ *    strings.
+ *
+ * Adding a new language for Strategy B is a one-file edit in
+ * `http-patterns/index.ts`: register a new `HttpLanguagePlugin` and
+ * widen `HTTP_SCAN_GLOB` if needed.
+ */
+export declare const HANDLES_ROUTE_QUERY = "\nMATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)\nRETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,\n       route.name AS routePath, route.id AS routeId,\n       route.method AS routeMethod,\n       route.responseKeys AS responseKeys,\n       r.reason AS routeSource";
 /**
  * Canonicalize a provider-side HTTP path for contract-id generation:
  *   - strip query string

package/dist/core/group/extractors/http-route-extractor.js

@@ -4,6 +4,7 @@ import Parser from 'tree-sitter';
 import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import { readSafe } from './fs-utils.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
+import { logger } from '../../logger.js';
 import { getPluginForFile, HTTP_SCAN_GLOB, } from './http-patterns/index.js';
 /**
  * Language-agnostic orchestrator for HTTP route (provider + consumer)
@@ -29,10 +30,14 @@ import { getPluginForFile, HTTP_SCAN_GLOB, } from './http-patterns/index.js';
  * widen `HTTP_SCAN_GLOB` if needed.
  */
 // ─── Graph-assisted queries ──────────────────────────────────────────
-const HANDLES_ROUTE_QUERY = `
+// Exported so integration tests can run the exact production query against a
+// real LadybugDB (guards the Route.method column contract — see
+// route-method-roundtrip.test.ts).
+export const HANDLES_ROUTE_QUERY = `
 MATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)
 RETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,
        route.name AS routePath, route.id AS routeId,
+       route.method AS routeMethod,
        route.responseKeys AS responseKeys,
        r.reason AS routeSource`;
 const FETCHES_QUERY = `
@@ -273,14 +278,26 @@ export class HttpRouteExtractor {
         try {
             rows = await db(HANDLES_ROUTE_QUERY);
         }
-        catch {
+        catch (err) {
+            // A failure here silently disables the entire graph-assisted HTTP
+            // provider path (the source-scan fallback still runs and masks most
+            // of the damage), so surface it at debug level to make a total
+            // outage observable instead of invisible.
+            logger.debug(`[http-route-extractor] HANDLES_ROUTE query failed; graph providers skipped: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
         for (const row of rows) {
             const filePath = String(row.filePath ?? '');
             const routePath = String(row.routePath ?? '');
             const routeSource = String(row.routeSource ?? row.routeReason ?? '');
-            let method = methodFromRouteReason(routeSource);
+            // Prefer the HTTP verb persisted on the Route node by the ingestion
+            // routes phase (Spring/Laravel framework routes and decorator routes
+            // carry it). Fall back to parsing it out of the edge reason for
+            // older indexes or filesystem routes that never stored a method.
+            const graphMethod = String(row.routeMethod ?? '')
+                .trim()
+                .toUpperCase();
+            let method = (graphMethod || null) ?? methodFromRouteReason(routeSource);
             // Look up handler name (and backfill method if missing) from the
             // plugin's scan of the handler file. This replaces the old
             // regex-based `inferMethodFromFileScan` and `pickJavaHandlerName`
@@ -396,7 +413,8 @@ export class HttpRouteExtractor {
         try {
             rows = await db(FETCHES_QUERY);
         }
-        catch {
+        catch (err) {
+            logger.debug(`[http-route-extractor] FETCHES query failed; graph consumers skipped: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
         for (const row of rows) {

package/dist/core/incremental/subgraph-extract.js

@@ -57,7 +57,13 @@ const isGraphWide = (label) => label === 'Community' || label === 'Process';
  * A→C edge. These are always extracted (and the orchestrator delete-alls them
  * first, like Community/Process) so they rebuild from the fresh graph.
  */
-const isGraphWideRelType = (type) => type === 'TAINT_PATH';
+// `CALL_SUMMARY` (PDG FU-C) is intra-procedural (a callee's RETURN-VALUE ASCENT
+// depends only on its OWN body), but the orchestrator delete-alls it on an
+// incremental `--pdg` writeback to keep the emit path single — so it must be
+// re-included from the FULL fresh graph (which the emit phase recomputes every
+// run) or an unchanged function's summary would be lost. Cheap: one self-loop
+// edge per return-flowing function.
+const isGraphWideRelType = (type) => type === 'TAINT_PATH' || type === 'CALL_SUMMARY';
 /**
  * Build a Map<nodeId, filePath> for every File-bound node in the graph.
  * Graph-wide nodes (Community/Process) have no filePath and are filtered.