gitnexus 1.6.8-rc.6 → 1.6.8-rc.7

package/dist/cli/analyze-config.js

@@ -78,6 +78,12 @@ const KEY_SPECS = {
     embeddingBatchSize: { target: 'embeddingBatchSize', kind: 'numeric-string' },
     embeddingSubBatchSize: { target: 'embeddingSubBatchSize', kind: 'numeric-string' },
     embeddingDevice: { target: 'embeddingDevice', kind: 'string' },
+    // #1589/#1852 residual — extra fetch-wrapper function names to treat as HTTP
+    // consumers. The auto-detector only flags functions that call the bare global
+    // `fetch()`; a wrapper built on axios / a custom client, or named outside the
+    // built-in convention set, is otherwise invisible to route_map consumers.
+    // Listing it here adds it to the cross-file consumer scan.
+    fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
 };
 /** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
 const NESTED_KEY = 'analyze';
@@ -195,6 +201,39 @@ const normalizeValue = (kind, value, key) => {
             }
             return trimmed;
         }
+        case 'string-array': {
+            // Generic shared validator — `source` already names the config key, so
+            // messages here stay key-agnostic (no fetch-wrapper coupling in the
+            // shared normalizer; #1589/#1852 review F7).
+            if (!Array.isArray(value)) {
+                throw new GitNexusRcError(`${source} must be an array of strings.`);
+            }
+            const names = [];
+            for (const item of value) {
+                if (typeof item !== 'string') {
+                    throw new GitNexusRcError(`${source} entries must all be strings.`);
+                }
+                const trimmed = item.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} entries must not be empty.`);
+                }
+                assertNoHiddenChars(trimmed, source);
+                // Values may be interpolated into a RegExp downstream. Restrict to
+                // identifier / member-access shapes so a config value can never smuggle
+                // regex metacharacters into a consumer.
+                if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(trimmed)) {
+                    throw new GitNexusRcError(`${source} entry "${trimmed}" must be an identifier or member name ` +
+                        `(letters, digits, _, $, . — e.g. "client.get").`);
+                }
+                names.push(trimmed);
+            }
+            if (names.length === 0) {
+                throw new GitNexusRcError(`${source} must list at least one string.`);
+            }
+            // De-duplicate and cap to a sane bound so a pathological config cannot
+            // blow up the consumer scan's alternation.
+            return Array.from(new Set(names)).slice(0, 100);
+        }
         case 'numeric-string': {
             // Mirror Commander's contract: these options reach the existing CLI
             // validation as strings. Accept a JSON number or a string; normalize to a

package/dist/cli/analyze.d.ts

@@ -101,6 +101,14 @@ export interface AnalyzeOptions {
     embeddingBatchSize?: string;
     embeddingSubBatchSize?: string;
     embeddingDevice?: string;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers (#1589/#1852
+     * residual). Supplied via `.gitnexusrc` `fetchWrappers: [...]`. Threaded into
+     * the routes phase, where the cross-file consumer scan unions them with the
+     * auto-detected `fetch()` wrappers so a custom/axios-based wrapper named
+     * outside the built-in convention still produces `route_map` consumers.
+     */
+    fetchWrappers?: string[];
 }
 /**
  * Whether the post-index skill step should run.

package/dist/cli/analyze.js

@@ -864,6 +864,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.
             workerPoolSize,
+            // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
+            // forwarded to the routes phase consumer scan.
+            fetchWrappers: options.fetchWrappers,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);

package/dist/cli/eval-server.js

@@ -155,7 +155,43 @@ export function formatImpactResult(result) {
     const direction = result.direction;
     const byDepth = result.byDepth || {};
     const total = result.impactedCount || 0;
+    // #2129 — an ambiguous bare name must not print the "isolated / safe to
+    // refactor" headline. Surface the per-candidate blast radius + the maximum,
+    // 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') {
+        // #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;
+        const total = result.totalCandidates ?? shown;
+        const countPhrase = total > shown ? `${total} symbols (showing ${shown})` : `${total} symbols`;
+        const lines = [
+            `${target?.name || '?'}: AMBIGUOUS — ${countPhrase} share this name. ` +
+                `Max blast radius ${result.maxImpactedCount ?? 0} (${result.maxRisk ?? 'UNKNOWN'} risk). ` +
+                `Disambiguate with --uid for one authoritative result:`,
+        ];
+        for (const c of result.candidates || []) {
+            lines.push(`  ${c.kind} ${c.name} → ${c.filePath}:${c.line || '?'}  ` +
+                `[${c.impactedCount ?? 0} ${direction}, risk ${c.risk ?? 'UNKNOWN'}]  (uid: ${c.uid})`);
+        }
+        // #2129 review F1 — a failed per-candidate probe makes the max a lower bound.
+        if (result.partialProbe) {
+            lines.push('  ⚠️  One or more candidate probes failed — max blast radius / risk are lower bounds.');
+        }
+        return lines.join('\n');
+    }
     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;
+        // callers binding via DI / dynamic dispatch were not traced. Say so instead.
+        if (result.epistemic === 'lower-bound') {
+            const lines = [
+                `${target?.name || '?'}: no direct ${direction} dependencies traced, but this is a LOWER BOUND — unresolved indirection on the path (actual impact may be higher):`,
+            ];
+            for (const b of result.boundaries || [])
+                lines.push(`    • ${b}`);
+            return lines.join('\n');
+        }
         return `${target?.name || '?'}: No ${direction} dependencies found. This symbol appears isolated.`;
     }
     const lines = [];
@@ -164,6 +200,13 @@ export function formatImpactResult(result) {
     if (result.partial) {
         lines.push('⚠️  Partial results — graph traversal was interrupted. Deeper impacts may exist.');
     }
+    // #1858 — an interface / indirection boundary on the path makes this a lower
+    // bound; surface it so the count is not read as exhaustive.
+    if (result.epistemic === 'lower-bound') {
+        lines.push('⚠️  Lower bound — unresolved indirection on the path (callers binding via DI / dynamic dispatch are not traced; actual impact may be higher):');
+        for (const b of result.boundaries || [])
+            lines.push(`    • ${b}`);
+    }
     lines.push('');
     const depthLabels = {
         1: 'WILL BREAK (direct)',

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

@@ -297,22 +297,72 @@ export const routesPhase = {
         // scan JS/TS consumer files for calls to those wrapper functions with
         // URL-like string arguments and add them to allFetchCalls so
         // processNextjsFetchRoutes can create FETCHES edges.
-        if (allFetchWrapperDefs && allFetchWrapperDefs.length > 0 && routeRegistry.size > 0) {
-            const wrapperNames = new Set(allFetchWrapperDefs.map((d) => d.functionName));
+        // Wrapper names come from two sources: functions the parse phase
+        // auto-detected as calling the bare global `fetch()`, plus any names the
+        // user declared in `.gitnexusrc` `fetchWrappers` (#1589/#1852 residual).
+        // Config names let an axios/custom-client wrapper — or one named outside the
+        // built-in convention — still produce route_map consumers; without them it
+        // silently falls back to `consumers: []`. Configured names alone are enough
+        // to run the scan even when nothing was auto-detected.
+        // Configured names are already validated/trimmed/de-duped/capped by
+        // analyze-config.ts — trusted as-is (#1589/#1852 review F9, dropped the
+        // redundant re-trim/re-filter). The single filter below guards only the
+        // auto-detected `functionName`s, which have no shape guarantee.
+        const configuredWrappers = ctx.options?.fetchWrappers ?? [];
+        const wrapperNames = new Set([...(allFetchWrapperDefs ?? []).map((d) => d.functionName), ...configuredWrappers].filter((n) => typeof n === 'string' && n.trim().length > 0));
+        if (wrapperNames.size > 0 && routeRegistry.size > 0) {
             const jsFiles = allPaths.filter((p) => /\.[jt]sx?$/.test(p));
-            if (jsFiles.length > 0 && wrapperNames.size > 0) {
-                const jsContents = await readFileContents(ctx.repoPath, jsFiles);
-                for (const [filePath, content] of jsContents) {
-                    for (const name of wrapperNames) {
-                        const regex = new RegExp(`\\b${escapeRegex(name)}\\s*\\(\\s*['"\`](/[^'"\`\\s)]+)['"\`]`, 'g');
-                        let match;
-                        while ((match = regex.exec(content)) !== null) {
-                            allFetchCalls.push({
-                                filePath,
-                                fetchURL: match[1],
-                                lineNumber: content.substring(0, match.index).split('\n').length,
-                            });
+            if (jsFiles.length > 0) {
+                // Reuse contents already read for handler extraction; only read the
+                // remainder (mirrors the Expo block above). Avoids a second full read of
+                // files we already have in memory.
+                const unreadJsFiles = jsFiles.filter((p) => !handlerContents?.has(p));
+                const extraContents = unreadJsFiles.length > 0
+                    ? await readFileContents(ctx.repoPath, unreadJsFiles)
+                    : new Map();
+                // One alternation regex over every wrapper name per file — O(files), not
+                // O(files × wrappers) (#1852 review F3). Names are escaped and grouped
+                // non-capturing so capture group 1 stays the URL. The left boundary is a
+                // negative lookbehind, not `\b`: a bare configured name like `get` must
+                // match the free call `get('/x')` but NOT a member access `client.get(`
+                // (a `.get(` on an unrelated object), and `apiFetch` must not match
+                // `myApiFetch`. Member-style wrappers are configured with the dot
+                // (`client.get`), where the `.` is part of the pattern. The `u` flag +
+                // Unicode property classes make the boundary cover non-ASCII identifier
+                // characters too — ASCII `\w` would let `caféget('/x')` match `get`
+                // (#1852 review F10).
+                const alternation = [...wrapperNames].map(escapeRegex).join('|');
+                const wrapperCallRegex = new RegExp(`(?<![.\\p{L}\\p{N}_$])(?:${alternation})\\s*\\(\\s*['"\`](/[^'"\`\\s)]+)['"\`]`, 'gu');
+                const scanContent = (filePath, content) => {
+                    wrapperCallRegex.lastIndex = 0;
+                    // 1-based line number via a running newline counter: matches arrive in
+                    // ascending index, so accumulate newlines incrementally instead of
+                    // re-allocating `content.substring(0, match.index).split('\n')` on
+                    // every match (#1852 review F12). Output is identical.
+                    let line = 1;
+                    let scanned = 0;
+                    let match;
+                    while ((match = wrapperCallRegex.exec(content)) !== null) {
+                        for (; scanned < match.index; scanned++) {
+                            if (content.charCodeAt(scanned) === 10 /* '\n' */)
+                                line++;
                         }
+                        allFetchCalls.push({
+                            filePath,
+                            fetchURL: match[1],
+                            lineNumber: line,
+                        });
+                    }
+                };
+                for (const [filePath, content] of extraContents)
+                    scanContent(filePath, content);
+                // Also scan already-read JS/TS handler files (a handler can itself
+                // consume another route through a wrapper).
+                if (handlerContents) {
+                    for (const p of jsFiles) {
+                        const cached = handlerContents.get(p);
+                        if (cached !== undefined)
+                            scanContent(p, cached);
                     }
                 }
             }

package/dist/core/ingestion/pipeline.d.ts

@@ -104,6 +104,15 @@ export interface PipelineOptions {
      * `process.env` state across invocations. When undefined, the env var decides.
      */
     keepLocalValueSymbols?: boolean;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers, threaded
+     * from `.gitnexusrc` `fetchWrappers` via `AnalyzeOptions` (#1589/#1852
+     * residual). The routes phase unions these with the auto-detected `fetch()`
+     * wrappers when scanning for `route_map` consumers, so a wrapper named outside
+     * the built-in convention (or built on axios / a custom client) is still
+     * traced. Empty/undefined leaves behavior unchanged.
+     */
+    fetchWrappers?: readonly string[];
 }
 /**
  * All pipeline phases with their dependency relationships.

package/dist/core/run-analyze.d.ts

@@ -88,6 +88,13 @@ export interface AnalyzeOptions {
      * removed); `undefined` defers to the env / auto-formula fallback.
      */
     workerPoolSize?: number;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers, forwarded to
+     * `PipelineOptions.fetchWrappers` (#1589/#1852 residual). Sourced from the CLI
+     * `.gitnexusrc` `fetchWrappers` list. `undefined`/empty leaves the route
+     * consumer scan unchanged.
+     */
+    fetchWrappers?: string[];
 }
 export interface AnalyzeResult {
     repoName: string;

package/dist/core/run-analyze.js

@@ -416,6 +416,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }, {
         parseCache,
         workerPoolSize: options.workerPoolSize,
+        fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');

package/dist/mcp/local/local-backend.d.ts

@@ -16,6 +16,15 @@ export declare function isTestFilePath(filePath: string): boolean;
 export declare const VALID_NODE_LABELS: Set<string>;
 /** Valid relation types for impact analysis filtering */
 export declare const VALID_RELATION_TYPES: Set<string>;
+/**
+ * Relation types the #1858 epistemic-boundary probe keys on. Kept as
+ * module-level `readonly` arrays (not Sets) because computeEpistemicBoundary
+ * binds them as Cypher query params (`r.type IN $heritage` / `IN $types`).
+ * The heritage set is exactly the IMPACT_RELATION_CONFIDENCE 0.85 tier —
+ * "statically verifiable, but the concrete binding past it is not".
+ */
+export declare const EPISTEMIC_HERITAGE_RELATION_TYPES: readonly string[];
+export declare const EPISTEMIC_CONSUMER_RELATION_TYPES: readonly string[];
 /**
  * Per-relation-type confidence floor for impact analysis.
  *
@@ -431,6 +440,28 @@ export declare class LocalBackend {
     private rename;
     private impact;
     private _impactImpl;
+    /**
+     * #1858 — epistemic lower-bound detection.
+     *
+     * impact()/context() traverse only edges materialized in the graph. When the
+     * queried symbol sits on an interface / abstract boundary, callers that bind
+     * to the interface via DI, a container, or dynamic dispatch — rather than
+     * naming the concrete symbol — are not traced. The reported count is then a
+     * lower bound, not an exact figure. Instead of returning a confident count
+     * that silently omits those callers, annotate the result with
+     * `epistemic: 'lower-bound'` plus a human-readable boundary note. A fully
+     * resolved leaf with no indirection stays `epistemic: 'exact'`.
+     *
+     * Aligns with the numeric confidence model rather than the long-deleted
+     * TIER_CONFIDENCE enum: the heritage/indirection edges this keys on
+     * (IMPLEMENTS / METHOD_IMPLEMENTS / EXTENDS) carry the 0.85
+     * `IMPACT_RELATION_CONFIDENCE` floor — "statically verifiable, but the
+     * concrete binding past it is not".
+     *
+     * Never throws: on query error it returns 'exact', so it can only add signal,
+     * never suppress a result.
+     */
+    private computeEpistemicBoundary;
     /**
      * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
      */

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

@@ -96,12 +96,32 @@ export const VALID_RELATION_TYPES = new Set([
     'OVERRIDES', // Legacy alias — dual-read for pre-rename indexes
     'METHOD_IMPLEMENTS',
     'ACCESSES',
+    // Emitted by emit-references.ts / scope-resolution/graph-bridge/edges.ts and
+    // already part of the default impact relTypes + context() incoming queries.
+    // It was missing from this allowlist, so `impact({relationTypes:['USES']})`
+    // silently filtered to [] and fell back to the full default traversal
+    // (#2129/#1858 review F5). No IMPACT_RELATION_CONFIDENCE floor → 0.5 fallback,
+    // matching the FETCHES / WRAPS / HANDLES_ROUTE precedent below.
+    'USES',
     'HANDLES_ROUTE',
     'FETCHES',
     'HANDLES_TOOL',
     'ENTRY_POINT_OF',
     'WRAPS',
 ]);
+/**
+ * Relation types the #1858 epistemic-boundary probe keys on. Kept as
+ * module-level `readonly` arrays (not Sets) because computeEpistemicBoundary
+ * binds them as Cypher query params (`r.type IN $heritage` / `IN $types`).
+ * The heritage set is exactly the IMPACT_RELATION_CONFIDENCE 0.85 tier —
+ * "statically verifiable, but the concrete binding past it is not".
+ */
+export const EPISTEMIC_HERITAGE_RELATION_TYPES = [
+    'IMPLEMENTS',
+    'METHOD_IMPLEMENTS',
+    'EXTENDS',
+];
+export const EPISTEMIC_CONSUMER_RELATION_TYPES = ['CALLS', 'USES', 'ACCESSES'];
 /**
  * Per-relation-type confidence floor for impact analysis.
  *
@@ -2100,6 +2120,23 @@ export class LocalBackend {
         // Method/Function/Constructor enrichment: fetch method-specific properties
         const symKind = isClassLike ? resolvedLabel || 'Class' : sym.type || sym[2];
         const isMethodLike = symKind === 'Method' || symKind === 'Function' || symKind === 'Constructor';
+        // #1858 review F2 — start the epistemic boundary probe here (right after
+        // `symKind` is known) so it runs CONCURRENTLY with the methodMetadata fetch
+        // below, mirroring how _runImpactBFS overlaps it with the BFS. It is awaited
+        // at result assembly. (It cannot start earlier — `symKind` is only computed
+        // on this line, after the incoming/outgoing round-trips.)
+        //
+        // #1858 review F3 — pass an interface-preserving type, NOT `symKind`.
+        // `symKind` collapses a single-resolved Interface to 'Class' (resolvedLabel
+        // is '' on the single-candidate path), which would skip computeEpistemicBoundary's
+        // `symType === 'Interface'` self-boundary branch and under-report a leaf
+        // interface as 'exact'. `enrichCandidateLabels` runs BEFORE the single-candidate
+        // early return and patches `sym.type` from '' to 'Interface' (LadybugDB returns
+        // '' for labels()[0] on Interface/Class), so `sym.type` is the reliable signal
+        // here — mirroring impact()'s `resolvedLabel || symbol.type` derivation. Do not
+        // "fix" enrichment ordering; F3 depends on enrichment-before-early-return.
+        const epistemicSymType = (resolvedLabel || sym.type || symKind || '');
+        const epistemicPromise = this.computeEpistemicBoundary(repo, symId, epistemicSymType, (sym.name || sym[1]));
         let methodMetadata;
         if (isMethodLike) {
             try {
@@ -2130,6 +2167,12 @@ export class LocalBackend {
                 /* method metadata unavailable — omit silently */
             }
         }
+        // #1858 — same epistemic boundary signal as impact(): when this symbol sits
+        // behind an interface / indirection boundary, callers binding via DI or
+        // dynamic dispatch are not reflected in `incoming`, so the view is a lower
+        // bound. Additive; never suppresses a field. Resolved from the probe started
+        // above (concurrent with methodMetadata).
+        const epistemic = await epistemicPromise;
         return {
             status: 'found',
             symbol: {
@@ -2142,6 +2185,7 @@ export class LocalBackend {
                 ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
                 ...(methodMetadata ? { methodMetadata } : {}),
             },
+            ...epistemic,
             incoming: categorize(incomingRows),
             outgoing: categorize(outgoingRows),
             ...(typedPropertyRows.length > 0
@@ -2675,21 +2719,103 @@ export class LocalBackend {
             };
         }
         if (outcome.kind === 'ambiguous') {
-            return {
-                status: 'ambiguous',
-                message: `Found ${outcome.candidates.length} symbols matching '${target}'. Use target_uid, file_path, or kind to disambiguate.`,
-                target: { name: target },
-                direction,
-                impactedCount: 0,
-                risk: 'UNKNOWN',
-                candidates: outcome.candidates.map((c) => ({
+            // #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
+            // under-report the "run impact before editing" workflow exists to prevent
+            // (the dropped caller calls a *different* same-name node, so it never shows
+            // up against the one the resolver happened to pick). Run a bounded,
+            // 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
+            // one or more per-candidate probes threw, so maxRisk / maxImpactedCount
+            // are lower bounds over the probes that succeeded (a failed candidate must
+            // not be masked by a benign sibling success).
+            let probeFailed = false;
+            const candidateSummaries = await Promise.all(probed.map(async (c) => {
+                const cType = c.type || '';
+                const cRelTypes = (cType === 'Class' || cType === 'Interface') &&
+                    !hasExplicitRelationTypes &&
+                    !relationTypes.includes('ACCESSES')
+                    ? [...relationTypes, 'ACCESSES']
+                    : relationTypes;
+                // #1858/#2129 review F8 — name the shape the probe summary is read
+                // through (`_runImpactBFS` returns `Promise<any>`, so this is the
+                // narrowing cast) so a future rename of those fields fails tsc instead
+                // of silently zeroing candidate counts.
+                let summary = null;
+                try {
+                    summary = await this._runImpactBFS(repo, { id: c.id, name: c.name, filePath: c.filePath }, cType, direction, {
+                        maxDepth,
+                        relationTypes: cRelTypes,
+                        includeTests,
+                        minConfidence,
+                        summaryOnly: true,
+                        skipEpistemic: true,
+                        skipEnrichment: true,
+                    });
+                }
+                catch (e) {
+                    probeFailed = true;
+                    logQueryError('impact:ambiguous-candidate', e);
+                }
+                return {
                     uid: c.id,
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
                     line: c.startLine,
                     score: Number(c.score.toFixed(2)),
-                })),
+                    impactedCount: summary?.impactedCount ?? 0,
+                    risk: summary?.risk ?? 'UNKNOWN',
+                    direct: summary?.summary?.direct ?? 0,
+                };
+            }));
+            // Rank by blast radius so the most-impactful interpretation is first, and
+            // hoist the maximum count/risk to the top level so the response cannot be
+            // misread as "no impact".
+            candidateSummaries.sort((a, b) => b.impactedCount - a.impactedCount);
+            const maxImpactedCount = candidateSummaries.reduce((m, c) => Math.max(m, c.impactedCount), 0);
+            const RISK_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+            // If EVERY candidate probe failed (all 'UNKNOWN' — e.g. pool exhaustion
+            // under the fan-out), the worst real risk is genuinely unknown, not LOW.
+            // Reporting LOW here would re-introduce the false-safe signal. Only fall to
+            // the LOW seed when at least one candidate produced a real risk.
+            const anyKnownRisk = candidateSummaries.some((c) => RISK_ORDER.includes(c.risk));
+            const maxRisk = anyKnownRisk
+                ? candidateSummaries.reduce((worst, c) => (RISK_ORDER.indexOf(c.risk) > RISK_ORDER.indexOf(worst) ? c.risk : worst), 'LOW')
+                : 'UNKNOWN';
+            const truncated = outcome.candidates.length > probed.length;
+            return {
+                status: 'ambiguous',
+                message: `Found ${outcome.candidates.length} symbols matching '${target}'` +
+                    (truncated
+                        ? ` (showing ${candidateSummaries.length} of ${outcome.candidates.length})`
+                        : '') +
+                    `. Blast radius differs per candidate (max ${maxImpactedCount} impacted at risk ${maxRisk}). ` +
+                    `Disambiguate with target_uid (or file_path/kind) for a single authoritative result.`,
+                target: { name: target },
+                direction,
+                // Full match count — `candidates[]` is truncated to AMBIGUOUS_MAX_CANDIDATES,
+                // so consumers (CLI formatter) need this to report "N of M" honestly (#2129
+                // review F11; the CLI previously read the truncated array length).
+                totalCandidates: outcome.candidates.length,
+                // `impactedCount` stays 0 and `risk` stays UNKNOWN — there is no single
+                // resolved symbol, and UNKNOWN must NOT read as "safe to refactor". The
+                // real blast radius is surfaced per-candidate plus `maxImpactedCount` /
+                // `maxRisk` so a real caller can never hide behind the ambiguous zero
+                // (#2129).
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                maxImpactedCount,
+                maxRisk,
+                ...(probeFailed ? { partialProbe: true } : {}),
+                ...(truncated && { candidatesTruncated: true }),
+                candidates: candidateSummaries,
             };
         }
         const sym = {
@@ -2713,12 +2839,109 @@ export class LocalBackend {
             summaryOnly: params.summaryOnly,
         });
     }
+    /**
+     * #1858 — epistemic lower-bound detection.
+     *
+     * impact()/context() traverse only edges materialized in the graph. When the
+     * queried symbol sits on an interface / abstract boundary, callers that bind
+     * to the interface via DI, a container, or dynamic dispatch — rather than
+     * naming the concrete symbol — are not traced. The reported count is then a
+     * lower bound, not an exact figure. Instead of returning a confident count
+     * that silently omits those callers, annotate the result with
+     * `epistemic: 'lower-bound'` plus a human-readable boundary note. A fully
+     * resolved leaf with no indirection stays `epistemic: 'exact'`.
+     *
+     * Aligns with the numeric confidence model rather than the long-deleted
+     * TIER_CONFIDENCE enum: the heritage/indirection edges this keys on
+     * (IMPLEMENTS / METHOD_IMPLEMENTS / EXTENDS) carry the 0.85
+     * `IMPACT_RELATION_CONFIDENCE` floor — "statically verifiable, but the
+     * concrete binding past it is not".
+     *
+     * Never throws: on query error it returns 'exact', so it can only add signal,
+     * never suppress a result.
+     */
+    async computeEpistemicBoundary(repo, symId, symType, symName) {
+        const HERITAGE_TYPES = EPISTEMIC_HERITAGE_RELATION_TYPES;
+        const CONSUMER_TYPES = EPISTEMIC_CONSUMER_RELATION_TYPES;
+        try {
+            // Discover the interface / abstract supertypes on the target's boundary.
+            // If the target is itself an interface, it is its own boundary node.
+            const boundary = new Map();
+            if (symType === 'Interface') {
+                boundary.set(symId, { name: symName || '', label: 'Interface' });
+            }
+            const ifaceRows = await executeParameterized(repo.lbugPath, `MATCH (x)-[r:CodeRelation]->(iface)
+         WHERE x.id = $symId AND r.type IN $heritage
+         RETURN DISTINCT iface.id AS id, iface.name AS name, labels(iface)[0] AS label
+         LIMIT 25`, { symId, heritage: HERITAGE_TYPES }).catch(() => []);
+            for (const r of ifaceRows) {
+                const id = (r.id ?? r[0]);
+                if (id && !boundary.has(id)) {
+                    boundary.set(id, {
+                        name: (r.name ?? r[1] ?? ''),
+                        label: (r.label ?? r[2] ?? 'Interface'),
+                    });
+                }
+            }
+            if (boundary.size === 0)
+                return { epistemic: 'exact' };
+            const ifaceIds = Array.from(boundary.keys());
+            // Count per interface id with scalar equality. A parameterized
+            // `iface.id IN $ids` combined with `COUNT(DISTINCT ...)` + implicit
+            // group-by returns no rows under the LadybugDB cypher subset, so query
+            // each boundary node individually (boundary is small — capped at 25).
+            const countByType = async (types) => {
+                const m = new Map();
+                await Promise.all(ifaceIds.map(async (ifaceId) => {
+                    const rows = await executeParameterized(repo.lbugPath, `MATCH (other)-[r:CodeRelation]->(iface)
+               WHERE iface.id = $ifaceId AND r.type IN $types
+               RETURN COUNT(DISTINCT other.id) AS cnt`, { ifaceId, types }).catch(() => []);
+                    const cnt = rows.length > 0 ? Number(rows[0].cnt ?? rows[0][0] ?? 0) : 0;
+                    m.set(ifaceId, cnt);
+                }));
+                return m;
+            };
+            const [implCounts, consumerCounts] = await Promise.all([
+                countByType(HERITAGE_TYPES),
+                countByType(CONSUMER_TYPES),
+            ]);
+            const boundaries = [];
+            for (const [id, info] of boundary) {
+                const impls = implCounts.get(id) ?? 0;
+                const consumers = consumerCounts.get(id) ?? 0;
+                // Flag only a genuine indirection risk: an interface that is actually
+                // consumed (callers bind to it) or that has multiple implementations
+                // (runtime dispatch is ambiguous). A concrete type implementing an
+                // interface nothing references is fully traced → stays exact.
+                if (consumers >= 1 || impls >= 2) {
+                    const label = (info.label || 'Interface').toLowerCase();
+                    const name = info.name || '(unnamed)';
+                    const article = /^[aeiou]/.test(label) ? 'an' : 'a';
+                    const parts = [];
+                    if (impls >= 1)
+                        parts.push(`${impls} ${impls === 1 ? 'implementation' : 'implementations'}`);
+                    if (consumers >= 1)
+                        parts.push(`${consumers} interface-level ${consumers === 1 ? 'consumer' : 'consumers'}`);
+                    boundaries.push(`${name} is ${article} ${label} with ${parts.join(' and ')}; callers that bind via the ${label} ` +
+                        `(e.g. a DI container or dynamic dispatch) are not traced to the concrete symbol — ` +
+                        `actual impact may be higher.`);
+                }
+            }
+            if (boundaries.length === 0)
+                return { epistemic: 'exact' };
+            return { epistemic: 'lower-bound', boundaries };
+        }
+        catch {
+            return { epistemic: 'exact' };
+        }
+    }
     /**
      * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
      */
     async _runImpactBFS(repo, sym, symType, direction, opts) {
         const { maxDepth, relationTypes, includeTests, minConfidence } = opts;
         const skipPerSymbolEnrichment = opts.skipPerSymbolEnrichment ?? false;
+        const skipEnrichment = opts.skipEnrichment ?? false;
         const hasExplicitLimit = typeof opts.limit === 'number' && Number.isFinite(opts.limit);
         const paginationLimit = hasExplicitLimit
             ? Math.max(1, Math.min(Math.trunc(opts.limit), 10000))
@@ -2735,6 +2958,18 @@ export class LocalBackend {
         const safeMinConfidence = Number.isFinite(minConfidence) ? minConfidence : 0;
         const confidenceFilter = safeMinConfidence > 0 ? ' AND r.confidence >= $minConfidence' : '';
         const symId = sym.id || sym[0];
+        // #1858 — kick off the epistemic boundary probe concurrently with the BFS.
+        // It depends only on symId/symType/symName (all known now) and touches no
+        // shared state, so its extra round-trip overlaps the traversal instead of
+        // adding to the serial path. `skipEpistemic` (ambiguous #2129 candidate
+        // probes, group fan-out) resolves to no field, preserving prior behavior.
+        // #1858/#2129 review F8 — the skip case adds no field, so `epistemic` is
+        // optional here (the union's `{}` subtype). computeEpistemicBoundary's own
+        // return keeps `epistemic` REQUIRED — only this promise widens to the skip
+        // subtype.
+        const epistemicPromise = opts.skipEpistemic
+            ? Promise.resolve({})
+            : this.computeEpistemicBoundary(repo, symId, symType, (sym.name || sym[1]));
         const impacted = [];
         const visited = new Set([symId]);
         let frontier = [symId];
@@ -2872,7 +3107,13 @@ export class LocalBackend {
         // Max number of chunks to process to avoid unbounded DB round-trips.
         // Configurable via env IMPACT_MAX_CHUNKS, default 10 => max items = 1000
         const MAX_CHUNKS = parseInt(process.env.IMPACT_MAX_CHUNKS || '10', 10);
-        if (impacted.length > 0) {
+        // `skipEnrichment` (ambiguous #2129 per-candidate probes) bypasses the
+        // process/module aggregation passes entirely — those probes need only the
+        // count + a count-based risk, so paying the bounded-but-real enrichment cost
+        // ~6× per ambiguous call is wasted. risk then derives from directCount /
+        // total only (processCount/moduleCount stay 0), an acceptable approximation
+        // for a disambiguation aid.
+        if (impacted.length > 0 && !skipEnrichment) {
             // ── Process enrichment: batched chunking (bounded by MAX_CHUNKS) ─
             // Uses merged Cypher query (WITH + OPTIONAL MATCH) to fetch
             // process + entry point info in 1 round-trip per chunk. Converted to
@@ -3093,6 +3334,9 @@ export class LocalBackend {
         for (const [depth, items] of Object.entries(grouped)) {
             byDepthCounts[Number(depth)] = items.length;
         }
+        // #1858 — await the epistemic boundary probe kicked off alongside the BFS
+        // above. Additive: leaves impactedCount and every existing field untouched.
+        const epistemic = await epistemicPromise;
         const base = {
             target: {
                 id: symId,
@@ -3103,6 +3347,7 @@ export class LocalBackend {
             direction,
             impactedCount: impacted.length,
             risk,
+            ...epistemic,
             ...(!traversalComplete && { partial: true }),
             summary: {
                 direct: directCount,
@@ -3292,6 +3537,10 @@ export class LocalBackend {
                 includeTests: opts.includeTests,
                 minConfidence: opts.minConfidence,
                 skipPerSymbolEnrichment: true,
+                // Group cross-repo fan-out consumes only byDepth (cross-impact.ts), not
+                // the #1858 epistemic/boundaries fields — computing them per neighbor is
+                // dead work on the highest-volume path, so suppress them here too.
+                skipEpistemic: true,
             });
         }
         catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.6",
+  "version": "1.6.8-rc.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",