brainclaw 1.24.0 → 1.26.0

package/dist/core/code-map/memory-reader.js

@@ -26,6 +26,12 @@ function coercePaths(raw) {
         return raw.filter((p) => typeof p === 'string');
     return [];
 }
+function optionalString(raw) {
+    return typeof raw === 'string' ? raw : undefined;
+}
+function optionalCount(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+}
 function toRelatedMemoryItem(kind, item) {
     return {
         id: typeof item.id === 'string' ? item.id : '',
@@ -33,6 +39,15 @@ function toRelatedMemoryItem(kind, item) {
         text: typeof item.text === 'string' ? item.text : '',
         tags: coerceTags(item.tags),
         related_paths: coercePaths(item.related_paths),
+        created_at: optionalString(item.created_at),
+        last_confirmed_at: optionalString(item.last_confirmed_at),
+        last_infirmed_at: optionalString(item.last_infirmed_at),
+        confirmation_count: optionalCount(item.confirmation_count),
+        infirmation_count: optionalCount(item.infirmation_count),
+        saved_me_count: optionalCount(item.saved_me_count),
+        misled_me_count: optionalCount(item.misled_me_count),
+        verified_at: optionalString(item.verified_at),
+        verify_cmd: optionalString(item.verify_cmd),
     };
 }
 /**

package/dist/core/code-map/query.js

@@ -11,8 +11,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { getLifecycleStats } from '../memory-lifecycle.js';
 import { hashContent } from './extractor.js';
-import { coarseFreshness } from './freshness.js';
+import { makeFreshnessBadge } from './freshness.js';
 import { readImportsIndex, readManifest, readResolutionIndex, readShard, readSymbolsIndex, } from './store.js';
 // --- lazy read-path freshness budget (spec §6.1) ---
 /** Default per-query lazy-check budget (spec §6.1). */
@@ -50,6 +51,7 @@ function budgetExhausted(checker) {
 }
 export function newAccumulator() {
     return {
+        checkedPaths: new Set(),
         staleChangedPaths: new Set(),
         missingPaths: new Set(),
         uncheckedPaths: new Set(),
@@ -76,6 +78,7 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     if (cached !== undefined)
         return cached;
     const abs = path.join(projectRoot, entry.path);
+    acc.checkedPaths.add(entry.path);
     let stat;
     try {
         stat = fs.statSync(abs);
@@ -151,46 +154,26 @@ export function validateStoreEntry(entry, checker, acc, cwd, preferredDirName) {
  * change/deletion yields `stale_changed_files`; else the manifest base status.
  */
 export function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex) {
-    const details = {};
-    if (acc.staleChangedPaths.size > 0) {
-        details.stale_changed_files = [...acc.staleChangedPaths].sort();
-    }
-    if (acc.missingPaths.size > 0) {
-        details.deleted_files = [...acc.missingPaths].sort();
-    }
-    if (acc.uncheckedPaths.size > 0) {
-        details.unchecked_files = [...acc.uncheckedPaths].sort();
-    }
-    let status = base;
-    if (emptyIndex && base !== 'missing_index') {
-        // §6.1 — zero confident matches: hint refresh rather than imply absence.
-        details.hint = 'missing_index_or_refresh';
-    }
-    if (acc.staleChangedPaths.size > 0 || acc.missingPaths.size > 0) {
-        status = 'stale_changed_files';
-    }
-    // §6.1.6 — `partial` means the lazy-check budget (file count / wall clock) ran
-    // out before we could validate everything. Reserve it for that cause only:
-    // unchecked-for-other-reasons (oversized file per §6.1.4, missing shard,
-    // unreadable file) must NOT be mislabeled as budget exhaustion. When the budget
-    // truly ran out, `partial` wins the top-line status — the agent should refresh
-    // before trusting the result — and the confirmed-stale list still rides along
-    // in `details.stale_changed_files`.
-    if (budgetExhausted || acc.budgetSkippedPaths.size > 0) {
-        status = 'partial';
-        details.partial_reason = 'lazy_check_budget_exhausted';
-        details.budget = { ...LAZY_BUDGET };
-    }
-    // pln#593 #2 — distinguish INDEX freshness (manifest state) from THIS call's
-    // read-path spot-check. When the call-level status diverges from the index
-    // status (a budget-limited `partial`, or a per-file `stale_changed_files` over a
-    // `fresh` index), surface the index status so an agent does not read
-    // status()=fresh vs find()/brief()=partial as a contradiction: it's "index
-    // <index_status>, this call's spot-check <status>".
-    if (status !== base)
-        details.index_status = base;
+    const hasStale = acc.staleChangedPaths.size > 0 || acc.missingPaths.size > 0;
+    const partial = budgetExhausted || acc.budgetSkippedPaths.size > 0;
+    const spotStatus = partial ? 'partial' : hasStale ? 'stale' : acc.checkedPaths.size > 0 ? 'fresh' : 'not_run';
+    const hint = emptyIndex && base !== 'missing_index' ? 'missing_index_or_refresh' : undefined;
     void hadConfidentMatch;
-    return { status, coarse: coarseFreshness(status), details };
+    // `base` stays the top-level index classification. A stale or budget-limited
+    // candidate spot-check is honest evidence, but it must not turn find()/brief()
+    // into a different badge than status()/work() for the same index state.
+    return makeFreshnessBadge(base, {
+        spotCheck: {
+            status: spotStatus,
+            checked_files: acc.checkedPaths.size,
+            stale_changed_files: [...acc.staleChangedPaths].sort(),
+            deleted_files: [...acc.missingPaths].sort(),
+            unchecked_files: [...acc.uncheckedPaths].sort(),
+            budget_exhausted: partial,
+            partial_reason: partial ? 'lazy_check_budget_exhausted' : null,
+        },
+        extra: hint ? { hint } : undefined,
+    });
 }
 const DEFAULT_FIND_LIMIT = 20;
 /** Lowercase token normalization mirroring indexes.ts (spec §5.6 keys). */
@@ -277,6 +260,58 @@ export function scoreEntry(entry, query) {
         score *= 0.4;
     return score;
 }
+/**
+ * Number of distinct indexed files that import a symbol (or its defining file).
+ *
+ * This is deliberately a tie-breaker, not a broad popularity boost: a precise
+ * textual match must always beat a merely popular substring match. The symbol
+ * and file reverse indexes can name the same importer, so count their UNION to
+ * avoid giving named imports a double bonus over namespace/default imports.
+ */
+export function importCentrality(entry, resolutionIndex) {
+    if (!resolutionIndex)
+        return 0;
+    const importers = new Set();
+    for (const dep of resolutionIndex.dependents_by_symbol[entry.node_id] ?? [])
+        importers.add(dep.path);
+    for (const dep of resolutionIndex.dependents_by_file[entry.path] ?? [])
+        importers.add(dep.path);
+    return importers.size;
+}
+/** A test-only helper is a weak orientation point when a file has real exports too. */
+function isTestHelperSymbol(name) {
+    const normalized = normIdent(name);
+    return (name.startsWith('_') ||
+        /(?:^|_)(?:test|tests|mock|stub|fixture|reset)(?:_|$)/i.test(name) ||
+        normalized.includes('fortest') ||
+        normalized.includes('fortests'));
+}
+/**
+ * Pick one meaningful definition per file for the reading-list explanation.
+ * A path brief resolves all symbols in that file; repeatedly adding +12 for
+ * each one made the result's reason depend on index order, which could select
+ * an internal `__reset…ForTests` helper ahead of the public entry point.
+ */
+function representativeDefinitions(defining) {
+    const byPath = new Map();
+    const relevance = (entry) => {
+        let score = entry.score_hint * 100; // public definitions before internals
+        if (entry.subtype === 'component' || entry.subtype === 'hook')
+            score += 2;
+        if (isTestHelperSymbol(entry.name))
+            score -= 50;
+        return score;
+    };
+    for (const entry of defining) {
+        const previous = byPath.get(entry.path);
+        if (!previous ||
+            relevance(entry) > relevance(previous) ||
+            (relevance(entry) === relevance(previous) && entry.name.localeCompare(previous.name) < 0)) {
+            byPath.set(entry.path, entry);
+        }
+    }
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
 function resolveRoot(ctx) {
     if (ctx.projectRoot)
         return ctx.projectRoot;
@@ -325,6 +360,7 @@ export function findInStore(query, ctx, checker, acc) {
     const root = resolveRoot(ctx);
     const maxBytes = maxParseBytes(ctx);
     const candidates = gatherSymbolEntries(index, query);
+    const resolutionIndex = readResolutionIndex(ctx.cwd, ctx.preferredDirName);
     const ranked = [];
     for (const entry of candidates) {
         // §6.1 — lazy validate before serving as confident.
@@ -332,17 +368,23 @@ export function findInStore(query, ctx, checker, acc) {
         if (!confident)
             continue;
         ranked.push({
-            node_id: entry.node_id,
-            name: entry.name,
-            path: entry.path,
-            file_id: entry.file_id,
-            kind: entry.kind,
-            subtype: entry.subtype ?? null,
-            score: scoreEntry(entry, query),
+            match: {
+                node_id: entry.node_id,
+                name: entry.name,
+                path: entry.path,
+                file_id: entry.file_id,
+                kind: entry.kind,
+                subtype: entry.subtype ?? null,
+                score: scoreEntry(entry, query),
+            },
+            centrality: importCentrality(entry, resolutionIndex),
         });
     }
-    ranked.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.name.localeCompare(b.name));
-    return { matches: ranked, base, hasIndex: true, emptyCandidates: candidates.length === 0, acc };
+    ranked.sort((a, b) => b.match.score - a.match.score ||
+        b.centrality - a.centrality ||
+        a.match.path.localeCompare(b.match.path) ||
+        a.match.name.localeCompare(b.match.name));
+    return { matches: ranked.map(({ match }) => match), base, hasIndex: true, emptyCandidates: candidates.length === 0, acc };
 }
 export function find(query, limit, ctx) {
     const checker = makeLazyChecker();
@@ -352,7 +394,7 @@ export function find(query, limit, ctx) {
         return {
             query,
             matches: [],
-            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+            freshness_badge: makeFreshnessBadge('missing_index', { extra: { hint: 'run refresh' } }),
         };
     }
     const capped = r.matches.slice(0, limit ?? DEFAULT_FIND_LIMIT);
@@ -361,43 +403,178 @@ export function find(query, limit, ctx) {
 }
 /** spec §11 — cap related memory at top 5 by relevance. */
 export const RELATED_MEMORY_CAP = 5;
+const MEMORY_JOIN_MIN_IDENTIFIER_LENGTH = 4;
+const MEMORY_JOIN_STOP_WORDS = new Set([
+    'default', 'module', 'index', 'main', 'test', 'tests', 'spec', 'react', 'node',
+]);
+function stableNames(names) {
+    const byNormalized = new Map();
+    for (const raw of names) {
+        const name = raw.trim();
+        const normalized = normIdent(name);
+        if (!normalized || byNormalized.has(normalized))
+            continue;
+        byNormalized.set(normalized, name);
+    }
+    return [...byNormalized.values()].sort((a, b) => a.localeCompare(b));
+}
+/** Avoid joining a prose memory to generic import noise such as `default` or `React`. */
+function memoryJoinTerms(names) {
+    return stableNames(names).filter((name) => {
+        const normalized = normIdent(name);
+        return normalized.length >= MEMORY_JOIN_MIN_IDENTIFIER_LENGTH
+            && !MEMORY_JOIN_STOP_WORDS.has(normalized)
+            && !isTestHelperSymbol(name);
+    });
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Identifier-aware, case-insensitive text match. The surrounding guards keep
+ * `Auth` from matching `author`, while still matching `ENTITY_REGISTRY` in a
+ * prose trap written as `entity_registry`.
+ */
+function textMentionsIdentifier(text, identifier) {
+    const escaped = escapeRegExp(identifier);
+    return new RegExp(`(^|[^A-Za-z0-9_$])${escaped}(?=$|[^A-Za-z0-9_$])`, 'i').test(text);
+}
+function isLifecycleMemoryKind(kind) {
+    return kind === 'decision' || kind === 'constraint' || kind === 'trap';
+}
+function validDate(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Make memory age explicit on the brief response. `verify_cmd` marks a
+ * perishable fact, so its empirical verification wins over the gentler
+ * lifecycle curve: missing verification is `unverified`, and one older than
+ * 30 days is `stale` (the same threshold used by memory anti-staleness).
+ */
+function describeMemoryFreshness(item) {
+    const verifiedAt = item.verified_at ?? null;
+    const verificationMs = validDate(item.verified_at);
+    const nowMs = Date.now();
+    if (item.verify_cmd) {
+        if (verificationMs === null) {
+            return { status: 'unverified', as_of: item.created_at ?? null, age_days: null, verified_at: verifiedAt };
+        }
+        const ageDays = Math.max(0, Math.floor((nowMs - verificationMs) / 86_400_000));
+        if (ageDays > 30)
+            return { status: 'stale', as_of: item.verified_at, age_days: ageDays, verified_at: verifiedAt };
+    }
+    if (!isLifecycleMemoryKind(item.kind) || validDate(item.created_at) === null) {
+        return { status: 'unknown', as_of: item.created_at ?? null, age_days: null, verified_at: verifiedAt };
+    }
+    const stats = getLifecycleStats({
+        entity: item.kind,
+        created_at: item.created_at,
+        last_confirmed_at: item.last_confirmed_at,
+        last_infirmed_at: item.last_infirmed_at,
+        confirmation_count: item.confirmation_count,
+        infirmation_count: item.infirmation_count,
+        saved_me_count: item.saved_me_count,
+        misled_me_count: item.misled_me_count,
+        nowMs,
+    });
+    return {
+        status: stats.classification,
+        as_of: stats.anchor_at,
+        age_days: stats.age_days,
+        verified_at: verifiedAt,
+    };
+}
 /**
  * Match memory items to a set of candidate file paths + the query symbol name
  * by (spec §11): related_paths, tags, or a literal file-path mention in the
  * memory text. Returns the top `RELATED_MEMORY_CAP` by relevance.
  */
-export function attachRelatedMemory(items, paths, symbolNames) {
+export function attachRelatedMemory(items, paths, symbolNames, importNames = []) {
     const pathSet = new Set(paths.map((p) => p.replace(/\\/g, '/')));
     const baseNames = new Set(paths.map((p) => path.basename(p)));
     const symLower = new Set(symbolNames.map((s) => s.toLowerCase()));
+    const symbolTerms = memoryJoinTerms(symbolNames);
+    const importTerms = memoryJoinTerms(importNames);
     const scored = [];
     for (const item of items) {
         let score = 0;
+        const sources = new Set();
         // related_paths — strongest signal.
         for (const rp of item.related_paths ?? []) {
             const norm = rp.replace(/\\/g, '/');
-            if (pathSet.has(norm))
+            if (pathSet.has(norm)) {
                 score += 5;
-            else if (baseNames.has(path.basename(norm)))
+                sources.add('related_path');
+            }
+            else if (baseNames.has(path.basename(norm))) {
                 score += 3;
+                sources.add('related_path_basename');
+            }
         }
         // literal file-path mention in the memory text.
         const text = item.text ?? '';
         for (const p of pathSet) {
-            if (text.includes(p))
+            if (text.includes(p)) {
                 score += 2;
+                sources.add('path_mention');
+            }
         }
         for (const bn of baseNames) {
-            if (text.includes(bn))
+            if (text.includes(bn)) {
                 score += 1;
+                sources.add('path_basename_mention');
+            }
         }
         // tags matching a symbol name (e.g. tag "App" / "useAuth").
         for (const tag of item.tags ?? []) {
-            if (symLower.has(tag.toLowerCase()))
+            if (symLower.has(tag.toLowerCase())) {
                 score += 2;
+                sources.add('symbol_tag');
+            }
+        }
+        // pln#601 amendment — response-local join from MEMORY TEXT to the names
+        // defined/imported by the brief target. We only admit identifier-shaped,
+        // non-test-helper terms and retain the exact terms as inspectable evidence.
+        const matchedSymbols = symbolTerms.filter((term) => textMentionsIdentifier(text, term));
+        const matchedImports = importTerms.filter((term) => textMentionsIdentifier(text, term));
+        if (matchedSymbols.length > 0) {
+            score += 4 * matchedSymbols.length;
+            sources.add('symbol_text');
+        }
+        if (matchedImports.length > 0) {
+            score += 3 * matchedImports.length;
+            sources.add('import_text');
+        }
+        if (score > 0) {
+            let confidence = 0.6;
+            if (sources.has('related_path'))
+                confidence = 1;
+            else if (sources.has('path_mention'))
+                confidence = 0.95;
+            else if (sources.has('related_path_basename'))
+                confidence = 0.85;
+            else if (sources.has('symbol_text'))
+                confidence = 0.82;
+            else if (sources.has('import_text'))
+                confidence = 0.72;
+            else if (sources.has('symbol_tag'))
+                confidence = 0.65;
+            const evidence = {
+                sources: [...sources].sort(),
+                matched_symbols: matchedSymbols,
+                matched_imports: matchedImports,
+                confidence,
+            };
+            // Clone: these response annotations must never mutate the records returned
+            // by the memory reader or be persisted into Code Map shards.
+            scored.push({
+                item: { ...item, match_evidence: evidence, memory_freshness: describeMemoryFreshness(item) },
+                score,
+            });
         }
-        if (score > 0)
-            scored.push({ item, score });
     }
     scored.sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id));
     return scored.slice(0, RELATED_MEMORY_CAP).map((s) => s.item);
@@ -436,7 +613,7 @@ function rankFiles(defining, forwardRows, reverseRows, symbolsIndex, importsInde
     };
     // 1. defining files — strongest, non-graph.
     const definingDirs = new Set();
-    for (const entry of defining) {
+    for (const entry of representativeDefinitions(defining)) {
         const subtypeNote = entry.subtype ? ` (${entry.subtype})` : '';
         bump(entry.path, entry.file_id, `defines matching symbol ${entry.name}${subtypeNote}`, 12, false);
         definingDirs.add(path.posix.dirname(entry.path.replace(/\\/g, '/')));
@@ -590,6 +767,24 @@ function reverseDeps(resolutionIndex, definingPaths, definingByNodeId) {
     }
     return [...byPath.values()];
 }
+function targetMemoryTerms(definingPaths, definingFileIds, nodeIndex, cwd, preferredDirName) {
+    const symbols = [...nodeIndex.values()]
+        .filter((entry) => definingPaths.has(entry.path))
+        .map((entry) => entry.name);
+    const imports = new Set();
+    for (const fileId of new Set(definingFileIds)) {
+        const shard = readShard(fileId, cwd, preferredDirName);
+        if (!shard)
+            continue;
+        for (const node of shard.nodes) {
+            if (node.kind !== 'module')
+                continue;
+            for (const imported of node.imported_names)
+                imports.add(imported);
+        }
+    }
+    return { symbolNames: stableNames(symbols), importNames: stableNames([...imports]) };
+}
 /**
  * Heuristic: does the brief target denote a file PATH rather than a bare symbol
  * name? A path separator or a supported source extension marks a path target —
@@ -604,13 +799,17 @@ function looksLikePathTarget(target) {
 /** Find files whose path matches the target directly (path-target briefs). */
 function filesMatchingPath(symbolsIndex, target) {
     const norm = target.replace(/\\/g, '/');
-    const seenPaths = new Set();
+    // Keep every symbol in the matching file. `rankFiles()` selects the one
+    // meaningful representative for the reason; deduping by path here used to
+    // retain whichever token bucket happened to be visited first (often an
+    // internal `__reset…ForTests` helper) and discarded the public entry point.
+    const seenNodeIds = new Set();
     const out = [];
     for (const bucket of Object.values(symbolsIndex.entries)) {
         for (const entry of bucket) {
             const p = entry.path.replace(/\\/g, '/');
-            if ((p === norm || p.endsWith(`/${norm}`) || p.includes(norm)) && !seenPaths.has(entry.path)) {
-                seenPaths.add(entry.path);
+            if ((p === norm || p.endsWith(`/${norm}`) || p.includes(norm)) && !seenNodeIds.has(entry.node_id)) {
+                seenNodeIds.add(entry.node_id);
                 out.push(entry);
             }
         }
@@ -631,6 +830,8 @@ export function briefInStore(target, ctx, checker, acc) {
         return {
             defining: [],
             definingPaths: new Set(),
+            memorySymbolNames: [],
+            memoryImportNames: [],
             matchKind: 'none',
             confident: [],
             base: 'missing_index',
@@ -686,6 +887,7 @@ export function briefInStore(target, ctx, checker, acc) {
             confidentDefiningFileIds.set(e.path, e.file_id);
     }
     const nodeIndex = buildNodeIdIndex(symbolsIndex);
+    const memoryTerms = targetMemoryTerms(definingPaths, defining.map((entry) => entry.file_id), nodeIndex, ctx.cwd, ctx.preferredDirName);
     const fwd = forwardDeps(confidentDefiningFileIds, nodeIndex, ctx.cwd, ctx.preferredDirName);
     const rev = reverseDeps(resolutionIndex, definingPaths, definingByNodeId);
     const ranked = rankFiles(defining, fwd, rev, symbolsIndex, importsIndex, target);
@@ -700,13 +902,25 @@ export function briefInStore(target, ctx, checker, acc) {
             continue;
         confident.push(rf);
     }
-    return { defining, definingPaths, matchKind, confident, base, hasIndex: true, emptyRanked: ranked.length === 0, acc };
+    return {
+        defining,
+        definingPaths,
+        memorySymbolNames: memoryTerms.symbolNames,
+        memoryImportNames: memoryTerms.importNames,
+        matchKind,
+        confident,
+        base,
+        hasIndex: true,
+        emptyRanked: ranked.length === 0,
+        acc,
+    };
 }
 /**
  * Attach related-memory ids per reading-list entry (spec §11). Shared by the
  * single-store brief() and the workspace aggregation so both surface memory identically.
  */
-export function attachMemoryIds(capped, related) {
+export function attachMemoryIds(capped, related, targetPaths = new Set()) {
+    const normalizedTargetPaths = new Set([...targetPaths].map((p) => p.replace(/\\/g, '/')));
     return capped.map((f) => {
         const ids = related
             .filter((m) => {
@@ -714,7 +928,9 @@ export function attachMemoryIds(capped, related) {
             const base2 = path.basename(fileNorm);
             const inPaths = (m.related_paths ?? []).some((rp) => rp.replace(/\\/g, '/') === fileNorm || path.basename(rp) === base2);
             const inText = (m.text ?? '').includes(fileNorm) || (m.text ?? '').includes(base2);
-            return inPaths || inText;
+            const symbolTextMatch = (m.match_evidence?.matched_symbols.length ?? 0) > 0
+                || (m.match_evidence?.matched_imports.length ?? 0) > 0;
+            return inPaths || inText || (normalizedTargetPaths.has(fileNorm) && symbolTextMatch);
         })
             .map((m) => m.id);
         return { path: f.path, reason: f.reason, score: f.score, related_memory_ids: ids };
@@ -729,7 +945,7 @@ export function brief(target, limit, ctx, memoryReader) {
             target,
             suggested_files_to_read: [],
             related_memory: [],
-            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+            freshness_badge: makeFreshnessBadge('missing_index', { extra: { hint: 'run refresh' } }),
         };
     }
     const cap = Math.min(limit ?? BRIEF_FILE_CAP, BRIEF_FILE_CAP);
@@ -737,11 +953,9 @@ export function brief(target, limit, ctx, memoryReader) {
     const capped = reserveSourceSlots(r.confident, cap, r.definingPaths);
     // Related memory (spec §11): match by the candidate paths + symbol names.
     const candidatePaths = capped.map((f) => f.path);
-    const symbolNames = [...new Set(r.defining.map((e) => e.name))];
-    if (symbolNames.length === 0)
-        symbolNames.push(target);
-    const related = attachRelatedMemory(memoryReader(ctx), candidatePaths, symbolNames);
-    const suggested = attachMemoryIds(capped, related);
+    const symbolNames = r.memorySymbolNames.length > 0 ? r.memorySymbolNames : [target];
+    const related = attachRelatedMemory(memoryReader(ctx), candidatePaths, symbolNames, r.memoryImportNames);
+    const suggested = attachMemoryIds(capped, related, r.definingPaths);
     const badge = deriveBadge(r.base, acc, checker.exhausted, capped.length > 0, r.emptyRanked);
     return { target, suggested_files_to_read: suggested, related_memory: related, freshness_badge: badge };
 }

package/dist/core/code-map/resolve.js

@@ -55,7 +55,7 @@ function edgesArrayEqual(a, b) {
     for (let i = 0; i < a.length; i++) {
         const x = a[i];
         const y = b[i];
-        if (x.id !== y.id || x.from !== y.from || x.to !== y.to || x.kind !== y.kind || x.confidence !== y.confidence) {
+        if (x.id !== y.id || x.from !== y.from || x.to !== y.to || x.kind !== y.kind || x.confidence !== y.confidence || x.origin !== y.origin) {
             return false;
         }
     }
@@ -77,6 +77,7 @@ export async function resolveProjectImports(input) {
     const ctx = {
         fileExists: (rel) => fileLang.has(toPosix(rel)),
         langOfFile: (rel) => fileLang.get(toPosix(rel)),
+        resolverConfig: input.resolverConfig,
     };
     // Target-file lookups for B: path -> shard, and a memoized importable index
     // (name -> importable symbols) per target file (built lazily, reused across importers).
@@ -100,9 +101,12 @@ export async function resolveProjectImports(input) {
         const provider = registry.providerForLang(shard.lang);
         // Non-pass-owned edges are preserved byte-identical (same order). Filtering BOTH
         // pass-owned kinds also strips any stale A/B edge from a prior run (idempotency).
-        const kept = shard.edges.filter((e) => !PASS_OWNED_EDGE_KINDS.has(e.kind));
+        const kept = shard.edges.filter((e) => !PASS_OWNED_EDGE_KINDS.has(e.kind) && e.origin !== 'usage_import');
         // Fresh pass-owned set (A resolves_to + B imports_symbol). Empty when no resolver.
         const fresh = [];
+        const seen = new Set();
+        // module + imported-name → unique target proven by imports_symbol below.
+        const resolvedImportedBindings = new Map();
         let freshSymbolCount = 0;
         if (provider?.resolveImport) {
             const seen = new Set();
@@ -148,11 +152,33 @@ export async function resolveProjectImports(input) {
                             continue; // dedup (duplicate names / re-imports)
                         seen.add(symId);
                         fresh.push({ id: symId, from: mod.id, to: target.id, kind: 'imports_symbol', confidence, source });
+                        resolvedImportedBindings.set(`${r.source}\0${name}`, target);
                         freshSymbolCount++;
                     }
                 }
             }
         }
+        // P4 imported-binding usages are emitted only after the exact `imports_symbol`
+        // proof above. If a module is unresolved, ambiguous, wildcard/default, or its
+        // target no longer exports the symbol, no call/reference edge survives.
+        for (const candidate of shard.reference_candidates ?? []) {
+            const target = resolvedImportedBindings.get(`${candidate.module}\0${candidate.imported_name}`);
+            if (!target)
+                continue;
+            const id = edgeId({ projectId, from: candidate.from, to: target.id, kind: candidate.kind });
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            fresh.push({
+                id,
+                from: candidate.from,
+                to: target.id,
+                kind: candidate.kind,
+                confidence: Math.min(clampConfidence(candidate.confidence), 1.0),
+                source: candidate.source,
+                origin: 'usage_import',
+            });
+        }
         // Single deterministic order over A+B so re-runs are byte-identical (from, to, kind).
         fresh.sort((a, b) => {
             if (a.from !== b.from)

package/dist/core/code-map/store.js

@@ -193,6 +193,7 @@ export function readResolutionIndex(cwd, preferredDirName) {
     // 'toString' (a path or node id) can't resolve to an inherited prototype member.
     parsed.data.dependents_by_file = Object.assign(Object.create(null), parsed.data.dependents_by_file);
     parsed.data.dependents_by_symbol = Object.assign(Object.create(null), parsed.data.dependents_by_symbol);
+    parsed.data.usages_by_symbol = Object.assign(Object.create(null), parsed.data.usages_by_symbol);
     return parsed.data;
 }
 export function writeResolutionIndex(index, cwd, preferredDirName) {