carrick 0.3.127 → 0.3.129

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';
@@ -187,6 +188,18 @@ const WRAPPER_CALL_MAX_DEPTH = 3;
  * 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.',
@@ -448,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) {
@@ -491,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})`);
@@ -521,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 {
@@ -536,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
@@ -620,6 +682,10 @@ 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
@@ -631,7 +697,7 @@ export class TypeInferrer {
      * 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) {
+    addUnwidenedReadings(responses, extractionConfig, deadline, read) {
         const outOfTime = (stage, unread) => {
             if (performance.now() <= deadline)
                 return false;
@@ -646,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;
@@ -685,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,
             });
@@ -807,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':
@@ -1909,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.
@@ -1920,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
@@ -2133,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;
@@ -2182,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;
         }
@@ -3460,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,
@@ -7630,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;
@@ -7648,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.
@@ -7866,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];
@@ -7953,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:
@@ -9178,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;
+}