ucn 5.2.1 → 5.3.0

package/core/output/graph.js

@@ -21,7 +21,7 @@ function formatImports(imports, filePath) {
     if (internal.length > 0) {
         lines.push('INTERNAL:');
         for (const imp of internal) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.resolved) {
                 lines.push(`    -> ${imp.resolved}${imp.indexed === false
                     ? ' (not indexed; absent from dependency graph)'
@@ -37,7 +37,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0) lines.push('');
         lines.push('EXTERNAL:');
         for (const imp of external) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -48,7 +48,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0 || external.length > 0) lines.push('');
         lines.push('DYNAMIC (unresolved):');
         for (const imp of dynamic) {
-            lines.push(`  ${imp.module || '(variable)'}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module || '(variable)'}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -407,6 +407,22 @@ function formatGraphJson(graph) {
     return JSON.stringify(result, null, 2);
 }
 
+// fix #338: deferred-edge vocabulary shared by deps and cycle output.
+const DEFERRED_REASON_LABELS = {
+    'function-local': 'function-local import',
+    'type-checking': 'TYPE_CHECKING-only import, never executed at runtime',
+    'type-only': 'type-only import, erased at compile time',
+};
+function deferredReasonLabel(reason) {
+    return DEFERRED_REASON_LABELS[reason] || 'deferred import';
+}
+const EAGER_CYCLE_DISPLAY_LIMIT = 25;
+const DEFERRED_CYCLE_DISPLAY_LIMIT = 10;
+function deferredImportLabel(imp) {
+    if (!imp.deferred) return '';
+    return imp.deferredReason ? ` [deferred: ${imp.deferredReason}]` : ' [deferred]';
+}
+
 function formatCircularDeps(result) {
     if (!result) return 'No results.';
     const lines = [];
@@ -420,7 +436,7 @@ function formatCircularDeps(result) {
 
     const scannedCount = result.filesWithImports != null ? result.filesWithImports : result.totalFiles;
 
-    if (result.cycles.length === 0) {
+    if (result.cycles.length === 0 && !(result.components || []).length && !result.summary?.truncated) {
         lines.push('');
         lines.push('No circular dependencies found.');
         lines.push(`Scanned ${scannedCount} files with import relationships.`);
@@ -429,12 +445,32 @@ function formatCircularDeps(result) {
 
     const eager = result.cycles.filter(cycle => cycle.classification !== 'deferred');
     const deferred = result.cycles.filter(cycle => cycle.classification === 'deferred');
+
+    // Groups first: a strongly connected file set is the unit a refactor has
+    // to break, and a 14-file tangle can hold hundreds of elementary cycles.
+    const groups = result.components || [];
+    if (groups.length > 0) {
+        lines.push('');
+        lines.push(`CYCLE GROUPS (${groups.length}) — every member reaches every other member:`);
+        for (const group of groups) {
+            const counts = [];
+            if (group.eagerCycles != null) counts.push(`${group.eagerCycles} import-time`);
+            if (group.deferredCycles != null) counts.push(`${group.deferredCycles} deferred`);
+            const suffix = counts.length > 0 ? `  [${counts.join(', ')}${result.summary.truncated ? '; enumerated counts only' : ''}]` : '';
+            lines.push(`  ${group.size} files: ${group.files.join(', ')}${suffix}`);
+        }
+    }
+
     let cycleNumber = 0;
-    const renderGroup = (title, group, deferredGroup = false) => {
+    const renderGroup = (title, group, deferredGroup, displayLimit) => {
         if (group.length === 0) return;
+        const shown = group.slice(0, displayLimit);
         lines.push('');
-        lines.push(`${title} (${group.length}):`);
-        for (const cycle of group) {
+        const heading = shown.length < group.length
+            ? `${title} (${group.length}, showing ${shown.length} shortest):`
+            : `${title} (${group.length}):`;
+        lines.push(heading);
+        for (const cycle of shown) {
             cycleNumber++;
             lines.push('');
             lines.push(`Cycle ${cycleNumber} (${cycle.length} files):`);
@@ -442,19 +478,32 @@ function formatCircularDeps(result) {
             if (deferredGroup) {
                 for (const edge of cycle.deferredEdges || []) {
                     const at = edge.line != null ? `:${edge.line}` : '';
-                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (function-local import)`);
+                    const why = (edge.reasons || []).map(deferredReasonLabel).join('; ') || 'function-local import';
+                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (${why})`);
                 }
             }
         }
+        if (shown.length < group.length) {
+            lines.push(`  ... and ${group.length - shown.length} more (use --json for the full list)`);
+        }
     };
-    renderGroup('IMPORT-TIME CYCLES', eager);
-    renderGroup('DEFERRED CYCLES', deferred, true);
+    renderGroup('IMPORT-TIME CYCLES', eager, false, EAGER_CYCLE_DISPLAY_LIMIT);
+    renderGroup('DEFERRED CYCLES', deferred, true, DEFERRED_CYCLE_DISPLAY_LIMIT);
 
     lines.push('');
     const { totalCycles, filesInCycles } = result.summary;
     lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} (${scannedCount} files with imports scanned).`);
+    if (result.summary.truncated) {
+        if (result.summary.truncationReasons?.includes('component-size')) {
+            lines.push(`Cycle enumeration skipped groups larger than ${result.summary.maxComponentSize} files.`);
+        }
+        if (!result.summary.truncationReasons || result.summary.truncationReasons.includes('cycle-limit')) {
+            lines.push(`Enumeration stopped at ${result.summary.cycleLimit} elementary cycles.`);
+        }
+        lines.push('The CYCLE GROUPS list and files-in-cycles count are complete; enumerated cycle counts are lower bounds.');
+    }
     if (deferred.length > 0) {
-        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} contain a function-local import; they are not unconditional import-time cycles, but may still matter if invoked during initialization.`);
+        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} close only through deferred edges (function-local, TYPE_CHECKING-only, or type-only imports); they are not unconditional import-time cycles, but a function-local edge may still matter if invoked during initialization.`);
     }
 
     return lines.join('\n');

package/core/output/lines.js

@@ -0,0 +1,259 @@
+/**
+ * core/output/lines.js - grep-shaped and raw output modes (fix #341).
+ *
+ * `--lines`: one `path:line:text` record per line — the `grep -n` shape — so
+ * `ucn` composes with head/cut/xargs and reads like the tool agents already
+ * reach for in a shell. Everything that is not a record (ACCOUNT/CONTRACT
+ * lines, disambiguation, notes) follows the records as `# ` comment lines:
+ * the CLI routes those to stderr, MCP keeps them in its single text block.
+ * Records outside the confirmed tier carry a trailing `\t# tag`, so the
+ * `path:line:` prefix stays parseable while the tier stays visible.
+ *
+ * `--raw` (source): the code text and nothing else — no header, no gutter —
+ * so an agent can extract pristine text for an exact-string edit.
+ */
+'use strict';
+
+const { CALLABLE_SYMBOL_KINDS } = require('../shared');
+const { formatSurfaceMessage } = require('../registry');
+const { formatAccountLines, formatCalleeAccountLine } = require('./analysis');
+
+const LINES_COMMANDS = new Set(['find', 'usages', 'search', 'show', 'impact']);
+
+function record(pathLike, line, text, tag = '') {
+    // One record per line is the contract: a multi-line signature or a
+    // wrapped call expression folds onto one line, and the source line's
+    // indentation is dropped (a locate result needs the text, `--raw` has
+    // the layout).
+    const body = String(text == null ? '' : text).replace(/\s*\n\s*/g, ' ').trim();
+    // Keep unusual filenames from becoming notes or extra physical records.
+    let file = String(pathLike).replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+    if (file.startsWith('# ')) file = './' + file;
+    return `${file}:${line == null ? 0 : line}:${body}${tag ? `\t# ${tag}` : ''}`;
+}
+
+function commentLines(text) {
+    return String(text || '').split(/\r?\n/).filter(Boolean).map(line => `# ${line}`);
+}
+
+function signatureOf(symbol) {
+    const owner = symbol.className ? `${symbol.className}.` : '';
+    const callable = CALLABLE_SYMBOL_KINDS.has(symbol.type) || symbol.params != null;
+    // A multi-line parameter list folds onto one line and drops the trailing
+    // comma the source may carry before its closing paren.
+    const params = String(symbol.params || '').replace(/\s*\n\s*/g, ' ').replace(/,\s*$/, '');
+    return callable ? `${owner}${symbol.name}(${params})` : `${owner}${symbol.name}`;
+}
+
+function pathOf(entry) {
+    return entry.relativePath || entry.file || '';
+}
+
+function unverifiedTag(entry) {
+    const reason = entry.reason || 'unverified';
+    const via = entry.dispatchVia ? ` via ${entry.dispatchVia}` : '';
+    return `unverified: ${reason}${via}`;
+}
+
+function accountComments(account) {
+    if (!account) return [];
+    return [].concat(formatAccountLines(account) || [])
+        .join('\n').split('\n').filter(Boolean).map(line => `# ${line}`);
+}
+
+function findRecords(result) {
+    const out = [];
+    if (Array.isArray(result)) {
+        for (const symbol of result) out.push(record(pathOf(symbol), symbol.startLine, signatureOf(symbol), symbol.type));
+    } else if (result && Array.isArray(result.types)) {
+        for (const type of result.types) {
+            out.push(record(pathOf(type), type.startLine ?? type.line, type.name, type.type || type.kind));
+        }
+    }
+    return { records: out, notes: [] };
+}
+
+function usagesRecords(result) {
+    const out = [];
+    const notes = [];
+    for (const usage of Array.isArray(result) ? result : []) {
+        const kind = usage.isDefinition ? 'definition' : (usage.usageType || 'reference');
+        out.push(record(pathOf(usage), usage.line, usage.content, kind === 'call' ? '' : kind));
+    }
+    const counts = result && result.summaryCounts;
+    if (counts && counts.hiddenTestUsages > 0) {
+        notes.push(`# ${counts.hiddenTestUsages} test-file usage(s) hidden by default (--include-tests)`);
+    }
+    return { records: out, notes };
+}
+
+function searchRecords(result) {
+    const out = [];
+    const notes = [];
+    // Structural search (--type=...) returns { meta, results: [{file, line,
+    // name, kind, receiver, params?}] }; text search returns file groups.
+    if (result && !Array.isArray(result) && Array.isArray(result.results)) {
+        for (const item of result.results) {
+            const text = item.params != null ? `${item.name}(${item.params})` : item.name;
+            out.push(record(item.file, item.line, text, item.kind || item.type));
+        }
+        const meta = result.meta;
+        if (meta && meta.totalMatched > meta.shown) {
+            notes.push(`# ${meta.totalMatched - meta.shown} more match(es) (--limit=N / --all)`);
+        }
+        return { records: out, notes };
+    }
+    for (const item of Array.isArray(result) ? result : []) {
+        if (Array.isArray(item.matches)) {
+            for (const match of item.matches) out.push(record(item.file, match.line, match.content));
+        } else if (item.file != null && item.line != null) {
+            const text = item.content != null ? item.content : signatureOf(item);
+            out.push(record(pathOf(item), item.line, text, item.type || item.kind));
+        }
+    }
+    const meta = result && result.meta;
+    if (meta && meta.filesSkipped > 0) {
+        notes.push(`# ${meta.filesSkipped} test file(s) hidden by default (--include-tests)`);
+    }
+    if (meta && meta.truncatedMatches > 0) {
+        notes.push(`# ${meta.truncatedMatches} more match(es) omitted by --top/--limit`);
+    }
+    return { records: out, notes };
+}
+
+function callerRecords(context) {
+    const out = [];
+    for (const caller of context.callers || []) {
+        const tag = caller.tier && caller.tier !== 'confirmed' ? unverifiedTag(caller) : '';
+        out.push(record(pathOf(caller), caller.line, caller.content, tag));
+    }
+    for (const caller of context.unverifiedCallers || []) {
+        out.push(record(pathOf(caller), caller.line, caller.content, unverifiedTag(caller)));
+    }
+    return out;
+}
+
+function showRecords(result, params = {}) {
+    const out = [];
+    const notes = [];
+    const context = result && result.context;
+    // Only an EXPLICIT --sections selects the band: the resolved defaults
+    // (summary, callers, callees) would mix callee records into a caller
+    // listing and skew `cut -d: -f1 | sort | uniq -c`.
+    const explicit = (Array.isArray(params.sections) ? params.sections : String(params.sections || '').split(','))
+        .map(s => String(s).trim().toLowerCase()).filter(Boolean);
+    const selected = new Set(explicit.length > 0 ? explicit : ['callers']);
+    if (context) {
+        if (selected.has('callers')) out.push(...callerRecords(context));
+        if (selected.has('callees')) {
+            for (const callee of context.callees || []) {
+                const count = callee.callCount > 1 ? ` x${callee.callCount}` : '';
+                out.push(record(pathOf(callee), callee.startLine, signatureOf(callee), `callee${count}`));
+            }
+            for (const callee of context.unverifiedCallees || []) {
+                for (const site of callee.sites || []) {
+                    out.push(record(pathOf(context), site, callee.name, `${unverifiedTag(callee)}; callee`));
+                }
+            }
+        }
+        notes.push(...accountComments(context.meta && context.meta.account));
+        if (context.meta && context.meta.calleeAccount && selected.has('callees')) {
+            notes.push(`# ${formatCalleeAccountLine(context.meta.calleeAccount)}`);
+        }
+    }
+    if (result && result.target && result.target.alternatives && result.target.alternatives.length > 0) {
+        notes.push(`# ${result.target.alternatives.length + 1} definitions; using ${result.target.handle || result.target.file}. Pass a file:line:name handle to pin another.`);
+    }
+    return { records: out, notes };
+}
+
+function impactRecords(result) {
+    const out = [];
+    const notes = [];
+    if (!result) return { records: out, notes };
+    if (Array.isArray(result.functions)) {
+        for (const fn of result.functions) {
+            out.push(...callerRecords(fn));
+            notes.push(...accountComments(fn.account));
+        }
+        for (const fn of result.deletedFunctions || []) {
+            for (const site of fn.remainingCallSites || []) {
+                out.push(record(pathOf(site), site.line, site.content, 'unverified: deleted-target-name-match'));
+            }
+        }
+        const summary = result.summary || {};
+        notes.push(`# Diff: ${summary.modifiedFunctions || 0} modified, ${summary.newFunctions || 0} new, ${summary.deletedFunctions || 0} deleted functions; ${(result.moduleLevelChanges || []).length} file(s) with module-level changes.`);
+        if (result.nonSourcePaths) notes.push(`# ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
+        return { records: [...new Set(out)], notes };
+    }
+    for (const group of result.byFile || []) {
+        for (const site of group.sites || []) {
+            const tag = site.tier && site.tier !== 'confirmed' ? unverifiedTag(site) : '';
+            out.push(record(group.file, site.line, site.expression, tag));
+        }
+    }
+    for (const site of result.unverifiedSites || []) {
+        out.push(record(pathOf(site), site.line, site.content || site.expression, unverifiedTag(site)));
+    }
+    if (result.propertyAccesses) {
+        const accesses = result.propertyAccesses;
+        for (const group of accesses.byFile || []) {
+            for (const access of group.sites || []) {
+                out.push(record(group.file, access.line, access.expression, 'property-access'));
+            }
+        }
+        for (const access of accesses.unverifiedSites || []) {
+            out.push(record(pathOf(access), access.line, access.expression, `${unverifiedTag(access)}; property-access`));
+        }
+        notes.push(`# PROPERTY ACCESS SITES: ${accesses.confirmedCount} confirmed, ${accesses.unverifiedCount} unverified, ${accesses.excluded?.total || 0} other-target (separate from caller ACCOUNT).`);
+    }
+    notes.push(...accountComments(result.account));
+    for (const warning of result.warnings || []) notes.push(...commentLines(warning.message));
+    if (result.scopeWarning?.hint) notes.push(...commentLines(result.scopeWarning.hint));
+    if (result.shownCallSites < result.totalCallSites) {
+        notes.push(`# ${result.totalCallSites - result.shownCallSites} more call site(s) omitted by --top/--limit`);
+    }
+    return { records: out, notes };
+}
+
+/**
+ * Render a public command result as grep-shaped records followed by `# `
+ * comment lines. Returns '' when the command has nothing to list.
+ */
+function formatPublicLines(command, result, params = {}, execution = {}) {
+    let shaped;
+    switch (command) {
+        case 'find': shaped = findRecords(result); break;
+        case 'usages': shaped = usagesRecords(result); break;
+        case 'search': shaped = searchRecords(result); break;
+        case 'show': shaped = showRecords(result, params); break;
+        case 'impact': shaped = impactRecords(result); break;
+        default: return null;
+    }
+    const lines = [...shaped.records, ...shaped.notes];
+    if (execution.note) lines.push(...commentLines(execution.note));
+    return lines.map(line => line.startsWith('# ')
+        ? commentLines(formatSurfaceMessage(line.slice(2), execution.surface)).join('\n') : line).join('\n');
+}
+
+/**
+ * Render a `source` result as the code text alone.
+ */
+function formatPublicRaw(result, execution = {}) {
+    let code = '';
+    if (result && Array.isArray(result.lines)) code = result.lines.join('\n');
+    else if (result && Array.isArray(result.entries)) {
+        code = result.entries.map(entry => entry.code == null ? '' : String(entry.code)).join('\n\n');
+    } else if (result && typeof result.code === 'string') code = result.code;
+    // A note (the same-name disambiguation, a hidden-section warning) must
+    // not vanish in raw mode. Code lines are never reinterpreted, so it
+    // cannot ride inside the text: the CLI prints `execution.note` to stderr
+    // itself (see emitCliText); the single-block surfaces get it appended as
+    // one trailing `# ` line after the code.
+    if (execution.note && execution.surface !== 'cli') {
+        return `${code.replace(/\n$/, '')}\n${commentLines(execution.note).join('\n')}`;
+    }
+    return code;
+}
+
+module.exports = { LINES_COMMANDS, formatPublicLines, formatPublicRaw, commentLines };

package/core/output/public.js

@@ -11,6 +11,7 @@
 const { COMMAND_CONTRACTS } = require('../command-contracts');
 const { COMMAND_TRUST_MATRIX } = require('../trust-matrix');
 const { toCliName, toMcpName, formatSurfaceMessage } = require('../registry');
+const { LINES_COMMANDS, formatPublicLines, formatPublicRaw } = require('./lines');
 
 const legacy = {
     ...require('./analysis'),
@@ -274,6 +275,20 @@ function formatRepo(result, params = {}, hints = presentationHints()) {
 }
 
 function formatPublicText(command, result, params = {}, execution = {}) {
+    // Grep-shaped and raw modes (fix #341): the agent-in-a-shell surface.
+    if (params.raw && command === 'source') {
+        return formatPublicRaw(result, {
+            ...execution,
+            note: execution.note ? formatSurfaceMessage(execution.note, execution.surface) : undefined,
+        });
+    }
+    if (params.lines && LINES_COMMANDS.has(command)) {
+        const shaped = formatPublicLines(command, result, params, {
+            ...execution,
+            note: execution.note ? formatSurfaceMessage(execution.note, execution.surface) : undefined,
+        });
+        if (shaped != null) return shaped;
+    }
     const hints = presentationHints(execution.surface);
     if (result?.scopeWarning?.hint) {
         result.scopeWarning = {

package/core/output/reporting.js

@@ -1,6 +1,7 @@
 /**
  * core/output/reporting.js - Stats/TOC/deadcode/entrypoints formatters
  */
+const path = require('path');
 
 const {
     lineRange,
@@ -457,7 +458,10 @@ function formatEntrypointsJson(results) {
  */
 function formatOrient(result, options = {}) {
     const lines = [];
-    lines.push(`PROJECT ORIENTATION — ${result.root}${result.scope ? ` (scoped to ${result.scope})` : ''}`);
+    // The title names the project (fix #343); the absolute root is the
+    // caller's own argument and `--sections=stats` prints it in full.
+    const projectName = path.basename(String(result.root || '')) || String(result.root || '');
+    lines.push(`PROJECT ORIENTATION — ${projectName}${result.scope ? ` (scoped to ${result.scope})` : ''}`);
     lines.push('═'.repeat(60));
 
     // Size + language mix (percent by symbols, largest first)
@@ -486,7 +490,10 @@ function formatOrient(result, options = {}) {
         const population = result.hot.totalKind === 'raw-call-candidates'
             ? `${result.hot.total} raw candidates`
             : result.hot.total;
-        lines.push(`HOT (most-called ${scope}, top ${result.hot.items.length} of ${population}):`);
+        const budgetNote = result.hot.budgetExhausted
+            ? `; refinement budget ${result.hot.maxRefine} reached — ranking approximate, exact list: ucn repo --sections=stats --hot`
+            : '';
+        lines.push(`HOT (most-called ${scope}, top ${result.hot.items.length} of ${population}${budgetNote}):`);
         for (const h of result.hot.items) {
             const label = h.className ? `${h.className}.${h.name}` : h.name;
             lines.push(`  ${label} — ${h.callCount} call(s) · ${h.file}:${h.line}`);

package/core/output-budget.js

@@ -33,18 +33,21 @@ function preservedContractMetadata(fullText, visibleText, options = {}) {
         // one physical line. Preserve the actionable test-scope contract as
         // its own sentence so a later parse-failure note cannot make the
         // whole metadata item too large for a small transport budget.
-        const firstSentenceEnd = /^\s*\d+ test-file usage\(s\) hidden\b/.test(rawLine)
+        const firstSentenceEnd = /^\s*(?:# )?\d+ test-file usage\(s\) hidden\b/.test(rawLine)
             ? rawLine.indexOf('. ')
             : -1;
         const contractLine = firstSentenceEnd >= 0
             ? rawLine.slice(0, firstSentenceEnd + 1)
             : rawLine;
-        if (!CONTRACT_LINE_RE.test(contractLine)) continue;
+        // Shell-shaped MCP/interactive results prefix disclosures with '# '.
+        // Match their contents but retain the prefix in the preserved text.
+        const evidenceLine = contractLine.replace(/^\s*# /, '').trim();
+        if (!CONTRACT_LINE_RE.test(evidenceLine)) continue;
         const line = contractLine.trim();
         if (!line || visible.has(line)) continue;
-        const priority = /^(?:ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT):/.test(line)
+        const priority = /^(?:ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT):/.test(evidenceLine)
             ? 0
-            : /^\d+ test-file usage\(s\) hidden\b/.test(line) ? 1 : 2;
+            : /^\d+ test-file usage\(s\) hidden\b/.test(evidenceLine) ? 1 : 2;
         candidates.push({ line, priority, sourceIndex });
     }
 

package/core/project.js

@@ -79,8 +79,33 @@ class ProjectIndex {
         this._opLinesCache = null;       // per-operation split-lines cache (Map<filePath, string[]>, bounded FIFO)
         this._opInnerSymbolRangesCache = null; // per-operation sorted class-method ranges by file
         this._opFlowTypeOriginCache = null; // per-operation annotation type identity results
+        this._opCppTypeCategoryCache = null; // per-operation normalized C++ parameter categories
+        this._opCppPathReceiverTypeCache = null; // per-operation C++ qualified receiver identity
+        this._opDerefPairs = null;      // per-operation Rust Deref identity pairs
+        this._opAliasPairs = null;      // per-operation language type-alias identity pairs
         this._parsedTreeCache = new Map(); // cross-operation LRU: filePath -> immutable tree entry
         this._parsedTreeCacheSourceBytes = 0;
+        // Cross-operation, content-hash-keyed usage classifications. Account
+        // queries often ask several projections for the same hot symbol; the
+        // AST answer is immutable until the file hash changes. Bounded by
+        // both entries and approximate payload size to avoid turning a warm
+        // MCP process into an unbounded repository mirror.
+        this._usageResultCache = new Map();
+        this._usageResultCacheWeight = 0;
+        this.usageCacheDirty = false;
+        // Exact text-ground sets are likewise immutable for one built index.
+        // The cache is cleared at every build and bounded in account.js.
+        this._groundSetCache = new Map();
+        this._groundSetCacheLines = 0;
+        // Bounded cross-operation memo for immutable name-level export
+        // ownership. Agent workflows ask show/impact/tests about related
+        // symbols in sequence; retaining these tri-state barrel verdicts
+        // avoids repeating the same bounded graph walks after every command.
+        this._nameBindingReachCache = new Map();
+        // Query-derived return flow depends on cross-file annotations and is
+        // deliberately never persisted. It is safe across commands only
+        // until the next build, which resets it below.
+        this._returnTypeFlowCache = new Map();
         this.calleeIndex = null;         // name -> Set<filePath> — inverted call index (built lazily)
     }
 
@@ -120,6 +145,11 @@ class ProjectIndex {
             this._opInnerSymbolRangesCache = new Map();
             this._opFlowTypeOriginCache = new Map();
             this._opImportReachCache = new Map();
+            this._opCppTypeCategoryCache = new Map();
+            this._opCppPathReceiverTypeCache = new Map();
+            this._opDerefPairs = undefined;
+            this._opAliasPairs = undefined;
+            this._opFindCallersCaches = null; // fix #340: findCallers per-file derivations
             this._opDepth = 0;
         }
         this._opDepth++;
@@ -145,6 +175,11 @@ class ProjectIndex {
             this._opInnerSymbolRangesCache = null;
             this._opFlowTypeOriginCache = null;
             this._opImportReachCache = null;
+            this._opCppTypeCategoryCache = null;
+            this._opCppPathReceiverTypeCache = null;
+            this._opDerefPairs = null;
+            this._opAliasPairs = null;
+            this._opFindCallersCaches = null;
             // Free cached file content from callsCache entries (retained during
             // operation for _readFile caching, not needed between operations)
             for (const entry of this.callsCache.values()) {
@@ -255,15 +290,38 @@ class ProjectIndex {
      * multiple times within one operation (e.g., about() calls both countSymbolUsages and usages).
      * @param {string} filePath - File to scan
      * @param {string} name - Symbol name to find
+     * @param {object} [options]
+     * @param {boolean} [options.skipCallRecovery] - omit usage-only call
+     * recovery when the caller has already classified lines from the call index
      * @returns {Array|null} Array of usage objects or null if parsing failed
      */
-    _getCachedUsages(filePath, name) {
-        const cacheKey = `${filePath}\0${name}`;
+    _getCachedUsages(filePath, name, options = {}) {
+        // Account construction checks the complete calls cache before it asks
+        // the language adapter to classify the remaining name occurrences.
+        // C/C++ can therefore skip its expensive macro replacement-list call
+        // recovery in that mode. Partition both cache layers so a partial
+        // account classification can never poison the full `usages` result.
+        const mode = [
+            options.skipCallRecovery ? 'skip-call-recovery' : '',
+        ].filter(Boolean).join('+');
+        const modeSuffix = mode ? `\0${mode}` : '';
+        const cacheKey = `${filePath}\0${name}${modeSuffix}`;
         if (this._opUsagesCache) {
             const cached = this._opUsagesCache.get(cacheKey);
             if (cached !== undefined) return cached;
         }
 
+        const fileHash = this.files.get(filePath)?.hash || '';
+        const persistentKey = `${filePath}\0${fileHash}\0${name}${modeSuffix}`;
+        if (this._usageResultCache?.has(persistentKey)) {
+            const cached = this._usageResultCache.get(persistentKey);
+            // Map insertion order is the LRU order.
+            this._usageResultCache.delete(persistentKey);
+            this._usageResultCache.set(persistentKey, cached);
+            if (this._opUsagesCache) this._opUsagesCache.set(cacheKey, cached.value);
+            return cached.value;
+        }
+
         // Header language is resolved during indexing from compilation
         // databases/include context. Re-detecting `.h` here can choose C for
         // a C++ header and silently drop member/template usages from the raw
@@ -292,10 +350,26 @@ class ProjectIndex {
                 !langModule.managesOwnParseTree
                 ? this._getParsedTree(filePath, content, lang)
                 : null;
-            const usages = langModule.findUsagesInCode(content, name, parser, tree);
+            const usages = langModule.findUsagesInCode(
+                content, name, parser, tree, options);
             if (this._opUsagesCache) {
                 this._opUsagesCache.set(cacheKey, usages);
             }
+            if (Array.isArray(usages) && this._usageResultCache) {
+                const weight = 64 + usages.length * 40;
+                this._usageResultCache.set(persistentKey, { value: usages, weight });
+                this._usageResultCacheWeight += weight;
+                this.usageCacheDirty = true;
+                const maxEntries = 4096;
+                const maxWeight = 16 * 1024 * 1024;
+                while (this._usageResultCache.size > maxEntries ||
+                    this._usageResultCacheWeight > maxWeight) {
+                    const oldest = this._usageResultCache.entries().next().value;
+                    if (!oldest) break;
+                    this._usageResultCache.delete(oldest[0]);
+                    this._usageResultCacheWeight -= oldest[1].weight;
+                }
+            }
             return usages;
         } catch (e) {
             return null;
@@ -327,6 +401,14 @@ class ProjectIndex {
         const startTime = Date.now();
         const quiet = options.quiet !== false;
 
+        // Build/discovery can add, remove, or reclassify files. Do not retain
+        // a text-universe answer across that boundary. Hash-keyed usage
+        // results remain safe and useful for unchanged files.
+        this._groundSetCache = new Map();
+        this._groundSetCacheLines = 0;
+        this._nameBindingReachCache = new Map();
+        this._returnTypeFlowCache = new Map();
+
         // A (re)build invalidates any cache-loaded reachability set — the
         // fingerprint guard in computeReachability is content-shaped and
         // cannot see every rebuild (fix #249: a stale loaded set survived
@@ -1169,7 +1251,7 @@ class ProjectIndex {
         const typeOrder = new Set([
             'class', 'struct', 'interface', 'type', 'impl', 'enum', 'record',
         ]);
-        const { isTestPath } = require('./shared');
+        const { isTestPath, CALLABLE_SYMBOL_KINDS } = require('./shared');
         const scored = definitions.map(d => {
             let score = 0;
             const rp = d.relativePath || '';
@@ -1200,10 +1282,21 @@ class ProjectIndex {
             // Deprioritize type-only overload signatures (TypeScript function_signature)
             if (d.isSignature) score -= 200;
             // Prefer larger function bodies (implementation over overload signature)
-            // Only for functions/methods — not for class-level types (struct vs impl)
+            // Only for functions — not for class-level types (struct vs impl).
+            // Same-named METHODS keep tying here on purpose: widening this to
+            // every callable kind reshuffled method-vs-method picks project-wide
+            // (httpx `send`), which is not the fix #343 defect.
             if (d.startLine && d.endLine && d.type === 'function') {
                 score += Math.min(d.endLine - d.startLine, 100);
             }
+            // Fix #343: a bare name denotes the CALLABLE when a field shares it.
+            // A Rust/Go/Java method used to tie with a same-named field (the
+            // builder idiom: `heap_limit` field + `heap_limit(&mut self)` setter)
+            // and lose on file order, so `impact heap_limit` answered 0 call
+            // sites against the field while the setter had 10 confirmed callers.
+            // Callable kinds tie among themselves as before; only the
+            // callable-vs-field tie is decided (a zero-line Java getter too).
+            if (CALLABLE_SYMBOL_KINDS.has(d.type)) score += 25;
             // Prefer shallower paths (fewer directory levels = more central to project)
             // Max bonus 50 for root-level files, decreasing with depth
             const depth = (rp.match(/\//g) || []).length;
@@ -2414,6 +2507,11 @@ class ProjectIndex {
     /** Load index from cache file */
     loadCache(cachePath) { return indexCache.loadCache(this, cachePath); }
 
+    /** Persist the bounded, content-hash-keyed usage-query cache. */
+    saveUsageCache(cachePath = undefined) {
+        return indexCache.saveUsageCache(this, cachePath);
+    }
+
     /** Return this project's default per-user cache file path. */
     getCachePath() { return indexCache.getProjectCachePath(this.root); }