carrick 0.3.112 → 0.3.113

package/sidecar/dist/src/type-inferrer.js

@@ -18,7 +18,7 @@
  * function's return type.
  */
 import * as path from 'node:path';
-import { Node, SyntaxKind, ts, } from 'ts-morph';
+import { Node, SyntaxKind, VariableDeclarationKind, ts, } from 'ts-morph';
 import { typeToStringAsDeclared } from './print-type.js';
 import { validateInferRequestItem } from './validators.js';
 import { notePrintedType, PrintedTypes } from './printed-names.js';
@@ -172,6 +172,15 @@ const RESPONSE_HELPER_MAX_DEPTH = 4;
  * the branch an error path, whose shape is not the endpoint's contract.
  */
 const STATUS_MEMBER_NAMES = ['status', 'statusCode'];
+/** The provenance sentence for each reason a branch was not read. */
+const SERIALISED_BODY_UNREAD_DETAIL = {
+    prebuilt: 'A return hands back a status and body built somewhere else, such as a variable or a field of another result, so the value in its body was not read.',
+    not_serialised: "A return's body string is not made by JSON.stringify, so the value it holds was not read.",
+    builder: 'A return calls a response helper that could not be followed to the one value it serialises, so what it sends was not read.',
+    top_type: 'A return serialises a value typed any or unknown, so the shape of its body is not known.',
+};
+/** `any` or `unknown` as a type in printed type text, not as a member name or a string. */
+const TOP_TYPE_TOKEN = /(?<![\w$'"`])(?:any|unknown)(?![\w$'"`?:])/;
 /**
  * The items whose whitespace-collapsed texts differ, first of each kept, in
  * order: how a joined union drops a member it already has.
@@ -789,6 +798,13 @@ export class TypeInferrer {
         // whose contract lives in the yield position. Unwrap it to the yield type so
         // both forms reduce to `Order` before structural expansion / rule matching.
         const awaitedType = this.unwrapAsyncIterableType(this.unwrapPromiseType(returnType));
+        // carrick#2200: a `{ statusCode, body: string }` return is transport the
+        // handler built itself; its contract is the value it serialised into
+        // `body`. Decided before the extraction config, whose rule for the
+        // envelope would read `body` and publish `string`.
+        if (this.serialisedBodyEnvelopeEngages(awaitedType, func)) {
+            return this.inferSerialisedBodyEnvelope(request, func);
+        }
         const unwrapResult = this.unwrapTypeWithConfig(awaitedType, func, extractionConfig);
         if (unwrapResult.wasUnwrapped && !unwrapResult.verifiedMachinery) {
             typeString = unwrapResult.typeString;
@@ -1525,17 +1541,13 @@ export class TypeInferrer {
             }
             this.log(`Response locator at ${request.file_path}:${request.line_number} names an error ` +
                 'or redirect send and its handler sends no success body; abstaining');
-            const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(site));
-            abstain.any_provenance = [
-                {
-                    path: '',
-                    kind: 'unknown',
-                    reason: 'no_success_payload',
-                    detail: "every response this route's handler sends states an error or redirect status, " +
-                        'or carries no body a JSON contract can describe, so it publishes no success body',
-                },
-            ];
-            return abstain;
+            return this.decidedAbstain(request, this.getNodeLocation(site), {
+                path: '',
+                kind: 'unknown',
+                reason: 'no_success_payload',
+                detail: "every response this route's handler sends states an error or redirect status, " +
+                    'or carries no body a JSON contract can describe, so it publishes no success body',
+            });
         }
         if (recovered && recovered.nodes.some((node) => contains(site, node))) {
             return this.inferredFromRecoveredPayload(request, recovered);
@@ -1763,18 +1775,14 @@ export class TypeInferrer {
             this.log(`Call result at ${request.file_path}:${request.line_number} is only ever read as ` +
                 `members of ${typeText(callExpr.getType(), callExpr)}; a part of a payload is not ` +
                 'a payload, so this site states no response contract');
-            const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(callExpr));
-            abstain.any_provenance = [
-                {
-                    path: '',
-                    kind: 'unknown',
-                    reason: 'projected_value_only',
-                    detail: "every read of this call's result takes a member out of it and none reads the " +
-                        'value itself, so what this site states is a part of a payload rather than the ' +
-                        'payload a caller receives',
-                },
-            ];
-            return abstain;
+            return this.decidedAbstain(request, this.getNodeLocation(callExpr), {
+                path: '',
+                kind: 'unknown',
+                reason: 'projected_value_only',
+                detail: "every read of this call's result takes a member out of it and none reads the " +
+                    'value itself, so what this site states is a part of a payload rather than the ' +
+                    'payload a caller receives',
+            });
         }
         typeString = this.unwrapPromise(typeString, returnType);
         // #336: consumer analogue of the #306 producer anchor. Anchor on the
@@ -2315,17 +2323,13 @@ export class TypeInferrer {
         else if (inCall.kind === 'no_body') {
             this.log(`Request locator at ${request.file_path}:${request.line_number} is a request config ` +
                 'that carries no body member; the call sends no request body');
-            const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(unwrapped));
-            abstain.any_provenance = [
-                {
-                    path: '',
-                    kind: 'unknown',
-                    reason: 'no_request_body',
-                    detail: `the call's request config sets no '${inCall.member}' member, which is where the call ` +
-                        'takes its body, so the call sends no request body',
-                },
-            ];
-            return abstain;
+            return this.decidedAbstain(request, this.getNodeLocation(unwrapped), {
+                path: '',
+                kind: 'unknown',
+                reason: 'no_request_body',
+                detail: `the call's request config sets no '${inCall.member}' member, which is where the call ` +
+                    'takes its body, so the call sends no request body',
+            });
         }
         // A `fetch` body is almost always `JSON.stringify(payload)`, whose own type
         // is the useless `string`. Drill to the serialized argument so the consumer
@@ -2380,17 +2384,13 @@ export class TypeInferrer {
             if (nonBodyPart !== undefined) {
                 this.log(`Request locator at ${request.file_path}:${request.line_number} reads the validated ` +
                     `'${nonBodyPart}' part, which is not a body; the route declares no request body here`);
-                const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(node));
-                abstain.any_provenance = [
-                    {
-                        path: '',
-                        kind: 'unknown',
-                        reason: 'no_request_body',
-                        detail: `the located read is the '${nonBodyPart}' part a validator binds, not a request body, ` +
-                            'so the route states no body contract here',
-                    },
-                ];
-                return abstain;
+                return this.decidedAbstain(request, this.getNodeLocation(node), {
+                    path: '',
+                    kind: 'unknown',
+                    reason: 'no_request_body',
+                    detail: `the located read is the '${nonBodyPart}' part a validator binds, not a request body, ` +
+                        'so the route states no body contract here',
+                });
             }
         }
         const payloadType = node.getType();
@@ -2882,16 +2882,12 @@ export class TypeInferrer {
     transportAbstain(request, callExpr, detail = "what this call's result carries is transport that the service's wrapper " +
         'rules verify and read no payload out of (a library response object around the body), ' +
         'so this site states no response contract') {
-        const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(callExpr));
-        abstain.any_provenance = [
-            {
-                path: '',
-                kind: 'unknown',
-                reason: 'machinery_envelope',
-                detail,
-            },
-        ];
-        return abstain;
+        return this.decidedAbstain(request, this.getNodeLocation(callExpr), {
+            path: '',
+            kind: 'unknown',
+            reason: 'machinery_envelope',
+            detail,
+        });
     }
     /**
      * `Future<T>` -> `T` for a thenable, read off the await protocol rather
@@ -4215,29 +4211,44 @@ export class TypeInferrer {
             const payloadNode = this.responseHelperPayloadNode(expression, 0, statedOnly, serialisers);
             if (!payloadNode)
                 continue;
-            // A `satisfies X` / `as X` on the argument states the contract in source:
-            // read the ANNOTATION, not the literal the compiler widened it from.
-            // `expandAnnotationTypeNode` keeps the bare name when the declaration is
-            // not resolvable, which is the honest answer on a bare checkout.
-            const stated = this.statedTypeNodeOf(payloadNode);
-            if (stated) {
-                candidates.push({
-                    typeString: this.expandAnnotationTypeNode(stated, wire),
-                    isExplicit: true,
-                    node: payloadNode,
-                    anchorType: this.unwrapPromiseType(stated.getType()),
-                    statedTypeNode: stated,
-                });
-                continue;
-            }
-            const payloadType = this.unwrapPromiseType(payloadNode.getType());
-            candidates.push({
-                typeString: this.expandResolvedTypeStructural(payloadType, typeText(payloadType, payloadNode), wire),
-                isExplicit: false,
-                node: payloadNode,
-                anchorType: payloadType,
-            });
+            candidates.push(this.payloadCandidateOf(payloadNode, wire));
+        }
+        return this.joinPayloadCandidates(candidates);
+    }
+    /** How one payload node reads: its stated annotation, else its resolved type. */
+    payloadCandidateOf(payloadNode, wire) {
+        // A `satisfies X` / `as X` on the argument states the contract in source:
+        // read the ANNOTATION, not the literal the compiler widened it from.
+        // `expandAnnotationTypeNode` keeps the bare name when the declaration is
+        // not resolvable, which is the honest answer on a bare checkout.
+        const stated = this.statedTypeNodeOf(payloadNode);
+        if (stated) {
+            return this.statedPayloadCandidate(payloadNode, stated, wire);
         }
+        const payloadType = this.unwrapPromiseType(payloadNode.getType());
+        return {
+            typeString: this.expandResolvedTypeStructural(payloadType, typeText(payloadType, payloadNode), wire),
+            isExplicit: false,
+            node: payloadNode,
+            anchorType: payloadType,
+        };
+    }
+    /** A payload whose contract a type node in the source states. */
+    statedPayloadCandidate(payloadNode, stated, wire) {
+        return {
+            typeString: this.expandAnnotationTypeNode(stated, wire),
+            isExplicit: true,
+            node: payloadNode,
+            anchorType: this.unwrapPromiseType(stated.getType()),
+            statedTypeNode: stated,
+        };
+    }
+    /**
+     * Join the payloads of several response branches into one contract, as
+     * several return statements are joined: an empty object drops beside a
+     * branch with members, equal texts dedupe, and the rest is a union.
+     */
+    joinPayloadCandidates(candidates) {
         if (candidates.length === 0) {
             return null;
         }
@@ -4268,6 +4279,516 @@ export class TypeInferrer {
             statedTypeNode: distinct.length === 1 ? distinct[0].statedTypeNode : undefined,
         };
     }
+    // ===========================================================================
+    // Serialised-body envelopes (carrick#2200)
+    // ===========================================================================
+    /**
+     * True when a handler's awaited return, or a member of its union, is a
+     * serialised-body envelope: an object with a numeric `statusCode` or
+     * `status` member and a `body` member typed `string`. Either member may be
+     * optional, as a platform's result type declares them.
+     *
+     * HTTP vocabulary only, the class `RESPONSE_INIT_MEMBER_NAMES` is. A `body`
+     * typed as an object is not an envelope: a runtime that serialises the
+     * handler's return value sends that object as the payload, so the shape is
+     * ambiguous and keeps the ordinary reading.
+     */
+    typeIsSerialisedBodyEnvelope(type, at) {
+        const members = type.isUnion() ? type.getUnionTypes() : [type];
+        return members.some((member) => {
+            if (!member.isObject() || member.isArray() || member.getCallSignatures().length > 0) {
+                return false;
+            }
+            const body = this.envelopeMemberType(member, 'body', at);
+            if (!body || !(body.isString() || body.isStringLiteral()))
+                return false;
+            return STATUS_MEMBER_NAMES.some((name) => {
+                const status = this.envelopeMemberType(member, name, at);
+                return status !== undefined && (status.isNumber() || statusCodesOfType(status) !== undefined);
+            });
+        });
+    }
+    /** A member's type with `undefined` and `null` removed, or `undefined` if absent. */
+    envelopeMemberType(type, name, at) {
+        const property = type.getProperty(name);
+        if (!property)
+            return undefined;
+        return property.getTypeAtLocation(at).getNonNullableType();
+    }
+    /**
+     * True when a handler's return is a serialised-body envelope AND the source
+     * shows the body is serialised, so the envelope reading applies:
+     *  - a returned branch builds an envelope whose `body` is `JSON.stringify`
+     *    of a value, inline, through a `const`, or in a builder the reading can
+     *    follow (`branchShowsSerialisation`); or
+     *  - the envelope type is declared outside the repository (a platform's
+     *    result type) with every member optional. Nothing else returns such a
+     *    type, so a value of it returned as-is is still transport. The repo's
+     *    own all-optional types (`Partial<Article>`) engage only on evidence.
+     *
+     * A domain object that merely has `status` and `body` members (an article,
+     * a message) shows neither and keeps the ordinary reading.
+     */
+    serialisedBodyEnvelopeEngages(type, func) {
+        if (!this.typeIsSerialisedBodyEnvelope(type, func))
+            return false;
+        const members = type.isUnion() ? type.getUnionTypes() : [type];
+        const platformShaped = members.some((member) => {
+            if (!this.typeIsSerialisedBodyEnvelope(member, func))
+                return false;
+            const properties = member.getProperties();
+            return properties.every((property) => property.hasFlags(ts.SymbolFlags.Optional) &&
+                this.symbolIsLibOrExternalOrigin(property));
+        });
+        if (platformShaped)
+            return true;
+        return this.envelopeBranches(func).some((branch) => this.branchShowsSerialisation(branch, func, 0));
+    }
+    /**
+     * True when a returned branch builds an envelope from a serialised value:
+     * a literal whose `body` is `JSON.stringify(...)`, a call to a builder the
+     * reading can follow, or a call handing on one such envelope.
+     */
+    branchShowsSerialisation(expression, scope, depth) {
+        if (depth > RESPONSE_HELPER_MAX_DEPTH)
+            return false;
+        const node = this.peelTransparentExpression(expression);
+        if (Node.isObjectLiteralExpression(node)) {
+            return this.serialisedBodyArgument(node, scope) !== undefined;
+        }
+        if (!Node.isCallExpression(node))
+            return false;
+        if (this.envelopeBuilderOf(node) !== undefined)
+            return true;
+        return this.handedOnArguments(node).some((arg) => this.branchShowsSerialisation(arg, scope, depth + 1));
+    }
+    /**
+     * The arguments a call could hand back as its result: every argument but
+     * an object literal, which is the call's input (`create({ body:
+     * JSON.stringify(doc) })` stores a document, it does not respond with it),
+     * and but a function, whose returns are read as the call's callbacks.
+     */
+    handedOnArguments(call) {
+        return call
+            .getArguments()
+            .map((arg) => this.peelTransparentExpression(arg))
+            .filter((arg) => !Node.isObjectLiteralExpression(arg) &&
+            !Node.isArrowFunction(arg) &&
+            !Node.isFunctionExpression(arg));
+    }
+    /**
+     * The returned branches of an envelope handler: each returned expression,
+     * conditional sides split. A returned call whose callbacks return values
+     * (`settle().then(ok, fail)`) is carried by those returns, plus every
+     * envelope it is handed directly (`withFallback(() => a, b)` can answer
+     * `b`); a call whose callbacks return nothing stays a branch of its own.
+     */
+    envelopeBranches(func) {
+        const carriedByCallbacks = new Set(this.returnedExpressions(func).filter((expression) => {
+            const call = this.peelTransparentExpression(expression);
+            if (!Node.isCallExpression(call))
+                return false;
+            return call.getArguments().some((arg) => {
+                const callback = this.peelTransparentExpression(arg);
+                return ((Node.isArrowFunction(callback) || Node.isFunctionExpression(callback)) &&
+                    this.returnedExpressions(callback).length > 0);
+            });
+        }));
+        const handedEnvelopes = [...carriedByCallbacks].flatMap((expression) => {
+            const call = this.peelTransparentExpression(expression);
+            if (!Node.isCallExpression(call))
+                return [];
+            return call
+                .getArguments()
+                .map((arg) => this.peelTransparentExpression(arg))
+                .filter((arg) => !Node.isArrowFunction(arg) &&
+                !Node.isFunctionExpression(arg) &&
+                this.typeIsSerialisedBodyEnvelope(arg.getType(), arg));
+        });
+        return [
+            ...this.responseReturnedExpressions(func).filter((expression) => !carriedByCallbacks.has(expression)),
+            ...handedEnvelopes,
+        ].flatMap((expression) => this.expandResponseBranches(expression, 0));
+    }
+    /**
+     * The `function_return` answer for a handler that returns a serialised-body
+     * envelope: the union of the values its success branches serialised.
+     *
+     * Each returned branch is read by `readEnvelopeBranch`. Error and redirect
+     * branches contribute nothing (carrick#1161). If any branch cannot be read,
+     * the answer is `unknown` with the decided reason `serialised_body_unread`
+     * and one sentence per cause: the branches that did read are part of the
+     * contract, and neither the envelope nor its `string` body is any of it.
+     */
+    inferSerialisedBodyEnvelope(request, func) {
+        const wire = this.wireFormatFor(request);
+        const branches = this.envelopeBranches(func);
+        const candidates = [];
+        const causes = new Set();
+        for (const branch of branches) {
+            const read = this.readEnvelopeBranch(branch, func, wire, 0);
+            if (read === 'dropped')
+                continue;
+            if ('unread' in read)
+                causes.add(read.unread);
+            else
+                candidates.push(read);
+        }
+        const location = this.getNodeLocation(func);
+        if (causes.size > 0) {
+            this.log(`Return at ${request.file_path}:${request.line_number} is a serialised-body ` +
+                `envelope and a returned branch was not read (${[...causes].join(', ')}); abstaining`);
+            return this.decidedAbstain(request, location, {
+                path: '',
+                kind: 'unknown',
+                reason: 'serialised_body_unread',
+                detail: [...causes].map((cause) => SERIALISED_BODY_UNREAD_DETAIL[cause]).join(' '),
+            });
+        }
+        const recovered = this.joinPayloadCandidates(candidates);
+        if (!recovered) {
+            return this.decidedAbstain(request, location, {
+                path: '',
+                kind: 'unknown',
+                reason: 'no_success_payload',
+                detail: 'every status and body this handler returns states an error or redirect status, so it publishes no success body',
+            });
+        }
+        return this.inferredFromRecoveredPayload(request, recovered);
+    }
+    /** An `unknown` answer the inferrer decided, carrying its reason at the root. */
+    decidedAbstain(request, location, reason) {
+        const abstain = this.createInferredType(request, 'unknown', false, location);
+        abstain.any_provenance = [reason];
+        return abstain;
+    }
+    /**
+     * What one returned branch of an envelope handler serialised:
+     *  - an envelope object literal: the argument of the `JSON.stringify` that
+     *    produced its `body`, inline or through a `const` in the same function;
+     *    its status member decides the branch;
+     *  - a call to a response builder this repository declares
+     *    (`envelopeBuilderOf`): the argument the builder serialises; the
+     *    argument or literal its status member takes decides the branch;
+     *  - any other call handing on exactly one envelope argument (never an
+     *    object literal, which is the call's input): that
+     *    envelope is read in its place. Its own stated status decides the
+     *    branch; only when it states none does a status the outer call's
+     *    arguments state decide (`log(ctx, 503, "code", prebuilt)`).
+     * Anything else, and a payload holding `any` or `unknown`, is unread, with
+     * its cause.
+     */
+    readEnvelopeBranch(expression, scope, wire, depth) {
+        if (depth > RESPONSE_HELPER_MAX_DEPTH)
+            return { unread: 'builder' };
+        const node = this.peelTransparentExpression(expression);
+        if (Node.isObjectLiteralExpression(node)) {
+            const status = this.envelopeLiteralStatus(node);
+            if (status === 'error' || status === 'redirect')
+                return 'dropped';
+            const payload = this.serialisedBodyArgument(node, scope);
+            return payload ? this.envelopePayloadCandidate(payload, wire) : { unread: 'not_serialised' };
+        }
+        if (!Node.isCallExpression(node))
+            return { unread: 'prebuilt' };
+        const builder = this.envelopeBuilderOf(node);
+        if (builder === 'failure')
+            return 'dropped';
+        if (builder) {
+            const status = this.builderCallStatus(node, builder);
+            if (status === 'error' || status === 'redirect')
+                return 'dropped';
+            const argument = node.getArguments()[builder.payloadParameter];
+            if (!argument)
+                return { unread: 'builder' };
+            return this.builderPayloadCandidate(node, builder, argument, wire);
+        }
+        const envelopes = this.handedOnArguments(node).filter((arg) => this.typeIsSerialisedBodyEnvelope(arg.getType(), arg));
+        if (envelopes.length > 1)
+            return { unread: 'builder' };
+        const inner = envelopes[0];
+        const innerStatus = inner ? this.envelopeOwnStatus(inner) : 'undecided';
+        if (innerStatus === 'undecided' || innerStatus === 'variable') {
+            const outer = this.responseSiteStatus(node);
+            if (outer === 'error' || outer === 'redirect')
+                return 'dropped';
+        }
+        if (!inner)
+            return { unread: 'builder' };
+        return this.readEnvelopeBranch(inner, scope, wire, depth + 1);
+    }
+    /** The status a builder call sends: its status argument, or the builder's literal. */
+    builderCallStatus(call, builder) {
+        if (builder.statusParameter !== undefined) {
+            return this.statusOfValue(call.getArguments()[builder.statusParameter]);
+        }
+        return builder.fixedStatus ?? 'undecided';
+    }
+    /**
+     * The status an envelope expression states itself: a literal's status
+     * member, or what a followable builder call sends. `'undecided'` for
+     * anything else (a variable holding an envelope states nothing here).
+     */
+    envelopeOwnStatus(expression) {
+        const node = this.peelTransparentExpression(expression);
+        if (Node.isObjectLiteralExpression(node))
+            return this.envelopeLiteralStatus(node);
+        if (!Node.isCallExpression(node))
+            return 'undecided';
+        const builder = this.envelopeBuilderOf(node);
+        if (builder === 'failure')
+            return 'error';
+        return builder ? this.builderCallStatus(node, builder) : 'undecided';
+    }
+    /** The status an envelope literal's `statusCode` or `status` member states. */
+    envelopeLiteralStatus(literal) {
+        for (const name of STATUS_MEMBER_NAMES) {
+            const value = this.envelopeMemberValue(literal, name);
+            if (value)
+                return this.statusOfValue(value);
+        }
+        return 'undecided';
+    }
+    /** The status a value states, classified as a send's status argument is. */
+    statusOfValue(value) {
+        if (!value)
+            return 'undecided';
+        const read = this.statedStatusCodes(this.peelTransparentExpression(value));
+        if (read === 'variable')
+            return 'variable';
+        if (!read)
+            return 'undecided';
+        const kind = classifyStatusCodes(read);
+        return kind === 'mixed' ? 'variable' : kind;
+    }
+    /**
+     * The value node an object literal gives a member: a property assignment's
+     * initializer, or a shorthand's own name.
+     */
+    envelopeMemberValue(literal, name) {
+        const property = literal.getProperty(name);
+        if (property && Node.isPropertyAssignment(property))
+            return property.getInitializer();
+        if (property && Node.isShorthandPropertyAssignment(property))
+            return property.getNameNode();
+        return undefined;
+    }
+    /**
+     * The value an envelope literal's `body` serialises: the argument of a
+     * `JSON.stringify` written there, or written as the initializer of a
+     * `const` that `scope` declares and `body` names. `undefined` when `body`
+     * is built any other way.
+     */
+    serialisedBodyArgument(literal, scope) {
+        const raw = this.envelopeMemberValue(literal, 'body');
+        if (!raw)
+            return undefined;
+        const value = this.peelTransparentExpression(raw);
+        const direct = this.unwrapJsonStringifyArg(value);
+        if (direct !== value)
+            return direct;
+        const initializer = this.constInitializerInScope(value, scope);
+        if (!initializer)
+            return undefined;
+        const bound = this.peelTransparentExpression(initializer);
+        const viaConst = this.unwrapJsonStringifyArg(bound);
+        return viaConst !== bound ? viaConst : undefined;
+    }
+    /**
+     * The initializer of the `const` an identifier (or a shorthand member's
+     * name) refers to, when `scope` itself declares it.
+     */
+    constInitializerInScope(node, scope) {
+        for (const declaration of this.valueSymbolOf(node)?.getDeclarations() ?? []) {
+            if (!Node.isVariableDeclaration(declaration))
+                continue;
+            if (declaration.getVariableStatement()?.getDeclarationKind() !==
+                VariableDeclarationKind.Const) {
+                continue;
+            }
+            if (this.findContainingFunctionForNode(declaration) !== scope)
+                continue;
+            return declaration.getInitializer();
+        }
+        return undefined;
+    }
+    /**
+     * The symbol of the value a node names: a shorthand member's value symbol
+     * (its own symbol is the property), else the identifier's symbol.
+     */
+    valueSymbolOf(node) {
+        const parent = node.getParent();
+        if (parent && Node.isShorthandPropertyAssignment(parent) && parent.getNameNode() === node) {
+            return parent.getValueSymbol();
+        }
+        return Node.isIdentifier(node) ? node.getSymbol() : undefined;
+    }
+    /** The index of the `params` entry a node names, or `undefined`. */
+    parameterIndexOf(node, params) {
+        for (const declaration of this.valueSymbolOf(node)?.getDeclarations() ?? []) {
+            const index = params.findIndex((param) => param === declaration);
+            if (index >= 0)
+                return index;
+        }
+        return undefined;
+    }
+    /**
+     * How a call's callee builds an envelope, when the callee is a function this
+     * repository declares (not lib, not an installed package) and every return
+     * it makes is an envelope literal:
+     *  - returns whose status member is a literal 4xx or 5xx are its failure
+     *    path and are ignored; a builder with nothing else is `'failure'`, so a
+     *    call to it is an error branch;
+     *  - every other return must serialise the same parameter into `body` and
+     *    take its status from the same parameter, or state the same literal
+     *    success or redirect status.
+     * `undefined` when the callee is anything else.
+     */
+    envelopeBuilderOf(call) {
+        let symbol = call.getExpression().getSymbol();
+        if (symbol?.isAlias())
+            symbol = symbol.getAliasedSymbol() ?? symbol;
+        if (!symbol || this.symbolIsLibOrExternalOrigin(symbol))
+            return undefined;
+        const builder = this.builderFunctionOf(symbol);
+        if (!builder)
+            return undefined;
+        const params = builder.getParameters();
+        const returned = this.returnedExpressions(builder).flatMap((expression) => this.expandResponseBranches(expression, 0));
+        let mapping;
+        let sawFailure = false;
+        for (const expression of returned) {
+            const literal = this.peelTransparentExpression(expression);
+            if (!Node.isObjectLiteralExpression(literal))
+                return undefined;
+            const statusValue = STATUS_MEMBER_NAMES.map((name) => this.envelopeMemberValue(literal, name)).find((value) => value !== undefined);
+            if (!statusValue)
+                return undefined;
+            const statusParameter = this.parameterIndexOf(statusValue, params);
+            let fixedStatus;
+            if (statusParameter === undefined) {
+                const codes = this.statedStatusCodes(this.peelTransparentExpression(statusValue));
+                if (!Array.isArray(codes))
+                    return undefined;
+                const kind = classifyStatusCodes(codes);
+                if (kind === 'error') {
+                    sawFailure = true;
+                    continue;
+                }
+                if (kind === 'mixed')
+                    return undefined;
+                fixedStatus = kind;
+            }
+            const serialised = this.serialisedBodyArgument(literal, builder);
+            const payloadParameter = serialised ? this.parameterIndexOf(serialised, params) : undefined;
+            if (payloadParameter === undefined)
+                return undefined;
+            const here = { builder, payloadParameter, statusParameter, fixedStatus };
+            if (mapping &&
+                (mapping.payloadParameter !== here.payloadParameter ||
+                    mapping.statusParameter !== here.statusParameter ||
+                    mapping.fixedStatus !== here.fixedStatus)) {
+                return undefined;
+            }
+            mapping = here;
+        }
+        if (mapping)
+            return mapping;
+        return sawFailure ? 'failure' : undefined;
+    }
+    /**
+     * The single function a callee symbol declares with a body: a function
+     * declaration, or a variable initialised with an arrow or function
+     * expression.
+     */
+    builderFunctionOf(symbol) {
+        const bodies = [];
+        for (const declaration of symbol.getDeclarations()) {
+            if (Node.isFunctionDeclaration(declaration) && declaration.getBody()) {
+                bodies.push(declaration);
+            }
+            else if (Node.isVariableDeclaration(declaration)) {
+                const initializer = declaration.getInitializer();
+                const fn = initializer ? this.peelTransparentExpression(initializer) : undefined;
+                if (fn && (Node.isArrowFunction(fn) || Node.isFunctionExpression(fn)))
+                    bodies.push(fn);
+            }
+        }
+        return bodies.length === 1 ? bodies[0] : undefined;
+    }
+    /**
+     * The payload a builder call serialises. The source states it, and the
+     * answer is explicit, when the argument carries `satisfies`/`as`, when the
+     * builder's parameter is one of its type parameters and the call passes
+     * type arguments (`reply<AddNoteResult>(201, x)`), or when the parameter is
+     * declared with a type that says something. Otherwise the argument's own
+     * type is read.
+     */
+    builderPayloadCandidate(call, builder, argument, wire) {
+        const payloadNode = this.peelTransparentExpression(argument);
+        if (this.statedTypeNodeOf(payloadNode)) {
+            return this.envelopePayloadCandidate(payloadNode, wire);
+        }
+        const declared = builder.builder.getParameters()[builder.payloadParameter]?.getTypeNode();
+        if (declared) {
+            const typeParameterIndex = builder.builder
+                .getTypeParameters()
+                .findIndex((tp) => tp.getName() === declared.getText().trim());
+            if (typeParameterIndex >= 0) {
+                const typeArgument = call.getTypeArguments()[typeParameterIndex];
+                if (typeArgument) {
+                    return this.checkedEnvelopeCandidate(this.statedPayloadCandidate(payloadNode, typeArgument, wire));
+                }
+            }
+            else if (!this.typeNodeStatesNothing(declared)) {
+                return this.checkedEnvelopeCandidate(this.statedPayloadCandidate(payloadNode, declared, wire));
+            }
+        }
+        return this.envelopePayloadCandidate(payloadNode, wire);
+    }
+    /**
+     * True when a declared parameter type does not say what is sent: a top
+     * type, the `object` keyword, an object type that names no member (`{}`,
+     * `Record<string, unknown>`), a union that admits both primitives and
+     * objects (a JSON-value type such as `string | number | Json[] | { [k:
+     * string]: Json }`), or a type that mentions a type parameter. A builder
+     * that takes "any value" states nothing about the payload a call hands it,
+     * so the argument's own type is read instead.
+     */
+    typeNodeStatesNothing(typeNode) {
+        const type = typeNode.getType();
+        if (type.isAny() || type.isUnknown() || type.isTypeParameter())
+            return true;
+        if (type.getFlags() & ts.TypeFlags.NonPrimitive)
+            return true;
+        if (type.isObject() && !type.isArray() && type.getProperties().length === 0) {
+            return true;
+        }
+        if (type.isUnion()) {
+            const members = type.getUnionTypes();
+            const primitive = members.some((member) => member.isString() ||
+                member.isNumber() ||
+                member.isBoolean() ||
+                member.isBooleanLiteral());
+            if (primitive && members.some((member) => member.isObject()))
+                return true;
+        }
+        return [typeNode, ...typeNode.getDescendants()].some((node) => Node.isTypeReference(node) && node.getType().isTypeParameter());
+    }
+    /** A serialised value's candidate, unread when it holds a top type. */
+    envelopePayloadCandidate(payloadNode, wire) {
+        return this.checkedEnvelopeCandidate(this.payloadCandidateOf(payloadNode, wire));
+    }
+    /**
+     * A payload candidate, or unread when its printed type is or holds `any`
+     * or `unknown` anywhere (`{ [x: string]: any }`, `{ data: any }`). A
+     * contract with a hole in it is not published on this path: the capture
+     * would refuse the text and re-read the line, which can publish the
+     * envelope.
+     */
+    checkedEnvelopeCandidate(candidate) {
+        return TOP_TYPE_TOKEN.test(candidate.typeString) ? { unread: 'top_type' } : candidate;
+    }
     /**
      * The request field each member of a joined union answers
      * (`response-modes.ts`). Case texts are joined by the published union's
@@ -4666,16 +5187,9 @@ export class TypeInferrer {
             const receiver = this.peelTransparentExpression(callee.getExpression());
             if (!Node.isCallExpression(receiver))
                 return undefined;
-            const first = receiver.getArguments()[0];
-            if (first) {
-                const read = this.statedStatusCodes(this.peelTransparentExpression(first));
-                if (read === 'variable')
-                    return 'variable';
-                if (read) {
-                    const kind = classifyStatusCodes(read);
-                    return kind === 'mixed' ? 'variable' : kind;
-                }
-            }
+            const status = this.statusOfValue(receiver.getArguments()[0]);
+            if (status !== 'undecided')
+                return status;
             callee = receiver.getExpression();
         }
         return undefined;