ucn 5.4.2 → 5.5.1

package/.claude/skills/ucn/references/trust-contract.md

@@ -4,62 +4,59 @@ Use this reference when an agent, CI job, or script will make decisions from UCN
 
 ## Evidence classes
 
-`confirmed` means UCN found positive identity evidence such as an exact binding, a same-class target, a validated receiver type, or an owned import/export chain. It does not mean the edge has a calibrated probability.
+`confirmed` means UCN found positive identity evidence such as an exact binding, a target on the same class definition (a same-name class in another module does not count), a validated receiver type, or an owned import/export chain. It does not mean the edge has a calibrated probability.
 
-`unverified` means a syntactic candidate could reach the target but identity could not be established. Preserve and expose these edges. Do not silently treat them as negatives.
+`unverified` means a syntactic candidate could reach the target but identity could not be established. Each carries the engine reason (`possible-dispatch`, `single-owner`, `method-ambiguous`, `overload-ambiguous`, `configuration-alternative`, ...; the per-language meanings are in [resolution-rules.md](resolution-rules.md)). Preserve and expose these edges. Do not silently treat them as negatives.
 
-`excluded` means the engine found evidence for a different definition, an incompatible receiver, an external package, an unrelated runtime-language boundary, an arity mismatch, or another stated reason. Inspect excluded reasons when investigating an accuracy issue.
+`excluded` means the engine found evidence for a different definition, an incompatible receiver, an external package, an unrelated runtime-language boundary, an arity mismatch, or another stated reason. Excluded sites are counted in `ACCOUNT` as other-target lines and exposed with their reasons under `account.excluded` in JSON. Inspect them when investigating an accuracy issue.
 
-`non-call` means the literal name occurred as a definition, import, type reference, property, comment/string, or other text. Use `usages` for the underlying sites; comment/string occurrences appear under `OTHER TEXT` unless `codeOnly=true`.
+`non-call` means the literal name occurred as a definition, import, type reference, property, comment/string, or other text. Use `usages` for the underlying sites; comment/string occurrences appear under `OTHER TEXT` unless `--code-only` (`code_only=true`).
 
-`beyond-text` means semantic binding or alias evidence produced an edge that a literal-name ground set could not observe.
+`beyond-text` means semantic binding or alias evidence produced an edge that a literal-name ground set could not observe (Rust `use m::f as g; g()`, a call generated by a macro expansion). A reflective access whose member name is built at runtime from literal fragments (`getattr(self, "_get_%s_perms" % src)`) is also beyond text: it is listed as an unverified caller with reason `reflection-pattern` and the pattern, never confirmed. A Java single-element annotation (`@Marker("x")`) sets the element `value` without naming it: it is listed as an unverified caller of that element with reason `annotation-shorthand`, and `plan` names the element there when the annotation type resolves.
+
+## Trust lines
+
+Every caller-bearing answer ends with trust lines that truncation preserves:
+
+- `ACCOUNT` partitions every line where the name occurs: confirmed, unverified, non-call (import, definition, reference, other text), other-target, unaccounted. In mixed-language repositories it also counts occurrences in unsupported-language source files.
+- `CONTRACT` states the scope of that partition. When unsupported-language files contain the name, it says so and limits the partition-complete claim to supported languages. Semantic completeness is never claimed.
+- `WARNING` identifies unreadable, unparsed, or partially indexed files (including `git-listing-failed`), lines in syntax-error recovery regions, and unsupported-language occurrence sites (file:line plus the line text). `usages` and `tests` carry the same disclosure as a note.
+- `FILTERED` means query options hid evidence.
+- `CALLEE ACCOUNT` partitions a function's call sites (confirmed, unverified, external/builtin, excluded, filtered); `TREE ACCOUNT` does the same for the interior of a caller-direction `trace`.
 
 ## Conservation scope
 
-The caller account partitions a literal-name text-occurrence ground set. A conserved account answers: “Did UCN explain every observed literal-name line?” It does not answer: “Did UCN discover every semantically possible runtime caller?”
+The caller account partitions a literal-name text-occurrence ground set. A conserved account answers: "Did UCN explain every observed literal-name line?" It does not answer: "Did UCN discover every semantically possible runtime caller?"
 
 Required automation checks:
 
 1. `account.conserved` is true.
 2. `account.contract.textComplete` is true.
-3. No unreadable or unparsed files are reported.
+3. No unreadable or unparsed files are reported, and no ground line sits in a syntax-error recovery region (`account.recovered`, WARNING line).
 4. No contract metadata was lost to truncation.
 5. Unverified and excluded reasons are retained for review.
-6. Compiler/LSP evaluation reports keep configuration-unscored evidence below the release ceiling; a high-precision result from an undersized scored subset is not accepted.
-7. The release review-burden board passes: true edges left unverified, zero-actionable-ambiguity target rate, actionable candidate p95, and effective unverified review items per oracle edge all remain within the published budget. Raw false candidates remain reported separately.
-8. The deterministic cross-command board reports zero disagreements: overlapping `find`, `show`, `source`, `impact`, `tests`, `check`, and caller `trace` claims resolve the same stable handle to the same identity, projections, caller tiers, evidence reasons, totals, and caller account.
 
-Even when all eight hold, `account.contract.semanticComplete` remains false. Use compiler/type-checker, test, runtime, and framework evidence for semantic decisions.
+Even when all five hold, `account.contract.semanticComplete` remains false. Use compiler/type-checker, test, runtime, and framework evidence for semantic decisions.
 
-`account.contract.observedTextZero` is safe only for the claim “the complete observed literal-name ground set contained no caller candidates or beyond-text edges.” It is explicitly not safe-delete proof.
+`account.contract.observedTextZero` is safe only for the claim "the complete observed literal-name ground set contained no caller candidates or beyond-text edges." It is explicitly not safe-delete proof.
 
 ## Numeric fields
 
-`evidenceScore` (and the legacy `confidence` alias where present) is an ordinal weight used for ordering and thresholding evidence classes. `scoreKind` is `ordinal-evidence-not-probability`. Never display it as measured accuracy or use it as a probability in risk calculations.
-
-## Unverified review burden
+`evidenceScore` (and the `confidence` alias where present) is an ordinal weight used for ordering and thresholding evidence classes. `scoreKind` is `ordinal-evidence-not-probability`. Never display it as measured accuracy or use it as a probability in risk calculations.
 
-Semantic recall can be complete while the result is still impractical: a true edge may be present only in a large unverified set. Release evaluation therefore measures both placement and the amount of review an agent must perform.
+## Provenance
 
-- `trueEdgeUnverifiedRate` is the share of statically exact oracle edges found only in the unverified tier. Runtime-polymorphic, compiler-dependent template, and oracle-unresolved references remain in the all-oracle view but never inflate the exact denominator.
-- `zeroActionableUnverifiedTargetRate` is the share of reviewed targets with no actionable ambiguity.
-- `actionableUnverifiedCandidatesP50`, `actionableUnverifiedCandidatesP95`, and `actionableUnverifiedCandidatesMax` measure actionable candidate-set size per target.
-- `unverifiedReviewItemsPerOracleEdge` measures effective review work relative to the oracle workload. Actionable false candidates count individually; each named runtime-dispatch family counts once.
-- `rawFalseUnverifiedPerOracleEdge` preserves the ungrouped false-candidate amplification for auditability.
-- `runtimeDependentOracleEdges`, `compilerDependentOracleEdges`, and `oracleAbstentionEdges` disclose why all-oracle coverage is broader than exact target identity.
-- `unverifiedReasons` groups candidates by the engine reason that kept them out of the confirmed tier.
+Caller and callee JSON carries compact `provenance`: `rule`, contributing `rules` when there is more than one, `validation`, and the receiver's source and origin line when recorded. Incomplete proofs include a `diagnostic`, also shown in text. Callees retain compact `siteProvenance` for each distinct occurrence; their summary uses the weakest confirmed site's rule. Exclusions expose counts by rule and validation under `account.excluded.evidenceSummary`.
 
-Configuration-gated candidates remain visible but are not labeled false when the compiler/LSP oracle did not score them. The raw JSON rollup is the source of truth for these fields; the Markdown report is generated from the same data.
+A lone project owner of a method name does not identify an untyped receiver. Such candidates stay unverified with `single-owner`; importing the class does not change that. `provenance-incomplete` means the available facts cannot establish this declaration. Inspect the site and diagnostic before editing it. Neither reason is permission to discard a possible caller. `validation: unsupported` means the witness collector does not cover that path (for example a wildcard re-export or an external inherited member); the existing classification is kept in report-only mode and is not a validated proof. Missing or inconsistent facts on a supported lookup still route unverified.
 
-The publish-blocking portable-AST ceilings are: at most 10% of exact true edges left unverified, at most 20% within any sufficiently sampled symbol kind, at least 80% of targets with zero actionable ambiguity, actionable-candidate p95 at most five, and at most 0.10 effective review items per oracle edge. The semantic gate separately requires 100% in-scope recall, at least 98% confirmed-tier precision, full conservation, and 100% public-command proof recall. Three class-aware floors gate at zero: unaccounted oracle edges of the exact, runtime-dispatch, and oracle-unresolved classes (caller and callee arms; compile-time-dispatch attributions stay report-only because their non-exact band varies with the compiler oracle's environment), runtime-dispatch oracle edges excluded with reason (possible-dispatch routing is demote-only), and deferred oracle-unresolved edges that exact definition lookup pins to the target re-enter the gate-bearing universe. Passing these sampled floors is release evidence, not runtime-completeness proof.
+## Release evaluation
 
-The performance gate runs each pinned repository in three independent processes with a fixed worker shape. Publish and PR gates require both CPU and wall-throughput floors on the median run, pin the expected file/LOC workload, and use the worst observed build/full-board peak RSS so memory failures cannot be averaged away. Exploratory one-process runs keep wall throughput diagnostic. Scoped reports are separate from the full release artifact; the dated rollup is release-qualified only when every required row came from a full release invocation. The composite release gate runs this stage first so verbose compiler-oracle output and report consumers cannot perturb its samples.
+Releases are gated on pinned real repositories against independent oracles (ts-morph, Pyright, gopls, rust-analyzer, JDT LS, Roslyn, clangd): 100% in-scope caller and callee recall with zero unaccounted oracle edges, at least 98% confirmed-tier precision, full conservation, zero false-dead claims in the default `deadcode` audit, exactly agreeing cross-command claims for the same handle (`find`, `show`, `source`, `impact`, `tests`, `check`, caller `trace`), bounded unverified review burden (at most 10% of exact true edges left unverified, at least 80% of targets with no actionable ambiguity, at most five actionable candidates at p95), and throughput and memory budgets. Passing these sampled gates is release evidence for the measured static evidence classes; it does not turn dynamic dispatch, generated code, reflection, or external dependencies into complete runtime knowledge.
 
 ## Truncation
 
-CLI and MCP text share the same 10K targeted / 3K broad default budgets and
-100K ceiling. CLI truncation appends preserved contract lines directly. MCP
-results may additionally include:
+CLI and MCP text share the same 10K targeted / 3K broad default budgets and 100K ceiling. Room for every trust line (ACCOUNT, CONTRACT, WARNING, FILTERED, CALLEE ACCOUNT, TREE ACCOUNT) is reserved before any body text, and truncation appends the ones the kept body does not show. A limit that cannot hold them withholds the answer: the text states how many trust lines it shows and the budget that carries all of them, and never shows body text without them. MCP results may additionally include:
 
 ```json
 {
@@ -83,7 +80,4 @@ Allow an automated change to proceed to compiler/tests only when:
 - the repo health report lists no unsupported source handoff relevant to the change;
 - the change is still validated by the language toolchain and relevant tests.
 
-Never auto-delete from a UCN-only signal. Computed dispatch is reported as a
-health blind spot, and modeled registry members are withheld from candidates,
-but neither protection proves runtime reachability. Require usages, entry-point
-review, public API review, and external validation.
+Never auto-delete from a UCN-only signal. Computed dispatch is reported as a health blind spot, and modeled registry members are withheld from candidates, but neither protection proves runtime reachability. C/C++ token-pasting macro invocations and Rust `macro_rules!` invocations that cannot be expanded are reported the same way. Require usages, entry-point review, public API review, and external validation.

package/README.md

@@ -1,6 +1,6 @@
 # UCN - Universal Code Navigator
 
-See what code does before you touch it.
+Auditable answers, with every match counted, unsure ones marked and blind spots named.
 
 [![npm](https://img.shields.io/npm/v/ucn)](https://www.npmjs.com/package/ucn)
 [![tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mleoca/0e10a790e16ab61ddd233e05645e203e/raw/ucn-tests.json)](https://github.com/mleoca/ucn/actions/workflows/ci.yml)
@@ -8,7 +8,9 @@ See what code does before you touch it.
 
 If you work with AI Agents, add UCN as a [Skill or MCP tool](#ai-setup). One tool
 gives the agent compact, source-linked answers to caller, impact, and test
-questions, with uncertainty labeled instead of guessed.
+questions, with uncertainty labeled instead of guessed. The answer depends on
+the indexed source, not on who asks: a person at a terminal and an agent over
+MCP receive the same records for the same question.
 
 <img src="assets/readme/ucn-connected-scope.gif" width="736" alt="Conceptual overview of UCN's relationship views, multi-hop exploration, visible uncertainty, index reuse, and refresh after edits. Nodes and timing are illustrative, not a captured query or benchmark.">
 
@@ -103,9 +105,11 @@ Captured findings · [Still image](assets/readme/ucn-evidence-graph.png) · [Dat
 
 The ACCOUNT line reconciles the observed name occurrences: confirmed calls,
 unverified candidates, non-call occurrences, and matches attributed to another
-target. CONTRACT describes the scope of that accounting. Warnings identify
-source the index could not cover. These details survive text truncation for
-an agent's output budget.
+target. Each occurrence is counted in exactly one category, so the totals can
+be checked line by line rather than taken on trust. CONTRACT describes the
+scope of that accounting. Warnings identify source the index could not cover.
+These details survive text truncation for an agent's output budget; a budget
+too small to hold them withholds the answer and names the budget that would.
 
 An empty result therefore means something specific about the inspected code.
 It cannot establish that reflection, generated code, runtime registration, or
@@ -117,7 +121,7 @@ needs the compiler and tests.
 
 Release gates compare UCN's answers with independent compilers and language
 servers on a ten-repository board of pinned production codebases. The local
-September 6, 2026 evaluation recorded these sampled caller results:
+October 4, 2026 evaluation recorded these sampled caller results:
 
 | Repository | Pinned commit | Oracle | Symbols sampled | Confirmed precision | In-scope recall |
 |---|---|---|---:|---:|---:|
@@ -134,10 +138,10 @@ September 6, 2026 evaluation recorded these sampled caller results:
 
 That evaluation reported zero missing in-scope oracle edges in both caller
 and callee answers, and 8,000 cross-command comparisons with zero disagreements.
-The default dead-code audit found zero false-dead results among 13 scored
-claims; 13 additional claims could not be pinned by the oracle and were unscored.
+The default dead-code audit found zero false-dead results among 9 scored
+claims; 4 additional claims could not be pinned by the oracle and were unscored.
 All ten repositories passed the performance budgets, with steady-state query
-p95 from 4.5 to 76.2 ms. Those timings exclude process startup and indexing;
+p95 from 4.7 to 101.1 ms. Those timings exclude process startup and indexing;
 cold builds and cache loading are measured separately.
 
 The samples are deterministic and stratified by reference activity. Confirmed
@@ -146,9 +150,9 @@ in either the confirmed or unverified band. Unverified candidates, oracle
 abstentions, and unscored findings remain separate. These measurements do not
 establish complete runtime knowledge or identical performance on every machine.
 
-The scheduled board covers 24 pinned repositories: the ten above plus zod,
+The scheduled board covers 25 pinned repositories: the ten above plus zod,
 express, hono, zustand, fastify, rich, click, attrs, grpc-go, chi, cursive,
-itertools, gson, and jsoup. A rotating fresh-repository arm checks codebases
+itertools, rayon, gson, and jsoup. A rotating fresh-repository arm checks codebases
 outside that pinned board.
 
 The [repository manifest](eval/lib/repos.js) records the full commits.
@@ -188,9 +192,10 @@ npm run trust:gate
 
 `deps --cycles` groups circular dependencies and distinguishes eager imports
 from deferred or type-only edges. Enumeration limits are disclosed. `repo`
-reports source coverage as well as project structure; its quick HOT ranking
-has a disclosed refinement budget, and `repo --sections=stats --hot` requests
-the exact ranking.
+reports source coverage as well as project structure; its HOT ranking counts
+confirmed production callers exactly (a refinement budget only binds on very
+large repositories, and is disclosed), and `repo --sections=stats --hot` ranks
+by all callers.
 
 `endpoints --bridge` matches server routes and client requests recognized by
 its framework extractors. `plan` handles code relationships
@@ -208,6 +213,8 @@ exits 2, and a successful listing exits 0. `--lines` supports `find`, `show`,
 `usages`, `search`, and `impact`; `show --lines` lists callers by default.
 Use `--json` when the script needs structured fields or a tree result.
 
+Listings are deterministic for a given source tree: a fresh build, a cache
+load, and an incremental rebuild return the same records in the same order.
 Listings have no default row cap. Explicit limits disclose what they omit,
 and a shell-mode character budget fails before writing partial output.
 `source --raw` extracts complete functions and classes unless an explicit
@@ -215,12 +222,16 @@ line limit is requested; any resulting truncation is reported on stderr.
 
 Ordinary text-mode command errors also exit 2. JSON keeps exit 0 for successful
 empty results and exit 1 for command errors (`meta.ok: false` plus `error`).
+An exception inside UCN is reported as `Internal error: ...` (JSON adds
+`meta.internalError: true`), never as an answer about the code.
 Target-less `check` exits 1 when `TRUST` is `BLOCKED`, 0 for other completed
 checks, and 2 if it could not run.
 
 Outside `--lines`, `find`, text `search`, `deadcode`, `api`, and
-`repo --sections=files` default to a maximum of 500 results. Use `--limit=N`
-to request more; `usages` lists every site unless a limit is given. Broad `find` queries select candidates by approximate usage
+`repo --sections=files` default to a maximum of 500 results. `find` text shows
+the top 5 in detail and counts the rest (JSON returns up to 500); `--limit=N`
+raises both. Use `--limit=N` to request more; `usages` lists every site,
+test files included, unless a limit or `--exclude-tests` is given. Broad `find` queries select candidates by approximate usage
 totals before calculating definition-pinned caller activity, and disclose
 that selection when limited.
 

package/cli/index.js

@@ -7,6 +7,11 @@
  * Auto-detects mode from target (file path → file mode, directory → project mode).
  */
 
+// Reuse V8 code caches across processes (Node >= 22.1; fix #365): compiling
+// the engine's modules is a fixed cost of every command. Node validates each
+// entry against the source, and NODE_DISABLE_COMPILE_CACHE turns it off.
+try { require('module').enableCompileCache?.(); } catch (_) { /* optional */ }
+
 const fs = require('fs');
 const path = require('path');
 
@@ -28,6 +33,7 @@ const {
 } = require('../core/registry');
 const { buildPublicParams, isPublicCommand } = require('../core/public-command');
 const { execute } = require('../core/execute');
+const { describeError } = require('../core/errors');
 const { applyOutputBudget, MAX_OUTPUT_CHARS } = require('../core/output-budget');
 const { clearAllCaches } = require('../core/cache');
 const { commentLines } = require('../core/output/lines');
@@ -188,7 +194,7 @@ function validateNumericFlags(flags) {
 }
 
 /** Emit the one CLI error contract, including failures before main dispatch. */
-function emitCliError(msg, command = activeCanonicalCommand) {
+function emitCliError(msg, command = activeCanonicalCommand, { internal = false } = {}) {
     const wantsJson = process.argv.includes('--json');
     const error = typeof msg === 'string' ? msg : String(msg);
     if (wantsJson) {
@@ -201,6 +207,8 @@ function emitCliError(msg, command = activeCanonicalCommand) {
         const env = {
             meta: {
                 ok: false,
+                // An exception inside UCN, not a refusal (fix #394).
+                ...(internal && { internalError: true }),
                 ...(surfaceCommand && {
                     command: surfaceCommand,
                     ...(canonical && surfaceCommand !== canonical && {
@@ -223,11 +231,24 @@ function emitCliError(msg, command = activeCanonicalCommand) {
  * Print an error message and abort command execution. Throw instead of calling
  * process.exit so index/cache finally blocks still run.
  */
-function fail(msg, command = activeCanonicalCommand) {
-    emitCliError(msg, command);
+function fail(msg, command = activeCanonicalCommand, options = {}) {
+    emitCliError(msg, command, options);
     throw new CommandError();
 }
 
+/** Fail with an execute() error: refusals are rendered for the CLI, internal errors kept verbatim. */
+function failExecution(execution) {
+    if (execution.internalError) fail(execution.error, activeCanonicalCommand, { internal: true });
+    fail(formatSurfaceMessage(execution.error, 'cli'));
+}
+
+/** Report an exception caught outside execute(). */
+function emitCaughtError(e) {
+    const described = describeError(e);
+    emitCliError(described.internalError ? described.error : `Error: ${described.error}`,
+        activeCanonicalCommand, { internal: !!described.internalError });
+}
+
 // ============================================================================
 // ARGUMENT PARSING
 // ============================================================================
@@ -607,7 +628,7 @@ function main() {
         }
     } catch (e) {
         if (!(e instanceof CommandError)) {
-            emitCliError(`Error: ${e.message}`);
+            emitCaughtError(e);
         }
         process.exitCode = flags.json ? 1 : 2;
     }
@@ -717,8 +738,8 @@ function runFileCommand(filePath, command, arg) {
     warnInapplicableFlags(canonical, scopedFlags, (message) => console.error(message));
     const params = buildPublicParams(canonical, arg, scopedFlags);
     const execution = execute(index, canonical, params);
-    const { ok, result, error } = execution;
-    if (!ok) fail(formatSurfaceMessage(error, 'cli'));
+    const { ok, result } = execution;
+    if (!ok) failExecution(execution);
     emitCliText(flags.json
         ? output.formatPublicJson(canonical, result, params, {
             ...execution, surface: 'cli',
@@ -799,7 +820,7 @@ function runProjectCommand(rootDir, command, arg) {
     });
     const publicExecution = execute(index, canonical, publicParams);
     if (!publicExecution.ok) {
-        fail(formatSurfaceMessage(publicExecution.error, 'cli'));
+        failExecution(publicExecution);
     }
     emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
@@ -813,7 +834,7 @@ function runProjectCommand(rootDir, command, arg) {
         resultExitCode(canonical, publicExecution.result));
     } catch (e) {
         if (!(e instanceof CommandError)) {
-            emitCliError(`Error: ${e.message}`);
+            emitCaughtError(e);
         }
         process.exitCode = flags.json ? 1 : 2;
     } finally {
@@ -822,7 +843,12 @@ function runProjectCommand(rootDir, command, arg) {
         // On cache-hit runs, only re-save if callsCache was mutated OR
         // reachability was computed (MED-1: persists the BFS result so
         // subsequent cold invocations don't repeat the 7-11s tax).
-        if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty)) {
+        // Files whose macro-expansion calls the command derived in part are
+        // derived whole first, so the next invocation reads them persisted.
+        if (flags.cache) {
+            try { index.completeMacroCallDerivations(); } catch (e) { /* best-effort */ }
+        }
+        if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty || index.macroExpansionDirty)) {
             try { index.saveCache(); } catch (e) { /* best-effort */ }
         }
         if (flags.cache && index.usageCacheDirty) {
@@ -866,7 +892,7 @@ function runGlobCommand(pattern, command, arg) {
     const publicParams = buildPublicParams(canonical, arg, flags);
     const publicExecution = execute(index, canonical, publicParams);
     if (!publicExecution.ok) {
-        fail(formatSurfaceMessage(publicExecution.error, 'cli'));
+        failExecution(publicExecution);
     }
     emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
@@ -906,7 +932,10 @@ Commands:
   show <symbol>                   Symbol summary and relationships
     --sections=summary,callers,callees,source,dependencies,tests,types,example,related
   find <name>                     Definitions; --type=type, --with-source
-  usages <name>                   Calls, imports, definitions, references
+    text: top 5 in detail + a count of the rest; --json: up to 500;
+    --limit=N raises both
+  usages <name>                   Calls, imports, definitions, references (test files
+                                  included; --exclude-tests hides them with a count)
   search [term]                   Text or structural search
     literal text by default; --regex enables regular-expression syntax
   source <symbol|file:range>      Exact function, class, or line extraction
@@ -1045,7 +1074,7 @@ function runInteractive(rootDir) {
 Commands:
   repo                   Repository overview (--sections=files,stats,health)
   show <name>            Symbol summary + relationships (--sections=...)
-  find <name>            Find definitions (--type=type, --with-source)
+  find <name>            Find definitions (--type=type, --with-source; top 5 shown, --limit=N)
   usages <name>          All usages grouped by type
   source <target>        Extract a symbol or file:line-range
   trace <name>           Call tree (--direction=callees|callers, --to=entrypoints)
@@ -1155,7 +1184,8 @@ Flags can be added per-command: show myFunc --sections=source,callers
             if (e instanceof FlagValidationError) {
                 console.log(e.message);
             } else {
-                console.error(`Error: ${e.message}`);
+                const described = describeError(e);
+                console.error(described.internalError ? described.error : `Error: ${described.error}`);
             }
         }
 
@@ -1177,7 +1207,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
     const publicParams = buildPublicParams(command, arg, iflags);
     const publicExecution = execute(index, command, publicParams);
     if (!publicExecution.ok) {
-        console.log(formatSurfaceMessage(publicExecution.error, 'cli'));
+        console.log(publicExecution.internalError ? publicExecution.error
+            : formatSurfaceMessage(publicExecution.error, 'cli'));
         return;
     }
     console.log(formatCliText(

package/core/accessors.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('path');
-const { codeUnitCompare } = require('./shared');
+const { codeUnitCompare, CALLABLE_SYMBOL_KINDS } = require('./shared');
 const { getParser, safeParse } = require('../languages');
 
 function inheritedAccessor(index, enclosing, name, definition) {
@@ -45,6 +45,85 @@ function accessKind(tree, usage) {
     return 'read';
 }
 
+// How an occurrence without a simple receiver touches a property (fix #397):
+// 'member' (the property of a longer member chain, `this.ctx.body`),
+// { pattern: true, thisSource } (a destructuring key, `const { body } =
+// this`, which reads the property from the source), or 'none' (a bare
+// variable, an object-literal key: never a property access). null when the
+// token cannot be located.
+const MEMBER_ACCESS_TYPES = new Set(['attribute', 'member_expression', 'member_access_expression',
+    'field_expression', 'selector_expression', 'field_access']);
+function receiverlessShape(tree, usage) {
+    if (!tree || !Number.isInteger(usage.column)) return null;
+    const node = tree.rootNode.descendantForPosition({ row: usage.line - 1, column: usage.column });
+    if (!node) return null;
+    const parent = node.parent;
+    if (MEMBER_ACCESS_TYPES.has(parent?.type) && node.startIndex > parent.startIndex) return 'member';
+    let key = null;
+    if (node.type === 'shorthand_property_identifier_pattern') key = node;
+    else if (parent?.type === 'pair_pattern' && parent.childForFieldName('key')?.startIndex === node.startIndex) key = node;
+    if (key) {
+        let pattern = key.parent;
+        if (pattern?.type === 'pair_pattern' || pattern?.type === 'object_assignment_pattern') pattern = pattern.parent;
+        const holder = pattern?.type === 'object_pattern' ? pattern.parent : null;
+        const source = holder?.type === 'variable_declarator' ? holder.childForFieldName('value') : null;
+        return { pattern: true, thisSource: source?.type === 'this',
+            shorthand: key.type === 'shorthand_property_identifier_pattern' };
+    }
+    return 'none';
+}
+
+// Source offset of an occurrence (fix #398F): orders it against same-line
+// assignments when its receiver is typed by return-type flow.
+function flowSiteOf(tree, usage) {
+    if (!tree || !Number.isInteger(usage.column)) return null;
+    const node = tree.rootNode.descendantForPosition({ row: usage.line - 1, column: usage.column });
+    return node ? node.startIndex : null;
+}
+
+// The enclosing callable scopes of a line, outermost first, as the parser's
+// call records spell them (`enclosingFunction.scopeChain`): the innermost
+// scope any record of the file reports around the line (anonymous callbacks
+// included), else the indexed callables containing it.
+function scopeChainAt(index, file, line, calls) {
+    let best = null;
+    for (const call of calls || []) {
+        const scope = call.enclosingFunction;
+        if (!scope || scope.startLine > line || scope.endLine < line) continue;
+        if (!best || scope.startLine > best.startLine ||
+            (scope.startLine === best.startLine && scope.endLine < best.endLine)) best = scope;
+    }
+    if (best && Array.isArray(best.scopeChain)) return best.scopeChain;
+    const scopes = (index.files.get(file)?.symbols || []).filter(symbol =>
+        CALLABLE_SYMBOL_KINDS.has(symbol.type) && symbol.startLine <= line && line <= symbol.endLine)
+        .sort((a, b) => a.startLine - b.startLine || b.endLine - a.endLine);
+    return scopes.map(symbol => symbol.startLine);
+}
+
+// A plain local receiver typed by return-type flow (`result =
+// runner.invoke(..)` with `invoke(..) -> Result`), the evidence the caller
+// engine uses for method calls on the same receiver (fix #398F).
+function flowReceiverType(index, ref, flowMaps) {
+    if (!/^[A-Za-z_$][\w$]*$/.test(ref.receiver || '') || ['self', 'cls', 'this'].includes(ref.receiver)) return null;
+    const callers = require('./callers');
+    let state = flowMaps.get(ref.file);
+    if (state === undefined) {
+        const calls = callers.getCachedCalls(index, ref.file);
+        state = calls ? { calls, map: callers._buildReturnTypeFlowMap(index, ref.file, calls) } : null;
+        flowMaps.set(ref.file, state);
+    }
+    const map = state?.map;
+    if (!map) return null;
+    const chain = scopeChainAt(index, ref.file, ref.line, state.calls);
+    const entry = callers._lookupReturnTypeFlow(map, {
+        receiver: ref.receiver, line: ref.line,
+        ...(Number.isInteger(ref.flowSite) && { callStart: ref.flowSite }),
+        enclosingFunction: chain.length ? { startLine: chain[chain.length - 1], scopeChain: chain } : null,
+    });
+    if (!entry?.type || entry.invalidated || !entry.fromFile) return null;
+    return { type: entry.type, fromFile: entry.fromFile };
+}
+
 // Descriptors/properties are consumed through reads and writes, not only
 // call syntax. Keep this vocabulary shared by impact and refactoring so the
 // two commands cannot disagree about whether a selected symbol is an accessor.
@@ -61,6 +140,8 @@ function isAccessorDefinition(definition) {
 
 function ownerName(definition) {
     if (definition.className) return definition.className;
+    // An object-literal accessor's owner is the literal (fix #397).
+    if (definition.objectLiteralLine && definition.registryContainer) return definition.registryContainer;
     if (!definition.receiver) return null;
     return String(definition.receiver)
         .replace(/^[*&]\s*/, '')
@@ -89,11 +170,19 @@ function typeMatchesOwner(index, typeName, contextFile, owner, ownerFile) {
         path.resolve(ownerDefs[0].file) === path.resolve(ownerFile);
 }
 
+// Members of the same object literal (fix #397): `this` in one names the
+// object the literal builds (or an object inheriting from it).
+function sameObjectLiteral(a, b) {
+    return !!a && !!b && !!a.objectLiteralLine && a.objectLiteralLine === b.objectLiteralLine &&
+        a.file === b.file;
+}
+
 function insideSelectedAccessorBody(index, name, definition, file, line) {
     return (index.symbols.get(name) || []).some(candidate =>
         isAccessorDefinition(candidate) &&
         candidate.file === definition.file &&
         candidate.className === definition.className &&
+        (candidate.objectLiteralLine || null) === (definition.objectLiteralLine || null) &&
         file === candidate.file &&
         line >= candidate.startLine &&
         line <= (candidate.endLine || candidate.startLine));
@@ -114,12 +203,16 @@ function findAccessorReferences(index, name, definition, options = {}) {
     const confirmed = [];
     const unverified = [];
     const excluded = [];
+    const flowMaps = new Map();
     // Use the parser's raw occurrence records rather than usages()' public
     // line-oriented inventory. A line can contain two same-spelled member
     // accesses with different receivers; collapsing them by file+line would
     // make a rename edit one token while silently losing the other.
     const refs = [];
     for (const [file, entry] of index.files) {
+        // `files` (fix #398F): a caller that needs one file family (tests)
+        // never parses the rest of the project.
+        if (options.files && !options.files.has(file)) continue;
         if (!index.matchesFilters(entry.relativePath, options)) continue;
         let content;
         let occurrences;
@@ -134,9 +227,16 @@ function findAccessorReferences(index, name, definition, options = {}) {
         const lines = content.split('\n');
         for (const usage of occurrences) {
             if (usage.usageType !== 'reference') continue;
+            let shape = null;
+            if (!usage.receiver) {
+                shape = receiverlessShape(tree, usage);
+                if (shape === 'none') continue;
+            }
             refs.push({
                 ...usage,
-                accessKind: accessKind(tree, usage),
+                ...(shape?.pattern && { patternKey: shape, ...(shape.thisSource && { receiver: 'this' }) }),
+                accessKind: shape?.pattern ? 'read' : accessKind(tree, usage),
+                ...(usage.receiver && { flowSite: flowSiteOf(tree, usage) }),
                 file,
                 relativePath: entry.relativePath,
                 content: lines[usage.line - 1] || '',
@@ -154,6 +254,7 @@ function findAccessorReferences(index, name, definition, options = {}) {
             accessKind: ref.accessKind,
             ...(Number.isInteger(ref.column) && { column: ref.column }),
             ...(ref.receiver && { receiver: ref.receiver }),
+            ...(ref.patternKey && { patternKey: { shorthand: !!ref.patternKey.shorthand } }),
         };
 
         // A backing-store attribute inside the selected getter/setter body
@@ -168,7 +269,9 @@ function findAccessorReferences(index, name, definition, options = {}) {
         const enclosing = index.findEnclosingFunction(ref.file, ref.line, true);
         const receiver = ref.receiver || null;
         if (receiver && ['self', 'cls', 'this'].includes(receiver) &&
-            ((enclosing?.className === owner && enclosing.file === definition.file) ||
+            ((definition.className && enclosing?.className === owner &&
+                enclosing.file === definition.file) ||
+                (!definition.className && sameObjectLiteral(enclosing, definition)) ||
                 inheritedAccessor(index, enclosing, name, definition))) {
             confirmed.push({
                 ...shaped,
@@ -195,6 +298,18 @@ function findAccessorReferences(index, name, definition, options = {}) {
             });
             continue;
         }
+        const flowed = !receiverType && receiver ? flowReceiverType(index, ref, flowMaps) : null;
+        if (flowed && bareTypeName(flowed.type) === owner &&
+            path.resolve(flowed.fromFile) === path.resolve(definition.file)) {
+            confirmed.push({
+                ...shaped,
+                callerName: enclosing?.name || null,
+                receiverType: flowed.type,
+                resolution: 'receiver-return-flow',
+                tier: 'confirmed',
+            });
+            continue;
+        }
         if (receiver && typeMatchesOwner(index, receiver, ref.file, owner, definition.file)) {
             confirmed.push({
                 ...shaped,