carrick 0.3.134 → 0.3.135

package/package.json

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

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

@@ -35,6 +35,7 @@ import { findAugmentationFiles } from './augmentations.js';
 import { installedVersions, lockfileVersions } from './lockfile.js';
 import { installedResolutionEdges, RESOLUTION_FILE } from './resolution-edges.js';
 import { rewriteEmittedSpecifiers } from './paths-rewrite.js';
+import { substituteMachinePathImports } from './machine-paths.js';
 import { installedPackageSpecifier, typesPackageOf, withInstalledPackages } from './installed-package.js';
 import { selfCheckStub } from './self-check.js';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
@@ -448,6 +449,23 @@ export function captureStub(opts) {
         entryDir,
     });
     const specifierRewrites = denoRewrites + placed.rewrites + rewritten.rewrites;
+    // What the rewrite could not map still names a machine path (carrick#2943).
+    const machinePaths = substituteMachinePathImports({
+        files: emittedFiles.map((rel) => path.join(typesDir, rel)),
+        surfaceAbsPath,
+        tree: stubGuard.narrow(typesDir),
+        labelRoot: opts.scanRoot ?? repoRoot,
+    });
+    if (machinePaths.size > 0) {
+        resolved = resolved.map((anchor) => {
+            const found = machinePaths.get(anchor.request.alias);
+            if (!found)
+                return anchor;
+            const paths = [...new Set([...(anchor.unresolved?.paths ?? []), ...found.paths])];
+            const specifiers = [...new Set([...found.modules, ...(anchor.unresolved?.specifiers ?? [])])];
+            return { ...anchor, unresolved: { paths, specifiers } };
+        });
+    }
     // ---- Pin external deps: installed node_modules first, lockfile fallback ----
     // Externals are collected AFTER the rewrite pass: a rewritten paths
     // specifier is internal, not a dependency.

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

@@ -0,0 +1,44 @@
+/**
+ * No stub names a module by a machine path (carrick#2943).
+ *
+ * The specifier rewrite maps an absolute specifier onto a file of the stub's
+ * tree or onto an installed package. What it cannot map stays as printed: a
+ * type that a printer could name only by where its module sits on this
+ * machine, such as a workspace sibling's source reached through a
+ * `node_modules` link, which the declaration emit does not carry. That path
+ * resolves on the machine that ran the capture, to a source file outside the
+ * stub, and nowhere else: the upload rewrites it to `<checkout>/...`, so the
+ * stored stub and a fresh one disagree about the same alias.
+ *
+ * Each such reference becomes `unknown` at its own position. In the surface
+ * the position is reported per alias, so the self-check labels the finding
+ * there as a reference that did not resolve rather than as declared; the rest
+ * of the alias's type survives. Any other tree file gets the dangling-import
+ * repair (carrick#1397), which writes `unknown` where the import's names were
+ * used. The stub then reads the same on every machine.
+ *
+ * Seam: node builtins + `typescript`, like the rest of this directory.
+ */
+import type { WriteGuard } from './guarded-fs.js';
+/** A specifier that names a module by where it sits on one machine. */
+export declare function isMachinePath(specifier: string): boolean;
+/** What the surface substitution replaced in one alias. */
+export interface MachinePathPositions {
+    /** Member paths now `unknown`, in the deep walk's notation (`''` = root). */
+    paths: string[];
+    /** The modules they named, relative to `labelRoot` (never absolute). */
+    modules: string[];
+}
+/**
+ * Replace every machine-path import in the stub's tree with `unknown`.
+ * `files` are absolute tree paths; `surfaceAbsPath` is one of them. Returns
+ * the positions replaced in the surface, by alias.
+ */
+export declare function substituteMachinePathImports(args: {
+    files: readonly string[];
+    surfaceAbsPath: string;
+    /** A guard over the stub's types tree. */
+    tree: WriteGuard;
+    /** The root a module is named from in a label (the scanned repo's). */
+    labelRoot: string;
+}): Map<string, MachinePathPositions>;

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

@@ -0,0 +1,97 @@
+/**
+ * No stub names a module by a machine path (carrick#2943).
+ *
+ * The specifier rewrite maps an absolute specifier onto a file of the stub's
+ * tree or onto an installed package. What it cannot map stays as printed: a
+ * type that a printer could name only by where its module sits on this
+ * machine, such as a workspace sibling's source reached through a
+ * `node_modules` link, which the declaration emit does not carry. That path
+ * resolves on the machine that ran the capture, to a source file outside the
+ * stub, and nowhere else: the upload rewrites it to `<checkout>/...`, so the
+ * stored stub and a fresh one disagree about the same alias.
+ *
+ * Each such reference becomes `unknown` at its own position. In the surface
+ * the position is reported per alias, so the self-check labels the finding
+ * there as a reference that did not resolve rather than as declared; the rest
+ * of the alias's type survives. Any other tree file gets the dangling-import
+ * repair (carrick#1397), which writes `unknown` where the import's names were
+ * used. The stub then reads the same on every machine.
+ *
+ * Seam: node builtins + `typescript`, like the rest of this directory.
+ */
+import ts from 'typescript';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { childPath } from './node-builder.js';
+import { repairDanglingImports } from './repair-dangling.js';
+import { collectSpecifiers } from './specifiers.js';
+/** A specifier that names a module by where it sits on one machine. */
+export function isMachinePath(specifier) {
+    return path.posix.isAbsolute(specifier) || /^[A-Za-z]:[\\/]/.test(specifier) || specifier.startsWith('\\\\');
+}
+/**
+ * Replace every machine-path import in the stub's tree with `unknown`.
+ * `files` are absolute tree paths; `surfaceAbsPath` is one of them. Returns
+ * the positions replaced in the surface, by alias.
+ */
+export function substituteMachinePathImports(args) {
+    const failing = new Map();
+    for (const file of args.files) {
+        if (path.resolve(file) === path.resolve(args.surfaceAbsPath))
+            continue;
+        const machine = [...collectSpecifiers(fs.readFileSync(file, 'utf8'))].filter(isMachinePath);
+        if (machine.length > 0)
+            failing.set(file, new Set(machine));
+    }
+    if (failing.size > 0)
+        repairDanglingImports(failing, args.tree);
+    return substituteInSurface(args.surfaceAbsPath, args.tree, args.labelRoot);
+}
+function substituteInSurface(surfaceAbsPath, tree, labelRoot) {
+    const byAlias = new Map();
+    const text = fs.readFileSync(surfaceAbsPath, 'utf8');
+    if (!/import\s*\(/.test(text))
+        return byAlias;
+    const source = ts.createSourceFile(surfaceAbsPath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const edits = [];
+    for (const statement of source.statements) {
+        if (!ts.isTypeAliasDeclaration(statement))
+            continue;
+        const found = { paths: [], modules: [] };
+        const visit = (node, at) => {
+            const specifier = importTypeSpecifier(node);
+            if (specifier !== undefined && isMachinePath(specifier)) {
+                edits.push({ start: node.getStart(source), end: node.getEnd() });
+                if (!found.paths.includes(at))
+                    found.paths.push(at);
+                const module = moduleLabel(specifier, labelRoot);
+                if (!found.modules.includes(module))
+                    found.modules.push(module);
+                return;
+            }
+            node.forEachChild((child) => visit(child, childPath(node, child, at)));
+        };
+        visit(statement.type, '');
+        if (found.paths.length > 0)
+            byAlias.set(statement.name.text, found);
+    }
+    if (edits.length === 0)
+        return byAlias;
+    edits.sort((a, b) => b.start - a.start);
+    let out = text;
+    for (const edit of edits)
+        out = `${out.slice(0, edit.start)}unknown${out.slice(edit.end)}`;
+    tree.writeFile(surfaceAbsPath, out);
+    return byAlias;
+}
+/** The string an `import("...")` type names, when `node` is one. */
+function importTypeSpecifier(node) {
+    if (!ts.isImportTypeNode(node) || !ts.isLiteralTypeNode(node.argument))
+        return undefined;
+    const literal = node.argument.literal;
+    return ts.isStringLiteral(literal) ? literal.text : undefined;
+}
+/** `specifier` relative to `root`, with forward slashes. */
+function moduleLabel(specifier, root) {
+    return path.relative(path.resolve(root), path.resolve(specifier)).split(path.sep).join('/');
+}

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

@@ -67,6 +67,8 @@ export declare function substituteUndeclaredNames(node: ts.TypeNode, program: ts
     node: ts.TypeNode;
     substitutions: UndeclaredSubstitution[];
 };
+/** The deep walk's path for `child` inside `parent`, extending `path`. */
+export declare function childPath(parent: ts.Node, child: ts.Node, path: string): string;
 /**
  * Bare names in a printed type node that nothing in the producer's program
  * declares (carrick#1165).

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

@@ -174,7 +174,7 @@ export function substituteUndeclaredNames(node, program, destination) {
     return { node: rewritten, substitutions };
 }
 /** The deep walk's path for `child` inside `parent`, extending `path`. */
-function childPath(parent, child, path) {
+export function childPath(parent, child, path) {
     if (ts.isPropertySignature(parent) && parent.type === child) {
         const name = ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name)
             ? parent.name.text

package/sidecar/dist/src/index.js

@@ -637,7 +637,7 @@ function handleListLibrarySurface(request) {
         const { claimsVerifier } = projectComponents();
         const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
         log(`Listing the declared surface of ${request.packages.length} specifier(s) from ${fromDir}`);
-        const { surfaces, surface_sha256 } = claimsVerifier.listSurface(fromDir, request.packages, request.max_entries ?? SURFACE_MAX_ENTRIES, request.exports ?? {});
+        const { surfaces, surface_sha256 } = claimsVerifier.listSurface(fromDir, request.packages, request.max_entries ?? SURFACE_MAX_ENTRIES, request.exports ?? {}, { handlers: request.handlers, resultCandidates: request.result_candidates });
         return { request_id: request.request_id, status: 'success', surfaces, surface_sha256 };
     }
     catch (err) {

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

@@ -50,6 +50,11 @@ type Outcome = {
      */
     members?: readonly ts.Declaration[];
     bodyMembers?: readonly ts.Declaration[];
+    /**
+     * Stamped: why a receive op's `request` was dropped while the op
+     * itself verified (carrick#2968). Only `request_member_missing`.
+     */
+    requestDropped?: string;
 } | {
     verdict: 'failed' | 'unchecked';
     reason: string;
@@ -86,6 +91,15 @@ export interface ModuleGraph {
     /** How the program resolves `name` from `from`; `undefined` where there is no graph, and Node resolution answers. */
     resolveModule(name: string, from: string, options: ts.CompilerOptions): ts.ResolvedModuleFull | undefined;
 }
+/**
+ * Test instrumentation, never on the wire: how many times the lister built a
+ * handler parameter's members and printed a type, since the caller last
+ * reset them (carrick#2977).
+ */
+export declare const surfaceReadCounts: {
+    handlerMemberBuilds: number;
+    typePrints: number;
+};
 export declare class LibraryClaimsVerifier {
     private readonly project;
     private readonly graph;
@@ -124,9 +138,20 @@ export declare class LibraryClaimsVerifier {
      * (`receiverExpression` on the export's `importLine`, read through
      * `DeclarationReader.returnOf`) and lists from it.
      *
+     * A member of an `instance:` receiver whose call returns another object
+     * that routes are registered on lists that object as its `scope_receiver`
+     * (carrick#2774), built as the verifier builds a scope step, under a cap of
+     * its own and left out of the hash.
+     *
+     * Each member's handler-parameter members (carrick#2674 S3) are listed
+     * only when `options.handlers` is set, and each signature's result
+     * candidates (carrick#2817) only when `options.resultCandidates` is
+     * (carrick#2966): on a large package either costs more than the rest of the
+     * listing.
+     *
      * `surface_sha256` is the full-surface hash (see `fullSurfaceSha256`).
      */
-    listSurface(fromDir: string, packages: string[], maxEntries: number, only?: Readonly<Record<string, string[]>>): ListedSurface;
+    listSurface(fromDir: string, packages: string[], maxEntries: number, only?: Readonly<Record<string, string[]>>, options?: SurfaceOptions): ListedSurface;
     /** `read` over a probe file holding `lines` in `fromDir`, removed again afterwards. */
     private readProbe;
 }
@@ -140,8 +165,8 @@ export interface ListedSurface {
  * array of `[package, exports]` for every surface that listed at least one
  * export, sorted by `package` (code unit order). A specifier that lists
  * nothing (unresolved, local, no value exports) is left out, so asking for a
- * subpath a version does not have changes nothing. Handler members are not
- * hashed. Type text already names
+ * subpath a version does not have changes nothing. Handler members, result
+ * candidates and scope receivers are not hashed. Type text already names
  * the request's directory as `<root>`.
  */
 export declare function fullSurfaceSha256(surfaces: readonly LibrarySurface[]): string;
@@ -177,4 +202,11 @@ export interface LabelledMembers {
     /** How each label read came out (`verified`, or the reason it was not), for the log. */
     outcomes?: Readonly<Record<string, number>>;
 }
+/** What a surface listing adds beyond the hashed surface, each only when asked (carrick#2966). */
+export interface SurfaceOptions {
+    /** Each member's `handlers` (carrick#2674 S3). */
+    handlers?: boolean;
+    /** Each signature's `result_candidates` (carrick#2817). */
+    resultCandidates?: boolean;
+}
 export {};

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

@@ -259,6 +259,12 @@ function sortedDeclarations(declarations) {
 }
 let probeSequence = 0;
 const NO_MODULE_GRAPH = { packageDirectoryOf: () => undefined, resolveModule: () => undefined };
+/**
+ * Test instrumentation, never on the wire: how many times the lister built a
+ * handler parameter's members and printed a type, since the caller last
+ * reset them (carrick#2977).
+ */
+export const surfaceReadCounts = { handlerMemberBuilds: 0, typePrints: 0 };
 export class LibraryClaimsVerifier {
     project;
     graph;
@@ -281,6 +287,7 @@ export class LibraryClaimsVerifier {
                 receiver: check.receiver,
                 verdict: 'verified',
                 ...(outcome.declarations?.length ? { declarations: outcome.declarations } : {}),
+                ...(outcome.requestDropped === undefined ? {} : { request_dropped: outcome.requestDropped }),
             }
             : {
                 claim_id: check.claim_id,
@@ -587,6 +594,8 @@ export class LibraryClaimsVerifier {
                 const declarations = [];
                 const members = [];
                 const bodyMembers = [];
+                // A request one receiver does not hold is dropped for the op (carrick#2968).
+                let requestDropped;
                 for (const receiver of receivers.value) {
                     const result = reader.judgeMessage(receiver, check.claim, rules, builtAtDefaults, collectionsOf);
                     if (result.outcome.verdict !== 'verified')
@@ -595,11 +604,14 @@ export class LibraryClaimsVerifier {
                     declarations.push(...(result.outcome.declarations ?? []));
                     members.push(...(result.outcome.members ?? []));
                     bodyMembers.push(...(result.outcome.bodyMembers ?? []));
+                    requestDropped ??= result.outcome.requestDropped;
                 }
                 const verified = declarations.length > 0 ? { verdict: 'verified', declarations: sortedDeclarations(declarations) } : { ...VERIFIED };
                 if (verified.verdict === 'verified' && members.length > 0)
                     verified.members = members;
-                if (verified.verdict === 'verified' && bodyMembers.length > 0)
+                if (verified.verdict === 'verified' && requestDropped !== undefined)
+                    verified.requestDropped = requestDropped;
+                else if (verified.verdict === 'verified' && bodyMembers.length > 0)
                     verified.bodyMembers = bodyMembers;
                 return { outcome: verified, holding };
             };
@@ -645,7 +657,11 @@ export class LibraryClaimsVerifier {
         const observe = (check, outcome) => {
             if (check.claim.kind !== 'op')
                 return;
-            const read = outcome.verdict === 'verified' ? 'verified' : `${outcome.verdict} ${outcome.reason}`;
+            const read = outcome.verdict !== 'verified'
+                ? `${outcome.verdict} ${outcome.reason}`
+                : outcome.requestDropped === undefined
+                    ? 'verified'
+                    : `verified request_dropped ${outcome.requestDropped}`;
             outcomes[read] = (outcomes[read] ?? 0) + 1;
             if (outcome.verdict !== 'verified')
                 return;
@@ -678,9 +694,20 @@ export class LibraryClaimsVerifier {
      * (`receiverExpression` on the export's `importLine`, read through
      * `DeclarationReader.returnOf`) and lists from it.
      *
+     * A member of an `instance:` receiver whose call returns another object
+     * that routes are registered on lists that object as its `scope_receiver`
+     * (carrick#2774), built as the verifier builds a scope step, under a cap of
+     * its own and left out of the hash.
+     *
+     * Each member's handler-parameter members (carrick#2674 S3) are listed
+     * only when `options.handlers` is set, and each signature's result
+     * candidates (carrick#2817) only when `options.resultCandidates` is
+     * (carrick#2966): on a large package either costs more than the rest of the
+     * listing.
+     *
      * `surface_sha256` is the full-surface hash (see `fullSurfaceSha256`).
      */
-    listSurface(fromDir, packages, maxEntries, only = {}) {
+    listSurface(fromDir, packages, maxEntries, only = {}, options = {}) {
         if (packages.length === 0)
             return { surfaces: [], surface_sha256: fullSurfaceSha256([]) };
         // Each specifier twice: as a namespace, which holds its named exports, and
@@ -709,10 +736,12 @@ export class LibraryClaimsVerifier {
         const buildLines = [];
         const builtIndex = new Map();
         packages.forEach((pkg, i) => {
-            for (const { export: name, receivers } of makers[i]) {
+            for (const { export: name, receivers, scopes } of makers[i]) {
                 const local = `__carrick_e${importLines.length}`;
                 importLines.push(probeLine(pkg, name, local));
-                for (const receiver of receivers) {
+                // The scope receivers a maker's members may return (carrick#2774) are
+                // built beside the makers, so `listPackage` reads them as it reads those.
+                for (const receiver of [...receivers, ...scopes]) {
                     const expression = receiverExpression(local, receiver);
                     if (expression === undefined)
                         continue;
@@ -722,7 +751,7 @@ export class LibraryClaimsVerifier {
             }
         });
         const firstBuild = imports.length + importLines.length;
-        const surfaces = this.readProbe(fromDir, [...imports, ...importLines, ...buildLines], (checker, reader, file) => packages.map((pkg, i) => reader.listPackage(pkg, probeOf(file, i), maxEntries, only[pkg], (name, receiver) => {
+        const surfaces = this.readProbe(fromDir, [...imports, ...importLines, ...buildLines], (checker, reader, file) => packages.map((pkg, i) => reader.listPackage(pkg, probeOf(file, i), maxEntries, only[pkg], options, (name, receiver) => {
             const index = builtIndex.get(builtKey({ package: pkg, export: name }, receiver));
             return index === undefined ? undefined : resolvedBuild(checker, file.statements[firstBuild + index]);
         })));
@@ -763,8 +792,8 @@ function resolvedBuild(checker, statement) {
  * array of `[package, exports]` for every surface that listed at least one
  * export, sorted by `package` (code unit order). A specifier that lists
  * nothing (unresolved, local, no value exports) is left out, so asking for a
- * subpath a version does not have changes nothing. Handler members are not
- * hashed. Type text already names
+ * subpath a version does not have changes nothing. Handler members, result
+ * candidates and scope receivers are not hashed. Type text already names
  * the request's directory as `<root>`.
  */
 export function fullSurfaceSha256(surfaces) {
@@ -772,10 +801,11 @@ export function fullSurfaceSha256(surfaces) {
         .filter(surface => surface.reason === undefined && surface.exports.length > 0)
         .map(surface => [surface.package, surface.exports])
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    // A member's `handlers` (carrick#2674) and a signature's `result_candidates`
-    // (carrick#2817) are out of the hash at every depth, so a package's key does
-    // not change when the lister learns to list them.
-    const text = JSON.stringify(listed, (key, value) => key === 'handlers' || key === 'result_candidates' ? undefined : value);
+    // A member's `handlers` (carrick#2674), a signature's `result_candidates`
+    // (carrick#2817) and a member's `scope_receiver` (carrick#2774) are out of
+    // the hash at every depth, so a package's key does not change when the
+    // lister learns to list them.
+    const text = JSON.stringify(listed, (key, value) => key === 'handlers' || key === 'result_candidates' || key === 'scope_receiver' ? undefined : value);
     return crypto.createHash('sha256').update(text).digest('hex');
 }
 function exportKey(check) {
@@ -928,6 +958,18 @@ function receiverExpression(local, receiver) {
         text = `${text}${parsed.scope.split('.').map(access).join('')}()`;
     return text;
 }
+/**
+ * The id of the receiver `member` of the receiver `receiver` returns when
+ * called with a path (carrick#2774): `receiver>scope:member`. Undefined for a
+ * receiver that is not an instance, or a member name the verifier's grammar
+ * does not read back as one scope step.
+ */
+function scopeReceiverId(receiver, member) {
+    if (!receiver.startsWith('instance:') || receiver.includes('>') || /[>.\s]/.test(member))
+        return undefined;
+    const id = `${receiver}>scope:${member}`;
+    return parseReceiver(id)?.scope === member ? id : undefined;
+}
 /** The symbols that say who declared a type: its own, its alias's, its parts'. */
 function typeSymbols(type) {
     const symbols = [type.getSymbol(), type.aliasSymbol];
@@ -1020,8 +1062,24 @@ class DeclarationReader {
     currentPackage = '';
     /** `declaredProperties` per type, for `currentPackage` (its augmentations decide them). */
     declared = new Map();
+    /**
+     * A handler parameter's listed members per type (`handlerMembersOf`), kept
+     * across every specifier of one package and cleared with `declared` when
+     * the package changes: a member's listing reads that package's
+     * augmentations (carrick#2977).
+     */
+    handlerMembers = new Map();
+    /** `takesString` per signature, and `scopeMembers` per type and home: the same types recur across receivers. */
+    takesStringRead = new Map();
+    scopeMembersRead = new Map();
+    /** Handler-parameter members `HANDLER_MEMBER_CAP` dropped in the package being listed. */
+    handlersDropped = 0;
+    /** Whether the package being listed lists each signature's `result_candidates`. */
+    listResultCandidates = false;
     /** The service root as given and as a realpath, longest first: what a listing prints as `<root>`. */
     printedRoots;
+    /** `printed` per type: its text reads nothing but the type and `printedRoots` (carrick#2977). */
+    printedTexts = new Map();
     constructor(program, probe, host, serviceRoot, scanRoot, graph) {
         this.program = program;
         this.probe = probe;
@@ -2045,6 +2103,10 @@ class DeclarationReader {
         const labels = claim.key_labels ?? {};
         let best;
         let held = false;
+        // An overload that holds but for a request member the declarations lack
+        // (carrick#2968): the op stands without its request, unless another
+        // overload holds the request too. Every other request fault fails the op.
+        let requestDropped;
         const bodyMembers = [];
         for (const signature of callee.signatures) {
             let result = this.messageSignatureOutcome(signature, layout.value, labels);
@@ -2055,19 +2117,26 @@ class DeclarationReader {
             }
             if (result.rank === Infinity && claim.request !== undefined) {
                 const read = this.requestOutcome(signature, claim.handler, claim.request, bodyMembers);
+                if (read?.verdict === 'failed' && read.reason === 'request_member_missing') {
+                    requestDropped = read.reason;
+                    continue;
+                }
                 if (read)
                     result = { rank: 5, outcome: read };
             }
             if (result.rank === Infinity) {
                 held = true;
+                requestDropped = undefined;
                 break;
             }
             best = furthest(best, result.rank, result.outcome);
         }
-        if (!held)
+        if (!held && requestDropped === undefined)
             return best.outcome;
-        if (boundRuns)
-            return this.boundRunsOutcome(receiver.makerHolding, boundRuns);
+        if (boundRuns) {
+            const ran = this.boundRunsOutcome(receiver.makerHolding, boundRuns);
+            return ran.verdict === 'verified' && requestDropped !== undefined ? { ...ran, requestDropped } : ran;
+        }
         const declarations = this.declarationsOf(callee);
         const members = callee.named
             ? (callee.named.property.declarations ?? [])
@@ -2077,6 +2146,7 @@ class DeclarationReader {
             ...(declarations.length > 0 ? { declarations } : {}),
             ...(members.length > 0 ? { members } : {}),
             ...(bodyMembers.length > 0 ? { bodyMembers } : {}),
+            ...(requestDropped === undefined ? {} : { requestDropped }),
         };
     }
     /**
@@ -3011,7 +3081,7 @@ class DeclarationReader {
      * `built` answers the probe's no-argument build of a receiver an export
      * makes, resolved, when the probe holds one.
      */
-    listPackage(pkg, probe, maxEntries, only, built) {
+    listPackage(pkg, probe, maxEntries, only, options, built) {
         this.setPackage(pkg);
         // Runtime modules on: a `node:` specifier is listed from the runtime's
         // types package, as the message roles read it.
@@ -3036,24 +3106,24 @@ class DeclarationReader {
             dropped += 1;
             return false;
         };
-        // Handler-parameter members (carrick#2674) have a cap of their own, so they
-        // take nothing from the main one: the listing, `truncated` and the hash are
-        // the ones the lister gave before handlers were listed.
-        let handlerBudget = maxEntries;
-        const takeHandler = () => {
-            if (handlerBudget <= 0)
-                return false;
-            handlerBudget -= 1;
-            return true;
-        };
+        // Handler-parameter members (carrick#2674) take nothing from the main cap,
+        // so the listing, `truncated` and the hash are the ones the lister gave
+        // before handlers were listed; each parameter has a cap of its own
+        // (`HANDLER_MEMBER_CAP`, carrick#2966).
+        this.handlersDropped = 0;
+        this.listResultCandidates = options.resultCandidates === true;
+        const withHandlers = options.handlers === true;
         // Four passes: every export and receiver, then every member name, then the
-        // members of each handler's parameters (carrick#2674), then signatures.
+        // members of each handler's parameters (carrick#2674; only when asked,
+        // carrick#2966), then signatures.
         const names = [];
         const handlers = [];
         const fills = [];
         // What the package's default export names: a maker also exported by name
         // under this declaration is imported the same way, so it is read the same.
         const defaultTarget = exported.find(each => each.name === 'default')?.target;
+        // The instance receivers listed, for the scope pass (carrick#2774).
+        const instances = [];
         for (const { name, target, type } of exported) {
             if (!take())
                 continue;
@@ -3065,7 +3135,11 @@ class DeclarationReader {
                 if (!take())
                     return;
                 const home = this.homeOf(pkg, [target, ...typeSymbols(receiverType)]);
-                entry.receivers.push(this.outlineReceiver(pkg, receiverName, receiverType, home, take, takeHandler, names, handlers, fills));
+                const receiver = this.outlineReceiver(pkg, receiverName, receiverType, home, take, names, handlers, fills);
+                entry.receivers.push(receiver);
+                if (receiverName.startsWith('instance:')) {
+                    instances.push({ export: name, target, type: receiverType, home, receiver });
+                }
             };
             receiverOf('export', type);
             for (const maker of this.makers(pkg, target, type)) {
@@ -3082,13 +3156,57 @@ class DeclarationReader {
         }
         for (const run of names)
             run();
-        for (const run of handlers)
-            run();
+        if (withHandlers)
+            for (const run of handlers)
+                run();
         for (const fill of fills)
             fill();
+        this.listScopeReceivers(pkg, instances, maxEntries, withHandlers, built);
         surface.truncated = dropped;
+        if (withHandlers)
+            surface.handlers_truncated = this.handlersDropped;
         return surface;
     }
+    /**
+     * The fifth pass (carrick#2774): each own member of an instance receiver
+     * whose call returns the object routes are registered on lists it as
+     * `scope_receiver`, outlined as any receiver is. Everything it lists draws
+     * on one budget of its own, spent after every other pass, so the listing
+     * without it, `truncated` and the hash are the ones the lister gave before.
+     * One level: a scope receiver lists no scope receiver of its own.
+     */
+    listScopeReceivers(pkg, sources, maxEntries, withHandlers, built) {
+        let budget = maxEntries;
+        const take = () => budget > 0 && (budget--, true);
+        const names = [];
+        const handlers = [];
+        const fills = [];
+        for (const source of sources) {
+            const holder = this.surfaceHolder(pkg, source.type, source.home);
+            for (const member of source.receiver.members) {
+                const id = member.own ? scopeReceiverId(source.receiver.receiver, member.name) : undefined;
+                if (id === undefined)
+                    continue;
+                const callee = this.ownCallee(holder, [], member.name, 'call');
+                if (!('signatures' in callee))
+                    continue;
+                if (!callee.signatures.some(signature => this.takesString(signature)))
+                    continue;
+                const type = this.scopeTypeOf(callee.signatures, built(source.export, id), source.type, source.home);
+                if (type === undefined || !take())
+                    continue;
+                const home = this.homeOf(pkg, [source.target, ...typeSymbols(type)]);
+                member.scope_receiver = this.outlineReceiver(pkg, id, type, home, take, names, handlers, fills);
+            }
+        }
+        for (const run of names)
+            run();
+        if (withHandlers)
+            for (const run of handlers)
+                run();
+        for (const fill of fills)
+            fill();
+    }
     /**
      * The receivers each export of a specifier can make, by receiver id, for
      * the probe statements that build them (see `LibraryClaimsVerifier.listSurface`).
@@ -3100,12 +3218,157 @@ class DeclarationReader {
             return [];
         return (this.listedExports(probe, only, moduleRead?.globalFile) ?? [])
             .filter(({ type }) => !this.isOpenTop(type))
-            .map(({ name, target, type }) => ({
-            export: name,
-            receivers: this.makers(pkg, target, type).map(maker => maker.receiver),
-        }))
+            .map(({ name, target, type }) => {
+            const makers = this.makers(pkg, target, type);
+            return {
+                export: name,
+                receivers: makers.map(maker => maker.receiver),
+                scopes: this.scopeCandidates(pkg, target, makers),
+            };
+        })
             .filter(({ receivers }) => receivers.length > 0);
     }
+    /**
+     * The `R>scope:m` receivers an export's `instance:` makers may have
+     * (carrick#2774): for each object type a maker's overloads declare as their
+     * return, each own member that `scopeTypeOf` lists at its declared return.
+     * A superset of the listing, which reads each at the type the probe's build
+     * resolves; the second program builds these so `listPackage` can.
+     */
+    scopeCandidates(pkg, target, makers) {
+        const found = new Set();
+        for (const maker of makers) {
+            if (!maker.receiver.startsWith('instance:'))
+                continue;
+            const types = new Set(maker.signatures.map(sig => this.checker.getReturnTypeOfSignature(sig)));
+            for (const type of types) {
+                if (this.returnSaysNothing(type) || !this.isObjectType(type))
+                    continue;
+                const home = this.homeOf(pkg, [target, ...typeSymbols(type)]);
+                for (const name of this.scopeMembers(pkg, type, home)) {
+                    const id = scopeReceiverId(maker.receiver, name);
+                    if (id !== undefined)
+                        found.add(id);
+                }
+            }
+        }
+        return [...found];
+    }
+    /** The members of `type` that list a scope receiver at their declared return, read once per type and home. */
+    scopeMembers(pkg, type, home) {
+        const key = [...home].sort().join('\u0000');
+        let byHome = this.scopeMembersRead.get(type);
+        if (byHome === undefined)
+            this.scopeMembersRead.set(type, (byHome = new Map()));
+        const read = byHome.get(key);
+        if (read !== undefined)
+            return read;
+        const names = [];
+        const holder = this.surfaceHolder(pkg, type, home);
+        for (const property of sortedByName(this.namedProperties(type))) {
+            if (!this.mayScope(property))
+                continue;
+            const callee = this.ownCallee(holder, [], property.getName(), 'call');
+            if ('signatures' in callee && this.scopeTypeOf(callee.signatures, undefined, type, home) !== undefined) {
+                names.push(property.getName());
+            }
+        }
+        byHome.set(key, names);
+        return names;
+    }
+    /** Some library signature of the member takes a string: the cheap superset of what `scopeTypeOf` asks first. */
+    mayScope(property) {
+        return this.librarySignatures(this.checker.getTypeOfSymbol(property), 'call').some(signature => this.takesString(signature));
+    }
+    /**
+     * The object a scope member returns, as the verifier reads a scope step
+     * (carrick#2774): what a route is registered on when the member is called
+     * with a path. Undefined unless:
+     * - some own signature takes a string, positionally or at a key of an
+     *   object parameter;
+     * - the returns (at `built`'s defaults, less those that say nothing) are
+     *   all object types, none thenable, sharing one declared symbol that is
+     *   declared in the receiver's home and has a callable member of its own;
+     * - that symbol and the receiver's share no declaration in the home
+     *   (`family`): the receiver itself (`basePath(): this`), a sibling or a
+     *   wrapper of one base is a builder's next link, not an object routes
+     *   are registered on.
+     * The type is the return of the overload `built` resolves, when that is
+     * one of the signatures that take a string, else the first of them.
+     */
+    scopeTypeOf(signatures, built, receiver, home) {
+        const takers = signatures.filter(signature => this.takesString(signature));
+        const returns = takers
+            .map(signature => ({ signature, type: this.returnOf(signature, built) }))
+            .filter(({ type }) => !this.returnSaysNothing(type));
+        if (returns.length === 0)
+            return undefined;
+        const symbolOf = (type) => type.getSymbol() ?? type.aliasSymbol;
+        const symbol = symbolOf(returns[0].type);
+        if (symbol === undefined)
+            return undefined;
+        // The receiver itself, a sibling of it, or a wrapper built from the same
+        // base (a fluent builder's `.default(x)`) is the same kind of thing, not
+        // an object routes are registered on: abstain.
+        const mine = this.family(receiver, home);
+        if ([...this.family(returns[0].type, home)].some(each => mine.has(each)))
+            return undefined;
+        for (const { type } of returns) {
+            if (!this.isObjectType(type) || symbolOf(type) !== symbol || this.isThenable(type))
+                return undefined;
+        }
+        if (!(symbol.declarations ?? []).some(declaration => this.isOwnFile(declaration.getSourceFile(), home)))
+            return undefined;
+        const chosen = returns.find(({ signature }) => built !== undefined && this.instantiates(built, signature)) ?? returns[0];
+        const callable = this.namedProperties(chosen.type).some(member => this.librarySignatures(this.checker.getTypeOfSymbol(member), 'call').length > 0);
+        return callable ? chosen.type : undefined;
+    }
+    /** The type's own declaration and every base it extends or implements that its home declares. */
+    family(type, home) {
+        const found = new Set();
+        const visit = (each, depth) => {
+            const target = (each.objectFlags ?? 0) & ts.ObjectFlags.Reference ? each.target : each;
+            const symbol = target.getSymbol();
+            if (symbol === undefined || found.has(symbol) || depth > 12)
+                return;
+            if (!(symbol.declarations ?? []).some(declaration => this.isOwnFile(declaration.getSourceFile(), home)))
+                return;
+            found.add(symbol);
+            if ((target.objectFlags ?? 0) & ts.ObjectFlags.ClassOrInterface) {
+                for (const base of this.checker.getBaseTypes(target))
+                    visit(base, depth + 1);
+            }
+        };
+        visit(type, 0);
+        return found;
+    }
+    /** A parameter of the signature accepts a string, positionally or at a key of its object. */
+    takesString(signature) {
+        let read = this.takesStringRead.get(signature);
+        if (read === undefined)
+            this.takesStringRead.set(signature, (read = this.readTakesString(signature)));
+        return read;
+    }
+    readTakesString(signature) {
+        const count = signature.getParameters().length;
+        for (let index = 0; index < count; index++) {
+            const slot = this.keyParameterAt(signature, index);
+            if (slot === undefined || slot === VARIADIC)
+                continue;
+            if (this.acceptsString(this.throughConditional(slot)))
+                return true;
+            if (this.isObjectType(slot) && this.handlerFailure(slot) !== undefined) {
+                if (this.listKeys(slot, () => true).some(key => key.accepts_string))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /** The type has a callable `then`: awaiting it gives something else. */
+    isThenable(type) {
+        const then = this.checker.getPropertyOfType(type, 'then');
+        return then !== undefined && this.checker.getNonNullableType(this.checker.getTypeOfSymbol(then)).getCallSignatures().length > 0;
+    }
     /**
      * The value exports a specifier lists (every one, or only those `only`
      * names), sorted by name: what its namespace holds, and `default` for a
@@ -3232,7 +3495,7 @@ class DeclarationReader {
      * parameters next (`handlers`), once every name is; its call, construct and
      * member signatures last (`fills`), once every handler is.
      */
-    outlineReceiver(pkg, receiverName, type, home, take, takeHandler, names, handlers, fills) {
+    outlineReceiver(pkg, receiverName, type, home, take, names, handlers, fills) {
         const receiver = { receiver: receiverName, members: [] };
         const holder = this.surfaceHolder(pkg, type, home);
         // The receiver's own call and construct signatures, as a claim with a
@@ -3260,7 +3523,7 @@ class DeclarationReader {
                 const member = { name: property.getName(), own, signatures: [] };
                 receiver.members.push(member);
                 handlers.push(() => {
-                    const listed = this.listHandlers(own ? callee.signatures : library, takeHandler);
+                    const listed = this.listHandlers(own ? callee.signatures : library);
                     if (listed.length > 0)
                         member.handlers = listed;
                 });
@@ -3276,14 +3539,14 @@ class DeclarationReader {
      * A parameter that declares no member lists nothing, and so does a handler
      * none of whose parameters do.
      */
-    listHandlers(signatures, take) {
+    listHandlers(signatures) {
         const listed = [];
         const seen = new Set();
         const add = (arg, key, slot) => {
             const place = JSON.stringify([arg, key ?? null]);
             if (seen.has(place))
                 return;
-            const params = this.listHandlerParams(slot, take);
+            const params = this.listHandlerParams(slot);
             if (params.length === 0)
                 return;
             seen.add(place);
@@ -3315,8 +3578,8 @@ class DeclarationReader {
         }
         return listed;
     }
-    /** The parameters of a function type's first signature that declare members, each member counting against the cap. */
-    listHandlerParams(handler, take) {
+    /** The parameters of a function type's first signature that declare members, each with its members (`handlerMembersOf`). */
+    listHandlerParams(handler) {
         const slot = this.throughConditional(this.throughConstraint(handler));
         if (slot === VARIADIC)
             return [];
@@ -3328,32 +3591,73 @@ class DeclarationReader {
         const listed = [];
         signature.getParameters().forEach((parameter, index) => {
             const type = this.checker.getTypeOfSymbol(parameter);
-            if (this.namedProperties(type).length === 0 || !take())
+            if (this.namedProperties(type).length === 0)
                 return;
-            const members = [];
-            this.listMembers(type, [], members, take);
+            const { members, dropped } = this.handlerMembersOf(type);
+            this.handlersDropped += dropped;
             listed.push({ param: index, name: parameter.getName(), type: this.printed(type), members });
         });
         return listed;
     }
-    /** A type's declared members by path, parents before children, each level sorted by name, down to `HANDLER_MEMBER_DEPTH`. */
-    listMembers(type, prefix, into, take) {
-        for (const property of sortedByName(this.namedProperties(type))) {
-            if (!take())
-                continue;
-            const memberType = this.checker.getTypeOfSymbol(property);
-            const path = [...prefix, property.getName()];
-            const callable = this.librarySignatures(memberType, 'call').length > 0;
-            into.push({
-                path,
-                type: this.printed(memberType),
-                optional: (property.flags & ts.SymbolFlags.Optional) !== 0,
-                function: callable,
-            });
-            if (!callable && path.length < HANDLER_MEMBER_DEPTH && this.isObjectType(memberType)) {
-                this.listMembers(memberType, path, into, take);
+    /**
+     * A handler parameter's declared members by path, down to
+     * `HANDLER_MEMBER_DEPTH`, at most `HANDLER_MEMBER_CAP` of them (carrick#2966).
+     * The cap keeps every top-level member before any nested one, so a wide
+     * parameter loses its deepest members, never a top-level one a later member
+     * name sorts after. Kept members come back parents before children, each
+     * level sorted by name. Read once per type in a package, across its
+     * specifiers: a type many handlers share is listed once.
+     */
+    handlerMembersOf(type) {
+        const known = this.handlerMembers.get(type);
+        if (known)
+            return known;
+        surfaceReadCounts.handlerMemberBuilds += 1;
+        const roots = [];
+        let kept = 0;
+        let dropped = 0;
+        // Breadth first: a level is kept whole, in name order, before the next.
+        let level = [{ type, prefix: [], into: roots }];
+        while (level.length > 0) {
+            const next = [];
+            for (const { type: holder, prefix, into } of level) {
+                for (const property of sortedByName(this.namedProperties(holder))) {
+                    if (kept >= HANDLER_MEMBER_CAP) {
+                        dropped += 1;
+                        continue;
+                    }
+                    kept += 1;
+                    const memberType = this.checker.getTypeOfSymbol(property);
+                    const path = [...prefix, property.getName()];
+                    const callable = this.librarySignatures(memberType, 'call').length > 0;
+                    const node = {
+                        member: {
+                            path,
+                            type: this.printed(memberType),
+                            optional: (property.flags & ts.SymbolFlags.Optional) !== 0,
+                            function: callable,
+                        },
+                        children: [],
+                    };
+                    into.push(node);
+                    if (!callable && path.length < HANDLER_MEMBER_DEPTH && this.isObjectType(memberType)) {
+                        next.push({ type: memberType, prefix: path, into: node.children });
+                    }
+                }
             }
+            level = next;
         }
+        const members = [];
+        const emit = (nodes) => {
+            for (const node of nodes) {
+                members.push(node.member);
+                emit(node.children);
+            }
+        };
+        emit(roots);
+        const listed = { members, dropped };
+        this.handlerMembers.set(type, listed);
+        return listed;
     }
     listSignatures(signatures, holder, take) {
         const listed = [];
@@ -3391,7 +3695,7 @@ class DeclarationReader {
                 params.push(param);
             }
             const entry = { params, returns: this.printed(this.checker.getReturnTypeOfSignature(signature)) };
-            const candidates = resultCandidatesOf(this.checker, signature);
+            const candidates = this.listResultCandidates ? resultCandidatesOf(this.checker, signature) : undefined;
             if (candidates !== undefined)
                 entry.result_candidates = candidates;
             listed.push(entry);
@@ -3441,9 +3745,15 @@ class DeclarationReader {
      * so where the cut falls does not depend on where the package is installed.
      */
     printed(type) {
+        const known = this.printedTexts.get(type);
+        if (known !== undefined)
+            return known;
+        surfaceReadCounts.typePrints += 1;
         const node = this.checker.typeToTypeNode(type, undefined, PRINT_FLAGS);
         const text = node === undefined ? this.checker.typeToString(type) : printTypeNode(this.orderUnions(node));
-        return truncate(this.scrubbed(text));
+        const listed = truncate(this.scrubbed(text));
+        this.printedTexts.set(type, listed);
+        return listed;
     }
     /** `text` with the service root written as `<root>`. */
     scrubbed(text) {
@@ -3617,8 +3927,10 @@ class DeclarationReader {
     /** Judge the next check as a claim about `pkg`. */
     setPackage(pkg) {
         const named = packageNameOf(pkg);
-        if (named !== this.currentPackage)
+        if (named !== this.currentPackage) {
             this.declared.clear();
+            this.handlerMembers.clear();
+        }
         this.currentPackage = named;
     }
     /**
@@ -3911,6 +4223,12 @@ class DeclarationReader {
  */
 /** The longest member path a handler parameter's members are listed to (`['raw', 'url']`). */
 const HANDLER_MEMBER_DEPTH = 2;
+/**
+ * The most members one handler parameter lists (carrick#2966), top-level
+ * first. The store's server question shows at most 300 of them in the same
+ * order, so this must stay at least that.
+ */
+const HANDLER_MEMBER_CAP = 500;
 const PRINT_FLAGS = ts.NodeBuilderFlags.AllowUniqueESSymbolType |
     ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope |
     ts.NodeBuilderFlags.IgnoreErrors |

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

@@ -679,6 +679,10 @@ export interface ListLibrarySurfaceRequest extends BaseRequest {
     max_entries?: number;
     /** Per package, the only exports to list (the ones the service imports); absent lists every value export. */
     exports?: Record<string, string[]>;
+    /** List each member's handler-parameter members (`handlers`, carrick#2674 S3); default false (carrick#2966). */
+    handlers?: boolean;
+    /** List each signature's `result_candidates` (carrick#2817); default false (carrick#2966). */
+    result_candidates?: boolean;
 }
 /**
  * Union type for all possible sidecar requests
@@ -982,6 +986,12 @@ export interface SemanticsResult {
     reason?: string;
     /** Verified op verdicts only: the declarations its member resolves to on the receiver. */
     declarations?: SemanticsDeclaration[];
+    /**
+     * Verified receive op verdicts only: the op verified but its `request`
+     * names a member the declarations lack, so the request is dropped and the
+     * route kept (carrick#2968). The reason, `request_member_missing`.
+     */
+    request_dropped?: string;
 }
 /** How one package of the request resolved, for logs. */
 export interface SemanticsModule {
@@ -1032,8 +1042,9 @@ export interface SurfaceSignature {
     returns: string;
     /**
      * Which parts of the awaited return could hold the response body
-     * (carrick#2817). Left out of the surface hash. Absent when the signature
-     * returns nothing.
+     * (carrick#2817). Left out of the surface hash. Listed only on a
+     * `result_candidates: true` request (carrick#2966); absent when the
+     * signature returns nothing.
      */
     result_candidates?: SurfaceResultCandidates;
 }
@@ -1065,9 +1076,17 @@ export interface SurfaceMember {
     /**
      * The members the parameters of a function this member takes declare
      * (carrick#2674): what a receive op's `request` field names its member
-     * paths in. Under a cap of their own, apart from the main one.
+     * paths in. Listed only on a `handlers: true` request, under a cap of
+     * their own: 500 members per parameter, top-level first (carrick#2966).
      */
     handlers?: SurfaceHandler[];
+    /**
+     * The object this member returns when called with a path, listed as a
+     * receiver (id `R>scope:m`) when routes are registered on it (carrick#2774).
+     * Instance receivers only, one level, under a cap of its own, and left out
+     * of the hash.
+     */
+    scope_receiver?: SurfaceReceiver;
     signatures: SurfaceSignature[];
 }
 /**
@@ -1116,6 +1135,11 @@ export interface LibrarySurface {
     reason?: string;
     /** Entries dropped by `max_entries`. */
     truncated: number;
+    /**
+     * With `handlers: true`, the handler-parameter members dropped by the cap of
+     * 500 per parameter (carrick#2966), summed over every listed parameter.
+     */
+    handlers_truncated?: number;
     exports: SurfaceExport[];
 }
 export interface ListLibrarySurfaceResponse extends BaseResponse {

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

@@ -2810,11 +2810,15 @@ export declare const ListLibrarySurfaceRequestSchema: z.ZodObject<{
     packages: z.ZodArray<z.ZodString, "many">;
     max_entries: z.ZodOptional<z.ZodNumber>;
     exports: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    handlers: z.ZodOptional<z.ZodBoolean>;
+    result_candidates: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     packages: string[];
     request_id: string;
     action: "list_library_surface";
     from_dir: string;
+    handlers?: boolean | undefined;
+    result_candidates?: boolean | undefined;
     max_entries?: number | undefined;
     exports?: Record<string, string[]> | undefined;
 }, {
@@ -2822,6 +2826,8 @@ export declare const ListLibrarySurfaceRequestSchema: z.ZodObject<{
     request_id: string;
     action: "list_library_surface";
     from_dir: string;
+    handlers?: boolean | undefined;
+    result_candidates?: boolean | undefined;
     max_entries?: number | undefined;
     exports?: Record<string, string[]> | undefined;
 }>;
@@ -5388,11 +5394,15 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     packages: z.ZodArray<z.ZodString, "many">;
     max_entries: z.ZodOptional<z.ZodNumber>;
     exports: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    handlers: z.ZodOptional<z.ZodBoolean>;
+    result_candidates: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     packages: string[];
     request_id: string;
     action: "list_library_surface";
     from_dir: string;
+    handlers?: boolean | undefined;
+    result_candidates?: boolean | undefined;
     max_entries?: number | undefined;
     exports?: Record<string, string[]> | undefined;
 }, {
@@ -5400,6 +5410,8 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     request_id: string;
     action: "list_library_surface";
     from_dir: string;
+    handlers?: boolean | undefined;
+    result_candidates?: boolean | undefined;
     max_entries?: number | undefined;
     exports?: Record<string, string[]> | undefined;
 }>, z.ZodObject<{

package/sidecar/dist/src/validators.js

@@ -588,6 +588,8 @@ export const ListLibrarySurfaceRequestSchema = BaseRequestSchema.extend({
     packages: z.array(z.string().min(1)),
     max_entries: z.number().int().positive().optional(),
     exports: z.record(z.string(), z.array(z.string().min(1))).optional(),
+    handlers: z.boolean().optional(),
+    result_candidates: z.boolean().optional(),
 });
 // ============================================================================
 // Discriminated Union Schema