lambder 7.3.1 → 8.1.1

package/README.md

@@ -34,7 +34,7 @@ and typed results with no hand-written client:
 import { LambderCaller } from "lambder/client";
 import type { ApiContractType } from "./backend/handler";
 
-const caller = new LambderCaller<ApiContractType>({ apiPath: "/api", isCorsEnabled: false });
+const caller = new LambderCaller<ApiContractType>({ apiPath: "/api" });
 const company = await caller.api("getCompany", { slug: "acme" });
 ```
 
@@ -67,6 +67,10 @@ const company = await caller.api("getCompany", { slug: "acme" });
 - **Frontend hosting.** Serve a build from a folder, S3, R2 or any HTTP
   origin, with an app shell rendered through a build-pipeline-safe template
   engine.
+- **Direct uploads.** Files go from the browser straight to S3 on tickets
+  that pin their size, type and SHA-256, with a browser runner that hashes,
+  retries and reports progress, and a memory bucket that holds tests and the
+  mock to the same rules.
 - **Runs anywhere Lambda does.** API Gateway REST APIs (payload v1), HTTP APIs
   (payload v2) and Lambda Function URLs; the payload format is detected per
   event.
@@ -85,7 +89,7 @@ whatever the code you actually import needs:
 | What you import | What to install alongside |
 | --- | --- |
 | `lambder/client` (browser, shared isomorphic code) | `zod`. `LambderCookieJar` pulls in `tough-cookie` and its public suffix list, so a bundle that never imports the jar never carries either |
-| `lambder` on AWS Lambda (any current Node.js runtime; the package needs Node 20 or later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package |
+| `lambder` on AWS Lambda (any current Node.js runtime; the package needs Node 20 or later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package, as long as the runtime's `@aws-sdk/client-dynamodb` is new enough for `LambderDdbRateLimiter` (3.868.0, see below) |
 | `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, plus `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` when sessions or the DynamoDB stores are used; both are loaded on the first table access, so an app that uses neither needs neither |
 | `LambderS3FileSource` | `@aws-sdk/client-s3`, loaded on first read |
 | `LambderInvokeCaller` | `@aws-sdk/client-lambda`, loaded on the first call |
@@ -95,11 +99,16 @@ The SDK and its `@smithy` tree are roughly 21MB installed, which is why they are
 peers rather than dependencies: a frontend importing only `lambder/client` has
 no use for any of it, and a Lambda deployment package should not ship a second
 copy of what the runtime already loads. The runtime pins its own SDK version,
-so if you need a specific one, install it and bundle it yourself.
+so if you need a specific one, install it and bundle it yourself. One version
+matters to Lambder: `LambderDdbRateLimiter` needs `@aws-sdk/client-dynamodb`
+3.868.0 or later, the first whose throttling errors name their reasons. Under
+an older client it never recognizes a key-range throttle, so a flood on one
+key goes to `failOpen` instead of being refused. Check the version your
+runtime bundles before relying on it, or bundle the client yourself.
 
 ## Package entry points
 
-The package ships four entry points; pick by where the code runs:
+The package ships five entry points; pick by where the code runs:
 
 | Entry | Runs in | Carries |
 | --- | --- | --- |
@@ -107,6 +116,7 @@ The package ships four entry points; pick by where the code runs:
 | `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
 | `lambder/mock` | Browser and Node, in development and tests | `LambderMockApp`, the mock runtime: your typed contract served from mock handlers over the real API pipeline and memory stores |
 | `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiContract`: the contract as plain types a client compiles instead of the server |
 
 Frontends and shared isomorphic packages should import from `lambder/client`
 only; the entry's module graph contains no AWS SDK, Node built-ins, or server
@@ -117,12 +127,15 @@ Source layout mirrors this: `src/api/` (the isomorphic API core: request,
 answer, envelope, pipeline, and the declarative policies the pipeline runs),
 `src/core/` (the Lambda server adapter: routes, files, hooks, finalization),
 `src/session/` (the session manager, controller and crypto), `src/stores/`
-(every store implementation, DynamoDB and in-memory alike), `src/client/`,
+(every store and file-source implementation, DynamoDB and in-memory alike,
+and the helpers the two caches share), `src/client/`,
 `src/invoke/` (the lambda-to-lambda caller and the in-process handler
-transport), `src/mock/` (the mock runtime), and `src/shared/` (isomorphic
-modules every entry re-exports, grouped into `wire/` for the format both
-sides speak, `contracts/` for the four store interfaces, `transport/` for the
-caller-to-server seam, and `util/` for helpers).
+transport), `src/mock/` (the mock runtime), `src/testing/` (the test app),
+`src/build/` (what a generator script runs at build time), and `src/shared/`
+(isomorphic modules every entry re-exports, grouped into `wire/` for the
+format both sides speak, `contracts/` for the five store and source
+interfaces, `transport/` for the caller-to-server seam, and `util/` for
+helpers).
 Directories are layers and imports only ever point down;
 [docs/api-core.md](./docs/api-core.md#layering) states the order and the test
 that enforces it.
@@ -137,8 +150,8 @@ guide that matches what you are building. The full index lives in
 | --- | --- |
 | [Getting started](./docs/getting-started.md) | The three-step path from a first API to a typed frontend call |
 | [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
-| [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, and non-HTTP invocations |
-| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal` |
+| [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, crash reporting, and non-HTTP invocations |
+| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
 | [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
 | [Sessions](./docs/sessions.md) | Sessions over a store, cookie scope, secrets at rest, `dataRefresh`, the controller API |
 | [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |
@@ -147,11 +160,12 @@ guide that matches what you are building. The full index lives in
 | [The API core](./docs/api-core.md) | `LambderApiPipeline`: the one pipeline the server and the mock runtime run, the store interfaces, the transports |
 | [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression, transports |
 | [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
+| [Direct uploads](./docs/uploads.md) | Files the browser posts straight to S3 with tickets the server signs, verified before they count |
 | [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
 | [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, on-demand languages, runtime dictionaries |
 | [The mock runtime](./docs/mock.md) | `LambderMockApp`: the typed contract served from mock handlers over the real pipeline, in the browser and in tests |
 | [DynamoDB tables](./docs/dynamodb-tables.md) | Table shapes, TTL and IAM for sessions, cache, rate limits and idempotency |
-| [Exports reference](./docs/exports.md) | Every name the four entry points export, grouped by purpose |
+| [Exports reference](./docs/exports.md) | Every name the five entry points export, grouped by purpose |
 
 ## Standalone modules
 
@@ -162,7 +176,7 @@ framework:
 | --- | --- | --- |
 | `html` / `xml` tags + `LambderTemplatingEngine` | [Templating](./docs/templating.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
 | `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension, auto language detection and on-demand language loading (isomorphic) |
-| `LambderDdbCache` | [DynamoDB cache](./docs/ddb-cache.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill and grouped keys (server-only) |
+| `LambderDdbCache` / `LambderMemoryCache` | [DynamoDB cache](./docs/ddb-cache.md) | JSON cache behind one `LambderCache` interface: DynamoDB-backed and compressed, with lease-based single-fill and grouped keys (server-only), or in memory for tests |
 | `LambderDdbRateLimiter` / `LambderMemoryRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | Fixed-window rate limiter, atomic per window, in DynamoDB (server-only) or in memory |
 | `LambderDdbIdempotencyStore` / `LambderMemoryIdempotencyStore` | [Idempotency store](./docs/ddb-idempotency.md) | Idempotency records with owner-checked claims, in DynamoDB (compressed replays, server-only) or in memory |
 | `LambderMockApp` | [The mock runtime](./docs/mock.md) | The typed contract served from mock handlers over the real API pipeline, with failure injection, sessions and a call log (isomorphic) |
@@ -170,14 +184,25 @@ framework:
 ## Versioning and changes
 
 Released versions and what each one changed are in
-[CHANGELOG.md](./CHANGELOG.md). The current major is v7, which moved the API
-pipeline into an isomorphic core, put the session layer behind a store
-interface, dropped the resolver argument from guards, and replaced the MSW
-adapter with a mock runtime. Every break and what to do about it is in the
-7.0.0 entry. The compiler finds most of them. Three it cannot are named there:
-leftover `session` fields that `const` generics stop it from seeing, a
-`region` that went from required to optional, and mock handlers that now take
-the call context rather than the payload.
+[CHANGELOG.md](./CHANGELOG.md). The current major is v8, which came out of a
+review of 7.3.1: session writes that cannot undo a logout, API calls that must
+be JSON, output schemas applied at runtime, rate limits that count IPv6 callers
+by their /64 and custom keys after the guards, idempotency keys bound to the
+request they were first sent with, and the same behavior on every gateway and
+in the mock. Every break and what to do about it is in the 8.0.2 entry. The
+compiler finds most of them. Fourteen it cannot are named there: hand-built
+calls without a JSON Content-Type, hand-built answers without `apiVersion`,
+handlers whose payload does not match their output schema, code that decoded
+`ctx.path` itself, string routes that match case-sensitively, compression
+behind a REST API, two more IAM actions (`UpdateItem` on the session table,
+`GetItem` on the rate-limit table), custom-key limits charged after the
+guards, idempotency keys bound to the request they were first sent with,
+`errorMessage` always being an object, `credentials: true` needing named
+origins, template slots and `html` interpolations refused or checked in
+more attribute positions, `refreshSessionData()` throwing where it answered
+null, and `z.ZodType<T>` annotations leaving a field unchecked. Every live
+session is signed out once by the
+upgrade. An app still on v6 goes through the 7.0.0 entry first.
 
 ## Contributing
 

package/dist/api/LambderApiAnswer.d.ts

@@ -1,40 +1,36 @@
 import type { LambderApiHttpAnswer } from "../shared/wire/LambderApiOutcome.js";
 /**
- * The core's output for one API call: what goes back over the wire before
- * any transport-level finalization. The server adapter turns it into a
- * Lambda response (compression, ETag, base64); the mock transport hands it
- * to the caller as it is. It is also the shape the idempotency store
- * persists and replays, which is why it is plain data.
+ * The core's output for one API call, before any transport-level
+ * finalization. The server adapter turns it into a Lambda response
+ * (compression, ETag, base64); the mock transport hands it to the caller as
+ * it is. The idempotency store persists and replays this shape, which is why
+ * it is plain data.
  *
- * Header names keep the casing they were written with; lookups are
- * case-insensitive (see getAnswerHeader), the way LambderResponse treats
- * them.
+ * Header names keep their written casing; lookups are case-insensitive (see
+ * getAnswerHeader), as in LambderResponse.
  */
 export type LambderApiAnswer = {
     statusCode: number;
     headers: Record<string, string[]>;
     body: string;
     /**
-     * Finalization hints for the server adapter, carried through so an
-     * answer that started as a LambderResponse loses nothing on the way:
-     * `isBodyBase64` marks a body that is base64 of binary bytes (never
-     * cached by the idempotency engine, never compressed), `compress` and
-     * `etag` are the LambderResponse flags. The mock runtime finalizes
-     * nothing, so it hands the body to the caller as it stands; the stores
-     * drop the hints.
+     * Finalization hints for the server adapter, so an answer that started as
+     * a LambderResponse loses nothing on the way: `isBodyBase64` marks a body
+     * that is base64 of binary bytes (never cached by the idempotency engine,
+     * never compressed); `compress` and `etag` are the LambderResponse flags.
+     * The mock runtime finalizes nothing and the stores drop the hints.
      */
     isBodyBase64?: boolean;
     compress?: boolean | "auto";
     etag?: boolean | "auto";
 };
 /**
- * An answer in the accessor form resolveApiOutcome() reads, the same view a
- * fetch Response or a decoded Lambda result is given. What the mock
- * transport hands the caller.
+ * An answer in the accessor form resolveApiOutcome() reads (the same view a
+ * fetch Response or a decoded Lambda result gets); the mock transport hands
+ * this to the caller.
  *
- * The body is handed over as it stands, base64 hint or not: the only answers
- * that reach here are the mock runtime's own, which are JSON envelopes, and
- * a caller reading a binary body through the JSON accessors would have
- * nothing to do with what it decoded anyway.
+ * The body passes through as it stands, base64 hint or not: only the mock
+ * runtime's own answers reach here, and those are JSON envelopes. A binary
+ * body read through the JSON accessors would be of no use decoded anyway.
  */
 export declare const toHttpAnswer: (answer: LambderApiAnswer) => LambderApiHttpAnswer;

package/dist/api/LambderApiAnswer.js

@@ -1,13 +1,12 @@
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 /**
- * An answer in the accessor form resolveApiOutcome() reads, the same view a
- * fetch Response or a decoded Lambda result is given. What the mock
- * transport hands the caller.
+ * An answer in the accessor form resolveApiOutcome() reads (the same view a
+ * fetch Response or a decoded Lambda result gets); the mock transport hands
+ * this to the caller.
  *
- * The body is handed over as it stands, base64 hint or not: the only answers
- * that reach here are the mock runtime's own, which are JSON envelopes, and
- * a caller reading a binary body through the JSON accessors would have
- * nothing to do with what it decoded anyway.
+ * The body passes through as it stands, base64 hint or not: only the mock
+ * runtime's own answers reach here, and those are JSON envelopes. A binary
+ * body read through the JSON accessors would be of no use decoded anyway.
  */
 export const toHttpAnswer = (answer) => ({
     status: answer.statusCode,

package/dist/api/LambderApiCallContext.d.ts

@@ -3,9 +3,8 @@ import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 /**
  * The context the API core needs from whoever runs it. The server's render
  * context and the mock runtime's handler context both extend it; the
- * pipeline, the policy engines and the session controller read and write
- * nothing else on a context, so they never learn which adapter they run
- * under.
+ * pipeline, policy engines and session controller touch nothing else, so
+ * they never learn which adapter they run under.
  *
  * - `session` is set by the pipeline on session APIs (and by the session
  *   controller when a handler creates or ends one).
@@ -24,11 +23,25 @@ export type LambderApiCallContext<TSessionData = any> = {
 /** A fresh call context: no session, no guard data, nothing pending. */
 export declare const createApiCallContext: <TSessionData = any>() => LambderApiCallContext<TSessionData>;
 /**
- * What one call recorded about itself while it ran, in the order things
- * happened. Written as the call goes rather than assembled from what each
- * step returned, so a refusal partway through still reports the guards that
- * had already run: the mock's call log shows exactly the calls a developer is
- * looking at when something denied them.
+ * Binds an adapter's tools onto one call context: `getters` run when read
+ * (`ctx.sessionController` is built over the object it was read from),
+ * `methods` are plain functions, and each is non-enumerable and bound to that
+ * object.
+ *
+ * Non-enumerable keeps a tool on the right object: a copy of the context (a
+ * server hook's `{ ...ctx, extra }`) carries none of them, rather than tools
+ * still bound to the original and its session. The adapter binds them again
+ * on a copy it continues with; configurable lets that replace them.
+ */
+export declare const bindCallTools: (ctx: object, tools: {
+    getters?: Record<string, () => unknown>;
+    methods?: Record<string, (...args: never[]) => unknown>;
+}) => void;
+/**
+ * What one call recorded about itself while it ran, in order. Written as the
+ * call goes rather than assembled from each step's return, so a call refused
+ * partway still reports the guards that had already run (the mock's call log
+ * shows them for exactly the calls a developer is debugging).
  */
 export type LambderApiCallTrace = {
     /** The guards that ran, in order, including on a call that a later one refused. */

package/dist/api/LambderApiCallContext.js

@@ -2,12 +2,30 @@ import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 /** A fresh call context: no session, no guard data, nothing pending. */
 export const createApiCallContext = () => ({
     session: null,
-    // No prototype, for the reason the guard and policy registries are Maps:
-    // guard names are the app's to choose, and on a plain object a guard
-    // named "toString" or "constructor" reads back as an inherited function
-    // for a handler that only wanted to know whether the guard returned
+    // No prototype: guard names are the app's to choose, and on a plain
+    // object a guard named "toString" or "constructor" would read back as an
+    // inherited function to a handler checking whether that guard returned
     // anything.
     guardData: Object.create(null),
     responseHeaders: new LambderAnswerHeaders(),
     logList: [],
 });
+/**
+ * Binds an adapter's tools onto one call context: `getters` run when read
+ * (`ctx.sessionController` is built over the object it was read from),
+ * `methods` are plain functions, and each is non-enumerable and bound to that
+ * object.
+ *
+ * Non-enumerable keeps a tool on the right object: a copy of the context (a
+ * server hook's `{ ...ctx, extra }`) carries none of them, rather than tools
+ * still bound to the original and its session. The adapter binds them again
+ * on a copy it continues with; configurable lets that replace them.
+ */
+export const bindCallTools = (ctx, tools) => {
+    for (const [name, get] of Object.entries(tools.getters ?? {})) {
+        Object.defineProperty(ctx, name, { get, enumerable: false, configurable: true });
+    }
+    for (const [name, value] of Object.entries(tools.methods ?? {})) {
+        Object.defineProperty(ctx, name, { value, enumerable: false, configurable: true, writable: true });
+    }
+};

package/dist/api/LambderApiDefinition.d.ts

@@ -6,9 +6,10 @@ import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRate
  * addApi/addSessionApi options carry, minus the handler, in a shape the mock
  * runtime can restate from a type-only contract. The schemas are optional
  * because the mock has none; when input is present, validation runs and the
- * handler sees the parsed payload. Output is read by nothing at request
- * time: it is part of the endpoint's signature (apiSignatureOf), which is
- * what a client's build is checked against.
+ * handler sees the parsed payload. Output is part of the endpoint's
+ * signature (apiSignatureOf), which is what a client's build is checked
+ * against; the server's resolver also parses every payload a handler
+ * answers through it before it is sent.
  */
 export type LambderApiDefinition = {
     name: string;

package/dist/api/LambderApiEnvelope.d.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 import type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 import { type LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderCrashDetail } from "../shared/wire/LambderCrashDetail.js";
 import type { LambderApiAnswer } from "./LambderApiAnswer.js";
 export declare const API_ANSWER_CONTENT_TYPE = "application/json; charset=utf-8";
 /** The envelope's config plus the logList channel the call accumulated. */
@@ -40,14 +41,13 @@ export type LambderValidationAnswerBody = {
 };
 /**
  * The standard answer for a rejected input: a 422 whose body spells the
- * ZodError out. Spelled out rather than serialized as-is: zod 4 keeps
- * `issues` as a non-enumerable property, so JSON.stringify(zodError) would
- * carry the issues only inside the message string, and a client's
- * validation handler would receive a ZodError with nothing to branch on.
+ * ZodError out. Not serialized as-is: zod 4 keeps `issues` non-enumerable,
+ * so JSON.stringify(zodError) would carry the issues only inside the message
+ * string, leaving a client's validation handler nothing to branch on.
  *
- * zod's own `message` never ships: it is the whole issue tree re-serialized,
- * so carrying it would send every capped byte a second time. The generated
- * summary takes its place on every answer, trimmed or not.
+ * zod's own `message` never ships: it is the whole issue tree re-serialized
+ * and would send every capped byte a second time. A generated summary takes
+ * its place on every answer.
  */
 export declare const validationAnswer: (zodError: z.ZodError, logList?: unknown[]) => LambderApiAnswer;
 /** No API is registered under the requested name: a refusal, not a 404, so a typed caller reads it. */
@@ -62,6 +62,11 @@ export declare const invalidPayloadAnswer: (apiVersion: string | null | undefine
  * The last-resort answer when the call crashed and nothing else could
  * answer: a 500 that is still an envelope, so a caller reads a structured
  * failure rather than a text page. The server sends it only when its global
- * error handler is absent or itself failed.
+ * error handler is absent or itself failed. `revealed` (the crash in full,
+ * with the call's logList) is passed only for a caller the app's
+ * `crashes.reveal` trusts.
  */
-export declare const crashAnswer: (apiVersion: string | null | undefined) => LambderApiAnswer;
+export declare const crashAnswer: (apiVersion: string | null | undefined, revealed?: {
+    crash: LambderCrashDetail;
+    logList: unknown[];
+}) => LambderApiAnswer;

package/dist/api/LambderApiEnvelope.js

@@ -1,14 +1,13 @@
-import { LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
+import { LAMBDER_REFUSAL_CODES, refusalMessageOf } from "../shared/wire/LambderApiRefusal.js";
 import { setAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 /*
  * The one place the API envelope is written, and the one mapping from each
  * kind of protocol outcome onto an answer: a success, a thrown refusal, a
  * rejected input, an unknown name, a missing session, a stale client, a
  * malformed compressed payload, and the last-resort crash. The server's
- * res.api() and the mock runtime's handler wrapping both build through
- * buildApiEnvelope, and the pipeline renders every refusal through the
- * functions below, so the two sides cannot drift on a single byte of the
- * wire format. Pure: no Node built-ins, no response classes.
+ * res.api(), the mock runtime and the pipeline all build through these
+ * functions, so server and mock cannot drift on a single byte of the wire
+ * format. Pure: no Node built-ins, no response classes.
  */
 export const API_ANSWER_CONTENT_TYPE = "application/json; charset=utf-8";
 /**
@@ -22,12 +21,13 @@ export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionE
     ...(versionExpired ? { versionExpired } : {}),
     ...(sessionExpired ? { sessionExpired } : {}),
     ...(notAuthorized ? { notAuthorized } : {}),
-    // Presence, not truthiness: the three channels below carry app values,
-    // and an app that refuses with errorMessage: "" (or 0, or a message
-    // object it built empty) meant to say something. The flags above are
-    // booleans, where false and absent are the same statement.
+    // Presence, not truthiness: these channels carry app values, and an app
+    // that refuses with errorMessage: "" (or 0) meant to say something. The
+    // flags above are booleans, where false and absent mean the same. An
+    // errorMessage goes out as a message object whatever form it was written
+    // in, so every reader meets one shape.
     ...(message !== undefined ? { message } : {}),
-    ...(errorMessage !== undefined ? { errorMessage } : {}),
+    ...(errorMessage !== undefined ? { errorMessage: refusalMessageOf(errorMessage) } : {}),
     ...(crash !== undefined ? { crash } : {}),
     ...(logList?.length ? { logList } : {}),
 });
@@ -63,11 +63,11 @@ export const refusalAnswer = (err, apiVersion, logList) => envelopeAnswer(buildA
  */
 const MAX_VALIDATION_ISSUES = 50;
 /**
- * What the whole issue list may cost, serialized. The count cap alone bounds
+ * What the whole issue list may cost, serialized. A count cap alone bounds
  * the wrong thing: ONE `unrecognized_keys` issue carries every key the client
- * posted, so a strictObject answered a 1MB body with a 4MB one, unauthenticated
- * and before any guard ran, and past maxResponseBytes the 422 became a 500.
- * Bytes are what the amplification is measured in, so bytes are what is
+ * posted, so a strictObject could answer a 1MB body with a 4MB one,
+ * unauthenticated and before any guard ran, and past maxResponseBytes the 422
+ * would become a 500. The amplification is measured in bytes, so bytes are
  * capped.
  */
 const MAX_VALIDATION_ISSUES_BYTES = 32_000;
@@ -78,10 +78,9 @@ const MAX_VALIDATION_TEXT_CHARS = 200;
 const utf8Encoder = new TextEncoder();
 const clampText = (value) => value.length > MAX_VALIDATION_TEXT_CHARS ? `${value.slice(0, MAX_VALIDATION_TEXT_CHARS)}...` : value;
 /**
- * One issue with its own strings and lists bounded. Applied field by field
- * rather than to the named fields only, because `keys` is merely the one that
- * grows without a bound TODAY: any issue a schema authors itself may carry a
- * list or a message the client chose the size of.
+ * One issue with its own strings and lists bounded. Applied to every field
+ * rather than to known ones like `keys`, because any issue a schema authors
+ * itself may carry a list or a message whose size the client chose.
  */
 const clampIssueValue = (value) => {
     if (typeof value === "string")
@@ -91,10 +90,9 @@ const clampIssueValue = (value) => {
     return value;
 };
 const clampIssue = (issue) => 
-// Structurally an issue with shorter values, so the cast says what the
-// mapping already guarantees: every field is carried through, in kind,
-// and the union's discriminant with it. A mapped object has no way to say
-// that in the type system.
+// The mapping carries every field through in kind, the union's
+// discriminant included; the cast states that, since a mapped object
+// cannot express it in the type system.
 Object.fromEntries(Object.entries(issue).map(([key, value]) => [key, clampIssueValue(value)]));
 /** The issue list the body may carry: clamped, then cut to the byte budget, whole issues from the end. */
 const boundIssueList = (all) => {
@@ -108,9 +106,9 @@ const boundIssueList = (all) => {
         const size = utf8Encoder.encode(JSON.stringify(clamped)).length;
         if (bytes + size > MAX_VALIDATION_ISSUES_BYTES) {
             trimmed = true;
-            // A first issue that is over the budget on its own still has to
-            // say what it is: the three fields every issue carries, so a
-            // client always has a code and a path to branch on.
+            // A first issue over the budget on its own still ships the three
+            // fields every issue carries, so a client always has a code and a
+            // path to branch on.
             if (issues.length === 0) {
                 issues.push({ code: clamped.code, path: clamped.path.slice(0, MAX_VALIDATION_LIST_ENTRIES), message: clampText(clamped.message) });
             }
@@ -132,14 +130,13 @@ const summarizeIssues = (total, listed, trimmed) => {
 };
 /**
  * The standard answer for a rejected input: a 422 whose body spells the
- * ZodError out. Spelled out rather than serialized as-is: zod 4 keeps
- * `issues` as a non-enumerable property, so JSON.stringify(zodError) would
- * carry the issues only inside the message string, and a client's
- * validation handler would receive a ZodError with nothing to branch on.
+ * ZodError out. Not serialized as-is: zod 4 keeps `issues` non-enumerable,
+ * so JSON.stringify(zodError) would carry the issues only inside the message
+ * string, leaving a client's validation handler nothing to branch on.
  *
- * zod's own `message` never ships: it is the whole issue tree re-serialized,
- * so carrying it would send every capped byte a second time. The generated
- * summary takes its place on every answer, trimmed or not.
+ * zod's own `message` never ships: it is the whole issue tree re-serialized
+ * and would send every capped byte a second time. A generated summary takes
+ * its place on every answer.
  */
 export const validationAnswer = (zodError, logList) => {
     const { issues, trimmed } = boundIssueList(zodError.issues);
@@ -175,6 +172,8 @@ export const invalidPayloadAnswer = (apiVersion, message) => envelopeAnswer(buil
  * The last-resort answer when the call crashed and nothing else could
  * answer: a 500 that is still an envelope, so a caller reads a structured
  * failure rather than a text page. The server sends it only when its global
- * error handler is absent or itself failed.
+ * error handler is absent or itself failed. `revealed` (the crash in full,
+ * with the call's logList) is passed only for a caller the app's
+ * `crashes.reveal` trusts.
  */
-export const crashAnswer = (apiVersion) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { errorMessage: "Internal server error." }), { statusCode: 500 });
+export const crashAnswer = (apiVersion, revealed) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { errorMessage: "Internal server error.", ...revealed }), { statusCode: 500 });