carrick 0.3.83 → 0.3.85

package/sidecar/dist/src/capture/anchors.js

@@ -6,9 +6,9 @@
  */
 import ts from 'typescript';
 import * as path from 'node:path';
-import { printTypeForDestination, undeclaredNamesIn } from './node-builder.js';
+import { printTypeForDestination, substituteUndeclaredNames, undeclaredNamesIn, } from './node-builder.js';
 import { typeIsOrContainsMachinery } from './machinery.js';
-import { unresolvedAtAnchor } from './unresolved.js';
+import { unresolvedAtAnchor, unresolvedSpecifiersReachableFrom, } from './unresolved.js';
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export function entryRelativeSpecifier(entryDir, repoRoot, sourceFile) {
     const target = path
@@ -54,12 +54,25 @@ export function resolveAnchor(program, request, args) {
         // (a generated model that was never generated). The stub then self-checks
         // such a name as an error placeholder, which no walk flags. A name a
         // sibling symbol anchor imports is resolved by that import.
+        // carrick#1377: rewrite what nothing declares to `unknown` in place, so
+        // one member typed by a module the checkout does not have stops taking
+        // every member around it down with it.
+        const rewritten = siblingSpec || !args.placeholder
+            ? undefined
+            : substituteUndeclaredNamesInText(text, program, args.placeholder);
+        const aliasBody = rewritten?.text ?? text;
         const undeclaredNames = siblingSpec || !args.placeholder
             ? []
-            : undeclaredNamesInText(text, program, args.placeholder);
+            : undeclaredNamesInText(aliasBody, program, args.placeholder);
+        const unresolved = rewritten?.paths.length
+            ? {
+                paths: rewritten.paths,
+                specifiers: unresolvedSpecifiersForLiteral(program, request.source_file, args.repoRoot),
+            }
+            : undefined;
         return {
             request,
-            aliasText: siblingSpec ? `import('${siblingSpec}').${text}` : text,
+            aliasText: siblingSpec ? `import('${siblingSpec}').${text}` : aliasBody,
             // Literal anchors ARE the legacy-text tier (WP3 wiring of the design's
             // structural_fallback): hand-produced type text riding the surface.
             // The self-check still classifies decay; the fidelity metric counts
@@ -67,6 +80,7 @@ export function resolveAnchor(program, request, args) {
             // ratchetable. Demotions are distinguished by failureReason.
             serialization: 'structural_fallback',
             ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}),
+            ...(unresolved ? { unresolved } : {}),
         };
     }
     const sourceAbs = path.join(args.repoRoot, request.source_file);
@@ -276,7 +290,12 @@ function finishInferAnchor(program, sourceFile, request, located, placeholder, r
     if (!printed.text) {
         return demote(printed.failure ?? 'node builder print failed');
     }
-    const unresolved = unresolvedAtAnchor(program, sourceFile, type, located);
+    const atAnchor = unresolvedAtAnchor(program, sourceFile, type, located);
+    // carrick#1377: a member the print named undeclared and this rewrote to
+    // `unknown` is an unresolved position too, whether or not the source type
+    // carried the compiler's placeholder at it (a bare name the print reused as
+    // written does not). Both lists feed the same labelling.
+    const unresolved = mergeUnresolved(atAnchor, printed.substitutedPaths, () => unresolvedSpecifiersReachableFrom(program, sourceFile));
     return {
         request,
         aliasText: printed.text,
@@ -286,13 +305,55 @@ function finishInferAnchor(program, sourceFile, request, located, placeholder, r
         ...(unresolved ? { unresolved } : {}),
     };
 }
+/**
+ * Fold substituted member positions into what the source program could not
+ * resolve. `specifiers` is a thunk: the reachable-import walk is only worth
+ * running for an anchor that actually substituted something.
+ */
+function mergeUnresolved(atAnchor, substitutedPaths, specifiers) {
+    if (!substitutedPaths || substitutedPaths.length === 0)
+        return atAnchor;
+    const paths = new Set([...(atAnchor?.paths ?? []), ...substitutedPaths]);
+    return {
+        paths: [...paths],
+        specifiers: atAnchor?.specifiers ?? specifiers(),
+    };
+}
+/**
+ * The unresolved specifiers a LITERAL anchor's source file reaches, or none
+ * when the anchor names no file (its text names a type with nothing behind it
+ * and the detail says only that).
+ */
+function unresolvedSpecifiersForLiteral(program, sourceFileRel, repoRoot) {
+    if (!sourceFileRel)
+        return [];
+    const sourceFile = program.getSourceFile(path.join(repoRoot, sourceFileRel));
+    return sourceFile ? unresolvedSpecifiersReachableFrom(program, sourceFile) : [];
+}
 /** `undeclaredNamesIn` over type text rather than a built node. */
 function undeclaredNamesInText(text, program, destination) {
+    const parsed = parseLiteralAnchor(text);
+    return parsed ? undeclaredNamesIn(parsed, program, destination) : [];
+}
+/** `substituteUndeclaredNames` over type text rather than a built node. */
+function substituteUndeclaredNamesInText(text, program, destination) {
+    const parsed = parseLiteralAnchor(text);
+    if (!parsed)
+        return undefined;
+    const rewritten = substituteUndeclaredNames(parsed, program, destination);
+    if (rewritten.substitutions.length === 0)
+        return undefined;
+    const printer = ts.createPrinter({ removeComments: true });
+    return {
+        text: printer.printNode(ts.EmitHint.Unspecified, rewritten.node, parsed.getSourceFile()),
+        paths: rewritten.substitutions.map((entry) => entry.path),
+    };
+}
+/** The type node of `type __LiteralAnchor = <text>;`, or undefined. */
+function parseLiteralAnchor(text) {
     const parsed = ts.createSourceFile('literal-anchor.ts', `type __LiteralAnchor = ${text};`, ts.ScriptTarget.Latest, true);
     const statement = parsed.statements[0];
-    if (!statement || !ts.isTypeAliasDeclaration(statement))
-        return [];
-    return undeclaredNamesIn(statement.type, program, destination);
+    return statement && ts.isTypeAliasDeclaration(statement) ? statement.type : undefined;
 }
 /**
  * True when the anchor carries a LINE and nothing else — no payload span, no

package/sidecar/dist/src/capture/api.d.ts

@@ -13,7 +13,11 @@
  * (Named anchor_origin because `provenance` is taken by the op-level
  * producer-provenance fields in src/eval_output.rs.)
  */
-export type AnchorOrigin = 'llm-symbol' | 'deterministic-infer' | 'anchor-backfill';
+export type AnchorOrigin = 'llm-symbol' | 'deterministic-infer' | 'anchor-backfill'
+/** No type request reached capture for a manifest alias, so the driver sent
+ * an `unknown` placeholder: the surface carries every alias the check will
+ * probe, and the check's IsUnknown gate answers for it (cloud#1184). */
+ | 'manifest-placeholder';
 /**
  * Serialization tier of a captured alias (design doc, Capture step 5):
  *  - emitted: compiler declaration emit of an addressable symbol (best)
@@ -160,10 +164,13 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  *  - `no_request_body`: the located request read is a validated part the
  *    route's validator binds that is not a body (a path parameter, a query), so
  *    the route states no request body contract there (carrick#1166).
+ *  - `projected_value_only`: every read of a call's result takes a member out
+ *    of it and none reads the value itself, so the site states a part of a
+ *    payload rather than the payload a caller receives (carrick#1375).
  *  - `not_recorded`: the position carries a top type and this layer has no
  *    cause for it.
  */
-export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'not_recorded';
+export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'projected_value_only' | 'not_recorded';
 /**
  * One `any`/`unknown` finding inside a captured or inferred type, with its
  * position and its cause. Sorted by `path` wherever a list is emitted, so the
@@ -367,6 +374,24 @@ export interface CheckVerdict {
     resolved: boolean;
     /** Why `resolved` is false. Absent exactly when `resolved` is true. */
     unresolved_reason?: string;
+    /**
+     * Statements about THIS comparison that are neither the verdict nor an
+     * unresolution (carrick#1341).
+     *
+     * Two things the check can find are true of a pair it called COMPATIBLE, so
+     * neither can ride on `diagnostic`: an optionality gap (the sending side
+     * always provides a field the receiving side declares optional — legal,
+     * assigns, and still a drift between two sources), and the note that the
+     * comparison was made against the JSON wire form rather than the declared
+     * one (carrick#1340), which is why a producer `Date` read as a `string` is
+     * not reported.
+     *
+     * Written on EVERY bucket, empty when there is nothing to add. A note never
+     * changes `bucket` or `resolved` and is never a substitute for
+     * `diagnostic`: a reader that renders notes as a mismatch is reading an
+     * observation as a verdict.
+     */
+    notes: string[];
 }
 /**
  * A service degraded SERVICE-WIDE: install failure, or a stub-tree diagnostic

package/sidecar/dist/src/capture/check-classify.js

@@ -23,7 +23,7 @@
  */
 import { decisiveAssignmentLine } from './check-probe.js';
 import { scrubDiagnostic, scrubPaths } from './check-scrub.js';
-import { describeFieldReport } from './check-fields.js';
+import { describeFieldReport, fieldReportNotes, } from './check-fields.js';
 const PRIMARY_RE = /^(?<file>(?:[a-zA-Z]:)?[^(]*?)\((?<line>\d+),(?<col>\d+)\): error TS(?<code>\d+): (?<msg>.*)$/;
 /** Parse `tsc --pretty false` output into structured diagnostics. */
 export function parseTscOutput(stdout) {
@@ -69,7 +69,17 @@ function endpointAliasFor(side, plan) {
 export function classifyPair(input) {
     const { plan, probeDiags, poisonReason, scrubCtx } = input;
     const codes = [...new Set(probeDiags.map((d) => d.code))].sort((a, b) => a - b);
-    const base = { pair_id: plan.pairId, pair_key: plan.spec.pair_key, codes };
+    // `notes` sits on `base` so EVERY bucket carries it, including the
+    // compatible one (carrick#1341). The two statements it holds are true of a
+    // pair that agreed — an optionality gap assigns, and the wire allowance is
+    // exactly what made the pair agree — so a channel only reachable from the
+    // mismatch branch would be the same missing channel the ticket is about.
+    const base = {
+        pair_id: plan.pairId,
+        pair_key: plan.spec.pair_key,
+        codes,
+        notes: pairNotes(input, scrubCtx),
+    };
     // Every branch below this point except the last two returns a verdict about
     // a type nobody could read; each states that in one place rather than
     // repeating the reasoning.
@@ -231,6 +241,25 @@ export function classifyPair(input) {
  * name. Scrubbed on the same terms as the tsc text: a printed member type can
  * carry a stub-absolute `import("...")` path.
  */
+/**
+ * The observations this pair states that are not its verdict (carrick#1341):
+ * the note that the comparison was made against the serialised form, and each
+ * optionality gap the walk found. Empty when the walk did not run or found
+ * nothing to add — never a claim that the two sides agree.
+ *
+ * Scrubbed on the same terms as the diagnostic: a printed member type can
+ * carry a stub-absolute `import("...")` path.
+ *
+ * A note is an OBSERVATION and never moves a bucket. Nothing in this function
+ * reaches `bucket`, `resolved` or `unresolved_reason`, and the pair's verdict
+ * is decided above before this is read.
+ */
+function pairNotes(input, scrubCtx) {
+    const report = input.fieldReport;
+    if (!report)
+        return [];
+    return fieldReportNotes(report, input.plan.direction.sent, input.plan.direction.expected).map((note) => scrubPaths(note, scrubCtx));
+}
 function namedFields(input, scrubCtx) {
     const report = input.fieldReport;
     if (!report)

package/sidecar/dist/src/capture/check-fields.d.ts

@@ -75,6 +75,35 @@ export declare const MAX_NAMED_FIELDS = 8;
  * types agree.
  */
 export declare function pairFieldReports(opened: ProbeProgram | undefined, plans: ProbePlan[]): Map<string, PairFieldReport>;
+/**
+ * The one wording for "this comparison was made against the serialised form",
+ * shared by the mismatch diagnostic and the `notes` channel so the two can
+ * never drift apart (carrick#1341).
+ */
+export declare function wireFormNote(sentSide: Side): string;
+/**
+ * The statements this report makes that are NOT a mismatch: what belongs on
+ * `CheckVerdict.notes` (carrick#1341).
+ *
+ * Two of the things the walk can find are true of a pair the judge called
+ * COMPATIBLE, and so have no mismatch diagnostic to ride on:
+ *
+ *  - the wire note. Since carrick#1340 a producer `Date` read as a `string` is
+ *    not a drift, because that is what arrives. A reader comparing the two
+ *    declared shapes by hand sees `Date` against `string` and concludes the
+ *    check missed it, so the verdict has to say the comparison was made
+ *    against the serialised form.
+ *  - an optionality gap (`optional_in_expected`): the sending side always
+ *    provides a field the receiving side declares optional. That assigns, so
+ *    no diagnostic can exist for it, and the two sources still disagree — the
+ *    receiver carries a branch that never runs.
+ *
+ * Both are OBSERVATIONS. Nothing here is a verdict, nothing here may move one,
+ * and this is never a substitute for a mismatch reason: a caller that finds
+ * notes on an incompatible row has one statement made twice, not two
+ * statements. Returned in the report's own deterministic order.
+ */
+export declare function fieldReportNotes(report: PairFieldReport, sentSide: Side, expectedSide: Side): string[];
 /**
  * The sentence appended to a mismatch diagnostic. Names the two sides as
  * producer and consumer (never the probe's internal sent/expected), so the

package/sidecar/dist/src/capture/check-fields.js

@@ -75,11 +75,22 @@ export function pairFieldReports(opened, plans) {
         if (!declared || !expected)
             continue;
         const wire = declaredConstType(source, checker, 'sentWire');
-        const compared = wire ?? declared;
-        const report = diffReport(compared.type, expected.type, checker, isAssignableTo, expected.node);
-        report.wireApplied =
-            wire !== undefined &&
-                !(isAssignableTo(wire.type, declared.type) && isAssignableTo(declared.type, wire.type));
+        // Whether serialising changes anything observable about the sent type.
+        const wireChanges = wire !== undefined &&
+            !(isAssignableTo(wire.type, declared.type) && isAssignableTo(declared.type, wire.type));
+        // Walk the DECLARED type unless serialising really changed it.
+        //
+        // The probe declares its wire comparand through a conditional alias that
+        // short-circuits back to the declared type whenever that already assigns,
+        // and a conditional the checker has not had to resolve carries no members
+        // to walk. Reading it unconditionally therefore emptied the report on
+        // exactly the pairs that AGREE — the ones whose only statement is an
+        // optionality gap or the wire note (carrick#1341). Where serialisation
+        // did change the type the wire form is a mapped type with real members,
+        // and it stays the thing compared, because that is what the judge judged.
+        const compared = wireChanges ? wire.type : declared.type;
+        const report = diffReport(compared, expected.type, checker, isAssignableTo, expected.node);
+        report.wireApplied = wireChanges;
         results.set(plan.pairId, report);
     }
     return results;
@@ -221,6 +232,47 @@ function printType(type, ctx) {
     const flat = text.replace(/\s+/g, ' ').trim();
     return flat.length > MAX_TYPE_TEXT ? `${flat.slice(0, MAX_TYPE_TEXT - 1)}…` : flat;
 }
+/**
+ * The one wording for "this comparison was made against the serialised form",
+ * shared by the mismatch diagnostic and the `notes` channel so the two can
+ * never drift apart (carrick#1341).
+ */
+export function wireFormNote(sentSide) {
+    return `The ${sentSide}'s type is compared in the form JSON puts on the wire: a value with a toJSON() method (a Date, for example) travels as what it serialises to.`;
+}
+/**
+ * The statements this report makes that are NOT a mismatch: what belongs on
+ * `CheckVerdict.notes` (carrick#1341).
+ *
+ * Two of the things the walk can find are true of a pair the judge called
+ * COMPATIBLE, and so have no mismatch diagnostic to ride on:
+ *
+ *  - the wire note. Since carrick#1340 a producer `Date` read as a `string` is
+ *    not a drift, because that is what arrives. A reader comparing the two
+ *    declared shapes by hand sees `Date` against `string` and concludes the
+ *    check missed it, so the verdict has to say the comparison was made
+ *    against the serialised form.
+ *  - an optionality gap (`optional_in_expected`): the sending side always
+ *    provides a field the receiving side declares optional. That assigns, so
+ *    no diagnostic can exist for it, and the two sources still disagree — the
+ *    receiver carries a branch that never runs.
+ *
+ * Both are OBSERVATIONS. Nothing here is a verdict, nothing here may move one,
+ * and this is never a substitute for a mismatch reason: a caller that finds
+ * notes on an incompatible row has one statement made twice, not two
+ * statements. Returned in the report's own deterministic order.
+ */
+export function fieldReportNotes(report, sentSide, expectedSide) {
+    const notes = [];
+    if (report.wireApplied)
+        notes.push(wireFormNote(sentSide));
+    for (const difference of report.differences) {
+        if (difference.nature !== 'optional_in_expected')
+            continue;
+        notes.push(`${describeDifference(difference, sentSide, expectedSide)}.`);
+    }
+    return notes;
+}
 /**
  * The sentence appended to a mismatch diagnostic. Names the two sides as
  * producer and consumer (never the probe's internal sent/expected), so the
@@ -229,7 +281,7 @@ function printType(type, ctx) {
 export function describeFieldReport(report, sentSide, expectedSide) {
     const parts = [];
     if (report.wireApplied) {
-        parts.push(`The ${sentSide}'s type is compared in the form JSON puts on the wire: a value with a toJSON() method (a Date, for example) travels as what it serialises to.`);
+        parts.push(wireFormNote(sentSide));
     }
     if (report.differences.length > 0) {
         const named = report.differences

package/sidecar/dist/src/capture/check.js

@@ -83,6 +83,9 @@ function unverifiableAll(plans, gate, diagnostic) {
         codes: [],
         resolved: false,
         unresolved_reason: diagnostic,
+        // Nothing was compared here, so there is nothing to observe about the
+        // comparison (carrick#1341). Empty is the honest answer, not a default.
+        notes: [],
     }));
 }
 function sortVerdicts(verdicts) {
@@ -142,6 +145,7 @@ export async function runCheck(opts, onProgress) {
                 codes: [],
                 resolved: false,
                 unresolved_reason: 'one side of this pair has no captured type surface',
+                notes: [],
             });
         }
     }
@@ -186,6 +190,7 @@ export async function runCheck(opts, onProgress) {
             unresolved_reason: hit.kind === 'budget_exhausted'
                 ? `the ${hit.side} type is too deep or wide to verify at '${hit.path}'`
                 : `the ${hit.side} type carries '${hit.kind}' at '${hit.path}'`,
+            notes: [],
         });
     }
     writeProbes(ws, probing);

package/sidecar/dist/src/capture/deep-walk.js

@@ -266,7 +266,10 @@ export function provenanceOf(finding, unresolved) {
             detail: 'the type is too deep or wide to verify within the capture budget here, so it is reported unverified rather than assumed clean',
         };
     }
-    if (finding.kind === 'any' && unresolved?.paths.includes(finding.path)) {
+    // `unknown` reads here as well as `any` (carrick#1377): a reference nothing
+    // declares is rewritten to `unknown` at its own position, and a reader told
+    // the author declared it that way stops looking where the fix is.
+    if (unresolved?.paths.includes(finding.path)) {
         return {
             path: finding.path,
             kind: finding.kind,

package/sidecar/dist/src/capture/index.js

@@ -95,7 +95,12 @@ function emptyFidelity() {
         total_aliases: 0,
         by_serialization: { emitted: 0, node_builder: 0, structural_fallback: 0 },
         by_self_check: { ok: 0, allowlisted_external: 0, decayed_internal: 0 },
-        by_anchor_origin: { 'llm-symbol': 0, 'deterministic-infer': 0, 'anchor-backfill': 0 },
+        by_anchor_origin: {
+            'llm-symbol': 0,
+            'deterministic-infer': 0,
+            'anchor-backfill': 0,
+            'manifest-placeholder': 0,
+        },
         usable_rate: 0,
     };
 }

package/sidecar/dist/src/capture/node-builder.d.ts

@@ -30,9 +30,23 @@ export interface NodeBuilderPrintResult {
     failure?: string;
     /**
      * Names the print refers to that do not resolve at the destination in the
-     * producer's program (carrick#1165). Present only when there are some.
+     * producer's program (carrick#1165). Present only when there are some —
+     * which, since carrick#1377 rewrites what it can reach, means a reference
+     * the substitution could not replace.
      */
     undeclaredNames?: string[];
+    /**
+     * Member positions the print named something undeclared at, and where that
+     * reference now reads `unknown` (carrick#1377). In the walk's own path
+     * notation, so a finding at one of them can be labelled as what it is: a
+     * module that did not resolve, not a declared top type.
+     */
+    substitutedPaths?: string[];
+}
+/** One reference replaced by `unknown`, with the member position it sat at. */
+export interface UndeclaredSubstitution {
+    name: string;
+    path: string;
 }
 /**
  * Print `type` as a type node anchored at `destination` (a declaration inside
@@ -40,6 +54,19 @@ export interface NodeBuilderPrintResult {
  * any referenced symbol is not plainly accessible from the destination.
  */
 export declare function printTypeForDestination(program: ts.Program, type: ts.Type, destination: ts.Node): NodeBuilderPrintResult;
+/**
+ * Rewrite every reference in `node` that nothing in the producer's program
+ * declares to the `unknown` keyword, and report the member position each sat
+ * at (carrick#1377).
+ *
+ * The positions use the same notation as the capture's deep walk — `sub`,
+ * `items<0>.meta`, `[index]`, `()` for a callable return — so a path found
+ * here names the same member a self-check finding at that path names.
+ */
+export declare function substituteUndeclaredNames(node: ts.TypeNode, program: ts.Program, destination: ts.Node): {
+    node: ts.TypeNode;
+    substitutions: UndeclaredSubstitution[];
+};
 /**
  * Bare names in a printed type node that nothing in the producer's program
  * declares (carrick#1165).

package/sidecar/dist/src/capture/node-builder.js

@@ -117,10 +117,96 @@ export function printTypeForDestination(program, type, destination) {
             failure: `symbols not accessible from the surface entry: ${[...new Set(inaccessible)].join(', ')}`,
         };
     }
+    // carrick#1377: a reference nothing declares makes the WHOLE answer
+    // unpublishable, so one member typed by a package the checkout does not
+    // have used to discard every member around it. Replace what it names with
+    // `unknown` in place and print that; the rest of the shape survives, and
+    // the positions are reported so the finding at each can be labelled as a
+    // module that did not resolve rather than a top type the author declared.
+    const substituted = substituteUndeclaredNames(node, program, destination);
     const printer = ts.createPrinter({ removeComments: true });
-    const text = printer.printNode(ts.EmitHint.Unspecified, node, destination.getSourceFile());
-    const undeclaredNames = undeclaredNamesIn(node, program, destination);
-    return { text, inaccessible, ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}) };
+    const text = printer.printNode(ts.EmitHint.Unspecified, substituted.node, destination.getSourceFile());
+    // Asked of the REWRITTEN node: the field says what the printed answer
+    // names, so anything the substitution could not reach still fills it and
+    // still refuses publication.
+    const undeclaredNames = undeclaredNamesIn(substituted.node, program, destination);
+    const substitutedPaths = substituted.substitutions.map((entry) => entry.path);
+    return {
+        text,
+        inaccessible,
+        ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}),
+        ...(substitutedPaths.length > 0 ? { substitutedPaths } : {}),
+    };
+}
+/**
+ * Rewrite every reference in `node` that nothing in the producer's program
+ * declares to the `unknown` keyword, and report the member position each sat
+ * at (carrick#1377).
+ *
+ * The positions use the same notation as the capture's deep walk — `sub`,
+ * `items<0>.meta`, `[index]`, `()` for a callable return — so a path found
+ * here names the same member a self-check finding at that path names.
+ */
+export function substituteUndeclaredNames(node, program, destination) {
+    const undeclared = new Set(undeclaredNamesIn(node, program, destination));
+    if (undeclared.size === 0) {
+        return { node, substitutions: [] };
+    }
+    const substitutions = [];
+    const leftmost = (name) => ts.isIdentifier(name) ? name : leftmost(name.left);
+    // The path is carried down the visit rather than reconstructed, because a
+    // rewritten node has no parent to walk back up from.
+    const rewrite = (current, path) => {
+        if ((ts.isTypeReferenceNode(current) && undeclared.has(leftmost(current.typeName).text)) ||
+            (ts.isTypeQueryNode(current) && undeclared.has(leftmost(current.exprName).text))) {
+            substitutions.push({
+                name: ts.isTypeReferenceNode(current)
+                    ? leftmost(current.typeName).text
+                    : leftmost(current.exprName).text,
+                path: path === '' ? '<root>' : path,
+            });
+            return ts.factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+        }
+        return ts.visitEachChild(current, (child) => rewrite(child, childPath(current, child, path)), 
+        /* context */ undefined);
+    };
+    const rewritten = rewrite(node, '');
+    return { node: rewritten, substitutions };
+}
+/** The deep walk's path for `child` inside `parent`, extending `path`. */
+function childPath(parent, child, path) {
+    if (ts.isPropertySignature(parent) && parent.type === child) {
+        const name = ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name)
+            ? parent.name.text
+            : parent.name.getText?.() ?? '';
+        return path === '' ? name : `${path}.${name}`;
+    }
+    if (ts.isArrayTypeNode(parent) && parent.elementType === child) {
+        return `${path}<0>`;
+    }
+    if (ts.isIndexSignatureDeclaration(parent) && parent.type === child) {
+        return `${path}[index]`;
+    }
+    if ((ts.isFunctionTypeNode(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isCallSignatureDeclaration(parent)) &&
+        parent.type === child) {
+        return `${path}()`;
+    }
+    if (ts.isTypeReferenceNode(parent) && parent.typeArguments) {
+        const index = parent.typeArguments.indexOf(child);
+        if (index >= 0)
+            return `${path}<${index}>`;
+    }
+    if (ts.isTupleTypeNode(parent)) {
+        const index = parent.elements.indexOf(child);
+        if (index >= 0)
+            return `${path}<${index}>`;
+    }
+    // A union or intersection member sits at its parent's position, as the deep
+    // walk records it; everything else (a type literal's members, a parenthesis)
+    // keeps the path it was reached with.
+    return path;
 }
 /**
  * Bare names in a printed type node that nothing in the producer's program

package/sidecar/dist/src/capture/self-check.d.ts

@@ -22,7 +22,12 @@
  * Attribution is per-alias closure: failed specifiers are blamed on an alias
  * only if they occur in a file reachable from that alias's surface statement
  * (import-type seeds, then BFS over relative imports). The spike's
- * file-granularity shortcut is gone.
+ * file-granularity shortcut is gone -- including on the SURFACE file itself,
+ * which holds every alias, so a file-granular bucket there blamed the whole
+ * service for one alias's dangling specifier (cloud#1184). A surface
+ * diagnostic is attributed by `export type` statement span, exactly as
+ * check-poison.ts contains poison; one that no statement covers keeps the
+ * service-wide bucket.
  */
 import ts from 'typescript';
 import type { CaptureAliasRecord } from './api.js';