carrick 0.3.127 → 0.3.128

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

@@ -130,6 +130,14 @@ const HTTP_V2_RULES = { http: false, message: true, ops: new Set(['request']), m
  * the method from the member's own name (`get` registers GET) or from a slot.
  */
 const SERVER_RULES = { http: false, message: true, ops: new Set(['receive']), methods: ROUTE_METHODS };
+/**
+ * A server's rules as `labelledMembers` reads them (carrick#2674): a `send`
+ * op is the reply a handler sends back through its reply parameter, on the
+ * connection the request came in on, so it names nothing on the wire. Only
+ * the stated-parameter reading takes these; `run` keeps `SERVER_RULES`, so
+ * no verdict the scanner reads rows from changes.
+ */
+const SERVER_REPLY_RULES = { ...SERVER_RULES, ops: new Set(['receive', 'send']), namelessSends: true };
 /**
  * The role table: the role alone picks the checks. A role this build does
  * not read yet (GraphQL executors) answers `role_unsupported`, and `none`
@@ -263,7 +271,8 @@ export class LibraryClaimsVerifier {
      * A check on an instance or a scope reads the maker or scope claims of the
      * same request first, whatever their place in it.
      */
-    run(fromDir, checks, budgetMs, scanRoot) {
+    run(fromDir, checks, budgetMs, scanRoot, options = {}) {
+        const { observe, readReplies = false, typePackages = {} } = options;
         const deadline = performance.now() + budgetMs;
         const stamp = (check, outcome) => outcome.verdict === 'verified'
             ? {
@@ -294,7 +303,11 @@ export class LibraryClaimsVerifier {
             if (check.role === 'http_client' && hasV2Field(check.claim))
                 v2Exports.add(exportKey(check));
         }
-        const rulesFor = (check) => check.role === 'http_client' && v2Exports.has(exportKey(check)) ? HTTP_V2_RULES : ROLE_TABLE[check.role];
+        const rulesFor = (check) => check.role === 'http_client' && v2Exports.has(exportKey(check))
+            ? HTTP_V2_RULES
+            : readReplies && check.role === 'server_framework'
+                ? SERVER_REPLY_RULES
+                : ROLE_TABLE[check.role];
         for (const check of checks) {
             const key = exportKey(check);
             if (!importIndex.has(key)) {
@@ -448,14 +461,19 @@ export class LibraryClaimsVerifier {
                 if (types.some(type => reader.returnSaysNothing(type))) {
                     return { reason: receiverPath.maker ? 'maker_unresolved' : 'export_untyped' };
                 }
+                const claim = check.claim;
+                const keyBound = claim.kind === 'op' && claim.name !== undefined && 'bound' in claim.name && claim.name.bound === 'key'
+                    ? verifiedCollects(check.package).length > 0
+                    : undefined;
                 return {
                     value: types.map(type => ({
                         type,
                         pkg: check.package,
-                        home: reader.homeOf(check.package, [exported.target, ...typeSymbols(type)]),
+                        home: withTypePackages(reader.homeOf(check.package, [exported.target, ...typeSymbols(type)]), typePackages[check.package]),
                         makerBindsName,
                         scoped: receiverPath.scope !== undefined,
                         makerHolding,
+                        ...(keyBound === undefined ? {} : { keyBound }),
                         madeBy: receiverPath.maker?.member === null && receiverPath.scope === undefined ? check.export : undefined,
                     })),
                 };
@@ -480,6 +498,32 @@ export class LibraryClaimsVerifier {
                     return { reason: 'unresolved' };
                 return { value: returns };
             };
+            /**
+             * The `collects` scope checks of the request (#2474 R6a) that verify,
+             * of one package or of any: judged only when a claim reads them, so a
+             * request with none judges exactly what it judged before.
+             */
+            const verifiedCollects = (pkg) => checks
+                .map((other, i) => ({ other, i }))
+                .filter(({ other }) => other.claim.kind === 'scope' && other.claim.collects !== undefined && (pkg === undefined || other.package === pkg))
+                .filter(({ i }) => judge(i).outcome.verdict === 'verified')
+                .map(({ i }) => i);
+            /**
+             * What the request's verified `collects` scopes return, read at their
+             * defaults: the collections an adapter's `runs` slot can take, matched
+             * across packages (an HTTP framework's adapter serves another
+             * package's router). Undefined when there are none.
+             */
+            const collections = () => {
+                const types = new Set();
+                for (const i of verifiedCollects()) {
+                    const built = builtReceiver(checks[i]);
+                    const read = holdingReturns([judge(i)], built === undefined ? undefined : atDefaults(checks[i], built));
+                    if ('value' in read)
+                        read.value.forEach(type => types.add(type));
+                }
+                return types.size > 0 ? [...types] : undefined;
+            };
             const judge = (index) => {
                 const cached = judged.get(index);
                 if (cached)
@@ -535,16 +579,28 @@ export class LibraryClaimsVerifier {
                     return { outcome: unchecked(receivers.reason) };
                 const built = builtReceiver(check);
                 const builtAtDefaults = built === undefined ? undefined : atDefaults(check, built);
+                // An adapter's `runs` is read against the request's collections only
+                // when today's reading refuses it (#2474 R6a): `judgeMake` asks.
+                const collectionsOf = check.claim.kind === 'make' && check.claim.runs !== undefined ? collections : undefined;
                 const holding = [];
                 const declarations = [];
+                const members = [];
+                const bodyMembers = [];
                 for (const receiver of receivers.value) {
-                    const result = reader.judgeMessage(receiver, check.claim, rules, builtAtDefaults);
+                    const result = reader.judgeMessage(receiver, check.claim, rules, builtAtDefaults, collectionsOf);
                     if (result.outcome.verdict !== 'verified')
                         return result;
                     holding.push(...(result.holding ?? []));
                     declarations.push(...(result.outcome.declarations ?? []));
+                    members.push(...(result.outcome.members ?? []));
+                    bodyMembers.push(...(result.outcome.bodyMembers ?? []));
                 }
-                return { outcome: declarations.length > 0 ? { verdict: 'verified', declarations: sortedDeclarations(declarations) } : VERIFIED, holding };
+                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)
+                    verified.bodyMembers = bodyMembers;
+                return { outcome: verified, holding };
             };
             const semantics = [];
             for (let index = 0; index < checks.length; index++) {
@@ -553,7 +609,9 @@ export class LibraryClaimsVerifier {
                     semantics.push(stamp(check, unchecked('budget')));
                     continue;
                 }
-                semantics.push(stamp(check, judge(index).outcome));
+                const outcome = judge(index).outcome;
+                observe?.(check, outcome);
+                semantics.push(stamp(check, outcome));
             }
             return {
                 semantics,
@@ -564,6 +622,42 @@ export class LibraryClaimsVerifier {
             this.project.removeSourceFile(probe);
         }
     }
+    /**
+     * The members a service's server-framework labels name, read with the
+     * verifier itself so only a label that verifies in the service's own
+     * program counts (carrick#2674): each verified `send` op that carries a
+     * `payload` slot, and each verified `receive` op whose `request` names a
+     * `body` path. Other checks are not judged.
+     */
+    labelledMembers(fromDir, checks, budgetMs, scanRoot, typePackages = {}) {
+        const sends = new Map();
+        const bodies = new Set();
+        const wanted = checks.filter(check => check.role === 'server_framework' &&
+            check.claim.kind === 'op' &&
+            ((check.claim.op === 'send' && check.claim.payload !== undefined) ||
+                (check.claim.op === 'receive' && check.claim.request?.body !== undefined)));
+        // A receiver an op is read on can need the maker or scope claims beside it.
+        const context = checks.filter(check => check.role === 'server_framework' && (check.claim.kind === 'make' || check.claim.kind === 'scope'));
+        if (wanted.length === 0)
+            return { sends, bodies };
+        const outcomes = {};
+        const observe = (check, outcome) => {
+            if (check.claim.kind !== 'op')
+                return;
+            const read = outcome.verdict === 'verified' ? 'verified' : `${outcome.verdict} ${outcome.reason}`;
+            outcomes[read] = (outcomes[read] ?? 0) + 1;
+            if (outcome.verdict !== 'verified')
+                return;
+            if (check.claim.op === 'send' && check.claim.payload !== undefined) {
+                for (const member of outcome.members ?? [])
+                    sends.set(declarationKey(member), check.claim.payload);
+            }
+            for (const member of outcome.bodyMembers ?? [])
+                bodies.add(declarationKey(member));
+        };
+        this.run(fromDir, [...context, ...wanted], budgetMs, scanRoot, { observe, readReplies: true, typePackages });
+        return { sends, bodies, outcomes };
+    }
     /**
      * Each specifier's declared surface, read with the verifier's predicates
      * (carrick#1660): every value export (or only those `only` names for the
@@ -668,7 +762,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. Type text already names
+ * subpath a version does not have changes nothing. Handler members are not
+ * hashed. Type text already names
  * the request's directory as `<root>`.
  */
 export function fullSurfaceSha256(surfaces) {
@@ -676,7 +771,10 @@ 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));
-    return crypto.createHash('sha256').update(JSON.stringify(listed)).digest('hex');
+    // 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));
+    return crypto.createHash('sha256').update(text).digest('hex');
 }
 function exportKey(check) {
     return JSON.stringify([check.package, check.export]);
@@ -733,17 +831,31 @@ function placementInvalid(claim) {
     return of === undefined || (of.maker === undefined && of.scope === undefined);
 }
 /**
- * Where a handler's request holds its path and method (#2474 R0) is read on
- * a receive op with a handler, and names `path` or `url`; every member path
- * it gives is non-empty.
+ * Where a handler's request holds its path, method and body (#2474 R0,
+ * carrick#2674) is read on a receive op with a handler, and names `path`,
+ * `url` or `body`; every member path it gives is non-empty.
  */
 function requestAtValid(claim) {
     const request = claim.request;
     if (claim.op !== 'receive' || claim.handler === undefined)
         return false;
-    if (request.path === undefined && request.url === undefined)
+    if (request.path === undefined && request.url === undefined && request.body === undefined)
         return false;
-    return [request.path, request.url, request.method].every(members => members === undefined || members.length > 0);
+    return [request.path, request.url, request.method, request.body].every(members => members === undefined || members.length > 0);
+}
+/** A receiver's home packages, with the type-only packages the store lists for its package. */
+function withTypePackages(home, typePackages) {
+    return typePackages && typePackages.length > 0 ? new Set([...home, ...typePackages]) : home;
+}
+/**
+ * A declaration's key within one process: its file as the compiler names it
+ * and its start. Two programs of one project name a declaration alike, so a
+ * label read in the verifier's probe program joins a member read in the
+ * inferrer's (carrick#2674).
+ */
+export function declarationKey(declaration) {
+    const file = declaration.getSourceFile();
+    return `${file.fileName}:${declaration.getStart(file)}`;
 }
 /**
  * A message check names a receiver its claim can be read on (contract
@@ -1502,10 +1614,10 @@ class DeclarationReader {
      * overloads it holds on. `built` is the probe's no-argument build of the
      * receiver a maker or scope claim makes (see `returnOf`).
      */
-    judgeMessage(receiver, claim, rules, built) {
+    judgeMessage(receiver, claim, rules, built, collections) {
         switch (claim.kind) {
             case 'make':
-                return this.judgeMake(receiver, claim, built);
+                return this.judgeMake(receiver, claim, built, collections);
             case 'scope':
                 return this.judgeScope(receiver, claim, built);
             case 'op':
@@ -1523,8 +1635,15 @@ class DeclarationReader {
      * defaults (`returnOf`). Those overloads are the ones an instance is read
      * through. A definition (`task({ id, run })`) is a maker with a `name` and a
      * `handler` slot; a queue (`new Queue("emails")`) one with a positional name.
-     */
-    judgeMake(receiver, claim, built) {
+     *
+     * An adapter (#2474 R6a, contract amendment 3 on carrick#2434) is a maker
+     * whose `runs` slot takes a collection rather than a function. Today's
+     * reading runs first, unchanged; only an overload it refuses on `runs` is
+     * read again, when the request holds verified `collects` scopes
+     * (`collections`), with `runs` taking what one of them returns
+     * (`runsCollectionOutcome`). With no such scope this arm never runs.
+     */
+    judgeMake(receiver, claim, built, collections) {
         const layout = this.layout({
             base: claim.base,
             prefix: claim.prefix,
@@ -1542,6 +1661,12 @@ class DeclarationReader {
         let best;
         for (const signature of callee.signatures) {
             let result = this.messageSignatureOutcome(signature, layout.value, labels);
+            if (result.outcome.verdict !== 'verified' && result.outcome.reason.startsWith('runs_') && collections !== undefined) {
+                const collected = collections();
+                if (collected !== undefined) {
+                    result = this.messageSignatureOutcome(signature, layout.value, labels, declared => this.runsCollectionOutcome(signature, declared, collected));
+                }
+            }
             if (result.rank === Infinity && this.returnSaysNothing(this.returnOf(signature, built))) {
                 result = { rank: 6, outcome: unchecked('maker_unresolved') };
             }
@@ -1570,12 +1695,23 @@ class DeclarationReader {
      * overloads: a `>scope:` receiver read through it is not resolved.
      * `runs` without `yields` (or the reverse), or `mounts` beside either, is
      * `claim_invalid`.
+     *
+     * Procedure routers (#2474 R6a, contract amendment 3 on carrick#2434): a
+     * scope carries exactly one of `name` and `collects`, and `collects` never
+     * beside `runs`, `yields` or `mounts` (`claim_invalid`). With `collects`
+     * the member takes an object of procedures there (`collectsOutcome`), and
+     * its return, the collection, is read as a plain scope's is.
      */
     judgeScope(receiver, claim, built) {
         if ((claim.runs === undefined) !== (claim.yields === undefined))
             return { outcome: unchecked('claim_invalid') };
         if (claim.mounts !== undefined && claim.runs !== undefined)
             return { outcome: unchecked('claim_invalid') };
+        if ((claim.name === undefined) === (claim.collects === undefined))
+            return { outcome: unchecked('claim_invalid') };
+        if (claim.collects !== undefined && (claim.runs !== undefined || claim.mounts !== undefined)) {
+            return { outcome: unchecked('claim_invalid') };
+        }
         const binds = claim.runs !== undefined || claim.mounts !== undefined;
         const layout = this.layout({ name: claim.name, runs: claim.runs, mounts: claim.mounts });
         if ('failure' in layout)
@@ -1598,6 +1734,11 @@ class DeclarationReader {
                 if (mounted)
                     result = { rank: 5, outcome: mounted };
             }
+            if (result.rank === Infinity && claim.collects !== undefined) {
+                const collected = this.collectsOutcome(signature, claim.collects);
+                if (collected)
+                    result = { rank: 5, outcome: collected };
+            }
             if (result.rank === Infinity && !binds && this.returnSaysNothing(this.returnOf(signature, built))) {
                 result = { rank: 6, outcome: unchecked('scope_unresolved') };
             }
@@ -1646,6 +1787,63 @@ class DeclarationReader {
             return erased ? undefined : failed('mounts_not_instance');
         return this.checker.isTypeAssignableTo(receiver.type, slot) ? undefined : failed('mounts_not_instance');
     }
+    /**
+     * `collects: { arg, key?, join }` on a scope (#2474 R6a): the parameter
+     * there is an object type that is not a function, whose keys name the
+     * procedures. A parameter typed `any`, `unknown`, `{}` or by an
+     * unconstrained type parameter says nothing (`collects_untyped`).
+     * Undefined when it holds.
+     */
+    collectsOutcome(signature, collects) {
+        let declared = this.keyParameterAt(signature, collects.arg);
+        if (declared !== undefined && collects.key !== undefined) {
+            const property = this.declaredProperty(declared, collects.key);
+            declared = property ? this.throughConstraint(this.checker.getTypeOfSymbol(property)) : undefined;
+        }
+        if (declared === undefined)
+            return failed('param_missing');
+        if (declared === VARIADIC)
+            return unchecked('collects_untyped');
+        const parts = this.parts(declared);
+        if (parts.length === 0)
+            return failed('collects_not_object');
+        if (parts.some(part => this.isOpenTop(part) || this.isUnconstrained(part) || this.isEmptyObject(part))) {
+            return unchecked('collects_untyped');
+        }
+        if (parts.some(part => !this.isObjectLike(part) || part.getCallSignatures().length > 0)) {
+            return failed('collects_not_object');
+        }
+        return undefined;
+    }
+    /**
+     * An adapter's `runs` slot (#2474 R6a) takes one of `collections`, the
+     * types the request's verified `collects` scopes return, read as a mounted
+     * instance is (`fitsErased`, then assignability). A slot typed `any`,
+     * `unknown`, `{}` or by an unconstrained type parameter says nothing
+     * (`runs_untyped`). Undefined when it holds.
+     */
+    runsCollectionOutcome(signature, declared, collections) {
+        if (declared === undefined)
+            return failed('param_missing');
+        const slot = this.throughConstraint(declared);
+        if (slot === VARIADIC)
+            return unchecked('runs_untyped');
+        const parts = this.parts(slot);
+        if (parts.length === 0)
+            return failed('runs_not_collection');
+        if (parts.some(part => this.isOpenTop(part) || this.isUnconstrained(part) || this.isEmptyObject(part))) {
+            return unchecked('runs_untyped');
+        }
+        const own = signature.typeParameters ?? [];
+        for (const collection of collections) {
+            const erased = this.fitsErased(collection, slot, own);
+            if (erased === true)
+                return undefined;
+            if (erased === undefined && this.checker.isTypeAssignableTo(collection, slot))
+                return undefined;
+        }
+        return failed('runs_not_collection');
+    }
     /**
      * `receiver` fits `slot` with the signature's own type parameters
      * (`own`) erased to their constraints (carrick#2652), or undefined when
@@ -1776,7 +1974,7 @@ class DeclarationReader {
         // what it runs, and one that hands its handler a receiver (a server's
         // connection event) names nothing on the wire itself, so neither needs a
         // name of its own.
-        const nameless = claim.runs !== undefined || claim.yields !== undefined;
+        const nameless = claim.runs !== undefined || claim.yields !== undefined || (claim.op === 'send' && rules.namelessSends === true);
         if ((name === undefined && !nameless) || (claim.op === 'send' && claim.payload === undefined)) {
             return unchecked('claim_invalid');
         }
@@ -1785,7 +1983,8 @@ class DeclarationReader {
             nameSlot = undefined;
         }
         else if ('bound' in name) {
-            if (name.bound === 'maker' ? !receiver.makerBindsName : !receiver.scoped)
+            const bound = name.bound === 'maker' ? receiver.makerBindsName : name.bound === 'scope' ? receiver.scoped : receiver.keyBound === true;
+            if (!bound)
                 return failed('name_unbound');
         }
         else {
@@ -1812,6 +2011,7 @@ class DeclarationReader {
         const labels = claim.key_labels ?? {};
         let best;
         let held = false;
+        const bodyMembers = [];
         for (const signature of callee.signatures) {
             let result = this.messageSignatureOutcome(signature, layout.value, labels);
             if (result.rank === Infinity && claim.yields !== undefined) {
@@ -1820,7 +2020,7 @@ class DeclarationReader {
                     result = { rank: 5, outcome: given };
             }
             if (result.rank === Infinity && claim.request !== undefined) {
-                const read = this.requestOutcome(signature, claim.handler, claim.request);
+                const read = this.requestOutcome(signature, claim.handler, claim.request, bodyMembers);
                 if (read)
                     result = { rank: 5, outcome: read };
             }
@@ -1835,7 +2035,15 @@ class DeclarationReader {
         if (boundRuns)
             return this.boundRunsOutcome(receiver.makerHolding, boundRuns);
         const declarations = this.declarationsOf(callee);
-        return declarations.length > 0 ? { verdict: 'verified', declarations } : VERIFIED;
+        const members = callee.named
+            ? (callee.named.property.declarations ?? [])
+            : callee.signatures.flatMap(signature => signature.getDeclaration() ?? []);
+        return {
+            verdict: 'verified',
+            ...(declarations.length > 0 ? { declarations } : {}),
+            ...(members.length > 0 ? { members } : {}),
+            ...(bodyMembers.length > 0 ? { bodyMembers } : {}),
+        };
     }
     /**
      * Where a verified op or scope's member is declared, as position rows spell
@@ -1882,6 +2090,18 @@ class DeclarationReader {
      */
     methodOutcome(claim, rules) {
         const words = rules.methods;
+        // A procedure named by its key (#2474 R6a): a receive op with a handler
+        // whose label states its method, a route word. The member names the
+        // procedure kind (`query`), not a verb, so it need not equal the method.
+        if (claim.name !== undefined && 'bound' in claim.name && claim.name.bound === 'key') {
+            if (!words || claim.op !== 'receive' || claim.handler === undefined || claim.method === undefined) {
+                return unchecked('claim_invalid');
+            }
+            if (claim.method_key !== undefined || claim.method_default !== undefined || claim.options !== undefined) {
+                return unchecked('claim_invalid');
+            }
+            return words.has(claim.method) ? undefined : failed('method_not_word');
+        }
         if (!words) {
             const any = claim.method !== undefined ||
                 claim.method_key !== undefined ||
@@ -2010,13 +2230,14 @@ class DeclarationReader {
             })));
     }
     /**
-     * `request: { param, path?, url?, method? }` on a receive op (#2474 R0):
-     * some signature of the handler this overload takes declares a parameter
-     * at `param` on which every member path the claim gives resolves, step by
-     * step, through properties the library declares (`declaredProperty`).
-     * Undefined when it holds.
+     * `request: { param, path?, url?, method?, body? }` on a receive op (#2474
+     * R0, carrick#2674): some signature of the handler this overload takes
+     * declares a parameter at `param` on which every member path the claim
+     * gives resolves, step by step, through properties the library declares
+     * (`declaredProperty`). Undefined when it holds; the declarations of the
+     * member the `body` path ends on are then added to `bodyMembers`.
      */
-    requestOutcome(signature, handler, request) {
+    requestOutcome(signature, handler, request, bodyMembers) {
         let declared = this.keyParameterAt(signature, handler.arg);
         if (declared !== undefined && handler.key !== undefined) {
             const property = this.declaredProperty(declared, handler.key);
@@ -2027,25 +2248,33 @@ class DeclarationReader {
         const slot = this.throughConditional(this.throughConstraint(declared));
         if (slot === VARIADIC)
             return unchecked('handler_untyped');
-        const paths = [request.path, request.url, request.method].filter((p) => p !== undefined);
+        const paths = [request.path, request.url, request.method, request.body].filter((p) => p !== undefined);
         let best = failed('param_missing');
         for (const part of this.parts(slot)) {
             for (const handed of part.getCallSignatures()) {
                 const given = this.parameterAt(handed, request.param);
                 if (given === undefined || given === VARIADIC)
                     continue;
+                const ends = new Map();
                 const resolves = paths.every(members => {
                     let at = given;
+                    let last;
                     for (const member of members) {
                         const property = this.declaredProperty(at, member);
                         if (!property)
                             return false;
+                        last = property;
                         at = this.checker.getTypeOfSymbol(property);
                     }
+                    if (last)
+                        ends.set(members, last);
                     return true;
                 });
-                if (resolves)
+                if (resolves) {
+                    const body = request.body ? ends.get(request.body) : undefined;
+                    bodyMembers.push(...(body?.declarations ?? []));
                     return undefined;
+                }
                 best = failed('request_member_missing');
             }
         }
@@ -2110,8 +2339,12 @@ class DeclarationReader {
      *    prefix key accepting a string and a handler key a declared function.
      * 4. Every string slot of the call besides the name is accounted for
      *    (design D2, `nameSiblings`).
+     *
+     * `runsAs` replaces the `runs` predicate (an adapter's collection, #2474
+     * R6a); absent, a `runs` slot is a declared function.
      */
-    messageSignatureOutcome(signature, layout, labels) {
+    messageSignatureOutcome(signature, layout, labels, runsAs) {
+        const runsFailure = runsAs ?? ((declared) => this.runsFailure(declared));
         for (const [arg, part] of layout.positional) {
             if (part === 'method') {
                 const declared = this.keyParameterAt(signature, arg);
@@ -2148,7 +2381,7 @@ class DeclarationReader {
             if (part !== 'handler' && part !== 'ack' && part !== 'runs')
                 continue;
             const declared = this.keyParameterAt(signature, arg);
-            const failure = part === 'runs' ? this.runsFailure(declared) : this.handlerFailure(declared);
+            const failure = part === 'runs' ? runsFailure(declared) : this.handlerFailure(declared);
             if (failure)
                 return { rank: 3, outcome: failure };
         }
@@ -2157,7 +2390,7 @@ class DeclarationReader {
             const slot = this.keyParameterAt(signature, arg);
             if (slot === undefined)
                 return { rank: 1, outcome: failed('param_missing') };
-            const view = this.viewFor(slot, keys);
+            const view = this.viewFor(slot, keys, runsFailure);
             if ('rank' in view)
                 return view;
             views.set(arg, view.view);
@@ -2172,7 +2405,7 @@ class DeclarationReader {
      * union member that is an object type and not a function type, declaring
      * every claimed key with the type its part needs.
      */
-    viewFor(slot, keys) {
+    viewFor(slot, keys, runsFailure) {
         if (slot === VARIADIC || !this.isObjectType(slot)) {
             return { rank: 1, outcome: this.slotFailure(slot, 'param_missing') };
         }
@@ -2202,7 +2435,7 @@ class DeclarationReader {
                     break;
                 }
                 if (part === 'runs') {
-                    const bad = this.runsFailure(type);
+                    const bad = runsFailure(type);
                     if (bad) {
                         failure = { rank: 3, outcome: bad };
                         break;
@@ -2769,8 +3002,20 @@ class DeclarationReader {
             dropped += 1;
             return false;
         };
-        // Three passes: every export and receiver, then every member name, then signatures.
+        // 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;
+        };
+        // Four passes: every export and receiver, then every member name, then the
+        // members of each handler's parameters (carrick#2674), 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.
@@ -2786,7 +3031,7 @@ class DeclarationReader {
                 if (!take())
                     return;
                 const home = this.homeOf(pkg, [target, ...typeSymbols(receiverType)]);
-                entry.receivers.push(this.outlineReceiver(pkg, receiverName, receiverType, home, take, names, fills));
+                entry.receivers.push(this.outlineReceiver(pkg, receiverName, receiverType, home, take, takeHandler, names, handlers, fills));
             };
             receiverOf('export', type);
             for (const maker of this.makers(pkg, target, type)) {
@@ -2803,6 +3048,8 @@ class DeclarationReader {
         }
         for (const run of names)
             run();
+        for (const run of handlers)
+            run();
         for (const fill of fills)
             fill();
         surface.truncated = dropped;
@@ -2947,10 +3194,11 @@ class DeclarationReader {
     }
     /**
      * A receiver, now; its member names later (`names`), once every export and
-     * receiver of the package is listed; its call, construct and member
-     * signatures last (`fills`), once every name is.
+     * receiver of the package is listed; the members of its handlers'
+     * 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, names, fills) {
+    outlineReceiver(pkg, receiverName, type, home, take, takeHandler, 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
@@ -2977,11 +3225,102 @@ class DeclarationReader {
                 const own = 'signatures' in callee;
                 const member = { name: property.getName(), own, signatures: [] };
                 receiver.members.push(member);
+                handlers.push(() => {
+                    const listed = this.listHandlers(own ? callee.signatures : library, takeHandler);
+                    if (listed.length > 0)
+                        member.handlers = listed;
+                });
                 fills.push(() => (member.signatures = this.listSignatures(own ? callee.signatures : library, holder.type, take)));
             }
         });
         return receiver;
     }
+    /**
+     * The functions a member's signatures take, at a positional argument or at a
+     * key of an options object, with the members their parameters declare. A
+     * handler is listed once per place, from the first signature that states it.
+     * A parameter that declares no member lists nothing, and so does a handler
+     * none of whose parameters do.
+     */
+    listHandlers(signatures, take) {
+        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);
+            if (params.length === 0)
+                return;
+            seen.add(place);
+            listed.push(key === undefined ? { arg, params } : { arg, key, params });
+        };
+        for (const signature of signatures) {
+            const count = signature.getParameters().length;
+            for (let arg = 0; arg < count; arg++) {
+                const slot = this.keyParameterAt(signature, arg);
+                if (slot === undefined || slot === VARIADIC)
+                    continue;
+                if (this.handlerFailure(slot) === undefined) {
+                    add(arg, undefined, slot);
+                    continue;
+                }
+                if (!this.isObjectType(slot))
+                    continue;
+                const keys = new Map();
+                for (const view of this.keyViews(slot)) {
+                    for (const property of this.namedProperties(view)) {
+                        const type = this.checker.getTypeOfSymbol(property);
+                        if (!keys.has(property.getName()) && this.handlerFailure(type) === undefined)
+                            keys.set(property.getName(), type);
+                    }
+                }
+                for (const key of [...keys.keys()].sort(byName))
+                    add(arg, key, keys.get(key));
+            }
+        }
+        return listed;
+    }
+    /** The parameters of a function type's first signature that declare members, each member counting against the cap. */
+    listHandlerParams(handler, take) {
+        const slot = this.throughConditional(this.throughConstraint(handler));
+        if (slot === VARIADIC)
+            return [];
+        const signature = this.parts(slot)
+            .flatMap(part => part.getCallSignatures())
+            .find(each => each.getParameters().length > 0);
+        if (!signature)
+            return [];
+        const listed = [];
+        signature.getParameters().forEach((parameter, index) => {
+            const type = this.checker.getTypeOfSymbol(parameter);
+            if (this.namedProperties(type).length === 0 || !take())
+                return;
+            const members = [];
+            this.listMembers(type, [], members, take);
+            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);
+            }
+        }
+    }
     listSignatures(signatures, holder, take) {
         const listed = [];
         for (const signature of signatures) {
@@ -3532,6 +3871,8 @@ class DeclarationReader {
  * union the builder cuts short keeps the members it made first, so the
  * listing orders every union before its own cut (`truncate`).
  */
+/** The longest member path a handler parameter's members are listed to (`['raw', 'url']`). */
+const HANDLER_MEMBER_DEPTH = 2;
 const PRINT_FLAGS = ts.NodeBuilderFlags.AllowUniqueESSymbolType |
     ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope |
     ts.NodeBuilderFlags.IgnoreErrors |