carrick 0.3.105 → 0.3.107

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

@@ -20,8 +20,10 @@
 import * as path from 'node:path';
 import { Node, SyntaxKind, ts, } from 'ts-morph';
 import { validateInferRequestItem } from './validators.js';
+import { notePrintedType, PrintedTypes } from './printed-names.js';
 import { externalImportsOf, isExternalOrigin } from './origin.js';
 import { reachedOnlyOnFailure } from './failure-path.js';
+import { functionAtLine } from './function-line-index.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, } from './type-structural-expander.js';
 /**
@@ -220,6 +222,14 @@ const REQUEST_BODY_PARTS = new Set(['json', 'form', 'body']);
  * these names; a type parameter alone also types response modes and fallbacks.
  */
 const BODY_MEMBER_NAMES = new Set(['data', 'body', 'json']);
+/**
+ * The zero-argument reads that take the WHOLE body out of a transport response
+ * (the platform `Response` and the clients that copy its shape): parsed as
+ * JSON, or as raw text (carrick#1842).
+ */
+const WHOLE_BODY_READS = new Set(['json', 'text']);
+/** The body format a caller names to read a response as raw text (carrick#1842). */
+const RAW_TEXT_FORMAT = 'text';
 /**
  * Print a `Type` to its string form WITHOUT the compiler's default truncation.
  *
@@ -230,18 +240,33 @@ const BODY_MEMBER_NAMES = new Set(['data', 'body', 'json']);
  */
 const TYPE_TEXT_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias;
 function typeText(type, enclosingNode) {
-    return type.getText(enclosingNode, TYPE_TEXT_FLAGS);
+    const text = type.getText(enclosingNode, TYPE_TEXT_FLAGS);
+    notePrintedType(type, enclosingNode, text);
+    return text;
+}
+/**
+ * `text` is `string`, alone or beside `null` and `undefined` in either order:
+ * the only payload a raw-text read publishes (carrick#1842).
+ */
+function isBareStringText(text) {
+    const members = text.split('|').map((member) => member.trim());
+    return (members.includes('string') &&
+        members.every((member) => member === 'string' || member === 'null' || member === 'undefined'));
 }
 /**
  * How long the unwidened reading of one batch may take by default. The
  * reading adds a field and never an answer, so running out costs only the
- * readings not yet made; the rewrite is always undone.
+ * readings not yet made; the rewrite is always undone. It reports no
+ * progress, so this is also the longest a batch goes silent after its last
+ * request: well inside the 900s the scanner allows between two signs of life.
  */
 const UNWIDENED_BUDGET_MS = 120_000;
 /**
- * No reading starts or continues past this long after the batch began: the
- * scanner's read deadline for one request is 900s, and the inferences the
- * batch already made must reach it.
+ * No reading starts or continues past this long after the batch began. The
+ * number dates from when the scanner allowed a whole request 900s; it now
+ * allows that long between progress reports (carrick#1914), so a batch can
+ * run past this and still be read. A batch that does publishes no unwidened
+ * reading, as before.
  */
 const UNWIDENED_LATEST_MS = 600_000;
 /**
@@ -286,32 +311,39 @@ export class TypeInferrer {
      *
      * @param requests - Array of inference requests
      * @param extractionConfig - Agent-generated extraction config for payload unwrapping
+     * @param onRequestDone - Called once per request, as the batch is done with it
      * @returns InferResult with inferred types or errors
      */
-    infer(requests, extractionConfig) {
+    infer(requests, extractionConfig, onRequestDone) {
         const started = performance.now();
         const inferredTypes = [];
         const errors = [];
         /** Response inferences the unwidened reading re-reads (carrick#1516). */
         const responses = [];
         for (const request of requests) {
-            // Plain JavaScript has no type annotations to extract, and `checkJs` is
-            // off, so inferring against a `.js` file yields nothing useful — it only
-            // crashes deep in the compiler API on undefined symbols (`escapedName`,
-            // `flags`) and floods the log with the resulting error strings. Skip it.
-            // `allowJs` stays on so `.ts` files can still resolve `.js` imports.
-            if (/\.(js|jsx|mjs|cjs)$/i.test(request.file_path)) {
-                continue;
-            }
             try {
+                // Plain JavaScript has no type annotations to extract, and `checkJs` is
+                // off, so inferring against a `.js` file yields nothing useful — it only
+                // crashes deep in the compiler API on undefined symbols (`escapedName`,
+                // `flags`) and floods the log with the resulting error strings. Skip it.
+                // `allowJs` stays on so `.ts` files can still resolve `.js` imports.
+                if (/\.(js|jsx|mjs|cjs)$/i.test(request.file_path)) {
+                    continue;
+                }
                 const loc = this.formatRequestLocation(request);
                 const itemError = validateInferRequestItem(request);
                 if (itemError) {
                     errors.push(`Invalid infer item at ${request.file_path}:${loc} (${request.infer_kind}): ${itemError}`);
                     continue;
                 }
-                const result = this.inferSingle(request, extractionConfig);
+                // carrick#1836: what the names the published text prints meant, read
+                // while the program the prints were made in is still the project's.
+                // The unwidened re-read below records nothing: it prints the same
+                // node, and its reading has a budget.
+                const prints = new PrintedTypes();
+                const result = prints.during(() => this.inferSingle(request, extractionConfig));
                 if (result) {
+                    this.recordPrintedNames(result, request, prints);
                     inferredTypes.push(result);
                     if (request.infer_kind === 'response_body' || request.infer_kind === 'function_return') {
                         responses.push({ request, result });
@@ -326,6 +358,9 @@ export class TypeInferrer {
                 const loc = this.formatRequestLocation(request);
                 errors.push(`Error inferring type at ${request.file_path}:${loc}: ${error}`);
             }
+            finally {
+                onRequestDone?.();
+            }
         }
         try {
             const deadline = Math.min(performance.now() + this.unwidenedBudgetMs, started + UNWIDENED_LATEST_MS);
@@ -341,6 +376,18 @@ export class TypeInferrer {
             errors: errors.length > 0 ? errors : undefined,
         };
     }
+    /**
+     * carrick#1836: list on `result` the declarations behind the names its text
+     * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
+     */
+    recordPrintedNames(result, request, prints) {
+        const sourceFile = this.getSourceFile(request.file_path);
+        if (!sourceFile)
+            return;
+        const printedNames = prints.namesIn([result.type_string], sourceFile.compilerNode, this.project.getTypeChecker().compilerObject);
+        if (printedNames.length > 0)
+            result.printed_names = printedNames;
+    }
     /**
      * carrick#1516: read each response inference again with the literals on its
      * handler's path marked `as const`, and record the narrower type the handler
@@ -733,7 +780,7 @@ export class TypeInferrer {
             return null;
         }
         const anchor = this.unwrapArrayLevels(awaitedType);
-        const inferred = this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(func), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth);
+        const inferred = this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(func), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
         if (provenance && provenance.length > 0) {
             inferred.any_provenance = provenance;
         }
@@ -975,7 +1022,7 @@ export class TypeInferrer {
             typeString = this.expandResolvedTypeStructural(resolved, typeString, this.wireFormatFor(request));
         }
         const anchor = this.unwrapArrayLevels(this.unwrapPromiseType(payloadType));
-        return this.createInferredType(request, typeString, false, this.getNodeLocation(payloadNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth);
+        return this.createInferredType(request, typeString, false, this.getNodeLocation(payloadNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
     }
     /**
      * True when a located call's own result is the route's payload, so the
@@ -1031,7 +1078,12 @@ export class TypeInferrer {
         // resolved symbol is the better answer and keeps its precedence.
         const stated = recovered.statedTypeNode;
         const writtenAnchor = resolvedSymbol === undefined && stated ? this.writtenAnchorOf(stated) : undefined;
-        return this.createInferredType(request, recovered.typeString, recovered.isExplicit, this.getNodeLocation(recovered.node), undefined, resolvedSymbol ?? writtenAnchor?.symbol, writtenAnchor ? writtenAnchor.depth : recoveredAnchor?.depth, writtenAnchor?.source);
+        // carrick#1819: a symbol the resolved type carries has a declaration file
+        // as much as one read off the annotation does.
+        const resolvedSource = resolvedSymbol !== undefined && recoveredAnchor
+            ? this.primaryTypeSymbolSource(recoveredAnchor.element)
+            : undefined;
+        return this.createInferredType(request, recovered.typeString, recovered.isExplicit, this.getNodeLocation(recovered.node), undefined, resolvedSymbol ?? writtenAnchor?.symbol, writtenAnchor ? writtenAnchor.depth : recoveredAnchor?.depth, writtenAnchor ? writtenAnchor.source : resolvedSource);
     }
     /**
      * carrick#1161: type a route response from every send in the handler the
@@ -1196,6 +1248,38 @@ export class TypeInferrer {
             typeString = explicitType;
             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.
+        // That changes who finds the payload, never what is published: where the
+        // rules read through the carrier, their answer is given the way the
+        // carrier read gives its own. A result that is no carrier keeps the
+        // answer it had.
+        const where = `${request.file_path}:${request.line_number}`;
+        const resultIsCarrier = !explicitType && this.resultCarrierArguments(returnType, terminalNode) !== undefined;
+        // 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
+        // `Promise<T>` the text unwrap at the end of this function peels: the
+        // class is transport. A rule that matched the type as written, a type the
+        // source states and a carrier behind the thenable have each answered
+        // already and keep their answers.
+        if (!unwrapResult.wasUnwrapped && !explicitType && !resultIsCarrier) {
+            const yielded = this.awaitedBeyondPromise(returnType);
+            if (yielded) {
+                typeString = typeText(yielded, terminalNode);
+            }
+        }
+        // The rules verified what the carrier holds as transport and read no
+        // payload out of it (`Reply<unknown>`). That is the decision carrick#1841
+        // makes below, and it is decided here for the same reason: left
+        // undecided, the capture's own locator re-reads the raw call and
+        // publishes the library's objects.
+        if (unwrapResult.verifiedMachinery && resultIsCarrier) {
+            this.log(`Call result at ${where} is a carrier of transport the service's wrapper rules ` +
+                'verify and read no payload out of; this site states no response contract');
+            return this.transportAbstain(request, callExpr);
+        }
         // carrick#1376: the call answers a RESULT CARRIER — a generic union whose
         // branches say whether the call worked and carry, on the success side, the
         // value it produced. The carrier is the transport's own bookkeeping; the
@@ -1203,22 +1287,67 @@ export class TypeInferrer {
         // the carrier instead reports an envelope as a wire contract, which is the
         // same class of answer the machinery guard refuses on the producer side.
         //
-        // A wrapper rule that already unwrapped, and a type the source itself
-        // states, both outrank this: they are what the service's own config and
-        // its own author said.
-        const carrierCandidate = unwrapResult.wasUnwrapped || explicitType
+        // A type the source itself states outranks this: it is what the author
+        // said. A wrapper rule that unwrapped is read first, and on a carrier it
+        // no longer ends the matter (carrick#1843):
+        //
+        //  - a service with a rule for `Task` and none for `Outcome` leaves
+        //    `Outcome<Reply<T>, E>`, which is as much a carrier as it was before
+        //    the rule could match. The carrier read takes what the rule left.
+        //  - a service with a rule for `Outcome` too reads the payload out of the
+        //    carrier itself. That payload is what the carrier holds, and is
+        //    published as the carrier read publishes it, so a site answers the
+        //    same whichever of the two found its payload.
+        //
+        // A rule that left no single payload (a union join) leaves nothing to
+        // read.
+        const afterRules = unwrapResult.wasUnwrapped ? unwrapResult.payloadType : returnType;
+        const readThroughCarrier = unwrapResult.wasUnwrapped &&
+            resultIsCarrier &&
+            !!afterRules &&
+            this.resultCarrierArguments(afterRules, terminalNode) === undefined;
+        const carrierCandidate = explicitType || !afterRules
             ? undefined
-            : this.resultCarrierPayload(returnType, terminalNode, use.projections, `${request.file_path}:${request.line_number}`);
+            : readThroughCarrier
+                ? afterRules
+                : this.resultCarrierPayload(afterRules, terminalNode, use.projections, where);
+        // carrick#1841: what the carrier holds goes through the service's wrapper
+        // rules before it is published, as the call's own result did. The carrier
+        // is found by its shape, so what it holds can still be a library's
+        // envelope: a request library answers `Task<Outcome<Reply<T>, E>>`, and
+        // `Reply<T>` is that library's response object, a status, a url and
+        // headers around the body. Where a rule reads a payload out of it, that
+        // payload is the body. Where a rule verifies it as the library's transport
+        // and reads nothing out of it, this site states no contract, and the
+        // transport object must not stand in for one: judged against a
+        // producer's body, every member it adds reads as a field the producer
+        // does not send.
+        //
+        // The abstain is decided, so it rides the row (`machinery_envelope` at the
+        // root, no anchor). A plain `null` is re-read by the capture's own
+        // locator, which would resolve the raw call and publish the carrier.
+        const carrierUnwrap = carrierCandidate
+            ? this.unwrapTypeWithConfig(carrierCandidate, terminalNode, extractionConfig)
+            : undefined;
+        if (carrierCandidate &&
+            carrierUnwrap?.wasUnwrapped &&
+            carrierUnwrap.typeString.trim() === 'unknown') {
+            const carried = typeText(carrierCandidate, terminalNode);
+            this.log(`Call result at ${where} carries ${carried}, which the service's wrapper rules ` +
+                'verify as transport and read no payload out of; this site states no response contract');
+            return this.transportAbstain(request, callExpr);
+        }
+        const carried = carrierUnwrap?.wasUnwrapped && carrierUnwrap.payloadType
+            ? carrierUnwrap.payloadType
+            : carrierCandidate;
         // The payload rides the row as its own MEMBERS, never as its bare name
         // (#257): `derive_capture_anchors` turns a usable inference into a literal
         // capture anchor, and a bare name is out of scope where the surface
         // declares the alias, so it would decay to a top type and publish nothing
         // — trading a wrong answer for no answer. Where the payload carries no
         // member shape to print, the carrier keeps its own answer.
-        const carrierText = carrierCandidate
-            ? this.structuralTextFromType(carrierCandidate, terminalNode)
-            : null;
-        const carrierPayload = carrierText ? carrierCandidate : undefined;
+        const carrierText = carried ? this.structuralTextFromType(carried, terminalNode) : null;
+        const carrierPayload = carrierText ? carried : undefined;
         if (carrierPayload && carrierText) {
             typeString = carrierText;
         }
@@ -1281,19 +1410,40 @@ export class TypeInferrer {
         // to no single payload (union join, verified machinery) carries no
         // payloadType and anchors nothing; the wrapper's own symbol must never
         // anchor via that path.
-        const callPayloadType = this.unwrapPromiseType(callExpr.getType());
-        const callUnwrap = this.unwrapTypeWithConfig(callPayloadType, callExpr, extractionConfig);
+        //
+        // carrick#1877: the call's payload is what `await` yields for the call's
+        // type. Where no rule matched that type as the names peel it, the same
+        // protocol reading the text takes is read here, so a subclass of
+        // `Promise` anchors the row on what it resolves to and never on itself.
+        let callPayloadType = this.unwrapPromiseType(callExpr.getType());
+        let callUnwrap = this.unwrapTypeWithConfig(callPayloadType, callExpr, extractionConfig);
+        let readByProtocol = false;
+        if (!callUnwrap.wasUnwrapped) {
+            const yielded = this.awaitedBeyondPromise(callPayloadType);
+            if (yielded) {
+                callPayloadType = yielded;
+                callUnwrap = this.unwrapTypeWithConfig(yielded, callExpr, extractionConfig);
+                readByProtocol = true;
+            }
+        }
         // carrick#1376: the carrier's own symbol must never anchor either. The
         // surface pre-claims the alias from the anchor, so anchoring on the
         // carrier makes the capture emit the transport's bookkeeping as the
         // operation's declaration — and where the carrier is a local interface the
         // service does not export, nothing is emitted at all and the row reads
         // null. The payload the carrier was found to hold is the anchor.
-        const anchorSource = carrierPayload
-            ? carrierPayload
-            : callUnwrap.wasUnwrapped
-                ? callUnwrap.payloadType
-                : callPayloadType;
+        //
+        // carrick#1843: that holds for a carrier a rule left of the call's own
+        // result too. A rule for `Task` alone turns `Task<Outcome<T, E>>` into
+        // `Outcome<T, E>` here, and where the terminal's read took no payload out
+        // of it (an open payload, or a terminal further down a chain) the
+        // carrier's alias would otherwise be the anchor. The same holds for a
+        // carrier the protocol reading left (carrick#1877).
+        const callAfterRules = callUnwrap.wasUnwrapped ? callUnwrap.payloadType : callPayloadType;
+        const leftCarrier = (callUnwrap.wasUnwrapped || readByProtocol) &&
+            !!callAfterRules &&
+            this.resultCarrierArguments(callAfterRules, callExpr) !== undefined;
+        const anchorSource = carrierPayload ?? (leftCarrier ? undefined : callAfterRules);
         let anchor = anchorSource
             ? this.unwrapArrayLevels(this.unwrapPromiseType(anchorSource))
             : undefined;
@@ -1338,7 +1488,7 @@ export class TypeInferrer {
                 }
             }
         }
-        const inferred = this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(terminalNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, anchor ? this.primaryTypeSymbol(anchor.element) : undefined, anchor?.depth);
+        const inferred = this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(terminalNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, anchor ? this.primaryTypeSymbol(anchor.element) : undefined, anchor?.depth, anchor ? this.primaryTypeSymbolSource(anchor.element) : undefined);
         // 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.
@@ -1346,8 +1496,101 @@ export class TypeInferrer {
         if (statedBody) {
             inferred.stated_body = statedBody;
         }
+        // carrick#1842: `string` cannot tell a body read as raw text from a JSON
+        // body that is a string, and raw text states no structural contract. The
+        // row says which it is, so the check phase can read the pair unverifiable
+        // instead of comparing `string` with the other side's body.
+        if (isBareStringText(typeString) &&
+            (this.textReadAtTerminal(callExpr, terminalNode) || this.callChoosesTextBody(callExpr))) {
+            inferred.raw_text_read = true;
+        }
         return inferred;
     }
+    /**
+     * The terminal of a call's def-use walk is a zero-argument `.text()` read of
+     * the call's own result (carrick#1842): on its binding (`res.text()`,
+     * through a declaration, `await` or a cast), or in the callback a `then` on
+     * the call hands the response to (`fetch(u).then((res) => res.text())`).
+     */
+    textReadAtTerminal(callExpr, terminal) {
+        const value = Node.isVariableDeclaration(terminal) ? terminal.getInitializer() : terminal;
+        const read = value ? this.unwrapExpressionNode(value) : undefined;
+        if (!read || !Node.isCallExpression(read))
+            return false;
+        const callResult = this.unwrapPromiseType(callExpr.getType()).compilerType;
+        if (this.isTextReadOf(read, (receiver) => receiver === callExpr ||
+            this.unwrapPromiseType(receiver.getType()).compilerType === callResult)) {
+            return true;
+        }
+        const then = read.getExpression();
+        if (!Node.isPropertyAccessExpression(then) ||
+            then.getName() !== 'then' ||
+            this.unwrapExpressionNode(then.getExpression()) !== callExpr) {
+            return false;
+        }
+        const callback = read.getArguments()[0];
+        if (!callback || (!Node.isArrowFunction(callback) && !Node.isFunctionExpression(callback))) {
+            return false;
+        }
+        const param = callback.getParameters()[0]?.getNameNode();
+        if (!param || !Node.isIdentifier(param))
+            return false;
+        const returned = this.returnedExpressions(callback);
+        const inner = returned.length === 1 ? this.unwrapExpressionNode(returned[0]) : undefined;
+        return (!!inner &&
+            Node.isCallExpression(inner) &&
+            this.isTextReadOf(inner, (receiver) => Node.isIdentifier(receiver) && receiver.getSymbol() === param.getSymbol()));
+    }
+    /** `call` is `<receiver>.text()` with no arguments, and `accept` takes its receiver. */
+    isTextReadOf(call, accept) {
+        const access = call.getExpression();
+        return (Node.isPropertyAccessExpression(access) &&
+            access.getName() === RAW_TEXT_FORMAT &&
+            call.getArguments().length === 0 &&
+            accept(this.unwrapExpressionNode(access.getExpression())));
+    }
+    /**
+     * The call's resolved signature, at this site, types a member of an object
+     * argument as exactly the literal `'text'`, and the source passes that
+     * literal there (carrick#1842). That is how a request library lets a caller
+     * choose a text body from the formats it offers (`{ type: 'text' }`): a
+     * generic config instantiated by the literal, or an overload taken by it.
+     * A member typed as a wider union (`kind: 'text' | 'image'`) chooses no
+     * format, and no member name is read.
+     */
+    callChoosesTextBody(callExpr) {
+        const checker = this.project.getTypeChecker().compilerObject;
+        let signature;
+        try {
+            signature = checker.getResolvedSignature(callExpr.compilerNode);
+        }
+        catch {
+            return false;
+        }
+        if (!signature || signature.parameters.length === 0)
+            return false;
+        return callExpr.getArguments().some((argument, index) => {
+            if (!Node.isObjectLiteralExpression(argument))
+                return false;
+            const parameter = signature.parameters[Math.min(index, signature.parameters.length - 1)];
+            const parameterType = checker.getTypeOfSymbolAtLocation(parameter, callExpr.compilerNode);
+            return argument.getProperties().some((property) => {
+                if (!Node.isPropertyAssignment(property))
+                    return false;
+                const value = property.getInitializer();
+                if (!value ||
+                    !(Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value)) ||
+                    value.getLiteralValue() !== RAW_TEXT_FORMAT) {
+                    return false;
+                }
+                const member = checker.getPropertyOfType(parameterType, property.getName());
+                if (!member)
+                    return false;
+                const declared = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(member, callExpr.compilerNode));
+                return declared.isStringLiteral() && declared.value === RAW_TEXT_FORMAT;
+            });
+        });
+    }
     /**
      * What the source states the body read at `terminal` to be, when the type
      * `extractExplicitTypeFromAncestor` printed for it is stated AT the read
@@ -1459,10 +1702,12 @@ export class TypeInferrer {
             symbol = symbol.getAliasedSymbol() ?? symbol;
         }
         const source = symbol?.getDeclarations()[0]?.getSourceFile().getFilePath();
+        const typeArguments = node.getTypeArguments().length;
         return {
             root: nameNode.getText(),
             ...(source ? { root_source: source } : {}),
             ...depthField,
+            ...(typeArguments > 0 ? { root_type_arguments: typeArguments } : {}),
         };
     }
     inferVariable(sourceFile, request, extractionConfig) {
@@ -1801,6 +2046,21 @@ export class TypeInferrer {
                 return { terminal: returnExpr, projectionOnly: false, projections: [] };
             }
         }
+        // carrick#1851: the source reads the body in place on the call's own
+        // value, `const body = await (await fetch(url)).text()`. No binding holds
+        // the response, so the walk below has nothing to follow, and the call
+        // itself would stand as the terminal and publish the transport object.
+        // The read is the terminal, as it is when the walk finds it on a binding,
+        // and a call that takes the read and states what it returns says more
+        // than the read does (carrick#1382).
+        const inPlaceRead = this.bodyReadOnCallValue(callExpr);
+        if (inPlaceRead) {
+            return {
+                terminal: this.statedPayloadAroundBodyRead(inPlaceRead) ?? inPlaceRead,
+                projectionOnly: false,
+                projections: [],
+            };
+        }
         const binding = this.extractBindingFromCall(callExpr);
         if (binding && func) {
             let currentNames = binding.names;
@@ -1834,9 +2094,9 @@ export class TypeInferrer {
                     continue;
                 }
                 // The body a caller reads OUT of a transport response IS the payload
-                // of the call that produced it: `res.json()` on the tracked binding,
-                // with whatever `as T` the source states around it read by
-                // `extractExplicitTypeFromAncestor` below. A bare identifier never
+                // of the call that produced it: `res.json()` or `res.text()` on the
+                // tracked binding, with whatever `as T` the source states around it
+                // read by `extractExplicitTypeFromAncestor` below. A bare identifier never
                 // matches `expressionUsesNames` (it tests DESCENDANTS), so without
                 // this the body read is invisible to the def-use walk.
                 if (Node.isIdentifier(expr) && this.isIdentifierUsage(expr, currentNames)) {
@@ -1962,36 +2222,11 @@ export class TypeInferrer {
      * reader can see is an envelope.
      */
     resultCarrierPayload(type, at, projections, where) {
-        const carrier = this.unwrapThenableType(this.unwrapPromiseType(type));
-        if (!carrier.isUnion()) {
-            return undefined;
-        }
-        const branches = carrier.getUnionTypes();
-        if (branches.length < 2 || !branches.every((branch) => this.isObjectShape(branch))) {
-            return undefined;
-        }
-        const args = [
-            ...carrier.getAliasTypeArguments(),
-            ...carrier.getTypeArguments(),
-        ];
-        if (args.length < 2) {
-            return undefined;
-        }
-        // A type argument only names a payload when a branch actually holds it:
-        // a generic that parameterises a status code or a key carries nothing.
-        const carried = args.filter((arg) => branches.some((branch) => branch
-            .getProperties()
-            .some((property) => {
-            try {
-                return property.getTypeAtLocation(at).getText() === arg.getText();
-            }
-            catch {
-                return false;
-            }
-        })));
-        if (carried.length === 0) {
+        const shape = this.resultCarrierArguments(type, at);
+        if (!shape) {
             return undefined;
         }
+        const { carrier, carried } = shape;
         const argTexts = new Map(carried.map((arg) => [arg.getText(), arg]));
         const read = new Set();
         for (const projection of projections) {
@@ -2026,12 +2261,102 @@ export class TypeInferrer {
         return undefined;
     }
     /**
-     * `Future<T>` -> `T` for a promise-like of the source's own making, read off
-     * the await protocol rather than a name: a `then` whose first parameter is a
-     * callback, whose own first parameter is the value awaiting it yields.
-     * `Promise` and `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     * The shape test of `resultCarrierPayload`: the carrier `type` is, once a
+     * promise-like around it is peeled, and the type arguments a branch of it
+     * holds as a member. `undefined` when `type` is not a carrier.
+     */
+    resultCarrierArguments(type, at) {
+        const carrier = this.unwrapThenableType(this.unwrapPromiseType(type));
+        if (!carrier.isUnion()) {
+            return undefined;
+        }
+        const branches = carrier.getUnionTypes();
+        if (branches.length < 2 || !branches.every((branch) => this.isObjectShape(branch))) {
+            return undefined;
+        }
+        const args = [
+            ...carrier.getAliasTypeArguments(),
+            ...carrier.getTypeArguments(),
+        ];
+        if (args.length < 2) {
+            return undefined;
+        }
+        // A type argument only names a payload when a branch actually holds it:
+        // a generic that parameterises a status code or a key carries nothing.
+        const carried = args.filter((arg) => branches.some((branch) => branch
+            .getProperties()
+            .some((property) => {
+            try {
+                return property.getTypeAtLocation(at).getText() === arg.getText();
+            }
+            catch {
+                return false;
+            }
+        })));
+        return carried.length === 0 ? undefined : { carrier, carried };
+    }
+    /**
+     * The decided abstain of a call whose result carries transport the
+     * service's wrapper rules verify and read no payload out of (carrick#1841,
+     * carrick#1843): `unknown` with `machinery_envelope` at the root and no
+     * anchor. The root reason is what keeps the capture's own locator from
+     * re-reading the raw call (`inference_decided_no_contract`,
+     * engine/type_compat_v2.rs).
+     */
+    transportAbstain(request, callExpr) {
+        const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(callExpr));
+        abstain.any_provenance = [
+            {
+                path: '',
+                kind: 'unknown',
+                reason: 'machinery_envelope',
+                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',
+            },
+        ];
+        return abstain;
+    }
+    /**
+     * `Future<T>` -> `T` for a thenable, read off the await protocol rather
+     * than a name: a `then` whose first parameter is a callback, whose own
+     * first parameter is the value awaiting it yields. `Promise` and
+     * `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     *
+     * The callback is read through `null` and `undefined` (carrick#1877). A
+     * `then` of the source's own making declares `(value: T) => void`; the
+     * platform's declares `onfulfilled?: ((value: T) => ...) | null`, and that
+     * is the `then` a subclass of `Promise` inherits. Read as written, an
+     * optional, nullable callback has no call signature, and the subclass was
+     * not seen as a thenable at all.
+     *
+     * A `then` that cannot be called, or whose first parameter is no callback,
+     * is no protocol, and the type is returned as it is.
+     *
+     * The compiler's own awaited type arbitrates. This walk reads the first
+     * signature of `then`; the language reads all of them. Where awaiting the
+     * type and awaiting what this walk found are not the same thing to the
+     * compiler (an overloaded `then` whose first signature is not the one
+     * `await` takes), the walk did not read the protocol, and the type is
+     * returned as it is rather than published as a guess.
      */
     unwrapThenableType(type) {
+        const yielded = this.firstThenValue(type);
+        if (yielded === type)
+            return type;
+        try {
+            const checker = this.project.getTypeChecker().compilerObject;
+            const awaited = checker.getAwaitedType(type.compilerType);
+            return awaited !== undefined && awaited === checker.getAwaitedType(yielded.compilerType)
+                ? yielded
+                : type;
+        }
+        catch {
+            return type;
+        }
+    }
+    /** The value `then`'s first signature hands its callback, read until it stops changing. */
+    firstThenValue(type) {
         let current = type;
         for (let depth = 0; depth < 8; depth++) {
             const then = current.getProperty('then');
@@ -2044,7 +2369,8 @@ export class TypeInferrer {
                     .getTypeAtLocation(declaration)
                     .getCallSignatures()[0]
                     ?.getParameters()[0]
-                    ?.getTypeAtLocation(declaration);
+                    ?.getTypeAtLocation(declaration)
+                    .getNonNullableType();
             }
             catch {
                 return current;
@@ -2059,6 +2385,18 @@ export class TypeInferrer {
         }
         return current;
     }
+    /**
+     * What `await` yields for `type` where the names do not say: `type` is,
+     * once `Promise` and `PromiseLike` are peeled, a thenable by the protocol
+     * (a subclass of `Promise`, a class with a `then` of its own). `undefined`
+     * where the names say it all or `type` is no thenable, so a caller keeps
+     * the reading it had (carrick#1877).
+     */
+    awaitedBeyondPromise(type) {
+        const named = this.unwrapPromiseType(type);
+        const yielded = this.unwrapThenableType(named);
+        return yielded === named ? undefined : yielded;
+    }
     /**
      * The platform's error shape, in full: `name` and `message` strings AND a
      * `stack`, which is what the `Error` interface declares and every subclass
@@ -2094,10 +2432,10 @@ export class TypeInferrer {
      * `query.data`, `envelope` in `envelope.list[0]` — or `undefined` when the
      * identifier names the value itself.
      *
-     * A member CALL is not a projection: `res.text()` yields a body rather than
+     * A member CALL is not a projection: `res.blob()` yields a body rather than
      * a part of one, and what it returns stays the walk's business. The
-     * zero-argument json body read has its own branch and is taken before this
-     * is asked.
+     * zero-argument json and text body reads have their own branch and are
+     * taken before this is asked.
      */
     projectionOnReceiver(identifier) {
         const access = identifier.getParent();
@@ -2340,12 +2678,42 @@ export class TypeInferrer {
                 !this.leavesAPositionOpen(statedNode));
         });
     }
-    bodyReadOnReceiver(identifier) {
-        const access = identifier.getParent();
+    /**
+     * The zero-argument whole-body read taken in place on the value `callExpr`
+     * yields, or `undefined` (carrick#1851): `(await fetch(url)).text()`. The
+     * receiver is the call itself, through the wrappers that leave a value as
+     * it is (parentheses, `await`, `!`), so it is the same read
+     * `bodyReadOnReceiver` finds on a binding of that value. A call that is not
+     * awaited first is read the same way: a request that is a promise and reads
+     * its own body (`send(url).json()`) yields the body from that read too.
+     */
+    bodyReadOnCallValue(callExpr) {
+        let value = callExpr;
+        for (;;) {
+            const parent = value.getParent();
+            if (!parent ||
+                !(Node.isParenthesizedExpression(parent) ||
+                    Node.isAwaitExpression(parent) ||
+                    Node.isNonNullExpression(parent)) ||
+                parent.getExpression() !== value) {
+                break;
+            }
+            value = parent;
+        }
+        return this.bodyReadOnReceiver(value);
+    }
+    /**
+     * The zero-argument whole-body read that takes `receiver` as its receiver,
+     * `res.json()` or `res.text()`, or `undefined`. A text read is a body read
+     * like a json one (carrick#1842): without it, `return res.text()` left the
+     * walk on the response binding and published the transport object.
+     */
+    bodyReadOnReceiver(receiver) {
+        const access = receiver.getParent();
         if (!access ||
             !Node.isPropertyAccessExpression(access) ||
-            access.getExpression() !== identifier ||
-            access.getName() !== 'json') {
+            access.getExpression() !== receiver ||
+            !WHOLE_BODY_READS.has(access.getName())) {
             return undefined;
         }
         const call = access.getParent();
@@ -2609,26 +2977,31 @@ export class TypeInferrer {
         if (depth >= maxDepth) {
             return { kind: 'no-match' };
         }
-        const symbol = type.getSymbol() || type.getAliasSymbol();
-        const symbolName = symbol?.getName();
-        // 1. Check exact wrapperSymbols match. When the rule also carries
-        // originModuleGlobs, the symbol's declaration must come from a matching
-        // module — names like `Response` are shared by the DOM, frameworks, and
-        // HTTP clients, so a bare name match would unwrap unrelated types.
-        if (rule.wrapperSymbols && symbolName && rule.wrapperSymbols.includes(symbolName)) {
-            const originGated = !!(rule.originModuleGlobs && rule.originModuleGlobs.length > 0);
-            if (!originGated || this.symbolOriginatesFromModules(symbol, rule.originModuleGlobs)) {
-                const extracted = this.extractPayloadFromWrapper(type, node, rule, config, depth);
-                if (extracted) {
-                    return { kind: 'extracted', result: extracted };
-                }
-                // A name-only match is not proof of machinery: a local type that
-                // happens to share the name must keep its real structural type when
-                // nothing was extracted. Only origin-verified matches may collapse
-                // to `unknown`.
-                return originGated ? { kind: 'verified-no-payload' } : { kind: 'no-match' };
+        const readings = this.wrapperReadings(type);
+        // 1. Check exact wrapperSymbols match, against either name the type goes
+        // by (carrick#1843). When the rule also carries originModuleGlobs, the
+        // declaration of the name that matched must come from a matching module
+        // — names like `Response` are shared by the DOM, frameworks, and HTTP
+        // clients, so a bare name match would unwrap unrelated types. A name
+        // that fails that gate is no match, and the rule's test of members and
+        // origin below still has its turn: a service's alias that shares the
+        // rule's name can stand around the very type the rule verifies.
+        const named = readings.filter((reading) => rule.wrapperSymbols?.includes(reading.symbol.getName()));
+        const globs = rule.originModuleGlobs ?? [];
+        const originGated = globs.length > 0;
+        const matched = originGated
+            ? named.find((reading) => this.symbolOriginatesFromModules(reading.symbol, globs))
+            : named[0];
+        if (matched) {
+            const extracted = this.extractPayloadFromWrapper(type, matched, node, rule, config, depth);
+            if (extracted) {
+                return { kind: 'extracted', result: extracted };
             }
-            return { kind: 'no-match' };
+            // A name-only match is not proof of machinery: a local type that
+            // happens to share the name must keep its real structural type when
+            // nothing was extracted. Only origin-verified matches may collapse
+            // to `unknown`.
+            return originGated ? { kind: 'verified-no-payload' } : { kind: 'no-match' };
         }
         // 2. Check machineryIndicators + originModuleGlobs. Indicators alone are
         // too many false positives, so the origin gate is mandatory here — which
@@ -2640,10 +3013,18 @@ export class TypeInferrer {
             if (!this.typeHasMachineryIndicators(type, rule.machineryIndicators)) {
                 return { kind: 'no-match' };
             }
-            if (!this.symbolOriginatesFromModules(symbol, rule.originModuleGlobs)) {
+            // The rule named neither of the type's names, so this branch reads
+            // what it always read: the first symbol the type has, and the type's
+            // own arguments. An alias the rule did not name says nothing about
+            // where a payload is, whoever declares it (carrick#1843):
+            // `Omit<Response, 'json'>` is written through a library alias whose
+            // first argument is the transport itself, and a service's own alias
+            // around a library's object orders its parameters as it likes.
+            const symbol = type.getSymbol() || type.getAliasSymbol();
+            if (!symbol || !this.symbolOriginatesFromModules(symbol, rule.originModuleGlobs)) {
                 return { kind: 'no-match' };
             }
-            const extracted = this.extractPayloadFromWrapper(type, node, rule, config, depth);
+            const extracted = this.extractPayloadFromWrapper(type, { symbol, typeArguments: type.getTypeArguments(), viaAlias: false }, node, rule, config, depth);
             if (extracted) {
                 return { kind: 'extracted', result: extracted };
             }
@@ -2651,14 +3032,44 @@ export class TypeInferrer {
         }
         return { kind: 'no-match' };
     }
+    /**
+     * The names `type` goes by, own symbol first (carrick#1843).
+     *
+     * `type Task<A> = __Task<A>` has the class's symbol and arguments, and the
+     * alias's beside them. `type Reply<T> = { ... }` has the anonymous `__type`
+     * with no arguments of its own. `type Outcome<A, E> = Done<A, E> |
+     * Failed<A, E>` has no symbol of its own at all. In each, the alias and its
+     * arguments are what a rule naming `Task`, `Reply` or `Outcome` describes.
+     */
+    wrapperReadings(type) {
+        const readings = [];
+        const own = type.getSymbol();
+        if (own) {
+            readings.push({ symbol: own, typeArguments: type.getTypeArguments(), viaAlias: false });
+        }
+        const alias = type.getAliasSymbol();
+        if (alias && alias !== own) {
+            readings.push({
+                symbol: alias,
+                typeArguments: type.getAliasTypeArguments(),
+                viaAlias: true,
+            });
+        }
+        return readings;
+    }
     /**
      * Extract the payload type from a matched wrapper. Returns null when the
      * rule matched the wrapper but no payload is recoverable from generics or
      * property paths — the caller decides what a payload-less match means
      * (verified machinery collapses to `unknown` after every rule has run;
      * a name-only match leaves the type untouched).
+     *
+     * `payloadGenericIndex` counts the arguments of `reading`, the name the
+     * rule matched (carrick#1843): an alias is free to order its parameters
+     * differently from the type it stands for, so the same index into the
+     * other list is a different argument.
      */
-    extractPayloadFromWrapper(type, node, rule, config, depth) {
+    extractPayloadFromWrapper(type, reading, node, rule, config, depth) {
         // The outer extraction already succeeded on the paths below; a recursive
         // inner pass that finds nothing more must not demote the result back to
         // "not unwrapped" (which would discard the recovered payload). Only when
@@ -2677,7 +3088,7 @@ export class TypeInferrer {
         };
         // 1. Try generic type argument at payloadGenericIndex
         const genericIndex = rule.payloadGenericIndex ?? 0;
-        const typeArgs = type.getTypeArguments();
+        const typeArgs = reading.typeArguments;
         if (typeArgs.length > genericIndex) {
             const payloadArg = typeArgs[genericIndex];
             // Check if it's a useful type (not any/unknown/never)
@@ -2694,8 +3105,11 @@ export class TypeInferrer {
                     payloadType: payloadArg,
                 };
             }
-            // Try "first useful generic" heuristic
-            for (let i = 0; i < typeArgs.length; i++) {
+            // Try "first useful generic" heuristic. It is a guess about a type's
+            // own arguments and is not extended to an alias's (carrick#1843): the
+            // alias this reaches most often is a result carrier, `Outcome<A, E>`,
+            // whose next argument after an open payload is the error side.
+            for (let i = 0; !reading.viaAlias && i < typeArgs.length; i++) {
                 const argType = typeArgs[i];
                 const text = typeText(argType, node);
                 if (!this.isUselessType(text)) {
@@ -3749,11 +4163,19 @@ export class TypeInferrer {
     /**
      * Declaration file (absolute path) of the anchor symbol
      * `primaryTypeSymbol` reports for this type, or `undefined` when the type
-     * has no user-facing anchor or no source declaration. The scanner's
-     * pub/sub two-anchor arbitration (carrick#413) uses this to re-aim a
-     * demoted explicit bundle request: the bundler resolves a `SymbolRequest`
-     * only against declarations IN its `source_file`, so the request must
-     * point at the file that actually declares the tsc-witnessed payload type.
+     * has no user-facing anchor or no source declaration. Every path that
+     * reports the symbol reports this beside it (carrick#1819): it is where a
+     * reader finds the type an anchor names. The scanner's pub/sub two-anchor
+     * arbitration (carrick#413) also uses it to re-aim a demoted explicit
+     * bundle request: the bundler resolves a `SymbolRequest` only against
+     * declarations IN its `source_file`, so the request must point at the file
+     * that actually declares the tsc-witnessed payload type.
+     *
+     * The declarations read are those of the type's own symbol, so a name
+     * imported through a barrel reports the file that declares it, and a name
+     * two files declare reports the one this type resolves to. A declaration in
+     * an installed package or a TypeScript lib is reported as it is found, as
+     * an absolute path; what a reader is shown for it is the scanner's call.
      *
      * Only declaration kinds the bundler's `validateSymbols` can resolve
      * (interface, type alias, class, enum, function, variable) count. A
@@ -4073,44 +4495,7 @@ export class TypeInferrer {
      * which is the honest answer and the one a consumer check can act on.
      */
     findFunctionByLine(sourceFile, line) {
-        const LINE_TOLERANCE = 2;
-        const functions = [];
-        /** Statements opening inside the forward window, in source order. */
-        const windowStatements = [];
-        for (const node of sourceFile.getDescendants()) {
-            if (Node.isFunctionDeclaration(node) ||
-                Node.isArrowFunction(node) ||
-                Node.isFunctionExpression(node) ||
-                Node.isMethodDeclaration(node)) {
-                functions.push(node);
-            }
-            if (Node.isStatement(node)) {
-                const start = node.getStartLineNumber();
-                if (start >= line && start <= line + LINE_TOLERANCE) {
-                    windowStatements.push(node);
-                }
-            }
-        }
-        const separatedFromAnchor = (fn) => windowStatements.some((statement) => statement.getStartLineNumber() < fn.getStartLineNumber() &&
-            !(statement.getStart() <= fn.getStart() && statement.getEnd() >= fn.getEnd()));
-        let best;
-        let bestDelta = Infinity;
-        for (const fn of functions) {
-            const delta = Math.abs(fn.getStartLineNumber() - line);
-            if (delta > LINE_TOLERANCE)
-                continue;
-            if (fn.getStartLineNumber() > line && separatedFromAnchor(fn))
-                continue;
-            const isCloser = delta < bestDelta;
-            const isInnermostTie = delta === bestDelta &&
-                best !== undefined &&
-                fn.getEnd() - fn.getStart() < best.getEnd() - best.getStart();
-            if (isCloser || isInnermostTie) {
-                best = fn;
-                bestDelta = delta;
-            }
-        }
-        return best;
+        return functionAtLine(sourceFile, line);
     }
     /**
      * Walk up from a node to find its innermost containing function.