carrick 0.3.53

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

@@ -0,0 +1,160 @@
+/**
+ * Framework-machinery detection for the v2 capture path (carrick#371).
+ *
+ * A producer response anchor whose resolved type IS or CONTAINS HTTP transport
+ * machinery — a fetch/DOM `Response`/`Request`, a Node `http.ServerResponse`, a
+ * wrapper envelope `{ response: Response; error?: undefined } | { ...; error }`,
+ * or a wrapper function `(req: Request) => Promise<Response>` — must never be
+ * emitted as a comparable contract. Comparing it against the consumer's real
+ * payload manufactures a false compat mismatch (the bug this module fixes).
+ *
+ * This is the raw-`ts` seam mirror of `type-inferrer.ts`'s
+ * `typeIsOrContainsResponseMachinery` (ts-morph): the capture/ seam forbids
+ * importing a module from outside it, so the canonical indicator set and the
+ * detection shape are duplicated here in lockstep — the same pattern by which
+ * `BUILTIN_ANCHOR_SYMBOLS` mirrors `socket_io.rs`. Detection is STRUCTURAL and
+ * framework-agnostic: no framework NAME appears, only the shared HTTP-message
+ * member surface, gated by a lib / `node_modules` declaration origin so a user
+ * payload that merely shares a member name can never trip it.
+ */
+import ts from 'typescript';
+/**
+ * Strongly-discriminating member names of HTTP transport machinery. Kept
+ * identical to `MACHINERY_MEMBER_INDICATORS` in `type-inferrer.ts`. These are
+ * the names no JSON payload carries (`ok`, `redirected`, `bodyUsed`,
+ * `writeHead`, ...), so the origin gate + threshold never fire on real data.
+ * Exported so a drift-guard test (`machinery-indicator-mirror.test.ts`) asserts
+ * it stays equal to the `type-inferrer.ts` copy — nothing else enforces the
+ * lockstep, and if the two drift one path silently stops abstaining.
+ */
+export const MACHINERY_MEMBER_INDICATORS = new Set([
+    // fetch / DOM Response & Request body-consumer surface
+    'ok',
+    'redirected',
+    'bodyUsed',
+    'arrayBuffer',
+    'blob',
+    'formData',
+    'clone',
+    'json',
+    'statusText',
+    // Node http ServerResponse / reply-object surface
+    'statusCode',
+    'statusMessage',
+    'setHeader',
+    'getHeader',
+    'removeHeader',
+    'writeHead',
+    'flushHeaders',
+]);
+/** Machinery needs at least this many indicator members to be recognized. */
+const MACHINERY_INDICATOR_THRESHOLD = 3;
+/**
+ * True when `type`, resolved against `node`, IS or CONTAINS framework
+ * machinery.
+ *
+ * DETECTS, exactly:
+ *   1. the type itself is machinery (`isFrameworkMachinery`);
+ *   2. a union/intersection member is machinery (the envelope union);
+ *   3. a DIRECT property whose type is machinery (`{ response: Response }`),
+ *      ONE level of descent only;
+ *   4. a CALL SIGNATURE whose AWAITED return type is machinery — the wrapper
+ *      function `(req) => Promise<Response>` the Infer fallback resolves to.
+ *      (Only the call return is awaited; property types below are not.)
+ *
+ * DELIBERATELY NOT DETECTED — stated so this comment never overstates the
+ * guarantee (mirrors the same list in `type-inferrer.ts`). Each is a
+ * non-regression (pre-existing verdict unchanged, never a new wrong one), a
+ * tracked follow-up:
+ *   - machinery nested deeper than one property level;
+ *   - a PROPERTY typed `Promise<Response>` (property types are not awaited /
+ *     Promise-unwrapped before the check — only call-signature returns are);
+ *   - an array element type: `Response[]` is not descended to its element;
+ *   - `interface X extends Response` declared in USER source — the origin gate
+ *     is lib/`node_modules` only, so a user-declared subtype reads as a real
+ *     contract.
+ *
+ * The depth cap + origin gate keep a legitimate payload that merely references a
+ * machinery type far inside from over-abstaining.
+ */
+export function typeIsOrContainsMachinery(checker, type, node) {
+    return isOrContains(checker, type, node, 0);
+}
+function isOrContains(checker, type, node, depth) {
+    if (isFrameworkMachinery(checker, type)) {
+        return true;
+    }
+    if (type.isUnion() || type.isIntersection()) {
+        return type.types.some((part) => isOrContains(checker, part, node, depth));
+    }
+    if (depth >= 1) {
+        return false;
+    }
+    // A wrapper function value: descend into its (awaited) return type.
+    for (const sig of checker.getSignaturesOfType(type, ts.SignatureKind.Call)) {
+        const returnType = sig.getReturnType();
+        const awaited = checker.getAwaitedType?.(returnType) ?? returnType;
+        if (isOrContains(checker, awaited, node, depth + 1)) {
+            return true;
+        }
+    }
+    // Direct properties: the `{ response: Response; error }` envelope shape.
+    for (const prop of checker.getPropertiesOfType(type)) {
+        const propType = checker.getTypeOfSymbolAtLocation(prop, node);
+        if (isOrContains(checker, propType, node, depth + 1)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when `type` itself is an HTTP-machinery type: it structurally carries at
+ * least `MACHINERY_INDICATOR_THRESHOLD` of the indicator members AND its symbol
+ * is declared in a lib (`lib.*.d.ts`) or `node_modules` origin.
+ */
+function isFrameworkMachinery(checker, type) {
+    let hits = 0;
+    for (const prop of checker.getPropertiesOfType(type)) {
+        if (MACHINERY_MEMBER_INDICATORS.has(prop.getName())) {
+            hits += 1;
+            if (hits >= MACHINERY_INDICATOR_THRESHOLD)
+                break;
+        }
+    }
+    if (hits < MACHINERY_INDICATOR_THRESHOLD) {
+        return false;
+    }
+    return symbolIsLibOrExternalOrigin(checker, type.getSymbol() ?? type.aliasSymbol);
+}
+/**
+ * True when the symbol is declared in a TS lib file (`lib.*.d.ts`) or under
+ * `node_modules`. Works on a bare checkout: the DOM `Response`/`Request`
+ * resolve from the bundled `lib.dom.d.ts` even with no installed dependencies.
+ */
+function symbolIsLibOrExternalOrigin(checker, symbol) {
+    if (!symbol) {
+        return false;
+    }
+    const isExternalPath = (filePath) => {
+        const normalized = filePath.replace(/\\/g, '/');
+        return (normalized.includes('/node_modules/') ||
+            /\/lib\.[^/]*\.d\.ts$/.test(normalized));
+    };
+    for (const decl of symbol.getDeclarations() ?? []) {
+        if (isExternalPath(decl.getSourceFile().fileName)) {
+            return true;
+        }
+    }
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+        try {
+            const aliased = checker.getAliasedSymbol(symbol);
+            if (aliased && aliased !== symbol) {
+                return symbolIsLibOrExternalOrigin(checker, aliased);
+            }
+        }
+        catch {
+            // Ignore errors when resolving the aliased symbol.
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * SymbolTracker-backed node-builder printing for anonymous inferred types
+ * (design doc, Capture step 5). This is WP1's risk concentration, built
+ * failure-visibility-first: any tracked symbol that is not plainly
+ * accessible from the destination file demotes the alias to the
+ * structural_fallback tier with a recorded reason -- the bundle never ships
+ * a silently wrong .d.ts.
+ *
+ * The four banked corrections from the 2026-07-02 derisk sweep, applied
+ * verbatim:
+ *  1. enclosingDeclaration anchors in the DESTINATION surface file (the
+ *     entry's placeholder alias for this anchor), never undefined.
+ *  2. Demotion triggers on accessibility !== Accessible -- that includes
+ *     CannotBeNamed (2), not just NotAccessible (1).
+ *  3. Detection drives off the trackSymbol callback; the
+ *     reportInaccessibleUniqueSymbolError / reportInaccessibleThisError
+ *     callbacks never fire for these shapes and are implemented only as
+ *     belt-and-braces recorders.
+ *  4. The tracker is passed as the 5th argument of the (internal)
+ *     typeToTypeNode signature: (type, enclosingDeclaration, flags,
+ *     internalFlags, tracker).
+ */
+import ts from 'typescript';
+export interface NodeBuilderPrintResult {
+    /** Printed type text, present only when the print is trusted. */
+    text?: string;
+    /** Symbols the tracker flagged as not accessible from the destination. */
+    inaccessible: string[];
+    /** Failure description when text is absent. */
+    failure?: string;
+}
+/**
+ * Print `type` as a type node anchored at `destination` (a declaration inside
+ * the surface entry file). Returns untrusted-failure instead of text whenever
+ * any referenced symbol is not plainly accessible from the destination.
+ */
+export declare function printTypeForDestination(program: ts.Program, type: ts.Type, destination: ts.Node): NodeBuilderPrintResult;

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

@@ -0,0 +1,123 @@
+/**
+ * SymbolTracker-backed node-builder printing for anonymous inferred types
+ * (design doc, Capture step 5). This is WP1's risk concentration, built
+ * failure-visibility-first: any tracked symbol that is not plainly
+ * accessible from the destination file demotes the alias to the
+ * structural_fallback tier with a recorded reason -- the bundle never ships
+ * a silently wrong .d.ts.
+ *
+ * The four banked corrections from the 2026-07-02 derisk sweep, applied
+ * verbatim:
+ *  1. enclosingDeclaration anchors in the DESTINATION surface file (the
+ *     entry's placeholder alias for this anchor), never undefined.
+ *  2. Demotion triggers on accessibility !== Accessible -- that includes
+ *     CannotBeNamed (2), not just NotAccessible (1).
+ *  3. Detection drives off the trackSymbol callback; the
+ *     reportInaccessibleUniqueSymbolError / reportInaccessibleThisError
+ *     callbacks never fire for these shapes and are implemented only as
+ *     belt-and-braces recorders.
+ *  4. The tracker is passed as the 5th argument of the (internal)
+ *     typeToTypeNode signature: (type, enclosingDeclaration, flags,
+ *     internalFlags, tracker).
+ */
+import ts from 'typescript';
+/**
+ * SymbolAccessibility is internal to the compiler (stable since TS 1.x):
+ * Accessible = 0, NotAccessible = 1, CannotBeNamed = 2. Mirrored here
+ * because the public .d.ts does not export it; correction 2 depends on the
+ * distinction between the two failure members.
+ */
+const ACCESSIBLE = 0;
+/**
+ * The node builder can only print out-of-scope symbols as `import("...")`
+ * type references when the tracker carries a moduleResolverHost -- without
+ * one it returns no node at all for external-package symbols
+ * (probe-verified on TS 5.8). Hand-rolling the host is a losing game (it
+ * needs a dozen emit-host internals); TS's own factory builds it from the
+ * program, which is exactly the "route through the emitter's machinery, not
+ * a bare typeToTypeNode" guidance from the derisk sweep.
+ */
+function moduleResolverHostFor(program) {
+    const factory = ts.createModuleSpecifierResolutionHost;
+    if (!factory)
+        return undefined;
+    return factory(program, {
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        directoryExists: ts.sys.directoryExists,
+        getCurrentDirectory: () => program.getCurrentDirectory(),
+        useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+    });
+}
+/**
+ * Print `type` as a type node anchored at `destination` (a declaration inside
+ * the surface entry file). Returns untrusted-failure instead of text whenever
+ * any referenced symbol is not plainly accessible from the destination.
+ */
+export function printTypeForDestination(program, type, destination) {
+    const checker = program.getTypeChecker();
+    const inaccessible = [];
+    const seen = new Set();
+    const record = (symbol, meaning) => {
+        if (seen.has(symbol))
+            return;
+        seen.add(symbol);
+        const accessibility = checker.isSymbolAccessible(symbol, destination, // correction 1: destination file, never undefined
+        meaning ?? ts.SymbolFlags.Type, 
+        /* shouldComputeAliasesToMakeVisible */ false).accessibility;
+        // Correction 2: anything other than Accessible demotes -- CannotBeNamed
+        // (2) is a distinct enum member that a `=== NotAccessible` check misses.
+        if (accessibility !== ACCESSIBLE) {
+            inaccessible.push(symbol.getName());
+        }
+    };
+    // Correction 3: trackSymbol is the callback that actually fires. The
+    // report* callbacks are dead for the verified failure shapes (unexported
+    // local interfaces, unique-symbol keys, local recursive aliases) but are
+    // kept as recorders in case other shapes reach them.
+    const tracker = {
+        moduleResolverHost: moduleResolverHostFor(program),
+        trackSymbol: (symbol, enclosing, meaning) => {
+            void enclosing;
+            record(symbol, meaning);
+            // Returning false tells the builder no error was reported here; the
+            // demotion decision is ours, made after the walk completes.
+            return false;
+        },
+        reportInaccessibleThisError: () => {
+            inaccessible.push('this');
+        },
+        reportInaccessibleUniqueSymbolError: () => {
+            inaccessible.push('(unique symbol)');
+        },
+        reportPrivateInBaseOfClassExpression: (propertyName) => {
+            inaccessible.push(propertyName);
+        },
+    };
+    let node;
+    try {
+        node = checker.typeToTypeNode(type, destination, ts.NodeBuilderFlags.NoTruncation |
+            ts.NodeBuilderFlags.UseStructuralFallback |
+            ts.NodeBuilderFlags.InTypeAlias, 
+        /* internalFlags */ undefined, tracker // correction 4: 5th argument
+        );
+    }
+    catch (err) {
+        return {
+            inaccessible,
+            failure: `node builder threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!node) {
+        return { inaccessible, failure: 'node builder returned no type node' };
+    }
+    if (inaccessible.length > 0) {
+        return {
+            inaccessible,
+            failure: `symbols not accessible from the surface entry: ${[...new Set(inaccessible)].join(', ')}`,
+        };
+    }
+    const printer = ts.createPrinter({ removeComments: true });
+    const text = printer.printNode(ts.EmitHint.Unspecified, node, destination.getSourceFile());
+    return { text, inaccessible };
+}

package/sidecar/dist/src/capture/paths-rewrite.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Post-emit specifier rewrite pass (design doc, Capture step 3 -- REQUIRED
+ * component). Declaration emit ships tsconfig-`paths`-mapped specifiers
+ * verbatim (`@app/models/item` dangles after relocation into the stub), and
+ * node-builder-printed import types can carry absolute source paths. Both
+ * are mapped onto tree-relative specifiers here, at capture time, in the
+ * producer's own resolution context -- `paths` cannot be fixed at check time
+ * (program-global, and namespaces collide across stubs).
+ *
+ * Specifiers that map outside the emitted tree are left untouched: the
+ * per-alias self-check classifies them as dangling internals with a recorded
+ * reason, which is the honest outcome.
+ */
+import ts from 'typescript';
+import { type PathsPattern } from './specifiers.js';
+export interface RewriteArgs {
+    /** Absolute path of the stub's types/ directory. */
+    typesDir: string;
+    /** Tree-relative emitted file paths (as recorded in emitted_files, without
+     * the leading "types/"). */
+    files: string[];
+    /** The producer repo's parsed compiler options. */
+    options: ts.CompilerOptions;
+    /** Absolute path of the tsconfig the options came from. */
+    configPath: string;
+    /** Effective rootDir the emit ran with (tree layout mirrors it). */
+    entryDir: string;
+}
+export declare function parsePathsPatterns(options: ts.CompilerOptions, configPath: string): PathsPattern[];
+/**
+ * Rewrite paths-mapped and absolute-internal specifiers in every emitted
+ * file. Returns the number of specifiers rewritten.
+ */
+export declare function rewriteEmittedSpecifiers(args: RewriteArgs): number;

package/sidecar/dist/src/capture/paths-rewrite.js

@@ -0,0 +1,100 @@
+/**
+ * Post-emit specifier rewrite pass (design doc, Capture step 3 -- REQUIRED
+ * component). Declaration emit ships tsconfig-`paths`-mapped specifiers
+ * verbatim (`@app/models/item` dangles after relocation into the stub), and
+ * node-builder-printed import types can carry absolute source paths. Both
+ * are mapped onto tree-relative specifiers here, at capture time, in the
+ * producer's own resolution context -- `paths` cannot be fixed at check time
+ * (program-global, and namespaces collide across stubs).
+ *
+ * Specifiers that map outside the emitted tree are left untouched: the
+ * per-alias self-check classifies them as dangling internals with a recorded
+ * reason, which is the honest outcome.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isRelative, matchPathsPattern, rewriteSpecifiers, } from './specifiers.js';
+export function parsePathsPatterns(options, configPath) {
+    const paths = options.paths;
+    if (!paths)
+        return [];
+    // Since TS 4.1 `paths` without `baseUrl` resolves relative to the config
+    // file; the parser records that base internally as pathsBasePath.
+    const base = path.resolve(options.baseUrl ??
+        (options.pathsBasePath || path.dirname(configPath)));
+    const patterns = [];
+    for (const [pattern, targets] of Object.entries(paths)) {
+        const starIdx = pattern.indexOf('*');
+        patterns.push({
+            pattern,
+            prefix: starIdx === -1 ? pattern : pattern.slice(0, starIdx),
+            suffix: starIdx === -1 ? undefined : pattern.slice(starIdx + 1),
+            targets: targets.map((t) => path.resolve(base, t)),
+        });
+    }
+    return patterns;
+}
+/** Map an absolute source path to its tree-relative emitted file, if any. */
+function treeFileFor(absSource, entryDir, emitted) {
+    const noExt = absSource.replace(/\.(d\.ts|ts|tsx|mts|cts)$/, '');
+    const rel = path.relative(entryDir, noExt).split(path.sep).join('/');
+    if (rel.startsWith('..'))
+        return undefined;
+    for (const candidate of [`${rel}.d.ts`, `${rel}/index.d.ts`]) {
+        if (emitted.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Tree-relative .d.ts path -> extensionless specifier from `fromFile`. */
+function relativeSpecifier(fromFile, toFile) {
+    const fromDir = path.posix.dirname(fromFile);
+    let rel = path.posix.relative(fromDir, toFile.replace(/\.d\.ts$/, ''));
+    if (!rel.startsWith('.'))
+        rel = `./${rel}`;
+    return rel;
+}
+/**
+ * Rewrite paths-mapped and absolute-internal specifiers in every emitted
+ * file. Returns the number of specifiers rewritten.
+ */
+export function rewriteEmittedSpecifiers(args) {
+    const patterns = parsePathsPatterns(args.options, args.configPath);
+    const emitted = new Set(args.files);
+    let total = 0;
+    for (const file of args.files) {
+        const absFile = path.join(args.typesDir, file);
+        const text = fs.readFileSync(absFile, 'utf8');
+        const { text: rewritten, rewrites } = rewriteSpecifiers(text, (spec) => {
+            // Absolute internal paths (node-builder import types).
+            if (spec.startsWith('/')) {
+                const target = treeFileFor(spec, args.entryDir, emitted);
+                return target ? relativeSpecifier(file, target) : undefined;
+            }
+            if (isRelative(spec))
+                return undefined;
+            // tsconfig-paths patterns, first matching target that exists in-tree
+            // (mirrors the resolver's declaration-order semantics).
+            for (const pattern of patterns) {
+                const star = matchPathsPattern(spec, pattern);
+                if (star === undefined)
+                    continue;
+                for (const targetTemplate of pattern.targets) {
+                    const absTarget = targetTemplate.replace('*', star);
+                    const target = treeFileFor(absTarget, args.entryDir, emitted);
+                    if (target)
+                        return relativeSpecifier(file, target);
+                }
+                // Matched a pattern but no in-tree target: leave it for the
+                // self-check to classify (never guess).
+                return undefined;
+            }
+            return undefined;
+        });
+        if (rewrites > 0) {
+            fs.writeFileSync(absFile, rewritten);
+            total += rewrites;
+        }
+    }
+    return total;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * 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 type { CaptureAliasRecord } from './api.js';
+import type { ResolvedAnchor } from './anchors.js';
+export interface SelfCheckArgs {
+    stubDir: string;
+    surfaceAbsPath: string;
+    resolved: ResolvedAnchor[];
+    pinned: Record<string, string>;
+    bareCheckout: boolean;
+    /** Producer repo root; its node_modules (if any) backs resolution. */
+    repoRoot: string;
+}
+export declare function selfCheckStub(args: SelfCheckArgs): CaptureAliasRecord[];