lambder 6.0.1 → 7.0.1

package/README.md

@@ -7,16 +7,14 @@ idempotency), so an application is a set of declarations rather than a pile of
 per-handler boilerplate.
 
 ```typescript
-import { initLambder, LambderLocalFileSource } from "lambder";
+import { initLambder, LambderLocalFileSource, LambderDdbSessionStore } from "lambder";
 import { z } from "zod";
 
 const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
     files: new LambderLocalFileSource({ root: "./public" }),
-    session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: process.env.SESSION_SALT! },
-});
-
-lambder.addApi("getCompany", {
+    session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: process.env.SESSION_SALT! },
+}).addApi("getCompany", {
     input: z.object({ slug: z.string() }),
     output: z.object({ id: z.string(), name: z.string() }),
 }, async ({ apiPayload }, res) => res.api(await loadCompany(apiPayload.slug)));
@@ -25,6 +23,10 @@ export type ApiContractType = typeof lambder.ApiContract;
 export const handler = lambder.getHandler();
 ```
 
+Registration chains onto the creation call: every `addApi` returns an instance
+carrying the contract so far, so the whole backend is one declaration and
+`lambder.ApiContract` is the accumulated type.
+
 The frontend imports that contract type and gets autocomplete, typed payloads
 and typed results with no hand-written client:
 
@@ -44,8 +46,14 @@ const company = await caller.api("getCompany", { slug: "acme" });
   and consumed by the frontend as a type-only import.
 - **Simple route and API declaration.** Paths, regexes, predicates and
   structured matchers, chained fluently.
-- **Sessions.** DynamoDB-backed, with secrets hashed at rest, sliding
-  expiration, data refresh and cross-subdomain cookies.
+- **Sessions.** Over a store of your choosing (DynamoDB, memory, your own),
+  with secrets hashed at rest, sliding expiration, data refresh and
+  cross-subdomain cookies.
+- **One API core, two runtimes.** The request pipeline (envelope, refusals,
+  sessions, guards, rate limits, idempotency) is one isomorphic class; the
+  Lambda server and the mock runtime are adapters over it, so a mock behaves
+  like the server by construction and the whole policy layer is testable
+  in-process with no AWS.
 - **Declarative policies.** Named rate-limit policies, authorization guards and
   idempotency, referenced by name from an API declaration and checked at
   compile time.
@@ -69,18 +77,19 @@ const company = await caller.api("getCompany", { slug: "acme" });
 npm install lambder zod
 ```
 
-`zod` and the AWS SDK clients are optional peer dependencies, so installing
-lambder never drags them into your tree. Add whatever the code you actually
-import needs:
+`zod` is a required peer dependency: the published declarations name its types,
+so npm installs it alongside lambder. The four AWS SDK clients and `msw` are
+optional peers, so installing lambder never drags them into your tree. Add
+whatever the code you actually import needs:
 
 | What you import | What to install alongside |
 | --- | --- |
-| `lambder/client` (browser, shared isomorphic code) | `zod` |
-| `lambder` on AWS Lambda (`nodejs18.x` and 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/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` 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 |
-| `lambder/testing` | `msw` |
+| `lambder/mock` | nothing; `msw` only for the optional network-panel adapter |
 
 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
@@ -94,19 +103,28 @@ The package ships three entry points; pick by where the code runs:
 
 | Entry | Runs in | Carries |
 | --- | --- | --- |
-| `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus everything from `lambder/client` |
-| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiError`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
-| `lambder/testing` | Dev and test tooling | `LambderMSW`, the MSW adapter that serves your typed contract from mock handlers |
+| `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus the API core's building blocks and everything from `lambder/client` except the two request-compression helpers, `compressPayloadGzip` and `isRequestCompressionAvailable`, which stay on the client entry where a payload is compressed |
+| `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 |
 
 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
 pipeline, so the browser boundary is structural rather than left to
 tree-shaking.
 
-Source layout mirrors this: `src/core/` (request pipeline), `src/policies/`
-(declarative rate limits, guards, idempotency), `src/session/`, `src/stores/`
-(DynamoDB primitives), `src/client/`, `src/invoke/` (the lambda-to-lambda
-caller), and `src/shared/` (isomorphic modules both entries re-export).
+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/`,
+`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).
+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.
 
 ## Documentation
 
@@ -119,16 +137,17 @@ 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 `LambderApiError` |
+| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal` |
 | [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
-| [Sessions](./docs/sessions.md) | DynamoDB sessions, cookie scope, secrets at rest, `dataRefresh`, the controller API |
+| [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 |
 | [Calling another lambda](./docs/invoke.md) | `LambderInvokeCaller`: invoking a Lambder app in another function, its contract, failures and compression |
-| [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression |
+| [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` |
 | [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
 | [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, runtime dictionaries |
-| [Testing](./docs/testing.md) | `LambderMSW`: typed MSW mocking of the API contract |
+| [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 three entry points export, grouped by purpose |
 
@@ -142,22 +161,30 @@ 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 and auto language detection (isomorphic) |
 | `LambderDdbCache` | [DynamoDB cache](./docs/ddb-cache.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill and grouped keys (server-only) |
-| `LambderDdbRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | DynamoDB fixed-window rate limiter, atomic per window (server-only) |
-| `LambderDdbIdempotency` | [Idempotency store](./docs/ddb-idempotency.md) | DynamoDB idempotency records with owner-checked claims and compressed replays (server-only) |
-| `LambderMSW` | [Testing](./docs/testing.md) | Typed MSW mocking of the API contract for frontend development |
+| `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) |
 
 ## Versioning and changes
 
 Released versions and what each one changed are in
-[CHANGELOG.md](./CHANGELOG.md). The current major is v5, which is v4's API
-plus this documentation set: upgrading from 4.x needs no code changes.
-Upgrading from 3.x is covered by the breaking-changes section of the 4.0.1
-entry.
+[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.
 
 ## Contributing
 
-Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to
-run the tests and what a good change looks like.
+Contributions are welcome. Open an issue for a bug or an idea, or send a pull
+request. `npm test` typechecks, builds `dist/` and runs the suite, and it must
+pass before a change is ready: the type system carries a lot of this
+framework's guarantees, so a change that only passes at runtime is not
+finished. New behavior belongs in the matching page under
+[docs/](./docs/README.md) and in [CHANGELOG.md](./CHANGELOG.md) too.
 
 ## License
 

package/dist/api/LambderApiAnswer.d.ts

@@ -0,0 +1,40 @@
+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.
+ *
+ * Header names keep the casing they were written with; lookups are
+ * case-insensitive (see getAnswerHeader), the way LambderResponse treats
+ * them.
+ */
+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.
+     */
+    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.
+ *
+ * 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.
+ */
+export declare const toHttpAnswer: (answer: LambderApiAnswer) => LambderApiHttpAnswer;

package/dist/api/LambderApiAnswer.js

@@ -0,0 +1,19 @@
+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.
+ *
+ * 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.
+ */
+export const toHttpAnswer = (answer) => ({
+    status: answer.statusCode,
+    statusText: "",
+    header: (name) => getAnswerHeader(answer.headers, name)?.join(", ") ?? null,
+    json: async () => JSON.parse(answer.body),
+    text: async () => answer.body,
+    setCookies: getAnswerHeader(answer.headers, "Set-Cookie") ?? [],
+});

package/dist/api/LambderApiCallContext.d.ts

@@ -0,0 +1,38 @@
+import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
+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.
+ *
+ * - `session` is set by the pipeline on session APIs (and by the session
+ *   controller when a handler creates or ends one).
+ * - `guardData` receives the return values of the guards that ran.
+ * - `responseHeaders` collects headers written during the call, applied
+ *   onto the answer by the pipeline.
+ * - `logList` collects entries for the envelope's logList channel
+ *   (`res.logToApiResponse` on the server).
+ */
+export type LambderApiCallContext<TSessionData = any> = {
+    session: LambderSessionRecord<TSessionData> | null;
+    guardData: Record<string, unknown>;
+    responseHeaders: LambderAnswerHeaders;
+    logList: unknown[];
+};
+/** 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.
+ */
+export type LambderApiCallTrace = {
+    /** The guards that ran, in order, including on a call that a later one refused. */
+    guardsRun: string[];
+    /** True when a stored idempotent answer was replayed and no handler ran. */
+    replayed: boolean;
+};

package/dist/api/LambderApiCallContext.js

@@ -0,0 +1,13 @@
+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
+    // anything.
+    guardData: Object.create(null),
+    responseHeaders: new LambderAnswerHeaders(),
+    logList: [],
+});

package/dist/api/LambderApiDefinition.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "../shared/wire/LambderApiOptionValues.js";
+/**
+ * One endpoint's declaration as the pipeline runs it: what the server's
+ * addApi/addSessionApi options carry, minus the handler, in a shape the mock
+ * runtime can restate from a type-only contract. The schema is optional
+ * because the mock has none; when present, input validation runs and the
+ * handler sees the parsed payload.
+ */
+export type LambderApiDefinition = {
+    name: string;
+    mode: LambderApiMode;
+    guards?: LambderGuardsOptionValue;
+    rateLimit?: LambderRateLimitOptionValue;
+    idempotency?: LambderApiIdempotencyOption;
+    input?: z.ZodType;
+};

package/dist/api/LambderApiDefinition.js

@@ -0,0 +1 @@
+export {};

package/dist/api/LambderApiEnvelope.d.ts

@@ -0,0 +1,67 @@
+import type { z } from "zod";
+import type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
+import { type LambderApiRefusal } from "../shared/wire/LambderApiRefusal.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. */
+export type LambderApiEnvelopeConfig = LambderApiResponseConfig & {
+    logList?: unknown[];
+};
+/**
+ * The wire envelope for one answer. Flags are only present when set, so a
+ * plain success is `{ apiVersion, payload }` and nothing else; an empty
+ * logList is omitted.
+ */
+export declare const buildApiEnvelope: <T>(apiVersion: string | null | undefined, payload: T | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, crash, }?: LambderApiEnvelopeConfig) => LambderApiEnvelopeBody<T>;
+/** An envelope as an answer: JSON body, JSON content type, the status and headers given (200 and none by default). */
+export declare const envelopeAnswer: (envelope: LambderApiEnvelopeBody<unknown>, options?: {
+    statusCode?: number;
+    headers?: Record<string, string | string[]>;
+}) => LambderApiAnswer;
+/**
+ * A thrown refusal as an answer: its errorMessage and flags on the envelope,
+ * its status (200 unless it set one) and its extra headers (Retry-After on a
+ * rate limit). The logList the call accumulated rides along, as it does on
+ * a success.
+ */
+export declare const refusalAnswer: (err: LambderApiRefusal, apiVersion: string | null | undefined, logList?: unknown[]) => LambderApiAnswer;
+/** The body a validation refusal carries, the shape resolveApiOutcome reads a 422 by. */
+export type LambderValidationAnswerBody = {
+    error: string;
+    zodError: {
+        name: string;
+        message: string;
+        issues: z.core.$ZodIssue[];
+    };
+    /** Present only when the answer was trimmed (issues dropped, or oversized values inside one shortened): how many issues there were. */
+    issueCount?: number;
+    /** The logList channel the call accumulated, as a success carries it; omitted when empty. */
+    logList?: unknown[];
+};
+/**
+ * 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.
+ *
+ * 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.
+ */
+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. */
+export declare const apiNotFoundAnswer: (apiVersion: string | null | undefined, logList?: unknown[]) => LambderApiAnswer;
+/** A session API called without a live session: the protocol's sessionExpired flag, which the caller clears its cookies on. */
+export declare const sessionExpiredAnswer: (apiVersion: string | null | undefined, logList?: unknown[]) => LambderApiAnswer;
+/** The caller's version is behind the server's: the protocol's versionExpired flag, which the caller reloads on. */
+export declare const versionExpiredAnswer: (apiVersion: string | null | undefined) => LambderApiAnswer;
+/** A compressed request payload that could not be restored: a 400 with the reason, never a crash. */
+export declare const invalidPayloadAnswer: (apiVersion: string | null | undefined, message: string) => LambderApiAnswer;
+/**
+ * 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.
+ */
+export declare const crashAnswer: (apiVersion: string | null | undefined) => LambderApiAnswer;

package/dist/api/LambderApiEnvelope.js

@@ -0,0 +1,180 @@
+import { LAMBDER_REFUSAL_CODES } 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.
+ */
+export const API_ANSWER_CONTENT_TYPE = "application/json; charset=utf-8";
+/**
+ * The wire envelope for one answer. Flags are only present when set, so a
+ * plain success is `{ apiVersion, payload }` and nothing else; an empty
+ * logList is omitted.
+ */
+export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, crash, } = {}) => ({
+    apiVersion: apiVersion ?? null,
+    payload,
+    ...(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.
+    ...(message !== undefined ? { message } : {}),
+    ...(errorMessage !== undefined ? { errorMessage } : {}),
+    ...(crash !== undefined ? { crash } : {}),
+    ...(logList?.length ? { logList } : {}),
+});
+/** An envelope as an answer: JSON body, JSON content type, the status and headers given (200 and none by default). */
+export const envelopeAnswer = (envelope, options = {}) => {
+    const headers = { "Content-Type": [API_ANSWER_CONTENT_TYPE] };
+    for (const [key, value] of Object.entries(options.headers ?? {})) {
+        // Through setAnswerHeader, so a header the refusal names under another
+        // casing replaces the envelope's own rather than shipping beside it.
+        setAnswerHeader(headers, key, value);
+    }
+    return { statusCode: options.statusCode ?? 200, headers, body: JSON.stringify(envelope) };
+};
+/**
+ * A thrown refusal as an answer: its errorMessage and flags on the envelope,
+ * its status (200 unless it set one) and its extra headers (Retry-After on a
+ * rate limit). The logList the call accumulated rides along, as it does on
+ * a success.
+ */
+export const refusalAnswer = (err, apiVersion, logList) => envelopeAnswer(buildApiEnvelope(apiVersion, null, {
+    ...(err.errorMessage !== undefined ? { errorMessage: err.errorMessage } : {}),
+    ...(err.notAuthorized ? { notAuthorized: true } : {}),
+    ...(err.sessionExpired ? { sessionExpired: true } : {}),
+    logList,
+}), {
+    ...(err.statusCode !== undefined ? { statusCode: err.statusCode } : {}),
+    ...(err.headers ? { headers: err.headers } : {}),
+});
+/**
+ * How many issues a 422 spells out before it starts counting instead. A
+ * caller fixing their request needs the first few; the rest are the same
+ * mistake repeated.
+ */
+const MAX_VALIDATION_ISSUES = 50;
+/**
+ * What the whole issue list may cost, serialized. The 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
+ * capped.
+ */
+const MAX_VALIDATION_ISSUES_BYTES = 32_000;
+/** How many entries of one issue's own lists (`keys`, `path`) survive. */
+const MAX_VALIDATION_LIST_ENTRIES = 20;
+/** How long one string inside an issue may be. */
+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.
+ */
+const clampIssueValue = (value) => {
+    if (typeof value === "string")
+        return clampText(value);
+    if (Array.isArray(value))
+        return value.slice(0, MAX_VALIDATION_LIST_ENTRIES).map(clampIssueValue);
+    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.
+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) => {
+    const issues = [];
+    let bytes = 0;
+    let trimmed = false;
+    for (const issue of all.slice(0, MAX_VALIDATION_ISSUES)) {
+        const clamped = clampIssue(issue);
+        if (JSON.stringify(clamped) !== JSON.stringify(issue))
+            trimmed = true;
+        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.
+            if (issues.length === 0) {
+                issues.push({ code: clamped.code, path: clamped.path.slice(0, MAX_VALIDATION_LIST_ENTRIES), message: clampText(clamped.message) });
+            }
+            break;
+        }
+        issues.push(clamped);
+        bytes += size;
+    }
+    return { issues, trimmed: trimmed || issues.length < all.length };
+};
+/** What the answer says about itself, in place of zod's own message. */
+const summarizeIssues = (total, listed, trimmed) => {
+    const head = `${total} validation issue${total === 1 ? "" : "s"}`;
+    if (listed < total)
+        return `${head}; the first ${listed} are listed.`;
+    if (trimmed)
+        return `${head}; oversized values are shortened.`;
+    return `${head}.`;
+};
+/**
+ * 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.
+ *
+ * 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.
+ */
+export const validationAnswer = (zodError, logList) => {
+    const { issues, trimmed } = boundIssueList(zodError.issues);
+    return {
+        statusCode: 422,
+        headers: { "Content-Type": [API_ANSWER_CONTENT_TYPE] },
+        body: JSON.stringify({
+            error: "Input validation failed",
+            zodError: {
+                name: zodError.name,
+                message: summarizeIssues(zodError.issues.length, issues.length, trimmed),
+                issues,
+            },
+            ...(trimmed ? { issueCount: zodError.issues.length } : {}),
+            ...(logList?.length ? { logList } : {}),
+        }),
+    };
+};
+/** No API is registered under the requested name: a refusal, not a 404, so a typed caller reads it. */
+export const apiNotFoundAnswer = (apiVersion, logList) => envelopeAnswer(buildApiEnvelope(apiVersion, null, {
+    errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.apiNotFound, content: "API not found." },
+    logList,
+}));
+/** A session API called without a live session: the protocol's sessionExpired flag, which the caller clears its cookies on. */
+export const sessionExpiredAnswer = (apiVersion, logList) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { sessionExpired: true, logList }));
+/** The caller's version is behind the server's: the protocol's versionExpired flag, which the caller reloads on. */
+export const versionExpiredAnswer = (apiVersion) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { versionExpired: true }));
+/** A compressed request payload that could not be restored: a 400 with the reason, never a crash. */
+export const invalidPayloadAnswer = (apiVersion, message) => envelopeAnswer(buildApiEnvelope(apiVersion, null, {
+    errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidRequestPayload, content: message },
+}), { statusCode: 400 });
+/**
+ * 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.
+ */
+export const crashAnswer = (apiVersion) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { errorMessage: "Internal server error." }), { statusCode: 500 });