carrick 0.3.107 → 0.3.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.107",
+  "version": "0.3.108",
   "description": "Maps your entire TypeScript codebase across services and repositories, giving AI agents full context on existing types, routes, and function behaviours over MCP before they write duplicate or breaking code.",
   "keywords": [
     "typescript",
@@ -58,11 +58,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.107",
-    "@carrick-tools/cli-darwin-x64": "0.3.107",
-    "@carrick-tools/cli-linux-arm64": "0.3.107",
-    "@carrick-tools/cli-linux-x64": "0.3.107",
-    "@carrick-tools/cli-win32-x64": "0.3.107"
+    "@carrick-tools/cli-darwin-arm64": "0.3.108",
+    "@carrick-tools/cli-darwin-x64": "0.3.108",
+    "@carrick-tools/cli-linux-arm64": "0.3.108",
+    "@carrick-tools/cli-linux-x64": "0.3.108",
+    "@carrick-tools/cli-win32-x64": "0.3.108"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "carrick",
   "description": "Claude Code plugin for Carrick, which indexes TypeScript codebases across service and repository boundaries. After each edit it adds the file's routes, calls, and cross-service type mismatches to the session, and it registers Carrick's language server. It pairs with the Carrick MCP server, which lets agents search functions by intent rather than name.",
-  "version": "0.3.107",
+  "version": "0.3.108",
   "author": {
     "name": "Carrick",
     "email": "hello@carrick.tools"

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

@@ -346,6 +346,14 @@ export interface CaptureStubResult {
     ts_version: string;
     errors: string[];
 }
+/**
+ * The stages of a capture that it reports as it reaches them (carrick#1916),
+ * in order: the program the anchors are read in is being built; the anchors
+ * are being resolved in it; the declarations are being emitted; the stub is
+ * being checked. A capture whose anchors belong to several projects goes
+ * through the first two once per project.
+ */
+export type CapturePhase = 'program' | 'anchors' | 'emit' | 'self-check';
 export interface CaptureStubOptions {
     repoRoot: string;
     serviceName: string;
@@ -360,6 +368,13 @@ export interface CaptureStubOptions {
      * lie inside it only beneath a `.carrick` directory (carrick#1768).
      */
     scanRoot?: string;
+    /**
+     * Told each stage as the capture reaches it, and each anchor as it is
+     * resolved (`message` is then `<done> of <total>`). Called by the work
+     * itself, between units, so a capture that stops finishing them stops
+     * reporting. It changes nothing the capture writes.
+     */
+    onProgress?: (phase: CapturePhase, message: string) => void;
 }
 /** Wire protocol of a matched pair (drives the direction table). */
 export type ProbeProtocol = 'http' | 'graphql' | 'socket' | 'pubsub';

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

@@ -14,6 +14,8 @@
  *   IsFormBody gate fired (TS2344)        -> unverifiable (form-encoded body)
  *   IsByteBody gate fired (TS2344)        -> unverifiable (bytes, even agreeing)
  *   raw-text read marked on a side        -> unverifiable (text, even agreeing)
+ *   assignment error, sent union taken in part by a weak expected type
+ *                                         -> unverifiable (carrick#1995)
  *   assignment-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *
@@ -27,6 +29,7 @@ import type { CheckVerdict } from './api.js';
 import { type ProbePlan, type Side } from './check-probe.js';
 import { type ScrubContext } from './check-scrub.js';
 import type { PairDeepFindings } from './check-deep.js';
+import type { DispatchUnion } from './check-union.js';
 import { type PairFieldReport } from './check-fields.js';
 export interface RawDiagnostic {
     /** Workspace-relative, forward-slash file path (empty for global errors). */
@@ -66,6 +69,12 @@ export interface ClassifyInput {
      * run, in which case the tsc text stands alone.
      */
     fieldReport?: PairFieldReport;
+    /**
+     * Set when the sent side is a union the expected side takes only in part,
+     * every other member failing by nothing but the compiler's weak-type check
+     * (carrick#1995). Read only where the decisive assignment failed.
+     */
+    dispatchUnion?: DispatchUnion;
     /**
      * The side whose capture record says it reads the body as raw text
      * (carrick#1842), the sent side when both do. Read from the record, not the

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

@@ -14,6 +14,8 @@
  *   IsFormBody gate fired (TS2344)        -> unverifiable (form-encoded body)
  *   IsByteBody gate fired (TS2344)        -> unverifiable (bytes, even agreeing)
  *   raw-text read marked on a side        -> unverifiable (text, even agreeing)
+ *   assignment error, sent union taken in part by a weak expected type
+ *                                         -> unverifiable (carrick#1995)
  *   assignment-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *
@@ -220,6 +222,24 @@ export function classifyPair(input) {
     // the `string` it becomes) has no error on this line and is not a drift.
     const decisiveLine = decisiveAssignmentLine(plan);
     const assignDiag = probeDiags.find((d) => d.line === decisiveLine && ASSIGNMENT_CODES.has(d.code));
+    // 5a. Unless the mismatch is a sent union the expected type takes in part,
+    //     the members it rejects sharing no field with a type whose every field
+    //     is optional (carrick#1995). That is a route answering a body per
+    //     branch read by a caller of one branch: no member breaks a reader whose
+    //     every read allows absence, and which member the call receives is not
+    //     in the types. Not a fact either way, and no side to retype.
+    if (assignDiag && input.dispatchUnion) {
+        const { members, agreeing } = input.dispatchUnion;
+        const sent = plan.direction.sent;
+        const expected = plan.direction.expected;
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: `${sent}:union`,
+            diagnostic: `the ${sent} type is a union of ${members} bodies; the ${expected} type, every field optional, accepts ${agreeing} of them and shares no field with the other ${members - agreeing}, so the call reads one of the bodies the route answers and the types do not say which.`,
+            ...notAFact(`the ${sent} type is a union of bodies and the ${expected} type, every field optional, accepts only some of them`),
+        };
+    }
     if (assignDiag) {
         const text = scrubDiagnostic(assignDiag.message, scrubCtx, plan.sentEndpoint.alias, plan.expectedEndpoint.alias);
         return {

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

@@ -28,6 +28,7 @@
  *
  * Seam: node builtins + `typescript` + this bundle only.
  */
+import ts from 'typescript';
 import type { ProbePlan, Side } from './check-probe.js';
 import type { ProbeProgram } from './check-deep.js';
 /** What kind of difference one field path carries. */
@@ -69,6 +70,29 @@ export interface PairFieldReport {
  * how many more there are rather than pretending the list is complete.
  */
 export declare const MAX_NAMED_FIELDS = 8;
+/**
+ * The two types the judge's decisive assignment compared for one plan, read in
+ * the probe program, with the compiler's own assignability relation.
+ * `undefined` when the probe or either alias cannot be read, or the compiler
+ * build exposes no relation: every statement made without them would be a
+ * guess.
+ *
+ * The sent side is whatever that assignment actually sent: the GraphQL
+ * comparand where one exists, then the JSON wire form where serialising
+ * changes the type. Reading `sent` there instead would describe a type the
+ * judge did not compare, which is the one way a reader of this pair could
+ * contradict it.
+ */
+export declare function comparedTypes(opened: ProbeProgram, plan: ProbePlan): {
+    compared: ts.Type;
+    expected: {
+        type: ts.Type;
+        node: ts.Node;
+    };
+    wireApplied: boolean;
+    checker: ts.TypeChecker;
+    isAssignableTo: (source: ts.Type, target: ts.Type) => boolean;
+} | undefined;
 /**
  * Field reports for every plan whose probe the program could read, keyed by
  * pair id. A plan with no entry has no report, which is not a claim that its

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

@@ -54,6 +54,56 @@ function assignabilityOf(checker) {
     const fn = checker.isTypeAssignableTo;
     return typeof fn === 'function' ? fn.bind(checker) : undefined;
 }
+/**
+ * The two types the judge's decisive assignment compared for one plan, read in
+ * the probe program, with the compiler's own assignability relation.
+ * `undefined` when the probe or either alias cannot be read, or the compiler
+ * build exposes no relation: every statement made without them would be a
+ * guess.
+ *
+ * The sent side is whatever that assignment actually sent: the GraphQL
+ * comparand where one exists, then the JSON wire form where serialising
+ * changes the type. Reading `sent` there instead would describe a type the
+ * judge did not compare, which is the one way a reader of this pair could
+ * contradict it.
+ */
+export function comparedTypes(opened, plan) {
+    const { program, checker, probesDir } = opened;
+    const isAssignableTo = assignabilityOf(checker);
+    if (!isAssignableTo)
+        return undefined;
+    const file = program.getSourceFile(`${probesDir}/probes/${plan.fileName}`.split('\\').join('/'));
+    const source = file ??
+        program.getSourceFiles().find((sf) => sf.fileName.endsWith(`/probes/${plan.fileName}`));
+    if (!source)
+        return undefined;
+    const declared = declaredConstType(source, checker, 'sentComparand') ??
+        declaredConstType(source, checker, 'sent');
+    const expected = declaredConstType(source, checker, 'expected');
+    if (!declared || !expected)
+        return undefined;
+    const wire = declaredConstType(source, checker, 'sentWire');
+    // Whether serialising changes anything observable about the sent type.
+    const wireApplied = wire !== undefined &&
+        !(isAssignableTo(wire.type, declared.type) && isAssignableTo(declared.type, wire.type));
+    // 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 field 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.
+    return {
+        compared: wireApplied ? wire.type : declared.type,
+        expected,
+        wireApplied,
+        checker,
+        isAssignableTo,
+    };
+}
 /**
  * Field reports for every plan whose probe the program could read, keyed by
  * pair id. A plan with no entry has no report, which is not a claim that its
@@ -63,44 +113,12 @@ export function pairFieldReports(opened, plans) {
     const results = new Map();
     if (!opened)
         return results;
-    const { program, checker, probesDir } = opened;
-    const isAssignableTo = assignabilityOf(checker);
-    if (!isAssignableTo)
-        return results;
     for (const plan of plans) {
-        const file = program.getSourceFile(`${probesDir}/probes/${plan.fileName}`.split('\\').join('/'));
-        const source = file ??
-            program
-                .getSourceFiles()
-                .find((sf) => sf.fileName.endsWith(`/probes/${plan.fileName}`));
-        if (!source)
-            continue;
-        // Whatever the judge's decisive assignment actually sent: the GraphQL
-        // comparand where one exists, then the JSON wire form where one exists.
-        // Reading `sent` there instead would describe a type the judge did not
-        // compare, which is the one way this walk could contradict it.
-        const declared = declaredConstType(source, checker, 'sentComparand') ??
-            declaredConstType(source, checker, 'sent');
-        const expected = declaredConstType(source, checker, 'expected');
-        if (!declared || !expected)
+        const pair = comparedTypes(opened, plan);
+        if (!pair)
             continue;
-        const wire = declaredConstType(source, checker, 'sentWire');
-        // 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, plan.spec.protocol === 'graphql' ? GRAPHQL_SERVER_SUPPLIED : NONE_SERVER_SUPPLIED);
-        report.wireApplied = wireChanges;
+        const report = diffReport(pair.compared, pair.expected.type, pair.checker, pair.isAssignableTo, pair.expected.node, plan.spec.protocol === 'graphql' ? GRAPHQL_SERVER_SUPPLIED : NONE_SERVER_SUPPLIED);
+        report.wireApplied = pair.wireApplied;
         results.set(plan.pairId, report);
     }
     return results;

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

@@ -0,0 +1,40 @@
+/**
+ * A sent union whose members the expected type takes only in part, where the
+ * rest fail by nothing but the compiler's weak-type check (carrick#1995).
+ *
+ * A handler that answers a different body per branch (an action that switches
+ * on a field of the request) publishes the union of those bodies. A caller of
+ * one branch reads the response with a type whose every field is optional. The
+ * compiler then rejects each member that shares no field with that type
+ * (TS2559, "has no properties in common"): a type whose every property is
+ * optional is a "weak type", and the check exists to catch a misspelt property
+ * bag. It is not a soundness rule. At runtime every member satisfies a type
+ * whose reads all allow absence, and the call only ever receives the body of
+ * the branch it asked for, which the types do not say.
+ *
+ * So the pair is neither compatible nor incompatible: the judge cannot say
+ * which member the call receives. Kept narrow on purpose:
+ * - the sent type must be a union with at least one member that assigns;
+ * - the expected type must be one object type whose every property is
+ *   optional, with no index or call signatures;
+ * - every member that does not assign must be an object with properties, none
+ *   of which the expected type names.
+ * A sent type that is not a union and shares no field with a weak expected
+ * type is the misspelling the check exists for, and stays a mismatch.
+ *
+ * Read in the probe program, over the two types the decisive assignment
+ * compared, with the compiler's own relation. Seam: typescript + this bundle.
+ */
+import ts from 'typescript';
+import type { ProbePlan } from './check-probe.js';
+import type { ProbeProgram } from './check-deep.js';
+export interface DispatchUnion {
+    /** Members of the sent union. */
+    members: number;
+    /** Members the expected type takes. */
+    agreeing: number;
+}
+/** The finding for every plan whose compared types have this shape, by pair id. */
+export declare function pairDispatchUnions(opened: ProbeProgram | undefined, plans: ProbePlan[]): Map<string, DispatchUnion>;
+/** The shape above for one compared pair, or `undefined` when it does not hold. */
+export declare function dispatchUnion(sent: ts.Type, expected: ts.Type, checker: ts.TypeChecker, isAssignableTo: (source: ts.Type, target: ts.Type) => boolean): DispatchUnion | undefined;

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

@@ -0,0 +1,92 @@
+/**
+ * A sent union whose members the expected type takes only in part, where the
+ * rest fail by nothing but the compiler's weak-type check (carrick#1995).
+ *
+ * A handler that answers a different body per branch (an action that switches
+ * on a field of the request) publishes the union of those bodies. A caller of
+ * one branch reads the response with a type whose every field is optional. The
+ * compiler then rejects each member that shares no field with that type
+ * (TS2559, "has no properties in common"): a type whose every property is
+ * optional is a "weak type", and the check exists to catch a misspelt property
+ * bag. It is not a soundness rule. At runtime every member satisfies a type
+ * whose reads all allow absence, and the call only ever receives the body of
+ * the branch it asked for, which the types do not say.
+ *
+ * So the pair is neither compatible nor incompatible: the judge cannot say
+ * which member the call receives. Kept narrow on purpose:
+ * - the sent type must be a union with at least one member that assigns;
+ * - the expected type must be one object type whose every property is
+ *   optional, with no index or call signatures;
+ * - every member that does not assign must be an object with properties, none
+ *   of which the expected type names.
+ * A sent type that is not a union and shares no field with a weak expected
+ * type is the misspelling the check exists for, and stays a mismatch.
+ *
+ * Read in the probe program, over the two types the decisive assignment
+ * compared, with the compiler's own relation. Seam: typescript + this bundle.
+ */
+import ts from 'typescript';
+import { comparedTypes } from './check-fields.js';
+/** The finding for every plan whose compared types have this shape, by pair id. */
+export function pairDispatchUnions(opened, plans) {
+    const results = new Map();
+    if (!opened)
+        return results;
+    for (const plan of plans) {
+        const pair = comparedTypes(opened, plan);
+        if (!pair)
+            continue;
+        const finding = dispatchUnion(pair.compared, pair.expected.type, pair.checker, pair.isAssignableTo);
+        if (finding)
+            results.set(plan.pairId, finding);
+    }
+    return results;
+}
+/** The shape above for one compared pair, or `undefined` when it does not hold. */
+export function dispatchUnion(sent, expected, checker, isAssignableTo) {
+    if (!sent.isUnion())
+        return undefined;
+    const names = weakPropertyNames(expected, checker);
+    if (!names)
+        return undefined;
+    let agreeing = 0;
+    for (const member of sent.types) {
+        if (isAssignableTo(member, expected)) {
+            agreeing += 1;
+            continue;
+        }
+        if (!sharesNoProperty(member, names, checker))
+            return undefined;
+    }
+    if (agreeing === 0 || agreeing === sent.types.length)
+        return undefined;
+    return { members: sent.types.length, agreeing };
+}
+/**
+ * The property names of a weak object type: one object type, at least one
+ * property, every property optional, no index signature and no call or
+ * construct signature. `undefined` for any other type.
+ */
+function weakPropertyNames(type, checker) {
+    if (!(type.flags & ts.TypeFlags.Object))
+        return undefined;
+    if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0 ||
+        checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length > 0 ||
+        checker.getIndexInfosOfType(type).length > 0) {
+        return undefined;
+    }
+    const properties = checker.getPropertiesOfType(type);
+    if (properties.length === 0)
+        return undefined;
+    if (!properties.every((property) => (property.flags & ts.SymbolFlags.Optional) !== 0)) {
+        return undefined;
+    }
+    return new Set(properties.map((property) => property.name));
+}
+/** Whether `member` is an object with properties, none of them in `names`. */
+function sharesNoProperty(member, names, checker) {
+    if (!(member.flags & ts.TypeFlags.Object))
+        return false;
+    const properties = checker.getPropertiesOfType(member);
+    return properties.length > 0 && properties.every((property) => !names.has(property.name));
+}

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

@@ -26,6 +26,7 @@ import { assembleWorkspace, writeProbes, } from './check-workspace.js';
 import { buildPoisonIndexes } from './check-poison.js';
 import { openProbeProgram, probeDeepFindings } from './check-deep.js';
 import { pairFieldReports } from './check-fields.js';
+import { pairDispatchUnions } from './check-union.js';
 function runProcess(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
@@ -262,6 +263,9 @@ export async function runCheck(opts, onProgress) {
     // incompatible (carrick-tools/carrick-cloud#1118). It names what the verdict
     // is about; it never decides one.
     const fieldsByPair = pairFieldReports(probeProgram, probing);
+    // And which pairs compared a union the expected side takes only in part,
+    // the rest failing by nothing but the weak-type check (carrick#1995).
+    const unionsByPair = pairDispatchUnions(probeProgram, probing);
     const verdicts = sortVerdicts([
         ...probing.map((plan) => classifyPair({
             plan,
@@ -270,6 +274,7 @@ export async function runCheck(opts, onProgress) {
             scrubCtx,
             deepFindings: deepByPair.get(plan.pairId),
             fieldReport: fieldsByPair.get(plan.pairId),
+            dispatchUnion: unionsByPair.get(plan.pairId),
             rawTextSide: rawTextSideOf(plan, aliasRecords),
         })),
         ...preGated,

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

@@ -256,7 +256,8 @@ export function captureStub(opts) {
     }
     // ---- Phase A: analysis program over placeholder entry + anchor sources ----
     let resolved;
-    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath, guard };
+    const progress = opts.onProgress ?? (() => { });
+    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath, guard, progress };
     try {
         resolved = ownerGroups && emitProject
             ? resolveAnchorsByOwner(opts, ownerGroups, emitProject, analysisCtx, errors)
@@ -277,14 +278,9 @@ export function captureStub(opts) {
     }
     const scratch = WriteGuard.scratch('carrick-capture-v2-');
     const staging = scratch.dir;
-    const emitted = new Map();
-    // Input .d.ts files (ambient stubs, augmentation declarations, local
-    // hand-written declarations in the import closure) are never re-emitted by
-    // tsc; they must ship verbatim or the tree's references to them dangle.
-    const declarationSources = new Map();
-    const sourceByEmitted = new Map();
-    let emitPartial = false;
+    let written;
     try {
+        progress('emit', 'emitting declarations');
         guard.writeFile(entryPath, entryLines.join('\n') + '\n');
         const emitOptions = {
             ...parsed.options,
@@ -300,35 +296,13 @@ export function captureStub(opts) {
             outDir: staging,
             rootDir: entryDir,
         };
-        const program = ts.createProgram([entryPath, ...augmentationSources], emitOptions, deno?.host(emitOptions));
-        const emitResult = program.emit(undefined, (fileName, text, _bom, _error, sources) => {
-            emitted.set(fileName, text);
-            if (sources?.[0])
-                sourceByEmitted.set(path.relative(staging, fileName).split(path.sep).join('/'), sources[0].fileName);
-        }, undefined, 
-        /* emitOnlyDtsFiles */ true);
-        // emitSkipped is PER-PROGRAM even when only one file's declaration emit
-        // failed (e.g. TS4023 from a hand-rolled ambient stub shadowing a real
-        // package): every other file's .d.ts was still written to the callback.
-        // Fail wholesale only when nothing at all emitted; otherwise keep the
-        // emitted subset and demote exactly the aliases it cannot support.
-        if (emitResult.emitSkipped && emitted.size === 0) {
-            return fail(stubDir, packageName, ['declaration emit was skipped']);
-        }
-        emitPartial = emitResult.emitSkipped;
-        for (const d of emitResult.diagnostics) {
-            errors.push(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
-        }
-        for (const sourceFile of program.getSourceFiles()) {
-            if (!sourceFile.isDeclarationFile)
-                continue;
-            const abs = path.resolve(sourceFile.fileName);
-            const rel = path.relative(entryDir, abs).split(path.sep).join('/');
-            if (rel.startsWith('..') || rel.includes('node_modules/'))
-                continue;
-            declarationSources.set(rel, sourceFile.getFullText());
-            sourceByEmitted.set(rel, abs);
-        }
+        written = emitDeclarations({
+            rootNames: [entryPath, ...augmentationSources],
+            options: emitOptions,
+            host: deno?.host(emitOptions),
+            staging,
+            entryDir,
+        });
     }
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
@@ -338,6 +312,9 @@ export function captureStub(opts) {
             guard.unlink(entryPath);
         scratch.guard.remove(staging);
     }
+    const { emitted, declarationSources, sourceByEmitted } = written;
+    const emitPartial = written.partial;
+    errors.push(...written.diagnostics);
     // ---- Partial-emit recovery ----
     // The corpus-2 notifications-svc shape: one file's declaration emit was
     // skipped but the rest of the tree emitted fine. Keep the tree; demote any
@@ -490,6 +467,7 @@ export function captureStub(opts) {
         target: parsed.options.target !== undefined ? ts.ScriptTarget[parsed.options.target] : undefined,
     }, null, 2) + '\n');
     // ---- Capture-time self-check (per-alias closure attribution) ----
+    progress('self-check', 'checking the stub');
     const aliases = selfCheckStub({
         guard: stubGuard,
         stubDir,
@@ -526,6 +504,58 @@ export function captureStub(opts) {
         errors,
     };
 }
+/**
+ * Phase B: build the program of the final entry and emit its declarations.
+ *
+ * A function of its own so that its program dies with it (carrick#1916). The
+ * program is as large as the service, and nothing after the emit reads it:
+ * what the capture needs is the text returned here. While the emit ran inside
+ * `captureStub`, that one long function's frame went on holding the program
+ * for as long as the capture ran, so the self-check loaded its own program
+ * beside it; on a 2,345-file service that was 1,290 MB of a 2,741 MB peak.
+ *
+ * The caller builds the options and the host. A host is held by its program
+ * and holds none itself, so the caller keeping one keeps no program alive.
+ *
+ * Throws when the emit was skipped and wrote nothing.
+ */
+function emitDeclarations(args) {
+    const emitted = new Map();
+    const declarationSources = new Map();
+    const sourceByEmitted = new Map();
+    const program = ts.createProgram(args.rootNames, args.options, args.host);
+    const emitResult = program.emit(undefined, (fileName, text, _bom, _error, sources) => {
+        emitted.set(fileName, text);
+        if (sources?.[0])
+            sourceByEmitted.set(path.relative(args.staging, fileName).split(path.sep).join('/'), sources[0].fileName);
+    }, undefined, 
+    /* emitOnlyDtsFiles */ true);
+    // emitSkipped is PER-PROGRAM even when only one file's declaration emit
+    // failed (e.g. TS4023 from a hand-rolled ambient stub shadowing a real
+    // package): every other file's .d.ts was still written to the callback.
+    // Fail wholesale only when nothing at all emitted; otherwise keep the
+    // emitted subset and demote exactly the aliases it cannot support.
+    if (emitResult.emitSkipped && emitted.size === 0) {
+        throw new Error('declaration emit was skipped');
+    }
+    for (const sourceFile of program.getSourceFiles()) {
+        if (!sourceFile.isDeclarationFile)
+            continue;
+        const abs = path.resolve(sourceFile.fileName);
+        const rel = path.relative(args.entryDir, abs).split(path.sep).join('/');
+        if (rel.startsWith('..') || rel.includes('node_modules/'))
+            continue;
+        declarationSources.set(rel, sourceFile.getFullText());
+        sourceByEmitted.set(rel, abs);
+    }
+    return {
+        emitted,
+        declarationSources,
+        sourceByEmitted,
+        partial: emitResult.emitSkipped,
+        diagnostics: emitResult.diagnostics.map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n')),
+    };
+}
 /**
  * Partial-emit demotion: demote every anchor whose alias text names, by a
  * relative or an absolute path, a module the stub will not resolve, and
@@ -655,6 +685,7 @@ function resolveAnchors(opts, parsed, ctx, deno) {
     }
     ctx.guard.writeFile(ctx.entryPath, placeholderLines.join('\n') + '\n');
     try {
+        ctx.progress('program', 'building the program the anchors are read in');
         const anchorSources = [
             ...new Set(opts.anchors
                 .flatMap((a) => (a.source_file ? [path.join(ctx.repoRoot, a.source_file)] : []))),
@@ -664,6 +695,11 @@ function resolveAnchors(opts, parsed, ctx, deno) {
             noEmit: true,
         };
         const program = ts.createProgram([ctx.entryPath, ...anchorSources, ...(deno?.globals ?? [])], options, deno?.host(options));
+        // The checker binds every file of the program when it is first asked for,
+        // which the first anchor would otherwise do: asked for here, so that the
+        // report below says the program is whole before any anchor is read.
+        program.getTypeChecker();
+        ctx.progress('anchors', `0 of ${opts.anchors.length}`);
         const entrySource = program.getSourceFile(ctx.entryPath);
         const placeholders = new Map();
         if (entrySource) {
@@ -696,13 +732,17 @@ function resolveAnchors(opts, parsed, ctx, deno) {
                 siblingSymbolSpecs.set(anchor.symbol_name, entryRelativeSpecifier(ctx.entryDir, ctx.repoRoot, anchor.source_file, resolveFromEntry));
             }
         }
-        return opts.anchors.map((request) => resolveAnchor(program, request, {
-            repoRoot: ctx.repoRoot,
-            entryDir: ctx.entryDir,
-            placeholder: placeholders.get(request.alias),
-            siblingSymbolSpecs,
-            resolveFromEntry,
-        }));
+        return opts.anchors.map((request, index) => {
+            const anchor = resolveAnchor(program, request, {
+                repoRoot: ctx.repoRoot,
+                entryDir: ctx.entryDir,
+                placeholder: placeholders.get(request.alias),
+                siblingSymbolSpecs,
+                resolveFromEntry,
+            });
+            ctx.progress('anchors', `${index + 1} of ${opts.anchors.length}`);
+            return anchor;
+        });
     }
     finally {
         if (fs.existsSync(ctx.entryPath))

package/sidecar/dist/src/definition-resolver.d.ts

@@ -26,11 +26,12 @@
  * inference path in `type-inferrer.ts`), which walks the resolved `Type` and
  * rebuilds the inlined text.
  *
- * Each resolve call builds its own throwaway in-memory project over the stub
- * tree, so the warm sidecar's long-lived project never sees stub files and
- * cannot accumulate stale trees across requests.
+ * Each resolve call builds its own throwaway project over the stub tree and
+ * reads nothing else: not the service's project, and not whether the sidecar
+ * was ever initialised. So the request costs what the stub costs, in a process
+ * that has built nothing as in one that has (carrick#1927), and the sidecar's
+ * long-lived project never sees stub files.
  */
-import { Project } from 'ts-morph';
 export interface ResolvedDefinition {
     type_alias: string;
     /** Original declaration text as written (preserves named types) */
@@ -39,10 +40,6 @@ export interface ResolvedDefinition {
     expanded: string;
 }
 export declare class DefinitionResolver {
-    private readonly project;
-    constructor(options: {
-        project: Project;
-    });
     /**
      * Resolve surface aliases from a capture stub package directory
      * (`<stub_dir>/types/surface.d.ts` + its declaration tree).