lambder 9.0.2 → 10.0.1

package/dist/api/LambderApiGuards.d.ts

@@ -3,6 +3,8 @@ import type { z } from "zod";
 import type { LambderApiRequest } from "./LambderApiRequest.js";
 import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiMode, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
+import type { LambderDeclaredRefuse } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderHandlerRefusalsOf, type LambderRefusalDeclaration } from "./LambderApiRefusals.js";
 import type { LambderGuardsOptionValue } from "../shared/wire/LambderApiOptionValues.js";
 import { LAMBDER_RESPONSE_BRAND } from "../shared/util/LambderResponseBrand.js";
 /**
@@ -44,6 +46,16 @@ export type LambderGuardPlacement = {
     /** Default: "beforeInputValidation". */
     runAt?: LambderGuardRunAt;
 };
+/**
+ * The refusal codes a guard may refuse with, from the app's vocabulary (the
+ * `refusals` option at creation). They join the codes of every API that
+ * declares the guard, so each such API's contract lists them and its callers
+ * narrow on them. Checked against the vocabulary at creation, since a guard
+ * is built before the instance that knows it.
+ */
+export type LambderGuardRefusals<TRefusals extends readonly string[] = readonly string[]> = {
+    refusals?: TRefusals;
+};
 /**
  * A named guard, run before the API's own input validation unless it says
  * otherwise (LambderGuardPlacement). Three input modes:
@@ -85,7 +97,7 @@ export type LambderGuardPlacement = {
  * the builder's binding: a server guard would compile into a mock guards map
  * and read `ctx.ip` as undefined, authorizing or refusing everything.
  */
-export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any, TCtx = any, TSessionCtx = TCtx> = LambderGuardPlacement & ({
+export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any, TCtx = any, TSessionCtx = TCtx> = LambderGuardPlacement & LambderGuardRefusals & ({
     apiInput: TInput;
     guardInput?: undefined;
     session: true;
@@ -116,65 +128,97 @@ export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any,
     session?: false;
     handler: LambderGuardHandler<TCtx, undefined, TParam, TOutput>;
 });
+/**
+ * The refuse a guard's handler context carries when the guard is built from
+ * an init with a declared vocabulary: typed to the guard's own refusals,
+ * with data required where a code declares it, and never uncoded where the
+ * app requires codes. A builder with no vocabulary type (the standalone
+ * lambderGuard, the mock's) adds nothing to the context.
+ */
+type LambderGuardRefuse<TVocabulary, TRefusals extends readonly string[], TCodesRequired extends boolean> = [
+    TVocabulary
+] extends [never] ? unknown : {
+    refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<TVocabulary, TRefusals[number] & keyof TVocabulary & string>, TCodesRequired>;
+};
+/**
+ * A guard's refusals against the vocabulary of the init that builds it: a
+ * code the vocabulary does not hold is refused on the `refusals` option, and
+ * an init that declared no vocabulary refuses every code. A builder with no
+ * vocabulary type checks nothing here; create() checks the guard against the
+ * vocabulary then.
+ */
+type LambderGuardRefusalsKnownIn<TVocabulary, TRefusals extends readonly string[]> = [
+    TVocabulary
+] extends [never] ? unknown : [Exclude<TRefusals[number], keyof TVocabulary & string>] extends [never] ? unknown : {
+    refusals: readonly (keyof TVocabulary & string)[];
+};
 /**
  * The builder's shape, generic over the two context types a guard may
  * receive: the plain one and the session-typed one. Ties the handler's
  * payload, context, param, and output types together inside one literal
  * and returns the exact shape so type extraction (mode, session, param,
  * output) works downstream. The param type is inferred from the handler's
- * 3rd argument annotation; the output from its return type.
+ * 3rd argument annotation; the output from its return type. TVocabulary is
+ * the app's refusal vocabulary where the init declared one, which types the
+ * handler's ctx.refuse and checks the guard's refusals option.
  */
-export type LambderGuardBuilder<TCtx, TSessionCtx> = {
-    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+export type LambderGuardBuilder<TCtx, TSessionCtx, TVocabulary = never, TCodesRequired extends boolean = false> = {
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         apiInput: TInput;
         session: true;
-        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        handler: (ctx: TSessionCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         apiInput: TInput;
         guardInput?: undefined;
         session: true;
         handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
-    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         apiInput: TInput;
-        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        handler: (ctx: TCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         apiInput: TInput;
         guardInput?: undefined;
         session?: undefined;
         handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
-    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         guardInput: TInput;
         session: true;
-        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        handler: (ctx: TSessionCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         guardInput: TInput;
         apiInput?: undefined;
         session: true;
         handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
-    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         guardInput: TInput;
-        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        handler: (ctx: TCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         guardInput: TInput;
         apiInput?: undefined;
         session?: undefined;
         handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
-    <TParam = undefined, TOutput = void>(guard: {
+    <TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         session: true;
-        handler: (ctx: TSessionCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        handler: (ctx: TSessionCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         apiInput?: undefined;
         guardInput?: undefined;
         session: true;
         handler: (ctx: TSessionCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
     }>;
-    <TParam = undefined, TOutput = void>(guard: {
-        handler: (ctx: TCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    <TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
+        handler: (ctx: TCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        refusals?: TRefusals;
         apiInput?: undefined;
         guardInput?: undefined;
         session?: undefined;
@@ -187,7 +231,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
  * binds it to its own handler contexts, so mock guards are the same shape
  * as server guards and run through the same engine.
  */
-export declare const lambderGuardBuilder: <TCtx, TSessionCtx>() => LambderGuardBuilder<TCtx, TSessionCtx>;
+export declare const lambderGuardBuilder: <TCtx, TSessionCtx, TVocabulary = never, TCodesRequired extends boolean = false>(vocabulary?: ReadonlyMap<string, LambderRefusalDeclaration> | null) => LambderGuardBuilder<TCtx, TSessionCtx, TVocabulary, TCodesRequired>;
 /** The param type a guard's handler declares as its 3rd argument; undefined for paramless guards. */
 type LambderGuardParamOf<G> = G extends {
     handler: (...args: infer A) => any;
@@ -218,7 +262,12 @@ export type LambderGuardMeta<G> = (G extends {
 } : {}) & {
     param: LambderGuardParamOf<G>;
     output: LambderGuardOutputOf<G>;
+    refusals: LambderGuardRefusalNamesIn<G>;
 };
+/** The refusal codes a built guard declares, as a union; never for a guard that declares none. */
+type LambderGuardRefusalNamesIn<G> = G extends {
+    refusals?: infer R;
+} ? (NonNullable<R> extends readonly (infer N extends string)[] ? N : never) : never;
 export type LambderGuardMetaMap<TGuards> = {
     [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
 };
@@ -290,6 +339,12 @@ type GuardInputsEntries<TGuards, TOpt> = {
 };
 /** The guardInputs map an API's contract requires clients to send; never when no declared guard uses guardInput mode. */
 export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
+/** The refusal codes an API's declared guards add to its own: a union of code names, never when none of them declares any. */
+export type LambderGuardRefusalNamesOf<TGuards, TOpt> = {
+    [K in LambderGuardNamesIn<TOpt> & keyof TGuards]: TGuards[K] extends {
+        refusals: infer R;
+    } ? R : never;
+}[LambderGuardNamesIn<TOpt> & keyof TGuards];
 /** Normalize the three guards-option forms into ordered { name, param } entries. Read by the engine, and by the signature digest for the names alone. */
 export declare const toGuardEntries: (value?: LambderGuardsOptionValue) => {
     name: string;

package/dist/api/LambderApiGuards.js

@@ -1,4 +1,5 @@
 import { parsePreflightSlice } from "./LambderApiValidationRefusal.js";
+import { assertRefusalCodesDeclared } from "./LambderApiRefusals.js";
 import { LAMBDER_RESPONSE_BRAND, isLambderResponseLike } from "../shared/util/LambderResponseBrand.js";
 /**
  * A guard builder bound to a pair of context types. The server's
@@ -6,7 +7,14 @@ import { LAMBDER_RESPONSE_BRAND, isLambderResponseLike } from "../shared/util/La
  * binds it to its own handler contexts, so mock guards are the same shape
  * as server guards and run through the same engine.
  */
-export const lambderGuardBuilder = () => ((guard) => guard);
+export const lambderGuardBuilder = (vocabulary) => ((guard) => {
+    // An init's builder knows the vocabulary (null: the init declared
+    // none) and refuses a guard naming a code outside it as it is built.
+    // The standalone builder passes nothing, and create() checks then.
+    if (vocabulary !== undefined)
+        assertRefusalCodesDeclared("a guard", Array.isArray(guard.refusals) ? guard.refusals : [], vocabulary);
+    return guard;
+});
 /** Normalize the three guards-option forms into ordered { name, param } entries. Read by the engine, and by the signature digest for the names alone. */
 export const toGuardEntries = (value) => {
     if (value === undefined)
@@ -64,6 +72,10 @@ export class LambderApiGuardsEngine {
                 throw new Error(`Lambder: guard "${name}" has no handler function.`);
             if (guardDef.apiInput && guardDef.guardInput)
                 throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
+            const refusals = guardDef.refusals;
+            if (refusals !== undefined && (!Array.isArray(refusals) || refusals.some((code) => typeof code !== "string" || code === ""))) {
+                throw new Error(`Lambder: guard "${name}" has a refusals option that is not a list of refusal codes.`);
+            }
             const runAt = guardDef.runAt;
             if (runAt !== undefined && runAt !== "beforeInputValidation" && runAt !== "afterInputValidation") {
                 throw new Error(`Lambder: guard "${name}" has runAt "${String(runAt)}"; use "beforeInputValidation" (default) or "afterInputValidation".`);

package/dist/api/LambderApiIdempotency.js

@@ -77,7 +77,7 @@ const isReplayableAnswer = (answer) => answer.statusCode < 500
  */
 const keyReusedRefusal = (apiName) => new LambderApiRefusal(`Idempotency key reused for a different request to "${apiName}".`, {
     statusCode: 409,
-    errorMessage: {
+    refusal: {
         type: "error",
         code: LAMBDER_REFUSAL_CODES.idempotencyKeyReused,
         content: "This request key was already used for a different request. Start the operation again.",
@@ -110,7 +110,7 @@ const requestFingerprintOf = async (payload) => {
         const content = "Invalid request payload: nested too deep to fingerprint.";
         throw new LambderApiRefusal(content, {
             statusCode: 400,
-            errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidRequestPayload, content },
+            refusal: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidRequestPayload, content },
         });
     }
     try {
@@ -193,7 +193,7 @@ export class LambderApiIdempotencyEngine {
             const content = `Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`;
             throw new LambderApiRefusal(content, {
                 statusCode: 400,
-                errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidIdempotencyKey, content },
+                refusal: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidIdempotencyKey, content },
             });
         }
         return rawKey;
@@ -311,7 +311,7 @@ export class LambderApiIdempotencyEngine {
         if (begun.state === "pending") {
             throw new LambderApiRefusal(`Duplicate request for "${apiName}": the original is still processing.`, {
                 statusCode: 409,
-                errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.duplicateInFlight, content: "This request is already being processed." },
+                refusal: { type: "warning", code: LAMBDER_REFUSAL_CODES.duplicateInFlight, content: "This request is already being processed." },
             });
         }
         // The other replay path: the original settled between this request's

package/dist/api/LambderApiOutputValidationError.d.ts

@@ -4,9 +4,11 @@ import { z } from "zod";
  * the declared shape, so the payload was not sent and the call is answered
  * as a crash. Either the schema rejected the payload, or the parse threw: an
  * async refinement or transform (the output is parsed synchronously, so an
- * output schema cannot be async), or a transform that threw. The output
- * side's counterpart of LambderApiValidationRefusal, with the API it happened
- * in, for a crash reporter.
+ * output schema cannot be async), or a transform that threw. Or the parsed
+ * output is not an object or an array, which every answer is (see
+ * isObjectPayload). The output side's counterpart of
+ * LambderApiValidationRefusal, with the API it happened in, for a crash
+ * reporter.
  *
  * Its own class because it is a crash after the fact: the handler ran to
  * its answer, whatever it wrote or charged along the way included. The
@@ -22,11 +24,15 @@ export declare class LambderApiOutputValidationError extends Error {
     readonly zodError: z.ZodError | null;
     /**
      * `failure` is how the parse ended: `{ zodError }` when the schema
-     * rejected the payload, `{ thrown }` when parsing it threw.
+     * rejected the payload, `{ thrown }` when parsing it threw, `{ notObject }`
+     * when what it produced is not an object or an array (the kind named, the
+     * value never).
      */
     constructor(apiName: string, failure: {
         zodError: z.ZodError;
     } | {
         thrown: unknown;
+    } | {
+        notObject: string;
     });
 }

package/dist/api/LambderApiOutputValidationError.js

@@ -4,9 +4,11 @@ import { z } from "zod";
  * the declared shape, so the payload was not sent and the call is answered
  * as a crash. Either the schema rejected the payload, or the parse threw: an
  * async refinement or transform (the output is parsed synchronously, so an
- * output schema cannot be async), or a transform that threw. The output
- * side's counterpart of LambderApiValidationRefusal, with the API it happened
- * in, for a crash reporter.
+ * output schema cannot be async), or a transform that threw. Or the parsed
+ * output is not an object or an array, which every answer is (see
+ * isObjectPayload). The output side's counterpart of
+ * LambderApiValidationRefusal, with the API it happened in, for a crash
+ * reporter.
  *
  * Its own class because it is a crash after the fact: the handler ran to
  * its answer, whatever it wrote or charged along the way included. The
@@ -22,11 +24,17 @@ export class LambderApiOutputValidationError extends Error {
     zodError;
     /**
      * `failure` is how the parse ended: `{ zodError }` when the schema
-     * rejected the payload, `{ thrown }` when parsing it threw.
+     * rejected the payload, `{ thrown }` when parsing it threw, `{ notObject }`
+     * when what it produced is not an object or an array (the kind named, the
+     * value never).
      */
     constructor(apiName, failure) {
         let message;
-        if ("zodError" in failure) {
+        if ("notObject" in failure) {
+            message = `Lambder: API "${apiName}" answered ${failure.notObject}, and an API answers with an object or an array, `
+                + "so it was not sent. An API with nothing to answer declares `output: z.object({})` and returns `{}`.";
+        }
+        else if ("zodError" in failure) {
             // Paths and messages only: an issue's message names the expected
             // type, and the values themselves stay out of a crash report.
             const issues = failure.zodError.issues.slice(0, 3).map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
@@ -42,7 +50,7 @@ export class LambderApiOutputValidationError extends Error {
             message = `Lambder: API "${apiName}" answered a payload its output schema threw on while parsing it (a transform that threw, `
                 + "or an async step a synchronous parse cannot run), so it was not sent. What the schema threw is the cause.";
         }
-        super(message, { cause: "zodError" in failure ? failure.zodError : failure.thrown });
+        super(message, "notObject" in failure ? undefined : { cause: "zodError" in failure ? failure.zodError : failure.thrown });
         this.name = "LambderApiOutputValidationError";
         this.apiName = apiName;
         this.zodError = "zodError" in failure ? failure.zodError : null;

package/dist/api/LambderApiPipeline.d.ts

@@ -105,7 +105,8 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * Steps whose subsystem is not configured are skipped. A LambderApiRefusal
  * thrown by any step, guard or handler is rendered here, in one place: a
  * validation error through onInvalidInput, any other refusal as the refusal
- * envelope, and a session ended while the handler held it
+ * envelope once checked against the endpoint's declared codes
+ * (checkedRefusal), and a session ended while the handler held it
  * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
  * crash means (a global error handler, a mock event).
  *

package/dist/api/LambderApiPipeline.js

@@ -3,6 +3,7 @@ import { lookupApiSignature } from "../shared/wire/LambderApiSignatureMap.js";
 import { apiNotFoundAnswer, invalidPayloadAnswer, refusalAnswer, sessionExpiredAnswer, validationAnswer, versionExpiredAnswer, } from "./LambderApiEnvelope.js";
 import { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./LambderApiValidationRefusal.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { checkedRefusal } from "./LambderApiRefusals.js";
 import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { compareDottedVersions, isDottedVersion } from "../shared/wire/LambderVersionOrder.js";
@@ -34,7 +35,8 @@ const usesIdempotency = (definition) => definition.idempotency !== undefined &&
  * Steps whose subsystem is not configured are skipped. A LambderApiRefusal
  * thrown by any step, guard or handler is rendered here, in one place: a
  * validation error through onInvalidInput, any other refusal as the refusal
- * envelope, and a session ended while the handler held it
+ * envelope once checked against the endpoint's declared codes
+ * (checkedRefusal), and a session ended while the handler held it
  * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
  * crash means (a global error handler, a mock event).
  *
@@ -242,7 +244,13 @@ export class LambderApiPipeline {
                 answer = await this.refuseInput(err, ctx, request);
             }
             else if (isLambderApiRefusal(err)) {
-                answer = refusalAnswer(err, this.apiVersion, ctx.logList);
+                // Checked against the endpoint's declared codes, and its data
+                // parsed, before it becomes an answer; a refusal the endpoint
+                // may not send throws from here as a crash. By this point the
+                // idempotency engine has already released the claim, as it
+                // does for every thrown refusal: a retry runs the handler
+                // again and decides afresh.
+                answer = refusalAnswer(checkedRefusal(definition.name, definition.refusals, err), this.apiVersion, ctx.logList);
             }
             else if (err instanceof LambderSessionNotFoundError) {
                 // No usable session: it ended while the handler held it (a

package/dist/api/LambderApiRateLimits.d.ts

@@ -1,11 +1,11 @@
 import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
-import type { LambderRateLimitOptionValue, LambderRateLimitOverride } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderRateLimitMessage, LambderRateLimitOptionValue, LambderRateLimitOverride } from "../shared/wire/LambderApiOptionValues.js";
 import type { z } from "zod";
 import type { LambderApiRequest } from "./LambderApiRequest.js";
 import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import { type LambderRateLimiter, type LambderRateLimitExceeded, type LambderRateLimitPolicy } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
-import { LambderApiRefusal, type LambderAppRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
+import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import type { LambderNonEmptyOptionMap } from "../shared/util/LambderTypeUtilities.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
@@ -16,12 +16,16 @@ export declare const DEFAULT_RATE_LIMIT_REFUSAL: {
 };
 /**
  * The refusal a rate-limited call answers with: a 429 envelope carrying the
- * framework code (a policy's own message inherits it unless it sets a more
- * specific one) and a Retry-After header. The engine throws it; the mock
- * runtime's failure injection throws the same one, so an injected rate
- * limit is indistinguishable from a real one.
+ * framework code, whatever message a policy or an API wrote, and a
+ * Retry-After header. The engine throws it; the mock runtime's failure
+ * injection throws the same one, so an injected rate limit is
+ * indistinguishable from a real one.
+ *
+ * The code goes on after the message, so a message that carries one anyway
+ * (a plain-JS caller, a cast) cannot replace it: a rate limit is never a code
+ * an endpoint declares, and the pipeline would refuse to send one it did not.
  */
-export declare const rateLimitRefusal: (detail: string, retryAfterSeconds: number, message?: LambderAppRefusalMessage) => LambderApiRefusal;
+export declare const rateLimitRefusal: (detail: string, retryAfterSeconds: number, message?: LambderRateLimitMessage) => LambderApiRefusal;
 /**
  * A custom rate-limit key. `apiInput` names the fields of the API's OWN
  * payload the key derives from: that slice is validated against the raw
@@ -106,8 +110,8 @@ export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy
      * takes it: `per: "ip"` and `per: "session"` have one place each.
      */
     chargeAt?: LambderRateLimitChargeAt;
-    /** Envelope errorMessage for refused requests; inherits code "lambder/rate-limited" unless it sets its own. Default: a warning saying too many requests. */
-    errorMessage?: LambderAppRefusalMessage;
+    /** The refusal's message for refused requests: its type, title and content, under the code "lambder/rate-limited". Default: a warning saying too many requests. */
+    refusal?: LambderRateLimitMessage;
 };
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
     /** Your limiter instance (LambderDdbRateLimiter, LambderMemoryRateLimiter, or your own); its table and keyPrefix apply as configured on it. */
@@ -188,7 +192,7 @@ export type LambderRateLimitCheckResult = false | (LambderRateLimitExceeded & {
 /**
  * `ctx.rateLimit(policy, key?)`: counts one attempt against a named policy
  * and, when it is over, refuses the request the way a declared limit does (a
- * 429 with Retry-After and the policy's errorMessage). For a limit whose key
+ * 429 with Retry-After and the policy's refusal). For a limit whose key
  * only the handler knows, or one to charge only on some paths through it.
  *
  * The key tuple is NoInfer: left inferable, a key passed where none belongs
@@ -216,7 +220,7 @@ export type LambderRateLimitChargeResult = {
 };
 type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
     budget: "perPolicy";
-} ? Pick<LambderRateLimitOverride, "errorMessage"> : LambderRateLimitOverride;
+} ? Pick<LambderRateLimitOverride, "refusal"> : LambderRateLimitOverride;
 /** The map form's full shape: every referable policy name, each carrying its own override. */
 type LambderRateLimitMap<TPolicies, TPayload, TIncludeSession extends boolean> = {
     readonly [K in LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;

package/dist/api/LambderApiRateLimits.js

@@ -11,16 +11,37 @@ const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
 export const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
 /**
  * The refusal a rate-limited call answers with: a 429 envelope carrying the
- * framework code (a policy's own message inherits it unless it sets a more
- * specific one) and a Retry-After header. The engine throws it; the mock
- * runtime's failure injection throws the same one, so an injected rate
- * limit is indistinguishable from a real one.
+ * framework code, whatever message a policy or an API wrote, and a
+ * Retry-After header. The engine throws it; the mock runtime's failure
+ * injection throws the same one, so an injected rate limit is
+ * indistinguishable from a real one.
+ *
+ * The code goes on after the message, so a message that carries one anyway
+ * (a plain-JS caller, a cast) cannot replace it: a rate limit is never a code
+ * an endpoint declares, and the pipeline would refuse to send one it did not.
  */
 export const rateLimitRefusal = (detail, retryAfterSeconds, message) => new LambderApiRefusal(detail, {
-    errorMessage: message ? { code: LAMBDER_REFUSAL_CODES.rateLimited, ...message } : DEFAULT_RATE_LIMIT_REFUSAL,
+    refusal: message ? { type: message.type, ...(message.title !== undefined ? { title: message.title } : {}), content: message.content, code: LAMBDER_REFUSAL_CODES.rateLimited } : DEFAULT_RATE_LIMIT_REFUSAL,
     statusCode: 429,
     headers: { "Retry-After": String(Math.max(1, Math.floor(retryAfterSeconds))) },
 });
+/**
+ * A rate-limit message carries no code of its own and no data: its code is
+ * always the framework's, which rateLimitRefusal sets, and a code there would
+ * read as one the app chose for clients to branch on when it never reaches
+ * them.
+ */
+const assertRateLimitMessage = (where, message) => {
+    if (message === undefined)
+        return;
+    const { code, data } = message;
+    if (code !== undefined) {
+        throw new Error(`Lambder: ${where} sets a refusal code. A rate-limit refusal is always "${LAMBDER_REFUSAL_CODES.rateLimited}", so an endpoint never has to declare it; write the type, title and content only.`);
+    }
+    if (data !== undefined) {
+        throw new Error(`Lambder: ${where} sets refusal data. A rate-limit refusal carries none.`);
+    }
+};
 /**
  * A key builder bound to a context type, the counterpart of
  * lambderGuardBuilder. The server's lambderRateLimitKey() is this bound to
@@ -143,6 +164,7 @@ export class LambderApiRateLimitsEngine {
                     throw new Error(`Lambder: rate-limit policy "${name}" sets chargeAt, which only a policy keyed by a { apiInput?, handler } key takes: per "ip" and per "session" each run at one fixed place, and a policy without per is charged by the code that names it.`);
                 }
             }
+            assertRateLimitMessage(`rate-limit policy "${name}"`, policy.refusal);
             const budget = policy.budget;
             if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
                 throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
@@ -191,6 +213,8 @@ export class LambderApiRateLimitsEngine {
             }
             if (override)
                 assertWindowLimits(`API "${apiName}" override of rate-limit policy "${name}"`, override);
+            if (override)
+                assertRateLimitMessage(`API "${apiName}" override of rate-limit policy "${name}"`, override.refusal);
             if (override && hasWindowOverride(override) && !RATE_LIMIT_WINDOW_KEYS.some((key) => (override[key] ?? policy[key]))) {
                 throw new Error(`Lambder: API "${apiName}" overrides rate-limit policy "${name}" down to no enforced window, which limits nothing. ` +
                     `A policy is required to declare a window; an override may not take the last one away.`);
@@ -225,7 +249,7 @@ export class LambderApiRateLimitsEngine {
             const limits = windowsOf(policy, override);
             const exceeded = await this.countAttempt(name, trackerKeyOf(name, policy, apiName, key), limits, `API "${apiName}"`);
             if (exceeded) {
-                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, this.retryAfterOf(exceeded), override?.errorMessage ?? policy.errorMessage);
+                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, this.retryAfterOf(exceeded), override?.refusal ?? policy.refusal);
             }
         }
     }
@@ -252,7 +276,7 @@ export class LambderApiRateLimitsEngine {
         const retryAfterSeconds = this.retryAfterOf(exceeded);
         return {
             checkResult: { ...exceeded, retryAfterSeconds },
-            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, policy.errorMessage),
+            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, policy.refusal),
         };
     }
     /**