@cleocode/core 2026.9.7 → 2026.9.9

package/dist/nexus/living-brain.js

@@ -17,7 +17,7 @@
  *    which tasks touched those nodes?
  *
  * Design constraints:
- * - All substrate errors are caught and produce empty collections — never throws.
+ * - Substrate errors are recorded in coverage; ambiguity returns qualified candidates.
  * - conduit.db absence is a graceful no-op: conduitThreads returns [].
  * - All return shapes are defined in packages/contracts/src/nexus-living-brain-ops.ts.
  * - REUSES existing primitives: T1067 bridge, T1066 edge writers, existing
@@ -29,11 +29,15 @@
 import { existsSync } from 'node:fs';
 import { engineError, engineSuccess } from '../engine-result.js';
 import { reasonWhySymbol } from '../memory/brain-reasoning.js';
+import { isCurrentDecisionCodeEvidence } from '../memory/decision-cross-link.js';
 import { EDGE_TYPES } from '../memory/edge-types.js';
+import { graphMemoryAuthority, memoryEligibilityClause } from '../memory/eligibility.js';
 import { getConduitDbPath } from '../store/conduit-sqlite.js';
 import { getBrainDb, getBrainNativeDb } from '../store/memory-sqlite.js';
 import { getNexusDb, getNexusNativeDb } from '../store/nexus-sqlite.js';
 import { typedAll, typedGet } from '../store/typed-query.js';
+import { assessKnowledgeCoverage, KnowledgeSymbolAmbiguityError, recordKnowledgeGap, resolveKnowledgeSymbol, } from './knowledge.js';
+import { getTaskKnowledgeEvidence } from './task-evidence.js';
 import { getSymbolsForTask, getTasksForSymbol } from './tasks-bridge.js';
 // ---------------------------------------------------------------------------
 // Internal: map ImpactResult riskLevel → RiskTier
@@ -52,13 +56,15 @@ function toRiskTier(riskLevel) {
         case 'low':
             return 'LOW';
         default:
-            return 'NONE';
+            return 'UNKNOWN';
     }
 }
 /**
  * Return the highest risk tier from an array.
  */
 function maxRiskTier(tiers) {
+    if (tiers.length === 0 || tiers.includes('UNKNOWN'))
+        return 'UNKNOWN';
     const order = ['NONE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
     let max = 0;
     for (const t of tiers) {
@@ -81,14 +87,16 @@ function maxRiskTier(tiers) {
  * - **SENTIENT**: Tier-2 proposals whose sourceId matches this symbol
  * - **CONDUIT**: message threads mentioning this symbol (empty if conduit.db absent)
  *
- * All substrate failures produce empty collections — never throws.
+ * Substrate failures are exposed through coverage; ambiguous names are rejected.
  *
  * @param symbolId - Nexus node ID or symbol name (partial match accepted for nexus lookup)
  * @param projectRoot - Absolute path to project root
  * @returns Full cross-substrate context
  */
 export async function getSymbolFullContext(symbolId, projectRoot) {
+    const coverage = await assessKnowledgeCoverage(projectRoot);
     const result = {
+        coverage,
         symbolId,
         nexus: null,
         brainMemories: [],
@@ -100,20 +108,18 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
     // ---- NEXUS substrate ----
     let resolvedSymbolId = symbolId;
     try {
-        await getNexusDb();
-        const nexusNative = getNexusNativeDb();
+        await getNexusDb(projectRoot);
+        const nexusNative = getNexusNativeDb(projectRoot);
         if (nexusNative) {
-            // Try exact match on id first; fall back to name lookup.
-            // ADR-090 · T11648: project-scoped graph — `project_id` column dropped.
-            let symbolNode = typedGet(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id
-           FROM nexus_nodes WHERE id = ? LIMIT 1`), symbolId);
-            if (!symbolNode) {
-                // Fuzzy match on name (case-insensitive)
-                symbolNode = typedGet(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id
-             FROM nexus_nodes
-             WHERE LOWER(name) = LOWER(?) AND kind NOT IN ('community', 'process', 'folder')
-             LIMIT 1`), symbolId);
-            }
+            const candidates = typedAll(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id FROM nexus_nodes`));
+            const selected = resolveKnowledgeSymbol(symbolId, candidates.map((node) => ({
+                id: node.id,
+                name: node.name,
+                label: node.label,
+                kind: node.kind,
+                filePath: node.file_path,
+            })));
+            const symbolNode = candidates.find((node) => node.id === selected?.id);
             if (symbolNode) {
                 resolvedSymbolId = symbolNode.id;
                 // Callers: relations where target_id = symbolNode.id.
@@ -182,6 +188,9 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] NEXUS substrate error:', err instanceof Error ? err.message : String(err));
     }
     // ---- BRAIN substrate ----
@@ -200,12 +209,12 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
             ];
             const placeholders = codeEdgeTypes.map(() => '?').join(', ');
             // brain → symbol edges (from_id is brain node, to_id is symbol)
-            const brainToSymbolEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+            const brainToSymbolEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
            FROM brain_page_edges
            WHERE to_id = ? AND edge_type IN (${placeholders})
            LIMIT 100`), resolvedSymbolId, ...codeEdgeTypes);
             // symbol → observation edges (from_id is symbol/file, to_id is brain node)
-            const symbolToBrainEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+            const symbolToBrainEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
            FROM brain_page_edges
            WHERE from_id = ? AND edge_type = ?
            LIMIT 100`), resolvedSymbolId, EDGE_TYPES.AFFECTS);
@@ -213,6 +222,8 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
             const brainNodeIds = new Set();
             const edgeByBrainId = new Map();
             for (const edge of brainToSymbolEdges) {
+                if (!isCurrentDecisionCodeEvidence(brainNative, edge.provenance))
+                    continue;
                 brainNodeIds.add(edge.from_id);
                 edgeByBrainId.set(edge.from_id, edge);
             }
@@ -226,6 +237,11 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
              FROM brain_page_nodes WHERE id = ? LIMIT 1`), nodeId);
                 const edge = edgeByBrainId.get(nodeId);
                 if (brainNode && edge) {
+                    const authority = graphMemoryAuthority(brainNative, brainNode.id, brainNode.node_type);
+                    if (authority === 'historical')
+                        continue;
+                    if (authority === 'unverified')
+                        recordKnowledgeGap(coverage, 'partial', `Graph memory source is unverified: ${brainNode.id}`);
                     // Filter out conduit_mentions_symbol — those go to conduitThreads
                     if (edge.edge_type === EDGE_TYPES.CONDUIT_MENTIONS_SYMBOL) {
                         result.conduitThreads.push({
@@ -235,6 +251,7 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
                     }
                     else {
                         result.brainMemories.push({
+                            authority,
                             nodeId: brainNode.id,
                             nodeType: brainNode.node_type,
                             label: brainNode.label,
@@ -248,6 +265,9 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] BRAIN substrate error:', err instanceof Error ? err.message : String(err));
     }
     // ---- TASKS substrate ----
@@ -261,6 +281,9 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
         }));
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] TASKS substrate error:', err instanceof Error ? err.message : String(err));
     }
     // ---- SENTIENT substrate ----
@@ -299,6 +322,9 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] SENTIENT substrate error:', err instanceof Error ? err.message : String(err));
     }
     // ---- CONDUIT substrate ----
@@ -315,6 +341,8 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
     catch {
         // Non-fatal: conduit check is best-effort
     }
+    if (!result.nexus)
+        recordKnowledgeGap(coverage, 'missing', `No indexed symbol matches '${symbolId}'.`);
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -331,158 +359,133 @@ export async function getSymbolFullContext(symbolId, projectRoot) {
  * - Queries brain decisions linked to this task via brain_memory_links
  * - Computes aggregate risk tier
  *
- * All substrate failures produce empty collections — never throws.
+ * Substrate failures are exposed through coverage; ambiguous names are rejected.
+ * Historical file associations survive optional impact failure. UNKNOWN entries
+ * use zero numeric placeholders; only blastRadius.symbolsAnalyzed counts completed
+ * assessments, and file precision does not establish that a symbol changed.
  *
  * @param taskId - Task ID (e.g., 'T001')
  * @param projectRoot - Absolute path to project root
  * @returns Full task code impact analysis
  */
 export async function getTaskCodeImpact(taskId, projectRoot) {
+    const coverage = await assessKnowledgeCoverage(projectRoot);
     const result = {
+        coverage,
         taskId,
         files: [],
         symbols: [],
-        blastRadius: { totalAffected: 0, maxRisk: 'NONE', symbolsAnalyzed: 0 },
+        blastRadius: { totalAffected: 0, maxRisk: 'UNKNOWN', symbolsAnalyzed: 0 },
         brainObservations: [],
         decisions: [],
-        riskScore: 'NONE',
+        riskScore: 'UNKNOWN',
     };
-    // ---- Resolve files from tasks.db ----
-    let filesJson = null;
-    try {
-        const { getDb } = await import('../store/sqlite.js');
-        const { eq } = await import('drizzle-orm');
-        const { tasks: tasksTable } = await import('../store/tasks-schema.js');
-        const tasksDb = await getDb(projectRoot);
-        const rows = await tasksDb
-            .select({ filesJson: tasksTable.filesJson })
-            .from(tasksTable)
-            .where(eq(tasksTable.id, taskId))
-            .all();
-        if (rows[0]?.filesJson) {
-            filesJson = rows[0].filesJson;
-        }
-    }
-    catch {
-        // Fallback: try to get files from brain_page_edges task edges
-    }
-    if (!filesJson) {
-        // Try to infer from task_touches_symbol edges
-        try {
-            await getBrainDb(projectRoot);
-            const brainNative = getBrainNativeDb(projectRoot);
-            await getNexusDb();
-            const nexusNative = getNexusNativeDb();
-            if (brainNative && nexusNative) {
-                const taskEdges = typedAll(brainNative.prepare(`SELECT to_id FROM brain_page_edges
-             WHERE from_id = ? AND edge_type = ?
-             LIMIT 100`), `task:${taskId}`, EDGE_TYPES.TASK_TOUCHES_SYMBOL);
-                const filePaths = new Set();
-                for (const edge of taskEdges) {
-                    const node = typedGet(nexusNative.prepare(`SELECT file_path FROM nexus_nodes WHERE id = ? LIMIT 1`), edge.to_id);
-                    if (node?.file_path)
-                        filePaths.add(node.file_path);
-                }
-                if (filePaths.size > 0) {
-                    filesJson = JSON.stringify(Array.from(filePaths));
-                }
-            }
-        }
-        catch {
-            // Give up on file resolution
-        }
-    }
-    if (filesJson) {
-        try {
-            const parsed = JSON.parse(filesJson);
-            if (Array.isArray(parsed)) {
-                result.files = parsed.filter((f) => typeof f === 'string');
-            }
-        }
-        catch {
-            // malformed JSON
-        }
-    }
+    const taskEvidence = await getTaskKnowledgeEvidence(taskId, projectRoot, coverage);
+    result.files = taskEvidence.files.map((file) => file.path);
+    result.findings = taskEvidence.findings;
     // ---- Symbols via T1067 bridge ----
     let symbolIds = [];
+    const evidenceBySymbol = new Map();
     try {
-        const symbolRefs = await getSymbolsForTask(taskId, projectRoot);
+        const symbolRefs = await getSymbolsForTask(taskId, projectRoot, taskEvidence);
+        for (const ref of symbolRefs)
+            evidenceBySymbol.set(ref.nexusNodeId, ref);
         symbolIds = symbolRefs.map((s) => s.nexusNodeId);
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] getSymbolsForTask failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Impact BFS per symbol ----
     if (symbolIds.length > 0) {
         try {
-            await getNexusDb();
-            const nexusNative = getNexusNativeDb();
-            if (nexusNative) {
-                const { analyzeImpact } = await import('@cleocode/nexus');
-                // Load all nodes + relations once
-                const allNodes = typedAll(nexusNative.prepare(`SELECT id, name, kind, file_path, label, is_exported FROM nexus_nodes LIMIT 50000`));
-                // T11545: `weight` moved to the sibling nexus_relation_weights table and
-                // is unused by the GraphRelation mapping below — select only structural cols.
-                const allRelations = typedAll(nexusNative.prepare(`SELECT id, source_id, target_id, type, confidence FROM nexus_relations LIMIT 200000`));
-                // Map to GraphNode / GraphRelation contracts
-                const graphNodes = allNodes.map((n) => ({
-                    id: n.id,
-                    name: n.name ?? n.label,
-                    kind: n.kind,
-                    filePath: n.file_path ?? '',
-                    startLine: 0,
-                    endLine: 0,
-                    language: 'unknown',
-                    exported: n.is_exported === 1,
-                }));
-                const graphRelations = allRelations.map((r) => ({
-                    source: r.source_id,
-                    target: r.target_id,
-                    type: r.type,
-                    confidence: r.confidence ?? 1.0,
-                }));
-                const symbolEntries = [];
-                for (const symbolId of symbolIds.slice(0, 50)) {
-                    const node = allNodes.find((n) => n.id === symbolId);
-                    if (!node)
-                        continue;
-                    let impactResult;
-                    try {
-                        impactResult = analyzeImpact(symbolId, graphNodes, graphRelations);
-                    }
-                    catch {
-                        impactResult = {
-                            target: symbolId,
-                            riskLevel: 'low',
-                            summary: '',
-                            affectedByDepth: {
-                                depth1_willBreak: [],
-                                depth2_likelyAffected: [],
-                                depth3_mayNeedTesting: [],
-                            },
-                            totalAffected: 0,
-                        };
-                    }
-                    symbolEntries.push({
-                        nexusNodeId: symbolId,
-                        label: node.name ?? node.label,
-                        kind: node.kind,
-                        filePath: node.file_path,
-                        riskLevel: toRiskTier(impactResult.riskLevel),
-                        totalAffected: impactResult.totalAffected,
-                        directCallers: impactResult.affectedByDepth.depth1_willBreak.length,
-                    });
-                }
-                result.symbols = symbolEntries;
-                result.blastRadius = {
-                    totalAffected: symbolEntries.reduce((sum, s) => sum + s.totalAffected, 0),
-                    maxRisk: maxRiskTier(symbolEntries.map((s) => s.riskLevel)),
-                    symbolsAnalyzed: symbolEntries.length,
-                };
-                result.riskScore = result.blastRadius.maxRisk;
+            await getNexusDb(projectRoot);
+            const nexusNative = getNexusNativeDb(projectRoot);
+            if (!nexusNative)
+                throw new Error('Task impact graph connection is unavailable.');
+            // Historical association is independent of the optional impact engine.
+            const readSymbol = nexusNative.prepare('SELECT id, name, kind, file_path, label FROM nexus_nodes WHERE id = ?');
+            for (const symbolId of symbolIds) {
+                const node = typedGet(readSymbol, symbolId);
+                if (!node)
+                    continue;
+                result.symbols.push({
+                    nexusNodeId: symbolId,
+                    precision: evidenceBySymbol.get(symbolId)?.precision ?? 'file',
+                    evidence: evidenceBySymbol.get(symbolId)?.evidence ?? [],
+                    label: node.name ?? node.label,
+                    kind: node.kind,
+                    filePath: node.file_path,
+                    riskLevel: 'UNKNOWN',
+                    totalAffected: 0,
+                    directCallers: 0,
+                });
+            }
+            const { analyzeImpact } = await import('@cleocode/nexus');
+            // Load all nodes + relations once
+            const allNodes = typedAll(nexusNative.prepare(`SELECT id, name, kind, file_path, label, is_exported FROM nexus_nodes LIMIT 50001`));
+            // T11545: `weight` moved to the sibling nexus_relation_weights table and
+            // is unused by the GraphRelation mapping below — select only structural cols.
+            const allRelations = typedAll(nexusNative.prepare(`SELECT id, source_id, target_id, type, confidence FROM nexus_relations LIMIT 200001`));
+            if (allNodes.length > 50000 || allRelations.length > 200000) {
+                recordKnowledgeGap(coverage, 'partial', 'Impact graph exceeds the 50000-node or 200000-relationship assessment limit.');
+                coverage.nextAction = `cleo doctor knowledge --task ${taskId}`;
+            }
+            // Map to GraphNode / GraphRelation contracts
+            const graphNodes = allNodes.map((n) => ({
+                id: n.id,
+                name: n.name ?? n.label,
+                kind: n.kind,
+                filePath: n.file_path ?? '',
+                startLine: 0,
+                endLine: 0,
+                language: 'unknown',
+                exported: n.is_exported === 1,
+            }));
+            const graphRelations = allRelations.map((r) => ({
+                source: r.source_id,
+                target: r.target_id,
+                type: r.type,
+                confidence: r.confidence ?? 1.0,
+            }));
+            for (const entry of result.symbols.slice(0, 50)) {
+                const impactResult = analyzeImpact(entry.nexusNodeId, graphNodes, graphRelations);
+                entry.riskLevel =
+                    coverage.status !== 'current'
+                        ? 'UNKNOWN'
+                        : impactResult.totalAffected === 0
+                            ? 'NONE'
+                            : toRiskTier(impactResult.riskLevel);
+                entry.totalAffected = impactResult.totalAffected;
+                entry.directCallers = impactResult.affectedByDepth.depth1_willBreak.length;
+                result.blastRadius.symbolsAnalyzed += 1;
+                result.blastRadius.totalAffected += impactResult.totalAffected;
             }
+            result.blastRadius.maxRisk = maxRiskTier(result.symbols.map((entry) => entry.riskLevel));
+            result.riskScore = result.blastRadius.maxRisk;
         }
         catch (err) {
+            if (err instanceof KnowledgeSymbolAmbiguityError)
+                throw err;
+            const failure = err instanceof Error ? err.message : String(err);
+            recordKnowledgeGap(coverage, 'failed', `Task impact assessment failed: ${failure}`);
+            coverage.nextAction = `cleo doctor knowledge --task ${taskId}`;
+            result.findings.push({
+                id: `task-impact:${taskId}`,
+                projectId: coverage.projectId,
+                affectedRecordIds: [taskId, ...symbolIds],
+                description: `Optional impact assessment failed: ${failure}. Inspect the diagnostic and retry the task footprint after the analyzer is available. Historical associations remain evidence, not proof that each symbol changed.`,
+                evidence: taskEvidence.files.flatMap((file) => file.evidence),
+                repairClass: 'agent-resolvable',
+                state: 'failed',
+                proposedAction: null,
+                verification: [
+                    'Repeat the task footprint with a working impact analyzer; retain the same independently supported file and symbol associations.',
+                ],
+                recovery: null,
+            });
             console.warn('[living-brain] blast radius analysis failed:', err instanceof Error ? err.message : String(err));
         }
     }
@@ -490,8 +493,8 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
     try {
         await getBrainDb(projectRoot);
         const brainNative = getBrainNativeDb(projectRoot);
-        await getNexusDb();
-        const nexusNative = getNexusNativeDb();
+        await getNexusDb(projectRoot);
+        const nexusNative = getNexusNativeDb(projectRoot);
         if (brainNative && nexusNative && result.files.length > 0) {
             for (const filePath of result.files) {
                 // Find nexus file node for this path
@@ -499,12 +502,12 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
                 if (!fileNode)
                     continue;
                 // Find modified_by edges from this file node to observation nodes
-                const modEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+                const modEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
              FROM brain_page_edges
              WHERE from_id = ? AND edge_type = ?
              LIMIT 20`), fileNode.id, EDGE_TYPES.AFFECTS);
                 // Also check reverse (observation → file via modified_by)
-                const modByEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+                const modByEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
              FROM brain_page_edges
              WHERE to_id = ? AND edge_type = 'modified_by'
              LIMIT 20`), fileNode.id);
@@ -530,6 +533,9 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] brain observations query failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Decisions from brain_memory_links ----
@@ -542,7 +548,7 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
            WHERE task_id = ? AND memory_type = 'decision'
            LIMIT 20`), taskId);
             for (const link of linkRows) {
-                const decisionRow = typedGet(brainNative.prepare(`SELECT id, decision FROM brain_decisions WHERE id = ? LIMIT 1`), link.memory_id);
+                const decisionRow = typedGet(brainNative.prepare(`SELECT id, decision FROM main.brain_decisions AS source WHERE id = ?${memoryEligibilityClause('decisions', 'source')} LIMIT 1`), link.memory_id);
                 if (decisionRow) {
                     result.decisions.push({
                         decisionId: decisionRow.id,
@@ -554,8 +560,32 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] decisions query failed:', err instanceof Error ? err.message : String(err));
     }
+    if (result.symbols.length === 0) {
+        recordKnowledgeGap(coverage, coverage.maintenanceState === 'pending' ? 'partial' : 'missing', coverage.maintenanceState === 'pending'
+            ? 'Task evidence assessment is deferred; zero matches do not establish missing evidence.'
+            : 'No task evidence has been resolved to indexed symbols.');
+    }
+    if (symbolIds.length > 50) {
+        coverage.nextAction = `cleo doctor knowledge --task ${taskId}`;
+        recordKnowledgeGap(coverage, 'partial', 'Impact is bounded to 50 task symbols; additional associations remain unassessed.');
+    }
+    if (result.symbols.length < symbolIds.length) {
+        recordKnowledgeGap(coverage, 'partial', 'Some task-linked symbols are absent from the graph.');
+    }
+    if (result.blastRadius.symbolsAnalyzed < result.symbols.length) {
+        coverage.limitations.push('Impact counts include only completed analyzer results. Zero counts for unassessed symbols are placeholders, not evidence of NONE; their risk remains UNKNOWN.');
+    }
+    if (coverage.status !== 'current') {
+        result.riskScore = 'UNKNOWN';
+        result.blastRadius.maxRisk = 'UNKNOWN';
+        for (const entry of result.symbols)
+            entry.riskLevel = 'UNKNOWN';
+    }
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -569,7 +599,7 @@ export async function getTaskCodeImpact(taskId, projectRoot) {
  * - tasksForNodes: for each code node, which tasks touched it (T1067 reverse-lookup)
  * - plasticitySignal: sum of weights on all anchoring edges
  *
- * All substrate failures produce empty collections — never throws.
+ * Substrate failures are exposed through coverage; ambiguous names are rejected.
  *
  * @param entryId - Brain entry node ID (format: '<type>:<source-id>')
  * @param projectRoot - Absolute path to project root
@@ -591,18 +621,20 @@ export async function getBrainEntryCodeAnchors(entryId, projectRoot) {
     try {
         await getBrainDb(projectRoot);
         const brainNative = getBrainNativeDb(projectRoot);
-        await getNexusDb();
-        const nexusNative = getNexusNativeDb();
+        await getNexusDb(projectRoot);
+        const nexusNative = getNexusNativeDb(projectRoot);
         if (!brainNative || !nexusNative)
             return result;
         const placeholders = anchorEdgeTypes.map(() => '?').join(', ');
         // brain entry → code node edges
-        const anchorEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+        const anchorEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
          FROM brain_page_edges
          WHERE from_id = ? AND edge_type IN (${placeholders})
          LIMIT 100`), entryId, ...anchorEdgeTypes);
         let totalWeight = 0;
         for (const edge of anchorEdges) {
+            if (!isCurrentDecisionCodeEvidence(brainNative, edge.provenance))
+                continue;
             // Verify the target exists in nexus
             const nexusNode = typedGet(nexusNative.prepare(`SELECT id, kind, name, file_path, label FROM nexus_nodes WHERE id = ? LIMIT 1`), edge.to_id);
             if (nexusNode) {
@@ -656,7 +688,7 @@ export async function getBrainEntryCodeAnchors(entryId, projectRoot) {
  * 2. `getTasksForSymbol(symbolId)` — tasks that touch this symbol
  * 3. Brain observations/decisions via `code_reference`, `modified_by`, `documents` edges
  *
- * All substrate failures produce empty collections — never throws.
+ * Substrate failures are exposed through coverage; ambiguous names are rejected.
  *
  * @param symbolId - Nexus node ID or symbol name (partial match accepted)
  * @param projectRoot - Absolute path to project root
@@ -665,35 +697,39 @@ export async function getBrainEntryCodeAnchors(entryId, projectRoot) {
  * @epic T1042
  */
 export async function reasonImpactOfChange(symbolId, projectRoot) {
+    const coverage = await assessKnowledgeCoverage(projectRoot);
     const result = {
+        coverage,
         symbolId,
         structural: {
             directCallers: 0,
             likelyAffected: 0,
             mayNeedTesting: 0,
             totalAffected: 0,
-            riskLevel: 'NONE',
+            riskLevel: 'UNKNOWN',
         },
         openTasks: [],
         brainRiskNotes: [],
-        mergedRiskScore: 'NONE',
+        mergedRiskScore: 'UNKNOWN',
         narrative: `No impact data available for symbol '${symbolId}'.`,
     };
     // ---- Resolve nexus node ID (may be a name) ----
     let resolvedId = symbolId;
     try {
-        await getNexusDb();
-        const nexusNative = getNexusNativeDb();
+        await getNexusDb(projectRoot);
+        const nexusNative = getNexusNativeDb(projectRoot);
         if (nexusNative) {
-            // ADR-090 · T11648: project-scoped graph — `project_id` column dropped
-            // (the stray `weight` column never existed on nexus_nodes; removed too).
-            let nexusNode = typedGet(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id
-           FROM nexus_nodes WHERE id = ? LIMIT 1`), symbolId);
+            const candidates = typedAll(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id FROM nexus_nodes`));
+            const nexusNode = resolveKnowledgeSymbol(symbolId, candidates.map((node) => ({
+                id: node.id,
+                name: node.name,
+                label: node.label,
+                kind: node.kind,
+                filePath: node.file_path,
+            })));
             if (!nexusNode) {
-                nexusNode = typedGet(nexusNative.prepare(`SELECT id, kind, name, file_path, label, community_id
-             FROM nexus_nodes
-             WHERE LOWER(name) = LOWER(?) AND kind NOT IN ('community', 'process', 'folder')
-             LIMIT 1`), symbolId);
+                recordKnowledgeGap(coverage, 'missing', `No indexed symbol matches '${symbolId}'.`);
+                return result;
             }
             if (nexusNode) {
                 resolvedId = nexusNode.id;
@@ -701,12 +737,15 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] reasonImpactOfChange nexus resolve failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Structural blast radius via analyzeImpact ----
     try {
-        await getNexusDb();
-        const nexusNative = getNexusNativeDb();
+        await getNexusDb(projectRoot);
+        const nexusNative = getNexusNativeDb(projectRoot);
         if (nexusNative) {
             const { analyzeImpact } = await import('@cleocode/nexus');
             const allNodes = typedAll(nexusNative.prepare(`SELECT id, name, kind, file_path, label, is_exported FROM nexus_nodes LIMIT 50000`));
@@ -729,33 +768,24 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
                 type: r.type,
                 confidence: r.confidence ?? 1.0,
             }));
-            let impactResult;
-            try {
-                impactResult = analyzeImpact(resolvedId, graphNodes, graphRelations);
-            }
-            catch {
-                impactResult = {
-                    target: resolvedId,
-                    riskLevel: 'low',
-                    summary: '',
-                    affectedByDepth: {
-                        depth1_willBreak: [],
-                        depth2_likelyAffected: [],
-                        depth3_mayNeedTesting: [],
-                    },
-                    totalAffected: 0,
-                };
-            }
+            const impactResult = analyzeImpact(resolvedId, graphNodes, graphRelations);
             result.structural = {
                 directCallers: impactResult.affectedByDepth.depth1_willBreak.length,
                 likelyAffected: impactResult.affectedByDepth.depth2_likelyAffected.length,
                 mayNeedTesting: impactResult.affectedByDepth.depth3_mayNeedTesting.length,
                 totalAffected: impactResult.totalAffected,
-                riskLevel: toRiskTier(impactResult.riskLevel),
+                riskLevel: coverage.status !== 'current'
+                    ? 'UNKNOWN'
+                    : impactResult.totalAffected === 0
+                        ? 'NONE'
+                        : toRiskTier(impactResult.riskLevel),
             };
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] reasonImpactOfChange structural analysis failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Open tasks via task_touches_symbol ----
@@ -768,6 +798,9 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
         }));
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] reasonImpactOfChange open-tasks lookup failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Brain risk notes via code_reference / documents / modified_by edges ----
@@ -783,18 +816,20 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
             ];
             const placeholders = riskEdgeTypes.map(() => '?').join(', ');
             // Brain nodes → symbol (brain references this symbol)
-            const brainToSymbolEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+            const brainToSymbolEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
            FROM brain_page_edges
            WHERE to_id = ? AND edge_type IN (${placeholders})
            LIMIT 50`), resolvedId, ...riskEdgeTypes);
             // symbol → brain nodes (symbol points to observations)
-            const symbolToBrainEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight
+            const symbolToBrainEdges = typedAll(brainNative.prepare(`SELECT from_id, to_id, edge_type, weight, provenance
            FROM brain_page_edges
            WHERE from_id = ? AND edge_type = ?
            LIMIT 50`), resolvedId, EDGE_TYPES.AFFECTS);
             const seenIds = new Set();
             const processEdges = (edges, isReverse) => {
                 for (const edge of edges) {
+                    if (!isCurrentDecisionCodeEvidence(brainNative, edge.provenance))
+                        continue;
                     const nodeId = isReverse ? edge.from_id : edge.to_id;
                     if (seenIds.has(nodeId))
                         continue;
@@ -802,7 +837,13 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
                     const brainNode = typedGet(brainNative.prepare(`SELECT id, node_type, label, quality_score
                FROM brain_page_nodes WHERE id = ? LIMIT 1`), nodeId);
                     if (brainNode) {
+                        const authority = graphMemoryAuthority(brainNative, brainNode.id, brainNode.node_type);
+                        if (authority === 'historical')
+                            continue;
+                        if (authority === 'unverified')
+                            recordKnowledgeGap(coverage, 'partial', `Graph memory source is unverified: ${brainNode.id}`);
                         const riskNote = {
+                            authority,
                             nodeId: brainNode.id,
                             nodeType: brainNode.node_type,
                             label: brainNode.label,
@@ -818,6 +859,9 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
         }
     }
     catch (err) {
+        if (err instanceof KnowledgeSymbolAmbiguityError)
+            throw err;
+        recordKnowledgeGap(coverage, 'failed', err instanceof Error ? err.message : String(err));
         console.warn('[living-brain] reasonImpactOfChange brain risk notes failed:', err instanceof Error ? err.message : String(err));
     }
     // ---- Compute merged risk score ----
@@ -841,7 +885,7 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
     const openCount = result.openTasks.length;
     const riskNoteCount = result.brainRiskNotes.length;
     result.narrative =
-        `Changing ${symLabel} will break ${d1} direct caller${d1 !== 1 ? 's' : ''} (d=1)` +
+        `Static analysis of ${symLabel} identifies ${d1} direct caller${d1 !== 1 ? 's' : ''} (d=1)` +
             (d2 > 0 ? `, likely affect ${d2} at d=2` : '') +
             (openCount > 0
                 ? `, and is referenced in ${openCount} open task${openCount !== 1 ? 's' : ''}`
@@ -850,6 +894,11 @@ export async function reasonImpactOfChange(symbolId, projectRoot) {
                 ? ` and ${riskNoteCount} BRAIN risk note${riskNoteCount !== 1 ? 's' : ''}`
                 : '') +
             `. Merged risk: ${result.mergedRiskScore}.`;
+    if (coverage.status !== 'current') {
+        result.mergedRiskScore = 'UNKNOWN';
+        result.structural.riskLevel = 'UNKNOWN';
+        result.narrative = `Impact cannot be fully assessed for ${symLabel}. Coverage: ${coverage.status}. ${coverage.reasons.join(' ')}`;
+    }
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -862,6 +911,9 @@ export async function nexusFullContext(symbolId, projectRoot) {
         return engineSuccess(result);
     }
     catch (error) {
+        if (error instanceof KnowledgeSymbolAmbiguityError) {
+            return engineError(error.code, error.message, { details: { candidates: error.candidates } });
+        }
         return engineError('E_INTERNAL', error instanceof Error ? error.message : String(error));
     }
 }
@@ -872,6 +924,9 @@ export async function nexusTaskFootprint(taskId, projectRoot) {
         return engineSuccess(result);
     }
     catch (error) {
+        if (error instanceof KnowledgeSymbolAmbiguityError) {
+            return engineError(error.code, error.message, { details: { candidates: error.candidates } });
+        }
         return engineError('E_INTERNAL', error instanceof Error ? error.message : String(error));
     }
 }
@@ -882,6 +937,9 @@ export async function nexusBrainAnchors(entryId, projectRoot) {
         return engineSuccess(result);
     }
     catch (error) {
+        if (error instanceof KnowledgeSymbolAmbiguityError) {
+            return engineError(error.code, error.message, { details: { candidates: error.candidates } });
+        }
         return engineError('E_INTERNAL', error instanceof Error ? error.message : String(error));
     }
 }
@@ -892,6 +950,9 @@ export async function nexusImpactFull(symbolId, projectRoot) {
         return engineSuccess(result);
     }
     catch (error) {
+        if (error instanceof KnowledgeSymbolAmbiguityError) {
+            return engineError(error.code, error.message, { details: { candidates: error.candidates } });
+        }
         return engineError('E_INTERNAL', error instanceof Error ? error.message : String(error));
     }
 }
@@ -902,6 +963,9 @@ export async function nexusWhy(symbolId, projectRoot) {
         return engineSuccess(result);
     }
     catch (error) {
+        if (error instanceof KnowledgeSymbolAmbiguityError) {
+            return engineError(error.code, error.message, { details: { candidates: error.candidates } });
+        }
         return engineError('E_INTERNAL', error instanceof Error ? error.message : String(error));
     }
 }