ucn 5.0.5 → 5.1.1

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

@@ -53,7 +53,7 @@ not an accuracy grade.
 For caller-bearing `show`, `impact`, `trace`, `tests`, and `check` views:
 
 - `CONFIRMED` has binding, receiver, import, or ownership evidence for the pinned target.
-- `UNVERIFIED` is a possible target with insufficient identity evidence. Review it before a breaking change.
+- `UNVERIFIED` is a possible target with insufficient identity evidence. Review it before a breaking change. When same-name definitions cause the ambiguity, `show` lists their stable handles once above the sites so the competing targets are explicit.
 - `ACCOUNT` partitions observed literal-name lines into confirmed, unverified, non-call, excluded, and unresolved buckets. In mixed-language repositories it also counts occurrences in unsupported-language source files.
 - `CONTRACT` states the scope and completeness of that observed-text partition. When unsupported-language files contain the name, it says so explicitly and the partition-complete claim is limited to supported languages.
 - `WARNING` identifies unreadable, unparsed, or partially indexed files, and lists unsupported-language occurrence sites (file:line plus the line text) so nothing grep would show is hidden. `usages` and `tests` carry the same disclosure as a note.

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

@@ -41,16 +41,17 @@ Even when all eight hold, `account.contract.semanticComplete` remains false. Use
 
 Semantic recall can be complete while the result is still impractical: a true edge may be present only in a large unverified set. Release evaluation therefore measures both placement and the amount of review an agent must perform.
 
-- `trueEdgeUnverifiedRate` is the share of semantic oracle edges found only in the unverified tier.
+- `trueEdgeUnverifiedRate` is the share of statically exact oracle edges found only in the unverified tier. Runtime-polymorphic, compiler-dependent template, and oracle-unresolved references remain in the all-oracle view but never inflate the exact denominator.
 - `zeroActionableUnverifiedTargetRate` is the share of reviewed targets with no actionable ambiguity.
 - `actionableUnverifiedCandidatesP50`, `actionableUnverifiedCandidatesP95`, and `actionableUnverifiedCandidatesMax` measure actionable candidate-set size per target.
 - `unverifiedReviewItemsPerOracleEdge` measures effective review work relative to the oracle workload. Actionable false candidates count individually; each named runtime-dispatch family counts once.
 - `rawFalseUnverifiedPerOracleEdge` preserves the ungrouped false-candidate amplification for auditability.
+- `runtimeDependentOracleEdges`, `compilerDependentOracleEdges`, and `oracleAbstentionEdges` disclose why all-oracle coverage is broader than exact target identity.
 - `unverifiedReasons` groups candidates by the engine reason that kept them out of the confirmed tier.
 
 Configuration-gated candidates remain visible but are not labeled false when the compiler/LSP oracle did not score them. The raw JSON rollup is the source of truth for these fields; the Markdown report is generated from the same data.
 
-The publish-blocking portable-AST ceilings are: at most 10% of exact true edges left unverified, at most 20% within any sufficiently sampled symbol kind, at least 80% of targets with zero actionable ambiguity, actionable-candidate p95 at most five, and at most 0.10 effective review items per oracle edge. The semantic gate separately requires 100% in-scope recall, at least 98% confirmed-tier precision, full conservation, and 100% public-command proof recall. Passing these sampled floors is release evidence, not runtime-completeness proof.
+The publish-blocking portable-AST ceilings are: at most 10% of exact true edges left unverified, at most 20% within any sufficiently sampled symbol kind, at least 80% of targets with zero actionable ambiguity, actionable-candidate p95 at most five, and at most 0.10 effective review items per oracle edge. The semantic gate separately requires 100% in-scope recall, at least 98% confirmed-tier precision, full conservation, and 100% public-command proof recall. Three class-aware floors gate at zero: unaccounted oracle edges of the exact, runtime-dispatch, and oracle-unresolved classes (caller and callee arms; compile-time-dispatch attributions stay report-only because their non-exact band varies with the compiler oracle's environment), runtime-dispatch oracle edges excluded with reason (possible-dispatch routing is demote-only), and deferred oracle-unresolved edges that exact definition lookup pins to the target re-enter the gate-bearing universe. Passing these sampled floors is release evidence, not runtime-completeness proof.
 
 The performance gate runs each pinned repository in three independent processes with a fixed worker shape. Publish and PR gates require both CPU and wall-throughput floors on the median run, pin the expected file/LOC workload, and use the worst observed build/full-board peak RSS so memory failures cannot be averaged away. Exploratory one-process runs keep wall throughput diagnostic. Scoped reports are separate from the full release artifact; the dated rollup is release-qualified only when every required row came from a full release invocation. The composite release gate runs this stage first so verbose compiler-oracle output and report consumers cannot perturb its samples.
 

package/README.md

@@ -638,7 +638,9 @@ answers. It's guidance over the same engine, not a second implementation.
   and external consumers can be invisible. UCN reports these blind spots
   (`repo --sections=health --deep`) rather than pretending they don't exist.
 - Interface, trait, template, overload, and untyped-receiver dispatch may stay
-  in the UNVERIFIED tier with a reason instead of being guessed.
+  in the UNVERIFIED tier with a reason instead of being guessed. When
+  same-name definitions compete, `show` lists their stable handles once so
+  agents can see exactly what needs disambiguation.
 - C/C++ analysis doesn't run the preprocessor or compiler; build-specific
   branches, advanced templates, and macro expansion can remain unresolved. C#
   analysis doesn't run Roslyn; source generators and external assembly

package/core/analysis.js

@@ -12,7 +12,8 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { parse } = require('./parser');
 const { detectLanguage, langTraits } = require('../languages');
-const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots, codeUnitCompare } = require('./shared');
+const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots,
+    codeUnitCompare, formatSymbolHandle } = require('./shared');
 const { isTestFile } = require('./discovery');
 const { computeReachability, symbolKey } = require('./entrypoints');
 const { getLanguageAdapter } = require('../languages');
@@ -23,6 +24,62 @@ const { projectComputedDispatch } = require('./ast-analysis');
 // passed to one of these (the common pattern in mocha/jest/vitest).
 const _JS_TEST_FRAMEWORK_CALLS = new Set(['describe', 'it', 'test', 'spec', 'context', 'suite']);
 
+/**
+ * Give agents the exact indexed definitions behind a same-name ambiguity.
+ * Candidate handles live once on the context result rather than being copied
+ * onto every unverified site (a single broad name can have thousands).
+ */
+function buildAmbiguityCandidates(index, name, selected, unverified) {
+    const relevant = (unverified || []).filter(site =>
+        site.reason === 'method-ambiguous' || site.reason === 'ambiguous-binding');
+    if (relevant.length === 0) return null;
+    const byHandle = new Map();
+    for (const definition of (index.symbols.get(name) || [])) {
+        if (!definition.file || !definition.startLine) continue;
+        const handle = formatSymbolHandle(definition);
+        if (handle && !byHandle.has(handle)) byHandle.set(handle, definition);
+    }
+    const definitions = [...byHandle.values()]
+        .sort((a, b) => {
+            const aSelected = a.bindingId === selected.bindingId ||
+                (a.file === selected.file && a.startLine === selected.startLine);
+            const bSelected = b.bindingId === selected.bindingId ||
+                (b.file === selected.file && b.startLine === selected.startLine);
+            if (aSelected !== bSelected) return aSelected ? -1 : 1;
+            const fileCmp = codeUnitCompare(a.relativePath || a.file, b.relativePath || b.file);
+            if (fileCmp !== 0) return fileCmp;
+            if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+            return codeUnitCompare(a.type, b.type);
+        });
+    if (definitions.length < 2) return null;
+    const limit = 12;
+    const items = definitions.slice(0, limit).map(definition => ({
+        handle: formatSymbolHandle(definition),
+        type: definition.type,
+        ...(definition.className && { owner: definition.className }),
+        ...(!definition.className && definition.receiver && {
+            owner: definition.receiver.replace(/^\*/, ''),
+        }),
+        ...(!definition.className && !definition.receiver && definition.assignedReceiver && {
+            owner: definition.assignedReceiver,
+            memberAssignment: true,
+        }),
+        selected: definition.bindingId === selected.bindingId ||
+            (definition.file === selected.file && definition.startLine === selected.startLine),
+    }));
+    // reduce, not Math.max(...spread): a broad name on a monorepo can carry
+    // enough unverified sites to overflow the argument list.
+    const dispatchOwners = relevant.reduce(
+        (max, site) => Math.max(max, Number(site.dispatchCandidates) || 0), 0);
+    return {
+        name,
+        totalDefinitions: definitions.length,
+        ...(dispatchOwners > 0 && { dispatchOwners }),
+        items,
+        truncated: definitions.length > items.length,
+    };
+}
+
 /**
  * Tag each call site with `inTestCase` based on its enclosing function's
  * entry-point classification. Uses each language's `getEntryPointKind`
@@ -338,6 +395,8 @@ function context(index, name, options = {}) {
 
         typeCallers = [...typeCallers].sort(byFileLine);
         typeUnverified = [...typeUnverified].sort(byFileLine);
+        const typeAmbiguityCandidates = buildAmbiguityCandidates(
+            index, name, def, typeUnverified);
 
         const callerTotal = typeCallers.length;
         if (options.maxCallers && options.maxCallers > 0) {
@@ -366,6 +425,9 @@ function context(index, name, options = {}) {
             // Also include places where the type is used in function parameters/returns
             callers: typeCallers,
             unverifiedCallers: typeUnverified,
+            ...(typeAmbiguityCandidates && {
+                ambiguityCandidates: typeAmbiguityCandidates,
+            }),
             meta: { account: typeAccount, callerTotal }
         };
 
@@ -485,6 +547,8 @@ function context(index, name, options = {}) {
 
     const callerHistogram = buildHistogram(callers);
     const calleeHistogram = buildHistogram(callees);
+    const ambiguityCandidates = buildAmbiguityCandidates(
+        index, name, def, unverifiedCallers);
     const callerTotal = callers.length;
     const calleeTotal = callees.length;
     if (options.maxCallers && options.maxCallers > 0) {
@@ -512,6 +576,7 @@ function context(index, name, options = {}) {
         returnType: def.returnType,
         callers,
         unverifiedCallers,
+        ...(ambiguityCandidates && { ambiguityCandidates }),
         callees,
         unverifiedCallees: rawCallees.unverifiedCallees || [],
         callerHistogram,

package/core/bridge.js

@@ -835,7 +835,8 @@ function collectProjectRouterMounts(index) {
                     const targetEntry = index.files.get(targetFile);
                     if (targetEntry) {
                         const exportedReceivers = (targetEntry.exportDetails || [])
-                            .filter(exp => exp.type === 'module.exports' || exp.isDefault ||
+                            .filter(exp => (exp.type === 'module.exports' && exp.defaultLike) ||
+                                exp.isDefault ||
                                 exp.kind === 'default' || exp.type === 'export-default' ||
                                 exp.name === ref.name)
                             .map(exp => exp.localName || exp.name).filter(Boolean);

package/core/cache.js

@@ -599,7 +599,25 @@ function clearAllCaches() {
 // v166: C++ nested aliases persist their lexical owner ranges, and `auto`
 // return functions persist a unanimously inferred local concrete type. v165
 // was used during prerelease development before both fields were complete.
-const CACHE_FORMAT_VERSION = 167;
+// v173: JS/TS fluent methods persist AST-proven `this` return identity, and
+// nested const/arrow callables persist their enclosing lexical owner range.
+// v172: immutable JS/TS class-member aliases materialize their local and
+// exported callable identities, preserving declared return types through
+// factory aliases and chained receivers.
+// v171: import bindings persist their syntactic kind (named/default/namespace)
+// so an exported ESM namespace object can carry exact member ownership through
+// a downstream named or default import.
+// v170: statically-owned CommonJS property assignments persist their local
+// callable identity, allowing exact module ownership to exclude a different
+// same-name export without treating all CJS surfaces as opaque.
+// v169: CommonJS export details distinguish the value assigned directly to
+// module.exports (`defaultLike`) from property exports; this prevents a
+// namespace require from becoming a confirmed call to every exported member.
+// v168: JS/TS one-hop member-assignment defs persist assignedReceiver — the
+// object they patch (`console.log = fn` → 'console') — so the builtin-global
+// exclusion can see cross-file that a project def rebinds the global's
+// member (fix #286a); impl-kind symbols leave the bindings table (#286b).
+const CACHE_FORMAT_VERSION = 173;
 
 /**
  * Save index to cache file
@@ -640,7 +658,9 @@ function saveCache(index, cachePath) {
     // Strip redundant fields from symbols and file entries to reduce cache size.
     // v6: All paths stored as relative paths (saves ~60% on large codebases).
     // symbol.file = path.join(root, symbol.relativePath) — reconstructable
-    // symbol.bindingId = relativePath:type:startLine — reconstructable
+    // Default symbol.bindingId = relativePath:type:startLine — reconstructable.
+    // Preserve non-default IDs: synthetic declarations can share a source line
+    // and need their explicit identity to survive a cache round-trip.
     // fileEntry.path = Map key — redundant
     // fileEntry.relativePath = now the Map key — redundant
     const root = index.root;
@@ -648,6 +668,12 @@ function saveCache(index, cachePath) {
     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;
+            }
             return rest;
         });
         strippedSymbols.push([name, stripped]);
@@ -897,12 +923,15 @@ function loadCache(index, cachePath) {
                 const fileEntry = index.files.get(s.file);
                 if (fileEntry) {
                     fileEntry.symbols.push(s);
-                    fileEntry.bindings.push({
-                        id: s.bindingId,
-                        name: s.name,
-                        type: s.type,
-                        startLine: s.startLine
-                    });
+                    if (!s.memberAssigned && !s.bodyScopedName && !s.exportedAlias &&
+                        s.type !== 'impl') {
+                        fileEntry.bindings.push({
+                            id: s.bindingId,
+                            name: s.name,
+                            type: s.type,
+                            startLine: s.startLine
+                        });
+                    }
                 }
             }
         }