lambder 9.0.2 → 10.0.1

package/CHANGELOG.md

@@ -9,6 +9,201 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [10.0.1] - 2026-09-28
+
+A major that makes both sides of an API answer exact. A success is only ever
+the handler's parsed output, an object or an array, so a caller's success is
+typed as exactly the endpoint's output and is never null or falsy. A refusal
+names a code the app declared once, with the schema of its data and the
+status and flag it leaves with: the contract carries every code an endpoint
+can refuse with, a caller narrows `refusal.data` on the code, and a refusal
+outside its declaration is a crash rather than an answer, which is what keeps
+the caller's type honest. The envelope field that carries it is now called
+what it is, `refusal`.
+
+### Changed (breaking)
+
+- **The envelope's `errorMessage` is `refusal`,** on every surface: the wire
+  field, an outcome's `refusal` and its reason `'refusal'` (not
+  `'errorMessage'`), the callers' `refusalHandler`, `res.apiRefusal({
+  refusal })`, a `LambderApiRefusal`'s `refusal` and the option that sets it,
+  a rate-limit policy's and an override's `refusal`, the generated policy
+  table's `refusal`, and `LambderIdempotentAttemptOutcome.refusal`. The field
+  carries a typed refusal with a code and data, and it may be an "info" or a
+  "warning", so "error message" named neither its role nor its type. Lambda's
+  own `errorMessage` on a function error is Lambda's and keeps its name.
+- **An API's output is an object or an array.** An output schema whose JSON
+  form is anything else (`z.void()`, `z.boolean()`, `z.number()`, a nullable
+  or an optional object, `z.date()`) is a compile error on the `output`
+  option, and a handler that answers one anyway is a crash
+  (`LambderApiOutputValidationError`, which gains that kind). `caller.api()`
+  is then truthy exactly on success.
+  - To move: an API with nothing to answer declares `output: z.object({})`
+    and returns `{}`; one that answered a primitive wraps it
+    (`{ count }`); one whose output was nullable answers `{ order: null }`.
+- **A success outcome's payload is exactly the output.**
+  `LambderApiSuccessOutcome<T>` is `payload: T`, not `T | null | undefined`,
+  and `LambderCaller.api()` returns `T | undefined`, `undefined` on every
+  failure, a refusal included (it no longer hands back the refusal
+  envelope's payload). `LambderInvokeCaller` no longer turns an absent
+  payload into `null`.
+- **A reader takes a success only when its payload is an object or an
+  array.** A 2xx envelope with no flag and no refusal whose payload is
+  null, a primitive or missing reads as reason `server`: no handler wrote it.
+- **`res.api(payload, config, options)` is `res.apiRefusal(config,
+  options)`.** An API call answered from outside its handler (a hook, a
+  fallback, the input validation handler, the global error handler) is
+  always a refusal: the config carries a `refusal` or one of the
+  `versionExpired`, `sessionExpired` and `notAuthorized` flags (a compile
+  error and a thrown error otherwise), the payload is null, and its message
+  carries a framework code or none, never an app code or data.
+  `res.die.api` is `res.die.apiRefusal`, and `LambderApiResponseConfig` is
+  `LambderApiRefusalConfig`.
+  - To move: `res.api(null, config, options)` becomes `res.apiRefusal(config,
+    options)`. A hook that answered an API call with a cached success moves
+    the cache into the handler, which answers from it.
+- **The mock's `onInvalidInput` answers `{ config, statusCode? }`,** a
+  refusal held to the same rule, with no payload. A mock handler that
+  answers anything but an object or an array crashes the call, as the
+  server does, instead of answering a null payload.
+- **The envelope is two shapes.** `LambderApiEnvelopeBody<T>` is a
+  `LambderApiSuccessEnvelope<T>` (the payload) or a
+  `LambderApiRefusalEnvelope` (a null payload beside the flags, the
+  refusal and a crash). A failure outcome's `response` is the refusal
+  envelope. `buildApiEnvelope` is replaced by `successEnvelope`,
+  `refusalEnvelope` and `plainRefusalEnvelope`, and
+  `LambderApiEnvelopeConfig` by `LambderRefusalEnvelopeFields`.
+  `LambderJsonOutputOf` is removed: an output is `LambderJsonOf` of the
+  schema's output.
+- **A coded refusal must be declared, and leaves as declared.** A refusal
+  whose code is neither a framework code nor one its endpoint declares, data
+  on a refusal whose code declares none, no data on one whose code carries
+  data, data its code's schema rejects, or a declared code raised with a
+  status or `notAuthorized` flag of its own (its declaration owns them) is
+  now a crash (`LambderApiRefusalValidationError`) rather than an answer. The
+  same check runs on a refusal a hook throws for an API call, and in the
+  mock where it has the generated options.
+  - To move: declare every code with `initLambder().declareRefusals()`
+    (below), name each in the `refusals` option of the APIs and guards that
+    raise it, and move a code's status and `notAuthorized` from its raise
+    sites into its declaration.
+- **`create()` takes no `refusals`.** The vocabulary is declared on the init,
+  `initLambder<SessionData>().declareRefusals(vocabulary)`, before any guard
+  is built, so guards and shared helpers can be typed to it; `create()` on
+  that init hands it to the instance. `LambderCreateOptions.refusals` stays
+  for the class constructed directly.
+- **`LambderRefusalMessage` is generic over an endpoint's declared codes.**
+  Its argument is the contract's map of code to `{ data }` or `{}`
+  (`LambderContractRefusalsOf`), not a union of code strings, and the
+  message is one arm per code, so `data` narrows on `code`. The message
+  shape gains `data`. `LambderAppRefusalMessage` is
+  `LambderUncheckedRefusalMessage`: the message before any check, what a
+  thrown refusal carries and what a reader gets off a body no server
+  vouched for; an app's own message is a declared one.
+- **A rate-limit message carries no code.** A policy's and an override's
+  `refusal` is a `LambderRateLimitMessage` (type, title, content); every
+  rate-limit refusal is `lambder/rate-limited`. A code or data there is a
+  compile error on a policy and a creation or registration error on both.
+- **An endpoint's signature covers its declared refusals,** codes, data
+  schemas, statuses and flags, so every endpoint's signature changes once
+  with this version, and adding a code to an endpoint or a guard, or
+  changing how a code leaves, reloads its callers.
+- **The instance has a ninth and a tenth type parameter,** the refusal
+  vocabulary and whether every refusal names a code. Code that names
+  `Lambder<...>` with every parameter written out adds two.
+- **An entry of the mock whose `apiOptions` entry declares guards needs
+  `guardDeclarations` beside the table,** which holds the codes those guards
+  add, and one that can refuse with a declared code needs the vocabulary
+  declared on the mock init (`initLambderMock().declareRefusals()`, the same
+  object the server's init declares); registering one without them throws,
+  as does a table naming a code the vocabulary does not hold.
+- **`LambderContractRefusalsFor` is `LambderWireRefusalsOf`** (it pairs with
+  `LambderHandlerRefusalsOf`: the same codes in the handler's form and in
+  wire form), and **`handWrittenRefusalEnvelope` is `plainRefusalEnvelope`**
+  (what it enforces is a plain refusal message: a framework code or none,
+  and no data).
+
+### Added
+
+- **Declared refusals.** `initLambder().declareRefusals(vocabulary)` is the
+  app's vocabulary: each code once, `{}` or `{ data: schema }` (an object or
+  an array, as an output), with the `status` every refusal with it leaves
+  with (200 by default, never 422 or a 5xx) and whether it sets
+  `notAuthorized`. The init it returns is bound to it: its `guard()` types a
+  guard's `ctx.refuse` to the guard's `refusals` and refuses a guard naming a
+  code outside the vocabulary as it is built, its `refuse` is typed to the
+  whole vocabulary for shared helpers and hooks, and its `create()` hands the
+  vocabulary to the instance. `addApi` and `addSessionApi` take `refusals`,
+  one code or a non-empty list, and a guard takes `refusals` too; a guard's
+  codes join every API that declares it. The handler's context carries
+  `ctx.refuse`, typed to those codes with `data` required where a code
+  declares it and no status or flag of its own; the free `refuse()` and
+  `LambderApiRefusal` take `code` and `data` from a shared helper. A declared
+  code's data is parsed through its schema before it is sent, and the
+  refusal leaves with its declaration's status and flag. The contract entry
+  carries `refusals`, every code the endpoint can refuse with;
+  `LambderContractRefusalsOf`, `LambderContractRefusalMessage`,
+  `LambderContractRefusals` and `LambderContractAnyRefusalMessage` read it;
+  an outcome's `refusal` (on the browser caller, the invoke caller, the test
+  visitor and the mock) and a per-call `refusalHandler` are typed per
+  endpoint, and the constructor's `refusalHandler` across the contract. The
+  generated options record each API's `refusals` and each guard declaration's;
+  the vocabulary itself is not written, since it is shared code the mock
+  declares as the server does.
+- **`declareRefusals(vocabulary, { requireCodes: true })`** makes every
+  refusal an API answers with name a declared or framework code: an uncoded
+  `refuse("...")` from a handler, a guard or a helper is then a crash rather
+  than an answer, and `ctx.refuse` and the init's `refuse` require a code.
+  The mock's `declareRefusals` takes the same option.
+- **`assertApiRefusal(outcome, code)`** in `lambder/testing` and
+  `lambder/mock`: asserts a refusal's code on any failure arm and narrows its
+  `refusal` to that code, data typed. `LambderExpectedFailure.code` is
+  typed to the outcome's codes.
+- **The mock declares the vocabulary and refuses as the server does.**
+  `initLambderMock().declareRefusals(vocabulary, { requireCodes? })` takes
+  the same object and option the server's init does, from shared code. A
+  mock handler's `ctx.refuse` and the mock init's `refuse` are then typed to
+  the codes the contract gives the endpoint with each code's data in the
+  schema's input form, and the mock checks and sends a refusal exactly as the
+  server would: the code among the codes the generated tables give the entry,
+  the data parsed through the code's schema (defaults filled, transforms run
+  once), and the declaration's status and flag. `failNext` and `setFailure`
+  take an injected refusal the same way. A mock that declared no vocabulary
+  types `ctx.refuse` from the contract's wire form and checks nothing.
+  `LambderMockRefusalsOf` is the map behind both.
+- `checkedRefusal`, `LambderApiRefusalValidationError`,
+  `LambderRefusalDeclaration`, `LambderRefusalVocabulary`,
+  `LambderRefusalStatusCode`,
+  `LambderApiAllowedRefusal`, `LambderApiAllowedRefusals`,
+  `LambderEndpointRefusals`, `LambderRefusalsOption`,
+  `LambderRefusalNamesIn`, `LambderRefusalsOptionValue`,
+  `LambderHandlerRefusalsOf`, `LambderWireRefusalsOf`,
+  `LambderGuardRefusals`, `LambderGuardRefusalNamesOf`,
+  `LambderPlainRefusalMessage`, `LambderUncheckedRefusalMessage`,
+  `LambderDeclaredRefuse`, `LambderDeclaredRefuseOptions`,
+  `LambderRateLimitMessage`, `LambderRefusalEnvelopeFields`,
+  `isLambderRefusalCode`, `isObjectPayload`, `successEnvelope`,
+  `refusalEnvelope` and `plainRefusalEnvelope`.
+
+## [9.0.3] - 2026-09-27
+
+An upload bucket can now sign a ticket that sends the file with a PUT instead
+of a form POST, for a store without S3's presigned POST (Cloudflare R2 among
+them).
+
+### Added
+
+- **`LambderUploadTicket` is `{ method: "POST", ... }` or `{ method: "PUT",
+  ... }`.** A POST ticket carries `formFields` as before; a PUT ticket carries
+  `headers`, every one signed into the URL, that `LambderUploadRunner` sends
+  unchanged with the file as the body. `LambderMemoryUploadBucket` and
+  `LambderS3UploadBucket` both take a `uploadMethod` option (default `POST`)
+  and sign whichever kind of ticket that asks for.
+- **`uploadObjectHeaders`** builds a PUT ticket's headers the way
+  `uploadObjectFormFields` builds a POST ticket's fields: the tag set as
+  `x-amz-tagging`, each metadata entry as `x-amz-meta-<name>`, `cache-control`
+  and `content-disposition`.
+
 ## [9.0.2] - 2026-09-27
 
 Nothing a handler or a caller does changes; the package, its docs and its

package/README.md

@@ -24,7 +24,8 @@ export const handler = lambder.getHandler();
 ```
 
 A handler returns its output, which is parsed through the output schema before
-it is sent, and says no by throwing `refuse()`. Registration chains onto the
+it is sent, and says no by throwing a refusal: `ctx.refuse()`, typed to the
+codes the API declares, or `refuse()` from anywhere. 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.
@@ -46,6 +47,16 @@ const company = await caller.api("getCompany", { slug: "acme" });
   runtime validation and compile-time inference on both sides of the wire.
 - **One inferred contract.** The API contract is derived from the backend code
   and consumed by the frontend as a type-only import.
+- **Exact results.** A success is only ever the handler's parsed output, an
+  object or an array, so a caller's success is typed as exactly the output and
+  is never null or falsy; everything a hook or an error handler answers is a
+  refusal.
+- **Declared refusals.** An app declares its refusal codes once, each with the
+  schema of its data, the status it leaves with and whether it flags
+  `notAuthorized`; every API and guard names the codes it may refuse with, and
+  a guard's or a handler's `ctx.refuse` is typed to them. The contract carries
+  them, a caller narrows `refusal.data` on the code, and a refusal outside its
+  declaration is a crash, never an answer.
 - **Simple route and API declaration.** Paths, regexes, predicates and
   structured matchers, chained fluently.
 - **Sessions.** Over a store of your choosing (DynamoDB, memory, your own),
@@ -69,8 +80,9 @@ 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,
+- **Direct uploads.** Files go from the browser straight to S3, or to R2 on
+  presigned PUTs, 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
@@ -163,7 +175,7 @@ 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 |
+| [Direct uploads](./docs/uploads.md) | Files the browser sends straight to S3 or R2 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 |
@@ -187,16 +199,19 @@ framework:
 ## Versioning and changes
 
 Released versions and what each one changed are in
-[CHANGELOG.md](./CHANGELOG.md). The current major is v9, which gives an API
-handler one shape: it takes its context and returns its output, says no with
-`refuse()`, and writes headers, cookies and log entries through the context,
-while the response builder stays with routes, hooks and error handlers. Every
-break and what to do about it is in the 9.0.1 entry, and the compiler finds
-most of them. The one it cannot is a change of behavior: a refusal is no
-longer stored under an idempotency key, so a retry after one runs the handler
-again. An app still on v7 goes through the 8.0.2 entry first, which
-names the breaks of v8 the compiler cannot find, and one on v6 through the
-7.0.0 entry before that.
+[CHANGELOG.md](./CHANGELOG.md). The current major is v10, which makes both
+sides of an answer exact. A success is only ever the handler's parsed output,
+and an output is an object or an array, so `caller.api()` is truthy exactly
+on success and a success's payload is typed as exactly the output; a hook, a
+fallback or an error handler answers an API call with `res.apiRefusal()`,
+never with a payload. A refusal names a code the app declared, which the
+contract carries and a caller narrows on, with its data typed. Every break
+and what to do about it is in the 10.0.1 entry, and the compiler finds most
+of them. The ones it cannot are changes of behavior: a refusal whose code its
+API does not declare is now a crash rather than an answer, and a success
+whose payload is not an object or an array now reads as a server failure. An
+app still on v8 goes through the 9.0.1 entry first, and one on an older
+major through the entries before it.
 
 ## Contributing
 

package/dist/api/LambderApiDefinition.d.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { LambderEndpointRefusals } from "./LambderApiRefusals.js";
 import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "../shared/wire/LambderApiOptionValues.js";
 /**
@@ -10,6 +11,13 @@ import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRate
  * signature (apiSignatureOf), which is what a client's build is checked
  * against; the server also parses every output a handler returns through it
  * before it is sent.
+ *
+ * `refusals` is every code the endpoint may refuse with (its own option and
+ * its guards'), resolved against the vocabulary, and whether every refusal
+ * has to name one: what every refusal it answers with is checked against
+ * (checkedRefusal); the codes are part of its signature. Undefined where the
+ * codes are not known (a mock without generated options), which checks
+ * nothing.
  */
 export type LambderApiDefinition = {
     name: string;
@@ -19,4 +27,5 @@ export type LambderApiDefinition = {
     idempotency?: LambderApiIdempotencyOption;
     input?: z.ZodType;
     output?: z.ZodType;
+    refusals?: LambderEndpointRefusals;
 };

package/dist/api/LambderApiEnvelope.d.ts

@@ -1,26 +1,38 @@
 import type { z } from "zod";
-import type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiEnvelopeBody, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderApiRefusalEnvelope, LambderApiSuccessEnvelope } 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. */
-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.
+ * A handler's answer as the wire envelope: its parsed output and the logList
+ * the call accumulated, nothing else. The only envelope a reader takes for a
+ * success; an empty logList is omitted.
+ */
+export declare const successEnvelope: <T>(apiVersion: string | null | undefined, payload: T, logList?: unknown[]) => LambderApiSuccessEnvelope<T>;
+/**
+ * Every other answer as the wire envelope: a null payload beside the
+ * refusal's message and flags. Flags are only present when set, and an
+ * empty logList is omitted.
+ */
+export declare const refusalEnvelope: (apiVersion: string | null | undefined, { versionExpired, sessionExpired, notAuthorized, refusal, logList, crash }: LambderRefusalEnvelopeFields) => LambderApiRefusalEnvelope;
+/**
+ * An API call answered from outside its handler (res.apiRefusal on the
+ * server, onInvalidInput in the mock) as its envelope, once the config is
+ * known to be a refusal: a refusal message or one of the three flags, so a
+ * reader never takes it for the handler's output, and a message with a
+ * framework code or none and no data, since it answers outside any one
+ * endpoint's declared refusals. `writer` names the call in the error, and
+ * the logList is the config's own or the one given.
  */
-export declare const buildApiEnvelope: <T>(apiVersion: string | null | undefined, payload: T | null, { versionExpired, sessionExpired, notAuthorized, errorMessage, logList, crash, }?: LambderApiEnvelopeConfig) => LambderApiEnvelopeBody<T>;
+export declare const plainRefusalEnvelope: (apiVersion: string | null | undefined, config: LambderApiRefusalConfig, writer: string, logList?: unknown[]) => LambderApiRefusalEnvelope;
 /** 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,
+ * A thrown refusal as an answer: its refusal 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.

package/dist/api/LambderApiEnvelope.js

@@ -1,35 +1,70 @@
-import { LAMBDER_REFUSAL_CODES, refusalMessageOf } from "../shared/wire/LambderApiRefusal.js";
+import { LAMBDER_REFUSAL_CODES, isLambderRefusalCode, 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 API
- * path and res.api(), the mock runtime and the pipeline all build through these
+ * path and res.apiRefusal(), 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";
 /**
- * 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.
+ * A handler's answer as the wire envelope: its parsed output and the logList
+ * the call accumulated, nothing else. The only envelope a reader takes for a
+ * success; an empty logList is omitted.
  */
-export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionExpired, notAuthorized, errorMessage, logList, crash, } = {}) => ({
+export const successEnvelope = (apiVersion, payload, logList) => ({
     apiVersion: apiVersion ?? null,
     payload,
-    ...(versionExpired ? { versionExpired } : {}),
-    ...(sessionExpired ? { sessionExpired } : {}),
-    ...(notAuthorized ? { notAuthorized } : {}),
+    ...(logList?.length ? { logList } : {}),
+});
+/**
+ * Every other answer as the wire envelope: a null payload beside the
+ * refusal's message and flags. Flags are only present when set, and an
+ * empty logList is omitted.
+ */
+export const refusalEnvelope = (apiVersion, { versionExpired, sessionExpired, notAuthorized, refusal, logList, crash }) => ({
+    apiVersion: apiVersion ?? null,
+    payload: null,
+    ...(versionExpired ? { versionExpired: true } : {}),
+    ...(sessionExpired ? { sessionExpired: true } : {}),
+    ...(notAuthorized ? { notAuthorized: true } : {}),
     // Presence, not truthiness: these channels carry app values, and an app
-    // that refuses with errorMessage: "" (or 0) meant to say something. The
+    // that refuses with refusal: "" (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
+    // refusal goes out as a message object whatever form it was written
     // in, so every reader meets one shape.
-    ...(errorMessage !== undefined ? { errorMessage: refusalMessageOf(errorMessage) } : {}),
+    ...(refusal !== undefined ? { refusal: refusalMessageOf(refusal) } : {}),
     ...(crash !== undefined ? { crash } : {}),
     ...(logList?.length ? { logList } : {}),
 });
+/**
+ * An API call answered from outside its handler (res.apiRefusal on the
+ * server, onInvalidInput in the mock) as its envelope, once the config is
+ * known to be a refusal: a refusal message or one of the three flags, so a
+ * reader never takes it for the handler's output, and a message with a
+ * framework code or none and no data, since it answers outside any one
+ * endpoint's declared refusals. `writer` names the call in the error, and
+ * the logList is the config's own or the one given.
+ */
+export const plainRefusalEnvelope = (apiVersion, config, writer, logList) => {
+    const { refusal, versionExpired, sessionExpired, notAuthorized } = config;
+    if (refusal === undefined && !versionExpired && !sessionExpired && !notAuthorized) {
+        throw new Error(`Lambder: ${writer} needs a refusal message or one of the versionExpired, sessionExpired and notAuthorized flags. An API call answered from outside its handler is always a refusal.`);
+    }
+    if (refusal !== undefined) {
+        const message = refusalMessageOf(refusal);
+        if (message.code !== undefined && !isLambderRefusalCode(message.code)) {
+            throw new Error(`Lambder: ${writer} was given the code "${message.code}". It answers outside any one API's declared refusals, so its message carries a framework code or none.`);
+        }
+        if (message.data !== undefined) {
+            throw new Error(`Lambder: ${writer} was given a message with data. Only a code an API declares carries data, and this answer is outside any one API's declaration.`);
+        }
+    }
+    return refusalEnvelope(apiVersion, { ...config, logList: config.logList ?? 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] };
@@ -41,13 +76,13 @@ export const envelopeAnswer = (envelope, options = {}) => {
     return { statusCode: options.statusCode ?? 200, headers, body: JSON.stringify(envelope) };
 };
 /**
- * A thrown refusal as an answer: its errorMessage and flags on the envelope,
+ * A thrown refusal as an answer: its refusal 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 } : {}),
+export const refusalAnswer = (err, apiVersion, logList) => envelopeAnswer(refusalEnvelope(apiVersion, {
+    ...(err.refusal !== undefined ? { refusal: err.refusal } : {}),
     ...(err.notAuthorized ? { notAuthorized: true } : {}),
     ...(err.sessionExpired ? { sessionExpired: true } : {}),
     logList,
@@ -155,17 +190,17 @@ export const validationAnswer = (zodError, 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." },
+export const apiNotFoundAnswer = (apiVersion, logList) => envelopeAnswer(refusalEnvelope(apiVersion, {
+    refusal: { 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 }));
+export const sessionExpiredAnswer = (apiVersion, logList) => envelopeAnswer(refusalEnvelope(apiVersion, { sessionExpired: true, logList }));
 /** The caller was built against another shape of the endpoint (the signature gate), or the app judged it stale: the protocol's versionExpired flag, which the caller reloads on. */
-export const versionExpiredAnswer = (apiVersion) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { versionExpired: true }));
+export const versionExpiredAnswer = (apiVersion) => envelopeAnswer(refusalEnvelope(apiVersion, { 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 },
+export const invalidPayloadAnswer = (apiVersion, message) => envelopeAnswer(refusalEnvelope(apiVersion, {
+    refusal: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidRequestPayload, content: message },
 }), { statusCode: 400 });
 /**
  * The last-resort answer when the call crashed and nothing else could
@@ -175,4 +210,4 @@ export const invalidPayloadAnswer = (apiVersion, message) => envelopeAnswer(buil
  * with the call's logList) is passed only for a caller the app's
  * `crashes.reveal` trusts.
  */
-export const crashAnswer = (apiVersion, revealed) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { errorMessage: "Internal server error.", ...revealed }), { statusCode: 500 });
+export const crashAnswer = (apiVersion, revealed) => envelopeAnswer(refusalEnvelope(apiVersion, { refusal: "Internal server error.", ...revealed }), { statusCode: 500 });