carrick 0.3.72 → 0.3.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.72",
+  "version": "0.3.73",
   "description": "The API contract index for a TypeScript workspace: what the other services do with the routes and calls in the file you are editing, in your editor and in your agent's context",
   "keywords": [
     "typescript",
@@ -57,11 +57,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.72",
-    "@carrick-tools/cli-darwin-x64": "0.3.72",
-    "@carrick-tools/cli-linux-arm64": "0.3.72",
-    "@carrick-tools/cli-linux-x64": "0.3.72",
-    "@carrick-tools/cli-win32-x64": "0.3.72"
+    "@carrick-tools/cli-darwin-arm64": "0.3.73",
+    "@carrick-tools/cli-darwin-x64": "0.3.73",
+    "@carrick-tools/cli-linux-arm64": "0.3.73",
+    "@carrick-tools/cli-linux-x64": "0.3.73",
+    "@carrick-tools/cli-win32-x64": "0.3.73"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",

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

@@ -6,6 +6,7 @@
  */
 import ts from 'typescript';
 import type { CaptureAnchorRequest, InferAnchorRequest } from './api.js';
+import type { UnresolvedAtAnchor } from './deep-walk.js';
 export interface ResolvedAnchor {
     request: CaptureAnchorRequest;
     /** RHS of `export type <alias> = ...;` in the surface entry. */
@@ -34,6 +35,20 @@ export interface ResolvedAnchor {
      * backfillable; the reason rides `self_check_detail` instead.
      */
     abstainReason?: string;
+    /**
+     * carrick#1165: identifiers the alias text names (a literal anchor's text
+     * or a node-builder print) that nothing in the producer's program declares.
+     * Recorded on the capture record as `undeclared_names`.
+     */
+    undeclaredNames?: string[];
+    /**
+     * carrick#1164: member paths the SOURCE program could not resolve, and the
+     * unresolved imports the anchor's file reaches. Printed into the surface
+     * those members read `any`, like an author's `any`; the self-check uses this
+     * to label them `unresolved_import` instead of `declared`. Absent when the
+     * anchor's type holds no unresolved placeholder.
+     */
+    unresolved?: UnresolvedAtAnchor;
 }
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export declare function entryRelativeSpecifier(entryDir: string, repoRoot: string, sourceFile: string): string;

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

@@ -6,8 +6,9 @@
  */
 import ts from 'typescript';
 import * as path from 'node:path';
-import { printTypeForDestination } from './node-builder.js';
+import { printTypeForDestination, undeclaredNamesIn } from './node-builder.js';
 import { typeIsOrContainsMachinery } from './machinery.js';
+import { unresolvedAtAnchor } from './unresolved.js';
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export function entryRelativeSpecifier(entryDir, repoRoot, sourceFile) {
     const target = path
@@ -48,6 +49,14 @@ export function resolveAnchor(program, request, args) {
         const siblingSpec = bareIdentifier
             ? args.siblingSymbolSpecs?.get(text)
             : undefined;
+        // carrick#1165: literal text is printed elsewhere (the v1 walk) and can
+        // name a type by a bare identifier that nothing in the program declares
+        // (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.
+        const undeclaredNames = siblingSpec || !args.placeholder
+            ? []
+            : undeclaredNamesInText(text, program, args.placeholder);
         return {
             request,
             aliasText: siblingSpec ? `import('${siblingSpec}').${text}` : text,
@@ -57,6 +66,7 @@ export function resolveAnchor(program, request, args) {
             // them at this tier so the legacy dependence stays measurable and
             // ratchetable. Demotions are distinguished by failureReason.
             serialization: 'structural_fallback',
+            ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}),
         };
     }
     const sourceAbs = path.join(args.repoRoot, request.source_file);
@@ -100,10 +110,14 @@ export function resolveAnchor(program, request, args) {
                 `and no sibling type alias derives from it (e.g. \`typeof ${request.symbol_name}\`); ` +
                 'demoted so the surface line stays valid');
         }
+        const arrayDepth = Math.max(0, request.array_depth ?? 0);
+        const declared = checker.getDeclaredTypeOfSymbol(resolvedExport);
+        const unresolved = unresolvedAtAnchor(program, sourceFile, declared, resolvedExport.declarations?.[0] ?? sourceFile, '<0>'.repeat(arrayDepth));
         return {
             request,
             aliasText: `import('${spec}').${request.symbol_name}${arraySuffix}`,
             serialization: 'emitted',
+            ...(unresolved ? { unresolved } : {}),
         };
     }
     if (request.kind === 'handler_return') {
@@ -126,10 +140,13 @@ export function resolveAnchor(program, request, args) {
             // Type parameters erase to their constraint/unknown under ReturnType<>.
             return demote(`handler '${request.symbol_name}' is generic`);
         }
+        const returned = callSignatures[0].getReturnType();
+        const unresolved = unresolvedAtAnchor(program, sourceFile, checker.getAwaitedType(returned) ?? returned, declaration ?? sourceFile);
         return {
             request,
             aliasText: `Awaited<ReturnType<typeof import('${spec}').${request.symbol_name}>>`,
             serialization: 'emitted',
+            ...(unresolved ? { unresolved } : {}),
         };
     }
     // kind === 'infer'
@@ -151,6 +168,10 @@ export function resolveAnchor(program, request, args) {
     if (!located) {
         return demote(locatorFailureReason(request));
     }
+    // carrick#1162: a serialised body is the JSON of its argument. The call's own
+    // `string` result is never the payload's contract, and publishing it reads
+    // incompatible against every object-typed counterparty.
+    located = serialisedArgument(located);
     // #439 part 1: a producer anchor whose locator landed inside a fluent
     // builder chain's config-descriptor argument (an all-literal metadata
     // object) must never capture that descriptor as the request type. Re-aim at
@@ -255,13 +276,24 @@ 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);
     return {
         request,
         aliasText: printed.text,
         serialization: 'node_builder',
         ...(reaimNote ? { reaimNote } : {}),
+        ...(printed.undeclaredNames ? { undeclaredNames: printed.undeclaredNames } : {}),
+        ...(unresolved ? { unresolved } : {}),
     };
 }
+/** `undeclaredNamesIn` over type text rather than a built node. */
+function undeclaredNamesInText(text, program, destination) {
+    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);
+}
 /**
  * True when the anchor carries a LINE and nothing else — no payload span, no
  * expression text, no parameter name. Such an anchor states where to look, not
@@ -689,6 +721,26 @@ function paramLocatorHints(request) {
         ? `line ${request.line_number}`
         : 'no line hint';
 }
+/**
+ * The argument of a `JSON.stringify(value)` call (through parentheses), or the
+ * node unchanged. The mirror of the v1 inferrer's `unwrapJsonStringifyArg`:
+ * the global serialiser is identified by the standard `JSON` object, the one
+ * name every runtime shares.
+ */
+function serialisedArgument(node) {
+    let current = node;
+    while (ts.isParenthesizedExpression(current))
+        current = current.expression;
+    if (ts.isCallExpression(current) &&
+        current.arguments.length > 0 &&
+        ts.isPropertyAccessExpression(current.expression) &&
+        ts.isIdentifier(current.expression.expression) &&
+        current.expression.expression.text === 'JSON' &&
+        current.expression.name.text === 'stringify') {
+        return current.arguments[0];
+    }
+    return node;
+}
 function locatorFailureReason(request) {
     const hints = [];
     if (request.span_start !== undefined)
@@ -741,17 +793,30 @@ function tightestCoveringNode(sourceFile, start, end) {
     visit(sourceFile);
     return best;
 }
+/**
+ * Locator text with insignificant whitespace removed: runs collapse to one
+ * space, and a member chain broken before its dot (`client\n  .list(…)`) reads
+ * as `client.list(…)` (carrick#1162), the same rule the v1 inferrer applies.
+ */
+function normalizeLocatorText(text) {
+    return text
+        .replace(/\s+/g, ' ')
+        .replace(/\s*(\?\.|\.)\s*/g, '$1')
+        .trim();
+}
 function nodeByExpressionText(sourceFile, text, fromLine) {
-    const wanted = text.replace(/\s+/g, ' ').trim();
+    const wanted = normalizeLocatorText(text);
     let best;
     const visit = (node) => {
         if (best)
             return;
         if (isPreferredTarget(node)) {
-            const nodeText = node.getText(sourceFile).replace(/\s+/g, ' ').trim();
+            const nodeText = normalizeLocatorText(node.getText(sourceFile));
             if (nodeText === wanted) {
-                const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
-                if (fromLine === undefined || line >= fromLine) {
+                // On or after the line, or COVERING it: a chain broken before its dot
+                // starts a line above the line the analyzer reports for the call.
+                const endLine = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+                if (fromLine === undefined || endLine >= fromLine) {
                     best = node;
                     return;
                 }

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

@@ -60,6 +60,13 @@ export interface LiteralAnchorRequest {
     /** Verbatim TS type text (a bare symbol name or an inline object type). */
     type_text: string;
     anchor_origin: AnchorOrigin;
+    /**
+     * Repo-root-relative file the text was printed from, when there is one.
+     * It joins the analysis program, so a name the text prints bare (an enum
+     * member, a recursive reference) is found declared (carrick#1165). The
+     * record's `source_file` stays `<inline>`: the answer is still the text.
+     */
+    source_file?: string;
 }
 /**
  * Addressable handler: `export type A = Awaited<ReturnType<typeof
@@ -123,9 +130,14 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  * honest value is `not_recorded` — never a guess.
  *
  *  - `declared`: the captured declaration states `any`/`unknown` at this
- *    position. Whatever put it there (an author annotation, or an emitter that
- *    printed an unresolved value as `any`), it is baked into the emitted text
- *    and no install re-resolves it.
+ *    position, and the producer's own program had a type there too: an author
+ *    annotation, not a failed resolution.
+ *  - `unresolved_import`: the position is `any` in the emitted text because the
+ *    producer's program could not resolve the type there — an import of a
+ *    dependency that is not installed, or of a generated module that was never
+ *    generated, on the scanned checkout (carrick#1164). The printer writes that
+ *    placeholder as `any`, so the text alone reads like `declared`; the capture
+ *    tells them apart on the source program at anchor time.
  *  - `budget_exhausted`: the subtree was too deep or wide to finish inside the
  *    capture walk's budget, so it is reported unverified rather than clean.
  *  - `no_payload_evidence`: a handler returned a call whose callee has no
@@ -141,10 +153,17 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  *    position while its parsed output is concrete, which is what a coercion
  *    declares (carrick#1101). The published type carries the output there, so
  *    this finding describes what a caller may send, not the printed member.
+ *  - `no_success_payload`: a route's handler sends only error or redirect
+ *    responses (by the status each send states), or no success send carries a
+ *    body a JSON contract can describe, so the route publishes no success body
+ *    rather than an error body or a redirect location (carrick#1161).
+ *  - `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).
  *  - `not_recorded`: the position carries a top type and this layer has no
  *    cause for it.
  */
-export type TypeProvenanceReason = 'declared' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'not_recorded';
+export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | '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
@@ -206,6 +225,22 @@ export interface CaptureAliasRecord {
      * Sorted by `path`; absent (not empty) when the walk found nothing.
      */
     any_provenance?: TypeProvenance[];
+    /**
+     * Internal module specifiers that fail to resolve anywhere in this alias's
+     * closure, as the emitted files write them (carrick#1165). The emitted
+     * tree is missing part of what the alias refers to, so a shape printed from
+     * it can name types nothing declares. Sorted; absent when there are none.
+     */
+    dangling_specifiers?: string[];
+    /**
+     * Identifiers this alias's printed text names that do not resolve where the
+     * surface declares it (carrick#1165): a literal anchor's text naming a type
+     * nothing declares, or a node-builder print reusing a source annotation
+     * whose own import did not resolve. Checked on the producer's program, so a global the
+     * program declares (a runtime or `@types` global) is never listed. Sorted;
+     * absent when there are none.
+     */
+    undeclared_names?: string[];
 }
 /** Aggregate fidelity metric, emitted per capture (one service). */
 export interface CaptureFidelity {

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

@@ -10,6 +10,8 @@
  *   surface import error (probe lines 1-2)-> unverifiable
  *   IsAny gate fired (TS2344)             -> gate_caught_baked_any
  *   IsUnknown/IsNever gate fired (TS2344) -> unverifiable
+ *   IsVoid gate fired (TS2344)            -> unverifiable (no body read)
+ *   IsFormBody gate fired (TS2344)        -> unverifiable (form-encoded body)
  *   assignment-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *

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

@@ -10,6 +10,8 @@
  *   surface import error (probe lines 1-2)-> unverifiable
  *   IsAny gate fired (TS2344)             -> gate_caught_baked_any
  *   IsUnknown/IsNever gate fired (TS2344) -> unverifiable
+ *   IsVoid gate fired (TS2344)            -> unverifiable (no body read)
+ *   IsFormBody gate fired (TS2344)        -> unverifiable (form-encoded body)
  *   assignment-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *
@@ -127,6 +129,32 @@ export function classifyPair(input) {
             ...notAFact(`the ${side} type is '${kind}'`),
         };
     }
+    // 4b. A side that states no contract (carrick#1162), below the decay gates so
+    //     an `unknown` side is reported as `unknown`: a `void`/`undefined`
+    //     response a call site reads no body from, and a form-encoded body whose
+    //     fields are runtime appends.
+    const shapeGate = gateDiags
+        .map((d) => plan.gateLines.get(d.line))
+        .find((name) => name.endsWith(':void') || name.endsWith(':form'));
+    if (shapeGate) {
+        const { side, kind } = sideForGate(shapeGate, plan);
+        if (kind === 'void') {
+            return {
+                ...base,
+                bucket: 'unverifiable',
+                gate: `${side}:void`,
+                diagnostic: `the ${side} type is 'void' (it reads no body), so there is no contract to verify.`,
+                ...notAFact(`the ${side} type is 'void'`),
+            };
+        }
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: `${side}:form`,
+            diagnostic: `the ${side} sends a form-encoded body, whose fields are appended at runtime and cannot be compared with a declared shape.`,
+            ...notAFact(`the ${side} sends a form-encoded body`),
+        };
+    }
     // 5. Assignment-class error on the value assignment line -> incompatible.
     const assignDiag = probeDiags.find((d) => d.line === plan.assignmentLine && ASSIGNMENT_CODES.has(d.code));
     if (assignDiag) {

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

@@ -84,7 +84,7 @@ function walkImportedAlias(file, localName, program, checker) {
             const type = checker.getDeclaredTypeOfSymbol(target);
             if (!type)
                 return undefined;
-            return findDisqualifyingTopTypes(type, program, checker, element.name).map(provenanceOf);
+            return findDisqualifyingTopTypes(type, program, checker, element.name).map((finding) => provenanceOf(finding));
         }
     }
     return undefined;

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

@@ -43,7 +43,7 @@ export declare function fnv1a(input: string): string;
  * path, so it is byte-stable across runs. */
 export declare function pairId(spec: CheckPairSpec): string;
 /** Names each gate line so a TS2344 can be attributed to a specific side+kind. */
-export type GateName = 'sent:any' | 'sent:unknown' | 'sent:never' | 'expected:any' | 'expected:unknown' | 'expected:never';
+export type GateName = 'sent:any' | 'sent:unknown' | 'sent:never' | 'sent:void' | 'sent:form' | 'expected:any' | 'expected:unknown' | 'expected:never' | 'expected:void';
 export interface ProbePlan {
     pairId: string;
     spec: CheckPairSpec;

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

@@ -95,6 +95,22 @@ export function buildProbe(spec, packageOf) {
     gateLines.set(push(`type _G_expected_any = Assert<Not<IsAny<Expected>>>;`), 'expected:any');
     gateLines.set(push(`type _G_expected_unknown = Assert<Not<IsUnknown<Expected>>>;`), 'expected:unknown');
     gateLines.set(push(`type _G_expected_never = Assert<Not<IsNever<Expected>>>;`), 'expected:never');
+    // carrick#1162: `void`/`undefined` is what a call site that reads no body
+    // types its response as (a wrapper returning `Promise<void>`). It states no
+    // contract, so no counterparty shape can be judged against it.
+    // `any` is excluded first: `[any] extends [void]` holds, and an `any` side
+    // must keep its own top-type reason, never read as "reads no body".
+    push(`type IsVoid<T> = 0 extends 1 & T ? false : [T] extends [never] ? false : [T] extends [void] ? true : false;`);
+    gateLines.set(push(`type _G_sent_void = Assert<Not<IsVoid<Sent>>>;`), 'sent:void');
+    gateLines.set(push(`type _G_expected_void = Assert<Not<IsVoid<Expected>>>;`), 'expected:void');
+    // carrick#1162: a form-encoded request body (the platform `FormData` or
+    // `URLSearchParams`) carries its fields as runtime appends, which no type
+    // records, so a field-by-field comparison against a declared shape reads
+    // every such body as missing all of its fields.
+    if (spec.protocol === 'http' && spec.type_kind === 'request') {
+        push(`type IsFormBody<T> = 0 extends 1 & T ? false : [T] extends [never] ? false : [T] extends [FormData | URLSearchParams] ? true : false;`);
+        gateLines.set(push(`type _G_sent_form = Assert<Not<IsFormBody<Sent>>>;`), 'sent:form');
+    }
     push(`declare const sent: Sent;`);
     let assignmentLine;
     if (spec.protocol === 'graphql') {

package/sidecar/dist/src/capture/deep-walk.d.ts

@@ -44,19 +44,46 @@ export type DeepTopType = Pick<TypeProvenance, 'kind' | 'path'>;
  *    void` safely accepts a stricter counterparty), so it is not a masked
  *    mismatch and demoting it would over-demote a sound shape;
  *  - TypeScript's unresolved-reference `error` placeholder (`intrinsicName ===
- *    'error'`) is excluded (see `flagOf`): it heals when the check installs the
+ *    'error'`) is excluded (see `disqualifyingFlag`): it heals when the check installs the
  *    pinned external, so it is a healable decay, not an author-baked `any`.
  * A type the walk cannot cheaply finish is NOT flagged — over-demoting a
  * legitimately fully-resolved type is the failure mode this guard must not have.
  */
 export declare function findDisqualifyingTopTypes(root: ts.Type, program: ts.Program, checker: ts.TypeChecker, location: ts.Node): DeepTopType[];
+/**
+ * Member paths at which `root` holds TypeScript's unresolved-reference
+ * placeholder (the `error` intrinsic) rather than a type (carrick#1164).
+ *
+ * Run on the SOURCE program, where a member typed through an import that did
+ * not resolve still carries the placeholder. Once printed into the stub the
+ * placeholder is the keyword `any`, indistinguishable from an author's `any`,
+ * so this is the only point at which the two causes can be told apart. Same
+ * walk, same budget and the same path notation as the self-check's walk over
+ * the emitted text, so a path found here names the member a self-check finding
+ * names. A walk that runs out of budget reports what it found before it did.
+ */
+export declare function findUnresolvedPlaceholders(root: ts.Type, program: ts.Program, checker: ts.TypeChecker, location: ts.Node): string[];
+/** What an anchor's SOURCE program could not resolve (carrick#1164). */
+export interface UnresolvedAtAnchor {
+    /** Member paths holding the unresolved-reference placeholder. */
+    paths: readonly string[];
+    /**
+     * Module specifiers, as the source wrote them, that did not resolve from the
+     * anchor's file or a module it reaches. Internal specifiers first. May be
+     * empty: a name the program never declared leaves the same placeholder.
+     */
+    specifiers: readonly string[];
+}
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
  * The self-check reads EMITTED declaration text, so a top type it finds is
- * text: whatever produced it — an author annotation, or an emitter that
- * printed a value it could not resolve — no install re-resolves it. That is
- * `declared`, and saying so is more useful than the bare `any` a reader gets
- * today. The one other cause it can distinguish is its own budget.
+ * text: an author annotation and an emitter that printed an unresolved value
+ * both read `any` there. The anchor's source program can still tell them apart
+ * (`findUnresolvedPlaceholders`), and when it recorded the finding's path as a
+ * placeholder the cause is `unresolved_import`: a dependency or a generated
+ * module was missing on the scanned checkout, which installing or generating
+ * it fixes (carrick#1164). Anything else at that position is `declared`. The
+ * one other cause the walk itself can distinguish is its own budget.
  */
-export declare function provenanceOf(finding: DeepTopType): TypeProvenance;
+export declare function provenanceOf(finding: DeepTopType, unresolved?: UnresolvedAtAnchor): TypeProvenance;

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

@@ -43,12 +43,38 @@ const MAX_DEEP_FINDINGS = 32;
  *    void` safely accepts a stricter counterparty), so it is not a masked
  *    mismatch and demoting it would over-demote a sound shape;
  *  - TypeScript's unresolved-reference `error` placeholder (`intrinsicName ===
- *    'error'`) is excluded (see `flagOf`): it heals when the check installs the
+ *    'error'`) is excluded (see `disqualifyingFlag`): it heals when the check installs the
  *    pinned external, so it is a healable decay, not an author-baked `any`.
  * A type the walk cannot cheaply finish is NOT flagged — over-demoting a
  * legitimately fully-resolved type is the failure mode this guard must not have.
  */
 export function findDisqualifyingTopTypes(root, program, checker, location) {
+    return walkTopTypes(root, program, checker, location, disqualifyingFlag);
+}
+/**
+ * Member paths at which `root` holds TypeScript's unresolved-reference
+ * placeholder (the `error` intrinsic) rather than a type (carrick#1164).
+ *
+ * Run on the SOURCE program, where a member typed through an import that did
+ * not resolve still carries the placeholder. Once printed into the stub the
+ * placeholder is the keyword `any`, indistinguishable from an author's `any`,
+ * so this is the only point at which the two causes can be told apart. Same
+ * walk, same budget and the same path notation as the self-check's walk over
+ * the emitted text, so a path found here names the member a self-check finding
+ * names. A walk that runs out of budget reports what it found before it did.
+ */
+export function findUnresolvedPlaceholders(root, program, checker, location) {
+    return walkTopTypes(root, program, checker, location, (t) => isErrorPlaceholder(t) ? 'any' : undefined)
+        .filter((finding) => finding.kind !== 'budget_exhausted')
+        .map((finding) => finding.path);
+}
+/** TypeScript's unresolved-reference placeholder: `TypeFlags.Any` with the
+ * internal `intrinsicName === 'error'` (stable since TS 1.x; see `anchors.ts`). */
+function isErrorPlaceholder(t) {
+    return ((t.flags & ts.TypeFlags.Any) !== 0 &&
+        t.intrinsicName === 'error');
+}
+function walkTopTypes(root, program, checker, location, flagOf) {
     // Cover v1's inline-expander reach with margin so this structural walk is a
     // genuine superset of v1's text-scan disqualifier AT DEPTH: anything v1 could
     // expand-and-flag as `any`/`unknown`, this walk reaches too. v1's expander
@@ -63,28 +89,6 @@ export function findDisqualifyingTopTypes(root, program, checker, location) {
     const MAX_VISITED = 4096;
     const seen = new Set();
     let visited = 0;
-    const flagOf = (t) => {
-        if (t.flags & ts.TypeFlags.Any) {
-            // TypeScript's unresolved-reference placeholder (e.g. `import('ext').Foo`
-            // on a bare checkout) carries `TypeFlags.Any` but `intrinsicName ===
-            // 'error'` — NOT an author-baked `any`. It resolves to the real type once
-            // the check phase installs the pinned external, so it must not count as a
-            // disqualifier: treating it as `any` would demote a healable external
-            // reference. Genuine author `any` carries `intrinsicName === 'any'`.
-            // (`intrinsicName` is internal but stable since TS 1.x — same standing as
-            // its use in anchors.ts.)
-            //
-            // The `error` placeholder also stands in for NON-healable causes (TS2304
-            // undefined name, TS2315 wrong-arity generic, a dangling internal
-            // specifier). Excluding those here is not a hole: each emits a diagnostic
-            // in the alias's own closure, so the closure-failure classification
-            // (`internalFailure` -> decayed_internal) or the check-phase POISON rule
-            // — NOT this deep walk — is their backstop, and both fail closed.
-            const name = t.intrinsicName;
-            return name === 'error' ? undefined : 'any';
-        }
-        return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
-    };
     // Findings accumulate rather than short-circuiting: the FIRST is what the
     // check phase pre-gates on (so the verdict is identical to the
     // stop-at-first walk this replaces), and the rest answer "which fields are
@@ -216,16 +220,44 @@ export function findDisqualifyingTopTypes(root, program, checker, location) {
     rest.sort((a, b) => a.path.localeCompare(b.path));
     return [head, ...rest];
 }
+/** The disqualifier the self-check and the check phase gate on (see
+ * `findDisqualifyingTopTypes`). */
+function disqualifyingFlag(t) {
+    if (t.flags & ts.TypeFlags.Any) {
+        // TypeScript's unresolved-reference placeholder (e.g. `import('ext').Foo`
+        // on a bare checkout) carries `TypeFlags.Any` but `intrinsicName ===
+        // 'error'` — NOT an author-baked `any`. It resolves to the real type once
+        // the check phase installs the pinned external, so it must not count as a
+        // disqualifier: treating it as `any` would demote a healable external
+        // reference. Genuine author `any` carries `intrinsicName === 'any'`.
+        // (`intrinsicName` is internal but stable since TS 1.x — same standing as
+        // its use in anchors.ts.)
+        //
+        // The `error` placeholder also stands in for NON-healable causes (TS2304
+        // undefined name, TS2315 wrong-arity generic, a dangling internal
+        // specifier). Excluding those here is not a hole: each emits a diagnostic
+        // in the alias's own closure, so the closure-failure classification
+        // (`internalFailure` -> decayed_internal) or the check-phase POISON rule
+        // — NOT this deep walk — is their backstop, and both fail closed.
+        return isErrorPlaceholder(t) ? undefined : 'any';
+    }
+    return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
+}
+/** How many unresolved specifiers a detail names before it counts the rest. */
+const MAX_NAMED_SPECIFIERS = 3;
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
  * The self-check reads EMITTED declaration text, so a top type it finds is
- * text: whatever produced it — an author annotation, or an emitter that
- * printed a value it could not resolve — no install re-resolves it. That is
- * `declared`, and saying so is more useful than the bare `any` a reader gets
- * today. The one other cause it can distinguish is its own budget.
+ * text: an author annotation and an emitter that printed an unresolved value
+ * both read `any` there. The anchor's source program can still tell them apart
+ * (`findUnresolvedPlaceholders`), and when it recorded the finding's path as a
+ * placeholder the cause is `unresolved_import`: a dependency or a generated
+ * module was missing on the scanned checkout, which installing or generating
+ * it fixes (carrick#1164). Anything else at that position is `declared`. The
+ * one other cause the walk itself can distinguish is its own budget.
  */
-export function provenanceOf(finding) {
+export function provenanceOf(finding, unresolved) {
     if (finding.kind === 'budget_exhausted') {
         return {
             path: finding.path,
@@ -234,6 +266,14 @@ export function provenanceOf(finding) {
             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)) {
+        return {
+            path: finding.path,
+            kind: finding.kind,
+            reason: 'unresolved_import',
+            detail: unresolvedDetail(unresolved.specifiers),
+        };
+    }
     return {
         path: finding.path,
         kind: finding.kind,
@@ -241,3 +281,16 @@ export function provenanceOf(finding) {
         detail: `the captured declaration states '${finding.kind}' at this position, so no counterparty shape can disagree with it`,
     };
 }
+function unresolvedDetail(specifiers) {
+    const lead = "the type at this position did not resolve on the scanned checkout, so the compiler printed a placeholder 'any' rather than a declared type";
+    if (specifiers.length === 0)
+        return lead;
+    const named = specifiers
+        .slice(0, MAX_NAMED_SPECIFIERS)
+        .map((specifier) => `'${specifier}'`)
+        .join(', ');
+    const more = specifiers.length > MAX_NAMED_SPECIFIERS
+        ? ` and ${specifiers.length - MAX_NAMED_SPECIFIERS} more`
+        : '';
+    return `${lead}; unresolved imports reachable from the anchor: ${named}${more}`;
+}