ucn 5.3.3 → 5.3.5

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

@@ -39,7 +39,7 @@ answer, a notice stating the full size and limit, and the accounting/contract
 lines needed to interpret what remains; the requested limit includes all
 three. The text block is the whole response on every surface.
 
-Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use.
+Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use. Concurrent invocations on a cold cache share one build: the first process takes a build lock, the others wait for its cache (`Waiting for another ucn process building the index...` on stderr) instead of rebuilding; a lock left by a dead process is broken automatically.
 
 Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; disagreeing conditional macro identities stay visible as unverified. C++ resolution uses namespace ownership, static overload shape (including arrays), and macro-parameter requalification. C# resolution uses declared property/field receiver types plus overload and hiding discipline. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
 
@@ -220,3 +220,25 @@ file set, the unit a refactor has to break.
 - Use `search` or ordinary repository search for text, filenames, configuration, and unsupported syntax.
 
 Read [references/commands.md](references/commands.md) for all public commands and flags. Read [references/trust-contract.md](references/trust-contract.md) before building automation that gates changes on UCN output.
+
+
+### Inspect confirmation provenance
+
+Caller and callee JSON carries compact `provenance`: `rule`, contributing `rules`
+when there is more than one, `validation`, and the receiver's source and origin
+line when recorded. Incomplete proofs include a `diagnostic`, also shown in text.
+Callees retain compact `siteProvenance` for each distinct occurrence; their summary
+uses the weakest confirmed site's rule. Exclusions expose counts by rule and
+validation under `account.excluded.evidenceSummary`. Full declaration, import,
+and member-lookup facts remain on engine results and in oracle reports.
+
+A lone project owner of a method name does not identify an untyped receiver.
+Such candidates stay unverified with `single-owner`; importing the class does not
+change that. `provenance-incomplete` means the available facts cannot establish
+this declaration. Inspect the site and diagnostic before editing it. Neither
+reason is permission to discard a possible caller. `validation: unsupported`
+means the witness collector does not yet cover that path (for example a wildcard
+re-export or an external inherited member). Its existing classification is kept
+in report-only mode; it is not a validated proof. Missing or inconsistent facts
+on a supported lookup still route unverified. Full rule migration is tracked as
+#356. Ordinal evidence weights are not probabilities.

package/cli/index.js

@@ -766,8 +766,18 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers });
-        needsCacheSave = flags.cache;
+        const buildOpts = { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers };
+        if (flags.cache && !flags.maxFiles) {
+            // Cross-process build lock (fix #354): concurrent cold-cache
+            // invocations share one build instead of each rebuilding.
+            index.buildCached(buildOpts, {
+                onWait: () => { if (!flags.quiet) console.error('Waiting for another ucn process building the index...'); },
+            });
+            needsCacheSave = false; // buildCached saved (or loaded the other process's cache)
+        } else {
+            index.build(null, buildOpts);
+            needsCacheSave = flags.cache;
+        }
     }
 
     try {
@@ -986,13 +996,10 @@ function runInteractive(rootDir) {
     if (flags.cache) {
         const loaded = !flags.clearCache && index.loadCache();
         iCacheFresh = loaded && !index.isCacheStale();
-        if (!iCacheFresh && loaded) {
-            index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
-        } else if (!iCacheFresh) {
-            index.build(null, { quiet: true, workers: flags.workers });
-        }
         if (!iCacheFresh) {
-            try { index.saveCache(); } catch (_) { /* best-effort */ }
+            index.buildCached({ quiet: true, forceRebuild: !!loaded, workers: flags.workers }, {
+                onWait: () => console.log('Waiting for another ucn process building the index...'),
+            });
         }
     } else {
         index.build(null, { quiet: true, workers: flags.workers });
@@ -1113,15 +1120,19 @@ Flags can be added per-command: show myFunc --sections=source,callers
             // appeared in neighbouring answers (UCN5-044).
             if (index.isCacheStale()) {
                 console.log('Source changed; rebuilding index...');
-                index.build(null, {
+                const rebuildOpts = {
                     quiet: true,
                     forceRebuild: true,
                     followSymlinks: flags.followSymlinks,
                     maxFiles: flags.maxFiles,
                     workers: flags.workers,
-                });
-                if (flags.cache) {
-                    try { index.saveCache(); } catch (_) { /* best-effort */ }
+                };
+                if (flags.cache && !flags.maxFiles) {
+                    index.buildCached(rebuildOpts, {
+                        onWait: () => console.log('Waiting for another ucn process building the index...'),
+                    });
+                } else {
+                    index.build(null, rebuildOpts);
                 }
                 console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
             }

package/core/account.js

@@ -463,7 +463,11 @@ function buildAccount(index, name, parts) {
         confirmed,
         unverified,
         nonCall,
-        excluded: { total: excludedTotal, byReason: excludedByReason },
+        excluded: { total: excludedTotal, byReason: excludedByReason,
+            ...(excludedEntries.some(e => e.provenance) && { evidence: excludedEntries
+                .filter(e => e.provenance).map(e => ({ file: relPath(index, e.file),
+                    line: e.line, reason: e.reason, provenance: e.provenance })) }),
+        },
         unparsed: groundSet.unparsed,
         unsupported,
         unreadableFiles: groundSet.unreadableFiles,

package/core/analysis.js

@@ -1158,6 +1158,8 @@ function impact(index, name, options = {}) {
                 evidenceScore: c.evidenceScore,
                 scoreKind: c.scoreKind,
                 resolution: c.resolution,
+                ...(c.provenance && { provenance: c.provenance }),
+                ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
                 ...(c.tier && { tier: c.tier }),
                 ...analysis
             });
@@ -1190,6 +1192,8 @@ function impact(index, name, options = {}) {
             evidenceScore: c.evidenceScore,
             scoreKind: c.scoreKind,
             resolution: c.resolution,
+            ...(c.provenance && { provenance: c.provenance }),
+            ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
             tier: c.tier,
         }));
         // findCallers already applied binding, receiver, module ownership, and
@@ -1241,6 +1245,8 @@ function impact(index, name, options = {}) {
                 evidenceScore: call.evidenceScore,
                 scoreKind: call.scoreKind,
                 resolution: call.resolution,
+                ...(call.provenance && { provenance: call.provenance }),
+                ...(call.siteProvenance && { siteProvenance: call.siteProvenance }),
                 ...(call.tier && { tier: call.tier }),
                 ...analysis
             });
@@ -1262,6 +1268,8 @@ function impact(index, name, options = {}) {
             evidenceScore: u.evidenceScore,
             scoreKind: u.scoreKind,
             resolution: u.resolution,
+            ...(u.provenance && { provenance: u.provenance }),
+            ...(u.siteProvenance && { siteProvenance: u.siteProvenance }),
             tier: 'unverified',
             ...(u.reason && { reason: u.reason }),
             ...(u.dispatchVia && { dispatchVia: u.dispatchVia }),
@@ -1711,6 +1719,8 @@ function about(index, name, options = {}) {
             evidenceScore: c.evidenceScore,
             scoreKind: c.scoreKind,
             resolution: c.resolution,
+            ...(c.provenance && { provenance: c.provenance }),
+            ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
             reachable: c.reachable,
         }));
 
@@ -1735,6 +1745,8 @@ function about(index, name, options = {}) {
                 evidenceScore: c.evidenceScore,
                 scoreKind: c.scoreKind,
                 resolution: c.resolution,
+                ...(c.provenance && { provenance: c.provenance }),
+                ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
                 ...(c.reason && { reason: c.reason }),
                 ...(c.dispatchVia && { dispatchVia: c.dispatchVia }),
                 ...(c.dispatchCandidates != null && { dispatchCandidates: c.dispatchCandidates }),
@@ -1786,6 +1798,8 @@ function about(index, name, options = {}) {
             evidenceScore: c.evidenceScore,
             scoreKind: c.scoreKind,
             resolution: c.resolution,
+            ...(c.provenance && { provenance: c.provenance }),
+            ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
             reachable: c.reachable,
             ...(c.returnType && { returnType: c.returnType }),
             ...(c.paramTypes && { paramTypes: c.paramTypes }),
@@ -2392,6 +2406,8 @@ function diffImpact(index, options = {}) {
                     evidenceScore: c.evidenceScore,
                     scoreKind: c.scoreKind,
                     resolution: c.resolution,
+                    ...(c.provenance && { provenance: c.provenance }),
+                    ...(c.siteProvenance && { siteProvenance: c.siteProvenance }),
                     ...(c.tier && { tier: c.tier }),
                 })),
                 unverifiedCallers: unverified.map(u => ({
@@ -2404,6 +2420,8 @@ function diffImpact(index, options = {}) {
                     evidenceScore: u.evidenceScore,
                     scoreKind: u.scoreKind,
                     resolution: u.resolution,
+                    ...(u.provenance && { provenance: u.provenance }),
+                    ...(u.siteProvenance && { siteProvenance: u.siteProvenance }),
                     tier: 'unverified',
                     ...(u.reason && { reason: u.reason }),
                     ...(u.dispatchVia && { dispatchVia: u.dispatchVia }),

package/core/cache.js

@@ -256,6 +256,14 @@ function pruneUserCache({ force = false, now = Date.now() } = {}) {
             root = data.root || null;
             touched = Math.max(touched, Number(data.timestamp) || 0);
         } catch (_) { /* malformed/incomplete cache expires below */ }
+        // fix #354: a project whose FIRST build is in progress has no
+        // index.json yet, only a live build.lock — another process's prune
+        // must not delete the lock (or the dir) out from under the builder.
+        const lockPath = path.join(dir, BUILD_LOCK_FILE);
+        if (!root && fs.existsSync(lockPath) && !_lockIsStale(lockPath)) {
+            entries.push({ dir, touched: now, bytes: null });
+            continue;
+        }
         if (!root || !fs.existsSync(root) || now - touched > CACHE_TTL_MS) {
             try {
                 fs.rmSync(dir, { recursive: true, force: true });
@@ -699,7 +707,10 @@ function clearAllCaches() {
 // v212 (fix #342): extendsGraph/extendedByGraph no longer persisted (rebuilt on load).
 // v213 (fix #348): Python from-import records carry per-name `renames` so
 // import bindings pair each alias with its own module.
-const CACHE_FORMAT_VERSION = 214;
+// v215: receiver-type provenance records the originating AST fact (#355).
+// v224 (#355 recovery): Go declaration origins; Rust aliases, wrapper patterns,
+// copied bindings and qualified macro receivers; TS indexed array evidence.
+const CACHE_FORMAT_VERSION = 224;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**
@@ -1494,7 +1505,101 @@ function _computeReachabilityFingerprint(index) {
     return `${fileCount}:${symbolCount}:${sample}`;
 }
 
+const BUILD_LOCK_FILE = 'build.lock';
+const BUILD_LOCK_STALE_MS = 15 * 60 * 1000;
+const BUILD_LOCK_WAIT_MS = 15 * 60 * 1000;
+const BUILD_LOCK_POLL_MS = 150;
+
+function _sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function _pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+function _readLock(lockPath) {
+    try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch (_) { return null; }
+}
+
+function _lockIsStale(lockPath) {
+    const info = _readLock(lockPath);
+    if (!info) {
+        // Unreadable or half-written: judge by mtime alone
+        try { return Date.now() - fs.statSync(lockPath).mtimeMs > BUILD_LOCK_STALE_MS; } catch (_) { return true; }
+    }
+    if (info.pid && !_pidAlive(info.pid)) return true;
+    return Date.now() - (info.startedAt || 0) > BUILD_LOCK_STALE_MS;
+}
+
+/**
+ * Cross-process build lock (fix #354): N concurrent cold-cache invocations
+ * used to rebuild the whole index N times at once (6 processes on a 474k-line
+ * repo: 9s each alone, 363s each together — the stampede fires after every
+ * version bump, because the bump invalidates every cache). One process takes
+ * the lock and builds; the others wait, then load the cache it saved. A lock
+ * whose holder is dead, or older than 15 minutes, is broken. Waiters give up
+ * after 15 minutes and build themselves (a wedged holder must never make the
+ * tool hang forever).
+ *
+ * @returns {{ built: boolean, waited: boolean }}
+ */
+function buildWithLock(index, buildOpts = {}, options = {}) {
+    const cacheDir = getProjectCacheDir(index.root);
+    const lockPath = path.join(cacheDir, BUILD_LOCK_FILE);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const deadline = Date.now() + BUILD_LOCK_WAIT_MS;
+    let announced = false;
+    for (;;) {
+        let fd = null;
+        try {
+            fd = fs.openSync(lockPath, 'wx');
+        } catch (e) {
+            if (e.code !== 'EEXIST') throw e;
+        }
+        if (fd !== null) {
+            try {
+                fs.writeSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
+                fs.closeSync(fd);
+                index.build(null, buildOpts);
+                if (options.save !== false) {
+                    try { saveCache(index); } catch (_) { /* best-effort */ }
+                }
+                return { built: true, waited: announced };
+            } finally {
+                try { fs.unlinkSync(lockPath); } catch (_) { /* already gone */ }
+            }
+        }
+        if (_lockIsStale(lockPath)) {
+            try { fs.unlinkSync(lockPath); } catch (_) { /* raced */ }
+            continue;
+        }
+        if (Date.now() > deadline) {
+            index.build(null, buildOpts);
+            if (options.save !== false) {
+                try { saveCache(index); } catch (_) { /* best-effort */ }
+            }
+            return { built: true, waited: true };
+        }
+        if (!announced) {
+            announced = true;
+            if (typeof options.onWait === 'function') options.onWait(_readLock(lockPath));
+        }
+        _sleepSync(BUILD_LOCK_POLL_MS);
+        if (!fs.existsSync(lockPath)) {
+            // The holder finished: its cache is the answer unless it is
+            // already stale again (or it never saved one)
+            if (options.reload !== false && loadCache(index) && !isCacheStale(index)) {
+                return { built: false, waited: true };
+            }
+            // fall through: take the lock ourselves
+        }
+    }
+}
+
 module.exports = {
+    buildWithLock,
     saveCache, saveUsageCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded,
     getUserCacheRoot, getProjectCacheDir, getProjectCachePath,
     getLegacyProjectCacheDir, migrateLegacyProjectCache, clearProjectCache,