carrick 0.3.101 → 0.3.103

package/package.json

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

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

@@ -1,27 +1,9 @@
 /**
- * Surface Emitter - Emits .d.ts surface files with rewritten module specifiers
- *
- * This module replaces the previous dts-bundle-generator approach with a
- * ts-morph-based AST transformation and emission pipeline.
- *
- * Key features:
- * - Does NOT bundle dependencies (unlike dts-bundle-generator)
- * - Rewrites module specifiers to repo-specific aliases (@carrick/{repoName}/{spec})
- * - Handles ImportDeclaration, ImportTypeNode, and ExportDeclaration
- * - Supports scoped packages and subpaths
- * - Includes a safety pass for any compiler-introduced raw specifiers
+ * TypeBundler - the `bundle` action: each requested symbol's declaration text,
+ * read from the init'd ts-morph project.
  */
 import { Project } from 'ts-morph';
-import type { PayloadDefinition, SurfaceEmitResult, SymbolRequest, BundleResult } from './types.js';
-/**
- * Options for SurfaceEmitter construction
- */
-export interface SurfaceEmitterOptions {
-    /** The ts-morph Project instance */
-    project: Project;
-    /** The repository root directory (absolute path) */
-    repoRoot: string;
-}
+import type { SymbolRequest, BundleResult } from './types.js';
 /**
  * Options for TypeBundler construction (legacy)
  */
@@ -31,82 +13,11 @@ export interface TypeBundlerOptions {
     /** The repository root directory (absolute path) */
     repoRoot: string;
 }
-/**
- * SurfaceEmitter - Generates .d.ts surface files with rewritten imports
- *
- * Usage:
- *   const emitter = new SurfaceEmitter({ project, repoRoot });
- *   const result = emitter.emit(repoName, payloads, outputPath);
- */
-export declare class SurfaceEmitter {
-    private readonly project;
-    private readonly repoRoot;
-    constructor(options: SurfaceEmitterOptions);
-    /**
-     * Emit a surface .d.ts file containing payload type declarations
-     *
-     * @param repoName - Repository name for specifier rewriting
-     * @param payloads - Payload definitions to include
-     * @param outputPath - Path to write the surface file
-     * @returns SurfaceEmitResult
-     */
-    emit(repoName: string, payloads: PayloadDefinition[], outputPath: string): SurfaceEmitResult;
-    /**
-     * Extract potential import references from a type string.
-     * These are module specifiers that might need rewriting.
-     */
-    private extractImportReferences;
-    /**
-     * Rewrite all module specifiers in a source file to use repo-scoped aliases.
-     *
-     * Targets:
-     * 1. ImportDeclaration.moduleSpecifier
-     * 2. ImportTypeNode argument (import("..."))
-     * 3. ExportDeclaration.moduleSpecifier
-     *
-     * @returns Array of rewritten specifiers
-     */
-    private rewriteModuleSpecifiers;
-    /**
-     * Determine if a module specifier should be rewritten.
-     * Only non-relative specifiers should be rewritten.
-     */
-    private shouldRewriteSpecifier;
-    /**
-     * Rewrite a module specifier to the repo-scoped format.
-     *
-     * Format: @carrick/{repoName}/{originalSpecifier}
-     *
-     * Preserves:
-     * - Scoped packages: "@scope/pkg" → "@carrick/repo-a/@scope/pkg"
-     * - Subpaths: "zod/lib/helpers" → "@carrick/repo-a/zod/lib/helpers"
-     * - Combined: "@scope/pkg/subpath" → "@carrick/repo-a/@scope/pkg/subpath"
-     */
-    private rewriteSpecifier;
-    /**
-     * Safety pass: Scan emitted content for any raw specifiers that might have
-     * been introduced by the TypeScript compiler and rewrite them.
-     *
-     * This catches edge cases where the compiler emits types with their original
-     * module specifiers that weren't caught by AST traversal.
-     */
-    private safetyRewritePass;
-    /**
-     * Log a message to stderr
-     */
-    private log;
-    /**
-     * Log an error to stderr
-     */
-    private logError;
-}
 /**
  * TypeBundler - Legacy bundler using simpler approach
  *
  * This is a simplified replacement that doesn't use dts-bundle-generator.
  * It extracts type definitions directly using ts-morph.
- *
- * @deprecated Use SurfaceEmitter instead for the new architecture
  */
 export declare class TypeBundler {
     private readonly project;

package/sidecar/dist/src/bundler.js

@@ -1,20 +1,12 @@
 /**
- * Surface Emitter - Emits .d.ts surface files with rewritten module specifiers
- *
- * This module replaces the previous dts-bundle-generator approach with a
- * ts-morph-based AST transformation and emission pipeline.
- *
- * Key features:
- * - Does NOT bundle dependencies (unlike dts-bundle-generator)
- * - Rewrites module specifiers to repo-specific aliases (@carrick/{repoName}/{spec})
- * - Handles ImportDeclaration, ImportTypeNode, and ExportDeclaration
- * - Supports scoped packages and subpaths
- * - Includes a safety pass for any compiler-introduced raw specifiers
+ * TypeBundler - the `bundle` action: each requested symbol's declaration text,
+ * read from the init'd ts-morph project.
  */
 import { Node, ts, } from 'ts-morph';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { expandTypeStructural, } from './type-structural-expander.js';
+import { externalImportsOf } from './origin.js';
 /**
  * #248: upper bound on `SymbolRequest.array_depth`. SDL list nesting is
  * realistically 1-3 levels (`[Order!]!`, at most `[[Order!]!]!`); this is a
@@ -116,267 +108,14 @@ function declarationSite(sourceFile, name, label) {
     }
     return { reason: `Symbol '${name}' not found in ${label}` };
 }
-/**
- * SurfaceEmitter - Generates .d.ts surface files with rewritten imports
- *
- * Usage:
- *   const emitter = new SurfaceEmitter({ project, repoRoot });
- *   const result = emitter.emit(repoName, payloads, outputPath);
- */
-export class SurfaceEmitter {
-    project;
-    repoRoot;
-    constructor(options) {
-        this.project = options.project;
-        this.repoRoot = options.repoRoot;
-    }
-    /**
-     * Emit a surface .d.ts file containing payload type declarations
-     *
-     * @param repoName - Repository name for specifier rewriting
-     * @param payloads - Payload definitions to include
-     * @param outputPath - Path to write the surface file
-     * @returns SurfaceEmitResult
-     */
-    emit(repoName, payloads, outputPath) {
-        const errors = [];
-        const manifest = [];
-        try {
-            // Phase 1: Generate surface content as a string
-            const surfaceLines = [
-                '// Generated surface file for type compatibility checking',
-                '// Do not edit - this file is auto-generated by Carrick',
-                '',
-            ];
-            // Collect all import specifiers we need to track for rewriting
-            const importSpecifiers = new Set();
-            // Phase 2: Add payload type declarations
-            for (const payload of payloads) {
-                const { alias, type_string, source_file } = payload;
-                // Analyze type string for import references
-                const detectedImports = this.extractImportReferences(type_string);
-                for (const imp of detectedImports) {
-                    importSpecifiers.add(imp);
-                }
-                // Add type alias declaration
-                surfaceLines.push(`export type ${alias} = ${type_string};`);
-                surfaceLines.push('');
-                manifest.push({
-                    alias,
-                    type_string,
-                    rewritten_imports: [],
-                });
-            }
-            // Phase 3: Create a temporary source file for AST manipulation
-            const tempFileName = `__carrick_surface_${repoName}_${Date.now()}.d.ts`;
-            const tempFilePath = path.join(this.repoRoot, tempFileName);
-            const initialContent = surfaceLines.join('\n');
-            const tempSourceFile = this.project.createSourceFile(tempFilePath, initialContent, { overwrite: true });
-            // Phase 4: Rewrite module specifiers in the AST
-            const rewrittenImports = this.rewriteModuleSpecifiers(tempSourceFile, repoName);
-            // Update manifest with rewritten imports
-            for (const entry of manifest) {
-                entry.rewritten_imports = rewrittenImports;
-            }
-            // Phase 5: Get the transformed content
-            let surfaceContent = tempSourceFile.getFullText();
-            // Phase 6: Safety pass - catch any raw specifiers the compiler might have added
-            surfaceContent = this.safetyRewritePass(surfaceContent, repoName);
-            // Phase 7: Clean up temporary source file from project
-            this.project.removeSourceFile(tempSourceFile);
-            // Phase 8: Write output file
-            const absoluteOutputPath = path.isAbsolute(outputPath)
-                ? outputPath
-                : path.join(this.repoRoot, outputPath);
-            // Ensure directory exists
-            const outputDir = path.dirname(absoluteOutputPath);
-            if (!fs.existsSync(outputDir)) {
-                fs.mkdirSync(outputDir, { recursive: true });
-            }
-            fs.writeFileSync(absoluteOutputPath, surfaceContent, 'utf-8');
-            this.log(`Emitted surface file: ${absoluteOutputPath}`);
-            return {
-                success: true,
-                surface_content: surfaceContent,
-                output_path: absoluteOutputPath,
-                manifest,
-            };
-        }
-        catch (err) {
-            const error = err instanceof Error ? err.message : String(err);
-            this.logError(`Surface emission failed: ${error}`);
-            errors.push(error);
-            return {
-                success: false,
-                errors,
-            };
-        }
-    }
-    /**
-     * Extract potential import references from a type string.
-     * These are module specifiers that might need rewriting.
-     */
-    extractImportReferences(typeString) {
-        const imports = [];
-        // Match import("...") syntax
-        const importTypeRegex = /import\s*\(\s*["']([^"']+)["']\s*\)/g;
-        let match;
-        while ((match = importTypeRegex.exec(typeString)) !== null) {
-            imports.push(match[1]);
-        }
-        // Match from "..." syntax (in case of inline imports)
-        const fromRegex = /from\s+["']([^"']+)["']/g;
-        while ((match = fromRegex.exec(typeString)) !== null) {
-            imports.push(match[1]);
-        }
-        return imports;
-    }
-    /**
-     * Rewrite all module specifiers in a source file to use repo-scoped aliases.
-     *
-     * Targets:
-     * 1. ImportDeclaration.moduleSpecifier
-     * 2. ImportTypeNode argument (import("..."))
-     * 3. ExportDeclaration.moduleSpecifier
-     *
-     * @returns Array of rewritten specifiers
-     */
-    rewriteModuleSpecifiers(sourceFile, repoName) {
-        const rewrittenSpecifiers = [];
-        // 1. Rewrite ImportDeclaration specifiers
-        const importDecls = sourceFile.getImportDeclarations();
-        for (const importDecl of importDecls) {
-            const specifier = importDecl.getModuleSpecifierValue();
-            if (this.shouldRewriteSpecifier(specifier)) {
-                const newSpecifier = this.rewriteSpecifier(specifier, repoName);
-                importDecl.setModuleSpecifier(newSpecifier);
-                rewrittenSpecifiers.push(`${specifier} → ${newSpecifier}`);
-            }
-        }
-        // 2. Rewrite ExportDeclaration specifiers
-        const exportDecls = sourceFile.getExportDeclarations();
-        for (const exportDecl of exportDecls) {
-            const specifier = exportDecl.getModuleSpecifierValue();
-            if (specifier && this.shouldRewriteSpecifier(specifier)) {
-                const newSpecifier = this.rewriteSpecifier(specifier, repoName);
-                exportDecl.setModuleSpecifier(newSpecifier);
-                rewrittenSpecifiers.push(`${specifier} → ${newSpecifier}`);
-            }
-        }
-        // 3. Rewrite ImportTypeNode arguments
-        // These appear in type positions: import("module").Type
-        sourceFile.forEachDescendant((node) => {
-            if (Node.isImportTypeNode(node)) {
-                const arg = node.getArgument();
-                if (Node.isLiteralTypeNode(arg)) {
-                    const literal = arg.getLiteral();
-                    if (Node.isStringLiteral(literal)) {
-                        const specifier = literal.getLiteralValue();
-                        if (this.shouldRewriteSpecifier(specifier)) {
-                            const newSpecifier = this.rewriteSpecifier(specifier, repoName);
-                            literal.setLiteralValue(newSpecifier);
-                            rewrittenSpecifiers.push(`${specifier} → ${newSpecifier}`);
-                        }
-                    }
-                }
-            }
-        });
-        return rewrittenSpecifiers;
-    }
-    /**
-     * Determine if a module specifier should be rewritten.
-     * Only non-relative specifiers should be rewritten.
-     */
-    shouldRewriteSpecifier(specifier) {
-        // Don't rewrite relative imports
-        if (specifier.startsWith('./') || specifier.startsWith('../')) {
-            return false;
-        }
-        // Don't rewrite already-rewritten specifiers
-        if (specifier.startsWith('@carrick/')) {
-            return false;
-        }
-        // Don't rewrite node built-ins
-        if (specifier.startsWith('node:')) {
-            return false;
-        }
-        // Some common node built-ins without prefix
-        const nodeBuiltins = [
-            'fs', 'path', 'os', 'util', 'events', 'stream', 'http', 'https',
-            'url', 'querystring', 'crypto', 'buffer', 'child_process', 'cluster',
-            'dgram', 'dns', 'net', 'readline', 'tls', 'tty', 'zlib', 'assert',
-            'async_hooks', 'console', 'constants', 'domain', 'inspector', 'module',
-            'perf_hooks', 'process', 'punycode', 'string_decoder', 'timers',
-            'trace_events', 'v8', 'vm', 'worker_threads'
-        ];
-        if (nodeBuiltins.includes(specifier) || nodeBuiltins.includes(specifier.split('/')[0])) {
-            return false;
-        }
-        return true;
-    }
-    /**
-     * Rewrite a module specifier to the repo-scoped format.
-     *
-     * Format: @carrick/{repoName}/{originalSpecifier}
-     *
-     * Preserves:
-     * - Scoped packages: "@scope/pkg" → "@carrick/repo-a/@scope/pkg"
-     * - Subpaths: "zod/lib/helpers" → "@carrick/repo-a/zod/lib/helpers"
-     * - Combined: "@scope/pkg/subpath" → "@carrick/repo-a/@scope/pkg/subpath"
-     */
-    rewriteSpecifier(specifier, repoName) {
-        return `@carrick/${repoName}/${specifier}`;
-    }
-    /**
-     * Safety pass: Scan emitted content for any raw specifiers that might have
-     * been introduced by the TypeScript compiler and rewrite them.
-     *
-     * This catches edge cases where the compiler emits types with their original
-     * module specifiers that weren't caught by AST traversal.
-     */
-    safetyRewritePass(content, repoName) {
-        // Common patterns to catch:
-        // - from "package"
-        // - import("package")
-        // - export * from "package"
-        // We need to be careful not to double-rewrite @carrick/ specifiers
-        // Pattern for import("...") that's not already @carrick
-        const importTypePattern = /import\s*\(\s*["'](?!@carrick\/|\.\.?\/|node:)([^"']+)["']\s*\)/g;
-        content = content.replace(importTypePattern, (match, specifier) => {
-            const newSpecifier = this.rewriteSpecifier(specifier, repoName);
-            return match.replace(`"${specifier}"`, `"${newSpecifier}"`).replace(`'${specifier}'`, `'${newSpecifier}'`);
-        });
-        // Pattern for from "..." that's not already @carrick
-        const fromPattern = /from\s+["'](?!@carrick\/|\.\.?\/|node:)([^"']+)["']/g;
-        content = content.replace(fromPattern, (match, specifier) => {
-            const newSpecifier = this.rewriteSpecifier(specifier, repoName);
-            return match.replace(`"${specifier}"`, `"${newSpecifier}"`).replace(`'${specifier}'`, `'${newSpecifier}'`);
-        });
-        return content;
-    }
-    /**
-     * Log a message to stderr
-     */
-    log(message) {
-        console.error(`[sidecar:surface-emitter] ${message}`);
-    }
-    /**
-     * Log an error to stderr
-     */
-    logError(message) {
-        console.error(`[sidecar:surface-emitter:error] ${message}`);
-    }
-}
 // =============================================================================
-// Legacy TypeBundler (kept for backwards compatibility during migration)
+// TypeBundler
 // =============================================================================
 /**
  * TypeBundler - Legacy bundler using simpler approach
  *
  * This is a simplified replacement that doesn't use dts-bundle-generator.
  * It extracts type definitions directly using ts-morph.
- *
- * @deprecated Use SurfaceEmitter instead for the new architecture
  */
 export class TypeBundler {
     project;
@@ -558,6 +297,7 @@ export class TypeBundler {
         return {
             program: this.project.getProgram().compilerObject,
             repoRoot: this.repoRoot,
+            imports: externalImportsOf(this.project),
         };
     }
     extractTypeDefinition(symbol) {

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

@@ -54,13 +54,20 @@ export function resolveAnchor(program, request, args) {
         // (a generated model that was never generated). The stub then self-checks
         // such a name as an error placeholder, which no walk flags. A name a
         // sibling symbol anchor imports is resolved by that import.
+        // 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`).
+        const scoped = siblingSpec
+            ? undefined
+            : qualifyNamesFromSource(text, program, request.source_file, 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
         // every member around it down with it.
         const rewritten = siblingSpec || !args.placeholder
             ? undefined
-            : substituteUndeclaredNamesInText(text, program, args.placeholder);
-        const aliasBody = rewritten?.text ?? text;
+            : substituteUndeclaredNamesInText(scopedText, program, args.placeholder);
+        const aliasBody = rewritten?.text ?? scopedText;
         const undeclaredNames = siblingSpec || !args.placeholder
             ? []
             : undeclaredNamesInText(aliasBody, program, args.placeholder);
@@ -349,6 +356,95 @@ function substituteUndeclaredNamesInText(text, program, destination) {
         paths: rewritten.substitutions.map((entry) => entry.path),
     };
 }
+/**
+ * carrick#1774: literal text with every type name read where it was printed.
+ *
+ * The text was printed in `sourceFileRel` (the v1 inferrer prints at the node,
+ * where the module's own declarations and imports are in scope), so a type
+ * reference in it means what its leftmost name resolves to in that file. The
+ * surface entry is another scope: there such a name names nothing (TS2304, a
+ * 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.
+ *
+ * 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) {
+    if (!sourceFileRel)
+        return undefined;
+    const source = program.getSourceFile(path.join(args.repoRoot, sourceFileRel));
+    const parsed = parseLiteralAnchor(text);
+    if (!source || !parsed)
+        return undefined;
+    const checker = program.getTypeChecker();
+    const meaning = ts.SymbolFlags.Type | ts.SymbolFlags.Namespace | ts.SymbolFlags.Alias;
+    // Names the text declares itself (`[K in ...]`, `<T>(...)`, `infer U`).
+    const typeParameters = new Set();
+    const collect = (node) => {
+        if (ts.isTypeParameterDeclaration(node))
+            typeParameters.add(node.name.text);
+        ts.forEachChild(node, collect);
+    };
+    collect(parsed);
+    const imports = new Map();
+    const importFor = (name) => {
+        if (imports.has(name))
+            return imports.get(name);
+        let found;
+        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 moduleSymbol = checker.getSymbolAtLocation(declaringFile);
+            const exported = moduleSymbol
+                ? checker
+                    .getExportsOfModule(moduleSymbol)
+                    .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(),
+                };
+            }
+        }
+        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);
+    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) {
+                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.visitEachChild(node, rewrite, /* context */ undefined);
+    };
+    const rewritten = rewrite(parsed);
+    if (rewrites === 0)
+        return undefined;
+    return ts
+        .createPrinter({ removeComments: true })
+        .printNode(ts.EmitHint.Unspecified, rewritten, parsed.getSourceFile());
+}
 /** 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);
@@ -839,17 +935,26 @@ function isPreferredTarget(node) {
         ts.isParameter(node) ||
         ts.isPropertyAssignment(node));
 }
+/**
+ * The deepest node a span names: a value-space target covering it, or a TYPE
+ * node it covers exactly (carrick#1775). A span is the scanner naming a node,
+ * and a declared type is named by its type node: the property type a generated
+ * GraphQL document declaration states for a field sits inside a type alias,
+ * where no value-space node covers it. Exactness keeps a span that names no
+ * node from being read as whatever type happens to enclose it.
+ */
 function tightestCoveringNode(sourceFile, start, end) {
     let best;
     const visit = (node) => {
-        if (node.getStart(sourceFile) <= start && node.getEnd() >= end) {
-            if (isPreferredTarget(node))
+        const nodeStart = node.getStart(sourceFile);
+        const nodeEnd = node.getEnd();
+        if (nodeStart <= start && nodeEnd >= end) {
+            if (isPreferredTarget(node) ||
+                (ts.isTypeNode(node) && nodeStart === start && nodeEnd === end)) {
                 best = node;
-            node.forEachChild(visit);
-        }
-        else {
-            node.forEachChild(visit);
+            }
         }
+        node.forEachChild(visit);
     };
     visit(sourceFile);
     return best;

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

@@ -40,6 +40,15 @@ const MAX_TYPE_TEXT = 80;
 /** Depth cap on the structural descent. Deeper differences are reported at the
  * deepest ancestor the walk reached, never dropped. */
 const MAX_FIELD_DEPTH = 4;
+/**
+ * Members a GraphQL server adds to every object a selection asks for
+ * (carrick#1759). The probe reads them as optional on the consumer, which is
+ * the probe's reading and not the consumer's source, so the walk states no
+ * optionality gap for them and does not count one the producer omits as a
+ * field the consumer is waiting on. A type they disagree on is still named.
+ */
+const GRAPHQL_SERVER_SUPPLIED = new Set(['__typename']);
+const NONE_SERVER_SUPPLIED = new Set();
 function assignabilityOf(checker) {
     const fn = checker.isTypeAssignableTo;
     return typeof fn === 'function' ? fn.bind(checker) : undefined;
@@ -89,7 +98,7 @@ export function pairFieldReports(opened, plans) {
         // 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);
+        const report = diffReport(compared, expected.type, checker, isAssignableTo, expected.node, plan.spec.protocol === 'graphql' ? GRAPHQL_SERVER_SUPPLIED : NONE_SERVER_SUPPLIED);
         report.wireApplied = wireChanges;
         results.set(plan.pairId, report);
     }
@@ -111,9 +120,9 @@ function declaredConstType(file, checker, name) {
     }
     return undefined;
 }
-function diffReport(sent, expected, checker, isAssignableTo, at) {
+function diffReport(sent, expected, checker, isAssignableTo, at, serverSupplied) {
     const found = [];
-    walk(sent, expected, '', 0, { checker, isAssignableTo, at, found });
+    walk(sent, expected, '', 0, { checker, isAssignableTo, at, found, serverSupplied });
     found.sort((a, b) => a.path === b.path ? compareText(a.nature, b.nature) : compareText(a.path, b.path));
     return {
         differences: found.slice(0, MAX_NAMED_FIELDS),
@@ -165,7 +174,11 @@ function walk(sent, expected, path, depth, ctx) {
     for (const [name, expectedProp] of expectedProps) {
         const at = join(path, name);
         const sentProp = sentProps.get(name);
+        const supplied = ctx.serverSupplied.has(name);
         if (!sentProp) {
+            // The server sends it whether or not the producer's type states it.
+            if (supplied)
+                continue;
             absent += 1;
             // An optional member the sender omits is what optional MEANS. Naming it
             // would state that the receiver requires it, which is false, and it is
@@ -180,9 +193,10 @@ function walk(sent, expected, path, depth, ctx) {
         if (sentOptional && !expectedOptional) {
             ctx.found.push({ path: at, nature: 'optional_in_sent' });
         }
-        else if (!sentOptional && expectedOptional) {
+        else if (!sentOptional && expectedOptional && !supplied) {
             // No assignment error exists for this direction, which is exactly why
-            // the judge cannot report it and this walk must.
+            // the judge cannot report it and this walk must. A server-supplied
+            // member is optional only in the probe's reading, so no gap is stated.
             ctx.found.push({ path: at, nature: 'optional_in_expected' });
         }
         const sentType = memberType(sentProp, ctx);

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

@@ -23,6 +23,11 @@
  * at compare time (ts_check type-checker `unwrapGraphqlPayload`, deleted in
  * WP8); the type-level port here is its v2-native equivalent.
  *
+ * GraphQL pairs also read the consumer's `__typename` as optional, at any depth
+ * (carrick#1759): the server adds that meta-field to every object a selection
+ * asks for, so a resolver's return type never states it, while a consumer type
+ * generated from a document that selects it declares it required.
+ *
  * Seam: node builtins + `typescript` + this bundle only. No imports needed here.
  */
 import type { CheckPairEndpoint, CheckPairSpec, ProbeProtocol, ProbeTypeKind } from './api.js';