lambder 7.2.5 → 8.0.2

package/dist/api/LambderApiGuards.d.ts

@@ -14,11 +14,10 @@ type LambderGuardMustNotAnswer = {
     readonly "lambder: a guard authorizes, it does not answer. Say no with refuse() or by throwing a LambderApiRefusal.": never;
 };
 /**
- * Intersected into the builder's parameter so the mistake is reported where
- * it is written, at the lambderGuard() call, rather than further away where
- * the guard is put into a map. An answering handler makes this a required
- * property no object literal can satisfy, and the property name is the
- * message.
+ * Intersected into the builder's parameter so the mistake is reported at the
+ * lambderGuard() call, not later where the guard is put into a map. For an
+ * answering handler this is a required property no object literal can
+ * satisfy, and the property name is the message.
  */
 type LambderGuardAnswerCheck<TOutput> = [
     TOutput
@@ -27,34 +26,50 @@ type LambderGuardAnswerCheck<TOutput> = [
 }>] extends [never] ? unknown : LambderGuardMustNotAnswer;
 /**
  * A built guard, unless its handler answers instead of authorizing. Applied
- * to the builder's RESULT rather than to its parameters, so the handler's
- * unannotated arguments keep taking their types from the overload that
- * matched and only the returned shape changes. A guard that hands back a
- * response denies nothing at runtime (the value would become
- * ctx.guardData[name] and the call would carry on), so it must not reach a
- * guards map: this turns the ordinary spelling of that mistake into a build
- * error, and the engine throws on the ones a cast smuggles past.
- *
- * Defined in terms of LambderGuardAnswerCheck so the two cannot drift: one
- * rule for what counts as answering, read twice.
+ * to the builder's RESULT rather than its parameters, so the handler's
+ * unannotated arguments keep their types from the matching overload. A guard
+ * that returns a response denies nothing at runtime (the value becomes
+ * ctx.guardData[name] and the call carries on), so this makes the ordinary
+ * spelling of that mistake a build error; the engine throws on the ones a
+ * cast smuggles past. Defined via LambderGuardAnswerCheck so there is one
+ * rule for what counts as answering.
  */
 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>;
 /**
- * A named guard, run before the API's own input validation. Three input
- * modes:
+ * 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";
+/** Where in the call a guard runs: see LambderGuardRunAt. */
+export type LambderGuardPlacement = {
+    /** Default: "beforeInputValidation". */
+    runAt?: LambderGuardRunAt;
+};
+/**
+ * A named guard, run before the API's own input validation unless it says
+ * otherwise (LambderGuardPlacement). Three input modes:
  *
  * - `apiInput`: the guard checks fields of the API's OWN payload. The slice
  *   is validated against the raw payload before `handler` runs and handed to
- *   it typed. The API's input schema stays the owner of those fields:
- *   declaring the guard on an API whose schema does not carry them is a
- *   compile error.
+ *   it typed. The API's input schema still owns those fields: declaring the
+ *   guard on an API whose schema lacks them is a compile error.
  * - `guardInput`: the guard has its own value the client sends SEPARATELY,
- *   outside the API payload, via the caller's options.guardInputs[name].
- *   The requirement lands on the API's contract (`guardInputs`), so the
- *   typed caller refuses to compile a call that does not send it. The API
- *   payload and handler never see the value.
+ *   via the caller's options.guardInputs[name]. The requirement lands on the
+ *   API's contract (`guardInputs`), so the typed caller refuses to compile a
+ *   call that omits it. The API payload and handler never see the value.
  * - neither: the guard reads only the context.
  *
  * Orthogonally, a guard may also:
@@ -70,22 +85,21 @@ type LambderGuardHandler<TCtx, TPayload, TParam, TOutput> = (ctx: TCtx, payload:
  *   the API handler's context as `ctx.guardData[guardName]`, fully typed.
  *   Guards that return nothing never appear in guardData.
  *
- * A guard says no by throwing: refuse() or a LambderApiRefusal, which the
- * pipeline renders as the structured refusal envelope. A validation failure
- * of its input slice answers like the API's own input validation (the app's
+ * A guard says no by throwing refuse() or a LambderApiRefusal, rendered as
+ * the structured refusal envelope. A validation failure of its input slice
+ * answers like the API's own input validation (the app's
  * setApiInputValidationErrorHandler when set, else the standard 422). Guards
- * build no responses and hold no resolver, which is what lets the same
- * engine run them on the server and in the mock runtime. Build with
- * lambderGuard() so the handler's payload/ctx/param types line up.
+ * build no responses and hold no resolver, so the same engine runs them on
+ * the server and in the mock runtime. Build with lambderGuard() so the
+ * handler's payload/ctx/param types line up.
  *
  * TCtx and TSessionCtx are the two contexts an adapter runs guards on, and
  * an adapter's guards map pins them (the server's to the render contexts,
- * the mock's to the mock call contexts). Left open, the binding the builder
- * establishes was thrown away at the map: a guard written for the server
- * compiled into a mock guards map and then read `ctx.ip` as undefined, so it
- * authorized or refused everything.
+ * the mock's to the mock call contexts). Left open, the map would discard
+ * 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> = {
+export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any, TCtx = any, TSessionCtx = TCtx> = LambderGuardPlacement & ({
     apiInput: TInput;
     guardInput?: undefined;
     session: true;
@@ -115,7 +129,7 @@ export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any,
     guardInput?: undefined;
     session?: false;
     handler: LambderGuardHandler<TCtx, undefined, TParam, TOutput>;
-};
+});
 /**
  * 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
@@ -129,7 +143,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
         apiInput: TInput;
         session: true;
         handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         apiInput: TInput;
         guardInput?: undefined;
         session: true;
@@ -138,7 +152,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
     <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
         apiInput: TInput;
         handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         apiInput: TInput;
         guardInput?: undefined;
         session?: undefined;
@@ -148,7 +162,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
         guardInput: TInput;
         session: true;
         handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         guardInput: TInput;
         apiInput?: undefined;
         session: true;
@@ -157,7 +171,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
     <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
         guardInput: TInput;
         handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         guardInput: TInput;
         apiInput?: undefined;
         session?: undefined;
@@ -166,7 +180,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
     <TParam = undefined, TOutput = void>(guard: {
         session: true;
         handler: (ctx: TSessionCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         apiInput?: undefined;
         guardInput?: undefined;
         session: true;
@@ -174,7 +188,7 @@ export type LambderGuardBuilder<TCtx, TSessionCtx> = {
     }>;
     <TParam = undefined, TOutput = void>(guard: {
         handler: (ctx: TCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardPlacement & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         apiInput?: undefined;
         guardInput?: undefined;
         session?: undefined;
@@ -196,15 +210,21 @@ type LambderGuardParamOf<G> = G extends {
 type LambderGuardOutputOf<G> = G extends {
     handler: (...args: any[]) => infer R;
 } ? Awaited<R> : never;
-/** Per-guard metadata carried on the Lambder instance: input mode, session requirement, param type, output type. */
+/**
+ * Per-guard metadata carried on the Lambder instance: input mode, session
+ * requirement, param type, output type. The input slices are recorded in
+ * their input form (z.input), which is what a client sends and what an API's
+ * posted payload is compared with; the guard's handler still receives the
+ * parsed form.
+ */
 export type LambderGuardMeta<G> = (G extends {
     apiInput: infer S extends z.ZodType;
 } ? {
-    apiInput: z.output<S>;
+    apiInput: z.input<S>;
 } : G extends {
     guardInput: infer S extends z.ZodType;
 } ? {
-    guardInput: z.output<S>;
+    guardInput: z.input<S>;
 } : {}) & (G extends {
     session: true;
 } ? {
@@ -216,9 +236,16 @@ export type LambderGuardMeta<G> = (G extends {
 export type LambderGuardMetaMap<TGuards> = {
     [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
 };
+/**
+ * The guard name when the API's payload carries the guard's apiInput slice.
+ * The payload is compared whole, not member by member: a bare `TPayload
+ * extends R` would distribute over a union input, so a slice one member
+ * carries would be allowed on an API whose other members lack it, and every
+ * request of those members would be refused by the slice's parse.
+ */
 type LambderGuardNameIfPayloadOk<TGuards, K extends keyof TGuards, TPayload> = TGuards[K] extends {
     apiInput: infer R;
-} ? (TPayload extends R ? K : never) : K;
+} ? ([TPayload] extends [R] ? K : never) : K;
 /**
  * Guard names an API may declare: apiInput-mode guards only when the API's
  * payload carries their fields, session guards only on session APIs.
@@ -285,7 +312,7 @@ export declare const toGuardEntries: (value?: LambderGuardsOptionValue) => {
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared
- * guards during preflight. Composed into LambderApiPolicyEngine. Reads the
+ * guards during preflight. Held by LambderApiPipeline. Reads the
  * request and writes the call context, so it runs unchanged under the
  * server and the mock runtime.
  */
@@ -298,10 +325,10 @@ export declare class LambderApiGuardsEngine {
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName: string, mode: LambderApiMode, guardsOption?: LambderGuardsOptionValue): void;
     /**
-     * Run the API's guards in declared order. Refusals throw; outputs land on
-     * ctx.guardData. Each guard is recorded on the trace as it returns, so a
-     * call that a later guard refused still reports the ones that passed.
+     * Run the API's guards that run at `runAt` (see LambderGuardRunAt) in
+     * declared order. Refusals throw; outputs land on ctx.guardData; the
+     * trace names every guard reached.
      */
-    run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace): Promise<void>;
+    run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace, runAt: LambderGuardRunAt): Promise<void>;
 }
 export {};

package/dist/api/LambderApiGuards.js

@@ -21,42 +21,39 @@ export const toGuardEntries = (value) => {
 };
 /**
  * One guard's input out of the map the client posted. The map is client
- * data, so it is read as data: a guard named for something Object.prototype
- * carries ("toString", "constructor") must come back absent when the client
- * sent nothing, not as the inherited function. Guard names are deliberately
- * unrestricted, which is what makes this the read's problem rather than the
- * name's.
+ * data, so a guard named for something Object.prototype carries
+ * ("toString", "constructor") must read as absent when the client sent
+ * nothing, not as the inherited function. Guard names are deliberately
+ * unrestricted, so the read has to handle this.
  */
 const readGuardInput = (guardInputs, name) => guardInputs !== undefined && Object.prototype.hasOwnProperty.call(guardInputs, name) ? guardInputs[name] : undefined;
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared
- * guards during preflight. Composed into LambderApiPolicyEngine. Reads the
+ * guards during preflight. Held by LambderApiPipeline. Reads the
  * request and writes the call context, so it runs unchanged under the
  * server and the mock runtime.
  */
 export class LambderApiGuardsEngine {
     // A Map, not an object: a plain object answers for "toString" and
     // "constructor" through its prototype, so an API declaring one of those as
-    // a guard name would pass the registration check that exists to catch
-    // exactly that typo, and then fail on every request. It also refuses to
+    // a guard name would pass the registration check meant to catch exactly
+    // that typo and then fail on every request. It would also refuse to
     // register a guard legitimately named one of them.
     guards = new Map();
     /** True once a guards map was configured. */
     get isConfigured() { return this.guards.size > 0; }
     /** Take the guards map given at creation; named like the other two engines' configure(). */
     configure(guards) {
-        // One configuration per instance, the rule the rate-limit and
-        // idempotency engines already hold to: a second map would silently
-        // merge into the first, and which of two same-named guards ran would
-        // depend on the order the calls happened to be made in.
+        // One configuration per instance, as in the rate-limit and idempotency
+        // engines: a second map would silently merge into the first, and which
+        // of two same-named guards ran would depend on call order.
         if (this.guards.size > 0)
             throw new Error("Lambder: guards were already configured.");
-        // Declaring the option is always declaring a guard, the same rule an
-        // API's own `guards: {}` is held to. Without this the engine stays
-        // unconfigured and every API that declares a guard is told that no
-        // guards option was given at all, which sends the reader to the wrong
-        // line.
+        // Declaring the option always declares a guard, the rule an API's own
+        // `guards: {}` is held to. Otherwise the engine stays unconfigured and
+        // every API declaring a guard is told no guards option was given,
+        // which sends the reader to the wrong line.
         if (Object.keys(guards).length === 0) {
             throw new Error("Lambder: the guards option was declared with no guards in it, which configures nothing. Name the guards APIs will declare, or leave the option off.");
         }
@@ -67,18 +64,21 @@ 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 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".`);
+            }
             this.guards.set(name, guardDef);
         }
     }
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName, mode, guardsOption) {
         const entries = toGuardEntries(guardsOption);
-        // The runtime half of LambderNonEmptyGuardsMap. `guards: {}` and
-        // `guards: []` are present-but-empty: they satisfy the require*ApiGuards
-        // field check while running nothing, which is the one shape that turns a
-        // mandatory authorization declaration back into an optional one. The type
-        // rejects both; a plain-JS caller, a cast, or a spread that happened to
-        // produce an empty object lands here instead.
+        // The runtime half of LambderNonEmptyOptionMap on the guards option.
+        // `guards: {}` and `guards: []` would satisfy the require*ApiGuards
+        // field check while running nothing, turning a mandatory authorization
+        // declaration into an optional one. The type rejects both; a plain-JS
+        // caller, a cast, or a spread that produced an empty object lands here.
         if (guardsOption !== undefined && entries.length === 0) {
             throw new Error(`Lambder: API "${apiName}" declares an empty guards option, which authorizes nothing. ` +
                 `Name the guard that authorizes it, or omit the option entirely.`);
@@ -94,29 +94,27 @@ export class LambderApiGuardsEngine {
         }
     }
     /**
-     * Run the API's guards in declared order. Refusals throw; outputs land on
-     * ctx.guardData. Each guard is recorded on the trace as it returns, so a
-     * call that a later guard refused still reports the ones that passed.
+     * Run the API's guards that run at `runAt` (see LambderGuardRunAt) in
+     * declared order. Refusals throw; outputs land on ctx.guardData; the
+     * trace names every guard reached.
      */
-    async run(request, ctx, guardsOption, trace) {
+    async run(request, ctx, guardsOption, trace, runAt) {
         for (const { name, param } of toGuardEntries(guardsOption)) {
             const guardDef = this.guards.get(name);
             if (!guardDef)
                 throw new Error(`Lambder: guard "${name}" is not configured. Declare it in the guards option at creation.`);
-            // Recorded before anything this guard does can refuse, so the list
-            // says which guards were reached and the one that said no is the
-            // last name on it. Recording after the return named every guard
-            // except the one someone reading the trace was looking for; doing
-            // it after the slice parse below had the same effect for a guard
-            // that refuses by rejecting its own input, which answers 422 and
-            // is exactly the refusal a reader is trying to place.
+            if ((guardDef.runAt ?? "beforeInputValidation") !== runAt)
+                continue;
+            // Recorded before anything this guard does can refuse, including
+            // the slice parse below (a guard that rejects its own input answers
+            // 422), so the guard that said no is the last name on the list.
             trace.guardsRun.push(name);
             let payload;
             if (guardDef.apiInput) {
-                payload = parsePreflightSlice(guardDef.apiInput, request.payload);
+                payload = await parsePreflightSlice(guardDef.apiInput, request.payload);
             }
             else if (guardDef.guardInput) {
-                payload = parsePreflightSlice(guardDef.guardInput, readGuardInput(request.guardInputs, name));
+                payload = await parsePreflightSlice(guardDef.guardInput, readGuardInput(request.guardInputs, name));
             }
             // A guard's return value becomes the handler's typed
             // ctx.guardData[name]; check-only guards return undefined.

package/dist/api/LambderApiIdempotency.d.ts

@@ -3,6 +3,7 @@ import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCal
 import type { LambderApiAnswer } from "./LambderApiAnswer.js";
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 export type LambderApiIdempotencyConfig = {
     /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
     store: LambderIdempotencyStore;
@@ -19,53 +20,56 @@ export type LambderApiIdempotencyConfig = {
     /** Skip idempotency (execute normally) when the store errors, instead of failing the request. Default: true. */
     failOpen?: boolean;
     /**
-     * Who a request is acting as, for scoping a PUBLIC API's stored answer.
-     * Session APIs already scope per session, so this only affects the ones
-     * that do not have a session to scope by.
+     * Who a request is acting as, for scoping a PUBLIC API's stored answer
+     * (session APIs already scope per user, by the session's sessionKey).
      *
      * Without it, a public API's scope is the posted key alone, which makes
-     * that key a bearer token for its own stored answer: anyone presenting it
-     * gets the response back, and the replay is served BEFORE guards run, so
-     * an API whose authorization is a guard hands its answer over without the
-     * guard ever being consulted. Returning an identity here puts that caller
-     * in the scope, so a key only replays to whoever it was issued to.
+     * the key a bearer token for its stored answer. The replay is served
+     * BEFORE guards run, so an API authorized by a guard would hand its
+     * answer to anyone holding the key. An identity here puts the caller in
+     * the scope, so a key replays only to whoever it was issued to.
      *
-     * Consulted only on public APIs, and a public API reads no session, so
-     * there is no session here to read: the context arrives without one, and
-     * an identity that came from a session would be the session scope the
-     * engine already applies. It sees what the request itself carries, and
-     * that is the point of it: `request.guardInputs`, `request.payload`,
-     * `request.headers` and `request.ip`.
-     *
-     * Read the credential a guard would check, not a value that changes
-     * between attempts: a single-use token (a captcha) would give the
-     * legitimate retry a different scope and defeat the replay it needs.
-     * Return null for requests with no identity to speak of.
+     * The context arrives without a session (public APIs read none); the
+     * function sees what the request carries: `request.guardInputs`,
+     * `request.payload`, `request.headers` and `request.ip`. Read the
+     * credential a guard would check, not a value that changes between
+     * attempts: a single-use token (a captcha) would give the legitimate
+     * retry a different scope and defeat its replay. Return null for
+     * requests with no identity.
      */
     callerIdentity?: (ctx: Omit<LambderApiCallContext, "session">, request: LambderApiRequest) => string | null | Promise<string | null>;
 };
+/**
+ * A call under an idempotency key: the scope its record lives under, and the
+ * fingerprint of the request as it was posted. Worked out once per call, by
+ * resolveKeyedCall, and handed to the replay lookup and the claim.
+ */
+export type LambderIdempotentCall = {
+    scopeKey: string;
+    fingerprint: string;
+};
 /**
  * Runtime side of the idempotency subsystem: claims a per-operation scope
  * around handler execution, replays stored answers, and settles claims.
- * Composed into LambderApiPolicyEngine. Works on plain answers, so it runs
+ * Held by LambderApiPipeline. Works on plain answers, so it runs
  * unchanged under the server and the mock runtime.
  */
 export declare class LambderApiIdempotencyEngine {
+    /** Stamped on the crash answer the engine records for an answer that broke its output schema. */
+    private readonly apiVersion;
     private store;
     private defaultTtlSeconds;
     private defaultPendingTtlSeconds;
     private failOpen;
     private callerIdentity;
+    constructor(apiVersion: string | null);
+    configure(config: LambderApiIdempotencyConfig): void;
     /**
-     * The scope this call resolved to, keyed by its context, which is the one
-     * object per call the engine is handed. A keyed request asks for it
-     * twice, at the replay lookup and at the claim, and callerIdentity is app
-     * code that may verify a token or read a store: running it twice per
-     * request is a cost the app never asked for, and one it cannot see.
-     * Entries go when the call's context does.
+     * Puts the engine over another store, for `lambder/testing`; the replay
+     * TTLs, failOpen and callerIdentity stay as configured. False when
+     * idempotency was never configured.
      */
-    private readonly scopeByCall;
-    configure(config: LambderApiIdempotencyConfig): void;
+    [LAMBDER_BACKEND_SWAP](store: LambderIdempotencyStore): boolean;
     /** Startup validation of one API registration's idempotency option. */
     assertRegistration(apiName: string, config: LambderApiIdempotencyOption): void;
     /** True once the idempotency option was configured; registration asserts check it. */
@@ -77,46 +81,55 @@ export declare class LambderApiIdempotencyEngine {
      */
     private readKey;
     /**
-     * The record's scope. Session APIs scope per session, so even a leaked
-     * key cannot cross users. Public APIs scope by the key alone unless the
-     * app supplies callerIdentity, because the key is required to be long
-     * (and documented to be random), and identity proxies like the client IP
-     * are deliberately NOT part of the scope: the retry idempotency exists
-     * for (a timeout followed by a network change) frequently arrives from a
-     * different IP. An app whose public APIs are authorized by a guard should
-     * give callerIdentity, since the replay is served before guards run.
+     * The record's scope. Session APIs scope per user (the sessionKey, which
+     * every session of one user shares), so even a leaked key cannot cross
+     * users. Public APIs scope by the key alone (it must be
+     * long and is documented to be random) unless the app supplies
+     * callerIdentity. The client IP is deliberately NOT part of the scope:
+     * the retry idempotency exists for (a timeout, then a network change)
+     * often arrives from a different IP. Apps whose public APIs are
+     * authorized by a guard should give callerIdentity, since the replay is
+     * served before guards run.
      *
-     * Fields are escaped and joined through joinKeyFields, so no two distinct
-     * scopes can produce one string.
+     * joinKeyFields escapes the fields, so no two distinct scopes collide.
+     * The identity field is the caller's (a device token in the docs' own
+     * example), so it is bounded first (boundKeyField): an over-long one
+     * would push the scope past a store's key limit, and the store's refusal
+     * is a throw that failOpen turns into no idempotency for that caller.
      */
     private scopeOf;
-    private computeScope;
     /**
-     * Replay fast path, run before the remaining rate limits and before
-     * guards: a completed record answers with its stored answer, so a
-     * legitimate retry neither burns rate-limit quota nor re-runs guards (the
-     * original already passed them, and no handler executes). The `per: "ip"`
-     * limits are the exception and are checked ahead of this, since the store
-     * read a replay costs is one of the things they exist to bound. Misses
-     * fall through to the normal pipeline; store errors follow the failOpen
-     * setting.
+     * The call's key worked out, once per call: its scope and its request's
+     * fingerprint, for findReplay and withIdempotency. Null for a call that
+     * sends no key, or when idempotency is not configured; a malformed key
+     * refuses with a 400. Taken at the replay lookup, before input validation
+     * replaces the payload with its parsed form, so the fingerprint is of the
+     * request as it was posted, and callerIdentity (app code that may verify
+     * a token or read a store) runs once.
+     */
+    resolveKeyedCall(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext): Promise<LambderIdempotentCall | null>;
+    /**
+     * Replay fast path, run before guards and all rate limits except
+     * `per: "ip"`: a completed record returns its stored answer, so a
+     * legitimate retry neither burns quota nor re-runs guards (the original
+     * passed them, and no handler executes). The IP limits run first because
+     * the store read a replay costs is one of the things they bound. Misses
+     * fall through to the normal pipeline; store errors follow failOpen.
      */
-    findReplay(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, trace: LambderApiCallTrace): Promise<LambderApiAnswer | null>;
+    findReplay(apiName: string, call: LambderIdempotentCall, trace: LambderApiCallTrace): Promise<LambderApiAnswer | null>;
     /**
-     * Idempotency wrapper around validation-passed handler execution. Without
-     * a client idempotencyKey the handler just runs; with one, the scope
-     * (identity + api + key) is claimed atomically: duplicates of an
-     * in-flight original refuse with 409, replays of a completed one return
-     * the stored answer verbatim, and a crashed original releases its claim
-     * so a retry actually retries.
+     * Idempotency wrapper around validation-passed handler execution, for a
+     * call resolveKeyedCall found a key on (a keyless call runs its handler
+     * without one): the scope (identity + api + key) is claimed atomically: duplicates of an in-flight original
+     * refuse with 409, replays of a completed one return the stored answer
+     * verbatim, and a crashed original releases its claim so a retry retries.
      *
-     * `exec` must hand back the handler's own answer, the headers the handler
-     * itself wrote included: the pipeline applies those before returning here,
-     * so a Set-Cookie the handler set is visible to the caching rule below.
+     * `exec` returns the handler's own answer with the headers the handler
+     * wrote, so a Set-Cookie it set is visible to the caching rule below.
      * Headers written EARLIER in the call (a session read evicting a stale
-     * cookie) are deliberately not on it: they are the call's, they reach the
-     * client either way, and charging them to this answer would make an
-     * idempotent operation silently stop being idempotent.
+     * cookie) are deliberately left off: they reach the client either way,
+     * and charging them to this answer would make it uncacheable, silently
+     * ending the operation's idempotency.
      */
-    withIdempotency(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, config: LambderApiIdempotencyOption, trace: LambderApiCallTrace, exec: () => Promise<LambderApiAnswer>): Promise<LambderApiAnswer>;
+    withIdempotency(apiName: string, { scopeKey, fingerprint }: LambderIdempotentCall, config: LambderApiIdempotencyOption, trace: LambderApiCallTrace, exec: () => Promise<LambderApiAnswer>): Promise<LambderApiAnswer>;
 }