ucn 5.5.3 → 5.6.0

package/core/deadcode.js

@@ -15,7 +15,10 @@ const { splitParentList } = require('./graph-build');
 const { isOverrideMarked, codeUnitCompare, lineInRanges, maskBlockComments, escapeRegExp } = require('./shared');
 const { projectComputedDispatch, projectReflectionSites } = require('./ast-analysis');
 const { reflectionPatternReferences, reflectionLiteralNames } = require('./reflection');
-const { protocolMemberOf, protocolTypeOf, typedLiteralContract, rustProjectTraits } = require('./contract-membership');
+const { protocolMemberOf, protocolTypeOf, typedLiteralContract, rustProjectTraits,
+    hierarchySlotClosure, goContractClosure, structuralContractsRequiring,
+    requirementIn, resetContractIndex } = require('./contract-membership');
+const { projectKind, downstreamExposureBlocks } = require('./deletion');
 
 const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
 
@@ -245,27 +248,170 @@ function typedLiteralExternalMember(index, symbol) {
     return !!typedLiteralContract(index, symbol)?.external;
 }
 
-// Go satisfies interfaces implicitly, so no `implements` edge exists for
-// compiler/stdlib callbacks. A zero textual usage for one of these exact
-// method shapes is not evidence of deadness (sort.Interface, http.Handler,
-// io.Reader, encoding marshalers, database/sql contracts, errors helpers).
-const GO_PROTOCOL_METHODS = new Map([
-    ['Len', 0], ['Less', 2], ['Swap', 2], ['ServeHTTP', 2],
-    ['Error', 0], ['String', 0], ['Read', 1], ['Write', 1], ['Close', 0],
-    ['Seek', 2], ['ReadAt', 2], ['WriteAt', 2], ['ReadByte', 0],
-    ['WriteByte', 1], ['ReadRune', 0], ['UnreadByte', 0], ['UnreadRune', 0],
-    ['MarshalJSON', 0], ['UnmarshalJSON', 1], ['MarshalText', 0],
-    ['UnmarshalText', 1], ['MarshalBinary', 0], ['UnmarshalBinary', 1],
-    ['Scan', 1], ['Value', 0], ['LogValue', 0], ['Unwrap', 0],
-    ['Is', 1], ['As', 1],
-]);
+/**
+ * A member a subtype or a structural satisfier MUST supply. A parser fact
+ * (`requiredMember`), read from the declaration's own syntax: an interface
+ * or object-type signature that is not optional, an abstract member, a
+ * trait method without a body, a Go interface method element, a Python
+ * abstract or Protocol member, a C++ pure virtual. A default-bodied
+ * interface or trait member is an implementation, not a requirement.
+ */
+function isRequiredDeclaration(member) {
+    return member.requiredMember === true;
+}
 
-function goImplicitExternalContract(symbol) {
-    if (!symbol.className || !GO_PROTOCOL_METHODS.has(symbol.name)) return false;
+/**
+ * Is this member held in place by a contract of the PROJECT? Invisible to a
+ * name count, because a same-name declaration line is a declaration, never
+ * a use. Returns the reason, or null:
+ *
+ *   'required-slot'        it is the implementation a type owes to an
+ *                          interface, abstract class or trait it declares
+ *                          (deleting it leaves the type incomplete); or,
+ *                          where interfaces are satisfied implicitly by
+ *                          method set, the method that makes a type satisfy
+ *                          a project interface; or a descendant declares
+ *                          that it overrides it (deleting it leaves an
+ *                          override of nothing);
+ *   'structural-contract'  its type has every member a project interface,
+ *                          object type or protocol requires, so the type
+ *                          can be used as that contract without naming it.
+ *
+ * A plain override of a concrete method is neither: with it gone, calls
+ * fall back to the inherited one.
+ */
+function requiredByProjectContract(index, symbol) {
+    if (!symbol.className) {
+        // A member of an object literal declared against a project
+        // interface (`const impl: Contract = { slot() {} }`): the literal
+        // owes the interface that member unless the interface says it is
+        // optional. An out-of-project supertype may require it too.
+        const declaredAs = typedLiteralContract(index, symbol)?.projectInterface;
+        if (!declaredAs) return null;
+        const contracts = (index.symbols.get(declaredAs.name) || []).filter(type =>
+            _CLASS_KINDS.includes(type.type) && (!declaredAs.file || type.file === declaredAs.file));
+        const requirement = requirementIn(index, contracts, symbol.name);
+        return requirement === 'required' || requirement === 'unknown' ? 'required-slot' : null;
+    }
+    // An implementation written against this contract BY NAME holds the
+    // member it implements, required or default-bodied: Rust's
+    // `impl Contract for T { fn slot() }` and C#'s `void IContract.Slot()`
+    // are errors once the contract has no such member. Matched on the
+    // contract's bare name: wider than identity, and only ever withholds.
+    const contractNamedBy = member => {
+        const named = member.traitName || member.explicitInterface;
+        return named ? String(named).replace(/<.*$/s, '').split('::').pop().split('.').pop().trim() : null;
+    };
+    if ((index.symbols.get(symbol.name) || []).some(member =>
+        member !== symbol && contractNamedBy(member) === symbol.className)) return 'required-slot';
+    // A requirement is the contract, not an implementation of one: only a
+    // descendant that says it overrides it (below) holds it in place.
+    const isRequirement = isRequiredDeclaration(symbol) ||
+        (index.symbols.get(symbol.className) || []).some(type =>
+            (type.type === 'interface' || type.type === 'trait') &&
+            path.dirname(type.file) === path.dirname(symbol.file));
+    if (!isRequirement) {
+        // Interfaces satisfied implicitly by method set: the closure joins
+        // a project interface when the type satisfies it or is converted
+        // to it.
+        const implicit = goContractClosure(index, symbol);
+        const joined = implicit && implicit.interfaceNames;
+        if (joined && (joined.size ?? joined.length ?? 0) > 0) return 'required-slot';
+    }
+    const closure = hierarchySlotClosure(index, symbol);
+    if (closure) {
+        if (!isRequirement && (closure.ancestors || []).some(ancestor =>
+            (ancestor.members || []).some(member => isRequiredDeclaration(member)))) return 'required-slot';
+        if ((closure.descendants || []).some(descendant =>
+            (descendant.members || []).some(member => isOverrideMarked(member)))) return 'required-slot';
+    }
+    if (!isRequirement && structuralContractsRequiring(index, symbol).length > 0) return 'structural-contract';
+    return null;
+}
+
+/**
+ * What holds a declaration in place whatever names it: facts about the
+ * declaration itself, the same for an audit, a deletion and an addition.
+ *   runtimeContract   the language runtime or the compiler invokes it;
+ *   externalContract  it implements or overrides something defined outside
+ *                     the project;
+ *   projectContract   a contract of the project requires it (the reason:
+ *                     'required-slot' or 'structural-contract'), or null;
+ *   registered        a decorator or a framework registration may invoke
+ *                     it without naming it.
+ */
+function contractFactsOf(index, declared, lang) {
+    return {
+        runtimeContract: !!(protocolMemberOf(index, declared) || protocolTypeOf(index, declared)),
+        externalContract: !!(CLASS_AUDIT_KINDS.includes(declared.type)
+            ? _heritageReachesExternalBase(index, declared, lang, false)
+            : overridesOutOfTreeBase(index, declared) ||
+                typedLiteralExternalMember(index, declared) ||
+                implicitStandardContract(declared, lang)),
+        projectContract: requiredByProjectContract(index, declared),
+        registered: !!(isFrameworkEntrypoint(declared, index) || hasUnknownRegistrationDecorator(declared)),
+    };
+}
+
+/**
+ * An absent declaration, placed back in its owner for the questions that
+ * depend on where a member stands (which type owns it, what that type
+ * implements, what overrides it). Its recorded lines describe a revision
+ * the index does not hold; the owner's lines are the index's. Returns the
+ * record itself when it has no owner type, a re-anchored copy when its
+ * owner is the one type of that name in its file, the record unchanged when
+ * the owner is declared elsewhere (a receiver method, an impl block, an
+ * out-of-class definition), and null when several types of that name share
+ * the file and nothing says which one it stood in.
+ */
+function anchoredInOwner(index, symbol) {
+    if (!symbol.className) return symbol;
+    const owners = (index.symbols.get(symbol.className) || []).filter(type =>
+        _CLASS_KINDS.includes(type.type) && type.file === symbol.file);
+    if (owners.length > 1) return null;
+    if (owners.length === 0) return { ...symbol };
+    const line = owners[0].endLine || owners[0].startLine;
+    const anchored = { ...symbol, startLine: line, endLine: line };
+    delete anchored.nameLine;
+    delete anchored.sourceSpan;
+    return anchored;
+}
+
+/**
+ * Run `question` with an absent declaration declared again: the record
+ * joins the name's definitions for the duration, and every index derived
+ * from them (contract closures, class identity) is rebuilt before and
+ * dropped after, so nothing computed with it outlives the call.
+ */
+function withDeclared(index, declared, question) {
+    const { resetClassIdentity } = require('./class-identity');
+    const existing = index.symbols.get(declared.name);
+    if (existing) existing.push(declared);
+    else index.symbols.set(declared.name, [declared]);
+    resetContractIndex(index);
+    resetClassIdentity(index);
+    try {
+        return question(declared);
+    } finally {
+        if (existing) existing.splice(existing.lastIndexOf(declared), 1);
+        else index.symbols.delete(declared.name);
+        resetContractIndex(index);
+        resetClassIdentity(index);
+    }
+}
+
+/**
+ * A method shaped like a member of a standard contract the language lets a
+ * type satisfy without naming it (trait `implicitStandardContracts`: Go's
+ * sort.Interface, http.Handler, io.Reader, the encoding marshalers ...).
+ */
+function implicitStandardContract(symbol, lang) {
+    const methods = langTraits(lang)?.implicitStandardContracts;
+    if (!methods || !symbol.className || !methods.has(symbol.name)) return false;
     const arity = Array.isArray(symbol.paramsStructured)
         ? symbol.paramsStructured.length
         : null;
-    return arity == null || arity === GO_PROTOCOL_METHODS.get(symbol.name);
+    return arity == null || arity === methods.get(symbol.name);
 }
 
 // Symbol types whose definition NAME line provably cannot reference a
@@ -364,53 +510,37 @@ function nameOnlySelfRecursive(index, name) {
  * part of both text and JSON output.
  */
 function scanDeadcodeCoverage(index, names) {
-    const matchedNames = new Set();
-    const files = new Set();
-    const unreadableFiles = new Set();
     const reasons = {};
-    let unknownCoverage = false;
     let parseRecoveries = 0;
 
-    const recordReason = (reason) => {
-        const key = reason || 'unknown';
-        reasons[key] = (reasons[key] || 0) + 1;
-    };
-    const scanContent = (content) => {
-        const identifiers = new Set(String(content).match(/\b[a-zA-Z_]\w*\b/g) || []);
-        for (const name of names) {
-            if (/^[a-zA-Z_]\w*$/.test(name)
-                ? identifiers.has(name)
-                : String(content).includes(name)) matchedNames.add(name);
-        }
-    };
-    const scanFile = (absPath, rel, reason) => {
-        files.add(rel);
-        recordReason(reason);
-        try {
-            const stat = fs.statSync(absPath);
-            if (!stat.isFile()) {
-                unknownCoverage = true;
-                return;
-            }
-            scanContent(index._readFile(absPath));
-        } catch (_) {
-            unreadableFiles.add(rel);
-            unknownCoverage = true;
-        }
-    };
-
+    // One classification and one scanner for every command
+    // (core/source-universe.js): parse failures and text-only source are
+    // searched for the candidate names in a single pass per file; a path
+    // nothing can be read from withdraws every claim.
+    const sourceUniverse = require('./source-universe');
+    const failed = [];
     for (const failedPath of index.failedFiles || []) {
         if (index.files.has(failedPath)) continue;
-        scanFile(failedPath, path.relative(index.root, failedPath), 'parse-failure');
-    }
-    for (const skipped of index.unsupportedFiles || []) {
-        const rel = skipped.relativePath;
-        scanFile(path.join(index.root, rel), rel, 'unsupported-language');
+        failed.push({
+            absolutePath: failedPath,
+            relativePath: path.relative(index.root, failedPath),
+            reason: 'parse-failure',
+        });
     }
-    for (const issue of index.discoveryIssues || []) {
-        const rel = issue.relativePath || '.';
-        scanFile(path.join(index.root, rel), rel, issue.reason || 'discovery-gap');
+    const scanned = sourceUniverse.scanTextOnlyNames(index, names, failed);
+    const matchedNames = scanned.matchedNames;
+    const files = new Set(scanned.files);
+    const unreadableFiles = new Set(scanned.unreadableFiles);
+    for (const [reason, count] of Object.entries(scanned.reasons)) reasons[reason] = count;
+    const { opaque } = sourceUniverse.universe(index);
+    for (const entry of opaque) {
+        files.add(entry.relativePath);
+        const key = entry.reason || 'discovery-gap';
+        reasons[key] = (reasons[key] || 0) + 1;
+        if (entry.reason === 'unreadable-file') unreadableFiles.add(entry.relativePath);
     }
+    const unknownCoverage = opaque.length > 0 || unreadableFiles.size > 0;
+
     for (const [, fileEntry] of index.files) {
         if (fileEntry.parseRecovery || fileEntry.parseError) parseRecoveries++;
     }
@@ -748,12 +878,78 @@ function deadcode(index, options = {}) {
     index._beginOp();
     try {
     const results = [];
+    // This pipeline IS the deletion eligibility rule. The audit runs it over
+    // every name; a deletion assessment (core/deletion.js) runs the same
+    // code over one name and asks why each declaration was or was not
+    // claimed. `names` restricts the pass, `explain(symbol, reason, detail)`
+    // reports every outcome (detail: the audit row of a claim, the sites of
+    // a use). Neither changes what is claimed.
+    const onlyNames = options.names instanceof Set ? options.names : null;
+    const explain = typeof options.explain === 'function' ? options.explain : null;
+    const withhold = (symbol, reason, detail) => { if (explain) explain(symbol, reason, detail); };
+    // Assessment only: names whose every call site the caller has shown to
+    // lie inside the declaration being assessed. Those calls are deleted
+    // with it, so the name goes on to the text scan under the recursion
+    // carve-out below. The audit never sets this.
+    const ownBodyOnly = options.ownBodyOnly instanceof Set ? options.ownBodyOnly : null;
+    // Declarations the index does not hold (deleted since, or read from a
+    // base revision), assessed from their own record against this index's
+    // uses of the name. Their line numbers describe a file that no longer
+    // has them, so they never mark a definition site in the current text.
+    const absent = new Map(); // symbol record -> file entry of its revision
+    const absentByName = new Map();
+    for (const extra of Array.isArray(options.declarations) ? options.declarations : []) {
+        const symbol = extra.symbol;
+        if (!symbol || !symbol.name) continue;
+        if (!symbol.relativePath) {
+            symbol.relativePath = path.relative(index.root, symbol.file).split(path.sep).join('/');
+        }
+        // With no file facts from the revision it was declared in, only what
+        // the record itself says is known: nothing is exported by a list the
+        // file no longer has.
+        absent.set(symbol, extra.fileEntry || index.files.get(symbol.file) || {
+            language: detectLanguage(symbol.file, index.root),
+            relativePath: symbol.relativePath,
+            symbols: [], exports: [], exportDetails: [], imports: [], bindings: [],
+        });
+        if (!absentByName.has(symbol.name)) absentByName.set(symbol.name, []);
+        absentByName.get(symbol.name).push(symbol);
+    }
+    // Where a member stands decides what it implements and what overrides
+    // it. An absent declaration answers those questions standing in its
+    // owner again (anchoredInOwner); null means it cannot be placed, and
+    // its contracts cannot be checked.
+    const anchored = new Map();
+    for (const symbol of absent.keys()) anchored.set(symbol, anchoredInOwner(index, symbol));
+    // The answers that depend on where a member stands. For an absent
+    // declaration they are computed together, under one overlay.
+    const standingFacts = (declared, lang) => contractFactsOf(index, declared, lang);
+    const absentFacts = new Map();
+    const standing = (symbol, lang) => {
+        if (!absent.has(symbol)) return null;
+        if (!absentFacts.has(symbol)) {
+            absentFacts.set(symbol, withDeclared(index, anchored.get(symbol),
+                declared => standingFacts(declared, lang)));
+        }
+        return absentFacts.get(symbol);
+    };
+    const symbolsOf = name => (absentByName.has(name)
+        ? [...(index.symbols.get(name) || []), ...absentByName.get(name)]
+        : index.symbols.get(name) || []);
+    const fileEntryOf = symbol => absent.get(symbol) || index.files.get(symbol.file);
+    const namedSymbols = absent.size === 0 ? index.symbols : (function* merged() {
+        for (const [name] of index.symbols) yield [name, symbolsOf(name)];
+        for (const name of absentByName.keys()) {
+            if (!index.symbols.has(name)) yield [name, symbolsOf(name)];
+        }
+    })();
     let excludedDecorated = 0;
     let excludedExported = 0;
     let excludedExternalContract = 0;
     let excludedRuntimeContract = 0;
     let excludedConstructors = 0;
     let excludedDynamicDispatch = 0;
+    let excludedRequiredSlot = 0;
     const computedDispatchByFile = projectComputedDispatch(index);
     const computedDispatchReceivers = new Set();
     const computedDispatchInfo = { count: 0, fileCount: 0, files: [] };
@@ -843,10 +1039,15 @@ function deadcode(index, options = {}) {
     const classAuditSet = new Set(CLASS_AUDIT_KINDS);
     const callableNames = new Set();
     for (const [symbolName, symbols] of index.symbols) {
+        if (onlyNames && !onlyNames.has(symbolName)) continue;
         if (symbols.some(s => auditTypeSet.has(s.type))) {
             callableNames.add(symbolName);
         }
     }
+    for (const [symbolName, symbols] of absentByName) {
+        if (onlyNames && !onlyNames.has(symbolName)) continue;
+        if (symbols.some(s => auditTypeSet.has(s.type))) callableNames.add(symbolName);
+    }
 
     // Pre-filter: names in the callee index have call sites → definitely used → not dead.
     // Exception (fix #253c): a name whose EVERY call site sits inside a
@@ -858,7 +1059,7 @@ function deadcode(index, options = {}) {
     for (const name of callableNames) {
         if (!index.calleeIndex.has(name)) {
             potentiallyDeadNames.add(name);
-        } else if (nameOnlySelfRecursive(index, name)) {
+        } else if ((ownBodyOnly && ownBodyOnly.has(name)) || nameOnlySelfRecursive(index, name)) {
             selfRecursiveNames.add(name);
             potentiallyDeadNames.add(name);
         }
@@ -867,12 +1068,12 @@ function deadcode(index, options = {}) {
     // Pre-filter exported symbols from the scan set when not auditing exports.
     // Go exports ~63K capitalized names on K8s — scanning these in Phase 2 only to
     // skip them in Phase 3 wastes O(63K × 11K files) = ~700M comparisons.
-    if (!options.includeExported) {
+    if (downstreamExposureBlocks(index, true, options)) {
         const narrowed = new Set();
         for (const name of potentiallyDeadNames) {
-            const syms = index.symbols.get(name) || [];
+            const syms = symbolsOf(name);
             // Keep the name only if at least one definition is NOT exported
-            const allExported = syms.every(s => symbolIsExported(index, s, index.files.get(s.file)));
+            const allExported = syms.every(s => symbolIsExported(index, s, fileEntryOf(s)));
             if (!allExported) narrowed.add(name);
         }
         potentiallyDeadNames = narrowed;
@@ -884,7 +1085,7 @@ function deadcode(index, options = {}) {
     if (options.file) {
         const filteredNames = new Set();
         for (const name of potentiallyDeadNames) {
-            const syms = index.symbols.get(name) || [];
+            const syms = symbolsOf(name);
             if (syms.some(s => s.relativePath && s.relativePath.includes(options.file))) {
                 filteredNames.add(name);
             }
@@ -937,11 +1138,6 @@ function deadcode(index, options = {}) {
     }
 
     const coverage = scanDeadcodeCoverage(index, potentiallyDeadNames);
-    const coverageSuppressedNames = new Set([
-        ...coverage.matchedNames,
-        ...literalReflectionNames,
-        ...macroSuppressedNames,
-    ]);
     if (coverage.claimsWithdrawn) {
         // An unreadable file/directory can contain a use of any candidate.
         // Returning no deletion candidates is the only sound verdict.
@@ -1245,8 +1441,16 @@ function deadcode(index, options = {}) {
         }
     }
 
-    for (const [name, symbols] of index.symbols) {
-        if (coverage.claimsWithdrawn || coverageSuppressedNames.has(name)) continue;
+    for (const [name, symbols] of namedSymbols) {
+        if (onlyNames && !onlyNames.has(name)) continue;
+        // A name-level withdrawal: no declaration of this name is claimed.
+        // The audit skips the name; an assessment still walks the chain so
+        // a more specific reason (the name has callers) is reported first.
+        const withdrawn = coverage.claimsWithdrawn ? 'unsearchable-source'
+            : literalReflectionNames.has(name) ? 'reflection'
+                : macroSuppressedNames.has(name) ? 'macro-reference'
+                    : coverage.matchedNames.has(name) ? 'unanalyzed-occurrence' : null;
+        if (withdrawn && !explain) continue;
         // Definition NAME lines of same-name def-kind symbols are
         // declarations, not usages — two never-called same-name methods used
         // to keep each other alive (fix #243: three unreferenced `delete`
@@ -1257,6 +1461,7 @@ function deadcode(index, options = {}) {
             if (sameNameDefLines) return sameNameDefLines;
             sameNameDefLines = new Map();
             for (const other of symbols) {
+                if (absent.has(other)) continue;
                 if (!DEF_NAME_LINE_KINDS.has(other.type)) continue;
                 const ln = other.nameLine ?? other.startLine;
                 if (ln == null) continue;
@@ -1277,6 +1482,7 @@ function deadcode(index, options = {}) {
             if (sameNameDefRanges) return sameNameDefRanges;
             sameNameDefRanges = new Map();
             for (const other of symbols) {
+                if (absent.has(other)) continue;
                 if (!DEF_NAME_LINE_KINDS.has(other.type)) continue;
                 let arr = sameNameDefRanges.get(other.file);
                 if (!arr) { arr = []; sameNameDefRanges.set(other.file, arr); }
@@ -1288,6 +1494,7 @@ function deadcode(index, options = {}) {
         for (const symbol of symbols) {
             // Skip non-audited types (callableTypes defined above)
             if (!auditTypeSet.has(symbol.type)) {
+                withhold(symbol, 'kind-not-audited');
                 continue;
             }
 
@@ -1297,19 +1504,22 @@ function deadcode(index, options = {}) {
             // surface (ECMA-262 body-only scope). Auditing them claims
             // callback handlers dead (`app.on('ready', function boot(){})`).
             if (symbol.bodyScopedName) {
+                withhold(symbol, 'expression-scoped-name');
                 continue;
             }
             // Generated by a project macro_rules! invocation (fix #374): the
             // definition is the macro's template or the invocation's
             // arguments, never a deletable declaration of its own.
             if (symbol.macroExpansion) {
+                withhold(symbol, 'macro-generated');
                 continue;
             }
-            const fileEntry = index.files.get(symbol.file);
+            const fileEntry = fileEntryOf(symbol);
             const lang = fileEntry?.language;
 
             // Skip bundled/minified files (webpack bundles, build artifacts)
             if (fileEntry?.isBundled) {
+                withhold(symbol, 'bundled-file');
                 continue;
             }
 
@@ -1321,6 +1531,7 @@ function deadcode(index, options = {}) {
             if (/^operator(?:\b|[^a-zA-Z0-9_$])/.test(symbol.name) ||
                 symbol.name === 'this[]' ||
                 ((lang === 'c' || lang === 'cpp') && symbol.name.startsWith('~'))) {
+                withhold(symbol, 'operator-surface');
                 continue;
             }
 
@@ -1330,22 +1541,26 @@ function deadcode(index, options = {}) {
             if (lang === 'rust' && (symbol.modifiers || []).some(modifier =>
                 modifier === 'pymethods' || modifier === 'pymodule_init')) {
                 excludedRuntimeContract++;
+                withhold(symbol, 'runtime-contract');
                 continue;
             }
 
             // Skip test files unless requested
             if (!options.includeTests && isTestFile(symbol.relativePath, lang)) {
+                withhold(symbol, 'test-file');
                 continue;
             }
 
             // Apply file filter (scopes deadcode to matching files)
             if (options.file && !symbol.relativePath.includes(options.file)) {
+                withhold(symbol, 'out-of-scope');
                 continue;
             }
 
             // Apply exclude and in filters
             if ((options.exclude && options.exclude.length > 0) || options.in) {
                 if (!index.matchesFilters(symbol.relativePath, { exclude: options.exclude, in: options.in })) {
+                    withhold(symbol, 'out-of-scope');
                     continue;
                 }
             }
@@ -1358,6 +1573,7 @@ function deadcode(index, options = {}) {
             // compile time and describes external/global shapes — nothing in
             // it is deletable code, so nothing in it is claimable.
             if (symbol.relativePath.endsWith('.d.ts')) {
+                withhold(symbol, 'ambient-declaration');
                 continue;
             }
             // The same holds for a `declare global` / `declare module 'x'`
@@ -1365,6 +1581,7 @@ function deadcode(index, options = {}) {
             // with declarations outside the project, whose readers UCN
             // cannot see (`interface Window`, a library's `Register`).
             if (symbol.ambientAugmentation) {
+                withhold(symbol, 'ambient-declaration');
                 continue;
             }
 
@@ -1372,6 +1589,7 @@ function deadcode(index, options = {}) {
             // Each language module declares its own isEntryPoint() rules.
             const langModule = getLanguageAdapter(lang);
             if (langModule.isEntryPoint?.(symbol)) {
+                withhold(symbol, 'entry-point');
                 continue;
             }
             // A constructor participates in the type's allocation protocol,
@@ -1385,14 +1603,24 @@ function deadcode(index, options = {}) {
                 (symbol.className && !classAuditSet.has(symbol.type) &&
                     langTraits(lang)?.constructorProtocol?.initializer === name)) {
                 excludedConstructors++;
+                withhold(symbol, 'constructor');
                 continue;
             }
             // Members the runtime/compiler invokes by name (trait
             // languageProtocolMember): Java serialization callbacks on
             // Serializable types, Python Enum hooks on Enum subclasses, C#
             // pattern-bound members, JS toJSON/then/[Symbol.*] (fix #363).
-            if (protocolMemberOf(index, symbol) || protocolTypeOf(index, symbol)) {
+            // An absent member that cannot be placed in one owner type
+            // cannot have its contracts checked: no claim, and no guess.
+            if (absent.has(symbol) && anchored.get(symbol) === null) {
+                withhold(symbol, 'owner-ambiguous');
+                continue;
+            }
+            if (standing(symbol, lang)
+                ? standing(symbol, lang).runtimeContract
+                : protocolMemberOf(index, symbol) || protocolTypeOf(index, symbol)) {
                 excludedRuntimeContract++;
+                withhold(symbol, 'runtime-contract');
                 continue;
             }
 
@@ -1402,6 +1630,7 @@ function deadcode(index, options = {}) {
             // contract (CS0535); classify it with other external contracts.
             if (lang === 'csharp' && symbol.explicitInterface) {
                 excludedExternalContract++;
+                withhold(symbol, 'external-contract');
                 continue;
             }
 
@@ -1420,6 +1649,7 @@ function deadcode(index, options = {}) {
             if ((hasFrameworkEntrypoint || hasDecoratorMetadata) &&
                 !options.includeDecorated) {
                 excludedDecorated++;
+                withhold(symbol, 'registered');
                 continue;
             }
 
@@ -1433,18 +1663,25 @@ function deadcode(index, options = {}) {
             // explicitly enables exported-surface review.
             if (symbol.memberAssigned && !symbol.registryMember && !isExported) {
                 excludedRuntimeContract++;
+                withhold(symbol, 'runtime-contract');
                 continue;
             }
 
             // Skip exported unless requested
-            if (isExported && !options.includeExported) {
+            // POLICY, not fact: an exported symbol may have consumers outside
+            // the repository. A library keeps it out of the audit; a project
+            // declared an application, or --include-exported, audits it.
+            // `isExported` stays the fact other shields read (above).
+            if (downstreamExposureBlocks(index, isExported, options)) {
                 excludedExported++;
+                withhold(symbol, 'downstream-exposure');
                 continue;
             }
 
             // Fast path: name has call sites in callee index → definitely used → not dead
             // (unless every site is the name's own recursion — fix #253c).
             if (index.calleeIndex.has(name) && !selfRecursiveNames.has(name)) {
+                withhold(symbol, 'has-callers');
                 continue;
             }
             // Class-kind claims (fix #253a): a class whose member the runtime
@@ -1460,15 +1697,20 @@ function deadcode(index, options = {}) {
                 // live. This is the normal invocation form for C# extension
                 // containers and other static helper types.
                 if (members.some(m => index.calleeIndex.has(m.name))) {
+                    withhold(symbol, 'member-in-use', explain && {
+                        members: members.filter(m => index.calleeIndex.has(m.name)).map(m => m.name),
+                    });
                     continue;
                 }
                 if (members.some(m => langModule.isEntryPoint?.(m))) {
+                    withhold(symbol, 'entry-point');
                     continue;
                 }
                 if (members.some(m => isFrameworkEntrypoint(m, index) ||
                     hasUnknownRegistrationDecorator(m))) {
                     if (!options.includeDecorated) {
                         excludedDecorated++;
+                        withhold(symbol, 'registered');
                         continue;
                     }
                 }
@@ -1484,7 +1726,9 @@ function deadcode(index, options = {}) {
             // resolves to — `user.load` keeps user.js's load alive, never an
             // unrelated module's same-name symbol.
             let nonDefUsages = allUsages.filter(u =>
-                !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine)) &&
+                // (an absent declaration has no definition site in this text)
+                !(!absent.has(symbol) && u.file === symbol.file &&
+                    (u.line === symbol.startLine || u.line === symbol.nameLine)) &&
                 !(defNameLines().get(u.file)?.has(u.line)) &&
                 // Self-recursion carve-out names (fix #253c): a reference
                 // inside a same-name def's own body is the recursion itself.
@@ -1510,7 +1754,7 @@ function deadcode(index, options = {}) {
             // AST ranges, not line prefixes (fix #247): a multi-line
             // `export { a,\n b }` block's continuation lines counted as
             // consumption, silently hiding every symbol exported that way.
-            if (isExported && options.includeExported) {
+            if (isExported && !downstreamExposureBlocks(index, isExported, options)) {
                 nonDefUsages = nonDefUsages.filter(u => {
                     if (u.file !== symbol.file) return true; // cross-file usage always counts
                     const ranges = exportSiteRanges(u.file);
@@ -1521,7 +1765,15 @@ function deadcode(index, options = {}) {
             // Total includes all usage types (calls, references, callbacks, re-exports)
             const totalUsages = nonDefUsages.length;
 
+            if (totalUsages > 0) withhold(symbol, 'has-usages', explain && { usages: nonDefUsages });
             if (totalUsages === 0) {
+                // A name-level withdrawal applies to every declaration the
+                // chain did not already explain (assessment only: the audit
+                // skipped this name before the chain).
+                if (withdrawn) {
+                    withhold(symbol, withdrawn);
+                    continue;
+                }
                 // External-contract override: the method may be invoked through
                 // an out-of-tree base class UCN can't index (deadcode analog of
                 // fix #210). A zero usage count is not evidence of deadness.
@@ -1532,13 +1784,30 @@ function deadcode(index, options = {}) {
                 // such subclasses non-textually (django `Command(BaseCommand)`
                 // by module path, pytest plugins by registration) — zero
                 // in-project references is not evidence of deadness there.
-                const isExternalContract = classAuditSet.has(symbol.type)
-                    ? _heritageReachesExternalBase(index, symbol, lang, false)
-                    : overridesOutOfTreeBase(index, symbol) ||
-                        typedLiteralExternalMember(index, symbol) ||
-                        (lang === 'go' && goImplicitExternalContract(symbol));
+                const isExternalContract = standing(symbol, lang)
+                    ? standing(symbol, lang).externalContract
+                    : (classAuditSet.has(symbol.type)
+                        ? _heritageReachesExternalBase(index, symbol, lang, false)
+                        : overridesOutOfTreeBase(index, symbol) ||
+                            typedLiteralExternalMember(index, symbol) ||
+                            implicitStandardContract(symbol, lang));
                 if (isExternalContract && !options.includeExported) {
                     excludedExternalContract++;
+                    withhold(symbol, 'external-contract');
+                    continue;
+                }
+                // Held in place by a contract of the project itself: the
+                // implementation a type owes to an interface, abstract class
+                // or trait, a member a descendant declares it overrides, or
+                // a member that lets its type stand in for a project
+                // interface or protocol by shape. A fact about the
+                // declaration, so no flag reveals it.
+                const projectContract = standing(symbol, lang)
+                    ? standing(symbol, lang).projectContract
+                    : requiredByProjectContract(index, symbol);
+                if (projectContract) {
+                    excludedRequiredSlot++;
+                    withhold(symbol, projectContract);
                     continue;
                 }
                 // Collect decorators/annotations for hint display
@@ -1583,6 +1852,7 @@ function deadcode(index, options = {}) {
                     computedDispatchReceivers.has(symbol.registryContainer);
                 if (dynamicallyDispatched) {
                     excludedDynamicDispatch++;
+                    withhold(symbol, 'dynamic-dispatch');
                     continue;
                 }
 
@@ -1599,6 +1869,7 @@ function deadcode(index, options = {}) {
                     reflectionWithheldByPattern.set(pattern,
                         (reflectionWithheldByPattern.get(pattern) || 0) + 1);
                     reflectionInfo.withheld++;
+                    withhold(symbol, 'reflection');
                     continue;
                 }
 
@@ -1617,6 +1888,7 @@ function deadcode(index, options = {}) {
                         reflectionInfo.withheldByTable.push({ name: symbol.name,
                             file: symbol.relativePath, line, startLine: symbol.startLine,
                             reason: 'literal-name-near-dynamic-reflection' });
+                        withhold(symbol, 'reflection');
                         continue;
                     }
                 }
@@ -1640,6 +1912,7 @@ function deadcode(index, options = {}) {
                     ...(declaredOn && { declaredOn }),
                     ...(isExternalContract && { externalContract: true })
                 });
+                if (explain) explain(symbol, 'claimed', results[results.length - 1]);
             }
         }
     }
@@ -1657,6 +1930,7 @@ function deadcode(index, options = {}) {
     results.excludedRuntimeContract = excludedRuntimeContract;
     results.excludedConstructors = excludedConstructors;
     results.excludedDynamicDispatch = excludedDynamicDispatch;
+    results.excludedRequiredSlot = excludedRequiredSlot;
     results.computedDispatch = computedDispatchInfo;
     reflectionInfo.withheldByTable.sort((a, b) => codeUnitCompare(a.file, b.file) ||
         a.startLine - b.startLine || codeUnitCompare(a.name, b.name));
@@ -1685,12 +1959,16 @@ function deadcode(index, options = {}) {
         reasons: coverage.reasons,
         parseRecoveries: coverage.parseRecoveries,
     };
-    results.pythonImplicitExportFiles = [...index.files.values()].filter(entry =>
-        isPythonPackageFile(index, entry) &&
-        !(entry.exportDetails || []).some(exp => exp.type === '__all__')).length;
+    // The Python public-surface rule is an exposure rule: it shields nothing
+    // in a project declared an application.
+    results.projectKind = projectKind(index);
+    results.pythonImplicitExportFiles = results.projectKind === 'application' ? 0
+        : [...index.files.values()].filter(entry =>
+            isPythonPackageFile(index, entry) &&
+            !(entry.exportDetails || []).some(exp => exp.type === '__all__')).length;
 
     return results;
     } finally { index._endOp(); }
 }
 
-module.exports = { buildUsageIndex, deadcode, nameOnlySelfRecursive, DEF_NAME_LINE_KINDS };
+module.exports = { buildUsageIndex, deadcode, nameOnlySelfRecursive, contractFactsOf, DEF_NAME_LINE_KINDS };