lambder 7.2.4 → 7.3.1

package/CHANGELOG.md

@@ -9,6 +9,94 @@ 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.
 
+## [7.3.1] - 2026-09-21
+
+### Added
+
+- **`lambder/testing`: a real app under test, in one call.** `lambderTestApp(lambder)`
+  takes the instance an app already exports and returns a `LambderTestApp`:
+  memory stores put under the instance, and simulated browsers in front of it,
+  with no HTTP and no AWS. Every piece existed before (the in-process handler
+  transport, the cookie jar, the memory stores), but each app had to assemble
+  them, and none could do the one thing that needs the framework's help: an
+  app is a module-level instance whose handlers and guards close over it, so a
+  test cannot be handed a copy over other stores, because the copy's closures
+  still reach the original and the production table under it. The stores are
+  therefore replaced **in place**, through a door keyed by a symbol no entry
+  point exports, so nothing on an instance's typed surface offers it to a
+  serving app. Nothing about the app is restructured, its guards, policies,
+  session model, hooks and error handlers all run as written, and from the
+  moment the test app exists the stores the app was created with are out of
+  the instance's reach.
+  - **Visitors.** `app.visitor()` is one simulated browser: its own cookie
+    jar, its own address (so a `per: "ip"` limit counts visitors apart, as it
+    does for two people in production), a typed `api` / `apiOutcome` over the
+    real pipeline, and `request(method, path)` for everything that is not an
+    API call (routes, redirects, session routes, public files), sharing the
+    same jar. `app.signIn(sessionKey, data)` returns a visitor already signed
+    in, minted by the app's own session model, so no login endpoint has to
+    exist. It throws, and says why, when the app's cookie domain does not
+    cover the visitor's host, instead of leaving every later call to answer
+    `sessionExpired`. `guardInputsProvider`, `headers`, `host`, `clientIp`,
+    `apiVersion` and `apiSignatures` are per visitor.
+  - **The mock app's verbs**, over the real handlers: `signIn`, `signOut`,
+    `expireSessionData`, `reset`, plus `event()` for what is not an HTTP
+    request (a schedule, SNS, SQS) and the stores themselves for assertions.
+  - **What the app threw.** A crash is answered by the app's global error
+    handler or by the framework's 500, and either answer deliberately says
+    nothing about the error, which leaves a test author with "status 500". The
+    test app watches what the instance throws without changing what it
+    answers: `visitor.apiOutcome` sets the thrown error as the failure's
+    `error.cause`, per call even with others in flight, and `app.crashes`
+    lists every one since the last reset.
+  - **Options** sit where `create()` takes them (`session.store`,
+    `rateLimits.limiter`, `idempotency.store`, `files`), each defaulting to a
+    fresh memory store, or for `files` to the app's own source.
+  - **`eventFormat: "v1" | "v2"`** (default `"v2"`): the gateway shape the
+    handler is called with, so an app behind a REST API can run its suite on
+    the event production delivers. `synthesizeLambdaHttpEvent` and
+    `lambderHandlerTransport` take the same option; a REST API event carries
+    its cookies in the Cookie header and every header in both delivery forms,
+    and the asserted client address stays the gateway's observation
+    (`requestContext.identity.sourceIp`) rather than a header, as on 2.0.
+  - The test app owns no clock, on purpose: faking `Date` with the test runner
+    moves the framework, the memory stores and the app's own handlers
+    together, which a clock of the test app's could not.
+- **`assertApiSuccess` and `assertApiFailure`**, from `lambder/testing` and
+  `lambder/mock`. They narrow an outcome through an `asserts` signature, so
+  what the proved arm carries reads on the next line, and they throw a plain
+  Error naming what the outcome actually was, with the failure's own error as
+  its cause. `assertApiFailure(outcome, reason?, { code?, status? })` types
+  the reason against the union it was handed, so a misspelled one does not
+  compile, and narrows per arm, since `server` shares its arm with three other
+  reasons and `Extract` would have dropped it. Typed structurally over `ok`
+  and `reason`, so a `LambderInvokeOutcome` narrows through the same two
+  functions, and no test runner is imported.
+- **[docs/testing.md](./docs/testing.md)**: testing a Lambder app in one page.
+  It was spread across ten pages as asides before.
+
+### Changed
+
+- The session manager asks "may this crypto sit in front of this store" of
+  every store it is given, a swapped one included, rather than only in its
+  constructor.
+- **The suite uses its own tools where the subject is what an app does.**
+  The routing, hook, plugin, action, redirect and thrown-response tests run
+  on the test app: a visitor's `request()` in place of a hand-built event, a
+  context and a body decoder, `app.event()` for the non-HTTP actions, a typed
+  `api()` for the plugin tests (which now also prove the contract flows
+  through `use()` to a caller), and `signIn()` in place of session records
+  forged with an SDK mock and hand-made hashes. Seven files lost their private
+  copies of the event and context builders. The hand-written `if(!outcome.ok)`
+  narrowing in the mock app's, the invoke caller's and the transports' tests
+  became the two assertions.
+- The tests whose subject is the wire stay on hand-built events, because the
+  event or the raw answer is what they test: event parsing, response
+  finalization, compression, cookies and CORS headers, the policy and refusal
+  answers (status, envelope, Retry-After), error answers, the two gateway
+  formats, and the transports themselves. `tests/helpers.ts` says which is
+  which.
+
 ## [7.2.4] - 2026-09-19
 
 ### Changed

package/README.md

@@ -99,13 +99,14 @@ so if you need a specific one, install it and bundle it yourself.
 
 ## Package entry points
 
-The package ships three entry points; pick by where the code runs:
+The package ships four 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/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 |
 
 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
@@ -142,6 +143,7 @@ guide that matches what you are building. The full index lives in
 | [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 |
 | [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` |
@@ -149,7 +151,7 @@ guide that matches what you are building. The full index lives in
 | [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, on-demand languages, runtime dictionaries |
 | [The mock runtime](./docs/mock.md) | `LambderMockApp`: the typed contract served from mock handlers over the real pipeline, in the browser and in tests |
 | [DynamoDB tables](./docs/dynamodb-tables.md) | Table shapes, TTL and IAM for sessions, cache, rate limits and idempotency |
-| [Exports reference](./docs/exports.md) | Every name the three entry points export, grouped by purpose |
+| [Exports reference](./docs/exports.md) | Every name the four entry points export, grouped by purpose |
 
 ## Standalone modules
 

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;
@@ -66,6 +67,12 @@ export declare class LambderApiIdempotencyEngine {
      */
     private readonly scopeByCall;
     configure(config: LambderApiIdempotencyConfig): void;
+    /**
+     * Puts the engine over another store, for `lambder/testing`; the replay
+     * TTLs, failOpen and callerIdentity stay as configured. False when
+     * idempotency was never configured.
+     */
+    [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. */

package/dist/api/LambderApiIdempotency.js

@@ -2,6 +2,7 @@ import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
 import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * A crashed original must not block retries forever, so a pending claim
  * expires on its own. The default is five minutes, which covers the great
@@ -102,6 +103,17 @@ export class LambderApiIdempotencyEngine {
         this.failOpen = config.failOpen ?? true;
         this.callerIdentity = config.callerIdentity;
     }
+    /**
+     * Puts the engine over another store, for `lambder/testing`; the replay
+     * TTLs, failOpen and callerIdentity stay as configured. False when
+     * idempotency was never configured.
+     */
+    [LAMBDER_BACKEND_SWAP](store) {
+        if (!this.store)
+            return false;
+        this.store = store;
+        return true;
+    }
     /** Startup validation of one API registration's idempotency option. */
     assertRegistration(apiName, config) {
         if (typeof config !== "object")

package/dist/api/LambderApiPipeline.d.ts

@@ -8,7 +8,10 @@ import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.
 import type { LambderApiGuard } from "./LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
-import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import type LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController, { type LambderSessionCookieOptions, type LambderSessionRequestInfo } from "../session/LambderSessionController.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
@@ -57,6 +60,26 @@ export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessio
     }>>;
     idempotency?: LambderApiIdempotencyConfig;
 };
+/** The stores `lambder/testing` puts under a built pipeline. One the pipeline has no subsystem for is left aside. */
+export type LambderPipelineBackends = {
+    sessionStore?: LambderSessionStore<any>;
+    rateLimiter?: LambderRateLimiter;
+    idempotencyStore?: LambderIdempotencyStore;
+};
+/**
+ * What a backend swap found: whether the rate-limit and idempotency
+ * subsystems exist to take a store, and, when sessions are configured, the
+ * cookie names a caller over this pipeline has to be told (they are the
+ * app's own choice and nothing else hands them out).
+ */
+export type LambderPipelineBackendSwap = {
+    sessions: {
+        tokenCookieKey: string;
+        csrfCookieKey: string;
+    } | null;
+    rateLimits: boolean;
+    idempotency: boolean;
+};
 /** What one run produced, beside the answer: what an adapter may want to report. */
 export type LambderApiRunResult = LambderApiCallTrace & {
     answer: LambderApiAnswer;
@@ -105,6 +128,12 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * (its cookies and posted CSRF token) or a route's (cookies and no CSRF).
      */
     sessionController(ctx: TCtx, request: LambderSessionRequestInfo): LambderSessionController<TSessionData>;
+    /**
+     * The backend swap: each store given goes under the subsystem that holds
+     * one, and everything the app configured around it (the session model,
+     * the named policies, the replay TTLs) stays in force.
+     */
+    [LAMBDER_BACKEND_SWAP](backends: LambderPipelineBackends): LambderPipelineBackendSwap;
     /** The session request info of an API request: its cookies, and the CSRF token it posted. */
     static sessionInfoOf(request: LambderApiRequest): LambderSessionRequestInfo;
     /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */

package/dist/api/LambderApiPipeline.js

@@ -7,6 +7,7 @@ import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderReques
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { compareDottedVersions, isDottedVersion } from "../shared/wire/LambderVersionOrder.js";
 import { LambderApiPolicyEngine } from "./LambderApiPolicyEngine.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import LambderSessionController, { assertSessionCookiePrefixes, } from "../session/LambderSessionController.js";
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
 /**
@@ -109,6 +110,19 @@ export class LambderApiPipeline {
             request,
         });
     }
+    /**
+     * The backend swap: each store given goes under the subsystem that holds
+     * one, and everything the app configured around it (the session model,
+     * the named policies, the replay TTLs) stays in force.
+     */
+    [LAMBDER_BACKEND_SWAP](backends) {
+        if (this.sessions && backends.sessionStore)
+            this.sessions.manager[LAMBDER_BACKEND_SWAP](backends.sessionStore);
+        return {
+            sessions: this.sessions ? { tokenCookieKey: this.sessions.tokenCookieKey, csrfCookieKey: this.sessions.csrfCookieKey } : null,
+            ...this.policies[LAMBDER_BACKEND_SWAP](backends),
+        };
+    }
     /** The session request info of an API request: its cookies, and the CSRF token it posted. */
     static sessionInfoOf(request) {
         return { host: request.host, cookies: request.cookies, csrfToken: request.token };

package/dist/api/LambderApiPolicyEngine.d.ts

@@ -5,6 +5,9 @@ import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
 import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
+import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * Runtime side of the declarative API options: composes the three policy
  * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
@@ -23,6 +26,14 @@ export declare class LambderApiPolicyEngine {
     configureRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     configureGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
     configureIdempotency(config: LambderApiIdempotencyConfig): void;
+    /** The backend swap, handed on to the two subsystems that hold a store. Each answers whether it had a place for one. */
+    [LAMBDER_BACKEND_SWAP](backends: {
+        rateLimiter?: LambderRateLimiter;
+        idempotencyStore?: LambderIdempotencyStore;
+    }): {
+        rateLimits: boolean;
+        idempotency: boolean;
+    };
     /** Startup validation of one API's declarative options. */
     assertRegistration(definition: LambderApiDefinition): void;
     /** The rate-limit policies that can be checked before the session is read: see LambderApiRateLimitsEngine.run. */

package/dist/api/LambderApiPolicyEngine.js

@@ -1,6 +1,7 @@
 import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
 import { LambderApiRateLimitsEngine } from "./LambderApiRateLimits.js";
 import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /** An API that asks for idempotency: declared, and not the explicit `false` opt-out. */
 const usesIdempotency = (definition) => definition.idempotency !== undefined && definition.idempotency !== false;
 /**
@@ -29,6 +30,13 @@ export class LambderApiPolicyEngine {
     configureIdempotency(config) {
         this.idempotency.configure(config);
     }
+    /** The backend swap, handed on to the two subsystems that hold a store. Each answers whether it had a place for one. */
+    [LAMBDER_BACKEND_SWAP](backends) {
+        return {
+            rateLimits: backends.rateLimiter ? this.rateLimits[LAMBDER_BACKEND_SWAP](backends.rateLimiter) : false,
+            idempotency: backends.idempotencyStore ? this.idempotency[LAMBDER_BACKEND_SWAP](backends.idempotencyStore) : false,
+        };
+    }
     /** Startup validation of one API's declarative options. */
     assertRegistration(definition) {
         const { name, mode } = definition;

package/dist/api/LambderApiRateLimits.d.ts

@@ -6,6 +6,7 @@ import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import { type LambderRateLimiter, type LambderRateLimitPolicy } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderApiRefusal, type LambderAppRefusalMessage } 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. */
 export declare const DEFAULT_RATE_LIMIT_REFUSAL: {
     type: "warning";
@@ -184,6 +185,12 @@ export declare class LambderApiRateLimitsEngine {
     /** True once rateLimits were configured. */
     get isConfigured(): boolean;
     configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    /**
+     * Puts the engine over another limiter, for `lambder/testing`; the named
+     * policies and failOpen stay as configured. False when rateLimits were
+     * never configured: there is nothing for a limiter to sit under.
+     */
+    [LAMBDER_BACKEND_SWAP](limiter: LambderRateLimiter): boolean;
     /** Startup validation of one API registration's rateLimit option. */
     assertRegistration(apiName: string, mode: LambderApiMode, rateLimitOption?: LambderRateLimitOptionValue): void;
     /**

package/dist/api/LambderApiRateLimits.js

@@ -4,6 +4,7 @@ import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
 import { parsePreflightSlice } from "./LambderApiValidationRefusal.js";
 import { assertNonNegativeInteger } from "../shared/util/LambderOptionChecks.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
 /** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
 export const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
@@ -139,6 +140,17 @@ export class LambderApiRateLimitsEngine {
         this.failOpen = config.failOpen ?? true;
         this.policies = new Map(Object.entries(config.policies));
     }
+    /**
+     * Puts the engine over another limiter, for `lambder/testing`; the named
+     * policies and failOpen stay as configured. False when rateLimits were
+     * never configured: there is nothing for a limiter to sit under.
+     */
+    [LAMBDER_BACKEND_SWAP](limiter) {
+        if (!this.limiter)
+            return false;
+        this.limiter = limiter;
+        return true;
+    }
     /** Startup validation of one API registration's rateLimit option. */
     assertRegistration(apiName, mode, rateLimitOption) {
         const entries = toRateLimitEntries(rateLimitOption);

package/dist/core/Lambder.d.ts

@@ -9,6 +9,9 @@ import type LambderSessionController from "../session/LambderSessionController.j
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import { type LambderIndexHtmlOptions } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
+import { type LambderPipelineBackends, type LambderPipelineBackendSwap } from "../api/LambderApiPipeline.js";
+import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { type LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
@@ -25,6 +28,14 @@ import { type LambderRouteHandler, type LambderInputValidationHandler, type Lamb
  * because its parameter is the class, and an options module that names the
  * class cannot be read without it.
  */
+/** Everything `lambder/testing` may put under a built instance: the pipeline's stores, and the source its files are read from. */
+export type LambderInstanceBackends = LambderPipelineBackends & {
+    fileSource?: LambderFileSource;
+};
+/** What the instance had a place for; see LambderPipelineBackendSwap. `files` is false on an instance created without the files option. */
+export type LambderInstanceBackendSwap = LambderPipelineBackendSwap & {
+    files: boolean;
+};
 export type LambderCreatedHook = (lambderInstance: Lambder<any, any, any, any, any, any, any, any>) => void | Promise<void>;
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
@@ -60,10 +71,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
      *
+     * Export it as an interface extending LambderFlattenContract, not as a
+     * type alias. Chaining builds the contract as an intersection one member
+     * deep per endpoint, and an interface collapses that into one declared
+     * set of members, which every generic read of the contract (a mock
+     * registry, a needs map, the typed caller) is then far cheaper against.
+     * See LambderFlattenContract for the measurements.
+     *
      * @example
      * ```typescript
      * const lambder = new Lambder().addApi(...).addApi(...);
-     * export type ApiContractType = typeof lambder.ApiContract;
+     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
      * ```
      */
     readonly ApiContract: _TContract;
@@ -88,6 +106,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private corsConfig;
     private finalizeOptions;
     private requireSessionApiGuards;
+    /** Told what a request threw, beside whatever answers it; null outside a test. See LAMBDER_CRASH_WATCH. */
+    private crashWatcher;
     private readonly trustedClientIpHeaders;
     private requirePublicApiGuards;
     constructor(options?: LambderCreateOptions<TSessionData>);
@@ -171,6 +191,20 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     getSessionController(ctx: LambderRenderContext | LambderSessionRenderContext<any, TSessionData>): LambderSessionController<TSessionData>;
     /** The session manager, for code that works on sessions outside a request (maintenance, tests). */
     getSessionManager(): LambderSessionManager<TSessionData>;
+    /**
+     * The backend swap `lambder/testing` performs: the stores given go under
+     * this instance in place, so every handler and guard that closed over it
+     * reaches them, and the production ones are out of reach from then on.
+     * Keyed by a symbol no entry point exports, so it is not part of what an
+     * app can call; see LAMBDER_BACKEND_SWAP.
+     */
+    [LAMBDER_BACKEND_SWAP](backends: LambderInstanceBackends): LambderInstanceBackendSwap;
+    /**
+     * The crash watch `lambder/testing` sets: told every error a request
+     * throws past the framework's own handling, before the global error
+     * handler or the last-resort 500 answers it. The answer is unchanged.
+     */
+    [LAMBDER_CRASH_WATCH](watcher: (error: Error) => void): void;
     /**
      * Every registered endpoint's signature, keyed by its hashed name: the
      * LambderApiSignatureMap both sides ship with. A generator imports the

package/dist/core/Lambder.js

@@ -10,6 +10,7 @@ import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
 import { apiNotFoundAnswer, crashAnswer, refusalAnswer, } from "../api/LambderApiEnvelope.js";
@@ -55,10 +56,17 @@ export default class Lambder {
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
      *
+     * Export it as an interface extending LambderFlattenContract, not as a
+     * type alias. Chaining builds the contract as an intersection one member
+     * deep per endpoint, and an interface collapses that into one declared
+     * set of members, which every generic read of the contract (a mock
+     * registry, a needs map, the typed caller) is then far cheaper against.
+     * See LambderFlattenContract for the measurements.
+     *
      * @example
      * ```typescript
      * const lambder = new Lambder().addApi(...).addApi(...);
-     * export type ApiContractType = typeof lambder.ApiContract;
+     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
      * ```
      */
     ApiContract;
@@ -83,6 +91,8 @@ export default class Lambder {
     corsConfig = null;
     finalizeOptions;
     requireSessionApiGuards;
+    /** Told what a request threw, beside whatever answers it; null outside a test. See LAMBDER_CRASH_WATCH. */
+    crashWatcher = null;
     trustedClientIpHeaders;
     requirePublicApiGuards;
     constructor(options = {}) {
@@ -287,6 +297,26 @@ export default class Lambder {
     getSessionManager() {
         return this.pipeline.sessionManager;
     }
+    /**
+     * The backend swap `lambder/testing` performs: the stores given go under
+     * this instance in place, so every handler and guard that closed over it
+     * reaches them, and the production ones are out of reach from then on.
+     * Keyed by a symbol no entry point exports, so it is not part of what an
+     * app can call; see LAMBDER_BACKEND_SWAP.
+     */
+    [LAMBDER_BACKEND_SWAP](backends) {
+        if (this.files && backends.fileSource)
+            this.files[LAMBDER_BACKEND_SWAP](backends.fileSource);
+        return { ...this.pipeline[LAMBDER_BACKEND_SWAP](backends), files: this.files !== null };
+    }
+    /**
+     * The crash watch `lambder/testing` sets: told every error a request
+     * throws past the framework's own handling, before the global error
+     * handler or the last-resort 500 answers it. The answer is unchanged.
+     */
+    [LAMBDER_CRASH_WATCH](watcher) {
+        this.crashWatcher = watcher;
+    }
     /**
      * Every registered endpoint's signature, keyed by its hashed name: the
      * LambderApiSignatureMap both sides ship with. A generator imports the
@@ -545,6 +575,7 @@ export default class Lambder {
             // client could parse. coerceToError is the shared version of that
             // care, the one every site in the framework now uses.
             const wrappedError = coerceToError(err, "an unstringifiable thrown value");
+            this.crashWatcher?.(wrappedError);
             // ctx may be null (createContext failed): derive the format from the raw event.
             const eventFormat = ctx?.eventFormat ?? (isV2HttpEvent(event) ? "v2" : "v1");
             try {

package/dist/core/LambderFiles.d.ts

@@ -1,5 +1,6 @@
 import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
 import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /** In-memory cache of files for warm invocations. Default: { maxBytes: 32MB, maxFileBytes: 2MB }. false disables it. */
 export type LambderFileMemoryCacheOption = false | {
     maxBytes?: number;
@@ -30,6 +31,12 @@ export declare class LambderFiles {
     private maxFileBytes;
     private templates;
     constructor(option: LambderFilesOption);
+    /**
+     * Puts the reader over another source, for `lambder/testing`. In place,
+     * because servePublicFiles holds this reader rather than the instance's
+     * field; both caches go with the source they were filled from.
+     */
+    [LAMBDER_BACKEND_SWAP](source: LambderFileSource): void;
     /**
      * The file at a request or handler path (leading slash optional), mime
      * type resolved; null when the path is invalid or the source has none.

package/dist/core/LambderFiles.js

@@ -1,5 +1,6 @@
 import mimeTypeResolver from "mime-types";
 import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 const DEFAULT_MEMORY_CACHE_MAX_BYTES = 32 * 1024 * 1024;
 const DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES = 2 * 1024 * 1024;
 /**
@@ -45,6 +46,17 @@ export class LambderFiles {
         this.maxBytes = memoryCache === false ? 0 : (memoryCache?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES);
         this.maxFileBytes = memoryCache === false ? 0 : (memoryCache?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES);
     }
+    /**
+     * Puts the reader over another source, for `lambder/testing`. In place,
+     * because servePublicFiles holds this reader rather than the instance's
+     * field; both caches go with the source they were filled from.
+     */
+    [LAMBDER_BACKEND_SWAP](source) {
+        this.source = source;
+        this.cache?.clear();
+        this.cacheBytes = 0;
+        this.templates.clear();
+    }
     /**
      * The file at a request or handler path (leading slash optional), mime
      * type resolved; null when the path is invalid or the source has none.

package/dist/index.d.ts

@@ -104,7 +104,7 @@ export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderFlattenContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -8,7 +8,8 @@
  * its body envelope, and a carried session as the cookie pair it travels as.
  * Server-only: Buffer and the codec's zlib restore.
  */
-import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
+import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, Context } from "aws-lambda";
+import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 import type { LambderCompressedBrotliPayload, LambderCompressedGzipPayload } from "../shared/wire/LambderRequestPayload.js";
 /** Marks a synthesized request as an invoke, for guards and hooks that want to tell. Not an authorization. */
 export declare const LAMBDER_INVOKE_HEADER = "x-lambder-invoke";
@@ -34,19 +35,32 @@ export type LambderSynthesizedRequest = {
     body?: string | Buffer;
 };
 /**
- * The payload-format-2.0 event API Gateway would deliver for this request.
+ * The event API Gateway would deliver for this request: payload format 2.0
+ * (an HTTP API, a Function URL) unless `eventFormat: "v1"` asks for the REST
+ * API's. An invoke is always 2.0; the other format is for an in-process call
+ * that wants the handler to meet the shape its own deployment delivers.
  * `invoke: true` adds the invoke marker headers a server-to-server call
  * carries; a browser-shaped request (the handler transport) leaves them off.
  *
- * The client address is `clientIp` and reaches the callee as
- * requestContext.http.sourceIp only. Writing it as x-forwarded-for as well
- * would put the same fact on a channel a callee may be configured to trust
- * (trustedClientIpHeaders), and the header is the one the caller's own
- * `headers` could otherwise have set.
+ * The client address is `clientIp` and reaches the callee as the gateway's
+ * observed source address only (requestContext.http.sourceIp, or
+ * requestContext.identity.sourceIp on a REST API event). Writing it as
+ * x-forwarded-for as well would put the same fact on a channel a callee may
+ * be configured to trust (trustedClientIpHeaders), and the header is the one
+ * the caller's own `headers` could otherwise have set.
  */
-export declare const synthesizeLambdaHttpEvent: (request: LambderSynthesizedRequest, options: {
+export declare function synthesizeLambdaHttpEvent(request: LambderSynthesizedRequest, options: {
     invoke: boolean;
-}) => APIGatewayProxyEventV2;
+    eventFormat?: "v2";
+}): APIGatewayProxyEventV2;
+export declare function synthesizeLambdaHttpEvent(request: LambderSynthesizedRequest, options: {
+    invoke: boolean;
+    eventFormat: "v1";
+}): APIGatewayProxyEvent;
+export declare function synthesizeLambdaHttpEvent(request: LambderSynthesizedRequest, options: {
+    invoke: boolean;
+    eventFormat?: LambderHttpEventFormat;
+}): APIGatewayProxyEventV2 | APIGatewayProxyEvent;
 /**
  * The body envelope LambderCaller sends, minus the fields only a browser has
  * a value for, as JSON. A plain payload arrives already serialized (the