carrick 0.3.104 → 0.3.106

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.104",
+  "version": "0.3.106",
   "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.104",
-    "@carrick-tools/cli-darwin-x64": "0.3.104",
-    "@carrick-tools/cli-linux-arm64": "0.3.104",
-    "@carrick-tools/cli-linux-x64": "0.3.104",
-    "@carrick-tools/cli-win32-x64": "0.3.104"
+    "@carrick-tools/cli-darwin-arm64": "0.3.106",
+    "@carrick-tools/cli-darwin-x64": "0.3.106",
+    "@carrick-tools/cli-linux-arm64": "0.3.106",
+    "@carrick-tools/cli-linux-x64": "0.3.106",
+    "@carrick-tools/cli-win32-x64": "0.3.106"
   },
   "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.104",
+  "version": "0.3.106",
   "author": {
     "name": "Carrick",
     "email": "hello@carrick.tools"

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

@@ -49,6 +49,12 @@ export interface ResolvedAnchor {
      * anchor's type holds no unresolved placeholder.
      */
     unresolved?: UnresolvedAtAnchor;
+    /**
+     * carrick#1446: set on a demotion whose alias text names a module the
+     * declaration emit skipped. The text dangles in the emitted tree, which the
+     * record states for a literal anchor, whose text is what the index serves.
+     */
+    namesUnemittedModule?: true;
 }
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export declare function entryRelativeSpecifier(entryDir: string, repoRoot: string, sourceFile: string): string;
@@ -67,6 +73,13 @@ export declare function resolveAnchor(program: ts.Program, request: CaptureAncho
      * these resolves through that module instead of dangling in the entry.
      */
     siblingSymbolSpecs?: Map<string, string>;
+    /**
+     * The file a module specifier resolves to from the surface entry, under
+     * the analysis program's own resolution (carrick#1789). A literal's name
+     * is imported through a package specifier only when the entry reaches the
+     * same module by it.
+     */
+    resolveFromEntry?: (specifier: string) => string | undefined;
 }): ResolvedAnchor;
 /**
  * Locate the target node: tightest expression covering the byte span when

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

@@ -8,6 +8,8 @@ import ts from 'typescript';
 import * as path from 'node:path';
 import { printTypeForDestination, substituteUndeclaredNames, undeclaredNamesIn, } from './node-builder.js';
 import { typeIsOrContainsMachinery } from './machinery.js';
+import { installedPackageSpecifier } from './installed-package.js';
+import { realPath } from './service-config.js';
 import { unresolvedAtAnchor, unresolvedSpecifiersReachableFrom, } from './unresolved.js';
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export function entryRelativeSpecifier(entryDir, repoRoot, sourceFile) {
@@ -56,10 +58,13 @@ export function resolveAnchor(program, request, args) {
         // sibling symbol anchor imports is resolved by that import.
         // carrick#1774: the text names types as they read where it was printed,
         // so a name its source file means by a repo module's export is imported
-        // from that module (a string-union alias printed bare read `any`).
+        // from that module (a string-union alias printed bare read `any`), and
+        // (carrick#1789) a name it imports from a package is imported from that
+        // package. carrick#1836: a name the source file cannot see is imported
+        // from the module the inference recorded it was printed for.
         const scoped = siblingSpec
             ? undefined
-            : qualifyNamesFromSource(text, program, request.source_file, args);
+            : qualifyNamesFromSource(text, program, request.source_file, request.printed_names, args);
         const scopedText = scoped ?? text;
         // carrick#1377: rewrite what nothing declares to `unknown` in place, so
         // one member typed by a module the checkout does not have stops taking
@@ -185,10 +190,33 @@ export function resolveAnchor(program, request, args) {
         }
         return finishInferAnchor(program, sourceFile, request, param, args.placeholder, undefined, args.repoRoot);
     }
-    let located = locateNode(sourceFile, request);
-    if (!located) {
+    const found = locate(sourceFile, request);
+    if (!found) {
         return demote(locatorFailureReason(request));
     }
+    // carrick#1785: the line fallback takes the first expression on the line,
+    // and a declaration's NAME is an expression to `ts.isExpression`. On a line
+    // that declares something, that name is all the fallback finds, and its type
+    // is the declared entity's own (a whole alias, a function, a class), never a
+    // payload. The line names the declaration, so the anchor abstains: an
+    // abstain, not a demotion, because the backfill has nothing better to
+    // re-anchor it with (carrick#766). It does not walk on to the next node
+    // either, which on a function's line is its first parameter.
+    if (found.by === 'line') {
+        const declaration = declarationNamedBy(found.node);
+        if (declaration) {
+            return {
+                request,
+                aliasText: 'unknown',
+                serialization: 'structural_fallback',
+                abstainReason: `the line fallback resolved the name of ` +
+                    `${describeNode(sourceFile, request.source_file, declaration)}; a ` +
+                    `declaration's name is not a payload, so the anchor abstains rather ` +
+                    `than publish the declared entity's own type`,
+            };
+        }
+    }
+    let located = found.node;
     // 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.
@@ -252,17 +280,18 @@ function finishInferAnchor(program, sourceFile, request, located, placeholder, r
     // here.
     //
     // A line alone names nothing. `firstExpressionOnLine` picks whatever comes
-    // first on the line, which on a re-export statement is the first exported
-    // binding. When THAT resolves to a top type the capture holds no payload and
-    // no type, and `export type <alias> = any;` states "a type was inferred and
-    // it collapsed" — a claim the scan cannot back. The honest word is `unknown`
-    // ("no contract stated here"), with the node the line resolved as the reason.
+    // first on the line. When THAT resolves to a top type the capture holds no
+    // payload and no type, and `export type <alias> = any;` states "a type was
+    // inferred and it collapsed" — a claim the scan cannot back. The honest word
+    // is `unknown` ("no contract stated here"), with the node the line resolved
+    // as the reason.
     //
     // Live shape: a route whose handlers are built by a framework factory and
     // re-exported at the bottom of the file. Both of the file's operations
-    // anchor at the export statement, the v1 walk abstains there (carrick#771),
-    // and the alias falls to this line-only locator, which resolves the first
-    // exported binding's identifier.
+    // anchor at the export statement and the v1 walk abstains there
+    // (carrick#771). The export line itself now abstains earlier, as a
+    // declaration's name (carrick#1785); this guard still holds for a line whose
+    // first node is a value that decayed, such as the factory call's binding.
     if (isTopType(type) && isLineOnly(request)) {
         return {
             request,
@@ -366,15 +395,25 @@ function substituteUndeclaredNamesInText(text, program, destination) {
  * member that reads `any`) or a global of the same name (`Notification`).
  * Each reference whose name the source resolves to a type that a module
  * inside the repo exports becomes `import('<module>').<export>`, with its
- * qualifier and type arguments kept. Anything else is left as written: a
- * global, a name only a function body declares, an unexported local, and a
- * type declared outside the repo or under `node_modules`, which the stub does
- * not ship.
+ * qualifier and type arguments kept. A name the source imports from an
+ * installed package becomes `import('<package specifier>').<export>`
+ * (carrick#1789): the stub ships no `node_modules`, but it pins the packages
+ * its surface imports, and the check phase installs them. Anything else is
+ * left as written: a global, a name only a function body declares, an
+ * unexported local, and a type declared outside the repo that no package
+ * import reaches.
+ *
+ * carrick#1836: a name the source file cannot see at all was printed without
+ * its scope (the inferrer's structural printer writes names bare). When the
+ * inference recorded one declaration for it (`printed`), the name is imported
+ * from that declaration's module, under the same repo rule. A name recorded
+ * for two declarations is left as written: the text no longer says which one
+ * a position meant.
  *
  * Returns the rewritten text, or undefined when nothing was rewritten, so a
  * text with no such name stays byte-identical.
  */
-function qualifyNamesFromSource(text, program, sourceFileRel, args) {
+function qualifyNamesFromSource(text, program, sourceFileRel, printed, args) {
     if (!sourceFileRel)
         return undefined;
     const source = program.getSourceFile(path.join(args.repoRoot, sourceFileRel));
@@ -391,6 +430,14 @@ function qualifyNamesFromSource(text, program, sourceFileRel, args) {
         ts.forEachChild(node, collect);
     };
     collect(parsed);
+    const specOf = (file) => {
+        const rel = path.relative(args.repoRoot, file.fileName);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+            return undefined;
+        if (rel.split(path.sep).includes('node_modules'))
+            return undefined;
+        return entryRelativeSpecifier(args.entryDir, args.repoRoot, rel.split(path.sep).join('/'));
+    };
     const imports = new Map();
     const importFor = (name) => {
         if (imports.has(name))
@@ -399,12 +446,8 @@ function qualifyNamesFromSource(text, program, sourceFileRel, args) {
         const atSource = checker.resolveName(name, source, meaning, false);
         const target = atSource && resolveSymbolAliases(checker, atSource);
         const declaringFile = target?.declarations?.[0]?.getSourceFile();
-        const rel = declaringFile && path.relative(args.repoRoot, declaringFile.fileName);
-        if (target &&
-            declaringFile &&
-            rel &&
-            !rel.startsWith('..') &&
-            !rel.split(path.sep).includes('node_modules')) {
+        const spec = declaringFile && specOf(declaringFile);
+        if (target && declaringFile && spec) {
             const moduleSymbol = checker.getSymbolAtLocation(declaringFile);
             const exported = moduleSymbol
                 ? checker
@@ -412,28 +455,46 @@ function qualifyNamesFromSource(text, program, sourceFileRel, args) {
                     .filter((candidate) => resolveSymbolAliases(checker, candidate) === target)
                 : [];
             const chosen = exported.find((candidate) => candidate.getName() === name) ?? exported[0];
-            if (chosen) {
-                found = {
-                    spec: entryRelativeSpecifier(args.entryDir, args.repoRoot, rel.split(path.sep).join('/')),
-                    exportName: chosen.getName(),
-                };
-            }
+            if (chosen)
+                found = { spec, exportPath: [chosen.getName()] };
         }
+        if (!found && atSource)
+            found = packageImportOf(program, atSource, args.resolveFromEntry);
+        if (!found && !atSource)
+            found = printedImportOf(program, name, printed, specOf);
         imports.set(name, found);
         return found;
     };
     const leftmost = (name) => ts.isIdentifier(name) ? name : leftmost(name.left);
-    const renameLeftmost = (name, to) => ts.isIdentifier(name)
-        ? ts.factory.createIdentifier(to)
-        : ts.factory.createQualifiedName(renameLeftmost(name.left, to), name.right);
+    const entityName = (parts) => parts
+        .slice(1)
+        .reduce((left, part) => ts.factory.createQualifiedName(left, part), ts.factory.createIdentifier(parts[0]));
+    const replaceLeftmost = (name, to) => ts.isIdentifier(name)
+        ? entityName(to)
+        : ts.factory.createQualifiedName(replaceLeftmost(name.left, to), name.right);
+    const dropLeftmost = (name) => ts.isIdentifier(name.left)
+        ? name.right
+        : ts.factory.createQualifiedName(dropLeftmost(name.left), name.right);
+    // What follows `import('<spec>')`: the export path, then the reference's
+    // own qualifier. Through a namespace import the namespace's name goes, and
+    // the next name must be something the package exports.
+    const qualifierFor = (typeName, target) => {
+        if ('exportPath' in target)
+            return replaceLeftmost(typeName, target.exportPath);
+        if (ts.isIdentifier(typeName))
+            return undefined;
+        const qualifier = dropLeftmost(typeName);
+        return target.namespaceExports.has(leftmost(qualifier).text) ? qualifier : undefined;
+    };
     let rewrites = 0;
     const rewrite = (node) => {
         if (ts.isTypeReferenceNode(node)) {
             const name = leftmost(node.typeName).text;
             const target = typeParameters.has(name) ? undefined : importFor(name);
-            if (target) {
+            const qualifier = target && qualifierFor(node.typeName, target);
+            if (target && qualifier) {
                 rewrites += 1;
-                return ts.factory.createImportTypeNode(ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(target.spec)), undefined, renameLeftmost(node.typeName, target.exportName), node.typeArguments?.map((argument) => rewrite(argument)), false);
+                return ts.factory.createImportTypeNode(ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(target.spec)), undefined, qualifier, node.typeArguments?.map((argument) => rewrite(argument)), false);
             }
         }
         return ts.visitEachChild(node, rewrite, /* context */ undefined);
@@ -445,6 +506,96 @@ function qualifyNamesFromSource(text, program, sourceFileRel, args) {
         .createPrinter({ removeComments: true })
         .printNode(ts.EmitHint.Unspecified, rewritten, parsed.getSourceFile());
 }
+/**
+ * carrick#1789: how the surface entry imports `local`, a name the source file
+ * binds with an import from an installed package, or undefined.
+ *
+ * The entry names the module the source's import resolves to by its file
+ * path, as the node builder names a library type it cannot reach by a bare
+ * specifier; the post-emit rewrite turns that path into the package's bare
+ * specifier and pins the installed version (`installedPackageSpecifier`). A
+ * bare specifier in the entry itself would be resolved from the entry: on a
+ * Deno service that goes through the graph's virtual `node_modules`, and the
+ * emitter then reads the package there, cannot name its types from the
+ * service's own modules (TS2742), and skips their declarations.
+ *
+ * Kept only when the module lies inside an installed package and the bare
+ * specifier that package gives resolves from the entry to the same file. So
+ * a tsconfig path alias to the repo's own module, a workspace package linked
+ * from the repo (no installed copy to pin), and an import of another
+ * installed copy than the entry reaches all stay as written.
+ */
+function packageImportOf(program, local, resolveFromEntry) {
+    if (!resolveFromEntry || !(local.flags & ts.SymbolFlags.Alias))
+        return undefined;
+    const declaration = local.declarations?.[0];
+    let statement;
+    let exportName;
+    if (declaration && ts.isImportSpecifier(declaration)) {
+        // `import { "a-b" as name }` has no qualifier an import type can write.
+        const exported = declaration.propertyName ?? declaration.name;
+        if (!ts.isIdentifier(exported))
+            return undefined;
+        statement = declaration.parent.parent.parent;
+        exportName = exported.text;
+    }
+    else if (declaration && ts.isImportClause(declaration)) {
+        statement = declaration.parent;
+        exportName = 'default';
+    }
+    else if (declaration && ts.isNamespaceImport(declaration)) {
+        statement = declaration.parent.parent;
+    }
+    else {
+        return undefined;
+    }
+    if (!ts.isImportDeclaration(statement))
+        return undefined;
+    const checker = program.getTypeChecker();
+    const moduleSymbol = checker.getSymbolAtLocation(statement.moduleSpecifier);
+    const moduleFile = moduleSymbol?.declarations?.find(ts.isSourceFile);
+    if (!moduleSymbol || !moduleFile)
+        return undefined;
+    const installed = installedPackageSpecifier(moduleFile.fileName, exportName);
+    const fromEntry = installed && resolveFromEntry(installed.specifier);
+    if (!fromEntry || realPath(fromEntry) !== realPath(moduleFile.fileName))
+        return undefined;
+    const spec = moduleFile.fileName;
+    const exported = new Set(checker.getExportsOfModule(moduleSymbol).map((symbol) => symbol.getName()));
+    if (exportName === undefined)
+        return { spec, namespaceExports: exported };
+    return exported.has(exportName) ? { spec, exportPath: [exportName] } : undefined;
+}
+/**
+ * carrick#1836: the import for `name` from the one declaration the inference
+ * recorded printing it for, or undefined.
+ *
+ * Undefined when the name was recorded for no declaration or for several,
+ * when the recorded module is not in this program or not inside the repo
+ * (`specOf`), and when its export path does not lead to a type there: a record
+ * that does not check out names nothing, and the text stays as written.
+ */
+function printedImportOf(program, name, printed, specOf) {
+    const recorded = (printed ?? []).filter((entry) => entry.name === name);
+    const identities = new Set(recorded.map((entry) => `${entry.file}\0${entry.export_path.join('.')}`));
+    if (identities.size !== 1)
+        return undefined;
+    const entry = recorded[0];
+    const declaring = program.getSourceFile(entry.file);
+    const spec = declaring && specOf(declaring);
+    if (!declaring || !spec)
+        return undefined;
+    const checker = program.getTypeChecker();
+    let current = checker.getSymbolAtLocation(declaring);
+    for (const part of entry.export_path) {
+        const next = current && checker.getExportsOfModule(current).find((s) => s.getName() === part);
+        current = next && resolveSymbolAliases(checker, next);
+    }
+    if (!current || !(current.flags & (ts.SymbolFlags.Type | ts.SymbolFlags.Namespace))) {
+        return undefined;
+    }
+    return { spec, exportPath: entry.export_path };
+}
 /** The type node of `type __LiteralAnchor = <text>;`, or undefined. */
 function parseLiteralAnchor(text) {
     const parsed = ts.createSourceFile('literal-anchor.ts', `type __LiteralAnchor = ${text};`, ts.ScriptTarget.Latest, true);
@@ -914,21 +1065,62 @@ function locatorFailureReason(request) {
  * else the first expression starting on line_number.
  */
 export function locateNode(sourceFile, request) {
+    return locate(sourceFile, request)?.node;
+}
+/** The node `locateNode` resolves, and which of its three locators found it. */
+function locate(sourceFile, request) {
     if (request.span_start !== undefined && request.span_end !== undefined) {
         const bySpan = tightestCoveringNode(sourceFile, request.span_start, request.span_end);
         if (bySpan)
-            return bySpan;
+            return { node: bySpan, by: 'span' };
     }
     if (request.expression_text) {
         const byText = nodeByExpressionText(sourceFile, request.expression_text, request.line_number);
         if (byText)
-            return byText;
+            return { node: byText, by: 'text' };
     }
     if (request.line_number !== undefined) {
-        return firstExpressionOnLine(sourceFile, request.line_number);
+        const byLine = firstExpressionOnLine(sourceFile, request.line_number);
+        if (byLine)
+            return { node: byLine, by: 'line' };
     }
     return undefined;
 }
+/**
+ * The declaration `node` is the name of, when it names one (carrick#1785): a
+ * type alias, interface, class, function, method, property, accessor, enum or
+ * enum member, namespace, or an import or export binding (whose `propertyName`
+ * names the binding too: `export { a as b }`).
+ *
+ * Not a binding whose name is also the value read at that position: a
+ * destructured element and a shorthand property keep resolving. A variable,
+ * a parameter and a property assignment never reach here, because each is a
+ * preferred target the line walk takes before its name.
+ */
+function declarationNamedBy(node) {
+    const parent = node.parent;
+    if (!parent)
+        return undefined;
+    // A specifier's only children are its names.
+    if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent))
+        return parent;
+    const named = ts.isTypeAliasDeclaration(parent) ||
+        ts.isInterfaceDeclaration(parent) ||
+        ts.isClassDeclaration(parent) ||
+        ts.isFunctionDeclaration(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isGetAccessorDeclaration(parent) ||
+        ts.isSetAccessorDeclaration(parent) ||
+        ts.isEnumDeclaration(parent) ||
+        ts.isEnumMember(parent) ||
+        ts.isModuleDeclaration(parent) ||
+        ts.isImportClause(parent) ||
+        ts.isNamespaceImport(parent);
+    return named && parent.name === node ? parent : undefined;
+}
 function isPreferredTarget(node) {
     return (ts.isExpression(node) ||
         ts.isVariableDeclaration(node) ||

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

@@ -71,6 +71,36 @@ export interface LiteralAnchorRequest {
      * record's `source_file` stays `<inline>`: the answer is still the text.
      */
     source_file?: string;
+    /**
+     * carrick#1836: what the text's bare names meant where they were printed,
+     * for the names `source_file` cannot resolve. A name listed once is
+     * imported from the module that declares it; a name listed for two
+     * declarations is left as written.
+     */
+    printed_names?: PrintedName[];
+    /**
+     * carrick#1842: the text is a body the call site reads as raw text. Copied
+     * onto the alias's record, where the check phase reads it.
+     */
+    raw_text_read?: true;
+}
+/**
+ * The declaration a bare name in printed type text meant (carrick#1836).
+ *
+ * The v1 inferrer prints some types with no enclosing declaration, and that
+ * print writes every named type by its bare name, whether or not the file the
+ * request names can see it. The compiler knew the symbol when it printed the
+ * name; this is that symbol, recorded as the module that declares it and the
+ * export path that reaches it there (`['Status']`, or `['Billing', 'Kind']`
+ * for a namespace member printed as `Kind`).
+ */
+export interface PrintedName {
+    /** The name as the text prints it: the leftmost part of a reference. */
+    name: string;
+    /** Absolute path of the module that declares it. */
+    file: string;
+    /** Export names from that module down to the declaration. */
+    export_path: string[];
 }
 /**
  * Addressable handler: `export type A = Awaited<ReturnType<typeof
@@ -152,7 +182,10 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  *    contract.
  *  - `machinery_envelope`: the return resolved to transport (a
  *    Response/Request-shaped envelope) and no payload was recoverable inside
- *    it or from the handler's returned arguments.
+ *    it or from the handler's returned arguments. On a consumer call result it
+ *    is a decided abstain: what the call's result carrier holds is transport
+ *    the service's wrapper rules verify and read no payload out of, such as a
+ *    request library's own response object (carrick#1841).
  *  - `coerced_input`: a request schema's INPUT is `any`/`unknown` at this
  *    position while its parsed output is concrete, which is what a coercion
  *    declares (carrick#1101). The published type carries the output there, so
@@ -251,6 +284,34 @@ export interface CaptureAliasRecord {
      * absent when there are none.
      */
     undeclared_names?: string[];
+    /**
+     * Every position at which this alias's type, as the emitted tree states it,
+     * holds TypeScript's unresolved-reference placeholder (carrick#1446): `''`
+     * when the alias's own type does not resolve, member paths otherwise, in the
+     * deep walk's notation, sorted by path. The compiler prints the placeholder
+     * as the name it could not follow, so the text reads like a type while every
+     * reader of the tree reads `any` there.
+     *
+     * Read on the self-check program, where the producer's installed packages
+     * resolve, so a name only a missing install leaves unresolved is listed only
+     * on a bare checkout. A literal anchor demoted because its text names a
+     * module the emit skipped is listed at its root: that text is what the
+     * index serves for it, and it names a module the tree does not hold.
+     *
+     * Kept apart from `any_provenance` on purpose: the check phase pre-gates
+     * on `any_provenance[0]`, and this list is what the index tells a reader,
+     * not a verdict. The scanner joins it onto the manifest entry beside the
+     * entry's other provenance. Absent when every position resolves.
+     */
+    unresolved_in_tree?: TypeProvenance[];
+    /**
+     * carrick#1842: the alias is a body its call site reads as raw text, from
+     * the literal anchor that published it. The check phase reads a pair with
+     * this on either side unverifiable: raw text states no structural contract,
+     * whether or not the other side's type assigns to `string`. Absent
+     * otherwise, and absent on every record a release before this one stored.
+     */
+    raw_text_read?: true;
 }
 /** Aggregate fidelity metric, emitted per capture (one service). */
 export interface CaptureFidelity {
@@ -295,7 +356,8 @@ export interface CaptureStubOptions {
     /**
      * The scanned repo's root, the upper bound of the search for a tsconfig
      * above `repoRoot` when none is named (carrick#1776). Without it only
-     * `repoRoot` is searched.
+     * `repoRoot` is searched. It is a protected tree as well: `outDir` may
+     * lie inside it only beneath a `.carrick` directory (carrick#1768).
      */
     scanRoot?: string;
 }
@@ -431,8 +493,6 @@ export interface CheckResult {
      * missing (soundness over availability — pinned design, Check step 2). */
     isolation: 'pnpm' | 'unavailable';
     install_ok: boolean;
-    /** Scrubbed install-failure summary when install_ok is false. */
-    install_error?: string;
     ts_version: string;
     /** Verdicts, sorted by pair_id for byte-stable output. */
     verdicts: CheckVerdict[];

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

@@ -12,6 +12,8 @@
  *   IsUnknown/IsNever gate fired (TS2344) -> unverifiable
  *   IsVoid gate fired (TS2344)            -> unverifiable (no body read)
  *   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-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *
@@ -22,7 +24,7 @@
  * Seam: node builtins + this bundle only.
  */
 import type { CheckVerdict } from './api.js';
-import { type ProbePlan } from './check-probe.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 PairFieldReport } from './check-fields.js';
@@ -64,6 +66,13 @@ export interface ClassifyInput {
      * run, in which case the tsc text stands alone.
      */
     fieldReport?: PairFieldReport;
+    /**
+     * 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
+     * type: a text read publishes `string`, which no type gate can tell from a
+     * JSON body that is a string.
+     */
+    rawTextSide?: Side;
 }
 /** Classify one pair into exactly one bucket, honouring the precedence order. */
 export declare function classifyPair(input: ClassifyInput): CheckVerdict;

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

@@ -12,6 +12,8 @@
  *   IsUnknown/IsNever gate fired (TS2344) -> unverifiable
  *   IsVoid gate fired (TS2344)            -> unverifiable (no body read)
  *   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-class error                -> incompatible
  *   no diagnostics                        -> compatible     [lowest precedence]
  *
@@ -172,19 +174,18 @@ export function classifyPair(input) {
         };
     }
     // 4c. A body of bytes (carrick#1793): a blob, a buffer or a stream has no JSON
-    //     shape, so a MISMATCH between the containers two sides hold the bytes
-    //     in (a `Uint8Array` sent, read with `.blob()`) is not a drift. It
-    //     overrides a mismatch only: bytes that assign to bytes (a stream sent
-    //     where a stream is read) agree, and that verdict stands. When both
-    //     sides are bytes the sent side is named, whatever order the
-    //     diagnostics came in.
+    //     shape, and the check cannot read a file's content. So a pair with
+    //     bytes on either side states no contract, whether the two sides
+    //     mismatch (a `Uint8Array` sent, read with `.blob()`) or agree (a stream
+    //     sent where a stream is read, carrick#1812). When both sides are bytes
+    //     the sent side is named, whatever order the diagnostics came in.
     const firedGates = new Set(gateDiags.map((d) => plan.gateLines.get(d.line)));
     const bytesGate = firedGates.has('sent:bytes')
         ? 'sent:bytes'
         : firedGates.has('expected:bytes')
             ? 'expected:bytes'
             : undefined;
-    const bytesVerdict = () => {
+    if (bytesGate) {
         const { side } = sideForGate(bytesGate, plan);
         return {
             ...base,
@@ -193,7 +194,21 @@ export function classifyPair(input) {
             diagnostic: `the ${side} body is bytes (a blob, a buffer or a stream), which has no JSON shape to compare with the other side.`,
             ...notAFact(`the ${side} body is bytes`, side),
         };
-    };
+    }
+    // 4d. A body read as raw text (carrick#1842): a `.text()` read, or a request
+    //     library's text format, takes the body unparsed, so `string` there
+    //     states no structural contract. Like bytes, the pair is not compared,
+    //     whether or not the other side's type assigns to `string`.
+    if (input.rawTextSide && plan.spec.protocol === 'http') {
+        const side = input.rawTextSide;
+        return {
+            ...base,
+            bucket: 'unverifiable',
+            gate: `${side}:text`,
+            diagnostic: `the ${side} reads the body as raw text, which has no JSON shape to compare with the other side.`,
+            ...notAFact(`the ${side} reads the body as raw text`, side),
+        };
+    }
     // 5. Assignment-class error on the DECISIVE assignment line -> incompatible.
     //
     // On an `http` pair that line is the JSON wire assignment, not the declared
@@ -206,8 +221,6 @@ export function classifyPair(input) {
     const decisiveLine = decisiveAssignmentLine(plan);
     const assignDiag = probeDiags.find((d) => d.line === decisiveLine && ASSIGNMENT_CODES.has(d.code));
     if (assignDiag) {
-        if (bytesGate)
-            return bytesVerdict();
         const text = scrubDiagnostic(assignDiag.message, scrubCtx, plan.sentEndpoint.alias, plan.expectedEndpoint.alias);
         return {
             ...base,
@@ -243,8 +256,6 @@ export function classifyPair(input) {
     if (wireOther) {
         const declaredMismatch = probeDiags.find((d) => d.line === plan.assignmentLine && ASSIGNMENT_CODES.has(d.code));
         if (declaredMismatch) {
-            if (bytesGate)
-                return bytesVerdict();
             return {
                 ...base,
                 bucket: 'incompatible',