carrick 0.3.53

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

@@ -0,0 +1,317 @@
+/**
+ * Capture-time self-check (design doc, Capture step 8, amendment 1), with
+ * per-alias closure attribution.
+ *
+ * The stub tree is typechecked standalone with `skipLibCheck: false` --
+ * spike-verified as load-bearing: the tree is entirely .d.ts and skipLibCheck
+ * skips declaration files wholesale, making the gate vacuous. When the
+ * source repo has node_modules, resolution is pointed at it via a temporary
+ * node_modules symlink inside the stub, so externals resolve exactly as they
+ * will at check time against installed pins.
+ *
+ * Classification per alias (three-way, keyed on diagnostics, never on
+ * printed type text):
+ *  - ok: resolves to a concrete type.
+ *  - allowlisted_external: resolution failed only through external
+ *    specifiers pinned in the stub's dependencies, on a bare checkout. The
+ *    alias KEEPS its serialization tier; the check-phase probe gates
+ *    (any/unknown/never, both sides) are the backstop.
+ *  - decayed_internal: a dangling internal specifier, an unpinned external,
+ *    or a top-type resolution with no allowlisted explanation.
+ *
+ * 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.
+ */
+import ts from 'typescript';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
+import { findDisqualifyingTopTypes, provenanceOf, } from './deep-walk.js';
+export function selfCheckStub(args) {
+    const typesDir = path.join(args.stubDir, 'types');
+    const treeFiles = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(p);
+            else if (entry.name.endsWith('.d.ts'))
+                treeFiles.push(p);
+        }
+    };
+    walk(typesDir);
+    // Point resolution at the producer repo's installed deps when present.
+    const repoNodeModules = path.join(args.repoRoot, 'node_modules');
+    const linkPath = path.join(args.stubDir, 'node_modules');
+    let linked = false;
+    if (!args.bareCheckout && fs.existsSync(repoNodeModules) && !fs.existsSync(linkPath)) {
+        fs.symlinkSync(repoNodeModules, linkPath, 'dir');
+        linked = true;
+    }
+    try {
+        return runSelfCheck(args, treeFiles);
+    }
+    finally {
+        // unlinkSync, not rmSync: the link target is a directory and rmSync
+        // refuses symlinks-to-directories with EISDIR.
+        if (linked)
+            fs.unlinkSync(linkPath);
+    }
+}
+function runSelfCheck(args, treeFiles) {
+    const program = ts.createProgram(treeFiles, {
+        noEmit: true,
+        strict: true,
+        // MUST be false: the whole stub tree is .d.ts (see module header).
+        skipLibCheck: false,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        types: [],
+    });
+    const checker = program.getTypeChecker();
+    const diagnostics = ts.getPreEmitDiagnostics(program);
+    // Failed module specifiers, split external-pinned vs internal, per FILE.
+    const failuresByFile = new Map();
+    const failuresFor = (fileName) => {
+        let entry = failuresByFile.get(fileName);
+        if (!entry) {
+            entry = { externalPinned: new Set(), internal: new Set() };
+            failuresByFile.set(fileName, entry);
+        }
+        return entry;
+    };
+    for (const d of diagnostics) {
+        if ((d.code !== 2307 && d.code !== 2792) || !d.file)
+            continue;
+        const msg = ts.flattenDiagnosticMessageText(d.messageText, ' ');
+        const m = /Cannot find module '([^']+)'/.exec(msg);
+        if (!m)
+            continue;
+        const spec = m[1];
+        const bucket = failuresFor(path.resolve(d.file.fileName));
+        if (!isRelative(spec) && args.pinned[packageNameOf(spec)]) {
+            bucket.externalPinned.add(spec);
+        }
+        else {
+            bucket.internal.add(spec);
+        }
+    }
+    // Per-file relative-import adjacency for closure walks.
+    const adjacency = new Map();
+    const treeSet = new Set(treeFiles.map((f) => path.resolve(f)));
+    for (const file of treeFiles) {
+        const abs = path.resolve(file);
+        const text = fs.readFileSync(abs, 'utf8');
+        const neighbors = [];
+        for (const spec of collectSpecifiers(text)) {
+            const resolved = resolveTreeSpecifier(abs, spec, treeSet);
+            if (resolved)
+                neighbors.push(resolved);
+        }
+        adjacency.set(abs, neighbors);
+    }
+    const surfaceAbs = path.resolve(args.surfaceAbsPath);
+    const surfaceSource = program.getSourceFile(surfaceAbs);
+    const records = [];
+    for (const anchor of args.resolved) {
+        // Demotions (failureReason present) never reached the surface with a
+        // real type; everything else — including successful literal anchors,
+        // which sit at the structural_fallback TIER but did produce text — is
+        // classified by the real self-check.
+        records.push(anchor.failureReason !== undefined
+            ? demotedRecord(anchor)
+            : checkedRecord(anchor, {
+                args,
+                program,
+                checker,
+                surfaceAbs,
+                surfaceSource,
+                adjacency,
+                failuresByFile,
+            }));
+    }
+    return records;
+}
+/** An alias that never reached a capture-native tier: the failure reason was
+ * recorded at demotion time; the surface line is `unknown` by construction. */
+function demotedRecord(anchor) {
+    return {
+        alias: anchor.request.alias,
+        anchor_kind: anchor.request.kind,
+        symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
+        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        anchor_origin: anchor.request.anchor_origin,
+        serialization: 'structural_fallback',
+        self_check: 'decayed_internal',
+        self_check_detail: anchor.failureReason,
+        capture_failure_reason: anchor.failureReason,
+        top_type_at_self_check: true,
+    };
+}
+function checkedRecord(anchor, ctx) {
+    const alias = anchor.request.alias;
+    let topType = true;
+    let deepFindings = [];
+    const seeds = [];
+    if (ctx.surfaceSource) {
+        for (const stmt of ctx.surfaceSource.statements) {
+            if (!ts.isTypeAliasDeclaration(stmt) || stmt.name.text !== alias)
+                continue;
+            const type = ctx.checker.getTypeAtLocation(stmt.name);
+            topType =
+                (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) !== 0;
+            if (!topType) {
+                deepFindings = findDisqualifyingTopTypes(type, ctx.program, ctx.checker, stmt.name);
+            }
+            // Seed the closure with the alias's own import-type targets.
+            const visit = (node) => {
+                if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+                    const lit = node.argument.literal;
+                    if (ts.isStringLiteral(lit) && isRelative(lit.text)) {
+                        const resolved = resolveTreeSpecifier(ctx.surfaceAbs, lit.text, new Set(ctx.adjacency.keys()));
+                        if (resolved)
+                            seeds.push(resolved);
+                    }
+                }
+                node.forEachChild(visit);
+            };
+            visit(stmt);
+        }
+    }
+    // Closure = surface itself + BFS from the alias's import-type seeds.
+    const closure = new Set([ctx.surfaceAbs]);
+    const queue = [...seeds];
+    while (queue.length > 0) {
+        const file = queue.pop();
+        if (closure.has(file))
+            continue;
+        closure.add(file);
+        for (const next of ctx.adjacency.get(file) ?? [])
+            queue.push(next);
+    }
+    let blamedExternal;
+    let internalFailure;
+    for (const file of closure) {
+        const failures = ctx.failuresByFile.get(file);
+        if (!failures)
+            continue;
+        if (!blamedExternal)
+            blamedExternal = [...failures.externalPinned][0];
+        if (!internalFailure)
+            internalFailure = [...failures.internal][0];
+    }
+    // Classification consults the closure failures REGARDLESS of the root
+    // type: a dangling internal specifier means part of this alias's closure
+    // is missing and the emitted tree is silently wrong even when the root
+    // resolves to a concrete shape (adversarial-review finding 1).
+    let outcome = 'ok';
+    let detail;
+    const allowlisted = () => {
+        const pkg = packageNameOf(blamedExternal);
+        outcome = 'allowlisted_external';
+        detail =
+            `unresolved external '${blamedExternal}' is pinned ` +
+                `(${pkg}@${ctx.args.pinned[pkg]}); kept at tier ${anchor.serialization} ` +
+                'on bare checkout; probe gates are the backstop';
+    };
+    // `unexplainedDeep`: a member-level author-baked any/unknown. The deep walk
+    // excludes TypeScript's unresolved-reference `error` placeholder (see
+    // `flagOf`), so `deep` is ALWAYS an author-baked disqualifier that survives
+    // into the emitted `.d.ts` text — never a healable external decay. The check
+    // phase must pre-gate exactly these: its probe gates are whole-type only and
+    // cannot see a member-level any.
+    let unexplainedDeep = [];
+    const deep = deepFindings[0];
+    if (internalFailure) {
+        outcome = 'decayed_internal';
+        detail = `dangling internal specifier '${internalFailure}'`;
+    }
+    else if (topType || deep) {
+        // `deepFindings` is only computed when `!topType`, so the two are mutually
+        // exclusive here.
+        if (deep) {
+            // A member-level disqualifier. Either an author-baked any/unknown (baked
+            // into the emitted text; does NOT heal when the check installs pins) or a
+            // `budget_exhausted` sentinel (a subtree too deep/wide to finish). Record
+            // it even when the closure ALSO carries a failing pinned external (which
+            // would otherwise allowlist the alias) — fail closed.
+            unexplainedDeep = deepFindings;
+            outcome = 'decayed_internal';
+            detail =
+                deep.kind === 'budget_exhausted'
+                    ? `type too deep or wide to verify within the capture budget at ` +
+                        `'${deep.path}'; abstaining (fail closed) rather than risk a buried ` +
+                        'any reading compatible'
+                    : `type carries '${deep.kind}' at '${deep.path}'; an arbitrary ` +
+                        'counterparty shape would read compatible';
+        }
+        else if (blamedExternal) {
+            // Root top type from a pinned external decay: heals when the check
+            // installs the pin.
+            if (ctx.args.bareCheckout) {
+                allowlisted();
+            }
+            else {
+                outcome = 'decayed_internal';
+                detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+            }
+        }
+        else {
+            // Root top type with no external explanation.
+            outcome = 'decayed_internal';
+            detail = 'alias resolved to a top type with no allowlisted external failure';
+        }
+    }
+    else if (blamedExternal) {
+        // The alias's own type is fully concrete, but its closure has failing
+        // pinned-external specifiers — previously invisible behind the topType
+        // gate. On a bare checkout that is the expected amendment-1 shape; on an
+        // installed checkout it means the tree references something the repo's
+        // own node_modules could not resolve.
+        if (ctx.args.bareCheckout) {
+            allowlisted();
+        }
+        else {
+            outcome = 'decayed_internal';
+            detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+        }
+    }
+    return {
+        alias,
+        anchor_kind: anchor.request.kind,
+        symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
+        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        anchor_origin: anchor.request.anchor_origin,
+        serialization: anchor.serialization,
+        self_check: outcome,
+        // A #438/#439 re-aim note is provenance only; a real decay detail always
+        // wins, so it surfaces exactly when the re-aimed alias self-checks clean.
+        // An abstain (carrick#766) is the most specific statement available: the
+        // surface line is `unknown` because this layer wrote it that way, so its
+        // reason outranks whatever the closure walk blames.
+        self_check_detail: anchor.abstainReason ?? detail ?? anchor.reaimNote,
+        top_type_at_self_check: topType,
+        ...(unexplainedDeep.length > 0
+            ? { any_provenance: unexplainedDeep.map(provenanceOf) }
+            : {}),
+    };
+}
+/** Resolve a relative specifier from `fromAbs` to a tree file, if present. */
+function resolveTreeSpecifier(fromAbs, spec, tree) {
+    if (!isRelative(spec))
+        return undefined;
+    const base = path.resolve(path.dirname(fromAbs), spec);
+    const candidates = [
+        `${base}.d.ts`,
+        path.join(base, 'index.d.ts'),
+        base.endsWith('.js') ? `${base.slice(0, -3)}.d.ts` : undefined,
+        base, // already .d.ts
+    ].filter((c) => c !== undefined);
+    for (const candidate of candidates) {
+        if (tree.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Module-specifier helpers shared across the capture bundle: extraction from
+ * declaration text, external/internal classification, and tsconfig-`paths`
+ * pattern matching for the post-emit rewrite pass.
+ */
+export declare function isRelative(spec: string): boolean;
+/** zod -> zod, @scope/pkg/sub -> @scope/pkg, pkg/sub -> pkg */
+export declare function packageNameOf(spec: string): string;
+/** Extract every module specifier mentioned in a .d.ts text: `from "x"`,
+ * `import "x"`, and `import("x")` type references. */
+export declare function collectSpecifiers(text: string): Set<string>;
+/**
+ * One parsed tsconfig `paths` mapping: pattern "prefix*suffix" (or exact) to
+ * substitution targets resolved against the config's path base.
+ */
+export interface PathsPattern {
+    /** Original pattern, e.g. "@app/*" */
+    pattern: string;
+    prefix: string;
+    /** undefined for exact (starless) patterns */
+    suffix?: string;
+    /** Absolute target templates ("*" preserved), in declaration order. */
+    targets: string[];
+}
+/**
+ * Match a specifier against a pattern. Returns the "*" capture ('' for exact
+ * matches) or undefined when there is no match.
+ */
+export declare function matchPathsPattern(spec: string, p: PathsPattern): string | undefined;
+/**
+ * Rewrite every specifier occurrence in a .d.ts text through `map`. The map
+ * receives each specifier and returns a replacement or undefined (keep).
+ * Operates on the same syntactic positions collectSpecifiers finds, so the
+ * two stay consistent by construction.
+ */
+export declare function rewriteSpecifiers(text: string, map: (spec: string) => string | undefined): {
+    text: string;
+    rewrites: number;
+};

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

@@ -0,0 +1,56 @@
+/**
+ * Module-specifier helpers shared across the capture bundle: extraction from
+ * declaration text, external/internal classification, and tsconfig-`paths`
+ * pattern matching for the post-emit rewrite pass.
+ */
+export function isRelative(spec) {
+    return spec.startsWith('./') || spec.startsWith('../') || spec.startsWith('/');
+}
+/** zod -> zod, @scope/pkg/sub -> @scope/pkg, pkg/sub -> pkg */
+export function packageNameOf(spec) {
+    const parts = spec.split('/');
+    return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+/** Extract every module specifier mentioned in a .d.ts text: `from "x"`,
+ * `import "x"`, and `import("x")` type references. */
+export function collectSpecifiers(text) {
+    const specs = new Set();
+    const re = /(?:from\s+|import\s+|import\s*\(\s*)["']([^"']+)["']/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        specs.add(m[1]);
+    }
+    return specs;
+}
+/**
+ * Match a specifier against a pattern. Returns the "*" capture ('' for exact
+ * matches) or undefined when there is no match.
+ */
+export function matchPathsPattern(spec, p) {
+    if (p.suffix === undefined) {
+        return spec === p.pattern ? '' : undefined;
+    }
+    if (spec.length >= p.prefix.length + p.suffix.length &&
+        spec.startsWith(p.prefix) &&
+        spec.endsWith(p.suffix)) {
+        return spec.slice(p.prefix.length, spec.length - p.suffix.length);
+    }
+    return undefined;
+}
+/**
+ * Rewrite every specifier occurrence in a .d.ts text through `map`. The map
+ * receives each specifier and returns a replacement or undefined (keep).
+ * Operates on the same syntactic positions collectSpecifiers finds, so the
+ * two stay consistent by construction.
+ */
+export function rewriteSpecifiers(text, map) {
+    let rewrites = 0;
+    const out = text.replace(/((?:from\s+|import\s+|import\s*\(\s*)["'])([^"']+)(["'])/g, (whole, open, spec, close) => {
+        const replacement = map(spec);
+        if (replacement === undefined || replacement === spec)
+            return whole;
+        rewrites++;
+        return `${open}${replacement}${close}`;
+    });
+    return { text: out, rewrites };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * DefinitionResolver - Resolves surface type aliases from a v2 capture stub
+ * package's declaration tree using the TypeScript compiler.
+ *
+ * Two forms are produced per alias:
+ *  - `definition`: the declaration *as written* (named refs preserved). For a
+ *    surface alias `export type A = import('./m').Order;` this follows the
+ *    alias to its target declaration in the stub tree (`interface Order {...}`)
+ *    so the definition keeps its real name and members; when the target is
+ *    anonymous (inline object types, node-builder prints) the surface alias
+ *    line itself is the as-written form.
+ *  - `expanded`: the fully *structural* form, with every named member type
+ *    inlined to its member structure, recursively.
+ *
+ * `type.getText(node, NoTruncation)` does NOT inline named members — the
+ * compiler prints a referenced type by its symbol name when that symbol is in
+ * scope (`total: Money`, not `total: { amountCents: number; currency: string }`).
+ * The structural form is produced by `expandTypeStructural` (shared with the
+ * 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.
+ */
+import { Project } from 'ts-morph';
+export interface ResolvedDefinition {
+    type_alias: string;
+    /** Original declaration text as written (preserves named types) */
+    definition: string;
+    /** Fully structural form: named member types inlined to their structure */
+    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).
+     *
+     * Uses a DEDICATED project with `moduleResolution: Bundler`, not the
+     * repo's own project: the stub tree's relative import-types are
+     * extensionless, which a NodeNext-configured repo project silently fails
+     * to resolve (the alias then reads as `any`). Bundler resolution accepts
+     * both extensionless and `.js`-suffixed specifiers — the same policy the
+     * check-phase workspace uses.
+     */
+    resolveFromStub(stubDir: string, aliases: string[]): ResolvedDefinition[];
+    /**
+     * Resolve a single alias: the original text and the structural form.
+     */
+    private resolveAlias;
+    private log;
+    private logError;
+}

package/sidecar/dist/src/definition-resolver.js

@@ -0,0 +1,153 @@
+/**
+ * DefinitionResolver - Resolves surface type aliases from a v2 capture stub
+ * package's declaration tree using the TypeScript compiler.
+ *
+ * Two forms are produced per alias:
+ *  - `definition`: the declaration *as written* (named refs preserved). For a
+ *    surface alias `export type A = import('./m').Order;` this follows the
+ *    alias to its target declaration in the stub tree (`interface Order {...}`)
+ *    so the definition keeps its real name and members; when the target is
+ *    anonymous (inline object types, node-builder prints) the surface alias
+ *    line itself is the as-written form.
+ *  - `expanded`: the fully *structural* form, with every named member type
+ *    inlined to its member structure, recursively.
+ *
+ * `type.getText(node, NoTruncation)` does NOT inline named members — the
+ * compiler prints a referenced type by its symbol name when that symbol is in
+ * scope (`total: Money`, not `total: { amountCents: number; currency: string }`).
+ * The structural form is produced by `expandTypeStructural` (shared with the
+ * 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.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { Project, Node } from 'ts-morph';
+import { expandTypeStructural } from './type-structural-expander.js';
+export class DefinitionResolver {
+    project;
+    constructor(options) {
+        this.project = options.project;
+    }
+    /**
+     * Resolve surface aliases from a capture stub package directory
+     * (`<stub_dir>/types/surface.d.ts` + its declaration tree).
+     *
+     * Uses a DEDICATED project with `moduleResolution: Bundler`, not the
+     * repo's own project: the stub tree's relative import-types are
+     * extensionless, which a NodeNext-configured repo project silently fails
+     * to resolve (the alias then reads as `any`). Bundler resolution accepts
+     * both extensionless and `.js`-suffixed specifiers — the same policy the
+     * check-phase workspace uses.
+     */
+    resolveFromStub(stubDir, aliases) {
+        const typesDir = path.join(stubDir, 'types');
+        const surfacePath = path.join(typesDir, 'surface.d.ts');
+        if (!fs.existsSync(surfacePath)) {
+            this.log(`No surface.d.ts under ${stubDir}; nothing to resolve`);
+            return [];
+        }
+        try {
+            const stubProject = new Project({
+                compilerOptions: {
+                    target: 99, // ESNext
+                    module: 99, // ESNext
+                    moduleResolution: 100, // Bundler
+                    strict: true,
+                    skipLibCheck: true,
+                },
+                skipAddingFilesFromTsConfig: true,
+            });
+            for (const filePath of walkDtsFiles(typesDir)) {
+                stubProject.addSourceFileAtPath(filePath);
+            }
+            const surface = stubProject.getSourceFile(surfacePath);
+            if (!surface) {
+                this.logError(`Failed to load ${surfacePath}`);
+                return [];
+            }
+            const results = [];
+            for (const alias of aliases) {
+                const result = this.resolveAlias(surface, alias);
+                if (result) {
+                    results.push(result);
+                }
+                else {
+                    this.log(`Could not resolve alias: ${alias}`);
+                }
+            }
+            return results;
+        }
+        catch (err) {
+            this.logError(`Resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    /**
+     * Resolve a single alias: the original text and the structural form.
+     */
+    resolveAlias(sourceFile, alias) {
+        const decl = sourceFile.getTypeAlias(alias) ??
+            sourceFile.getInterface(alias) ??
+            sourceFile.getClass(alias) ??
+            sourceFile.getEnum(alias);
+        if (!decl)
+            return null;
+        try {
+            const type = decl.getType();
+            // As-written form: prefer the alias target's own declaration (the real
+            // `interface Order {...}` in the tree) over the surface's import-type
+            // line, so named shapes read naturally. Fall back to the alias line for
+            // anonymous targets, self-referential alias symbols, or lib/external
+            // declarations outside the stub tree.
+            let definition = decl.getText();
+            for (const symbol of [type.getAliasSymbol(), type.getSymbol()]) {
+                const targetDecl = symbol?.getDeclarations()?.[0];
+                if (targetDecl &&
+                    targetDecl !== decl &&
+                    (Node.isInterfaceDeclaration(targetDecl) ||
+                        Node.isTypeAliasDeclaration(targetDecl) ||
+                        Node.isClassDeclaration(targetDecl) ||
+                        Node.isEnumDeclaration(targetDecl)) &&
+                    !targetDecl.getSourceFile().getFilePath().includes('node_modules')) {
+                    definition = targetDecl.getText();
+                    break;
+                }
+            }
+            // Structural form — every named member inlined to its shape.
+            const expanded = expandTypeStructural(type);
+            return { type_alias: alias, definition, expanded };
+        }
+        catch (err) {
+            this.logError(`Failed to resolve ${alias}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    log(message) {
+        console.error(`[sidecar:definition-resolver] ${message}`);
+    }
+    logError(message) {
+        console.error(`[sidecar:definition-resolver:error] ${message}`);
+    }
+}
+/** All .d.ts files under a directory, depth-first, deterministic order. */
+function walkDtsFiles(dir) {
+    const out = [];
+    const walk = (current) => {
+        const entries = fs
+            .readdirSync(current, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const p = path.join(current, entry.name);
+            if (entry.isDirectory())
+                walk(p);
+            else if (entry.name.endsWith('.d.ts'))
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out;
+}

package/sidecar/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Main entry point for the type-sidecar
+ *
+ * This module implements a message loop that:
+ * 1. Listens on stdin for JSON requests
+ * 2. Processes each request (init, bundle, emit_surface, infer, build_workspace, check_compatibility, health, shutdown)
+ * 3. Writes JSON responses to stdout
+ *
+ * IMPORTANT:
+ * - stdout is ONLY for JSON responses
+ * - stderr is for logging
+ * - Process stays alive between requests (warm standby)
+ */
+export {};