carrick 0.3.122 → 0.3.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.122",
+  "version": "0.3.124",
   "carrickCache": {
     "cache_version": 22,
     "intent_cache_version": 2
@@ -113,11 +113,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.122",
-    "@carrick-tools/cli-darwin-x64": "0.3.122",
-    "@carrick-tools/cli-linux-arm64": "0.3.122",
-    "@carrick-tools/cli-linux-x64": "0.3.122",
-    "@carrick-tools/cli-win32-x64": "0.3.122"
+    "@carrick-tools/cli-darwin-arm64": "0.3.124",
+    "@carrick-tools/cli-darwin-x64": "0.3.124",
+    "@carrick-tools/cli-linux-arm64": "0.3.124",
+    "@carrick-tools/cli-linux-x64": "0.3.124",
+    "@carrick-tools/cli-win32-x64": "0.3.124"
   },
   "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.122",
+  "version": "0.3.124",
   "author": {
     "name": "Carrick",
     "email": "hello@carrick.tools"

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

@@ -39,6 +39,12 @@ export const MACHINERY_MEMBER_INDICATORS = new Set([
     'clone',
     'json',
     'statusText',
+    // FROZEN (old path, 2026-10-21): the reply-object half below only (the
+    // fetch half above and the threshold stay). Deletions and safety fixes
+    // only. Fixes for wrong or missing types go in labelled reply objects
+    // (carrick#2472 C4) and the language library rows (carrick#2445). Delete
+    // when a delete-and-replay on the four repos moves no row wrongly, after
+    // carrick-cloud#2379 and carrick#2445 (carrick#2472, C6).
     // Node http ServerResponse / reply-object surface
     'statusCode',
     'statusMessage',

package/sidecar/dist/src/index.js

@@ -442,7 +442,7 @@ function handleVerifyLibraryClaims(request) {
         writeProgress(request.request_id, 'verify_library_claims', 'program ready');
         const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
         log(`Verifying ${request.checks.length} library claim(s) from ${fromDir}`);
-        const { semantics, modules } = claimsVerifier.run(fromDir, request.checks, request.budget_ms ?? SEMANTICS_BUDGET_MS);
+        const { semantics, modules } = claimsVerifier.run(fromDir, request.checks, request.budget_ms ?? SEMANTICS_BUDGET_MS, request.scan_root);
         return {
             request_id: request.request_id,
             status: 'success',

package/sidecar/dist/src/library-claims.d.ts

@@ -63,7 +63,7 @@ export declare class LibraryClaimsVerifier {
      * A check on an instance or a scope reads the maker or scope claims of the
      * same request first, whatever their place in it.
      */
-    run(fromDir: string, checks: LibraryCheck[], budgetMs: number): VerifyResult;
+    run(fromDir: string, checks: LibraryCheck[], budgetMs: number, scanRoot?: string): VerifyResult;
     /**
      * Each specifier's declared surface, read with the verifier's predicates
      * (carrick#1660): every value export (or only those `only` names for the

package/sidecar/dist/src/library-claims.js

@@ -39,6 +39,7 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ts } from 'ts-morph';
+import { PathNames, declaringFileName } from './position-rows.js';
 /** The methods a `verb` claim may name, and a method key may accept. */
 const HTTP_METHODS = new Set([
     'GET',
@@ -130,8 +131,9 @@ const HTTP_V2_RULES = { http: false, message: true, ops: new Set(['request']), m
 const SERVER_RULES = { http: false, message: true, ops: new Set(['receive']), methods: ROUTE_METHODS };
 /**
  * The role table: the role alone picks the checks. A role this build does
- * not read yet (GraphQL executors, server mounts) answers `role_unsupported`,
- * and `none` has nothing on the wire to check.
+ * not read yet (GraphQL executors) answers `role_unsupported`, and `none`
+ * has nothing on the wire to check. A server's mounts are scope claims
+ * (`mounts`, #2474 R0).
  */
 const ROLE_TABLE = {
     http_client: HTTP_RULES,
@@ -238,6 +240,13 @@ export function httpCheck(check) {
         }
     }
 }
+/** Declarations in a fixed order, each once. */
+function sortedDeclarations(declarations) {
+    const seen = new Map();
+    for (const each of declarations)
+        seen.set(`${each.decl_file}:${each.decl_line}`, each);
+    return [...seen.values()].sort((a, b) => (a.decl_file < b.decl_file ? -1 : a.decl_file > b.decl_file ? 1 : a.decl_line - b.decl_line));
+}
 let probeSequence = 0;
 export class LibraryClaimsVerifier {
     project;
@@ -250,10 +259,15 @@ export class LibraryClaimsVerifier {
      * A check on an instance or a scope reads the maker or scope claims of the
      * same request first, whatever their place in it.
      */
-    run(fromDir, checks, budgetMs) {
+    run(fromDir, checks, budgetMs, scanRoot) {
         const deadline = performance.now() + budgetMs;
         const stamp = (check, outcome) => outcome.verdict === 'verified'
-            ? { claim_id: check.claim_id, receiver: check.receiver, verdict: 'verified' }
+            ? {
+                claim_id: check.claim_id,
+                receiver: check.receiver,
+                verdict: 'verified',
+                ...(outcome.declarations?.length ? { declarations: outcome.declarations } : {}),
+            }
             : {
                 claim_id: check.claim_id,
                 receiver: check.receiver,
@@ -330,7 +344,7 @@ export class LibraryClaimsVerifier {
             const file = program.getSourceFile(probe.getFilePath());
             if (!file)
                 throw new Error(`probe file ${probePath} is not in the program`);
-            const reader = new DeclarationReader(program, file, this.project.getModuleResolutionHost(), fromDir);
+            const reader = new DeclarationReader(program, file, this.project.getModuleResolutionHost(), fromDir, scanRoot);
             const localRanges = readLocalRanges(fromDir);
             const moduleReads = new Map();
             const exportReads = new Map();
@@ -501,13 +515,15 @@ export class LibraryClaimsVerifier {
                 const built = builtReceiver(check);
                 const builtAtDefaults = built === undefined ? undefined : atDefaults(check, built);
                 const holding = [];
+                const declarations = [];
                 for (const receiver of receivers.value) {
                     const result = reader.judgeMessage(receiver, check.claim, rules, builtAtDefaults);
                     if (result.outcome.verdict !== 'verified')
                         return result;
                     holding.push(...(result.holding ?? []));
+                    declarations.push(...(result.outcome.declarations ?? []));
                 }
-                return { outcome: VERIFIED, holding };
+                return { outcome: declarations.length > 0 ? { verdict: 'verified', declarations: sortedDeclarations(declarations) } : VERIFIED, holding };
             };
             const semantics = [];
             for (let index = 0; index < checks.length; index++) {
@@ -695,6 +711,19 @@ function placementInvalid(claim) {
     const of = parseReceiver(claim.of);
     return of === undefined || (of.maker === undefined && of.scope === undefined);
 }
+/**
+ * Where a handler's request holds its path and method (#2474 R0) is read on
+ * a receive op with a handler, and names `path` or `url`; every member path
+ * it gives is non-empty.
+ */
+function requestAtValid(claim) {
+    const request = claim.request;
+    if (claim.op !== 'receive' || claim.handler === undefined)
+        return false;
+    if (request.path === undefined && request.url === undefined)
+        return false;
+    return [request.path, request.url, request.method].every(members => members === undefined || members.length > 0);
+}
 /**
  * A message check names a receiver its claim can be read on (contract
  * amendment 2, B3). A maker is read on the export itself. An element with
@@ -841,6 +870,8 @@ class DeclarationReader {
     probe;
     host;
     checker;
+    /** Names declaring files as position rows do: from the scan root, else the service root. */
+    pathNames;
     /** The service root, as a realpath. */
     root;
     packageDirectories = new Map();
@@ -853,11 +884,12 @@ class DeclarationReader {
     declared = new Map();
     /** The service root as given and as a realpath, longest first: what a listing prints as `<root>`. */
     printedRoots;
-    constructor(program, probe, host, serviceRoot) {
+    constructor(program, probe, host, serviceRoot, scanRoot) {
         this.program = program;
         this.probe = probe;
         this.host = host;
         this.checker = program.getTypeChecker();
+        this.pathNames = new PathNames(scanRoot ?? serviceRoot);
         this.root = this.realpath(serviceRoot);
         this.printedRoots = [...new Set([this.root, serviceRoot])]
             .filter(root => root.length > 1)
@@ -1472,9 +1504,26 @@ class DeclarationReader {
      * `member` (after `path`) is a home-declared callable member whose name
      * slot accepts a string, under the name-slot rules, and returns a type that
      * says something, read at its type-parameter defaults (`returnOf`).
+     *
+     * Route fields (#2474 R0, contract amendment of 2026-10-22 on carrick#2434):
+     * - `runs` with `yields`: the member runs the function at `runs` (a
+     *   function with a declared signature) and hands it, at `yields.param`,
+     *   an instance of the package's export `yields.export` (`yieldsOutcome`);
+     * - `mounts`: the receiver the claim is read on fits the parameter there
+     *   (`mountsOutcome`).
+     * Either one binds its instance through a parameter or an argument, not
+     * the member's return, so the return is not read and the claim holds no
+     * overloads: a `>scope:` receiver read through it is not resolved.
+     * `runs` without `yields` (or the reverse), or `mounts` beside either, is
+     * `claim_invalid`.
      */
     judgeScope(receiver, claim, built) {
-        const layout = this.layout({ name: claim.name });
+        if ((claim.runs === undefined) !== (claim.yields === undefined))
+            return { outcome: unchecked('claim_invalid') };
+        if (claim.mounts !== undefined && claim.runs !== undefined)
+            return { outcome: unchecked('claim_invalid') };
+        const binds = claim.runs !== undefined || claim.mounts !== undefined;
+        const layout = this.layout({ name: claim.name, runs: claim.runs, mounts: claim.mounts });
         if ('failure' in layout)
             return { outcome: layout.failure };
         const callee = this.ownCallee(receiver, claim.path ?? [], claim.member, 'call');
@@ -1485,7 +1534,17 @@ class DeclarationReader {
         let best;
         for (const signature of callee.signatures) {
             let result = this.messageSignatureOutcome(signature, layout.value, labels);
-            if (result.rank === Infinity && this.returnSaysNothing(this.returnOf(signature, built))) {
+            if (result.rank === Infinity && claim.yields !== undefined) {
+                const given = this.yieldsOutcome(signature, claim.runs, claim.yields, receiver);
+                if (given)
+                    result = { rank: 5, outcome: given };
+            }
+            if (result.rank === Infinity && claim.mounts !== undefined) {
+                const mounted = this.mountsOutcome(signature, claim.mounts, receiver);
+                if (mounted)
+                    result = { rank: 5, outcome: mounted };
+            }
+            if (result.rank === Infinity && !binds && this.returnSaysNothing(this.returnOf(signature, built))) {
                 result = { rank: 6, outcome: unchecked('scope_unresolved') };
             }
             if (result.rank === Infinity)
@@ -1494,9 +1553,38 @@ class DeclarationReader {
                 best = furthest(best, result.rank, result.outcome);
         }
         if (holding.length > 0)
-            return { outcome: VERIFIED, holding };
+            return binds ? { outcome: VERIFIED } : { outcome: VERIFIED, holding };
         return { outcome: best.outcome };
     }
+    /**
+     * `mounts: { arg, key? }` on a scope (#2474 R0): the receiver the claim is
+     * read on is assignable to the parameter there, so an instance like it can
+     * be served under the scope's name. A parameter typed `any`, `unknown`,
+     * `{}` or by an unconstrained type parameter says nothing
+     * (`mounts_untyped`). There is no separate "not a function" rule: a router
+     * type that is itself a handler is a common shape, and a parameter only a
+     * function fits fails here because the instance does not fit it.
+     * Undefined when it holds.
+     */
+    mountsOutcome(signature, mounts, receiver) {
+        let declared = this.keyParameterAt(signature, mounts.arg);
+        if (declared !== undefined && mounts.key !== undefined) {
+            const property = this.declaredProperty(declared, mounts.key);
+            declared = property ? this.checker.getTypeOfSymbol(property) : undefined;
+        }
+        if (declared === undefined)
+            return failed('param_missing');
+        const slot = this.throughConstraint(declared);
+        if (slot === VARIADIC)
+            return unchecked('mounts_untyped');
+        const parts = this.parts(slot);
+        if (parts.length === 0)
+            return failed('mounts_not_instance');
+        if (parts.some(part => this.isOpenTop(part) || this.isUnconstrained(part) || this.isEmptyObject(part))) {
+            return unchecked('mounts_untyped');
+        }
+        return this.checker.isTypeAssignableTo(receiver.type, slot) ? undefined : failed('mounts_not_instance');
+    }
     /**
      * A send, receive or request op: the home-declared callable member (after
      * `path`; or the receiver itself, when null) with some overload that takes
@@ -1513,6 +1601,9 @@ class DeclarationReader {
         if (claim.yields !== undefined && (claim.op !== 'receive' || claim.handler === undefined)) {
             return unchecked('claim_invalid');
         }
+        // So is where the handler's request holds its path and method (#2474 R0).
+        if (claim.request !== undefined && !requestAtValid(claim))
+            return unchecked('claim_invalid');
         const name = claim.name;
         // A send carries a payload: a name alone on `send(data)` is the data. An
         // op that runs a function or client it is handed takes its name from
@@ -1562,6 +1653,11 @@ class DeclarationReader {
                 if (given)
                     result = { rank: 5, outcome: given };
             }
+            if (result.rank === Infinity && claim.request !== undefined) {
+                const read = this.requestOutcome(signature, claim.handler, claim.request);
+                if (read)
+                    result = { rank: 5, outcome: read };
+            }
             if (result.rank === Infinity) {
                 held = true;
                 break;
@@ -1572,7 +1668,28 @@ class DeclarationReader {
             return best.outcome;
         if (boundRuns)
             return this.boundRunsOutcome(receiver.makerHolding, boundRuns);
-        return VERIFIED;
+        const declarations = this.declarationsOf(callee.signatures);
+        return declarations.length > 0 ? { verdict: 'verified', declarations } : VERIFIED;
+    }
+    /**
+     * Where the signatures a verified op resolved to are declared, as position
+     * rows spell it (`decl_file`, `decl_line`): the member on this receiver, so
+     * two members of one name on two types give two answers. A declaration no
+     * row could name is left out.
+     */
+    declarationsOf(signatures) {
+        const found = [];
+        for (const signature of signatures) {
+            const declaration = signature.getDeclaration();
+            if (!declaration)
+                continue;
+            const file = declaration.getSourceFile();
+            const decl_file = declaringFileName(this.program, this.pathNames, file);
+            if (decl_file === null)
+                continue;
+            found.push({ decl_file, decl_line: file.getLineAndCharacterOfPosition(declaration.getStart(file)).line + 1 });
+        }
+        return sortedDeclarations(found);
     }
     /**
      * The method fields of an op (label structure v2, carrick#2434), under the
@@ -1680,6 +1797,48 @@ class DeclarationReader {
         }
         return failed('yields_not_export');
     }
+    /**
+     * `request: { param, path?, url?, method? }` on a receive op (#2474 R0):
+     * some signature of the handler this overload takes declares a parameter
+     * at `param` on which every member path the claim gives resolves, step by
+     * step, through properties the library declares (`declaredProperty`).
+     * Undefined when it holds.
+     */
+    requestOutcome(signature, handler, request) {
+        let declared = this.keyParameterAt(signature, handler.arg);
+        if (declared !== undefined && handler.key !== undefined) {
+            const property = this.declaredProperty(declared, handler.key);
+            declared = property ? this.checker.getTypeOfSymbol(property) : undefined;
+        }
+        if (declared === undefined)
+            return failed('param_missing');
+        const slot = this.throughConditional(this.throughConstraint(declared));
+        if (slot === VARIADIC)
+            return unchecked('handler_untyped');
+        const paths = [request.path, request.url, request.method].filter((p) => p !== undefined);
+        let best = failed('param_missing');
+        for (const part of this.parts(slot)) {
+            for (const handed of part.getCallSignatures()) {
+                const given = this.parameterAt(handed, request.param);
+                if (given === undefined || given === VARIADIC)
+                    continue;
+                const resolves = paths.every(members => {
+                    let at = given;
+                    for (const member of members) {
+                        const property = this.declaredProperty(at, member);
+                        if (!property)
+                            return false;
+                        at = this.checker.getTypeOfSymbol(property);
+                    }
+                    return true;
+                });
+                if (resolves)
+                    return undefined;
+                best = failed('request_member_missing');
+            }
+        }
+        return best;
+    }
     /**
      * The declarations spell `name` in one of `member`'s parameters: an
      * overload whose parameter there is that literal, or a key of the map a

package/sidecar/dist/src/position-rows.d.ts

@@ -13,29 +13,26 @@
  * | `member`  | property or element access                        | the name or the argument  | the access     |
  * | `compare` | `=== !== == != < > <= >= instanceof in`           | the left operand          | the left operand |
  * | `ident`   | an identifier in expression position              | itself                    | itself         |
- * | `impl`    | a `call` or `member` whose declaration has no body | an implementation of it  | nothing        |
  * | `decl`    | a `call` or `member` on a union of declaring types | one of those declarations | nothing       |
  * | `jsx`     | a JSX opening or self-closing element's tag        | the tag's name           | the tag        |
  *
- * An `impl` row (version 2, carrick#2430) follows the `call` or `member` row
- * it belongs to and has its span: one per declaration that go-to-implementation
- * names for that row's declaration, when that declaration is an interface's
- * or type literal's method, a function-typed property signature, an abstract
- * member, or a function-typed class property or parameter with no
- * initializer. Its `decl_*` name the implementing declaration. Past
- * {@link IMPL_CAP} the row is one, with {@link FLAG_TOO_MANY} and nothing else.
- *
  * A `decl` row (version 3, carrick#2448) follows the `call` or `member` row
- * it belongs to, before its `impl` rows, and has its span: one per
+ * it belongs to and has its span: one per
  * declaration of the member when the receiver is a union whose constituents
  * declare it at more than one place (`(pick ? a : b).get()` with two
  * classes). That row names only the first of them. Each constituent's
  * declaration is its own member's, or, for a member with none (a mapped
- * type's), the declaration of the constituent type itself. Sorted and capped
- * as `impl` rows are; `type_text` is `null`.
+ * type's), the declaration of the constituent type itself. Sorted by file and
+ * position; past {@link DECL_CAP} the row is one, with {@link FLAG_TOO_MANY}
+ * and nothing else. `type_text` is `null`.
+ *
+ * Version 4 (carrick#2561) dropped the `impl` rows of versions 2 and 3: the
+ * go-to-implementation search behind them was most of the walk's time, and
+ * nothing read them. Implementations are asked for where discovery stops
+ * (carrick#2432).
  *
- * A row's key is `(start, end, kind)`, except that several `impl` rows, and
- * several `decl` rows, share one: TypeScript `getStart()`/`getEnd()` of the
+ * A row's key is `(start, end, kind)`, except that several `decl` rows share
+ * one: TypeScript `getStart()`/`getEnd()` of the
  * node, in UTF-16 code units from the start of the file, which is what the scanner's `sidecar_position`
  * gives for an SWC span. Every path written is relative to the scanned repo's
  * root, with `/` separators.
@@ -54,7 +51,7 @@ import { ts } from 'ts-morph';
 import type { ProjectLoader } from './project-loader.js';
 import type { PositionRowsCounts } from './types.js';
 /** The format's version, written in the header. */
-export declare const POSITION_ROWS_VERSION = 3;
+export declare const POSITION_ROWS_VERSION = 4;
 /** The type is `any`, declared or inferred. Never set with the error type. */
 export declare const FLAG_ANY = 1;
 /** The type is the compiler's error type: something did not resolve. */
@@ -63,7 +60,7 @@ export declare const FLAG_ERROR_TYPE = 2;
 export declare const FLAG_CHECKER_THREW = 4;
 /** The declaration is outside the checkout, not the default library and in no installed package. */
 export declare const FLAG_DECLARATION_UNNAMED = 8;
-/** An `impl` or `decl` row standing for more than {@link IMPL_CAP} rows of its kind; it names none. */
+/** A `decl` row standing for more than {@link DECL_CAP} rows; it names none. */
 export declare const FLAG_TOO_MANY = 16;
 /**
  * The declaration is published under the row's symbol name: its module
@@ -74,11 +71,11 @@ export declare const FLAG_TOO_MANY = 16;
 export declare const FLAG_PUBLISHED = 32;
 /** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
 export declare const FLAG_MODULE_DEFAULT = 64;
-/** The most `impl` rows one declaration lists, and the most `decl` rows one position lists. */
-export declare const IMPL_CAP = 16;
-/** The kinds {@link kindOf} gives a node; `impl`, `decl` and `jsx` rows are written beside them. */
+/** The most `decl` rows one position lists. */
+export declare const DECL_CAP = 16;
+/** The kinds {@link kindOf} gives a node; `decl` and `jsx` rows are written beside them. */
 export type NodeKind = 'call' | 'member' | 'compare' | 'ident';
-export type PositionKind = NodeKind | 'impl' | 'decl' | 'jsx';
+export type PositionKind = NodeKind | 'decl' | 'jsx';
 /** `[kind, start, end, symbol, decl_file, decl_line, decl_package, type_text, flags]` */
 export type PositionRow = [
     PositionKind,
@@ -110,5 +107,49 @@ export interface PositionRowsOptions {
  * a directory inside the scanned trees anywhere but beneath `.carrick`.
  */
 export declare function writePositionRows(options: PositionRowsOptions): PositionRowsCounts;
+/** What a declaration's file is written as in a row's `decl_file`: `lib:<name>` for the default library, else `PathNames`'. */
+export declare function declaringFileName(program: ts.Program, paths: PathNames, file: ts.SourceFile): string | null;
+/**
+ * Names for the files rows point at, never an absolute path: relative to the
+ * scanned repo's root when inside it (its real path too, so a root reached
+ * through a link still contains its files), `lib:<name>` for the compiler's
+ * default library, `pkg:<name>/<path>` for an installed package outside the
+ * root, and nothing otherwise.
+ */
+export declare class PathNames {
+    private readonly roots;
+    private readonly packageNames;
+    /**
+     * Answers by declaring file: a service's rows name a few thousand files
+     * hundreds of thousands of times, and the module graph's answer is a scan
+     * of its packages (on a Deno service it was 40% of the walk).
+     */
+    private readonly declaringFiles;
+    private readonly declaringPackages;
+    constructor(scanRoot: string);
+    /** The root `file` lies under, and its path from there; `undefined` outside every root. */
+    private inside;
+    /** A request file's name: relative to the root, which every file the scanner sends is inside. */
+    relative(file: string): string;
+    /** What a declaring file is written as, or `null` when nothing names it. */
+    declaringFile(fileName: string): string | null;
+    private nameDeclaringFile;
+    /**
+     * The package a declaring file belongs to: the module graph's or the path's
+     * answer (`installedPackageOf`), else, for a file inside the root, the
+     * `name` of the nearest package.json at or above it, up to the root.
+     */
+    declaringPackage(fileName: string, packageOf: (filePath: string) => string | undefined): string | null;
+    private nameDeclaringPackage;
+    private packageNameIn;
+    /**
+     * `import("/abs/path")` in a printed type, written with the declaring
+     * file's name instead. The print has no enclosing node, so it names every
+     * module by the file that declares it and one type reads the same from
+     * every file; it also skips the accessibility search an enclosing node
+     * costs (40% of the walk on a 600-file service).
+     */
+    scrubType(text: string): string;
+}
 /** The kind of row a node gives, if any (exported for the editor-parity test, carrick#2418). */
 export declare function kindOf(node: ts.Node): NodeKind | undefined;