lambder 8.1.2 → 9.0.1

package/CHANGELOG.md

@@ -9,6 +9,214 @@ 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.
 
+## [9.0.1] - 2026-09-27
+
+A major that gives an API handler one shape. It takes its context and returns
+its output; it says no with `refuse()`; it writes headers, cookies and log
+entries through the context. The response builder stays with routes, hooks,
+fallbacks and error handlers, which build HTTP responses. An API is typed data
+in and typed data out, and a handler that has no response builder cannot
+answer any other way, so the two ways a handler used to refuse (throwing, or
+answering null beside a reason) are one, and the untyped side channels are
+gone. A server handler and its mock twin now read alike.
+
+### Changed (breaking)
+
+- **An API handler returns its output.** `addApi` and `addSessionApi` take
+  `async (ctx) => output` instead of `async (ctx, res) => res.api(output)`.
+  The return is checked against the output schema's input form and parsed
+  through the schema before it is sent, as `res.api()`'s payload was:
+  undeclared fields are stripped, defaults filled, transforms run once, and
+  an output the schema rejects is answered as a crash
+  (`LambderApiOutputValidationError`). A literal in a returned object keeps
+  its type (`{ status: "open" }` is checked as `"open"`, not `string`), which
+  is why the handler's return is its own `const` type parameter; arrays in a
+  returned literal are read as readonly, which is all an answer needs.
+  - To move: drop the second parameter and return what was passed to
+    `res.api()`. An answer that was `res.api(null, { errorMessage })`,
+    `{ notAuthorized }` or `{ sessionExpired }` becomes `refuse(content, {
+    notAuthorized, sessionExpired, code, type })`. A handler that answered
+    null where the output does not allow null no longer compiles; it refuses
+    instead, or the output becomes nullable.
+- **A refusal is never stored for replay.** Only an answer (a returned
+  output) is stored under an idempotency key; a refusal is thrown, the claim
+  is released, and a retry runs the handler again, which decides afresh. A
+  corrected request after a refusal goes through under the same key instead
+  of being refused as a reused key.
+- **Response headers and cookies are written through the context.**
+  `ctx.setResponseHeader(key, value)`, `ctx.addResponseHeader(key, value)`,
+  `ctx.setCookie(name, value, options?)` and `ctx.clearCookie(name,
+  options?)` (the type `LambderResponseTools`) are on every context: routes,
+  API handlers, hooks, and mock handlers alike. `res.setHeader`,
+  `res.addHeader`, `res.setCookie` and `res.clearCookie` are removed. The
+  writers say "Response" because `ctx.header(name)` reads a request header.
+- **The log channel is `ctx.logList`.** `res.logToApiResponse(entry)` is
+  removed; push the entry onto `ctx.logList`, which the mock's context has
+  always had.
+- **Answer compression is declared per API.** `addApi` and `addSessionApi`
+  take `compress?: boolean | "auto"` beside the other options: "auto" (the
+  default) compresses for an accepting caller when the body is large enough,
+  false never (an answer carrying base64 bytes), true always. It covers
+  refusals and replayed answers too, and is a transport setting of the
+  server, not part of the contract. `res.apiBinary()` and the per-answer
+  response options of an API handler (status code, compression, cache
+  headers) are removed; a header goes through `ctx.setResponseHeader`.
+- **`res.api()` writes an envelope by hand, for code outside an API
+  handler.** A hook, the input validation handler or a global error handler
+  answering an API call still uses it; the payload goes out as given. The
+  typed overloads and `LambderResolver`'s output type parameter are removed,
+  with the types `LambderResolverApiMethod` and `LambderApiNullAnswerConfig`.
+  A binary or file answer is a route's job.
+
+### Removed
+
+- **The `message` envelope channel.** The untyped `message` field of the
+  envelope and of `LambderApiResponseConfig`, `LambderCaller`'s
+  `messageHandler` option and per-call override, and the mock's
+  `ctx.envelope`. What a success says belongs in the output schema, where it
+  is typed and parsed.
+
+### Added
+
+- `LambderResponseTools`, the type of the four response writers every
+  context carries, exported from `lambder`.
+
+## [8.3.1] - 2026-09-27
+
+Six additions, each a thing an app otherwise writes for itself once per kind
+of token, secret, retry loop, copied declaration or store: signed claims
+tokens, one-shot secrets over a store that settles their races, the declared
+API options as generated files of plain data, a backoff timer, the digest and
+random secret behind stored secrets, and the store conformance suites for a
+store an app writes over its own database. Nothing changes on the wire, and
+every existing option keeps its meaning.
+
+### Added
+
+- **`writeApiOptions` in `lambder/build`: the declared options as a generated
+  file.** The contract carries every API's `guards`, `rateLimit` and
+  `idempotency` options as types; code that decides something at runtime with
+  them (a mock restating the server's policies, a test walking the public
+  surface, a screen asking which permission an endpoint needs) copied them by
+  hand and held the copies honest with tests that read the source.
+  `writeApiOptions({ module, exportName, file, check })` writes them once, as
+  three `as const` tables of plain data (`apiOptions`, `rateLimitPolicies`,
+  `guardDeclarations`) from the new `lambder.apiOptionEntries()`, sorted by
+  name, and `check: true` fails a stale file naming what moved per table.
+  Nothing in the file is code: a guard parameter that is not plain data fails
+  the write by API name, a policy keyed by a handler is written as `per:
+  "custom"` and no more, and a guard's schema as its input mode alone.
+  - Readers in `lambder/client`, typed to the tables' literals:
+    `LambderApisWithGuard`, `LambderApisGuardedBy`, `LambderApisWithMode`,
+    `LambderGuardParamOf` and `apiGuardParam(apiOptions, name, guard)`.
+  - `writeApiGuardParams({ module, exportName, guard, file, check })` writes
+    one guard's parameters beside it, as an `as const` table (`guardParams`)
+    of the APIs that declare the guard and what each gives it, with nothing
+    else about any API and no import: the least a browser gating a screen on
+    that guard needs, where importing `apiOptions` as a value would ship
+    every endpoint name and every guard's parameter, reasons included.
+  - `lambderMockPoliciesFrom(rateLimitPolicies, { keys })` in `lambder/mock`
+    rebuilds the policy configs `create()` takes from the table, requiring a
+    key handler for exactly the custom-keyed policies; `create()` takes a
+    `guardDeclarations` option that holds each mock guard to the server
+    guard's input mode and session requirement (`LambderMockGuardShapeOf`);
+    and an `apiOptions` option, the table itself, from which every entry's
+    guards, rate limit and idempotency are read. Given it, an entry is its
+    handler alone, a restated option is a compile error and a throw, the
+    table must cover the contract under each endpoint's mode
+    (`LambderMockApiOptionsCover`), and a `restNotMocked` answer runs under
+    the mode the table gives the name, so an unmocked session endpoint reads
+    the session first.
+  - The entry types `LambderApiOptionEntries`, `LambderApiOptionEntry`,
+    `LambderRateLimitPolicyEntry` and `LambderGuardDeclarationEntry` live in
+    `shared/wire`, with `LambderGuardRunAt`, `LambderRateLimitBudget` and
+    `LambderRateLimitChargeAt`, which moved down there unchanged.
+
+  See [the options as a generated file](./docs/apis.md#the-options-as-a-generated-file).
+
+- **`LambderSignedClaims`: signed tokens that are their own record.** One
+  instance per kind of token, built once with the secret, a version and the
+  zod schema of its claims; `sign(claims)` writes `<version>.<base64url
+  claims>.<base64url HMAC-SHA256>`, `verify(token, { now? })` answers the
+  claims or null for a forged, foreign, malformed, refused or expired token
+  alike. An optional `exp` claim in epoch seconds is judged on every verify,
+  against an injectable clock. WebCrypto only, exported from `lambder` and
+  `lambder/client` for the edge runtimes and shared backend packages that
+  verify where the secret is at hand. Beside it, `keyedDigest(secret,
+  value)`, the HMAC-SHA256 as base64url a stored secret rests as;
+  `randomSecret(bytes?)`; and `constantTimeEquals`.
+
+- **`LambderOneShotSecrets`: codes and tokens handed out once and taken back
+  once.** The code emailed to an address, the link in an activation mail, the
+  code texted before a document opens, the code read out to pair a device:
+  one life (minted, sent, stored as a digest, tried against, spent), written
+  once, over a `LambderOneShotSecretStore` that settles its races in six
+  methods. An app declares its kinds (a `code` of an alphabet and length with
+  a ceiling on tries, or a `token` redeemed by value: random bytes, or an
+  alphabet's characters for one somebody types) and names, per secret,
+  the scope it proves; `issue(kind, scope, { cooldownSeconds?, meta? })`
+  answers the plaintext exactly once, `redeem(kind, scope, candidate)` and
+  `redeemToken(kind, candidate)` answer `accepted`, `wrong` (with the tries
+  left), `expired`, `exhausted` or `none`, and `retire(scope)` ends what the
+  scope holds. One record is live per scope; a cooldown is a condition on
+  the issuing write; a token's digest is claimed by one scope at a time in
+  that same write, and a secret drawn onto a digest another scope holds is
+  drawn again (up to five times), so two scopes that drew the same short
+  code never redeem each other's; a try is counted in the write that reads
+  the digest; a redemption is a conditional consume.
+  `LambderDdbOneShotSecretStore` keeps a code as one item under `OTS#` in
+  the policy table and a token as two, written in one transaction, and sends
+  a write DynamoDB refused for a concurrent transaction on its item again, up
+  to three times; `LambderMemoryOneShotSecretStore` keeps the same in a map, and
+  `lambderOneShotSecretStoreConformance` holds both, and an app's own store,
+  to one set of rules. The class sits in a new `src/secrets/` layer beside
+  `session/`.
+
+- **`LambderBackoffTimer`: waiting longer after each failure, once.** One
+  pending wait at a time: `retry(run)` and `wait(signal?)` climb a jittered
+  ladder (`baseMs` the shortest wait, `maxMs` the longest, `factor`,
+  `jitter`), `after(ms, run)` waits off
+  it, `reset()` and `cancel()`; `wait` rejects with the signal's reason on
+  abort and with an Error when dropped, so an await on it always settles.
+  Exported from `lambder` and `lambder/client`.
+
+  See [Secrets and retries](./docs/secrets.md).
+
+- **Store conformance suites in `lambder/testing`.** The rules each store
+  interface promises its engine were asserted in Lambder's own test suite,
+  where only Lambder's stores could meet them; a store an app writes over its
+  own database had nothing to hold it to the same rules. They are now
+  exported, one suite per interface: `lambderSessionStoreConformance`,
+  `lambderIdempotencyStoreConformance`, `lambderRateLimiterConformance` and
+  `lambderOneShotSecretStoreConformance`. Each takes the runner's own `it`
+  and `expect` (any jest-style `expect`; Lambder imports no runner) and a
+  `create` that builds a store for one case, handed the case's clock as
+  `now`. The one-shot suite also takes what a store over existing rows needs
+  in place of its defaults: two `scopes` it can hold, the kind it keeps for
+  each shape it holds (`kinds: { code?, token? }`, which decides whether the
+  cases about tries or the ones about digests run), the `meta`, and the
+  `lifetimeSeconds` it derives an expiry from. Among its rules: two issues
+  racing for one scope leave exactly one live record, two scopes racing for
+  one token digest leave it with exactly one, and `attempt` and `consume`
+  name a record by its scope and id together, so a record of another scope
+  is never the one named. Lambder's memory and DynamoDB stores run through
+  the same suites.
+
+  See [A store of your own](./docs/testing.md#a-store-of-your-own).
+
+### Changed
+
+- **`LambderUploadRunner` waits on a `LambderBackoffTimer` between tries at
+  storage.** The ladder is the timer's: each wait is `baseDelayMs` plus a
+  random share of a ceiling that starts at `baseDelayMs` and doubles per
+  failed attempt, the whole never past `maxDelayMs`. The first wait is
+  unchanged (between the base and twice it); a later one may be shorter than
+  before, since the ceiling now counts from the base rather than from twice
+  it.
+- **The session crypto shares its HMAC and its constant-time comparison** with
+  the new module through `shared/util/LambderTextDigest.ts` rather than
+  keeping copies of its own. Behaviour is unchanged.
+
 ## [8.1.2] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -17,15 +17,17 @@ const lambder = initLambder<SessionData>().create({
 }).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)));
+}, async ({ apiPayload }) => await loadCompany(apiPayload.slug));
 
 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.
+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
+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:
@@ -113,10 +115,10 @@ The package ships five entry points; pick by where the code runs:
 | Entry | Runs in | Carries |
 | --- | --- | --- |
 | `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/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `LambderUploadRunner`, `LambderBackoffTimer`, `LambderSignedClaims`, `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 |
+| `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; the store conformance suites, to hold a store you write to the rules Lambder's own meet |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters and nothing else, what a browser gating on that guard carries; `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
@@ -126,14 +128,15 @@ tree-shaking.
 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/`
+`src/session/` (the session manager, controller and crypto), `src/secrets/`
+(one-shot secrets over their store), `src/stores/`
 (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), `src/testing/` (the test app),
+transport), `src/mock/` (the mock runtime), `src/testing/` (the test app and the store conformance suites),
 `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
+format both sides speak, `contracts/` for the six store and source
 interfaces, `transport/` for the caller-to-server seam, and `util/` for
 helpers).
 Directories are layers and imports only ever point down;
@@ -152,11 +155,11 @@ guide that matches what you are building. The full index lives in
 | [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
 | [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 |
+| [Responses](./docs/responses.md) | The render context and its response tools (headers, cookies, log entries), the response builder routes and hooks use, 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 |
 | [Calling another lambda](./docs/invoke.md) | `LambderInvokeCaller`: invoking a Lambder app in another function, its contract, failures and compression |
-| [Testing](./docs/testing.md) | `lambderTestApp`: the real instance under test with no HTTP and no AWS, visitors, sign-in without a login endpoint, outcome assertions, crashes, time |
+| [Testing](./docs/testing.md) | `lambderTestApp`: the real instance under test with no HTTP and no AWS, visitors, sign-in without a login endpoint, outcome assertions, crashes, time, store conformance suites |
 | [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` |
@@ -184,25 +187,14 @@ framework:
 ## Versioning and changes
 
 Released versions and what each one changed are in
-[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.
+[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. 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.
 
 ## Contributing
 

package/dist/api/LambderApiCallContext.d.ts

@@ -1,5 +1,6 @@
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { type LambderCookieOptions, type LambderClearCookieOptions } from "../shared/wire/LambderCookie.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
@@ -12,7 +13,7 @@ import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
  * - `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).
+ *   (`ctx.logList.push(entry)` from a handler).
  */
 export type LambderApiCallContext<TSessionData = any> = {
     session: LambderSessionRecord<TSessionData> | null;
@@ -22,6 +23,35 @@ 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 a handler writes onto its answer beside the body: headers and cookies,
+ * collected on `responseHeaders` and applied to whatever answer the request
+ * ends with. On every context a handler receives, the server's and the
+ * mock's alike, since an API handler returns its output and has no response
+ * builder to write them on.
+ */
+export type LambderResponseTools = {
+    /** Replaces a response header. */
+    setResponseHeader(key: string, value: string | string[]): void;
+    /** Appends a response header value (repeatable for one key). */
+    addResponseHeader(key: string, value: string): void;
+    /**
+     * Adds a Set-Cookie header. A function-form `domain` is resolved against
+     * the request host. Defaults: Path=/, SameSite=Lax, Secure, not HttpOnly,
+     * browser-session lifetime.
+     */
+    setCookie(name: string, value: string, options?: LambderCookieOptions): void;
+    /**
+     * Adds a Set-Cookie header that deletes the cookie. Pass the `domain` and
+     * `path` it was set with: a cookie's identity is (name, domain, path), and
+     * a deletion under another scope deletes nothing.
+     */
+    clearCookie(name: string, options?: LambderClearCookieOptions): void;
+};
+/** The response tools of one context, writing into its own responseHeaders; `host` resolves a function-form cookie domain. */
+export declare const responseToolsOf: (ctx: {
+    responseHeaders: LambderAnswerHeaders;
+}, host: string) => LambderResponseTools;
 /**
  * Binds an adapter's tools onto one call context: `getters` run when read
  * (`ctx.sessionController` is built over the object it was read from),

package/dist/api/LambderApiCallContext.js

@@ -1,4 +1,5 @@
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { serializeCookie, serializeClearCookie } from "../shared/wire/LambderCookie.js";
 /** A fresh call context: no session, no guard data, nothing pending. */
 export const createApiCallContext = () => ({
     session: null,
@@ -10,6 +11,13 @@ export const createApiCallContext = () => ({
     responseHeaders: new LambderAnswerHeaders(),
     logList: [],
 });
+/** The response tools of one context, writing into its own responseHeaders; `host` resolves a function-form cookie domain. */
+export const responseToolsOf = (ctx, host) => ({
+    setResponseHeader: (key, value) => { ctx.responseHeaders.set(key, value); },
+    addResponseHeader: (key, value) => { ctx.responseHeaders.add(key, value); },
+    setCookie: (name, value, options) => { ctx.responseHeaders.add("Set-Cookie", serializeCookie(name, value, options, host)); },
+    clearCookie: (name, options) => { ctx.responseHeaders.add("Set-Cookie", serializeClearCookie(name, options, host)); },
+});
 /**
  * Binds an adapter's tools onto one call context: `getters` run when read
  * (`ctx.sessionController` is built over the object it was read from),

package/dist/api/LambderApiDefinition.d.ts

@@ -8,8 +8,8 @@ import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRate
  * because the mock has none; when input is present, validation runs and the
  * 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.
+ * against; the server also parses every output a handler returns through it
+ * before it is sent.
  */
 export type LambderApiDefinition = {
     name: string;

package/dist/api/LambderApiEnvelope.d.ts

@@ -13,7 +13,7 @@ export type LambderApiEnvelopeConfig = LambderApiResponseConfig & {
  * 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>;
+export declare const buildApiEnvelope: <T>(apiVersion: string | null | undefined, payload: T | null, { versionExpired, sessionExpired, notAuthorized, 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;

package/dist/api/LambderApiEnvelope.js

@@ -4,8 +4,8 @@ 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(), the mock runtime and the pipeline all build through these
+ * 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
  * functions, so server and mock cannot drift on a single byte of the wire
  * format. Pure: no Node built-ins, no response classes.
  */
@@ -15,7 +15,7 @@ export const API_ANSWER_CONTENT_TYPE = "application/json; charset=utf-8";
  * 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, } = {}) => ({
+export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionExpired, notAuthorized, errorMessage, logList, crash, } = {}) => ({
     apiVersion: apiVersion ?? null,
     payload,
     ...(versionExpired ? { versionExpired } : {}),
@@ -26,7 +26,6 @@ export const buildApiEnvelope = (apiVersion, payload, { versionExpired, sessionE
     // 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: refusalMessageOf(errorMessage) } : {}),
     ...(crash !== undefined ? { crash } : {}),
     ...(logList?.length ? { logList } : {}),

package/dist/api/LambderApiGuards.d.ts

@@ -37,22 +37,8 @@ type LambderGuardAnswerCheck<TOutput> = [
 type LambderGuardOf<TOutput, TGuard> = LambderGuardAnswerCheck<TOutput> extends LambderGuardMustNotAnswer ? LambderGuardMustNotAnswer : TGuard;
 /** One guard handler: the adapter's context, the validated input slice (undefined in the no-input mode), and the per-API parameter. */
 type LambderGuardHandler<TCtx, TPayload, TParam, TOutput> = (ctx: TCtx, payload: TPayload, param: TParam) => TOutput | Promise<TOutput>;
-/**
- * When a guard runs, relative to the API's input validation.
- *
- * - "beforeInputValidation" (default): an unauthorized caller learns nothing
- *   about the input, and no async refinement in the schema runs for it.
- * - "afterInputValidation": for a guard that spends something on the
- *   request, such as a single-use captcha token, which a request refused for
- *   a mistyped field would otherwise waste. The API's input schema then runs
- *   for callers this guard would refuse, so keep lookups (an "email is free"
- *   refinement) out of it, in the handler.
- *
- * Guards run in their declared order within each, and the limits keyed by
- * caller data are charged after both unless their policy says otherwise
- * (LambderRateLimitChargeAt).
- */
-export type LambderGuardRunAt = "beforeInputValidation" | "afterInputValidation";
+import type { LambderGuardRunAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderGuardRunAt };
 /** Where in the call a guard runs: see LambderGuardRunAt. */
 export type LambderGuardPlacement = {
     /** Default: "beforeInputValidation". */
@@ -331,4 +317,3 @@ export declare class LambderApiGuardsEngine {
      */
     run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace, runAt: LambderGuardRunAt): Promise<void>;
 }
-export {};

package/dist/api/LambderApiIdempotency.js

@@ -386,13 +386,11 @@ export class LambderApiIdempotencyEngine {
             }
             // A crash or a thrown refusal (LambderApiRefusal, refuse())
             // releases the claim so a retry retries. The rule is deliberate:
-            // ANSWERS are stored and replayed, returned refusal envelopes
-            // included; EXCEPTIONS are not, so a thrown refusal re-executes
-            // on retry and the handler decides afresh. (On the server,
-            // res.die.api() is an answer: the adapter catches it before it
-            // reaches here.) The handler's own error is what gets rethrown,
-            // since a cleanup error in its place would hide why the call
-            // failed.
+            // ANSWERS (the output a handler returned) are stored and
+            // replayed; EXCEPTIONS are not, so a thrown refusal re-executes
+            // on retry and the handler decides afresh. The handler's own
+            // error is what gets rethrown, since a cleanup error in its place
+            // would hide why the call failed.
             try {
                 await store.abandon(scopeKey, ownerToken);
             }

package/dist/api/LambderApiRateLimits.d.ts

@@ -78,34 +78,8 @@ export type LambderRateLimitKeyBuilder<TCtx> = {
 export declare const lambderRateLimitKeyBuilder: <TCtx>() => LambderRateLimitKeyBuilder<TCtx>;
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
 export type LambderRateLimitPer<TCtx = any> = "ip" | "session" | LambderRateLimitKeyFn<any, TCtx>;
-/**
- * What one budget spans:
- *
- * - "perApi" (default): every API referencing the policy gets its own
- *   counter, so the windows are a per-API ceiling (three APIs referencing a
- *   60/min policy allow one subject 180/min in total). An API may tune the
- *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
- * - "perPolicy": every API referencing the policy shares ONE counter, so the
- *   windows are one combined budget (e.g. one per-email allowance across
- *   send, register, and reset). The policy IS the group: to give user APIs
- *   and report APIs separate shared budgets, declare two policies.
- */
-export type LambderRateLimitBudget = "perApi" | "perPolicy";
-/**
- * When a custom-keyed policy is charged, relative to the guards and the input
- * schema.
- *
- * - "afterGuards" (default): after every guard and the input schema passed.
- *   The key is a value the caller chose (an email in the payload), so a
- *   caller who never passes a captcha guard cannot spend a victim's budget
- *   and lock them out of reset, register and send-code.
- * - "beforeGuards": before the guards and the input schema, so an attempt
- *   they refuse is counted too. For a limit on guessing a secret a guard or
- *   the schema checks (a one-time code checked by a guard, keyed per email):
- *   charged after them, a wrong guess is refused before it is ever counted.
- *   Pair it with an IP limit, since anyone may spend this budget.
- */
-export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
+import type { LambderRateLimitBudget, LambderRateLimitChargeAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderRateLimitBudget, LambderRateLimitChargeAt };
 /**
  * A named rate-limit policy: fixed windows, the key one counter tracks, and
  * what one budget spans.
@@ -357,4 +331,3 @@ export declare class LambderApiRateLimitsEngine {
      */
     private requestKeyOf;
 }
-export {};

package/dist/build/generatedTables.d.ts

@@ -0,0 +1,72 @@
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
+import { type LambderModuleLocation } from "./moduleLocation.js";
+/** What the generators read the options from: a Lambder instance, or anything else that reports them the same way. */
+export type LambderApiOptionsSource = {
+    apiOptionEntries(): LambderApiOptionEntries;
+};
+/** Which names of one table moved: entries that changed, entries the file did not have, entries the file had and the instance no longer reports. */
+export type LambderNameChanges = {
+    changed: string[];
+    added: string[];
+    removed: string[];
+};
+/** Imports the module, finds the instance under its export, and answers what it reports. `generator` names the caller in the errors. */
+export declare const loadApiOptionEntries: (location: {
+    module: LambderModuleLocation;
+    exportName?: string;
+}, generator: string) => Promise<LambderApiOptionEntries>;
+/** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
+export declare const readGeneratedTable: (contents: string, exportName: string) => Record<string, unknown> | null;
+/** How one table's entries differ from the ones a file held, by name, compared as canonical JSON so key order is not a change. */
+export declare const nameChangesOf: (current: Record<string, unknown>, previous: Record<string, unknown>) => LambderNameChanges;
+/** The opening comment of a generated file, one `//` line per line of the header. */
+export declare const headerLinesOf: (header: string) => string[];
+/**
+ * One table as a statement: its doc comment, the `// prettier-ignore` that
+ * keeps a formatter off the JSON a check reads back, and the table itself,
+ * `as const` with whatever `satisfies` clause the caller gives.
+ */
+export declare const tableStatementLines: (table: {
+    name: string;
+    doc: string;
+    value: unknown;
+    satisfies?: string;
+    semicolon: string;
+}) => string[];
+/**
+ * The end of a generator's run. With `check`, it answers whether the file
+ * holds what the instance reports and writes nothing. Otherwise it writes
+ * the file unless it already holds these tables, however it is formatted, so
+ * a watcher or an incremental build sees no change where there is none (a
+ * change of header or semicolons shows the next time a table changes).
+ * Either way the lines say what moved.
+ */
+export declare const settleGeneratedFile: (run: {
+    /** The file as the caller named it, for the lines. */
+    name: string;
+    /** The absolute path. */
+    file: string;
+    check: boolean | undefined;
+    /** The file's text before this run, or null when there was none. */
+    previousText: string | null;
+    /** Whether that text held the tables as written; false for a file rewritten by hand. */
+    readBack: boolean;
+    /** Each table the file holds, under its exported name: how many entries it has now, and which of them moved. */
+    tables: readonly {
+        name: string;
+        count: number;
+        changes: LambderNameChanges;
+    }[];
+    /** What the tables hold, for the lines: "6 APIs, 4 policies, 5 guards". */
+    held: string;
+    /** What the file holds when it is as written, for the line when it is not: "the three tables". */
+    tablesNoun: string;
+    /** The line when nothing moved: "no options changed". */
+    unmovedLine: string;
+    /** The file's contents, rendered only when it is written. */
+    render: () => string;
+}) => {
+    ok: boolean;
+    written: boolean;
+    lines: string[];
+};