ucn 5.0.6 → 5.2.0

package/core/verify.js

@@ -6,7 +6,8 @@
  */
 
 const { detectLanguage, getParser, getLanguageAdapter, safeParse, langTraits } = require('../languages');
-const { escapeRegExp, codeUnitCompare } = require('./shared');
+const { sameNode } = require('../languages/utils');
+const { escapeRegExp, codeUnitCompare, NON_CALLABLE_TYPES } = require('./shared');
 
 function codeUnitColumnForByteColumn(line, byteColumn) {
     if (!Number.isInteger(byteColumn) || byteColumn < 0) return null;
@@ -24,13 +25,14 @@ function codeUnitColumnForByteColumn(line, byteColumn) {
 
 /** Replace only AST identifier tokens on one source line. */
 function renameIdentifierTokens(index, filePath, lineNumber, oldName, newName,
-    preferredByteColumns = null, expectedCallCount = null) {
+    preferredByteColumns = null, expectedCallCount = null, tokenOptions = {}) {
     const absolute = filePath && require('path').isAbsolute(filePath)
         ? filePath : require('path').join(index.root, filePath || '');
     const content = index._readFile(absolute);
     const sourceLine = content.split('\n')[lineNumber - 1] || '';
     let byteColumns = Array.isArray(preferredByteColumns)
         ? preferredByteColumns.filter(Number.isInteger) : [];
+    const defNameByteColumns = [];
 
     if (byteColumns.length === 0) {
         const language = index.files.get(absolute)?.language ||
@@ -65,7 +67,20 @@ function renameIdentifierTokens(index, filePath, lineNumber, oldName, newName,
                             break;
                         }
                     }
-                    if (eligible) byteColumns.push(node.startPosition.column);
+                    if (eligible) {
+                        byteColumns.push(node.startPosition.column);
+                        // Definition-name token: the identifier that IS its
+                        // parent's `name` field (method_declaration name,
+                        // function_definition name, variable_declarator name).
+                        // Wrapper identity via sameNode (#233 — wrappers are
+                        // not reference-stable across walks).
+                        if (tokenOptions.definitionNameOnly && node.parent) {
+                            const nameChild = node.parent.childForFieldName?.('name');
+                            if (nameChild && sameNode(nameChild, node)) {
+                                defNameByteColumns.push(node.startPosition.column);
+                            }
+                        }
+                    }
                     continue;
                 }
                 stack.push(...(node.namedChildren || []));
@@ -73,6 +88,17 @@ function renameIdentifierTokens(index, filePath, lineNumber, oldName, newName,
         }
     }
 
+    // Definition-line discipline (fix #300, mux-measured): a def line can
+    // repeat the symbol as a parameter TYPE (`func (r *Route) BuildVarsFunc(f
+    // BuildVarsFunc) *Route`) — renaming every token breaks the type
+    // reference. Rename only the definition's own NAME token (AST name field;
+    // first occurrence as fallback) — javac/gopls rename semantics.
+    if (tokenOptions.definitionNameOnly && byteColumns.length > 1) {
+        byteColumns = defNameByteColumns.length > 0
+            ? [defNameByteColumns[0]]
+            : [Math.min(...byteColumns)];
+    }
+
     const columns = [...new Set(byteColumns
         .map(column => codeUnitColumnForByteColumn(sourceLine, column))
         .filter(Number.isInteger))].sort((a, b) => b - a);
@@ -720,7 +746,7 @@ function contractedCallerSweep(index, name, def) {
         return (a.line || 0) - (b.line || 0);
     });
 
-    return { confirmed, unverified, account };
+    return { confirmed, unverified, account, groundSet };
 }
 
 /** Map an unverified sweep entry to the public site shape (relative `file`). */
@@ -734,6 +760,14 @@ function unverifiedSiteShape(u) {
         ...(u.reason && { reason: u.reason }),
         ...(u.dispatchVia && { dispatchVia: u.dispatchVia }),
         ...(u.dispatchCandidates != null && { dispatchCandidates: u.dispatchCandidates }),
+        // External attribution (fixes #210/#220(6)/#265D): the engine already
+        // labels these routes; the JSON site must carry the flag so consumers
+        // can tell "satisfied by a contract outside the project" from
+        // project-attributed dispatch (the text band renders it already).
+        ...(u.externalContract && { externalContract: true }),
+        // Module-attribute attribution (fix #294): the name binds the module's
+        // export surface — a non-slot surface for rename purposes.
+        ...(u.moduleAttribute && { moduleAttribute: true }),
     };
 }
 
@@ -747,7 +781,7 @@ function unverifiedSiteShape(u) {
  * @returns {{ sites: Array, unverifiedSites: Array, account: object }}
  */
 function computePlanCallSites(index, name, def) {
-    const { confirmed, unverified, account } = contractedCallerSweep(index, name, def);
+    const { confirmed, unverified, account, groundSet } = contractedCallerSweep(index, name, def);
 
     const sites = [];
     const planLineSeen = new Map(); // 'file:line' -> per-line ordinal (fix #231)
@@ -782,7 +816,15 @@ function computePlanCallSites(index, name, def) {
         if (fc !== 0) return fc;
         return (a.line || 0) - (b.line || 0);
     });
-    return { sites, unverifiedSites: unverified.map(unverifiedSiteShape), account };
+    return {
+        sites,
+        unverifiedSites: unverified.map(unverifiedSiteShape),
+        // Plan-only evidence used to promote calls through a compiler-proven
+        // Go interface slot. Kept out of the public JSON surface.
+        rawUnverified: unverified,
+        account,
+        groundSet,
+    };
 }
 
 /**
@@ -1623,6 +1665,346 @@ const RESERVED_WORDS_BY_LANGUAGE = {
         'while').split(' ')),
 };
 
+/** Split a Go signature list on commas outside nested type syntax. */
+function splitGoSignatureList(raw) {
+    const text = String(raw || '').trim().replace(/^\((.*)\)$/s, '$1');
+    if (!text) return [];
+    const out = [];
+    let start = 0;
+    let round = 0;
+    let square = 0;
+    let curly = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '(') round++;
+        else if (ch === ')') round = Math.max(0, round - 1);
+        else if (ch === '[') square++;
+        else if (ch === ']') square = Math.max(0, square - 1);
+        else if (ch === '{') curly++;
+        else if (ch === '}') curly = Math.max(0, curly - 1);
+        else if (ch === ',' && round === 0 && square === 0 && curly === 0) {
+            out.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    out.push(text.slice(start).trim());
+    return out.filter(Boolean);
+}
+
+const GO_UNNAMED_TYPE_PREFIX = /^(?:\*|\[|map\[|chan(?:<-)?\s|<-chan\s|func\s*\(|interface\s*\{|struct\s*\{|\.\.\.)/;
+
+/** Turn one raw Go parameter/result declaration into its type spelling. */
+function goDeclarationType(raw) {
+    let value = String(raw || '').trim();
+    if (!value) return null;
+    // Named slots/results: `value T`, `ctx context.Context`. Unnamed type
+    // forms starting with Go type syntax (`chan T`, `func(...)`, `*T`) keep
+    // their whole text. Structured params normally handle grouped names;
+    // this fallback exists for unnamed interface slots and result tuples.
+    if (!GO_UNNAMED_TYPE_PREFIX.test(value)) {
+        const named = value.match(/^[A-Za-z_][A-Za-z0-9_]*\s+(.+)$/s);
+        if (named) value = named[1].trim();
+    }
+    return value.replace(/\s+/g, '');
+}
+
+/** Compiler-shaped Go method fingerprint: parameter types + result types. */
+function goMethodFingerprint(def) {
+    let params;
+    if (Array.isArray(def.paramsStructured) && def.paramsStructured.length > 0) {
+        params = [];
+        for (const param of def.paramsStructured) {
+            const rawType = param.type || (param.unnamed ? param.name : null);
+            const type = goDeclarationType(rawType);
+            if (!type) return null;
+            params.push(type);
+        }
+    } else if (def.params === '' || def.params == null) {
+        params = [];
+    } else {
+        params = splitGoSignatureList(def.params).map(goDeclarationType);
+        if (params.some(type => !type)) return null;
+    }
+    const results = def.returnType
+        ? splitGoSignatureList(def.returnType).map(goDeclarationType)
+        : [];
+    if (results.some(type => !type)) return null;
+    return `${params.join(',')}->${results.join(',')}`;
+}
+
+function goTypeIdentity(name, file) {
+    const pathMod = require('path');
+    return `${pathMod.dirname(file || '')}\0${name}`;
+}
+
+function goTypeDefinition(index, name, fromFile) {
+    const pathMod = require('path');
+    const dir = pathMod.dirname(fromFile || '');
+    const kinds = new Set(['struct', 'type', 'class']);
+    const defs = (index.symbols.get(name) || []).filter(candidate =>
+        candidate.file && pathMod.dirname(candidate.file) === dir &&
+        kinds.has(candidate.type));
+    if (defs.length !== 1 || defs[0].generics) return null;
+    return defs[0];
+}
+
+function goInterfaceMembers(index, interfaceDef) {
+    const out = [];
+    for (const defs of index.symbols.values()) {
+        for (const candidate of defs) {
+            if (candidate.file === interfaceDef.file &&
+                candidate.className === interfaceDef.name &&
+                candidate.type === 'method' &&
+                candidate.startLine >= interfaceDef.startLine &&
+                candidate.startLine <= interfaceDef.endLine) out.push(candidate);
+        }
+    }
+    return out;
+}
+
+/** Authored embedded-type spellings for one Go type declaration. */
+function goEmbeddedTypes(index, typeDef) {
+    const out = [];
+    for (const definitions of index.symbols.values()) {
+        for (const candidate of definitions) {
+            if (candidate.file === typeDef.file &&
+                candidate.className === typeDef.name &&
+                candidate.type === 'field' && candidate.fieldType &&
+                candidate.startLine >= typeDef.startLine &&
+                candidate.startLine <= typeDef.endLine) {
+                out.push(String(candidate.fieldType).trim());
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Complete method requirements for one project Go interface. A qualified or
+ * unresolved embedded interface makes the set open, so the caller abstains.
+ */
+function goInterfaceRequirements(index, interfaceDef, memo, visiting = new Set()) {
+    const key = `${interfaceDef.file}\0${interfaceDef.name}`;
+    if (memo.has(key)) return memo.get(key);
+    if (visiting.has(key) || interfaceDef.generics) return null;
+    visiting.add(key);
+    const requirements = new Map();
+    for (const member of goInterfaceMembers(index, interfaceDef)) {
+        const fingerprint = goMethodFingerprint(member);
+        if (!fingerprint) { visiting.delete(key); memo.set(key, null); return null; }
+        const previous = requirements.get(member.name);
+        if (previous && previous.fingerprint !== fingerprint) {
+            visiting.delete(key); memo.set(key, null); return null;
+        }
+        requirements.set(member.name, { fingerprint, defs: [member] });
+    }
+    for (const rawParent of goEmbeddedTypes(index, interfaceDef)) {
+        if (rawParent.includes('.')) {
+            visiting.delete(key); memo.set(key, null); return null;
+        }
+        const parent = (index.symbols.get(rawParent) || []).find(candidate =>
+            candidate.type === 'interface' &&
+            require('path').dirname(candidate.file || '') ===
+                require('path').dirname(interfaceDef.file || ''));
+        if (!parent) { visiting.delete(key); memo.set(key, null); return null; }
+        const inherited = goInterfaceRequirements(index, parent, memo, visiting);
+        if (!inherited) { visiting.delete(key); memo.set(key, null); return null; }
+        for (const [name, requirement] of inherited) {
+            const previous = requirements.get(name);
+            if (previous && previous.fingerprint !== requirement.fingerprint) {
+                visiting.delete(key); memo.set(key, null); return null;
+            }
+            if (!previous) requirements.set(name, requirement);
+        }
+    }
+    visiting.delete(key);
+    const result = requirements.size > 0 ? requirements : null;
+    memo.set(key, result);
+    return result;
+}
+
+/**
+ * Method set for a project Go named type, including promoted embedded methods.
+ * Unknown/external embeddings make the set open and force abstention.
+ */
+function goConcreteMethodSet(index, typeDef, memo, visiting = new Set()) {
+    const key = goTypeIdentity(typeDef.name, typeDef.file);
+    if (memo.has(key)) return memo.get(key);
+    if (visiting.has(key) || typeDef.generics) return null;
+    visiting.add(key);
+    const methods = new Map();
+    const directNames = new Set();
+    const dir = require('path').dirname(typeDef.file || '');
+    for (const [name, defs] of index.symbols) {
+        const owned = defs.filter(candidate =>
+            !NON_CALLABLE_TYPES.has(candidate.type) &&
+            candidate.className === typeDef.name && candidate.file &&
+            require('path').dirname(candidate.file) === dir &&
+            candidate.type !== 'method');
+        for (const method of owned) {
+            const fingerprint = goMethodFingerprint(method);
+            if (!fingerprint) { visiting.delete(key); memo.set(key, null); return null; }
+            const previous = methods.get(name);
+            if (previous && previous.fingerprint !== fingerprint) {
+                visiting.delete(key); memo.set(key, null); return null;
+            }
+            if (!previous) methods.set(name, { fingerprint, defs: [method] });
+            else previous.defs.push(method);
+            directNames.add(name);
+        }
+    }
+    for (const rawParent of goEmbeddedTypes(index, typeDef)) {
+        if (rawParent.includes('.')) {
+            visiting.delete(key); memo.set(key, null); return null;
+        }
+        const parent = goTypeDefinition(index, rawParent.replace(/^\*/, ''), typeDef.file);
+        if (!parent) { visiting.delete(key); memo.set(key, null); return null; }
+        const promoted = goConcreteMethodSet(index, parent, memo, visiting);
+        if (!promoted) { visiting.delete(key); memo.set(key, null); return null; }
+        for (const [name, method] of promoted) {
+            // A direct method shadows a promoted one. Two promoted methods of
+            // the same name are ambiguous in Go; abstain instead of coupling.
+            if (methods.has(name)) {
+                if (directNames.has(name)) continue;
+                visiting.delete(key); memo.set(key, null); return null;
+            }
+            methods.set(name, method);
+        }
+    }
+    visiting.delete(key);
+    memo.set(key, methods);
+    return methods;
+}
+
+function goMethodSetSatisfies(methods, requirements) {
+    if (!methods || !requirements) return false;
+    for (const [name, requirement] of requirements) {
+        if (methods.get(name)?.fingerprint !== requirement.fingerprint) return false;
+    }
+    return true;
+}
+
+function goMethodArityCompatible(def, argCount) {
+    if (!Number.isInteger(argCount)) return true;
+    let params;
+    if (Array.isArray(def.paramsStructured) && def.paramsStructured.length > 0) {
+        params = def.paramsStructured.map(param =>
+            param.type || (param.unnamed ? param.name : null));
+    } else if (def.params === '' || def.params == null) {
+        params = [];
+    } else {
+        params = splitGoSignatureList(def.params);
+    }
+    if (params.some(param => !param)) return true;
+    const variadic = params.length > 0 &&
+        goDeclarationType(params[params.length - 1])?.startsWith('...');
+    return variadic ? argCount >= params.length - 1 : argCount === params.length;
+}
+
+function goSlotCoversMethodAmbiguity(index, name, slot, raw) {
+    if (!slot || raw.reason !== 'method-ambiguous') return false;
+    const candidates = (index.symbols.get(name) || []).filter(definition =>
+        definition.className && !NON_CALLABLE_TYPES.has(definition.type) &&
+        goMethodArityCompatible(definition, raw.argCount));
+    return candidates.length > 0 && candidates.every(definition =>
+        slot.memberIdentity.has(`${require('path').resolve(definition.file)}\0${definition.startLine}`));
+}
+
+/**
+ * Compute the Go method/interface rename component containing the pinned
+ * member. Go satisfaction is implicit, so this is a bipartite fixed point:
+ * concrete types join interfaces whose complete method sets they satisfy,
+ * and every satisfier of a joined interface joins the same compiler slot.
+ */
+function goInterfaceRenameClosure(index, targetDef) {
+    if (!targetDef.className || goMethodFingerprint(targetDef) == null) return null;
+    const pathMod = require('path');
+    const interfaceMemo = new Map();
+    const methodMemo = new Map();
+    const interfaces = [];
+    for (const defs of index.symbols.values()) {
+        for (const candidate of defs) {
+            if (candidate.type !== 'interface') continue;
+            const requirements = goInterfaceRequirements(index, candidate, interfaceMemo);
+            const directTarget = goInterfaceMembers(index, candidate).find(member =>
+                member.name === targetDef.name &&
+                goMethodFingerprint(member) === goMethodFingerprint(targetDef));
+            if (requirements && directTarget) {
+                interfaces.push({
+                    key: `${candidate.file}\0${candidate.name}`,
+                    def: candidate,
+                    requirements,
+                    targetDefs: [directTarget],
+                });
+            }
+        }
+    }
+    if (interfaces.length === 0) return null;
+
+    const concreteByKey = new Map();
+    for (const definition of index.symbols.get(targetDef.name) || []) {
+        if (!definition.className || definition.type === 'method' ||
+            NON_CALLABLE_TYPES.has(definition.type)) continue;
+        const typeDef = goTypeDefinition(index, definition.className, definition.file);
+        if (!typeDef) continue;
+        const key = goTypeIdentity(typeDef.name, typeDef.file);
+        const node = concreteByKey.get(key) || {
+            key, def: typeDef, methods: goConcreteMethodSet(index, typeDef, methodMemo),
+            targetDefs: [],
+        };
+        node.targetDefs.push(definition);
+        concreteByKey.set(key, node);
+    }
+
+    const startInterface = interfaces.find(node =>
+        node.def.file === targetDef.file && node.def.name === targetDef.className);
+    const startConcreteKey = goTypeIdentity(targetDef.className, targetDef.file);
+    if (!startInterface && !concreteByKey.has(startConcreteKey)) return null;
+
+    const joinedInterfaces = new Set(startInterface ? [startInterface.key] : []);
+    const joinedConcrete = new Set(startInterface ? [] : [startConcreteKey]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const interfaceNode of interfaces) {
+            for (const concrete of concreteByKey.values()) {
+                if (!goMethodSetSatisfies(concrete.methods, interfaceNode.requirements)) continue;
+                if (joinedInterfaces.has(interfaceNode.key) && !joinedConcrete.has(concrete.key)) {
+                    joinedConcrete.add(concrete.key); changed = true;
+                }
+                if (joinedConcrete.has(concrete.key) && !joinedInterfaces.has(interfaceNode.key)) {
+                    joinedInterfaces.add(interfaceNode.key); changed = true;
+                }
+            }
+        }
+    }
+    if (joinedInterfaces.size === 0) return null;
+
+    const memberDefs = [];
+    const interfaceNames = new Set();
+    for (const node of interfaces) {
+        if (!joinedInterfaces.has(node.key)) continue;
+        interfaceNames.add(node.def.name);
+        memberDefs.push(...node.targetDefs);
+    }
+    for (const node of concreteByKey.values()) {
+        if (joinedConcrete.has(node.key)) memberDefs.push(...node.targetDefs);
+    }
+    const seen = new Set();
+    const uniqueMembers = memberDefs.filter(member => {
+        const key = `${pathMod.resolve(member.file)}\0${member.startLine}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+    return {
+        interfaceNames,
+        memberDefs: uniqueMembers,
+        memberIdentity: new Set(uniqueMembers.map(member =>
+            `${pathMod.resolve(member.file)}\0${member.startLine}`)),
+    };
+}
+
 function plan(index, name, options = {}) {
     index._beginOp();
     try {
@@ -1656,8 +2038,8 @@ function plan(index, name, options = {}) {
     // run contractedCallerSweep (v4 tiered contract), so plan and verify stay
     // in lock-step by construction. Unverified candidates are NOT planned
     // (they may target another symbol) but stay visible with reasons.
-    const { sites: planCallSites, unverifiedSites: planUnverified, account: planAccount } =
-        computePlanCallSites(index, name, def);
+    const { sites: planCallSites, unverifiedSites: planUnverified, account: planAccount,
+        groundSet: planGroundSet } = computePlanCallSites(index, name, def);
     const impactScopeWarning = computePlanScopeWarning(index, name, def, options);
 
     // Reject ambiguous multi-op invocations rather than silently coalescing.
@@ -1864,35 +2246,56 @@ function plan(index, name, options = {}) {
         // line appears ONCE however many call records it holds (fix #230 —
         // the non-global regex left the inner call behind and emitted a
         // duplicate entry per record).
-        const callLines = new Map();
-        for (const site of planCallSites) {
-            const lineKey = `${site.file}:${site.line}`;
-            const group = callLines.get(lineKey) || {
-                file: site.file,
-                absoluteFile: site.absoluteFile,
-                line: site.line,
-                expression: site.expression,
+        // Slot closure is discovered after the pin's own caller sweep. Keep a
+        // cumulative per-line record so later member sweeps can add a second
+        // exact token on the SAME line (`a.Run() || b.Run() || other.Run()`)
+        // and update one edit instead of losing it to line-level deduplication.
+        const emittedRenameCalls = new Map();
+        const emitRenameCallSites = (siteList) => {
+        const touched = new Set();
+        for (const incoming of siteList) {
+            const lineKey = `${incoming.file}:${incoming.line}`;
+            const site = emittedRenameCalls.get(lineKey) || {
+                file: incoming.file,
+                absoluteFile: incoming.absoluteFile,
+                line: incoming.line,
+                expression: incoming.expression,
                 columns: [],
                 missingColumn: false,
                 callCount: 0,
-                calledAs: site.calledAs,
+                calledAs: incoming.calledAs,
+                change: null,
             };
-            if (group.calledAs !== site.calledAs) group.calledAs = null;
-            group.callCount++;
-            if (Number.isInteger(site.column)) group.columns.push(site.column);
-            else group.missingColumn = true;
-            callLines.set(lineKey, group);
+            if (site.calledAs !== incoming.calledAs) site.calledAs = null;
+            site.callCount++;
+            if (Number.isInteger(incoming.column)) site.columns.push(incoming.column);
+            else site.missingColumn = true;
+            emittedRenameCalls.set(lineKey, site);
+            touched.add(lineKey);
         }
-        for (const site of callLines.values()) {
+        for (const lineKey of touched) {
+            const site = emittedRenameCalls.get(lineKey);
             // A renamed import preserves its local alias (`old as local` /
             // `{ old: local }`). The caller engine carries the authored name
             // in calledAs; that token must remain unchanged while the import's
             // source-side identifier is edited below.
             if (site.calledAs && site.calledAs !== name) continue;
-            const edit = renameIdentifierTokens(index,
+            let edit = renameIdentifierTokens(index,
                 site.absoluteFile || site.file, site.line, name,
                 options.renameTo, site.missingColumn ? [] : site.columns,
                 site.callCount);
+            // Column-less records restrict token eligibility to
+            // call-expression targets — which finds nothing for confirmed
+            // function-REFERENCE sites (`handler = serveWs`, macro-interior
+            // calls whose records carry no column). Retry in all-identifier
+            // mode: still AST tokens only, still refused unless the row's
+            // token count equals the engine's record count, so a line mixing
+            // the target with an unrelated same-name token stays manual.
+            if (edit.renamed === edit.source && site.missingColumn) {
+                edit = renameIdentifierTokens(index,
+                    site.absoluteFile || site.file, site.line, name,
+                    options.renameTo, null, site.callCount);
+            }
             const newExpression = edit.renamed;
             // A confirmed call through an import alias (`xf()`) is a real
             // caller but the alias spelling does not change. The required
@@ -1903,26 +2306,42 @@ function plan(index, name, options = {}) {
                 // required but cannot safely synthesize it. Never fall back
                 // to whole-line regex replacement.
                 if (site.missingColumn) {
-                    changes.push({
+                    const manual = {
                         file: site.file,
                         line: site.line,
                         expression: edit.source,
                         suggestion: `Rename call identifier "${name}" to "${options.renameTo}" manually`,
                         needsReview: true,
                         editKind: 'call',
-                    });
+                    };
+                    if (site.change) {
+                        for (const key of Object.keys(site.change)) delete site.change[key];
+                        Object.assign(site.change, manual);
+                    } else {
+                        site.change = manual;
+                        changes.push(manual);
+                    }
                 }
                 continue;
             }
-            changes.push({
+            const concrete = {
                 file: site.file,
                 line: site.line,
                 expression: edit.source,
                 suggestion: `Rename to: ${newExpression}`,
                 newExpression,
                 editKind: 'call',
-            });
+            };
+            if (site.change) {
+                for (const key of Object.keys(site.change)) delete site.change[key];
+                Object.assign(site.change, concrete);
+            } else {
+                site.change = concrete;
+                changes.push(concrete);
+            }
         }
+        };
+        emitRenameCallSites(planCallSites);
 
         // Also include import statements that reference the renamed function.
         // Name ownership (fix #230, the #217 rule): an import of the same
@@ -1933,9 +2352,19 @@ function plan(index, name, options = {}) {
         // 'no' (the binding provably resolves elsewhere) skips; 'unknown'
         // (CJS surfaces, star imports, resolver gaps) keeps the import —
         // a missed import breaks the rename just as surely.
-        const { _nameBindingReaches } = require('./callers');
+        const {
+            _nameBindingReaches,
+            _moduleAttributeBindingReaches,
+        } = require('./callers');
         const renameTargetFiles = new Set([def.file]);
-        const usages = index.usages(name, { codeOnly: true });
+        // A rename plan is repository-wide. The caller sweep already includes
+        // tests; the import/reference sweep must not silently hide them via
+        // usages()' navigation-oriented default test exclusion.
+        const usages = index.usages(name, {
+            codeOnly: true,
+            includeTests: true,
+            internalEvidence: true,
+        });
         const importUsages = usages.filter(u => u.usageType === 'import' && !u.isDefinition);
         for (const imp of importUsages) {
             // Skip if already covered by a call site change in the same file:line
@@ -2010,6 +2439,23 @@ function plan(index, name, options = {}) {
                 // re-export chain; unknown CJS/dynamic surfaces are unsafe to
                 // rewrite mechanically.
                 if (exportPath !== def.file && ownership !== 'yes') continue;
+                // Symbol identity (fix #300, mux-measured): a name-keyed
+                // export list records one entry per same-named symbol — under
+                // the METHOD pin (r *Route) BuildVarsFunc, the entry anchored
+                // at the same-named TYPE's definition line (`type
+                // BuildVarsFunc func(...)`) is the type's export surface, not
+                // the method's; renaming it silently renames the type and
+                // breaks every type reference. Skip entries whose line hosts
+                // a different same-named definition. CJS surfaces
+                // (`module.exports = { helper }`) have no def at their line
+                // and keep flowing.
+                const defsAtExportLine = (index.symbols.get(name) || []).filter(d =>
+                    d.file === exportPath &&
+                    (d.startLine === exported.line ||
+                        (d.nameLine ?? d.startLine) === exported.line));
+                const pinnedAtExportLine = defsAtExportLine.some(d =>
+                    d.file === def.file && d.startLine === def.startLine);
+                if (defsAtExportLine.length > 0 && !pinnedAtExportLine) continue;
                 const exportFile = targetEntry.relativePath || exportPath;
                 if (changes.some(change =>
                     change.file === exportFile && change.line === exported.line)) {
@@ -2034,6 +2480,109 @@ function plan(index, name, options = {}) {
             }
         }
 
+        // Python __all__ string entries are rename edits (fix #300,
+        // requests-measured): `__all__ = (..., "put", ...)` names the
+        // module-level binding by STRING — after the def and the import that
+        // binds it are renamed, the dangling entry is a compiler-checked
+        // break (pyright reportUnsupportedDunderAll). grep sees inside
+        // strings; the plan must too. Scan exactly the files whose
+        // module-level binding of the name this plan renames: the pin's own
+        // module (module-level pins only) and every file receiving an
+        // [import] edit. AST-detected: string elements of an __all__
+        // assignment matching the name exactly; dynamic __all__ manipulation
+        // stays out of scope.
+        if (!def.className) {
+            const pathMod = require('path');
+            const dunderFiles = new Set([def.file]);
+            for (const change of changes) {
+                if (change.editKind !== 'import') continue;
+                const abs = pathMod.isAbsolute(change.file)
+                    ? change.file : pathMod.join(index.root, change.file);
+                dunderFiles.add(abs);
+            }
+            for (const abs of dunderFiles) {
+                const fe = index.files.get(abs);
+                if (!fe || fe.language !== 'python') continue;
+                let content;
+                try { content = index._readFile(abs); } catch { continue; }
+                if (!content.includes('__all__')) continue;
+                const parser = getParser('python');
+                const tree = parser && (index._getParsedTree?.(abs, content, 'python') ||
+                    safeParse(parser, content));
+                if (!tree) continue;
+                const lines = content.split('\n');
+                const rel = fe.relativePath || abs;
+                const stack = [tree.rootNode];
+                while (stack.length > 0) {
+                    const node = stack.pop();
+                    if (node.type === 'assignment' || node.type === 'augmented_assignment') {
+                        const left = node.childForFieldName('left');
+                        if (left?.text !== '__all__') continue;
+                        const right = node.childForFieldName('right');
+                        if (!right) continue;
+                        const strStack = [right];
+                        while (strStack.length > 0) {
+                            const s = strStack.pop();
+                            if (s.type === 'string') {
+                                const inner = s.text.replace(/^[rbuf]*["']/i, '').replace(/["']$/, '');
+                                if (inner !== name) continue;
+                                const lineNo = s.startPosition.row + 1;
+                                if (changes.some(c => c.file === rel && c.line === lineNo)) continue;
+                                const sourceLine = lines[lineNo - 1] || '';
+                                const quoteRe = new RegExp(`(["'])${escapeRegExp(name)}\\1`, 'g');
+                                const newLine = sourceLine.replace(quoteRe, `$1${options.renameTo}$1`);
+                                if (newLine === sourceLine) continue;
+                                changes.push({
+                                    file: rel,
+                                    line: lineNo,
+                                    expression: sourceLine.trim(),
+                                    suggestion: `Update __all__ entry: ${newLine.trim()}`,
+                                    newExpression: newLine.trim(),
+                                    editKind: 'reference',
+                                });
+                            } else {
+                                for (let i = 0; i < s.namedChildCount; i++) strStack.push(s.namedChild(i));
+                            }
+                        }
+                        continue;
+                    }
+                    for (let i = 0; i < node.namedChildCount; i++) stack.push(node.namedChild(i));
+                }
+            }
+        }
+
+        // Overload signatures and their implementation are ONE callable
+        // (fix #265A, def side): renaming any member must rename the whole
+        // group, or the survivors keep the old name and the compiler rejects
+        // the group (TS 2394 / pyright reportInconsistentOverload). Same
+        // closure the caller engine uses (isSignature-gated, so Java arity
+        // overloads — separate bindable methods — never close).
+        {
+            const { _closeCallableIdentityGroup } = require('./callers');
+            const identityGroup = _closeCallableIdentityGroup(
+                index, [def], definitions);
+            for (const member of identityGroup) {
+                if (member === def) continue;
+                const line = member.nameLine || member.startLine;
+                const rel = member.relativePath || member.file;
+                if (changes.some(change =>
+                    change.file === rel && change.line === line)) continue;
+                const edit = renameIdentifierTokens(index, member.file,
+                    line, name, options.renameTo,
+                    null, null, { definitionNameOnly: true });
+                if (edit.renamed === edit.source) continue;
+                changes.push({
+                    file: rel,
+                    line,
+                    expression: edit.source,
+                    suggestion: `Update overload signature: ${edit.renamed}`,
+                    newExpression: edit.renamed,
+                    isDefinition: true,
+                    editKind: 'definition',
+                });
+            }
+        }
+
         // Renaming a virtual/overridden member is one hierarchy-wide change.
         // Leaving descendant declarations behind either fails compilation
         // (Java/C#/TS override) or silently changes dispatch (Python/JS).
@@ -2043,9 +2592,68 @@ function plan(index, name, options = {}) {
             // classes in unrelated packages. Follow only children whose base
             // resolves from the child's scope to this exact parent file.
             const identityKey = (className, file) => `${file || ''}\0${className}`;
+
+            // The pinned member may itself be an override: the dispatch slot
+            // is rooted at the TOPMOST project ancestor defining the name
+            // (flask PassList.check → JSONTag.check → every sibling
+            // override; outcome-eval 2026-08-18). Climb the extends chain
+            // with the same identity discipline, emit each ancestor definer,
+            // then walk DOWN from the root so sibling overrides join too.
+            // Arity-overload languages require the ancestor's signature to
+            // be the same virtual slot (a same-name different-arity Java
+            // method is a sibling, never the root).
+            let slotRoot = { name: def.className, file: def.file };
+            const slotAncestors = [];
+            const climbed = new Set([identityKey(slotRoot.name, slotRoot.file)]);
+            for (let hop = 0; hop < 8; hop++) {
+                const parents = index._getInheritanceParents(
+                    slotRoot.name, slotRoot.file) || [];
+                let moved = false;
+                for (const parentName of parents) {
+                    const parentFile = index._resolveClassFile(parentName, slotRoot.file);
+                    if (!parentFile) continue;
+                    const parentDef = (index.symbols.get(name) || []).find(symbol =>
+                        symbol.className === parentName && symbol.file === parentFile &&
+                        !NON_CALLABLE_TYPES.has(symbol.type));
+                    if (!parentDef) continue;
+                    if (langTraits(planLang)?.hasArityOverloads &&
+                        (parentDef.paramsStructured || []).length !==
+                        (def.paramsStructured || []).length) continue;
+                    const key = identityKey(parentName, parentFile);
+                    if (climbed.has(key)) break;
+                    climbed.add(key);
+                    slotRoot = { name: parentName, file: parentFile };
+                    slotAncestors.push({ className: parentName, file: parentFile, def: parentDef });
+                    moved = true;
+                    break;
+                }
+                if (!moved) break;
+            }
+            const slotMemberDefs = [];
+            for (const ancestor of slotAncestors) {
+                slotMemberDefs.push(ancestor.def);
+                const line = ancestor.def.nameLine || ancestor.def.startLine;
+                const rel = ancestor.def.relativePath || ancestor.def.file;
+                if (changes.some(change =>
+                    change.file === rel && change.line === line)) continue;
+                const edit = renameIdentifierTokens(index, ancestor.def.file,
+                    line, name, options.renameTo,
+                    null, null, { definitionNameOnly: true });
+                if (edit.renamed === edit.source) continue;
+                changes.push({
+                    file: rel,
+                    line,
+                    expression: edit.source,
+                    suggestion: `Update base definition: ${edit.renamed}`,
+                    newExpression: edit.renamed,
+                    isDefinition: true,
+                    editKind: 'definition',
+                });
+            }
+
             const descendants = new Map();
-            const queue = [{ name: def.className, file: def.file }];
-            const visited = new Set([identityKey(def.className, def.file)]);
+            const queue = [{ name: slotRoot.name, file: slotRoot.file }];
+            const visited = new Set([identityKey(slotRoot.name, slotRoot.file)]);
             while (queue.length > 0 && descendants.size < 5000) {
                 const parent = queue.shift();
                 for (const child of index.extendedByGraph.get(parent.name) || []) {
@@ -2066,11 +2674,19 @@ function plan(index, name, options = {}) {
             for (const override of index.symbols.get(name) || []) {
                 if (!override.className ||
                     !descendants.has(identityKey(override.className, override.file))) continue;
+                // Slot-rooting can put the pin's OWN class in the descendant
+                // set. The pin handles itself; same-class siblings (Java
+                // arity overloads, TS/Python signature stubs) belong to the
+                // identity-group pass, never the hierarchy walk.
+                if (override.className === def.className &&
+                    override.file === def.file &&
+                    override.startLine !== def.startLine) continue;
                 const line = override.nameLine || override.startLine;
                 const rel = override.relativePath || override.file;
                 if (changes.some(change => change.file === rel && change.line === line)) continue;
                 const edit = renameIdentifierTokens(index, override.file,
-                    line, name, options.renameTo);
+                    line, name, options.renameTo,
+                    null, null, { definitionNameOnly: true });
                 const sourceLine = edit.source;
                 const newExpression = edit.renamed;
                 if (newExpression === sourceLine) continue;
@@ -2083,7 +2699,260 @@ function plan(index, name, options = {}) {
                     isDefinition: true,
                     editKind: 'definition',
                 });
+                slotMemberDefs.push(override);
+            }
+
+            // Go interface slots are implicit (fix #302, mux Match): there is
+            // no implements edge for the hierarchy walk above. Compute the
+            // compiler-shaped satisfaction component from complete project
+            // method sets, then rename every declaration in that component.
+            // Open method sets (external/qualified embeds, generics, unknown
+            // signatures) abstain in goInterfaceRenameClosure — absence is
+            // never treated as proof.
+            const goInterfaceSlot = planLang === 'go'
+                ? goInterfaceRenameClosure(index, def)
+                : null;
+            if (goInterfaceSlot) {
+                for (const member of goInterfaceSlot.memberDefs) {
+                    if (member.file === def.file && member.startLine === def.startLine) continue;
+                    const line = member.nameLine || member.startLine;
+                    const rel = member.relativePath || member.file;
+                    if (!changes.some(change =>
+                        change.file === rel && change.line === line)) {
+                        const edit = renameIdentifierTokens(index, member.file,
+                            line, name, options.renameTo,
+                            null, null, { definitionNameOnly: true });
+                        if (edit.renamed !== edit.source) {
+                            changes.push({
+                                file: rel,
+                                line,
+                                expression: edit.source,
+                                suggestion: `Update Go interface-slot definition: ${edit.renamed}`,
+                                newExpression: edit.renamed,
+                                isDefinition: true,
+                                editKind: 'definition',
+                            });
+                        }
+                    }
+                    slotMemberDefs.push(member);
+                }
             }
+
+            // Rust trait slots (fix #296, serde-as_cast-measured): trait
+            // impls carry `traitName` markers, not extends edges — the climb
+            // and descendant walk above cannot see them, so renaming a trait
+            // method left every impl (and the trait declaration, under an
+            // impl pin) behind. Close the slot over the trait's own
+            // declaration member and every indexed impl member implementing
+            // it, with file-identity discipline (two crates may define
+            // same-named traits — a member joins only when its trait
+            // resolves to the pin's trait FILE).
+            const slotTraitNames = new Set();
+            let pinTraitFile = null;
+            if (def.traitName) {
+                slotTraitNames.add(def.traitName);
+                pinTraitFile = index._resolveClassFile(def.traitName, def.file) || null;
+            } else if ((index.symbols.get(def.className) || []).some(d =>
+                d.type === 'trait' && d.file === def.file)) {
+                slotTraitNames.add(def.className);
+                pinTraitFile = def.file;
+            }
+            if (slotTraitNames.size > 0 && pinTraitFile) {
+                const traitName = [...slotTraitNames][0];
+                for (const member of index.symbols.get(name) || []) {
+                    if (member.file === def.file && member.startLine === def.startLine) continue;
+                    if (NON_CALLABLE_TYPES.has(member.type)) continue;
+                    let inSlot = false;
+                    if (member.traitName === traitName) {
+                        inSlot = index._resolveClassFile(traitName, member.file) === pinTraitFile;
+                    } else if (member.className === traitName && member.file === pinTraitFile &&
+                        (index.symbols.get(traitName) || []).some(d =>
+                            d.type === 'trait' && d.file === member.file)) {
+                        inSlot = true; // the trait's own declaration member
+                    }
+                    if (!inSlot) continue;
+                    const line = member.nameLine || member.startLine;
+                    const rel = member.relativePath || member.file;
+                    if (!changes.some(change => change.file === rel && change.line === line)) {
+                        const edit = renameIdentifierTokens(index, member.file,
+                            line, name, options.renameTo,
+                            null, null, { definitionNameOnly: true });
+                        if (edit.renamed !== edit.source) {
+                            changes.push({
+                                file: rel,
+                                line,
+                                expression: edit.source,
+                                suggestion: `Update trait-slot definition: ${edit.renamed}`,
+                                newExpression: edit.renamed,
+                                isDefinition: true,
+                                editKind: 'definition',
+                            });
+                        }
+                    }
+                    slotMemberDefs.push(member);
+                }
+                // Macro-generated impls are invisible to the index (the
+                // as_cast_impl! family: the `fn` lives in a macro_rules body,
+                // no impl_item node exists). A definition-shaped ground line
+                // no indexed def claims, sitting inside a macro_rules body
+                // whose token tree names `impl … <Trait>`, implements the
+                // renamed slot — compiler-connected via the impl header, so
+                // the edit is synthesized mechanically.
+                // The sweep already computed the ground set for this exact
+                // name (contractedCallerSweep) — reuse it instead of a second
+                // full-repo text scan (read-only by contract).
+                const macroGround = planGroundSet;
+                const fnRe = new RegExp(`\\bfn\\s+${escapeRegExp(name)}\\b`);
+                const implRe = new RegExp(
+                    `\\bimpl\\b[^;{}]{0,160}\\b${escapeRegExp(traitName)}\\b`);
+                for (const [macroFile, lineNos] of macroGround.perFile) {
+                    const macroEntry = index.files.get(macroFile);
+                    if (!macroEntry || macroEntry.language !== 'rust') continue;
+                    const claimed = new Set((index.symbols.get(name) || [])
+                        .filter(d => d.file === macroFile)
+                        .map(d => d.nameLine || d.startLine));
+                    let macroTree = null;
+                    let macroNodes = null;
+                    for (const lineNo of lineNos) {
+                        if (claimed.has(lineNo)) continue;
+                        const rel = macroEntry.relativePath || macroFile;
+                        if (changes.some(change =>
+                            change.file === rel && change.line === lineNo)) continue;
+                        const content = index._readFile(macroFile);
+                        if (!fnRe.test(content.split('\n')[lineNo - 1] || '')) continue;
+                        if (macroTree === null) {
+                            const parser = getParser('rust');
+                            macroTree = (parser &&
+                                (index._getParsedTree?.(macroFile, content, 'rust') ||
+                                    safeParse(parser, content))) || false;
+                            macroNodes = [];
+                            if (macroTree) {
+                                const stack = [macroTree.rootNode];
+                                while (stack.length > 0) {
+                                    const node = stack.pop();
+                                    if (node.type === 'macro_definition') {
+                                        macroNodes.push(node);
+                                        continue;
+                                    }
+                                    for (let i = 0; i < node.namedChildCount; i++) {
+                                        stack.push(node.namedChild(i));
+                                    }
+                                }
+                            }
+                        }
+                        if (!macroTree || !macroNodes) continue;
+                        const mac = macroNodes.find(m =>
+                            m.startPosition.row + 1 <= lineNo &&
+                            m.endPosition.row + 1 >= lineNo);
+                        if (!mac || !implRe.test(mac.text)) continue;
+                        const edit = renameIdentifierTokens(index, macroFile,
+                            lineNo, name, options.renameTo,
+                            null, null, { definitionNameOnly: true });
+                        if (edit.renamed === edit.source) continue;
+                        changes.push({
+                            file: rel,
+                            line: lineNo,
+                            expression: edit.source,
+                            suggestion: `Update macro-generated trait implementation: ${edit.renamed}`,
+                            newExpression: edit.renamed,
+                            isDefinition: true,
+                            editKind: 'definition',
+                        });
+                    }
+                }
+            }
+
+            // A slot rename must also carry every member's CALL sites — the
+            // pin's sweep answers for the pin only (a TagDict-typed caller
+            // of TagDict.check is a confirmed caller of the SLOT being
+            // renamed, absent from PassList.check's answer). Union the
+            // members' sweeps; their unverified candidates join the visible
+            // band with slot attribution. Bounded — a pathological slot
+            // discloses the cut instead of sweeping forever.
+            const SLOT_SWEEP_CAP = 25;
+            const siteTokenKey = site =>
+                `${site.file}:${site.line}:${Number.isInteger(site.column) ? site.column : '*'}`;
+            const seenSiteTokens = new Set(planCallSites.map(site => siteTokenKey(site)));
+            const slotMemberSites = [];
+            for (const memberDef of slotMemberDefs.slice(0, SLOT_SWEEP_CAP)) {
+                const memberSweep = computePlanCallSites(index, name, memberDef);
+                for (const site of memberSweep.sites) {
+                    const key = siteTokenKey(site);
+                    if (seenSiteTokens.has(key)) continue;
+                    seenSiteTokens.add(key);
+                    slotMemberSites.push(site);
+                }
+                // A call through a joined Go interface receiver is bound to
+                // this exact METHOD SLOT even though runtime dispatch cannot
+                // select one concrete body. Promote it for rename purposes
+                // only; caller/context evidence stays honestly unverified.
+                for (const raw of memberSweep.rawUnverified || []) {
+                    const exactInterfaceReceiver = goInterfaceSlot &&
+                        raw.reason === 'possible-dispatch' &&
+                        goInterfaceSlot.interfaceNames.has(raw.dispatchVia);
+                    const closedAmbiguity = goSlotCoversMethodAmbiguity(
+                        index, name, goInterfaceSlot, raw);
+                    if ((!exactInterfaceReceiver && !closedAmbiguity) ||
+                        raw.externalContract) continue;
+                    const relativePath = raw.relativePath ||
+                        index.files.get(raw.file)?.relativePath || raw.file;
+                    const key = siteTokenKey({
+                        file: relativePath, line: raw.line, column: raw.column,
+                    });
+                    if (seenSiteTokens.has(key)) continue;
+                    let content = raw.content || '';
+                    if (!content && raw.file) {
+                        try { content = index._getFileLines(raw.file)[raw.line - 1] || ''; }
+                        catch { /* unreadable is already disclosed by the account */ }
+                    }
+                    const analysis = analyzeCallSite(index, {
+                        file: raw.file,
+                        relativePath,
+                        line: raw.line,
+                        content,
+                        usageType: 'call',
+                        receiver: raw.receiver,
+                    }, name, 0);
+                    seenSiteTokens.add(key);
+                    slotMemberSites.push({
+                        file: relativePath,
+                        absoluteFile: raw.file,
+                        line: raw.line,
+                        ...(Number.isInteger(raw.column) && { column: raw.column }),
+                        expression: content.trim(),
+                        args: analysis.args,
+                        argCount: analysis.argCount,
+                        ...(raw.calledAs && { calledAs: raw.calledAs }),
+                    });
+                }
+                for (const site of memberSweep.unverifiedSites) {
+                    if (planUnverified.some(existing =>
+                        existing.file === site.file &&
+                        existing.line === site.line)) continue;
+                    planUnverified.push({
+                        ...site,
+                        slotMember: memberDef.className,
+                    });
+                }
+            }
+            if (slotMemberDefs.length > SLOT_SWEEP_CAP) {
+                resolved.warnings.push({
+                    message: `Dispatch slot has ${slotMemberDefs.length} member ` +
+                        `definitions; call sites were swept for the first ` +
+                        `${SLOT_SWEEP_CAP} — review the rest manually.`,
+                });
+            }
+            emitRenameCallSites(slotMemberSites);
+            // A site a slot member's sweep CONFIRMED is a planned edit now —
+            // it no longer belongs in the pin's "may need this change" band.
+            const changedLines = new Set(changes.map(change =>
+                `${change.file}:${change.line}`));
+            const keptUnverified = planUnverified.filter(site =>
+                !changedLines.has(`${site.file}:${site.line}`));
+            planUnverified.length = 0;
+            planUnverified.push(...keptUnverified);
+            planUnverified.sort((a, b) => codeUnitCompare(a.file, b.file) ||
+                a.line - b.line);
         }
 
         // C/C++ declarations and definitions are one compiler symbol. A
@@ -2108,7 +2977,8 @@ function plan(index, name, options = {}) {
                 const rel = sibling.relativePath || sibling.file;
                 if (changes.some(change => change.file === rel && change.line === line)) continue;
                 const edit = renameIdentifierTokens(index, sibling.file,
-                    line, name, options.renameTo);
+                    line, name, options.renameTo,
+                    null, null, { definitionNameOnly: true });
                 if (edit.renamed === edit.source) continue;
                 changes.push({
                     file: rel,
@@ -2121,6 +2991,181 @@ function plan(index, name, options = {}) {
                 });
             }
         }
+
+        // Reference-position usages are rename edits too (outcome-eval
+        // flask, 2026-08-18): `return decorator`, `callback=handler`,
+        // `cls.method` values. Call syntax flows through the tiered sweep;
+        // references never did — a plan-following rename left them on the
+        // old name and the toolchain rejected the result. Evidence
+        // discipline mirrors the caller engine:
+        //   - same-file, non-method pin: nearest-binder containment — the
+        //     innermost same-name def whose scope container holds the line
+        //     must be the pin (a sibling nested `decorator` keeps its own
+        //     references; ties bind nothing);
+        //   - same-file, method pin: self/cls/this-received inside the
+        //     pin's class range (receiver evidence read from the line);
+        //   - cross-file, non-method pin: the #217 import-ownership chase —
+        //     'yes' edits, 'unknown' surfaces needsReview (no synthesized
+        //     edit), 'no' skips;
+        //   - cross-file method references are receiver-blind here:
+        //     call-shaped sites already flow through the sweep and the
+        //     unverified band.
+        // Shadow discipline (the #215/#203 concern — text rows carry no
+        // localShadow flag): a module-scope pin auto-edits only rows that
+        // sit at MODULE scope themselves (`TABLE = {"h": helper}`,
+        // `module.exports = { helper }`, decorator argument lists). A row
+        // inside some function body may reference a shadowing local
+        // (`const job = job2`), and argument-position references inside
+        // functions are the parser's #221 records — the sweep's domain —
+        // so those rows surface needsReview instead of a synthesized edit.
+        // A NESTED pin's own container is exempt: inside it the pin IS the
+        // binder (`return decorator`).
+        {
+            const fileSymbols = index.files.get(def.file)?.symbols || [];
+            const scopeKinds = new Set(['function', 'method', 'constructor',
+                'private', 'get', 'set', 'property', 'classmethod', 'special']);
+            const rangeOf = symbol => ({
+                start: symbol.startLine,
+                end: symbol.endLine || symbol.startLine,
+            });
+            const containerOf = (symbol) => {
+                const target = rangeOf(symbol);
+                let best = null;
+                for (const candidate of fileSymbols) {
+                    if (candidate === symbol || !scopeKinds.has(candidate.type)) continue;
+                    const range = rangeOf(candidate);
+                    if (!(range.start <= target.start && range.end >= target.end)) continue;
+                    if (range.start === target.start && range.end === target.end) continue;
+                    if (!best || (range.end - range.start) < (best.end - best.start)) {
+                        best = range;
+                    }
+                }
+                return best; // null = module scope
+            };
+            const binders = definitions
+                .filter(candidate => candidate.file === def.file &&
+                    !NON_CALLABLE_TYPES.has(candidate.type))
+                .map(candidate => ({ def: candidate, container: containerOf(candidate) }));
+            const classKinds = new Set(['class', 'struct', 'interface', 'trait',
+                'record', 'enum', 'namespace']);
+            const pinClassRange = def.className
+                ? fileSymbols.find(symbol => symbol.name === def.className &&
+                    classKinds.has(symbol.type) &&
+                    symbol.startLine <= def.startLine &&
+                    (symbol.endLine || symbol.startLine) >= (def.endLine || def.startLine))
+                : null;
+            const selfReceived = new RegExp(
+                `(?:^|[^A-Za-z0-9_$.])(?:self|cls|this)\\s*\\.\\s*` +
+                `${escapeRegExp(name)}(?![A-Za-z0-9_$])`);
+            const unverifiedLines = new Set(planUnverified.map(site =>
+                `${site.file}:${site.line}`));
+            const insideFunctionLike = (filePath, line) => {
+                const symbols = index.files.get(filePath)?.symbols || [];
+                return symbols.some(symbol => scopeKinds.has(symbol.type) &&
+                    symbol.startLine <= line &&
+                    (symbol.endLine || symbol.startLine) >= line);
+            };
+            const pinContainer = containerOf(def);
+            for (const ref of usages) {
+                if (ref.usageType !== 'reference' || ref.isDefinition) continue;
+                const rel = ref.relativePath || ref.file;
+                if (changes.some(change =>
+                    change.file === rel && change.line === ref.line)) continue;
+                if (unverifiedLines.has(`${rel}:${ref.line}`)) continue;
+                let verdict = null;
+                if (ref.file === def.file) {
+                    if (def.className) {
+                        const lineText = ref.content ||
+                            index.getLineContent(def.file, ref.line) || '';
+                        if (pinClassRange && ref.line >= pinClassRange.startLine &&
+                            ref.line <= (pinClassRange.endLine || Infinity) &&
+                            selfReceived.test(lineText)) {
+                            verdict = 'edit';
+                        }
+                    } else {
+                        let winner = null;
+                        let ambiguous = false;
+                        for (const binder of binders) {
+                            const contains = !binder.container ||
+                                (binder.container.start <= ref.line &&
+                                    binder.container.end >= ref.line);
+                            if (!contains) continue;
+                            const size = binder.container
+                                ? binder.container.end - binder.container.start
+                                : Infinity;
+                            if (!winner || size < winner.size) {
+                                winner = { def: binder.def, size };
+                                ambiguous = false;
+                            } else if (size === winner.size &&
+                                binder.def !== winner.def) {
+                                ambiguous = true;
+                            }
+                        }
+                        if (winner && !ambiguous && winner.def === def) {
+                            if (pinContainer) {
+                                verdict = 'edit'; // nested pin binds its container
+                            } else if (!insideFunctionLike(def.file, ref.line)) {
+                                verdict = 'edit'; // module-scope row, module pin
+                            } else {
+                                verdict = 'review'; // possible local shadow
+                            }
+                        }
+                    }
+                } else if (!def.className) {
+                    // Module-attribute references carry stronger evidence
+                    // than a bare name: `import requests; requests.put` binds
+                    // through requests' export chain even inside a function.
+                    // Parser-side local-shadow evidence is a hard guard — a
+                    // parameter/assignment named requests defeats the import.
+                    const moduleOwnership = ref.receiver &&
+                        !ref.receiverLocalBinding
+                        ? _moduleAttributeBindingReaches(
+                            index, ref.file, ref.receiver, name,
+                            renameTargetFiles)
+                        : null;
+                    if (moduleOwnership === 'yes') {
+                        verdict = 'edit';
+                    } else if (moduleOwnership === 'unknown') {
+                        verdict = 'review';
+                    } else if (!ref.receiver) {
+                        const ownership = _nameBindingReaches(
+                            index, ref.file, name, renameTargetFiles);
+                        if (ownership === 'yes' &&
+                            !insideFunctionLike(ref.file, ref.line)) {
+                            verdict = 'edit';
+                        } else if (ownership !== 'no') {
+                            verdict = 'review';
+                        }
+                    }
+                }
+                if (!verdict) continue;
+                if (verdict === 'edit') {
+                    const edit = renameIdentifierTokens(index, ref.file,
+                        ref.line, name, options.renameTo,
+                        Number.isInteger(ref.column) ? [ref.column] : null);
+                    if (edit.renamed === edit.source) continue;
+                    changes.push({
+                        file: rel,
+                        line: ref.line,
+                        expression: edit.source,
+                        suggestion: `Update reference: ${edit.renamed}`,
+                        newExpression: edit.renamed,
+                        editKind: 'reference',
+                    });
+                } else {
+                    changes.push({
+                        file: rel,
+                        line: ref.line,
+                        expression: (ref.content || '').trim(),
+                        suggestion: `Verify this reference resolves to ` +
+                            `${name} at ${def.relativePath || def.file}:` +
+                            `${def.startLine} before renaming`,
+                        needsReview: true,
+                        editKind: 'reference',
+                    });
+                }
+            }
+        }
     }
 
     // Every operation changes the selected declaration. Historically `plan`
@@ -2138,7 +3183,8 @@ function plan(index, name, options = {}) {
         existingDefinitionLine.editKind = 'definition';
         if (options.renameTo) {
             const renamed = renameIdentifierTokens(index, def.file,
-                definitionLine, name, options.renameTo).renamed;
+                definitionLine, name, options.renameTo,
+                null, null, { definitionNameOnly: true }).renamed;
             existingDefinitionLine.newExpression = renamed;
             existingDefinitionLine.suggestion = `Update definition: ${renamed}`;
         }
@@ -2152,7 +3198,8 @@ function plan(index, name, options = {}) {
         };
         if (options.renameTo) {
             const renamed = renameIdentifierTokens(index, def.file,
-                definitionLine, name, options.renameTo).renamed;
+                definitionLine, name, options.renameTo,
+                null, null, { definitionNameOnly: true }).renamed;
             definitionChange.newExpression = renamed;
             definitionChange.suggestion = `Update definition: ${renamed}`;
         } else {
@@ -2174,6 +3221,7 @@ function plan(index, name, options = {}) {
             !change.editKind).length,
         imports: changes.filter(change => change.editKind === 'import').length,
         exports: changes.filter(change => change.editKind === 'export').length,
+        references: changes.filter(change => change.editKind === 'reference').length,
         reviewRequired: changes.filter(change => change.needsReview).length,
     };