ucn 5.5.1 → 5.5.3

package/core/bridge.js

@@ -2279,53 +2279,6 @@ function extractNextjsRoutes(index) {
  * Detect HTTP client requests across the project.
  * Cached on `index._endpointsCache.clientRequests`.
  */
-// Python HTTP client types whose instances are receivers of request calls.
-// A receiver typed to one of these (with-binding, constructor assignment) or
-// bound to a pytest fixture that constructs one is a client by evidence, not
-// by name (fix #349: 145 of 625 real `tc.get("/api/...")` sites on one repo
-// were invisible because the receiver was not literally named `client`).
-const PY_CLIENT_TYPES = new Set([
-    'TestClient', 'Client', 'AsyncClient', 'Session', 'FlaskClient',
-    'ClientSession', 'AsyncSession', 'HTTPConnection', 'HTTPSConnection',
-]);
-const PY_CLIENT_FACTORIES = new Set(['test_client', 'Session', 'Client', 'AsyncClient']);
-const PY_REQUEST_METHODS = /^(get|post|put|delete|patch|options|head|request)$/;
-
-function _pythonClientFixtures(index) {
-    if (index._endpointsCache?.pyClientFixtures) return index._endpointsCache.pyClientFixtures;
-    const fixtures = new Set();
-    for (const [filePath, fileEntry] of index.files) {
-        if (fileEntry.language !== 'python') continue;
-        const fixtureDefs = (fileEntry.symbols || []).filter(s =>
-            (s.decorators || []).some(d => /(^|\.)fixture$/.test(String(d))));
-        if (fixtureDefs.length === 0) continue;
-        const calls = getCachedCalls(index, filePath) || [];
-        for (const def of fixtureDefs) {
-            const constructsClient = calls.some(c =>
-                c.enclosingFunction?.name === def.name &&
-                c.enclosingFunction?.startLine === def.startLine &&
-                (PY_CLIENT_TYPES.has(c.name) || (c.isMethod && PY_CLIENT_FACTORIES.has(c.name))));
-            if (constructsClient) fixtures.add(def.name);
-        }
-    }
-    if (!index._endpointsCache) index._endpointsCache = {};
-    index._endpointsCache.pyClientFixtures = fixtures;
-    return fixtures;
-}
-
-function _pythonClientReceiver(index, fileEntry, call, fixtures) {
-    if (!call.isMethod || !call.receiver || !PY_REQUEST_METHODS.test(call.name)) return null;
-    if (call.receiverType && PY_CLIENT_TYPES.has(String(call.receiverType).split('.').pop())) {
-        return 'python-client';
-    }
-    if (fixtures.size === 0 || !fixtures.has(call.receiver)) return null;
-    const fn = call.enclosingFunction;
-    if (!fn) return null;
-    const sym = (fileEntry.symbols || []).find(s => s.name === fn.name && s.startLine === fn.startLine);
-    const params = String(sym?.params || '').split(',').map(p => p.trim().split(/[:=]/)[0].trim());
-    return params.includes(call.receiver) ? 'pytest-client-fixture' : null;
-}
-
 // `fastify().route({...})` - a route declared on a freshly built server.
 const JS_SERVER_FACTORY_CALL = /^(fastify|Fastify|express|Hono|Koa)$/;
 
@@ -2347,7 +2300,7 @@ function extractClientRequests(index) {
     }
     const requests = [];
     const uncertain = [];
-    const pyFixtures = _pythonClientFixtures(index);
+    const clientProof = new (require('./client-receivers').ClientReceiverProof)(index, endpointsSession(index));
     let helperProof = null;
 
     for (const [filePath, fileEntry] of index.files) {
@@ -2431,7 +2384,9 @@ function extractClientRequests(index) {
                     continue;
                 }
                 if (!helperProof) helperProof = new RequestHelperProof(index, endpointsSession(index));
-                const proof = helperProof.classify(filePath, call);
+                const proof = call.isMethod
+                    ? { proven: !!clientProof.classify(filePath, call), reason: 'receiver-unproven' }
+                    : helperProof.classify(filePath, call);
                 const verb = call.isMethod && /^(get|post|put|delete|patch|options|head)$/i.test(call.name)
                     ? call.name.toUpperCase() : null;
                 const method = cfg.method || verb || 'ALL';
@@ -2462,7 +2417,7 @@ function extractClientRequests(index) {
             // fix #383: Go request constructors read their method and URL
             // from their own argument positions.
             if (call.requestTarget && lang === 'go' && call.receiver && !call.isPathCall &&
-                matchClientRequest({ ...call, firstStringArg: call.requestTarget.url }, lang, calls)) {
+                matchClientRequest({ ...call, firstStringArg: call.requestTarget.url }, lang, clientProof.classify(filePath, call))) {
                 const target = call.requestTarget;
                 if (isPathShaped(target.url)) {
                     // A request with a path but no scheme and host cannot be
@@ -2496,26 +2451,22 @@ function extractClientRequests(index) {
                 continue;
             }
             if (!call.firstStringArg) continue;
-            let r = matchClientRequest(call, lang, calls);
-            if (!r && lang === 'python') {
-                const framework = _pythonClientReceiver(index, fileEntry, call, pyFixtures);
-                if (framework) {
-                    r = { method: call.name.toUpperCase() === 'REQUEST' ? 'ALL' : call.name.toUpperCase(),
-                        framework, methodInferred: call.name === 'request' };
-                }
-            }
+            const conf = CLIENT_PATTERNS[lang];
+            const candidate = conf && (conf.bareCalls.has(call.name) ||
+                conf.receivers.some(p => p.methodPattern.test(call.name)));
+            const r = matchClientRequest(call, lang, candidate ? clientProof.classify(filePath, call) : null);
             if (!r) {
                 // Visible uncertainty: request-shaped call on an unrecognized
                 // receiver with a path-shaped literal. Listed, never counted.
-                const conf = CLIENT_PATTERNS[lang];
                 const pathShaped = call.firstStringArg.startsWith('/') || call.firstStringArg.includes('://');
-                if (conf && call.isMethod && call.receiver && pathShaped &&
+                if (conf && call.receiver && pathShaped &&
                     conf.receivers.some(p => p.methodPattern.test(call.name))) {
                     uncertain.push({
                         receiver: call.receiver, method: call.name, path: call.firstStringArg,
                         file: fileEntry.relativePath || filePath, absoluteFile: filePath, line: call.line,
                         callerName: call.enclosingFunction?.name || '<top-level>',
-                        reason: 'receiver-unrecognized',
+                        reason: conf.receivers.some(p => p.receiverPattern.test(call.receiver))
+                            ? 'receiver-name-only' : 'receiver-unrecognized',
                     });
                 }
                 continue;
@@ -2640,9 +2591,9 @@ function supertestProducerOf(call, calls, producers, locals) {
  * Match a call against client request patterns.
  * Returns { method, framework, methodInferred } or null.
  */
-function matchClientRequest(call, lang, allCallsInFile) {
+function matchClientRequest(call, lang, origin) {
     const conf = CLIENT_PATTERNS[lang];
-    if (!conf) return null;
+    if (!conf || !origin) return null;
 
     // 1) Bare-call patterns: fetch('/path') or fetch('/path', { method: 'POST' })
     if (!call.isMethod && conf.bareCalls.has(call.name)) {
@@ -2662,7 +2613,6 @@ function matchClientRequest(call, lang, allCallsInFile) {
     const isMethodLike = call.isMethod || (lang === 'go' && !!call.receiver && !call.isPathCall);
     if (isMethodLike && call.receiver) {
         for (const p of conf.receivers) {
-            if (!p.receiverPattern.test(call.receiver)) continue;
             if (!p.methodPattern.test(call.name)) continue;
 
             // Determine method
@@ -2697,7 +2647,7 @@ function matchClientRequest(call, lang, allCallsInFile) {
             } else {
                 method = methodName.toUpperCase();
             }
-            return { method, framework: p.framework, methodInferred: inferred };
+            return { method, framework: origin, methodInferred: inferred };
         }
     }
 

package/core/brief.js

@@ -102,7 +102,7 @@ function brief(index, name, options = {}) {
         const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
         if (!def) return null;
 
-        const language = detectLanguage(def.relativePath || def.file);
+        const language = index.languageOf(def.file || def.relativePath);
         const symbol = {
             name: def.name,
             type: def.type,
@@ -229,7 +229,10 @@ function firstSentence(text) {
 function countMembers(index, def) {
     if (!def || !def.file) return 0;
     let count = 0;
-    for (const arr of index.symbols.values()) {
+    // Build and cache loading keep each file's declaration list alongside
+    // the name index. This count only reads declarations of the pinned file.
+    const fileSymbols = index.files?.get(def.file)?.symbols;
+    for (const arr of fileSymbols ? [fileSymbols] : index.symbols.values()) {
         for (const s of arr) {
             if (s.file === def.file && s.className === def.name && s.isMethod) count++;
         }
@@ -362,8 +365,9 @@ function sideEffectsFor(index, symbol) {
         index._sideEffectCache.set(key, null);
         return null;
     }
-    const language = detectLanguage(symbol.relativePath || symbol.file);
-    const fileEntry = index.files.get(symbol.file);
+    const language = typeof index.languageOf === 'function'
+        ? index.languageOf(filePath) : detectLanguage(filePath, index.root);
+    const fileEntry = index.files.get(filePath);
     const fileImports = collectImportNames(fileEntry);
     const tags = classifySideEffects(bodyText, language, fileImports);
     index._sideEffectCache.set(key, tags);

package/core/build-worker.js

@@ -55,6 +55,7 @@ function externalMacrosFor(language) {
         consulted: new Set(),
         get objectBodies() { return resolve()?.objectBodies || EMPTY_MACROS; },
         get functionMacros() { return resolve()?.functionMacros || EMPTY_MACROS; },
+        get functionHeads() { return resolve()?.functionHeads || EMPTY_MACROS; },
     };
 }
 const signalArray = new Int32Array(signal);
@@ -180,7 +181,7 @@ if (control) {
     Atomics.wait(controlArray, workerIndex, 0);
     if (Atomics.load(controlArray, workerIndex) === 2) {
         const job = receiveMessageOnPort(port)?.message;
-        if (job) require('./rust-macro-expansion').runExpansionQueue(job, port);
+        if (job) await require('./rust-macro-expansion').runExpansionQueue(job, port);
     }
 }
 try { port.close(); } catch (_) { /* closed */ }

package/core/cache.js

@@ -14,6 +14,7 @@ const {
     classifyUnsupportedSourceFile,
 } = require('./discovery');
 const { codeUnitCompare } = require('./shared');
+const { syntaxWeightKind } = require('./source-memo');
 
 // Read UCN version for cache invalidation
 const UCN_VERSION = require('../package.json').version;
@@ -925,9 +926,123 @@ function clearAllCaches() {
 // v276 (fix #405b): a pending Rust file whose expansions the calls pass
 // reads by groups records each group's lines, expanded length and the words
 // its expansions output and its headers hold (`rustMacroExpansion.groups`).
-const CACHE_FORMAT_VERSION = 276;
+// v277: refactoring usages distinguish declarator-name tokens from value
+// references; C# local-function name tokens are definitions.
+// v278: generic invocation usages preserve the terminal name and receiver.
+// v279: C++ using facts retain their enclosing preprocessor branch groups.
+// v291: Value declarations retain lexical scope and forward-declaration facts;
+// value queries retain source-local shadow/text proofs and lexical block
+// ranges with each parse view's error positions.
+// v292: Python class syntax facts retain members, writes and dynamic stores.
+// v300: Java constructor declarations, construction arguments and delegation
+// records; qualified construction types, declaration source extents and
+// JS/TS assigned value names.
+// v303: Java producer chains retain argument counts for collection contracts.
+// v304: Java receiver producer paths retain their written type and source scope.
+// v305: Java variadic parameters retain their declared array type.
+// v306: Overload witnesses omit absent optional object fields consistently.
+// v307: Overload witnesses capture observed file fields separately.
+// v308 (fix #419): Java records without a declared canonical constructor
+// carry its parameters (`primaryParams`); record constructors delegate.
+// v309 (fix #421): C++ out-of-class constructor mem-initializers and
+// default initializations are call records.
+// v310 (fix #422): Rust bare and path call records carry the binding the
+// enclosing blocks give their name (`scopeBinding`, `receiverScopeBinding`),
+// qualified-path receivers and `macroScopeUnknown`; block `use` imports carry
+// their block lines and `use` items their visibility; files list their
+// item-position macro invocations (`itemMacros`).
+// v311 (fix #423): JS/TS module resolution follows a directory's package.json
+// `main` and maps workspace subpath exports naming absent build output to
+// their `src/` sources (persisted `moduleResolved` and import edges).
+// v312 (fix #424): Python usage records mark module-path segments
+// (`modulePath`) and the source-side name of an aliased from-import
+// (`importSource`).
+// v313 (fix #425): Go call records read method expressions `(*T).M` like
+// `T.M`, mark receivers no local binds (`receiverPackageLevel`), record
+// conversion operands, instantiated values and positional literal-element
+// selectors as values, and type type-switch bindings per clause.
+// v314 (fix #426): C# `out var` / implicitly typed pattern locals record no
+// receiver type (was the written `var`).
+// v315 (fix #427): C/C++ call records mark `field->m()` receivers
+// (`receiverFieldArrow`), the implicit object's constness
+// (`receiverConst`) and `(N)(x)` cast-or-call shapes
+// (`parenthesizedCallee`); member functions record `memberConst` /
+// `refQualifier`; a definition after a `static` declaration is `static`;
+// out-of-class conversion operators, pointer-to-member parameters,
+// `decltype(x)` locals and macro-wrapped C bodies are read; deduction
+// guides are no functions.
+// v316 (fix #428): C# call records mark implicitly typed lambda arguments
+// (`lambda:N:i`); Java files whose only parse errors are type annotations
+// before a variable arity `...` are read from the recovered parse (the
+// parameter is kept); reflection sites keyed by a parameter of the enclosing
+// callable record it (`keyParameter`).
+// v317 (fix #430): Python instance attributes (`self.x = v`), every name of
+// a Go multi-name field, Java enum fields, C/C++ members of unnamed nested
+// structs and unions (`memberPaths`) and C++ variable templates are indexed;
+// C# receivers drop the null-forgiving `!`; Java resources take their
+// declared type; C/C++ macro bodies read `#param` as a string literal.
+// v318 (fix #431): JS/TS properties a class's methods assign on `this` are
+// indexed as fields (`instanceAttribute`); value-reference records read
+// destructuring assignment targets as writes, parameter defaults as reads
+// and Python dict keys as values.
+// v319 (fix #433): a saved symbol keeps `file` (and a default `bindingId`)
+// as a 0 placeholder at its built position, so a loaded symbol has the key
+// order of a fresh build.
+// v320 (fix #434): call records of constructions through a method's own
+// receiver (`cls(..)`, `type(self)(..)`, `self.__class__(..)`, `new
+// this(..)`, `new this.constructor(..)`) carry `ownClass`.
+// v321 (fix #436): file entries carry `computedDispatchSites`, extracted
+// from the literal parse at index time (the doctor read them by parsing every
+// file on the first `repo` of a process).
+// v322: C# constructions retain terminal names and arity; nested generic receivers retain their qualifier.
+// v326: C++ files retain raw base-clause positions and their syntactic scopes.
+// v327: Python explicit-argument super calls retain a producer, not a lexical parent receiver.
+// v328: ambiguous C++ direct initializers retain empty template-call records.
+const CACHE_FORMAT_VERSION = 330;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
+function usageResultKey(index, filePath, name, mode) {
+    const hash = index.files.get(filePath)?.hash || '';
+    return `${filePath}\0${hash}\0${name}${mode ? `\0${mode}` : ''}`;
+}
+
+// A syntax family's stored value weighs what its producer declares
+// (core/source-memo.js SYNTAX_FAMILIES); a usage list weighs its sites.
+function usageResultWeight(value, mode) {
+    const kind = syntaxWeightKind(mode);
+    if (kind === 'rows') return 128 + value.length * 128;
+    return kind === 'json' ? 128 + 2 * Buffer.byteLength(JSON.stringify(value)) : 64 + value.length * 40;
+}
+
+/** Read an immutable, source-local analysis result from the shared LRU. */
+function getUsageResult(index, filePath, name, mode = '') {
+    const key = usageResultKey(index, filePath, name, mode);
+    const cached = index._usageResultCache?.get(key);
+    if (!cached) return undefined;
+    index._usageResultCache.delete(key);
+    index._usageResultCache.set(key, cached);
+    return cached.value;
+}
+
+/** Store file-local facts only; project-dependent resolutions do not belong here. */
+function storeUsageResult(index, filePath, name, mode, value) {
+    if (!index._usageResultCache || !Array.isArray(value)) return;
+    const key = usageResultKey(index, filePath, name, mode);
+    const prior = index._usageResultCache.get(key);
+    if (prior) index._usageResultCacheWeight -= prior.weight;
+    const weight = usageResultWeight(value, mode);
+    index._usageResultCache.delete(key);
+    index._usageResultCache.set(key, { value, weight });
+    index._usageResultCacheWeight += weight;
+    index.usageCacheDirty = true;
+    while (index._usageResultCache.size > 4096 || index._usageResultCacheWeight > 16 * 1024 * 1024) {
+        const oldest = index._usageResultCache.entries().next().value;
+        if (!oldest) break;
+        index._usageResultCache.delete(oldest[0]);
+        index._usageResultCacheWeight -= oldest[1].weight;
+    }
+}
+
 /**
  * Persist the small hot-name usage cache independently of index/call shards.
  * This keeps one-shot CLI repeats fast without rewriting the whole project
@@ -987,7 +1102,7 @@ function loadUsageCache(index, cacheFile) {
             if (!fileEntry || fileEntry.hash !== fileHash) continue;
             const suffix = mode ? `\0${mode}` : '';
             const key = `${filePath}\0${fileHash}\0${name}${suffix}`;
-            const weight = 64 + value.length * 40;
+            const weight = usageResultWeight(value, mode);
             restored.set(key, { value, weight });
             weightTotal += weight;
             while (restored.size > 4096 || weightTotal > 16 * 1024 * 1024) {
@@ -1058,14 +1173,18 @@ function saveCache(index, cachePath) {
     const strippedSymbols = [];
     for (const [name, defs] of index.symbols) {
         const stripped = defs.map(s => {
-            const { file, bindingId, ...rest } = s;
             const defaultBindingId = s.relativePath && s.type && s.startLine
                 ? `${s.relativePath}:${s.type}:${s.startLine}`
                 : null;
-            if (bindingId && bindingId !== defaultBindingId) {
-                rest.bindingId = bindingId;
+            // `file` and a default `bindingId` are rebuilt on load; their 0
+            // placeholders keep the key order of the built symbol (fix #433).
+            const out = {};
+            for (const key in s) {
+                if (key === 'file') out.file = 0;
+                else if (key === 'bindingId') out.bindingId = s.bindingId && s.bindingId !== defaultBindingId ? s.bindingId : 0;
+                else out[key] = s[key];
             }
-            return rest;
+            return out;
         });
         strippedSymbols.push([name, stripped]);
     }
@@ -1128,6 +1247,7 @@ function saveCache(index, cachePath) {
         //      argKinds for overload discipline (stale shapes would silently
         //      disable arity pruning)
         version: CACHE_FORMAT_VERSION,
+        callsGeneration: crypto.randomBytes(16).toString('hex'),
         ucnVersion: UCN_VERSION,  // Invalidate cache when UCN is updated
         configHash,
         discoveryHash,
@@ -1190,6 +1310,7 @@ function saveCache(index, cachePath) {
 
     // PERF-3: atomic write — tmp file + rename so concurrent readers/writers
     // never see a torn JSON. The calls/ shard write below already does this.
+    index._callsGenerationKey = cacheData.callsGeneration;
     const tmpFile = cacheFile + '.tmp';
     fs.writeFileSync(tmpFile, JSON.stringify(cacheData));
     fs.renameSync(tmpFile, cacheFile);
@@ -1254,6 +1375,7 @@ function saveCache(index, cachePath) {
             fs.rmSync(callsDir, { recursive: true, force: true });
         }
         fs.renameSync(callsTmpDir, callsDir);
+        require('./call-name-cache').save(index, callsDir);
 
         // Clean up legacy monolithic file
         const legacyFile = path.join(cacheDir, 'calls-cache.json');
@@ -1339,6 +1461,8 @@ function loadCache(index, cachePath) {
         index._rustMacroState = null;
         index._cppScope = null;
         index._contractIndex = null;
+        index._implicitConversionOwners = null;
+        index._constructionAliases = null;
         index._typeDenotation = null;
         index._languageFeatureMemo = null; // fix #380 protocol-type feature memo
 
@@ -1405,6 +1529,11 @@ function loadCache(index, cachePath) {
         // extendsGraph/extendedByGraph are derived below from the rehydrated
         // symbols (fix #342) — never read from the payload.
 
+        index._callsGenerationKey = typeof cacheData.callsGeneration === 'string'
+            ? cacheData.callsGeneration : null;
+        index._callNameCache = null;
+        index._callNameCacheReadGeneration = null;
+
         // Prepare lazy calls cache loading — load manifest but defer shard parsing.
         // Shards are loaded on first getCachedCalls access via ensureCallsCacheLoaded().
         if (index.callsCache.size === 0) {
@@ -1693,6 +1822,7 @@ function _prepareCallsCache(index, cacheFile) {
                 });
             }
             index._callsCachePrepared = true;
+            index._callNameCacheDir = path.join(cacheDir, 'calls');
             return;
         } catch (e) {
             // Corrupted manifest — fall through
@@ -2114,6 +2244,7 @@ function buildWithLock(index, buildOpts = {}, options = {}) {
 module.exports = {
     buildWithLock,
     saveCache, saveUsageCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded,
+    getUsageResult, storeUsageResult,
     ensureCallsShardForFile,
     getUserCacheRoot, getProjectCacheDir, getProjectCachePath,
     getLegacyProjectCacheDir, migrateLegacyProjectCache, clearProjectCache,

package/core/call-name-cache.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { calleeNames, codeUnitCompare } = require('./shared');
+const { fileMtime } = require('./source-memo');
+const { version } = require('../package.json');
+
+// Call-record names only. Binding, dispatch, aliases and type queries still
+// run through their ordinary record consumers.
+function snapshot(index, files, captured) {
+    return { files, captured, filesMap: index.files, graph: index.importGraph,
+        config: JSON.stringify(index.config), generation: index._callsGenerationKey };
+}
+
+function current(index, cache) {
+    return !!cache && cache.filesMap === index.files && cache.graph === index.importGraph &&
+        cache.config === JSON.stringify(index.config) && cache.files.size === index.files.size &&
+        [...cache.files].every(([file, item]) => index.files.get(file) === item.entry &&
+            item.entry.hash === item.hash);
+}
+
+function ensure(index) {
+    if (index.isProvenanceFactIndex || !index._callsGenerationKey ||
+        index._callNameCacheReadGeneration === index._callsGenerationKey) return;
+    index._callNameCacheReadGeneration = index._callsGenerationKey;
+    if (index._callNameCacheDir) load(index, index._callNameCacheDir);
+}
+
+function capture(index, collected, file, calls) {
+    if (index.isProvenanceFactIndex) return;
+    const entry = index.files.get(file), raw = index.callsCache.get(file);
+    if (!entry?.hash || raw?.hash !== entry.hash || !Array.isArray(calls) ||
+        !Number.isFinite(raw.mtime)) return;
+    const names = calleeNames(calls);
+    if ([...names].some(name => typeof name !== 'string')) return;
+    collected.set(file, { entry, hash: entry.hash, raw, rawCalls: raw.calls, names, mtime: raw.mtime });
+}
+
+function remember(index, files) {
+    if (index.isProvenanceFactIndex || files.size !== index.files.size) return;
+    index._callNameCache = snapshot(index, files, true);
+    if (index._callsGenerationKey && !index.callsCacheDirty && !index.macroExpansionDirty && index._callsCacheDir) save(index, path.join(index._callsCacheDir, 'calls'));
+}
+
+function save(index, directory) {
+    if (index.isProvenanceFactIndex) return;
+    const cache = index._callNameCache;
+    if (!cache?.captured || !index._callsGenerationKey ||
+        !current(index, cache) || !fs.existsSync(directory)) return;
+    for (const [file, item] of cache.files) {
+        if (index.files.get(file) !== item.entry ||
+            index.callsCache.get(file) !== item.raw || item.raw.calls !== item.rawCalls ||
+            item.raw.mtime !== item.mtime) return;
+    }
+    const dictionary = [...new Set([...cache.files.values()].flatMap(item =>
+        [...item.names]))].sort(codeUnitCompare);
+    const ids = new Map(dictionary.map((name, id) => [name, id]));
+    const files = [...cache.files].map(([file, item]) => [
+        path.relative(index.root, file), item.mtime,
+        [...item.names].map(name => ids.get(name)),
+    ]).sort((a, b) => codeUnitCompare(a[0], b[0]));
+    const target = path.join(directory, 'names.json');
+    try {
+        fs.writeFileSync(target + '.tmp', JSON.stringify({
+            version, format: 2, generation: index._callsGenerationKey, dictionary, files,
+        }));
+        fs.renameSync(target + '.tmp', target);
+    } catch (_) { /* A missing optimization falls back to the record shards. */ }
+}
+
+function load(index, directory) {
+    if (index.isProvenanceFactIndex) return;
+    index._callNameCache = null;
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(directory, 'names.json'), 'utf8'));
+        if (data.version !== version || data.format !== 2 ||
+            data.generation !== index._callsGenerationKey ||
+            !Array.isArray(data.dictionary) || !Array.isArray(data.files) ||
+            data.files.length !== index.files.size ||
+            data.dictionary.some(name => typeof name !== 'string') ||
+            new Set(data.dictionary).size !== data.dictionary.length) return;
+        const files = new Map();
+        for (const row of data.files) {
+            if (!Array.isArray(row) || row.length !== 3 || typeof row[0] !== 'string' ||
+                !Number.isFinite(row[1]) || !Array.isArray(row[2])) return;
+            const file = path.resolve(index.root, row[0]), entry = index.files.get(file);
+            if (!entry || files.has(file) || row[2].some(id =>
+                !Number.isInteger(id) || id < 0 || id >= data.dictionary.length) ||
+                new Set(row[2]).size !== row[2].length) return;
+            files.set(file, {
+                entry, hash: entry.hash, mtime: row[1], names: new Set(row[2].map(id => data.dictionary[id])),
+            });
+        }
+        index._callNameCache = snapshot(index, files, false);
+    } catch (_) { /* Missing or invalid names: use the record shards. */ }
+}
+
+function restore(index) {
+    if (index.isProvenanceFactIndex) return false;
+    ensure(index);
+    const cache = index._callNameCache;
+    // A fresh in-memory parse wins over persisted names, as it does over
+    // persisted call records. A rebuild discards this cache explicitly.
+    if (index.callsCache.size || !current(index, cache) ||
+        cache.generation !== index._callsGenerationKey) return false;
+    for (const [file, item] of cache.files) {
+        if (index.files.get(file) !== item.entry) return false;
+    }
+    const byName = new Map();
+    for (const [file] of index.files) {
+        for (const name of cache.files.get(file).names) {
+            let files = byName.get(name);
+            if (!files) byName.set(name, files = new Set());
+            files.add(file);
+        }
+    }
+    index.calleeIndex = byName;
+    return true;
+}
+
+function absent(index, file, name) {
+    if (index.isProvenanceFactIndex || index.callsCache.has(file)) return false;
+    ensure(index);
+    const item = index._callNameCache?.files.get(file);
+    if (!item || index.files.get(file) !== item.entry || item.entry.hash !== item.hash ||
+        item.entry.rustMacroExpansion || item.names.has(name)) return false;
+    // Match the raw record cache's mtime rule. Changed source must reach
+    // its normal read/hash/reparse path even if its previous names lacked
+    // this query. No negative binding or ownership verdict is cached.
+    try { return fileMtime(index, file) === item.mtime; } catch (_) { return false; }
+}
+
+module.exports = { capture, remember, save, load, restore, absent };

package/core/callable-scope.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/** Whether the written call lies inside the declaration's AST extent. */
+function containsCall(definition, call) {
+    const span = definition?.sourceSpan;
+    if (!span || call?.macroExpansion || definition.macroExpansion || definition.generatedByMacro) return null;
+    const line = call.line, column = call.column ?? call.callSite?.column;
+    if (!Number.isInteger(line) || !Number.isInteger(span.startLine) || !Number.isInteger(span.endLine)) return null;
+    if (line < span.startLine || line > span.endLine) return false;
+    if (Number.isInteger(column)) {
+        return (line > span.startLine || column >= span.startColumn) &&
+            (line < span.endLine || column < span.endColumn);
+    }
+    const start = call.callStart ?? call.callSite?.start;
+    if (Number.isInteger(start) && Number.isInteger(span.start) && Number.isInteger(span.end)) {
+        return start >= span.start && start < span.end;
+    }
+    return null;
+}
+
+module.exports = { containsCall };