ucn 5.6.0 → 5.6.1

package/.claude/skills/ucn/SKILL.md

@@ -19,7 +19,7 @@ UCN answers semantic questions about a codebase from a tree-sitter index: where
 2. `ucn find <name>` pins a definition. Pass its `path:line:name` handle to every later command. A plain name that matches several definitions carries an ambiguity warning in `show`, `source`, `trace`, `impact`, `tests`, `check` and `plan`; never treat the auto-selected definition as the repository-wide target.
 3. `ucn show <handle>` gives the summary, callers and callees. `--sections` replaces that selection; for example, `--sections=summary,source,tests` requests those three sections.
 4. Before a change: `ucn impact <handle>` and `ucn tests <handle> --depth=3`.
-5. After a signature change: `ucn check <handle>`; before committing: target-less `ucn check`. Both compare a changed declaration with its parameters at `--base` (default `HEAD`), so the call sites bound to the old declaration are checked against the new one; a site that fits no remaining overload is a mismatch, never an excluded other-target line. Target-less `check` gives each changed symbol a verdict by what the change did. `BLOCKED`: a break was observed (a call site that no longer fits, an import or bare call of a deleted name, an import of a name its module no longer exports, an import of a deleted file, an object literal declared as a type that gained a member it lacks); every site is listed. A site the toolchain does not look at (a line under `// @ts-ignore` or `# type: ignore`, a module loaded by a call the compiler does not resolve) is listed and is `REVIEW`, never what blocks. `REVIEW`: the change can reach existing code and the engine cannot settle it (a changed header, generator kind or body-inferred return; an added name already in use or a member that overrides, is required, is a new member of a TypeScript class other code can hold or enumerate, is an operator or conversion, or is invoked by a runtime or framework; a deletion a shield holds; a `(module)` item for changed exports, removed imports, loose module code or a new file an existing import can resolve to), with the reason named. `READY`: nothing that existed depends on it (a body edit that leaves the contract alone, new code under new names, a deletion with no static dependents). `TRUST` is the worst verdict. `--staged` describes the git index, not the worktree: files, `.gitignore` and `.ucn.json` come from the index, including paths marked skip-worktree or assume-unchanged; when the index cannot be exported, `check` and `impact` decline.
+5. After a signature change: `ucn check <handle>`; before committing: target-less `ucn check`. Both compare a changed declaration with its parameters at `--base` (default `HEAD`), so the call sites bound to the old declaration are checked against the new one; a site that fits no remaining overload is a mismatch, never an excluded other-target line. Target-less `check` gives each changed symbol a verdict by what the change did. `BLOCKED`: a break was observed (a call site that no longer fits, an import or bare call of a deleted name, an import of a name its module no longer exports, an import of a deleted file, an object literal declared as a type that gained a member it lacks); every site is listed. A site the toolchain does not look at (a line under `// @ts-ignore` or `# type: ignore`, a module loaded by a call the compiler does not resolve) is listed and is `REVIEW`, never what blocks. `REVIEW`: the change can reach existing code and the engine cannot settle it (a changed header, generator kind or body-inferred return; an added name already in use or a member that overrides, is required, is a new member of a TypeScript class other code can hold or enumerate, is an operator or conversion, or is invoked by a runtime or framework; a deletion a shield holds; a `(module)` item for changed exports, removed imports, loose module code or a new file an existing import can resolve to), with the reason named. `READY`: the modeled change checks found no unresolved exposure (a body edit that leaves the contract alone and preserves its call requirements, independent new code, or a deletion with no static dependents). Added or changed calls to project declarations are checked too: a proven argument-count mismatch blocks, while an unresolved target or call interface requires review. Changes to checker directives can require review even when declaration tokens stay the same. READY is not a compiler or runtime correctness claim. `TRUST` is the worst verdict. `--staged` describes the git index, not the worktree: files, `.gitignore` and `.ucn.json` come from the index, including paths marked skip-worktree or assume-unchanged; when the index cannot be exported, `check` and `impact` decline.
 6. `ucn source <handle>` or `ucn source path/to/file:10-30` for exact code, only when inspection is needed.
 
 The direct tests in `show <handle> --sections=tests` match `tests <handle>`. Equivalent file and line parameters preserve the same exact declaration, including overloads.
@@ -107,6 +107,8 @@ A test is a unit: its file, the suites around it, its name and its line, read fr
 
 C, C++ and HTML tests are not read as units. Not read anywhere: what a package's code does (an installed pytest plugin, a vite plugin called in a configuration, a preset, a runner or an extension a test class names, the value a package's function gives back as a row), what a fixture or a setup reaches more than one project module away, what a function of another project module gives back as a row, a constructor one module writes on a class of another as seen from that other module, a using alias of a constructed type, an array or a tuple, and setup files a runner loads for every file (jest setup files, mocha root hooks). Type names are resolved on two assumptions: the code compiles (a name has one meaning where it is used), and the packages and namespaces the project declares types in, and the namespaces around those, hold the types its source declares. Where the runner's options are not read the tests are listed as declared, with no command.
 
+Direct and transitive test links keep the selected declaration and the physical call position, including several functions or tests on one line. Text output includes each available unit selector as `run test:`; a position that cannot distinguish neighboring units withholds an exact selector. Rust tests introduced by conditional attributes stay visible, with commands withheld when their configuration is unresolved.
+
 `check` selects tests for every changed symbol by its declaration, counts each test once (`Tests potentially affected: N in M files`, `at least N` and `(K conditional)` as above) and prints the runner's command under `Run tests:`.
 
 Numeric evidence values are ordinal ranking weights, not probabilities. An observed-text zero is not a semantic zero or safe-delete proof.
@@ -158,7 +160,7 @@ C/C++ uses `compile_commands.json` when present for header classification and in
 
 ## Deletion protocol
 
-`ucn plan <handle> --delete` answers for one declaration: `no-static-dependents`, `has-static-dependents` with the first use, or `review` with the reason. It applies the rule `deadcode` applies to every name and is static evidence, not a guarantee. `deadcode` is a candidate generator, never deletion proof. Before deleting, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`, then corroborate with the compiler/type checker and tests. Members that reflection (exact names or literal-fragment patterns), computed dispatch, runtime protocols (Python dunders, Java serialization callbacks, C# pattern members, JS `toJSON`/`then`), unknown decorators, event-handler assignment, an outside base class, or macro expansion may reach are withheld or warned; the `deadcode` notes in the command reference list them. Never delete solely from `deadcode` or an observed-text-zero result.
+`ucn plan <handle> --delete` answers for one declaration: `no-static-dependents`, `has-static-dependents` with the first use, or `review` with the reason. It applies the rule `deadcode` applies to every name and is static evidence, not a guarantee. `deadcode` is a candidate generator, never deletion proof. Before deleting, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`, then corroborate with the compiler/type checker and tests. Members that reflection (exact names or literal-fragment patterns), computed dispatch, runtime protocols (Python dunders, Java serialization callbacks, C# pattern members, JS `toJSON`/`then`), unknown decorators, event-handler assignment, an outside base class, or macro expansion may reach are withheld or warned; the `deadcode` notes in the command reference list them. Known Python packaging entrypoints and required mock-patch targets also withhold deletion; ordinary strings and creation-permitted patching do not prove a dependent. Builtin decorator and base exemptions require binding identity, so aliases, shadowing and possible mutation can require review. Explicit project namespace effects are shared across files. Unknown ownership, computed namespace members and unmodeled execution order can conservatively withhold builtin exemptions project-wide (`builtin-namespace-effect` or `external-contract`), without claiming a confirmed use. Python source spellings that normalize to another identifier are withheld with `identifier-normalization` where the caller graph cannot establish their identity; runtime strings keep their exact spelling. Never delete solely from `deadcode` or an observed-text-zero result.
 
 ## Efficient use
 

package/.claude/skills/ucn/references/commands.md

@@ -22,7 +22,7 @@ Use text search (grep/ripgrep) for simple literals, error messages, configuratio
 | `impact [handle]` | Direct impact of one symbol; without a handle, the Git diff (`--base=<ref>`, `--staged`). Property targets add an access-site band, type targets a reference-site band. |
 | `tests <handle\|file>` | Statically linked direct tests; `--depth=N` adds transitively affected tests; `--calls-only` keeps direct calls and test-case matches. |
 | `check [handle]` | Call-site validation for one symbol against its declaration at `--base` (default `HEAD`); without a handle, the composed pre-commit check of the diff (`--base`, `--staged`). |
-| `plan <handle>` | Preview `--rename-to=X`, `--add-param=p` (`--default-value=v`), or `--remove-param=p`. Never edits files. A Python param added beside `*args` or keyword-only params is keyword-only (after them, before `**kwargs`); calls passing arguments where a param is inserted before a rest param are listed. `--delete` assesses deleting the declaration with the rule `deadcode` applies to every name: `no-static-dependents` (no use in project source outside its own declarations and no shield applies), `has-static-dependents` (the name is called or used outside the declaration; the first site is printed; evidence is by name, as in `deadcode`), or `review` with the reason (exported from a library, bound to an external or project contract, registered, reflected, source that could not be searched, used only inside the declaration itself). Static evidence, not a guarantee: run the compiler and the tests. `"kind": "application"` in `.ucn.json` lets exported symbols be assessed. |
+| `plan <handle>` | Preview `--rename-to=X`, `--add-param=p` (`--default-value=v`), or `--remove-param=p`. Never edits files. A Python param added beside `*args` or keyword-only params is keyword-only (after them, before `**kwargs`); calls passing arguments where a param is inserted before a rest param are listed. `--delete` assesses deleting the declaration with the rule `deadcode` applies to every name: `no-static-dependents` (no use in project source outside its own declarations and no shield applies), `has-static-dependents` (a call proven to reach this declaration, or an unambiguous use of its name, exists outside the declaration; the first site is printed), or `review` with the reason (exported from a library, bound to an external or project contract, registered, named by packaging metadata, reflected or named by a required mock-patch target, uses of the name that are not proven to reach this declaration, source that could not be searched, used only inside the declaration itself). Static evidence, not a guarantee: run the compiler and the tests. `"kind": "application"` in `.ucn.json` lets exported symbols be assessed. |
 
 `show <handle> --sections=tests` and `tests <handle>` select direct tests for the same declaration. Equivalent `--file` and `--line` parameters preserve that pin, including overloaded methods.
 

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 One section per released version, written from the commit subjects by `scripts/changelog.js` when the version is cut.
 
+## 5.6.1 - 2026-11-14
+
+### Fixes
+
+- deletion verdicts hold for mock-patch targets and packaging entry points and cite only proven uses, check judges the calls a change adds, a change selects tests by its declaration, and the pre-commit check repeats less work (525369e)
+
+### Documentation
+
+- the README reports the check and test-unit matrices at their current size, 507 single changes and 344 test projects (30923d8)
+- the README's ripgrep example states only what its animation shows (8e51ac2)
+
 ## 5.6.0 - 2026-11-14
 
 ### Features

package/README.md

@@ -101,11 +101,8 @@ receiver and ownership evidence determine how the candidate is classified.
 
 In ripgrep at [`82313cf9`](https://github.com/BurntSushi/ripgrep/commit/82313cf95849bfe425109ad9506a52154879b1b1),
 the selected `file_name` helper has four confirmed call sites among the 29 lines
-that mention the name. The other 25 are accounted for as well: 17 are not calls
-and 8 are attributed to other targets with the same name. This animation is a
-capture from September 2026, when one of those eight was still an unverified
-candidate. It shows the same 29 lines alongside import relationships and
-same-name definitions drawn from UCN's output.
+that mention the name. This animation accounts for all 29 lines, alongside
+import relationships and same-name definitions drawn from UCN's output.
 
 <a href="assets/readme/ucn-evidence-graph.gif"><img src="assets/readme/ucn-evidence-graph.gif" width="736" alt="Captured ripgrep findings for file_name: 29 matching lines in six files, partitioned into 4 confirmed calls, 1 unverified candidate, 17 non-call lines, 7 other-target lines, and 0 unaccounted. The graph shows selected import relationships and the distinct definitions; motion is illustrative."></a>
 
@@ -157,9 +154,9 @@ claims; 4 additional claims could not be pinned by the oracle and were unscored.
 The release gate also runs three matrices of small projects written by the
 evaluation, each judged by the language's own compiler or test runner. In the
 same run, across 68 deletions, `plan --delete` reported `no-static-dependents`
-for none that a compiler rejects. Across 369 single changes, `check` called
-none ready that a compiler rejects and blocked none that it accepts. Of 338
-test projects, 333 were judged by their own test runners, with zero failures
+for none that a compiler rejects. Across 507 single changes, `check` called
+none ready that a compiler rejects and blocked none that it accepts. Of 344
+test projects, 339 were judged by their own test runners, with zero failures
 in the matrix's test-discovery and command-selection checks. These checks
 account for skipped and conditional tests and each runner's selection scope;
 five projects were not runner-judged.

package/core/analysis.js

@@ -116,7 +116,7 @@ function tagInTestCase(index, sites) {
         const classify = kindOf.get(fileEntry.language);
         if (classify && site.callerFile && site.callerStartLine != null) {
             const encl = index.findEnclosingFunction
-                ? index.findEnclosingFunction(site.callerFile, site.line, true)
+                ? index.findEnclosingFunction(site.callerFile, site.line, true, site)
                 : null;
             if (encl && classify(encl) === 'test') {
                 site.inTestCase = true;
@@ -124,7 +124,7 @@ function tagInTestCase(index, sites) {
             }
         }
         if (site.line != null && isTestFile(fileEntry.relativePath, fileEntry.language) &&
-            model.unitAt(sitePath, site.line)) {
+            model.unitAt(sitePath, site)) {
             site.inTestCase = true;
         }
     }
@@ -2639,7 +2639,7 @@ function diffImpact(index, options = {}) {
                 // A deleted declaration's name is assessed as a deletion.
                 const removedNames = moved.removedNames.filter(name => !gone.has(name));
                 if (removedNames.length > 0 || moved.importsRemoved > 0 || moved.importsAdded > 0 ||
-                    moved.codeChanged || moved.starExportRemoved || moved.reboundBindings.length > 0) {
+                    moved.codeChanged || moved.checkingChanged || moved.starExportRemoved || moved.reboundBindings.length > 0) {
                     moduleChanges.push({
                         filePath: change.filePath,
                         relativePath: change.relativePath,

package/core/cache.js

@@ -1015,7 +1015,9 @@ function clearAllCaches() {
 // every file's text on each query).
 // v335: reflection/eval facts follow commented and parenthesized callees;
 // package reflection qualifiers retain Unicode names and lexical ownership.
-const CACHE_FORMAT_VERSION = 335;
+// v336 (fixes #501/#503): binding-resolved Python registration/reflection,
+// nested runtime owner paths, JS computed calls, and owned Rust attributes.
+const CACHE_FORMAT_VERSION = 336;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 function usageResultKey(index, filePath, name, mode) {

package/core/call-fit.js

@@ -0,0 +1,130 @@
+/** Positive, deliberately bounded argument-fit proofs for changed calls. */
+'use strict';
+
+const { langTraits } = require('../languages');
+const { argumentProvablyConverts, cppArgumentProvablyConverts } = require('./callers');
+
+function literalKind(argument) {
+    if (argument?.kind === 'number_literal' && /^\d+$/.test(argument.text || '') &&
+        Number(argument.text) <= 127) return 'smallInteger';
+    // Prefixes can change the type (Python bytes, C++ encoded strings).
+    // Only plain quoted strings belong to this bounded proof domain.
+    if (argument?.kind === 'string_literal' && ['"', "'"].includes(argument.text?.[0])) return 'string';
+    if (['true', 'false', 'boolean_literal'].includes(argument?.nodeType)) return 'boolean';
+    return null;
+}
+
+/** A written builtin type cannot borrow a project or imported namesake. */
+function unshadowed(index, definition, type) {
+    const simple = String(type || '').replace(/^&/, '').trim();
+    if ((index.symbols.get(simple) || []).length) return false;
+    const entry = index.files.get(definition.file);
+    if ((entry?.importDetails || []).some(detail => detail.type === 'from' && detail.names?.includes('*'))) return false;
+    return !(entry?.importBindings || []).some(binding => binding.name === '*' || binding.kind === 'wildcard' ||
+        binding.name === simple || binding.local === simple || binding.alias === simple);
+}
+
+function unavailableSurface(index, definition, caller) {
+    const sameOwner = caller.file === definition.file && caller.className && caller.className === definition.className &&
+        (caller.namespace || null) === (definition.namespace || null) &&
+        (caller.enclosingType || null) === (definition.enclosingType || null);
+    const uncertain = member => member.isAbstract || (member.modifiers || []).includes('abstract') || (member.decorators || []).length > 0 ||
+        !sameOwner && (member.modifiers || []).some(modifier => ['private', 'protected'].includes(modifier));
+    if (uncertain(definition)) return true;
+    if (definition.initializerOf) {
+        const owners = (index.symbols.get(definition.initializerOf) || []).filter(owner => owner.type === 'class');
+        if (owners.length !== 1 || uncertain(owners[0])) return true;
+    }
+    if (definition.type !== 'class') return false;
+    const entry = index.files.get(definition.file);
+    return (entry?.symbols || []).some(member => member.className === definition.name &&
+        member.startLine >= definition.startLine && member.startLine <= definition.endLine &&
+        (member.type === 'constructor' || member.isConstructor ||
+            ['constructor', '__init__'].includes(member.name)) && uncertain(member));
+}
+
+/** A visible checked-JS/JSDoc contract withdraws the dynamic-only proof. */
+function typedComments(index, file) {
+    const trait = langTraits(index.files.get(file)?.language)?.checkTypedComment;
+    if (!trait) return false;
+    const memo = index._opMemo?.('checkTypedComments', () => new Map());
+    if (memo?.has(file)) return memo.get(file);
+    let found = true;
+    try {
+        const source = index._readFile(file);
+        const root = index._getParsedTree(file, source, index.files.get(file)?.language)?.rootNode;
+        if (root) found = root.descendantsOfType('comment').some(comment => trait(comment.text));
+    } catch (_) { /* unread checking context stays unknown */ }
+    memo?.set(file, found);
+    return found;
+}
+
+/** True is a proof for this small domain; false means review, not mismatch. */
+function positivelyFits(index, definition, caller, record, result, stableInvocation = false) {
+    // A changed call may reuse its baseline availability only under an
+    // unchanged invocation context. Count/type fit alone cannot prove a
+    // new invocation, a receiver/generic/passing-mode change, or its result
+    // use valid. Constructors and their implementation projections are
+    // outside this proof: the public overload interface is not the body.
+    if (!stableInvocation || definition.initializerOf || definition.isConstructor ||
+        ['class', 'struct', 'record', 'constructor'].includes(definition.type)) return false;
+    if (unavailableSurface(index, definition, caller) || (definition.decorators || []).length) return false;
+    // A literal may select a different overload with different access,
+    // exception or passing-mode requirements even when both return the
+    // same type. Family completeness is not proved here: only a unique
+    // project declaration belongs to this small positive domain.
+    if ((index.symbols.get(definition.name) || []).length !== 1) return false;
+    if (definition.className) {
+        // A receiver or an inherited outside overload can choose a method
+        // absent from the project family. Only a static member of a
+        // non-derived owner belongs to this bounded preservation proof.
+        if (!(definition.modifiers || []).includes('static')) return false;
+        const owners = (index.symbols.get(definition.className) || []).filter(owner => owner.file === definition.file &&
+            owner.startLine <= definition.startLine && owner.endLine >= definition.endLine);
+        if (owners.length !== 1 || owners[0].extends?.length || owners[0].implements?.length) return false;
+    }
+    const traits = langTraits(index.files.get(definition.file)?.language);
+    if ((definition.modifiers || []).some(modifier => (traits.compileTimeCallableMarkers || []).includes(modifier))) return false;
+    const callerTraits = langTraits(index.files.get(caller.file)?.language);
+    // Written TS declarations do not make ordinary JS arguments checked.
+    if (callerTraits.lenientCallArity) return !typedComments(index, caller.file) && !typedComments(index, definition.file);
+    const shape = result.callShapes?.[0];
+    if (!shape || shape.hasSpread || shape.indirectKind) return false;
+    const arguments_ = shape.argumentFacts || [];
+    if (arguments_.length === 0) return false;
+    if (arguments_.length !== shape.argCount) return false;
+    const lists = result.parameterLists || [];
+    if (lists.length !== 1) return false;
+    const language = index.files.get(definition.file)?.language;
+    return lists.some(parameters => {
+        let positional = 0;
+        return arguments_.every((argument, at) => {
+            const parameter = argument.keyword ? parameters.find(p => p.name === argument.keyword)
+                : parameters[positional++];
+            if (!parameter || parameter.rest || !parameter.type) return false;
+            // The nominal conversion helpers classify values, not C++
+            // lvalue/rvalue reference binding or language passing modes.
+            if (/[&*]/.test(parameter.type) && parameter.type !== '&str') return false;
+            const kind = literalKind(argument);
+            if (!kind) return false;
+            if (traits.checkLiteralArguments) {
+                const accepted = traits.checkLiteralArguments[kind] || [];
+                return accepted.includes(parameter.type) && unshadowed(index, definition, parameter.type);
+            }
+            // Reuse the nominal overload engine's positive conversion
+            // facts, never its weaker "not disproved" applicability test.
+            if (!traits.hasArityOverloads || parameter.type.includes('.') ||
+                !unshadowed(index, definition, parameter.type)) return false;
+            const argumentKind = record.argKinds?.[at];
+            if (!argumentKind) return false;
+            if (traits.userDefinedConversions === 'constructors-and-operators') {
+                return cppArgumentProvablyConverts(index, argumentKind, parameter, definition,
+                    { ...record, argumentFile: caller.file }, at);
+            }
+            return argumentProvablyConverts(index, argumentKind, parameter, language, definition,
+                { file: caller.file });
+        });
+    });
+}
+
+module.exports = { positivelyFits };

package/core/callers.js

@@ -32574,6 +32574,6 @@ function findCallbackUsages(index, name) {
     return usages;
 }
 
-module.exports = { rustPathQualifierVerdict: _pathQualifierVerdict, rustTraitDeclPathProbe: _rustTraitDeclPathProbe, _recordIsNoCall, _cppMemberUsingBases, _cppTargetVisibility, rustTypeNameDenotes, _textualIncludeClosures, _textualLinkVerdict, isProvenanceBuiltinReceiver, provenanceParameterIdentity: _overloadTypeIdentity, selectProvenanceOverload, _unresolvedModuleIsGap, _nonSourceModuleFile, _moduleValueAliasType, _importReaches, _sameNominalPackageDir, getCachedCalls, getCachedCallsBearing, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable, _buildReturnTypeFlowMap, _lookupReturnTypeFlow, _cFamilySignatureKey,
+module.exports = { argumentProvablyConverts: _argProvablyConverts, cppArgumentProvablyConverts: _cppArgProvablyConverts, rustPathQualifierVerdict: _pathQualifierVerdict, rustTraitDeclPathProbe: _rustTraitDeclPathProbe, _recordIsNoCall, _cppMemberUsingBases, _cppTargetVisibility, rustTypeNameDenotes, _textualIncludeClosures, _textualLinkVerdict, isProvenanceBuiltinReceiver, provenanceParameterIdentity: _overloadTypeIdentity, selectProvenanceOverload, _unresolvedModuleIsGap, _nonSourceModuleFile, _moduleValueAliasType, _importReaches, _sameNominalPackageDir, getCachedCalls, getCachedCallsBearing, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable, _buildReturnTypeFlowMap, _lookupReturnTypeFlow, _cFamilySignatureKey,
     _isConfigurationAlternative, _isCrossFileConfigurationMember, _configurationAlternativeFiles, _sameOwnerPath,
     _goFileConstraint, _typeQueryRecords };

package/core/capture.js

@@ -63,7 +63,8 @@ const HAZARD_OF_SHIELD = Object.freeze({
  *   name in a shared scope)        package, an inclusion can reach it
  *                                  from anywhere.
  *
- * Returns a predicate over (relative path, line), or null for "anywhere".
+ * Returns candidate files and a predicate over (relative path, line), or
+ * null for "anywhere". Candidate files bound the scan before parsing.
  * An occurrence elsewhere is another name that happens to be spelled the
  * same: it could not have meant this declaration before, and cannot now.
  */
@@ -73,8 +74,8 @@ function reachOf(index, definition) {
     if (!entry) return null;
     const own = entry.relativePath;
     if (definition.lexicalScopeStartLine != null) {
-        return (file, line) => file === own &&
-            line >= definition.lexicalScopeStartLine && line <= definition.lexicalScopeEndLine;
+        return { files: new Set([own]), includes: (file, line) => file === own &&
+            line >= definition.lexicalScopeStartLine && line <= definition.lexicalScopeEndLine };
     }
     const traits = langTraits(entry.language) || {};
     if (traits.packageScope !== 'file' || traits.textualIncludes) return null;
@@ -87,7 +88,7 @@ function reachOf(index, definition) {
         for (const symbol of entry.symbols || []) if (!symbol.className) exported.add(symbol.name);
     }
     // A name the module does not export stays in the module.
-    if (!exported.has(definition.name)) return file => file === own;
+    if (!exported.has(definition.name)) return { files, includes: file => file === own };
     for (const other of index.files.values()) {
         const resolved = other.moduleResolved || {};
         const takesAll = (other.importDetails || []).some(detail =>
@@ -104,7 +105,7 @@ function reachOf(index, definition) {
                 binding.kind === 'namespace' || binding.kind === 'default'));
         if (takesAll || binds) files.add(other.relativePath);
     }
-    return file => files.has(file);
+    return { files, includes: file => files.has(file) };
 }
 
 /**
@@ -119,13 +120,19 @@ function reachOf(index, definition) {
  * @returns {{outside: {file, line}[], total: number}}
  */
 function occurrencesOutsideChange(index, name, addedLinesByFile, definition = null) {
-    const rows = index.usages(name, { includeTests: true, codeOnly: true }) || [];
     const reaches = reachOf(index, definition);
+    const options = { includeTests: true, codeOnly: true };
+    // Use the same proven module/lexical reach that filters the answer to
+    // avoid parsing unrelated files for every added declaration. The caller
+    // still assesses the full source-universe account before claiming novelty.
+    const rows = reaches
+        ? [...reaches.files].sort().flatMap(file => index.usages(name, { ...options, file }) || [])
+        : index.usages(name, options) || [];
     const outside = [];
     for (const row of rows) {
         const file = row.relativePath || row.file;
         if (addedLinesByFile.get(file)?.has(row.line)) continue;
-        if (reaches && !reaches(file, row.line)) continue;
+        if (reaches && !reaches.includes(file, row.line)) continue;
         outside.push({ file, line: row.line });
     }
     outside.sort((a, b) => (a.file === b.file ? a.line - b.line : (a.file < b.file ? -1 : 1)));
@@ -139,6 +146,31 @@ function ownersOf(index, definition) {
         type.startLine <= definition.startLine && (type.endLine || type.startLine) >= definition.startLine);
 }
 
+/** A member of a wholly new, unreachable owner cannot capture a namesake. */
+function newOwnerUnreached(index, definition, addedLinesByFile) {
+    if (!definition.className) return false;
+    const owners = ownersOf(index, definition);
+    if (owners.length !== 1) return false;
+    const owner = owners[0];
+    // An impl block, namespace or out-of-class member group can be newly
+    // written while its type existed all along (including outside source).
+    if (!['class', 'struct', 'record', 'enum', 'interface', 'trait', 'type', 'union'].includes(owner.type)) return false;
+    const memo = index._opMemo?.('checkNewOwnerReach', () => new WeakMap());
+    if (memo?.has(owner)) return memo.get(owner);
+    let unreachable = false;
+    const added = addedLinesByFile.get(owner.relativePath);
+    if (added?.has(owner.nameLine || owner.startLine) && !owner.extends && !owner.implements &&
+        !(owner.decorators || []).length && !(owner.attributes || []).length) {
+        // Name reach is the module/import scope of THIS owner, not the
+        // global spelling of a field. Bases, registrations and reflection
+        // remain separately guarded by the ordinary capture assessment.
+        const occurrences = occurrencesOutsideChange(index, owner.name, addedLinesByFile, owner);
+        unreachable = occurrences.outside.length === 0;
+    }
+    memo?.set(owner, unreachable);
+    return unreachable;
+}
+
 /** One syntax tree per file for the questions below. */
 function treeReader(index) {
     const { parseRevision } = require('./change-kinds');
@@ -328,4 +360,4 @@ function captureHazards(index, definition, facts = {}) {
     return hazards;
 }
 
-module.exports = { occurrencesOutsideChange, captureHazards, shapeChangeOf, literalsLackingMember, HAZARD_TEXT };
+module.exports = { occurrencesOutsideChange, captureHazards, shapeChangeOf, literalsLackingMember, newOwnerUnreached, HAZARD_TEXT };