carrick 0.3.126 → 0.3.128

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

@@ -31,6 +31,7 @@ import { functionAtLine } from './function-line-index.js';
 import { attributedDeclaration, installedPackageOf } from './declaration-attribution.js';
 import { endLineOf, startLineOf } from './line-index.js';
 import { elapsedMs, inferTiming, phaseClock, timedPhase } from './infer-timing.js';
+import { StatedParams } from './stated-params.js';
 import { classifyStatusCodes, constituents, httpStatus, statesNoBody, statesNoShape, statusKeyCode, statusTableOf, successEntries, } from './capture/index.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, jsonWireType, } from './type-structural-expander.js';
@@ -176,11 +177,29 @@ const RESPONSE_INIT_MEMBER_NAMES = new Set([
  * two; the bound is a backstop against a pathologically nested return.
  */
 const RESPONSE_HELPER_MAX_DEPTH = 4;
+/**
+ * How many wrapper calls a handler bound to one is followed through
+ * (carrick#2472 P3-2b): `wrap(trace(async (req, res) => …))` needs two. A
+ * backstop against a pathologically nested initializer.
+ */
+const WRAPPER_CALL_MAX_DEPTH = 3;
 /**
  * Members an options object uses to state an HTTP status. A >= 400 status marks
  * the branch an error path, whose shape is not the endpoint's contract.
  */
 const STATUS_MEMBER_NAMES = ['status', 'statusCode'];
+/**
+ * The reasons an `unknown` answer is a decision, not a failure to read: the
+ * list `DECIDED_ABSTAIN_REASONS` in `src/engine/type_compat_v2.rs` holds
+ * final. A stated reply never replaces one (carrick#2674).
+ */
+const DECIDED_ABSTAIN_REASONS = new Set([
+    'no_success_payload',
+    'no_request_body',
+    'projected_value_only',
+    'serialised_body_unread',
+    'body_built_by_callee',
+]);
 /** 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.',
@@ -442,13 +461,16 @@ export class TypeInferrer {
      * @param onRequestDone - Called once per request, as the batch is done with it
      * @returns InferResult with inferred types or errors
      */
-    infer(requests, extractionConfig, onRequestDone, modelSymbols) {
+    infer(requests, extractionConfig, onRequestDone, modelSymbols, labels) {
         const started = performance.now();
         this.modelSymbols = new Map((modelSymbols ?? []).map((symbol) => [symbol.alias, symbol]));
+        this.statedParams = this.statedParamsFor(labels ?? { sends: new Map(), bodies: new Set() });
         const inferredTypes = [];
         const errors = [];
         /** Response inferences the unwidened reading re-reads (carrick#1516). */
         const responses = [];
+        /** Request-body inferences it re-reads after them (carrick#2011). */
+        const bodies = [];
         /** How long each request took, in the order they were done (carrick#1985). */
         const timings = [];
         for (const request of requests) {
@@ -485,6 +507,9 @@ export class TypeInferrer {
                     if (request.infer_kind === 'response_body' || request.infer_kind === 'function_return') {
                         responses.push({ request, result });
                     }
+                    else if (request.infer_kind === 'request_body') {
+                        bodies.push({ request, result });
+                    }
                 }
                 else {
                     errors.push(`Could not infer type at ${request.file_path}:${loc} (${request.infer_kind})`);
@@ -515,10 +540,47 @@ export class TypeInferrer {
         }
         try {
             const deadline = Math.min(performance.now() + this.unwidenedBudgetMs, started + UNWIDENED_LATEST_MS);
-            this.addUnwidenedReadings(responses, extractionConfig, deadline);
+            // The responses' rewrite forgets every node of the files it touches, so
+            // each body's read node is kept as its span, taken now and found again
+            // in the restored file.
+            const bodySpans = bodies.map((body) => {
+                const node = this.readNodes.get(body.result.source_location);
+                return {
+                    ...body,
+                    readSpan: node && {
+                        file: node.getSourceFile(),
+                        start: node.getStart(),
+                        end: node.getEnd(),
+                        kind: node.getKind(),
+                    },
+                };
+            });
+            try {
+                this.addUnwidenedReadings(responses, extractionConfig, deadline, 'response');
+            }
+            catch (err) {
+                // The reading only ever adds a field; it never costs an answer.
+                this.logError(`Unwidened reading failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                // Second, and in a rewrite of its own: the bodies' files never delay a
+                // response's reading, whose budget a spent deadline turns into an
+                // abstention (carrick#2100).
+                this.addUnwidenedReadings(bodySpans, extractionConfig, deadline, 'request_body');
+            }
+            catch (err) {
+                this.logError(`Unwidened reading of request bodies failed: ${err instanceof Error ? err.message : String(err)}`);
+                // carrick#2011: a body whose reading was not made is judged on its
+                // widened type alone, so it is marked the way a spent budget marks it
+                // and its pair abstains on a mismatch rather than report one.
+                for (const body of bodies) {
+                    if (body.result.unwidened_type_string === undefined) {
+                        body.result.unwidened_out_of_budget = true;
+                    }
+                }
+            }
         }
         catch (err) {
-            // The reading only ever adds a field; it never costs an answer.
             this.logError(`Unwidened reading failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         return {
@@ -530,6 +592,12 @@ export class TypeInferrer {
     }
     /** The types the model named, by the alias of the row each is for (carrick#2111). */
     modelSymbols = new Map();
+    /**
+     * carrick#2674: what route handlers' parameters state, through the
+     * members the batch's verified server-framework labels name. Empty when
+     * the batch carries no labels, and then it reads nothing.
+     */
+    statedParams = this.statedParamsFor({ sends: new Map(), bodies: new Set() });
     /**
      * carrick#2111: where the model named a type for the response this request
      * reads, record on `inferred` how that type relates to the compiler's type
@@ -614,19 +682,29 @@ export class TypeInferrer {
      * really returns beside the published one (`unwidened_type_string`). See
      * `unwidened.ts` for what is marked and why the reading is sound.
      *
+     * carrick#2011: a request body (`read` is `'request_body'`) is read the same
+     * way, the call that sends it in place of the handler, except that a literal
+     * handed to any call other than the send is never marked.
+     *
      * One rewrite for the whole batch: every file on any request's path is
      * rewritten once, type-checked before and after, the requests re-inferred,
      * and every file restored before returning, so the project other requests
      * read is the project the scan loaded.
      *
      * Nothing is read past `deadline`: a batch that runs out keeps the readings
-     * it made and publishes none for the rest.
+     * it made and publishes none for the rest, and marks each of the rest
+     * `unwidened_out_of_budget` (carrick#2100). A request that never needed a
+     * reading (a declared return, nothing to mark) or lost it for a reason of
+     * its own (a marking that added a diagnostic) is never marked.
      */
-    addUnwidenedReadings(responses, extractionConfig, deadline) {
-        const outOfTime = (stage) => {
+    addUnwidenedReadings(responses, extractionConfig, deadline, read) {
+        const outOfTime = (stage, unread) => {
             if (performance.now() <= deadline)
                 return false;
-            this.log(`Unwidened reading stopped ${stage}: it ran out of its budget`);
+            this.log(`Unwidened reading stopped ${stage}: it ran out of its budget, ` +
+                `${unread.length} reading(s) not made`);
+            for (const plan of unread)
+                plan.result.unwidened_out_of_budget = true;
             return true;
         };
         const plans = [];
@@ -634,17 +712,19 @@ export class TypeInferrer {
         const checkedFiles = new Set();
         // Every position is read before the first rewrite: a rewrite forgets
         // every node of its file.
-        for (const { request, result } of responses) {
+        for (const { request, result, readSpan } of responses) {
             // A declared return type is the contract; nothing was widened.
             if (result.is_explicit)
                 continue;
-            const read = this.readNodes.get(result.source_location);
-            if (!read)
+            const readNode = readSpan
+                ? nodeAtSpan(readSpan)
+                : this.readNodes.get(result.source_location);
+            if (!readNode)
                 continue;
-            const functions = pathOf(read);
+            const functions = pathOf(readNode);
             let marked = 0;
             for (const fn of functions) {
-                const insertions = literalInsertions(fn);
+                const insertions = literalInsertions(fn, read === 'request_body' ? readNode : undefined);
                 marked += insertions.length;
                 if (insertions.length === 0)
                     continue;
@@ -673,7 +753,7 @@ export class TypeInferrer {
             plans.push({
                 request,
                 result,
-                read: { file: read.getSourceFile(), start: read.getStart(), end: read.getEnd() },
+                read: { file: readNode.getSourceFile(), start: readNode.getStart(), end: readNode.getEnd() },
                 path,
                 locatedByText,
             });
@@ -685,7 +765,7 @@ export class TypeInferrer {
             insertions.set(file, normalise(list));
         const before = new Map();
         for (const file of checkedFiles) {
-            if (outOfTime('before the rewrite'))
+            if (outOfTime('before the rewrite', plans))
                 return;
             before.set(file, fileDiagnostics(file));
         }
@@ -701,7 +781,7 @@ export class TypeInferrer {
             // holds it loses its reading.
             const tainted = new Set();
             for (const file of checkedFiles) {
-                if (outOfTime('while checking the rewrite'))
+                if (outOfTime('while checking the rewrite', plans))
                     return;
                 const list = insertions.get(file) ?? [];
                 for (const at of addedDiagnostics(before.get(file), fileDiagnostics(file), list)) {
@@ -713,9 +793,10 @@ export class TypeInferrer {
                     }
                 }
             }
-            for (const plan of plans) {
-                if (outOfTime('while re-reading'))
+            for (const [at, plan] of plans.entries()) {
+                if (outOfTime('while re-reading', plans.slice(at).filter((rest) => !tainted.has(rest)))) {
                     return;
+                }
                 if (tainted.has(plan)) {
                     this.log(`Unwidened reading for ${plan.request.file_path}:${plan.request.line_number} ` +
                         'dropped: marking its literals added a diagnostic on its path');
@@ -794,7 +875,7 @@ export class TypeInferrer {
             case 'function_return':
                 return this.inferFunctionReturn(sourceFile, request, extractionConfig);
             case 'response_body':
-                return this.inferResponseBody(sourceFile, request, extractionConfig);
+                return this.withStatedReply(sourceFile, request, this.inferResponseBody(sourceFile, request, extractionConfig));
             case 'call_result':
                 return this.inferCallResult(sourceFile, request, extractionConfig);
             case 'variable':
@@ -901,6 +982,16 @@ export class TypeInferrer {
         if (this.serialisedBodyEnvelopeEngages(awaitedType, func)) {
             return this.inferSerialisedBodyEnvelope(request, func);
         }
+        // A route handler that returns the reply it was handed (`return reply`)
+        // states no body by that return; the reply's type is built from the
+        // route's request type argument (carrick-cloud#2576).
+        const returned = this.returnedExpressions(func);
+        if (returned.length > 0 &&
+            returned.every((expression) => this.isRouteHandlerParameter(this.unwrapExpressionNode(expression), request))) {
+            this.log(`Return at ${request.file_path}:${request.line_number} is an object the ` +
+                'framework handed the handler; it states no body');
+            return null;
+        }
         const unwrapResult = this.unwrapTypeWithConfig(awaitedType, func, extractionConfig);
         if (unwrapResult.wasUnwrapped && !unwrapResult.verifiedMachinery) {
             typeString = unwrapResult.typeString;
@@ -1278,6 +1369,16 @@ export class TypeInferrer {
                 payloadNode = args[0];
             }
         }
+        // A parameter the route registration hands its handler is never the
+        // route's body: not the reply a handler returns (`return reply`), and not
+        // the request the drill reaches in a call that forwards it
+        // (`return finish(request, reply)`), whose type the framework built from
+        // the route's request type argument (carrick-cloud#2576).
+        if (this.isRouteHandlerParameter(payloadNode, request)) {
+            this.log(`Response payload at ${request.file_path}:${request.line_number} is an object ` +
+                'the framework handed the handler; it states no body');
+            return null;
+        }
         const payloadType = payloadNode.getType();
         let typeString = typeText(payloadType, payloadNode);
         const unwrapResult = this.unwrapTypeWithConfig(payloadType, payloadNode, extractionConfig);
@@ -1447,6 +1548,30 @@ export class TypeInferrer {
         }
         return this.receivingCallOf(located, isReturned);
     }
+    /**
+     * True when `node` is a bare reference to a parameter of the handler the
+     * route registration on the request's line hands in (found as
+     * `registrationAtLine` finds it, wrappers included): the request, the reply
+     * or the context the framework passes, never a body the route sends
+     * (carrick-cloud#2576). Where the parameter's type is declared is not read:
+     * a parameter of any other function is data, whether the repo or an
+     * installed package types it (`.then((account) => reply.send(account))`, a
+     * helper's `account: Account`).
+     */
+    isRouteHandlerParameter(node, request) {
+        if (!Node.isIdentifier(node))
+            return false;
+        const owners = (node.getSymbol()?.getDeclarations() ?? [])
+            .filter((decl) => Node.isParameterDeclaration(decl))
+            .map((decl) => decl.getParent().compilerNode);
+        if (owners.length === 0)
+            return false;
+        const sourceFile = this.project.getSourceFile(request.file_path);
+        if (!sourceFile)
+            return false;
+        const handler = this.registrationAtLine(sourceFile, request.line_number)?.handler;
+        return handler !== undefined && owners.includes(handler.compilerNode);
+    }
     /**
      * True when a located call's own result is the route's payload, so the
      * transitional drill into its first argument must not run (carrick#1732).
@@ -1852,6 +1977,16 @@ export class TypeInferrer {
             typeString = explicitType;
             isExplicit = true;
         }
+        // carrick#2714: the body read is cast to a placeholder
+        // (`(await res.json()) as { data: Item[] } | { error: unknown }`) and the
+        // source narrows the value later (`return json as { data: Item[] }`).
+        // The narrowed statement is the body, and it is reported as stated, so a
+        // model symbol naming an element inside it is not kept as the body.
+        const narrowed = func ? this.narrowedBodyStatement(terminalNode, func) : undefined;
+        if (narrowed) {
+            typeString = narrowed.text;
+            isExplicit = true;
+        }
         // carrick#1843: a rule can now match a thenable or a carrier by its alias,
         // so on a result that is a carrier (`Task<Outcome<Reply<T>, E>>`) the
         // rules reach what the carrier holds before the carrier read below does.
@@ -1863,6 +1998,17 @@ export class TypeInferrer {
         const callArgs = this.callResultArguments(callExpr);
         const resultIsCarrier = !explicitType &&
             this.resultCarrierArguments(returnType, terminalNode, callArgs) !== undefined;
+        // carrick#2714, carrick#1841: the call returns a request library's
+        // response object, the body in a member around a status, headers and the
+        // request's config. The body is what the source reads that member as, and
+        // never the object: judged against a producer's body, every transport
+        // member reads as one the producer does not send.
+        if (!explicitType && !resultIsCarrier && func) {
+            const transport = this.transportRuleOfCall(callExpr, extractionConfig);
+            if (transport && !this.callStatesTypedPayload(callExpr, extractionConfig)) {
+                return this.transportCallBody(request, callExpr, func, transport.rule, where);
+            }
+        }
         // carrick#1877: the terminal holds a thenable the names do not peel, a
         // subclass of `Promise` or a class with a `then` of its own. What a
         // caller receives is what `await` yields for it, as it is for the
@@ -2076,7 +2222,9 @@ export class TypeInferrer {
         const leftCarrier = (callUnwrap.wasUnwrapped || readByProtocol) &&
             !!callAfterRules &&
             this.resultCarrierArguments(callAfterRules, callExpr, callArgs) !== undefined;
-        const anchorSource = carrierPayload ?? (leftCarrier ? undefined : callAfterRules);
+        const anchorSource = narrowed?.typeNode
+            ? narrowed.typeNode.getType()
+            : carrierPayload ?? (leftCarrier ? undefined : callAfterRules);
         let anchor = anchorSource
             ? this.unwrapArrayLevels(this.unwrapPromiseType(anchorSource))
             : undefined;
@@ -2125,7 +2273,11 @@ export class TypeInferrer {
         // carrick#1749: say when the text is the source's own statement of the
         // body, and what that statement is rooted at, so the scanner can tell a
         // model symbol that names the body from one that names a part of it.
-        const statedBody = explicitType ? this.statedBodyAtRead(terminalNode) : undefined;
+        const statedBody = narrowed?.typeNode
+            ? this.statedRoot(narrowed.typeNode)
+            : explicitType
+                ? this.statedBodyAtRead(terminalNode)
+                : undefined;
         if (statedBody) {
             inferred.stated_body = statedBody;
         }
@@ -3403,6 +3555,243 @@ export class TypeInferrer {
         }
         return common;
     }
+    /**
+     * What the source narrows a call's value to, where the type stated at the
+     * walk's terminal is a placeholder that leaves a position open
+     * (carrick#2714, `as { data: Item[] } | { error: unknown }`): the one type
+     * stated for the value later in the function, on its success path
+     * (`return json as { data: Item[] }`). A closed statement at the terminal
+     * keeps the answer it had.
+     */
+    narrowedBodyStatement(terminal, func) {
+        const placeholder = this.explicitTypeNodeFromAncestor(terminal);
+        if (!placeholder || !this.leavesAPositionOpen(placeholder))
+            return undefined;
+        const stated = this.statedInFunction(terminal, func, {
+            returned: true,
+            parameters: false,
+            skipFailurePaths: true,
+        });
+        return stated?.typeNode ? stated : undefined;
+    }
+    /**
+     * The rule that verifies a call's result as a request library's response
+     * object, or undefined (carrick#2714). The result is that object when its
+     * awaited type is one a rule recognises. It is that object too when the
+     * call states no type arguments and its declared result, with its free
+     * type parameters at their defaults (`freeResultAtDefaults`), is a type a
+     * rule recognises (`get<T, R = Response<T>>(): Promise<R>`).
+     * The compiler then takes the parameter from where the value goes
+     * (`return client.post(…)` in a function declared `Promise<void>` types the
+     * call `Promise<void>`), and that is the caller's claim about the object,
+     * not what the call returns.
+     */
+    transportRuleOfCall(callExpr, extractionConfig) {
+        if (!extractionConfig || extractionConfig.rules.length === 0)
+            return undefined;
+        const awaited = this.unwrapPromiseType(callExpr.getType());
+        const direct = this.ruleRecognising(awaited, callExpr, extractionConfig);
+        if (direct)
+            return { rule: direct };
+        if (callExpr.getTypeArguments().length > 0)
+            return undefined;
+        const declared = this.freeResultAtDefaults(callExpr);
+        const rule = declared ? this.ruleRecognising(declared, callExpr, extractionConfig) : undefined;
+        return rule ? { rule } : undefined;
+    }
+    /**
+     * The first rule that matches `type` as a wrapper whose body is a member
+     * (`payloadPropertyPath`) the type has, whether or not it reads a payload
+     * out of it. A
+     * wrapper with no such member (the platform's `Response`) is read by its
+     * body reads (`res.json()`), which the def-use walk follows.
+     */
+    ruleRecognising(type, node, config) {
+        return config.rules.find((rule) => !!rule.payloadPropertyPath?.length &&
+            !!type.getProperty(rule.payloadPropertyPath[0]) &&
+            this.tryUnwrapWithRule(type, node, rule, config, 0).kind !== 'no-match');
+    }
+    /**
+     * What a call's declared result is when its free type parameters take
+     * their defaults, or undefined. A parameter is free when the declaration's
+     * result mentions it and none of its parameters do, so only a type
+     * argument, the default or the call's return position can fix it. The
+     * result is read through `Promise`, a free parameter (its default), and a
+     * conditional alias whose check type is a free parameter tested against
+     * exactly that parameter's default (`R extends Default ? Response<T> : R`:
+     * the true branch). Anything else is the type as written.
+     */
+    freeResultAtDefaults(callExpr) {
+        const declaration = this.project
+            .getTypeChecker()
+            .getResolvedSignature(callExpr)
+            ?.getDeclaration();
+        if (!declaration ||
+            !(Node.isMethodSignature(declaration) ||
+                Node.isMethodDeclaration(declaration) ||
+                Node.isFunctionDeclaration(declaration) ||
+                Node.isCallSignatureDeclaration(declaration))) {
+            return undefined;
+        }
+        const returnNode = declaration.getReturnTypeNode();
+        if (!returnNode)
+            return undefined;
+        const referenced = (node) => new Set((node ? [node, ...node.getDescendants()] : [])
+            .filter((n) => Node.isTypeReference(n))
+            .map((n) => n.getTypeName().getText()));
+        const inResult = referenced(returnNode);
+        const inParameters = new Set(declaration.getParameters().flatMap((parameter) => [...referenced(parameter.getTypeNode())]));
+        const free = new Map();
+        for (const parameter of declaration.getTypeParameters()) {
+            const name = parameter.getName();
+            if (inResult.has(name) && !inParameters.has(name))
+                free.set(name, parameter.getDefault());
+        }
+        if (free.size === 0)
+            return undefined;
+        const atDefaults = (node, depth) => {
+            if (!node || depth > 4)
+                return undefined;
+            if (!Node.isTypeReference(node))
+                return node.getType();
+            const name = node.getTypeName().getText();
+            if (free.has(name))
+                return atDefaults(free.get(name), depth + 1);
+            const args = node.getTypeArguments();
+            if ((name === 'Promise' || name === 'PromiseLike') && args.length === 1) {
+                return atDefaults(args[0], depth + 1);
+            }
+            const alias = node
+                .getTypeName()
+                .getSymbol()
+                ?.getDeclarations()
+                .find((d) => Node.isTypeAliasDeclaration(d));
+            const conditional = alias && Node.isTypeAliasDeclaration(alias) ? alias.getTypeNode() : undefined;
+            if (alias && Node.isTypeAliasDeclaration(alias) && conditional && Node.isConditionalTypeNode(conditional)) {
+                const index = alias
+                    .getTypeParameters()
+                    .findIndex((parameter) => parameter.getName() === conditional.getCheckType().getText());
+                const argument = index >= 0 ? args[index] : undefined;
+                const tested = argument && Node.isTypeReference(argument) ? argument.getTypeName().getText() : undefined;
+                const defaulted = tested !== undefined ? free.get(tested) : undefined;
+                if (defaulted && conditional.getExtendsType().getText() === defaulted.getText()) {
+                    return atDefaults(conditional.getTrueType(), depth + 1);
+                }
+            }
+            return node.getType();
+        };
+        return atDefaults(returnNode, 0);
+    }
+    /**
+     * The call states the body itself: the rules read a payload out of its
+     * result (`client.get<Widget>(url)`). An untyped payload is no payload to
+     * the rules (they verify the object and read nothing), and a result its
+     * return position chose is no response object to them.
+     */
+    callStatesTypedPayload(callExpr, extractionConfig) {
+        const unwrap = this.unwrapTypeWithConfig(this.unwrapPromiseType(callExpr.getType()), callExpr, extractionConfig);
+        return unwrap.wasUnwrapped && !unwrap.verifiedMachinery && !!unwrap.payloadType;
+    }
+    /**
+     * The body of a call that returns a response object (carrick#2714): the
+     * one type the source states, in the function the call is made in, for the
+     * reads of the object's payload member (`res.data as Widget`, `const w:
+     * Widget = res.data`, `return res.data` from a function that declares its
+     * return type), through a binding or in place. Where no read states one,
+     * or two state different types, or the object is handed on whole, the
+     * site states no response contract, and the abstain is decided so the
+     * capture does not re-read the call and publish the object.
+     */
+    transportCallBody(request, callExpr, func, rule, where) {
+        const reads = this.payloadMemberReads(callExpr, func, rule.payloadPropertyPath ?? []);
+        const statements = reads
+            .map((read) => this.statedInFunction(read, func, { returned: true, parameters: true, skipFailurePaths: true }))
+            .filter((stated) => stated !== null);
+        const texts = new Set(statements.map((stated) => stated.text));
+        if (texts.size !== 1) {
+            this.log(`Call result at ${where} is a response object around the body, and the source states ` +
+                `${texts.size === 0 ? 'no type' : `${texts.size} different types`} for the body it reads; ` +
+                'this site states no response contract');
+            return this.transportAbstain(request, callExpr, "this call returns the client's response object around the body, and the source " +
+                'states no single type for the body it reads from it, so this site states no ' +
+                'response contract');
+        }
+        const [stated] = statements;
+        this.log(`Call result at ${where} is a response object; the source states its body (${stated.how})`);
+        const anchor = stated.typeNode
+            ? this.unwrapArrayLevels(this.unwrapPromiseType(stated.typeNode.getType()))
+            : undefined;
+        const inferred = this.createInferredType(request, stated.text, true, this.getNodeLocation(stated.at), undefined, anchor ? this.primaryTypeSymbol(anchor.element) : undefined, anchor?.depth, anchor ? this.primaryTypeSymbolSource(anchor.element) : undefined);
+        if (stated.typeNode) {
+            inferred.stated_body = this.statedRoot(stated.typeNode);
+        }
+        return inferred;
+    }
+    /**
+     * The reads of a response object's payload member (`path`, e.g. `data`)
+     * that take it off the call's value: in place (`(await call).data`),
+     * through the name the value is bound to (`res.data`), or as a name
+     * destructured out of it (`const { data } = await call`).
+     */
+    payloadMemberReads(callExpr, func, path) {
+        if (path.length === 0)
+            return [];
+        const follow = (start) => {
+            let node = start;
+            for (const segment of path) {
+                const parent = node.getParent();
+                if (!parent ||
+                    !Node.isPropertyAccessExpression(parent) ||
+                    parent.getExpression() !== node ||
+                    parent.getName() !== segment) {
+                    return undefined;
+                }
+                node = parent;
+            }
+            return node;
+        };
+        let value = callExpr;
+        for (;;) {
+            const parent = value.getParent();
+            if (parent &&
+                (Node.isParenthesizedExpression(parent) ||
+                    Node.isAwaitExpression(parent) ||
+                    Node.isNonNullExpression(parent)) &&
+                parent.getExpression() === value) {
+                value = parent;
+                continue;
+            }
+            break;
+        }
+        const inPlace = follow(value);
+        if (inPlace)
+            return [inPlace];
+        const declaration = value.getParent();
+        if (!declaration || !Node.isVariableDeclaration(declaration) || declaration.getInitializer() !== value) {
+            return [];
+        }
+        const name = declaration.getNameNode();
+        if (Node.isObjectBindingPattern(name)) {
+            if (path.length !== 1)
+                return [];
+            return name
+                .getElements()
+                .filter((element) => !element.getDotDotDotToken() &&
+                (element.getPropertyNameNode()?.getText() ?? element.getName()) === path[0] &&
+                Node.isIdentifier(element.getNameNode()))
+                .map((element) => element.getNameNode());
+        }
+        if (!Node.isIdentifier(name))
+            return [];
+        const symbol = name.getSymbol()?.compilerSymbol;
+        if (!symbol)
+            return [];
+        return func
+            .getDescendantsOfKind(SyntaxKind.Identifier)
+            .filter((id) => id !== name && id.getSymbol()?.compilerSymbol === symbol)
+            .map(follow)
+            .filter((read) => read !== undefined);
+    }
     /**
      * The decided abstain of a call whose result carries transport the
      * service's wrapper rules verify and read no payload out of (carrick#1841,
@@ -6305,14 +6694,17 @@ export class TypeInferrer {
         return undefined;
     }
     /**
-     * The handler function referenced by a route-registration call: the first
+     * The handler function referenced by a route-registration call: the LAST
      * argument that is an inline function, or an identifier bound to a function
-     * (typically the 2nd+ arg — the path literal is not function-valued, so it is
-     * skipped naturally). No callee-name check: a call whose argument resolves to
-     * a function is structurally a registration regardless of the framework.
+     * (carrick#2472 P3-2b). The functions before it are middleware
+     * (`route(path).post(auth, audit, handler)`), which runs first and hands on;
+     * reading the first function read a middleware as the route. The path
+     * literal is not function-valued, so it is skipped naturally. No callee-name
+     * check: a call whose argument resolves to a function is structurally a
+     * registration regardless of the framework.
      */
     handlerFromRegistrationCall(call) {
-        for (const arg of call.getArguments()) {
+        for (const arg of [...call.getArguments()].reverse()) {
             const handler = this.asHandlerFunction(arg);
             if (handler) {
                 return handler;
@@ -6351,15 +6743,17 @@ export class TypeInferrer {
      * declaration (via the compiler's definition nodes) and returned when that
      * declaration is — or initializes to — a function. Anything else (a path
      * literal, an object, a non-function binding) yields undefined.
+     * `followWrapperCalls` false reads a binding to a wrapper call as no
+     * function, so a name the wrapper walk meets is never walked again.
      */
-    asHandlerFunction(node) {
+    asHandlerFunction(node, followWrapperCalls = true) {
         const expr = this.unwrapExpressionNode(node);
         if (Node.isArrowFunction(expr) || Node.isFunctionExpression(expr)) {
             return expr;
         }
         if (Node.isIdentifier(expr)) {
             for (const def of expr.getDefinitionNodes()) {
-                const func = this.functionFromDeclaration(def);
+                const func = this.functionFromDeclaration(def, followWrapperCalls);
                 if (func) {
                     return func;
                 }
@@ -6371,10 +6765,13 @@ export class TypeInferrer {
      * Extract a `FunctionLike` from a declaration node the compiler resolved an
      * identifier to: a function declaration is itself the function; a variable
      * declaration / binding whose initializer is an inline function yields that
-     * function (`const h = async () => { … }`). Import/re-export shims are walked
-     * by ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
+     * function (`const h = async () => { … }`), and one whose initializer is a
+     * wrapper call yields the function the call wraps
+     * (`const h = wrap<Contract>(async (req, res) => { … })`, carrick#2472
+     * P3-2b; `functionWrappedBy`). Import/re-export shims are walked by
+     * ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
      */
-    functionFromDeclaration(decl) {
+    functionFromDeclaration(decl, followWrapperCalls = true) {
         if (Node.isFunctionDeclaration(decl)) {
             return decl;
         }
@@ -6399,10 +6796,43 @@ export class TypeInferrer {
                 if (Node.isArrowFunction(inner) || Node.isFunctionExpression(inner)) {
                     return inner;
                 }
+                if (followWrapperCalls && Node.isCallExpression(inner)) {
+                    return this.functionWrappedBy(inner, 0);
+                }
             }
         }
         return undefined;
     }
+    /**
+     * The function a call wraps, for a name bound to that call and used as a
+     * handler (carrick#2472 P3-2b): the call's one argument that is a function
+     * literal, a name bound to one, or another such call, a few calls deep.
+     *
+     * Two conditions keep this to wrappers. The call's own value has to be
+     * callable, because the name is used as a function: `rows.map((row) => …)`
+     * is handed a function and yields a list. And exactly one argument may be a
+     * function: with two there is no saying which of them is wrapped.
+     */
+    functionWrappedBy(call, depth) {
+        if (depth >= WRAPPER_CALL_MAX_DEPTH)
+            return undefined;
+        if (!this.isCallableType(call.getType()))
+            return undefined;
+        const wrapped = [];
+        for (const arg of call.getArguments()) {
+            const value = this.unwrapExpressionNode(arg);
+            const func = Node.isArrowFunction(value) || Node.isFunctionExpression(value)
+                ? value
+                : Node.isCallExpression(value)
+                    ? this.functionWrappedBy(value, depth + 1)
+                    : Node.isIdentifier(value)
+                        ? this.asHandlerFunction(value, false)
+                        : undefined;
+            if (func)
+                wrapped.push(func);
+        }
+        return wrapped.length === 1 ? wrapped[0] : undefined;
+    }
     /**
      * True when `handler` reads nothing from the incoming message (carrick#827):
      * every use of one of its parameters, named or destructured, is the receiver
@@ -7045,6 +7475,15 @@ export class TypeInferrer {
      * below reads it.
      */
     bodyBuiltByCallee(node) {
+        const read = this.calleeBodyRead(node, 0);
+        return read.kind === 'passes' ? { kind: 'none' } : read;
+    }
+    /**
+     * `bodyBuiltByCallee`, telling apart a callee that sends the argument
+     * unchanged (`passes`) from one that states nothing about it (`none`).
+     * `depth` counts the forwarded locals followed (carrick#2671).
+     */
+    calleeBodyRead(node, depth) {
         const own = node.getType();
         if (own.isAny() || own.isUnknown())
             return { kind: 'none' };
@@ -7107,6 +7546,15 @@ export class TypeInferrer {
                 built.push(value);
                 continue;
             }
+            // carrick#2671: the use builds a local (`const payload = { ...input,
+            // code: norm(input.code) }`) the function then sends unchanged, itself
+            // or through a helper that passes it on as the body. The body is that
+            // local.
+            const forwarded = this.forwardedLocalHolding(use, body, depth);
+            if (forwarded) {
+                built.push(forwarded);
+                continue;
+            }
             const ancestors = use.getAncestors();
             const insideLiteral = ancestors
                 .slice(0, ancestors.indexOf(body))
@@ -7119,7 +7567,7 @@ export class TypeInferrer {
             }
         }
         if (built.length === 0)
-            return { kind: 'none' };
+            return passedThrough ? { kind: 'passes' } : { kind: 'none' };
         if (passedThrough) {
             return { kind: 'abstain', why: `the called function both sends the argument and builds a body from it (${from})` };
         }
@@ -7170,6 +7618,78 @@ export class TypeInferrer {
         }
         return undefined;
     }
+    /**
+     * carrick#2671: the `const` local whose initializer holds `use`, inside
+     * `scope`, when `scope` sends that local unchanged as the body: whole in a
+     * body slot, or as an argument into a function that passes it on as its
+     * body. The local's name, so its declared type is read. Undefined when the
+     * local is never sent, when a further body is built from it, or when a
+     * function lies between `use` and the declaration.
+     */
+    forwardedLocalHolding(use, scope, depth) {
+        if (depth >= 2)
+            return undefined;
+        let current = use;
+        let declaration;
+        while (current !== scope) {
+            const parent = current.getParent();
+            if (!parent)
+                return undefined;
+            if (Node.isArrowFunction(parent) ||
+                Node.isFunctionExpression(parent) ||
+                Node.isFunctionDeclaration(parent) ||
+                Node.isMethodDeclaration(parent)) {
+                return undefined;
+            }
+            if (Node.isVariableDeclaration(parent) && parent.getInitializer() === current) {
+                declaration = parent;
+                break;
+            }
+            current = parent;
+        }
+        if (!declaration)
+            return undefined;
+        if (declaration.getVariableStatement()?.getDeclarationKind() !== VariableDeclarationKind.Const) {
+            return undefined;
+        }
+        const name = declaration.getNameNode();
+        if (!Node.isIdentifier(name))
+            return undefined;
+        const symbol = name.getSymbol()?.compilerSymbol;
+        if (!symbol)
+            return undefined;
+        const checker = this.project.getTypeChecker().compilerObject;
+        let sent = false;
+        for (const ref of scope.getDescendantsOfKind(SyntaxKind.Identifier)) {
+            if (ref === name)
+                continue;
+            const parent = ref.getParent();
+            const refSymbol = parent && Node.isShorthandPropertyAssignment(parent)
+                ? checker.getShorthandAssignmentValueSymbol(parent.compilerNode)
+                : ref.getSymbol()?.compilerSymbol;
+            if (refSymbol !== symbol)
+                continue;
+            if (this.inSendNothingTest(ref, scope))
+                continue;
+            const value = this.bodyValueAround(ref, scope);
+            if (value === ref) {
+                sent = true;
+                continue;
+            }
+            if (value)
+                return undefined;
+            if (parent && Node.isCallExpression(parent) && parent.getArguments().includes(ref)) {
+                const onward = this.calleeBodyRead(ref, depth + 1);
+                if (onward.kind === 'passes') {
+                    sent = true;
+                    continue;
+                }
+                if (onward.kind !== 'none')
+                    return undefined;
+            }
+        }
+        return sent ? name : undefined;
+    }
     /** `value` is `use` behind what `sentValue` sees through. */
     isSameValue(value, use) {
         return this.sentValue(value) === use;
@@ -7442,6 +7962,15 @@ export class TypeInferrer {
      * carrying the provenance the reading recorded.
      */
     declaredRequestInferredType(request, contract, location) {
+        if (contract.noRequestBody !== undefined) {
+            this.log(`Route at ${request.file_path}:${request.line_number} states no request body: ${contract.noRequestBody}`);
+            return this.decidedAbstain(request, location, {
+                path: '',
+                kind: 'unknown',
+                reason: 'no_request_body',
+                detail: contract.noRequestBody,
+            });
+        }
         const inferred = this.createInferredType(request, contract.text, true, location, undefined, undefined);
         if (contract.provenance && contract.provenance.length > 0) {
             inferred.any_provenance = contract.provenance;
@@ -7460,12 +7989,74 @@ export class TypeInferrer {
      * own locator authoritative when a route declares nothing.
      */
     declaredRequestContract(registration, handler) {
+        // carrick#2674: the body member a verified label names, read at the
+        // handler's parameter, comes first. Where no label answers, the old rule
+        // that reads a member by its name stands.
+        const stated = this.statedParams.request(handler, registration);
+        if (stated?.kind === 'body') {
+            const text = this.structuralTextFromType(stated.type, stated.at);
+            if (text) {
+                return { text };
+            }
+        }
         const annotated = this.requestBodyFromHandlerParams(handler);
         if (annotated) {
             return { text: annotated };
         }
-        return (this.routeSchemaContract(registration, 'body') ??
-            this.validatedBodyContract(registration));
+        const schema = this.routeSchemaContract(registration, 'body') ??
+            this.validatedBodyContract(registration);
+        if (schema) {
+            return schema;
+        }
+        return stated?.kind === 'no_body' ? { text: 'unknown', noRequestBody: stated.detail } : null;
+    }
+    /** The stated-parameter reader over `labels`, judging files and statuses as this inferrer does. */
+    statedParamsFor(labels) {
+        return new StatedParams(labels, (file) => {
+            const sourceFile = file.getSourceFile();
+            if (sourceFile.isDeclarationFile())
+                return false;
+            return !isExternalOrigin(this.project.getProgram().compilerObject, sourceFile.compilerNode, this.repoRoot, externalImportsOf(this.project));
+        }, (call) => this.chainStatus(call));
+    }
+    /**
+     * carrick#2674: where today's reading of a route's response is empty
+     * (nothing, `void`, or an `unknown` the inferrer did not decide), the reply
+     * its handler's parameter states, cut to its success variants. A typed
+     * reading, or a decided abstain, stands as it is.
+     */
+    withStatedReply(sourceFile, request, today) {
+        if (!this.statedParams.readsReplies)
+            return today;
+        if (today && !this.isEmptyResponseReading(today))
+            return today;
+        const handler = this.registrationAtLine(sourceFile, request.line_number)?.handler ??
+            this.exportedFunctionOpeningOn(sourceFile, request.line_number);
+        if (!handler)
+            return today;
+        const stated = this.statedParams.reply(handler);
+        if (!stated)
+            return today;
+        const texts = [];
+        for (const variant of stated.variants) {
+            const text = this.structuralTextFromType(variant, stated.at);
+            // A variant holding `any` or `unknown` is one the check refuses as an
+            // anchor (`usable_inferred_text`): publishing it would fall back to the
+            // raw anchor under an explicit flag, so today's reading stands.
+            if (!text || printedTypeHoldsTopType(text))
+                return today;
+            texts.push(text);
+        }
+        this.log(`Route at ${request.file_path}:${request.line_number}: its handler's reply parameter states the body`);
+        return this.createInferredType(request, texts.length === 1 ? texts[0] : texts.map((text) => `(${text})`).join(' | '), true, this.getNodeLocation(handler));
+    }
+    /** Nothing read: `void`, or an `unknown` with no decided reason at its root. */
+    isEmptyResponseReading(inferred) {
+        if (inferred.type_string === 'void')
+            return true;
+        if (inferred.type_string !== 'unknown')
+            return false;
+        return !(inferred.any_provenance ?? []).some((provenance) => provenance.path === '' && DECIDED_ABSTAIN_REASONS.has(provenance.reason));
     }
     /**
      * Anchor (a): the request contract declared on the handler's own signature.
@@ -7678,7 +8269,7 @@ export class TypeInferrer {
                 return;
             const text = this.structuralTextFromTypeNode(typeNode);
             if (text)
-                found.push({ rank, text, at, how });
+                found.push({ rank, text, at, how, typeNode });
         };
         for (let i = 0; i < positions.length; i++) {
             const position = positions[i];
@@ -7765,7 +8356,7 @@ export class TypeInferrer {
             return null;
         }
         const [first] = decided;
-        return { text: first.text, provenance: first.provenance, at: first.at, how: first.how };
+        return { text: first.text, provenance: first.provenance, at: first.at, how: first.how, typeNode: first.typeNode };
     }
     /**
      * What a call that takes the value at argument `index` states for it:
@@ -8990,3 +9581,12 @@ export class TypeInferrer {
         console.error(`[sidecar:type-inferrer:error] ${message}`);
     }
 }
+/** The node a `SavedSpan` was taken from, in the file as it reads now. */
+function nodeAtSpan(span) {
+    let node = span.file.getDescendantAtPos(span.start);
+    while (node &&
+        !(node.getStart() === span.start && node.getEnd() === span.end && node.getKind() === span.kind)) {
+        node = node.getParent();
+    }
+    return node;
+}