lambder 7.3.1 → 8.1.1

package/dist/shared/wire/LambderAnswerHeaders.d.ts

@@ -4,9 +4,9 @@
  * call wrote so it can be applied onto whichever answer the call ends up
  * with.
  *
- * One implementation, at the bottom of the stack, because every layer above
- * it needs the same one: LambderResponse's own header methods are these three
- * functions, and a second copy had already drifted from them.
+ * One implementation at the bottom of the stack, because every layer above
+ * needs the same behavior: LambderResponse's own header methods are these
+ * three functions, so a second copy cannot drift from them.
  */
 /** The header's values under a case-insensitive lookup, or undefined. */
 export declare const getAnswerHeader: (headers: Record<string, string[]>, name: string) => string[] | undefined;
@@ -25,18 +25,15 @@ export type LambderHeaderTarget = {
  * the session controller's Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
- * `add` appends to it, exactly as the two would if called on the answer
- * directly.
+ * `add` appends to it, exactly as if called on the answer directly.
  *
  * These headers belong to the CALL, not to the response that first carried
- * them: on the server an afterRender hook may answer with a different
- * response than the handler produced, and a session cookie written during the
- * call has to travel across to it. So applying never forgets the operations,
- * and applying the same ones twice is a no-op: `set` writes the same value
- * again, and `add` skips a value the header already carries. The one thing
- * that costs is two `add` calls of the identical value under one name, which
- * collapse to one; duplicate identical header values carry no meaning in
- * HTTP, so nothing observable is lost.
+ * them: an afterRender hook may answer with a different response than the
+ * handler produced, and a session cookie written during the call must travel
+ * to it. So applying never forgets the operations, and applying them twice
+ * is a no-op (`add` skips a value the header already carries). The cost is
+ * that two identical `add` values under one name collapse to one, which HTTP
+ * gives no meaning to anyway.
  */
 export declare class LambderAnswerHeaders {
     private operations;
@@ -50,9 +47,8 @@ export declare class LambderAnswerHeaders {
     get size(): number;
     /**
      * Applies the recorded operations, in order, onto anything that reads and
-     * writes headers: a LambderResponse, or a header map through applyInto.
-     * One definition of what an operation does, so the two targets cannot
-     * drift apart.
+     * writes headers: a LambderResponse, or a header map through applyInto,
+     * so both targets share one definition of what an operation does.
      */
     applyTo(target: LambderHeaderTarget, fromIndex?: number): void;
     /** The same, onto an answer's plain header map. */

package/dist/shared/wire/LambderAnswerHeaders.js

@@ -4,9 +4,9 @@
  * call wrote so it can be applied onto whichever answer the call ends up
  * with.
  *
- * One implementation, at the bottom of the stack, because every layer above
- * it needs the same one: LambderResponse's own header methods are these three
- * functions, and a second copy had already drifted from them.
+ * One implementation at the bottom of the stack, because every layer above
+ * needs the same behavior: LambderResponse's own header methods are these
+ * three functions, so a second copy cannot drift from them.
  */
 /** The header's values under a case-insensitive lookup, or undefined. */
 export const getAnswerHeader = (headers, name) => {
@@ -40,18 +40,15 @@ export const addAnswerHeader = (headers, name, value) => {
  * the session controller's Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
- * `add` appends to it, exactly as the two would if called on the answer
- * directly.
+ * `add` appends to it, exactly as if called on the answer directly.
  *
  * These headers belong to the CALL, not to the response that first carried
- * them: on the server an afterRender hook may answer with a different
- * response than the handler produced, and a session cookie written during the
- * call has to travel across to it. So applying never forgets the operations,
- * and applying the same ones twice is a no-op: `set` writes the same value
- * again, and `add` skips a value the header already carries. The one thing
- * that costs is two `add` calls of the identical value under one name, which
- * collapse to one; duplicate identical header values carry no meaning in
- * HTTP, so nothing observable is lost.
+ * them: an afterRender hook may answer with a different response than the
+ * handler produced, and a session cookie written during the call must travel
+ * to it. So applying never forgets the operations, and applying them twice
+ * is a no-op (`add` skips a value the header already carries). The cost is
+ * that two identical `add` values under one name collapse to one, which HTTP
+ * gives no meaning to anyway.
  */
 export class LambderAnswerHeaders {
     operations = [];
@@ -69,9 +66,8 @@ export class LambderAnswerHeaders {
     get size() { return this.operations.length; }
     /**
      * Applies the recorded operations, in order, onto anything that reads and
-     * writes headers: a LambderResponse, or a header map through applyInto.
-     * One definition of what an operation does, so the two targets cannot
-     * drift apart.
+     * writes headers: a LambderResponse, or a header map through applyInto,
+     * so both targets share one definition of what an operation does.
      */
     applyTo(target, fromIndex = 0) {
         for (const operation of this.operations.slice(fromIndex)) {

package/dist/shared/wire/LambderApiContract.d.ts

@@ -38,7 +38,14 @@ export type LambderApiResponseConfig = {
     sessionExpired?: boolean;
     notAuthorized?: boolean;
     message?: any;
-    /** A refusal message, or a plain string: what LambderApiRefusal and res.api(null, { errorMessage }) put here. */
+    /**
+     * A refusal message, or a plain string when writing
+     * (`res.api(null, { errorMessage: "..." })`): the envelope goes out with
+     * the message object either way. Read off the wire it can still be a
+     * string, or no message at all, wherever a Lambder server did not write
+     * the body (a hand-built mock answer, a proxy); refusalMessageOf reads
+     * whatever arrives as a message.
+     */
     errorMessage?: LambderAppRefusalMessage | string;
     logList?: any[];
     /**
@@ -57,16 +64,76 @@ export type LambderApiResponseConfig = {
  * indistinguishable from an endpoint that answered nothing on purpose.
  */
 export type LambderApiNullAnswerConfig = LambderNonEmptyOptionMap<Pick<LambderApiResponseConfig, "versionExpired" | "sessionExpired" | "notAuthorized" | "errorMessage" | "message">> & LambderApiResponseConfig;
-/** The API wire envelope both sides speak: res.api() emits it, LambderCaller parses it. */
+/**
+ * The API wire envelope both sides speak: res.api() emits it, LambderCaller
+ * parses it. `apiVersion` is always there (null when the server set none):
+ * it is how a reader tells a Lambder envelope from another JSON answer, such
+ * as API Gateway's own `{ "message": ... }` errors, so an answer without it
+ * reads as a server failure.
+ */
 export type LambderApiEnvelopeBody<T> = LambderApiResponseConfig & {
-    apiVersion?: string | null;
+    apiVersion: string | null;
     payload?: T | null;
 };
+/** A value that is already JSON, recursive structures such as z.json() included. */
+type LambderJsonValue = string | number | boolean | null | LambderJsonValue[] | {
+    [key: string]: LambderJsonValue;
+};
+/** An array item once it has been through JSON: what an object would drop, an array writes as null. */
+type LambderJsonArrayItemOf<T> = T extends undefined | symbol | ((...args: any[]) => unknown) ? null : LambderJsonOf<T>;
+/**
+ * The keys of object T that JSON may leave out: those whose value may be
+ * undefined, since JSON.stringify omits such a key. Distributed over K, the
+ * keys of T, one at a time. An index signature is never one of them: a
+ * record's undefined entries are left out, which its value type already
+ * says once undefined is dropped from it.
+ */
+type LambderJsonOmissibleKeys<T, K extends keyof T = keyof T> = K extends keyof T ? (string extends K ? never : number extends K ? never : undefined extends T[K] ? K : never) : never;
+/**
+ * The type a value has once it has been through JSON: what an API's output
+ * reaches a client as. A Date becomes its string (through toJSON), a
+ * function, a symbol or an undefined member is dropped (written as null in
+ * an array), and a bigint, which JSON.stringify refuses, is never. A key
+ * whose value may be undefined is optional, since JSON leaves it out then,
+ * and a Map or a Set, whose entries are not properties, is written as an
+ * empty object. `unknown` stays unknown, and a type that is already JSON
+ * maps to itself, which is also what lets a recursive one such as z.json()
+ * resolve.
+ *
+ * An object is mapped in two steps. The omissible keys are made optional
+ * first, through the key types alone, and the mapping over the result then
+ * keeps each key's modifiers. Deciding optionality inside the mapping, per
+ * key, would need the mapped value of every key before the object's own
+ * keys were known, which a recursive type (a tree of its own nodes) cannot
+ * give without recursing for ever.
+ */
+export type LambderJsonOf<T> = unknown extends T ? T : T extends LambderJsonValue ? T : T extends {
+    toJSON(): infer TJson;
+} ? LambderJsonOf<TJson> : T extends undefined | bigint | symbol | ((...args: any[]) => unknown) ? never : T extends readonly unknown[] ? {
+    [K in keyof T]: LambderJsonArrayItemOf<T[K]>;
+} : T extends ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> ? {} : T extends object ? (Partial<Pick<T, LambderJsonOmissibleKeys<T>>> & Omit<T, LambderJsonOmissibleKeys<T>>) extends infer TKeyed ? {
+    [K in keyof TKeyed as K extends string | number ? (string extends K ? K : number extends K ? K : [LambderJsonOf<TKeyed[K]>] extends [never] ? never : K) : never]: LambderJsonOf<TKeyed[K]>;
+} : never : never;
+/**
+ * What an API's output reaches the client as: LambderJsonOf of the schema's
+ * output, except at the top, where an envelope carries no payload at all
+ * rather than a JSON `undefined`. A void or undefined output keeps its type,
+ * so a handler and a mock handler answer nothing, and an output that may be
+ * undefined keeps that member, which LambderJsonOf drops as it would a
+ * member of an object.
+ */
+export type LambderJsonOutputOf<T> = [T] extends [void] ? T : (undefined extends T ? undefined : never) | LambderJsonOf<T>;
 /**
  * One contract entry as addApi/addSessionApi record it: the payload types,
  * the mode, and every declarative option exactly as written. Options that
  * were not written are absent rather than undefined, so `keyof` an entry
  * lists only what the endpoint declared.
+ *
+ * `In` is what a client sends (the input schema's z.input: a field with a
+ * default is optional, a transform's source type is what is posted) and `Out`
+ * what it receives (the output schema's z.output as JSON, see
+ * LambderJsonOf). The handler's own types are the other side of each, and
+ * are not recorded here.
  */
 export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInputs = never, Guards = never, RateLimit = never, Idempotency = never> = {
     input: In;
@@ -81,59 +148,19 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 }) & ([Idempotency] extends [never] ? {} : {
     idempotency: Idempotency;
 });
-/** Helper type for merging a new entry into the contract during chaining. */
-export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
-    [K in Name]: Entry;
-};
 /**
- * The contract as one object type, for the `export interface` a consuming
- * app declares its contract through:
+ * Merges a new entry into the contract during chaining.
  *
- * ```ts
- * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
- * ```
- *
- * Chaining leaves the contract an intersection one member deep per endpoint
- * (LambderMergeContract above), and every `C[K]` written against a type
- * parameter then resolves the property across all of them. That lookup is
- * the atom the reading helpers below are built from, so its cost is paid
- * again by each of them, per endpoint, in every app that registers a mock,
- * declares a needs map, or otherwise reads the contract generically: in a
- * 182-endpoint app one indexed access measured ~3,000 type instantiations
- * and one mock registration ~18,000.
- *
- * Extending an interface is what collapses it. An interface's members are
- * declared, so they are resolved once for the whole declaration rather than
- * per lookup, and the same access measured ~6 instantiations after the
- * change: a 182-endpoint app's frontend type check went from 27.8M
- * instantiations to 7.0M and from 20.2s to 10.6s of check time. The alias
- * form (`type C = LambderFlattenContract<...>`) does NOT do this: a mapped
- * type stays deferred and each lookup pays the full cost again, so the
- * `interface ... extends` spelling is the point.
- *
- * Diagnostics are the same ones, and they read better: a message naming the
- * contract prints the interface by name, where the intersection is printed
- * as a truncated spill of entries.
- *
- * Every endpoint name must be a string literal for an interface to extend
- * the result, which registration through addApi/addSessionApi guarantees.
- *
- * Two things quietly undo it, both of which look like tidying:
- *
- * - `@typescript-eslint/no-empty-object-type` reports the empty body as
- *   "equivalent to its supertype" and its fix is a type alias, which is the
- *   one spelling that does not collapse anything. Disable the rule on the
- *   line rather than taking the fix.
- * - Extending anything but a mapped type loses the inferable index signature.
- *   An interface has none of its own, so a hand-written `interface C { ... }`
- *   is not assignable to LambderApiContractShape and is rejected by
- *   initLambderMock<C>, LambderCaller<C> and LambderInvokeCaller<C>;
- *   extending this mapped type is what keeps it. api-contract.test.ts pins
- *   that, along with the flattened contract being the same type member for
- *   member.
+ * The contract is therefore an intersection one member deep per endpoint, and
+ * every `C[K]` read generically (a typed caller, a mock registry, a test
+ * visitor) resolves the property across all of them. That costs nothing
+ * worth measuring in a small app and most of a large client's type check,
+ * which is what writeApiContract (lambder/build) is for: it writes the
+ * contract out as one object type with plain members, for clients to import
+ * instead of the server.
  */
-export type LambderFlattenContract<C> = {
-    [K in keyof C]: C[K];
+export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
+    [K in Name]: Entry;
 };
 /** Guard names referenced by a guards option, whichever of its three forms is used. */
 export type LambderGuardNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
@@ -149,6 +176,23 @@ export type LambderContractKeysWithMode<C, M extends LambderApiMode> = {
 export type LambderContractGuardsOf<C, K extends keyof C> = C[K] extends {
     guards: infer G;
 } ? G : never;
+/**
+ * The endpoint names whose guards option names guard N, in any of its three
+ * forms and whatever else it declares beside it. What a test that calls
+ * every endpoint behind one guard loops over, and what a list meant to hold
+ * exactly those endpoints is checked against. `satisfies` refuses a name the
+ * guard does not cover; a missing name needs a check of its own:
+ *
+ * ```ts
+ * type AdminApi = LambderContractKeysWithGuard<Contract, "platformAdmin">;
+ * const ADMIN_APIS = ["admin.listUsers", "admin.deleteUser"] as const satisfies readonly AdminApi[];
+ * // Fails to compile while an endpoint behind the guard is left off the list.
+ * const adminApisComplete: [Exclude<AdminApi, (typeof ADMIN_APIS)[number]>] extends [never] ? true : false = true;
+ * ```
+ */
+export type LambderContractKeysWithGuard<C, N extends string> = {
+    [K in keyof C]: N extends LambderGuardNamesIn<LambderContractGuardsOf<C, K>> ? K : never;
+}[keyof C] & string;
 /** Every guard name any endpoint of the contract declares, or only the endpoints of mode M. */
 export type LambderContractGuardNames<C, M extends LambderApiMode = LambderApiMode> = {
     [K in LambderContractKeysWithMode<C, M>]: LambderGuardNamesIn<LambderContractGuardsOf<C, K>>;
@@ -181,3 +225,4 @@ export type LambderContractRateLimitNames<C, M extends LambderApiMode = LambderA
 export type LambderContractIdempotencyOf<C, K extends keyof C> = C[K] extends {
     idempotency: infer I;
 } ? I : never;
+export {};

package/dist/shared/wire/LambderApiOutcome.d.ts

@@ -5,14 +5,13 @@
  * over a direct Lambda invoke) receive the same envelope and must read it
  * the same way: which status is a crash, which is a rejected input, in what
  * order the envelope flags are honoured, what a non-envelope body means.
- * Both hand their answer to resolveApiOutcome and act on the result; the
- * side effects each has (handlers, cookie clearing, error reporting) stay
- * with the caller that owns them. Pure and dependency-free, so the browser
- * entry resolves it.
+ * Both hand their answer to resolveApiOutcome and act on the result; their
+ * side effects (handlers, cookie clearing, error reporting) stay with them.
+ * Pure and dependency-free, so the browser entry can include it.
  */
 import type { z } from "zod";
 import type { LambderApiEnvelopeBody } from "./LambderApiContract.js";
-import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import { type LambderAppRefusalMessage } from "./LambderApiRefusal.js";
 /**
  * The 422 body's `zodError` as it survives JSON: a ZodError's name and
  * message, and its issues spelled out. Not a ZodError instance (it has no
@@ -37,18 +36,17 @@ type LambderApiFailureFields = {
     ok: false;
     /** HTTP status, when a response was received. */
     status?: number;
-    /** Envelope errorMessage, when the server provided one. */
-    errorMessage?: LambderAppRefusalMessage | string;
-    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
+    /** Envelope errorMessage, when the server provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
+    errorMessage?: LambderAppRefusalMessage;
+    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it, and so may a 503). */
     retryAfterSeconds?: number;
     /**
      * The answer's logList, when it carried one: the envelope's on a success
      * or an envelope refusal, the parsed 500 body's on a server failure, and
-     * the validation body's on a 422 (the server writes it there too). It is
-     * on every arm so that a caller surfaces logs in ONE place, right after
-     * reading the answer, instead of once per outcome it happens to handle:
-     * the browser caller surfaced them after its early returns and so never
-     * printed the logs of the answer whose logs matter most, a 500.
+     * the validation body's on a 422. It is on every arm so a caller surfaces
+     * logs in ONE place, right after reading the answer, rather than per
+     * outcome, where early returns would skip the logs that matter most: a
+     * 500's.
      */
     logList?: unknown[];
 };
@@ -69,30 +67,32 @@ export type LambderApiValidationFailure = LambderApiFailureFields & {
     reason: 'validation';
     zodError: LambderValidationError;
 };
-/** The server answered, and the envelope itself says the call is refused. Always carries that envelope. */
+/** The server answered, and the envelope itself says the call is refused. Always carries that envelope, and an `errorMessage` refusal always carries its message. */
 export type LambderApiEnvelopeFailure<T> = LambderApiFailureFields & {
-    reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage';
     response: LambderApiEnvelopeBody<T>;
-};
+} & ({
+    reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized';
+} | {
+    reason: 'errorMessage';
+    errorMessage: LambderAppRefusalMessage;
+});
 /**
  * Discriminated result of an API call: `ok: true` carries the payload, every
  * failure carries a machine-readable reason, so "the server returned null"
  * and "the request failed" are never conflated.
  *
- * The failure side is discriminated by `reason` rather than being one arm of
- * optional fields, so narrowing to a reason narrows to what that reason
- * actually carries: `zodError` after `reason === 'validation'`, `response`
- * after an envelope reason, `error` after the rest. Read as one wide arm, the
- * framework's own reader needed three non-null assertions to say what the
- * union already knew.
+ * The failure side is discriminated by `reason`, so narrowing to a reason
+ * narrows to what it carries: `zodError` after `reason === 'validation'`,
+ * `response` after an envelope reason, `error` after the rest, with no
+ * non-null assertion needed.
  */
 export type LambderApiOutcome<T> = LambderApiSuccessOutcome<T> | LambderApiCallFailure<T> | LambderApiValidationFailure | LambderApiEnvelopeFailure<T>;
 /**
- * What reading one HTTP answer can produce. Narrower than LambderApiOutcome
- * by the three reasons no answer can carry: `network` and `timeout` belong to
- * the caller's own abort, and `unknown` to something throwing around the
- * call. So a caller that has handled `server` and `validation` holds a
- * success or an envelope refusal, both of which carry the envelope.
+ * What reading one HTTP answer can produce: LambderApiOutcome minus the
+ * three reasons no answer carries (`network` and `timeout` are the caller's
+ * own abort, `unknown` is something throwing around the call). A caller that
+ * has handled `server` and `validation` holds a success or an envelope
+ * refusal, both of which carry the envelope.
  */
 export type LambderApiAnswerOutcome<T> = LambderApiSuccessOutcome<T> | (LambderApiCallFailure<T> & {
     reason: 'server';
@@ -100,10 +100,9 @@ export type LambderApiAnswerOutcome<T> = LambderApiSuccessOutcome<T> | (LambderA
 /**
  * What the mapping needs from an HTTP answer, whichever transport produced it.
  *
- * Exactly one of `json()` and `text()` is read per answer, never both: a
- * transport backed by a real Response body may only be read once, and the
- * mapping is written to that rule (a 5xx reads text and parses it itself, so
- * that a non-envelope body is still reportable).
+ * Exactly one of `json()` and `text()` is read per answer, since a real
+ * Response body may only be read once (a 5xx reads text and parses it
+ * itself, so a non-envelope body is still reportable).
  */
 export type LambderApiHttpAnswer = {
     status: number;
@@ -116,6 +115,17 @@ export type LambderApiHttpAnswer = {
     text: () => Promise<string>;
     /** The answer's Set-Cookie header values, for a transport that can see them (a cookie jar consumes them); absent in a browser. */
     setCookies?: string[];
+    /**
+     * The CSRF tokens of a transport that keeps the session's cookies itself
+     * (a cookie jar), where document.cookie is not where they live: the one
+     * it posted, and a read of the one it holds now. LambderCaller judges
+     * whether a sessionExpired is about the session the page still holds by
+     * these; absent, it compares document.cookie before and after the call.
+     */
+    csrfTokens?: {
+        posted: string;
+        held: () => string;
+    };
 };
 /**
  * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
@@ -123,6 +133,8 @@ export type LambderApiHttpAnswer = {
  * errorMessage, and a global error handler may add crash and logList); a
  * 422 is a validation failure only with Lambder's validation body; anything
  * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ * A failure read off any answer but a 422 carries the answer's Retry-After
+ * as retryAfterSeconds.
  */
 export declare const resolveApiOutcome: <T>(answer: LambderApiHttpAnswer) => Promise<LambderApiAnswerOutcome<T>>;
 export {};

package/dist/shared/wire/LambderApiOutcome.js

@@ -5,47 +5,65 @@
  * over a direct Lambda invoke) receive the same envelope and must read it
  * the same way: which status is a crash, which is a rejected input, in what
  * order the envelope flags are honoured, what a non-envelope body means.
- * Both hand their answer to resolveApiOutcome and act on the result; the
- * side effects each has (handlers, cookie clearing, error reporting) stay
- * with the caller that owns them. Pure and dependency-free, so the browser
- * entry resolves it.
+ * Both hand their answer to resolveApiOutcome and act on the result; their
+ * side effects (handlers, cookie clearing, error reporting) stay with them.
+ * Pure and dependency-free, so the browser entry can include it.
  */
+import { refusalMessageOf } from "./LambderApiRefusal.js";
+/**
+ * Whether a parsed body is Lambder's envelope, which always carries
+ * apiVersion (null when the server set none). An object without it is
+ * somebody else's answer: API Gateway's own errors ({"message": ...} on a
+ * 413, a throttle, a WAF or missing-route 403, an authorizer 401, a 502 from
+ * a crashed function), a proxy's, a load balancer's.
+ */
+const isApiEnvelope = (value) => value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "apiVersion");
 /**
  * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
  * the envelope when the server sent one (Lambder's own 500 body carries
  * errorMessage, and a global error handler may add crash and logList); a
  * 422 is a validation failure only with Lambder's validation body; anything
  * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ * A failure read off any answer but a 422 carries the answer's Retry-After
+ * as retryAfterSeconds.
  */
 export const resolveApiOutcome = async (answer) => {
     const status = answer.status;
+    const errorMessageOf = (envelope) => envelope?.errorMessage !== undefined ? { errorMessage: refusalMessageOf(envelope.errorMessage) } : {};
+    // Retry-After (delta-seconds) rides every refusal that knows its reset
+    // time, e.g. a rate limit, and a 503 that says when to come back; absent
+    // or unreadable is undefined.
+    const retryAfterValue = Number(answer.header("retry-after") ?? NaN);
+    const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
     if (status >= 500) {
         // Lambder's own 500 fallback is a JSON envelope, but custom error
-        // handlers may answer text/HTML: parse defensively.
+        // handlers may answer text or HTML, and a gateway in front answers
+        // JSON of its own: parse defensively, and keep only the envelope, so
+        // a foreign body's fields never read as the app's message or crash.
         let envelope;
         try {
             const bodyText = await answer.text();
             try {
                 const parsed = JSON.parse(bodyText);
-                if (parsed !== null && typeof parsed === "object")
+                if (isApiEnvelope(parsed))
                     envelope = parsed;
             }
-            catch { /* not an envelope */ }
+            catch { /* not JSON */ }
         }
         catch { /* body unavailable */ }
         return {
             ok: false, reason: 'server', status,
-            errorMessage: envelope?.errorMessage,
+            ...errorMessageOf(envelope),
             logList: envelope?.logList,
             ...(envelope ? { response: envelope } : {}),
             error: new Error("Request failed: " + status + " - " + (answer.statusText ?? "")),
+            ...retryAfter,
         };
     }
     if (status === 422) {
         // A 422 without Lambder's validation body (e.g. a proxy's error page)
-        // is a server failure, not a validation result.
-        // The validation body carries the call's logList as every other
-        // answer does, so it is read here rather than left on the wire.
+        // is a server failure, not a validation result. The validation body
+        // carries the call's logList like every other answer, so it is read.
         let body;
         try {
             body = await answer.json();
@@ -57,10 +75,6 @@ export const resolveApiOutcome = async (answer) => {
         }
         return { ok: false, reason: 'validation', status, zodError, logList: body?.logList };
     }
-    // Retry-After (delta-seconds) rides every refusal that knows its reset
-    // time, e.g. a rate limit; absent or unreadable is undefined.
-    const retryAfterValue = Number(answer.header("retry-after") ?? NaN);
-    const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
     let data;
     try {
         data = await answer.json();
@@ -69,18 +83,29 @@ export const resolveApiOutcome = async (answer) => {
     }
     catch (err) {
         // A non-envelope body (e.g. an HTML error page) is a server failure.
-        return { ok: false, reason: 'server', status, error: new Error("Request failed: response is not a valid API envelope (status " + status + ")", { cause: err }) };
+        return { ok: false, reason: 'server', status, error: new Error("Request failed: response is not a valid API envelope (status " + status + ")", { cause: err }), ...retryAfter };
+    }
+    // Read as envelopes, a gateway's own JSON errors would resolve as
+    // successes with no payload, so a refused save would look saved.
+    if (!isApiEnvelope(data)) {
+        const gatewayMessage = typeof data.message === "string" ? `: ${data.message}` : "";
+        return { ok: false, reason: 'server', status, error: new Error(`Request failed: ${status} - the answer is not a Lambder envelope${gatewayMessage}`), ...retryAfter };
     }
     if (data.versionExpired)
-        return { ok: false, reason: 'versionExpired', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'versionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
     if (data.sessionExpired)
-        return { ok: false, reason: 'sessionExpired', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'sessionExpired', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
     if (data.notAuthorized)
-        return { ok: false, reason: 'notAuthorized', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
-    // Presence, not truthiness: the writer keeps an errorMessage an app spelled
-    // out as the empty string, so a refusal that says nothing is still a
-    // refusal. Tested for truth here, it shipped back as a success.
+        return { ok: false, reason: 'notAuthorized', status, ...errorMessageOf(data), response: data, logList: data.logList, ...retryAfter };
+    // Presence, not truthiness: the writer keeps an errorMessage an app set
+    // to the empty string, and a refusal that says nothing is still a
+    // refusal, not a success.
     if (data.errorMessage !== undefined)
-        return { ok: false, reason: 'errorMessage', status, errorMessage: data.errorMessage, response: data, logList: data.logList, ...retryAfter };
+        return { ok: false, reason: 'errorMessage', status, errorMessage: refusalMessageOf(data.errorMessage), response: data, logList: data.logList, ...retryAfter };
+    // An envelope that says nothing is wrong is still not a success when the
+    // status says otherwise.
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: 'server', status, response: data, logList: data.logList, error: new Error(`Request failed: ${status} - ${answer.statusText ?? ""}`), ...retryAfter };
+    }
     return { ok: true, payload: data.payload, response: data, logList: data.logList };
 };