lambder 7.2.5 → 8.0.2

package/dist/shared/util/LambderTypeUtilities.js

@@ -1,8 +1,8 @@
 /**
  * The small type utilities more than one module needs.
  *
- * Nothing here is Lambder's own vocabulary: these are the shapes TypeScript
- * does not ship, written once because the alternative is the same three
- * lines in every module that wants them, drifting in name and in meaning.
+ * Nothing here is Lambder's own vocabulary: these are shapes TypeScript does
+ * not ship, written once so they cannot drift in name or meaning across the
+ * modules that use them.
  */
 export {};

package/dist/shared/util/boundKeyField.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounding the caller-supplied field of a tracker or scope key.
+ *
+ * The rate-limit engine and the idempotency engine each build a store key
+ * around a field only the caller controls: a custom rate-limit key or a
+ * session key, a callerIdentity or a session key. A store has a key limit of
+ * its own (a DynamoDB partition key stops at 2048 bytes) and refuses a key
+ * past it by throwing, and both engines fail open on a store throw by
+ * default: a long enough field (a 3,000-character email, a device token)
+ * would turn the rate limit or the idempotency off for that caller, in
+ * silence, while the table held the field in plain text. So the field is
+ * bounded before any store sees it, in one implementation the two engines
+ * share, so they cannot drift apart.
+ */
+/**
+ * The field bounded: `<kind>:<value>` while the value fits, `<kind>:h:<sha256
+ * hex>` once it does not. The digest keeps distinct callers on distinct
+ * counters and scopes, and a value that fits stays readable in the table.
+ */
+export declare const boundKeyField: (kind: string, value: string) => Promise<string>;

package/dist/shared/util/boundKeyField.js

@@ -0,0 +1,34 @@
+/**
+ * Bounding the caller-supplied field of a tracker or scope key.
+ *
+ * The rate-limit engine and the idempotency engine each build a store key
+ * around a field only the caller controls: a custom rate-limit key or a
+ * session key, a callerIdentity or a session key. A store has a key limit of
+ * its own (a DynamoDB partition key stops at 2048 bytes) and refuses a key
+ * past it by throwing, and both engines fail open on a store throw by
+ * default: a long enough field (a 3,000-character email, a device token)
+ * would turn the rate limit or the idempotency off for that caller, in
+ * silence, while the table held the field in plain text. So the field is
+ * bounded before any store sees it, in one implementation the two engines
+ * share, so they cannot drift apart.
+ */
+import { joinKeyFields } from "./joinKeyFields.js";
+import { sha256HexOf } from "./LambderTextDigest.js";
+/**
+ * The ceiling, in UTF-8 bytes, on the field as it is written into the key;
+ * past it, the field is replaced by its digest. Measured escaped, since
+ * joinKeyFields doubles every separator and escape character: a field of
+ * 1,000 separators is 2,000 bytes in the key. 1024 sits well inside every
+ * store's key limit, with the store's prefix and the engine's other fields
+ * (API and policy names, a posted idempotency key of at most 200 characters)
+ * joined around it.
+ */
+const MAX_KEY_FIELD_BYTES = 1024;
+/**
+ * The field bounded: `<kind>:<value>` while the value fits, `<kind>:h:<sha256
+ * hex>` once it does not. The digest keeps distinct callers on distinct
+ * counters and scopes, and a value that fits stays readable in the table.
+ */
+export const boundKeyField = async (kind, value) => new TextEncoder().encode(joinKeyFields(value)).length > MAX_KEY_FIELD_BYTES
+    ? `${kind}:h:${await sha256HexOf(value)}`
+    : `${kind}:${value}`;

package/dist/shared/util/canonicalJson.d.ts

@@ -0,0 +1,11 @@
+/**
+ * JSON with object keys sorted at every level, so two values that are the
+ * same data hash the same whatever order their keys were built in. Arrays
+ * keep their order: a tuple's positions and an enum's values are part of the
+ * data. Undefined entries are dropped, as JSON.stringify would drop them.
+ *
+ * What the API signature digests a schema's description with, and what the
+ * idempotency engine fingerprints a request with: two hashes that must not
+ * depend on the order a client or a builder happened to write keys in.
+ */
+export declare const canonicalJson: (value: unknown) => string;

package/dist/shared/util/canonicalJson.js

@@ -0,0 +1,28 @@
+/**
+ * JSON with object keys sorted at every level, so two values that are the
+ * same data hash the same whatever order their keys were built in. Arrays
+ * keep their order: a tuple's positions and an enum's values are part of the
+ * data. Undefined entries are dropped, as JSON.stringify would drop them.
+ *
+ * What the API signature digests a schema's description with, and what the
+ * idempotency engine fingerprints a request with: two hashes that must not
+ * depend on the order a client or a builder happened to write keys in.
+ */
+export const canonicalJson = (value) => JSON.stringify(sortKeys(value));
+const sortKeys = (value) => {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    // No prototype, so a "__proto__" key (JSON.parse makes it an own key) is
+    // kept as data. On a plain object the assignment would set the prototype
+    // instead, and two payloads differing only under "__proto__" would share
+    // one fingerprint.
+    const sorted = Object.create(null);
+    for (const key of Object.keys(source).sort()) {
+        if (source[key] !== undefined)
+            sorted[key] = sortKeys(source[key]);
+    }
+    return sorted;
+};

package/dist/shared/util/joinKeyFields.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * The rate limiter and the idempotency engine each join fields with a
+ * separator, and at least one field is caller data (a policy's rate-limit
+ * key, a posted idempotency key). A plain join lets two field lists produce
+ * one string, so two callers would share a counter or one would read
+ * another's stored answer. The caller's separator is escaped, not refused: a
+ * limit that rejects a legal key is a bug of its own.
+ *
+ * The join is one-way (a key is looked up or compared, never taken apart),
+ * unlike LambderDdbCache's reversible sort-key escape, which listSortKeys
+ * must decode to exactly what was written; neither stands in for the other.
+ * Both engines share this one implementation so they cannot drift apart.
+ */
+/**
+ * The fields joined into one key, each escaped, so no two distinct field
+ * lists can produce the same string.
+ */
+export declare const joinKeyFields: (...fields: string[]) => string;

package/dist/shared/util/joinKeyFields.js

@@ -0,0 +1,22 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * The rate limiter and the idempotency engine each join fields with a
+ * separator, and at least one field is caller data (a policy's rate-limit
+ * key, a posted idempotency key). A plain join lets two field lists produce
+ * one string, so two callers would share a counter or one would read
+ * another's stored answer. The caller's separator is escaped, not refused: a
+ * limit that rejects a legal key is a bug of its own.
+ *
+ * The join is one-way (a key is looked up or compared, never taken apart),
+ * unlike LambderDdbCache's reversible sort-key escape, which listSortKeys
+ * must decode to exactly what was written; neither stands in for the other.
+ * Both engines share this one implementation so they cannot drift apart.
+ */
+/** One field, with the separator and its own escape character escaped. */
+const escapeKeyField = (value) => value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+/**
+ * The fields joined into one key, each escaped, so no two distinct field
+ * lists can produce the same string.
+ */
+export const joinKeyFields = (...fields) => fields.map(escapeKeyField).join("|");

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;
@@ -94,43 +161,33 @@ export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
  * ```
  *
  * 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.
+ * (LambderMergeContract above), and every `C[K]` against a type parameter
+ * resolves the property across all of them. The reading helpers below are
+ * built on that lookup, so each pays it again per endpoint: in a 182-endpoint
+ * app one indexed access costs ~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.
+ * An interface's members are declared, so they resolve once for the whole
+ * declaration: the same access costs ~6 instantiations instead, roughly
+ * halving such an app's frontend type check time. The alias form
+ * (`type C = LambderFlattenContract<...>`) does NOT do this: a mapped type
+ * stays deferred and each lookup pays in full, so the `interface ... extends`
+ * spelling is the point. Diagnostics also print the interface by name rather
+ * than 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:
+ * Two things that look like tidying undo it:
  *
  * - `@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.
+ *   "equivalent to its supertype" and its fix is a type alias, the one
+ *   spelling that collapses nothing. Disable the rule on the line instead.
  * - 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.
+ *   A hand-written `interface C { ... }` has none, so it is not assignable to
+ *   LambderApiContractShape, and initLambderMock<C>, LambderCaller<C> and
+ *   LambderInvokeCaller<C> reject it. api-contract.test.ts pins this, and
+ *   that the flattened contract is the same type member for member.
  */
 export type LambderFlattenContract<C> = {
     [K in keyof C]: C[K];
@@ -149,6 +206,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 +255,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 {};