carrick 0.3.133 → 0.3.135

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 { holdsResult, resultCandidatesOf } from './result-candidates.js';
 import { PathNames, declaringFileName } from './position-rows.js';
 import { memberDeclaration } from './declaration-attribution.js';
 /** The methods a `verb` claim may name, and a method key may accept. */
@@ -258,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;
@@ -280,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,
@@ -586,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')
@@ -594,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 };
             };
@@ -644,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;
@@ -677,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
@@ -708,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;
@@ -721,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]);
         })));
@@ -762,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) {
@@ -771,9 +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) is 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' ? 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) {
@@ -926,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];
@@ -1018,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;
@@ -1365,6 +1425,8 @@ class DeclarationReader {
      * `claim_invalid`.
      */
     judgeHttp(receiver, claim) {
+        if (claim.kind === 'result')
+            return this.judgeHttpResult(receiver, claim);
         if (claim.kind === 'make') {
             const base = claim.base;
             if (claim.form !== 'call' ||
@@ -1624,7 +1686,37 @@ class DeclarationReader {
                 return { outcome: this.judgeOp(receiver, claim, rules) };
             case 'reserved':
                 return { outcome: this.judgeReserved(receiver, claim) };
+            case 'result':
+                return { outcome: this.resultOutcome(this.ownCallee(receiver, claim.path ?? [], claim.member, 'call'), claim.result) };
+        }
+    }
+    /**
+     * A `result` claim (carrick#2817): the claimed result is a candidate of at
+     * least one signature the callee declares, by rule R (`result-candidates.ts`).
+     * Anything else, including a call that returns nothing, is
+     * `result_not_candidate`.
+     */
+    resultOutcome(callee, shape) {
+        if ('failure' in callee)
+            return callee.failure;
+        for (const signature of callee.signatures) {
+            const candidates = resultCandidatesOf(this.checker, signature);
+            if (candidates !== undefined && holdsResult(candidates, shape))
+                return VERIFIED;
         }
+        return failed('result_not_candidate');
+    }
+    /** A `result` claim on an HTTP receiver: `path` walked from it, then `member` of what that reaches. */
+    judgeHttpResult(receiver, claim) {
+        let holder = receiver;
+        for (const hop of claim.path ?? []) {
+            const property = this.declaredProperty(holder, hop);
+            if (!property)
+                return failed('member_missing');
+            holder = this.checker.getTypeOfSymbol(property);
+        }
+        const callee = claim.member === null ? this.callSignatures(holder) : this.callableProperty(holder, claim.member);
+        return this.resultOutcome(callee, claim.result);
     }
     /**
      * `member` (or the export itself, when null) is callable (`call`) or
@@ -2011,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);
@@ -2021,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 ?? [])
@@ -2043,6 +2146,7 @@ class DeclarationReader {
             ...(declarations.length > 0 ? { declarations } : {}),
             ...(members.length > 0 ? { members } : {}),
             ...(bodyMembers.length > 0 ? { bodyMembers } : {}),
+            ...(requestDropped === undefined ? {} : { requestDropped }),
         };
     }
     /**
@@ -2977,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.
@@ -3002,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;
@@ -3031,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)) {
@@ -3048,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`).
@@ -3066,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
@@ -3198,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
@@ -3226,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;
                 });
@@ -3242,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);
@@ -3281,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 [];
@@ -3294,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 = [];
@@ -3356,7 +3694,11 @@ class DeclarationReader {
                     param.literals = [...literals].sort();
                 params.push(param);
             }
-            listed.push({ params, returns: this.printed(this.checker.getReturnTypeOfSignature(signature)) });
+            const entry = { params, returns: this.printed(this.checker.getReturnTypeOfSignature(signature)) };
+            const candidates = this.listResultCandidates ? resultCandidatesOf(this.checker, signature) : undefined;
+            if (candidates !== undefined)
+                entry.result_candidates = candidates;
+            listed.push(entry);
         }
         return listed;
     }
@@ -3403,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) {
@@ -3579,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;
     }
     /**
@@ -3873,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 |