gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

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

@@ -17,7 +17,7 @@ import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/l
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
 import { parseDiffHunks, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
 import { realpathSync } from 'fs';
-import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
+import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, getStoragePaths, loadMeta, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
@@ -27,7 +27,22 @@ 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, } from '../tools.js';
+import { findImportCycles } from '../../core/graph/import-cycles.js';
+import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
+import { EXTENSIONS } from '../../core/ingestion/import-resolvers/utils.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));
+}
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -96,12 +111,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.
  *
@@ -315,6 +350,12 @@ export class LocalBackend {
     initializedRepos = new Set();
     reinitPromises = new Map();
     lastStalenessCheck = new Map();
+    // Last meta.indexedAt observed for an open pool, keyed by lbugPath. Keyed by
+    // pool (not stored on the handle) because branch handles are produced fresh
+    // by applyBranchScope on every resolveRepo call, so mutating the handle would
+    // not persist across calls and the staleness check would reinit forever
+    // (#2106).
+    lastObservedIndexedAt = new Map();
     groupToolSvc = null;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -410,6 +451,8 @@ export class LocalBackend {
                 lastCommit: entry.lastCommit,
                 remoteUrl: entry.remoteUrl,
                 stats: entry.stats,
+                branch: entry.branch,
+                branches: entry.branches,
             };
             nextRepos.set(id, handle);
             // Build lightweight context (no LadybugDB needed)
@@ -432,13 +475,31 @@ export class LocalBackend {
         // the resolve→query wrong-clone window for good (#2067). Only a path that
         // dropped out of the registry must release its pooled connection + state.
         const liveLbugPaths = new Set([...nextRepos.values()].map((h) => h.lbugPath));
-        for (const prev of this.repos.values()) {
-            if (liveLbugPaths.has(prev.lbugPath))
+        // Branch pools (opened on demand by applyBranchScope) are NOT in this.repos
+        // — branch handles are minted fresh and discarded — so add every registered
+        // branch's lbugPath to the live set. Pure string work over the already-in-
+        // memory registry snapshot; no disk I/O on this hot path (#2106 R3).
+        for (const entry of entries) {
+            for (const b of entry.branches ?? []) {
+                liveLbugPaths.add(getStoragePaths(entry.path, b.branch).lbugPath);
+            }
+        }
+        // initializedRepos is the authoritative set of OPENED pool keys (flat AND
+        // branch); union it with the previously-known flat handles so an orphaned
+        // branch pool (e.g. after `clean --branch` removes its summary) is closed
+        // and forgotten too, not just flat handles.
+        const knownKeys = new Set([
+            ...[...this.repos.values()].map((h) => h.lbugPath),
+            ...this.initializedRepos,
+        ]);
+        for (const key of knownKeys) {
+            if (liveLbugPaths.has(key))
                 continue;
-            this.initializedRepos.delete(prev.lbugPath);
-            this.lastStalenessCheck.delete(prev.lbugPath);
-            this.reinitPromises.delete(prev.lbugPath);
-            closeLbug(prev.lbugPath).catch(() => { });
+            this.initializedRepos.delete(key);
+            this.lastStalenessCheck.delete(key);
+            this.lastObservedIndexedAt.delete(key);
+            this.reinitPromises.delete(key);
+            closeLbug(key).catch(() => { });
         }
         this.repos = nextRepos;
         this.contextCache = nextContext;
@@ -507,7 +568,7 @@ export class LocalBackend {
      * On a miss, re-reads the registry once in case a new repo was indexed
      * while the MCP server was running.
      */
-    async resolveRepo(repoParam) {
+    async resolveRepo(repoParam, branch) {
         let refreshedAfterAmbiguity = false;
         let result;
         try {
@@ -532,7 +593,7 @@ export class LocalBackend {
             this.maybeWarnSiblingDrift(result).catch(() => {
                 /* best-effort; never throw from resolveRepo */
             });
-            return result;
+            return this.applyBranchScope(result, branch);
         }
         // Miss — refresh registry and try once more (skip if already refreshed above)
         if (!refreshedAfterAmbiguity) {
@@ -541,7 +602,7 @@ export class LocalBackend {
         const retried = this.resolveRepoFromCache(repoParam);
         if (retried) {
             this.maybeWarnSiblingDrift(retried).catch(() => { });
-            return retried;
+            return this.applyBranchScope(retried, branch);
         }
         // Still no match — throw with helpful message
         if (this.repos.size === 0) {
@@ -562,6 +623,49 @@ export class LocalBackend {
         }
         throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`);
     }
+    /**
+     * Re-point a resolved repo handle at a specific branch index (#2106).
+     *
+     * - No `branch` (default) → the primary/flat handle, unchanged (backward
+     *   compatible: every existing caller passes no branch).
+     * - `branch` equal to the known primary → the flat handle.
+     * - `branch` matching an indexed non-primary branch → a handle whose
+     *   `lbugPath` points at `branches/<slug>/lbug`; the connection pool keys by
+     *   `lbugPath`, so this is the only change needed to scope every tool.
+     * - `branch` that was never indexed → a clear error (never a silently-empty
+     *   result against the wrong DB).
+     */
+    async applyBranchScope(handle, branch) {
+        if (!branch)
+            return handle;
+        if (handle.branch && handle.branch === branch)
+            return handle;
+        const summary = handle.branches?.find((b) => b.branch === branch);
+        if (summary) {
+            const { lbugPath } = getStoragePaths(handle.repoPath, branch);
+            return {
+                ...handle,
+                lbugPath,
+                indexedAt: summary.indexedAt,
+                lastCommit: summary.lastCommit,
+                stats: summary.stats,
+            };
+        }
+        // Legacy entry (pre-#2106): the registry has no recorded primary `branch`,
+        // so a `--branch <primary>` request misses the checks above. Read the flat
+        // meta.json (next to the flat handle's lbug) to learn the primary and serve
+        // the flat handle only when it actually matches — never serve flat for an
+        // arbitrary unindexed branch (#2106 R4).
+        if (!handle.branch) {
+            const flatMeta = await loadMeta(path.dirname(handle.lbugPath));
+            if (flatMeta?.branch && flatMeta.branch === branch)
+                return handle;
+        }
+        const indexed = [handle.branch, ...(handle.branches?.map((b) => b.branch) ?? [])].filter(Boolean);
+        const available = indexed.length > 0 ? indexed.join(', ') : '(primary only)';
+        throw new Error(`Branch "${branch}" is not indexed for "${handle.name}". ` +
+            `Indexed branches: ${available}. Run: gitnexus analyze --branch ${branch}`);
+    }
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.
      * Throws {@link RegistryAmbiguousTargetError} when `repoParam` matches
@@ -681,10 +785,19 @@ export class LocalBackend {
                 return; // Checked recently — skip
             this.lastStalenessCheck.set(poolKey, now);
             try {
-                const metaPath = path.join(repo.storagePath, 'meta.json');
+                // Read the meta.json that sits next to THIS handle's lbug. For the
+                // flat/primary handle this is `<storagePath>/meta.json` (unchanged);
+                // for a branch handle it is `<storagePath>/branches/<slug>/meta.json`.
+                // Reading the flat meta for a branch handle would compare the branch
+                // index's indexedAt against the primary's and thrash the pool (#2106).
+                const metaPath = path.join(path.dirname(repo.lbugPath), 'meta.json');
                 const metaRaw = await fs.readFile(metaPath, 'utf-8');
                 const meta = JSON.parse(metaRaw);
-                if (meta.indexedAt && meta.indexedAt !== repo.indexedAt) {
+                // Compare against the last indexedAt OBSERVED for this pool (keyed by
+                // lbugPath), not the handle's — branch handles are fresh spreads so a
+                // handle mutation would not persist and would reinit on every check.
+                const observed = this.lastObservedIndexedAt.get(poolKey) ?? repo.indexedAt;
+                if (meta.indexedAt && meta.indexedAt !== observed) {
                     // Index was rebuilt — close stale connection and re-init.
                     // Wrap in reinitPromises to prevent TOCTOU race where concurrent
                     // callers both detect staleness and double-close the pool.
@@ -692,7 +805,7 @@ export class LocalBackend {
                         try {
                             await closeLbug(poolKey);
                             this.initializedRepos.delete(poolKey);
-                            repo.indexedAt = meta.indexedAt;
+                            this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
                             await initLbug(poolKey, repo.lbugPath);
                             this.initializedRepos.add(poolKey);
                         }
@@ -714,6 +827,7 @@ export class LocalBackend {
         try {
             await initLbug(poolKey, repo.lbugPath);
             this.initializedRepos.add(poolKey);
+            this.lastObservedIndexedAt.set(poolKey, repo.indexedAt);
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries
@@ -792,6 +906,14 @@ export class LocalBackend {
                         lastCommit: s.lastCommit,
                     }))
                     : undefined,
+                branch: h.branch,
+                branches: h.branches && h.branches.length > 0
+                    ? h.branches.map((b) => ({
+                        branch: b.branch,
+                        indexedAt: b.indexedAt,
+                        lastCommit: b.lastCommit,
+                    }))
+                    : undefined,
             };
         });
     }
@@ -913,8 +1035,10 @@ export class LocalBackend {
             p.repo.startsWith('@')) {
             return this.callToolAtGroupRepo(method, p);
         }
-        // Resolve repo from optional param (re-reads registry on miss)
-        const repo = await this.resolveRepo(params?.repo);
+        // Resolve repo from optional param (re-reads registry on miss). An optional
+        // `branch` param scopes the resolved handle to that branch's index (#2106).
+        const repoParams = params;
+        const repo = await this.resolveRepo(repoParams?.repo, repoParams?.branch);
         switch (method) {
             case 'query':
                 return this.query(repo, params);
@@ -924,10 +1048,14 @@ export class LocalBackend {
             }
             case 'context':
                 return this.context(repo, params);
+            case 'explain':
+                return this.explain(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
@@ -950,6 +1078,37 @@ export class LocalBackend {
         }
     }
     // ─── 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.
      *
@@ -1280,9 +1439,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 });
@@ -2011,6 +2176,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 {
@@ -2041,6 +2223,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: {
@@ -2053,6 +2241,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
@@ -2074,6 +2263,230 @@ export class LocalBackend {
             })),
         };
     }
+    /**
+     * 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 = '';
+        const queryParams = {};
+        let anchor;
+        // Build the anchor as a file filter (used only when `target` is path-ish).
+        const buildFileAnchor = () => {
+            // Exact path via the BasicBlock id-prefix template, OR a
+            // path-separator-aligned suffix so partial paths work like context()'s
+            // file_path hint ("vuln.ts" ⇒ "src/vuln.ts", never "devuln.ts").
+            anchorClause =
+                'AND (a.id STARTS WITH $idPrefix OR a.filePath = $targetPath OR a.filePath ENDS WITH $targetSuffix)';
+            queryParams.idPrefix = `BasicBlock:${target}:`;
+            queryParams.targetPath = target;
+            queryParams.targetSuffix = `/${target}`;
+            anchor = { file: target };
+        };
+        // Resolve `target` as a symbol into the anchor. Returns an early-return
+        // payload (not_found / ambiguous) or undefined on success.
+        const resolveSymbolAnchor = async () => {
+            const outcome = await this.resolveSymbolCandidates(repo, { name: target }, {});
+            if (outcome.kind === 'not_found') {
+                return { error: `Symbol '${target}' not found` };
+            }
+            if (outcome.kind === 'ambiguous') {
+                return {
+                    status: 'ambiguous',
+                    message: `Found ${outcome.candidates.length} symbols matching '${target}'. Re-call explain 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;
+            queryParams.idPrefix = `BasicBlock:${sym.filePath}:`;
+            anchor = { file: sym.filePath, symbol: sym.name };
+            if (typeof sym.startLine === 'number' &&
+                typeof sym.endLine === 'number' &&
+                sym.endLine >= sym.startLine) {
+                anchorClause =
+                    'AND a.id STARTS WITH $idPrefix AND a.startLine >= $symStart AND a.startLine <= $symEnd';
+                queryParams.symStart = sym.startLine;
+                queryParams.symEnd = sym.endLine;
+                anchor.startLine = sym.startLine;
+                anchor.endLine = sym.endLine;
+            }
+            else {
+                // No usable span — degrade to the file-level filter (documented).
+                anchorClause = 'AND a.id STARTS WITH $idPrefix';
+            }
+            return undefined;
+        };
+        // 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}`;
+            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) {
+            if (looksLikeFilePath(target)) {
+                buildFileAnchor();
+            }
+            else {
+                // A bare or dotted symbol name (`UserController.create`) — resolve as a
+                // symbol rather than silently file-anchoring to an empty result.
+                const early = await resolveSymbolAnchor();
+                if (early)
+                    return early;
+            }
+        }
+        const { rows, totalFindings } = await runAnchoredQuery();
+        if (totalFindings === 0 && pdgStamped === undefined && !target) {
+            // Meta was unreadable and the repo-wide enumerate found nothing — the
+            // count above WAS the existence probe; surface the layer hint.
+            return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+        }
+        if (totalFindings === 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".
+            const probe = await executeParameterized(repo.lbugPath, `MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock) WHERE r.type = 'TAINTED' RETURN r.reason AS reason LIMIT 1`, {});
+            if (probe.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 } : {}),
+            };
+        });
+        return {
+            ...(anchor ? { anchor } : {}),
+            findings,
+            totalFindings,
+            ...(totalFindings > findings.length ? { truncated: true } : {}),
+            note: 'Intra-procedural findings only — cross-function, closure/callback, property/field, and implicit flows are not modeled; absence of a finding is not proof of safety. SANITIZES (kill) edges are queryable via cypher.',
+        };
+    }
     /**
      * Legacy explore — kept for backwards compatibility with resources.ts.
      * Routes cluster/process types to direct graph queries.
@@ -2269,8 +2682,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,
@@ -2586,21 +3011,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 = {
@@ -2624,12 +3131,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))
@@ -2646,6 +3250,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];
@@ -2783,7 +3399,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
@@ -3004,6 +3626,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,
@@ -3014,6 +3639,7 @@ export class LocalBackend {
             direction,
             impactedCount: impacted.length,
             risk,
+            ...epistemic,
             ...(!traversalComplete && { partial: true }),
             summary: {
                 direct: directCount,
@@ -3203,6 +3829,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 {