lambder 12.0.1 → 13.0.1

package/CHANGELOG.md

@@ -9,6 +9,86 @@ 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.
 
+## [13.0.1] - 2026-09-30
+
+A major: session data is checked against a schema on every read, and
+`dataRefresh` requires that schema. Beside it, one summary line per API call
+by default, an origin proof for the trusted forwarding headers, refusal codes
+declared per part of an app, a check that every translation keeps its
+placeholders, one round trip for a rate limit's windows, and every generated
+file in one call.
+
+### Changed (breaking)
+
+- **`session.dataRefresh` requires `session.dataSchema`**, the zod schema of
+  `session.data`, at compile time and at creation. Every read checks the
+  record's data against it and hands the request the schema's output; data
+  that does not match (a record written before a deploy changed its shape)
+  is refreshed on that read, whatever its deadline, and a refresh whose
+  output the schema refuses fails the read as a
+  `LambderSessionDataRefreshError`, writing nothing. Without `dataRefresh`
+  the schema is optional, and data that does not match ends the session.
+  With a schema, `createSession` and `updateSessionData` throw on data it
+  refuses and write nothing, rather than store a session its next read
+  would end. A record keeps its data as written or refreshed, and requests
+  are served the schema's output, so every read parses exactly what its
+  write was checked with. The same holds for the mock runtime's sessions.
+  - To move: give `dataSchema` beside `dataRefresh`, the schema your
+    `SessionData` type is, and derive the type from it
+    (`z.infer<typeof sessionDataSchema>`) so the two cannot drift.
+- **The DynamoDB rate limiter sends every window's write at once**, so a
+  policy capping several windows costs one round trip rather than one per
+  window. A window under its limit now counts an attempt another window
+  refuses (the smaller windows were counted first, and the larger ones
+  spared, before), and a window the table refused an attempt in is
+  remembered by the process until it resets, so a flood's later attempts
+  are refused without touching the table and stop raising the other
+  windows' counters. The memory limiter checks every window before counting
+  any, so an attempt it refuses counts nowhere.
+- **`LambderApiAnswer` and `LambderResponse` carry the answer's outcome**
+  (`outcome`, `callOutcome`), which the envelope builders and
+  `res.apiRefusal()` set, and `LambderInstanceBackends` takes a
+  `callSummary` writer.
+
+### Added
+
+- **One summary line per API call** (`callSummary`), written when the call
+  is answered: the endpoint, how it ended (`success`, `refusal` and its
+  code, a flag, `validation`, `crash`, a failing `created` hook's included),
+  the status, the duration and the handler's own time, whether an
+  idempotent answer was replayed, whether the invocation was the process's
+  first, and its request id with the id of the invocation that invoked it.
+  Nothing from the input, the session, the cookies or the caller's address.
+  By default each is one JSON line on stdout, which CloudWatch Logs Insights
+  reads field by field; a function receives each instead, and `false`
+  writes none. A test app collects them in `app.callSummaries`.
+- **The calling invocation's request id travels over invoke**
+  (`LAMBDER_PARENT_REQUEST_HEADER`), read by the callee from an invoke
+  alone, so the two functions' summary lines join.
+- **`originProof: { header, secrets }`**: the trusted client address and
+  host headers are read only from a request carrying the secret the proxy in
+  front of the app sets, so a request sent to the origin directly (an
+  `execute-api` or `lambda-url` address) is counted by the address it came
+  from. The header is taken off `ctx.headers`; `secrets` takes the previous
+  secret during a rotation; a secret under 32 characters, a proof guarding
+  no trusted header, and a proof header that is also a trusted one are
+  refused at creation.
+- **Refusal codes as a list of maps**: `declareRefusals([orderRefusals,
+  walletRefusals])`, on the server's init and the mock's alike, so each part
+  of an app declares its own codes, as guards and rate-limit policies are
+  declared. A code two maps declare is a compile error and a throw.
+- **Every translation keeps the default language's placeholders.** A block
+  whose text drops or adds a `{token}` against the default language's text
+  of the same key is refused where it arrives: an inline block when the
+  instance or an extension is created, a loaded one when its loader answers
+  (`loadLanguage` rejects, and the language stays on the default one), a
+  registered one at `registerDictionary`. Each error lists every mismatch of
+  the block.
+- **`generateApiFiles(config, { check })`** in `lambder/build`: every
+  contract, signature file, options file and guard-parameter file of every
+  app a generator script names, each app's module given once, in one call
+  that names every stale or broken file and does not stop at the first.
+
 ## [12.0.1] - 2026-09-30
 
 A major: endpoints are values. An app declares each endpoint with its

package/README.md

@@ -65,7 +65,8 @@ const company = await caller.companies.get({ slug: "acme" });
 - **Simple route and API declaration.** Paths, regexes, predicates and
   structured matchers, chained fluently.
 - **Sessions.** Over a store of your choosing (DynamoDB, memory, your own),
-  with secrets hashed at rest, sliding expiration, data refresh and
+  with secrets hashed at rest, sliding expiration, session data checked
+  against its schema on every read and refreshed from its source, and
   cross-subdomain cookies.
 - **One API core, two runtimes.** The request pipeline (envelope, refusals,
   sessions, guards, rate limits, idempotency) is one isomorphic class; the
@@ -79,6 +80,10 @@ const company = await caller.companies.get({ slug: "acme" });
   cookies, and a guard against Lambda's response size cap.
 - **Hooks and actions.** Lifecycle hooks, plus `addAction()` for the non-HTTP
   invocations (EventBridge, SQS, custom events) the same function receives.
+- **A summary line per call.** Every API call is logged once, as JSON, with
+  its endpoint, outcome, refusal code, status and timings, and the request
+  ids that join it to the calls it made; nothing from its input or its
+  caller.
 - **Lambda to lambda calls.** `LambderInvokeCaller` invokes a Lambder app in
   another function directly, with no API Gateway in between, typed from the
   callee's own contract and carrying its refusals, crash detail and logs back.
@@ -135,7 +140,7 @@ The package ships five entry points; pick by where the code runs:
 | `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `LambderUploadRunner`, `LambderBackoffTimer`, `LambderSignedClaims`, `html`/`xml` tagged templates, `createLambderI18n` |
 | `lambder/mock` | Browser and Node, in development and tests | `LambderMockApp`, the mock runtime: your typed contract served from mock handlers over the real API pipeline and memory stores |
 | `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions; the store conformance suites, to hold a store you write to the rules Lambder's own meet |
-| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters and nothing else, what a browser gating on that guard carries; `writeApiContract`: the contract as plain types a client compiles instead of the server |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters and nothing else, what a browser gating on that guard carries; `writeApiContract`: the contract as plain types a client compiles instead of the server; `generateApiFiles`: every one of them, for every app a script names, in one call |
 
 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

package/dist/api/LambderApiAnswer.d.ts

@@ -1,3 +1,4 @@
+import type { LambderCallOutcomeHint } from "../shared/wire/LambderCallOutcome.js";
 import type { LambderApiHttpAnswer } from "../shared/wire/LambderApiOutcome.js";
 /**
  * The core's output for one API call, before any transport-level
@@ -23,6 +24,12 @@ export type LambderApiAnswer = {
     isBodyBase64?: boolean;
     compress?: boolean | "auto";
     etag?: boolean | "auto";
+    /**
+     * What the answer is, as the code that wrote it knows it, for the call's
+     * summary line: set by the envelope and validation builders, dropped by
+     * the stores like the other hints (a replay reads it back from the text).
+     */
+    outcome?: LambderCallOutcomeHint;
 };
 /**
  * An answer in the accessor form resolveApiOutcome() reads (the same view a

package/dist/api/LambderApiEnvelope.js

@@ -1,3 +1,4 @@
+import { outcomeOfEnvelope } from "../shared/wire/LambderCallOutcome.js";
 import { LAMBDER_REFUSAL_CODES, isLambderRefusalCode, refusalMessageOf } from "../shared/wire/LambderApiRefusal.js";
 import { setAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 /*
@@ -73,7 +74,8 @@ export const envelopeAnswer = (envelope, options = {}) => {
         // casing replaces the envelope's own rather than shipping beside it.
         setAnswerHeader(headers, key, value);
     }
-    return { statusCode: options.statusCode ?? 200, headers, body: JSON.stringify(envelope) };
+    const statusCode = options.statusCode ?? 200;
+    return { statusCode, headers, body: JSON.stringify(envelope), outcome: outcomeOfEnvelope(envelope, statusCode) };
 };
 /**
  * A thrown refusal as an answer: its refusal and flags on the envelope,
@@ -187,6 +189,7 @@ export const validationAnswer = (zodError, logList) => {
             ...(trimmed ? { issueCount: zodError.issues.length } : {}),
             ...(logList?.length ? { logList } : {}),
         }),
+        outcome: { outcome: "validation", code: null },
     };
 };
 /** No API is registered under the requested name: a refusal, not a 404, so a typed caller reads it. */

package/dist/api/LambderApiRefusals.d.ts

@@ -3,6 +3,7 @@ import type { LambderJsonOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderRefusalStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
 import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderNoRepeatedNames } from "../shared/util/LambderNamedMaps.js";
 /**
  * One code of an app's refusal vocabulary: the schema of the data it carries,
  * when it carries data, and how every refusal with the code leaves the
@@ -69,6 +70,27 @@ export type LambderRefusalVocabularyChecks<TVocabulary> = {
         readonly "lambder: a refusal code may not start with lambder/, the prefix of the framework's own codes": never;
     } : LambderNoExtraKeys<TVocabulary[TCode], LambderRefusalDeclaration> & LambderRefusalDataCheck<TVocabulary[TCode]>;
 };
+/**
+ * The vocabulary as declareRefusals() takes it: one map of codes, or a list of
+ * them, so each part of an app declares its own codes beside its APIs. A
+ * code two maps declare is refused.
+ */
+export type LambderRefusalVocabularyOption = LambderNamedMapsOption<LambderRefusalVocabulary>;
+/** The one vocabulary a declareRefusals() option declares: a list's maps merged, a lone map as it is. */
+export type LambderMergedRefusalVocabulary<TOption> = LambderMergedNamedMaps<TOption> extends infer TMerged extends LambderRefusalVocabulary ? TMerged : never;
+/** A declareRefusals() option checked code by code, in each map of a list, and a list declaring no code twice. */
+export type LambderRefusalVocabularyOptionChecks<TOption> = TOption extends readonly unknown[] ? {
+    [TIndex in keyof TOption]: LambderRefusalVocabularyChecks<TOption[TIndex]>;
+} & LambderNoRepeatedNames<TOption> : LambderRefusalVocabularyChecks<TOption>;
+/**
+ * A declareRefusals() option as the one vocabulary it declares, checked
+ * (see readRefusalVocabulary) and keyed. `declarer` names the init in the
+ * errors.
+ */
+export declare const declaredRefusalVocabulary: (option: LambderRefusalVocabularyOption, declarer: string) => {
+    refusals: LambderRefusalVocabulary;
+    vocabulary: Map<string, LambderRefusalDeclaration>;
+};
 /** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
 export declare const allowedRefusalOf: (declaration: LambderRefusalDeclaration) => LambderApiAllowedRefusal;
 /**

package/dist/api/LambderApiRefusals.js

@@ -1,5 +1,18 @@
 import { LambderApiRefusal, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
+import { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
+/**
+ * A declareRefusals() option as the one vocabulary it declares, checked
+ * (see readRefusalVocabulary) and keyed. `declarer` names the init in the
+ * errors.
+ */
+export const declaredRefusalVocabulary = (option, declarer) => {
+    if (option === null || typeof option !== "object") {
+        throw new Error(`${declarer}: declareRefusals() takes the vocabulary, an object of codes or a list of them.`);
+    }
+    const refusals = mergeNamedMaps(option, "refusal code", "declareRefusals()");
+    return { refusals, vocabulary: readRefusalVocabulary(refusals) };
+};
 /** One code's declaration as checkedRefusal reads it: how a refusal with the code leaves, and its schema. */
 export const allowedRefusalOf = (declaration) => {
     const leaves = {

package/dist/build/generateApiFiles.d.ts

@@ -0,0 +1,60 @@
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderApiContractFileOptions } from "./writeApiContract.js";
+import { type LambderApiSignatureFileOptions } from "./writeApiSignatures.js";
+import { type LambderApiOptionsFileOptions } from "./writeApiOptions.js";
+import { type LambderApiGuardParamsFileOptions } from "./writeApiGuardParams.js";
+/** What a file's writer takes beyond where the instance is, which the app gives once for all its files. */
+type LambderAppFile<TOptions> = Omit<TOptions, "module" | "exportName" | "tsconfig" | "check">;
+/** One app: where its instance is, and which files it is written to. Each file is optional. */
+export type LambderApiFilesApp = {
+    /** The module that exports the instance, usually the server's entry: a path relative to the working directory, or a file URL. */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default". */
+    exportName?: string;
+    /** The tsconfig.json the module compiles under, which the contract is read through. Default: the nearest one at or above the module. */
+    tsconfig?: string;
+    /** The contract a client compiles against, as plain types (writeApiContract). */
+    contract?: LambderAppFile<LambderApiContractFileOptions>;
+    /** The signature file both sides ship (writeApiSignatures). */
+    signatures?: LambderAppFile<LambderApiSignatureFileOptions>;
+    /** The declared options as plain data, for a mock and tests (writeApiOptions). */
+    options?: LambderAppFile<LambderApiOptionsFileOptions>;
+    /** One file per guard whose parameters a browser needs (writeApiGuardParams). */
+    guardParams?: readonly LambderAppFile<LambderApiGuardParamsFileOptions>[];
+};
+/** The files generateApiFiles writes: every app's, by a name the output lines use. */
+export type LambderApiFilesConfig = {
+    apps: Record<string, LambderApiFilesApp>;
+};
+export type LambderApiFilesResult = {
+    /** False when a check found a file stale, or a writer failed. */
+    ok: boolean;
+    /** What happened, per app and file, as lines to print. */
+    lines: string[];
+};
+/**
+ * Writes every file the config names, or with `check` writes nothing and
+ * answers whether each one on disk is current. Paths are relative to the
+ * working directory, as each writer takes them.
+ *
+ * ```ts
+ * import { generateApiFiles } from "lambder/build";
+ *
+ * const result = await generateApiFiles({
+ *     apps: {
+ *         server: {
+ *             module: "backend/index.ts",
+ *             exportName: "lambder",
+ *             contract: { file: "shared/generated/apiContract.generated.ts" },
+ *             signatures: { file: "shared/generated/apiSignatures.generated.ts" },
+ *         },
+ *     },
+ * }, { check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ */
+export declare const generateApiFiles: (config: LambderApiFilesConfig, options?: {
+    check?: boolean;
+}) => Promise<LambderApiFilesResult>;
+export {};

package/dist/build/generateApiFiles.js

@@ -0,0 +1,85 @@
+import { writeApiContract } from "./writeApiContract.js";
+import { writeApiSignatures } from "./writeApiSignatures.js";
+import { writeApiOptions } from "./writeApiOptions.js";
+import { writeApiGuardParams } from "./writeApiGuardParams.js";
+const APP_KEYS = ["module", "exportName", "tsconfig", "contract", "signatures", "options", "guardParams"];
+const FILE_KINDS = ["contract", "signatures", "options", "guardParams"];
+/** A config that names apps, each with its module and at least one file, and no key the generator does not read. */
+function assertConfig(config) {
+    const apps = config?.apps;
+    if (apps === null || typeof apps !== "object" || Array.isArray(apps) || Object.keys(apps).length === 0) {
+        throw new Error("generateApiFiles: the config names no apps. Give `apps`, one entry per Lambder instance: { module, exportName, and the files it is written to }.");
+    }
+    for (const [name, app] of Object.entries(apps)) {
+        if (app === null || typeof app !== "object")
+            throw new Error(`generateApiFiles: the app "${name}" is not an object.`);
+        const unknownKeys = Object.keys(app).filter((key) => !APP_KEYS.includes(key));
+        if (unknownKeys.length)
+            throw new Error(`generateApiFiles: the app "${name}" has ${unknownKeys.map((key) => `"${key}"`).join(", ")}, which the generator does not read (it reads ${APP_KEYS.join(", ")}).`);
+        if (!app.module)
+            throw new Error(`generateApiFiles: the app "${name}" names no module to read its instance from.`);
+        if (!FILE_KINDS.some((kind) => app[kind] !== undefined)) {
+            throw new Error(`generateApiFiles: the app "${name}" is written to no file; give it a contract, signatures, options or guardParams.`);
+        }
+    }
+}
+/** A writer's run as lines: its own on success or a stale check, the reason when it threw. */
+const settle = async (label, write) => {
+    try {
+        return await write();
+    }
+    catch (err) {
+        const reasons = [];
+        for (let cause = err; cause instanceof Error && reasons.length < 4; cause = cause.cause)
+            reasons.push(cause.message);
+        return { ok: false, lines: [`✗ ${label} failed: ${reasons.join(": ") || String(err)}`] };
+    }
+};
+/**
+ * Writes every file the config names, or with `check` writes nothing and
+ * answers whether each one on disk is current. Paths are relative to the
+ * working directory, as each writer takes them.
+ *
+ * ```ts
+ * import { generateApiFiles } from "lambder/build";
+ *
+ * const result = await generateApiFiles({
+ *     apps: {
+ *         server: {
+ *             module: "backend/index.ts",
+ *             exportName: "lambder",
+ *             contract: { file: "shared/generated/apiContract.generated.ts" },
+ *             signatures: { file: "shared/generated/apiSignatures.generated.ts" },
+ *         },
+ *     },
+ * }, { check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ */
+export const generateApiFiles = async (config, options = {}) => {
+    assertConfig(config);
+    const check = options.check ?? false;
+    const apps = Object.entries(config.apps);
+    const runs = [];
+    // The contracts first: they compile the app's sources and run none of
+    // them, so a module that fails to load still gets its contract checked.
+    for (const [name, app] of apps) {
+        if (!app.contract)
+            continue;
+        runs.push(await settle(`${name}: the contract`, () => writeApiContract({ ...app.contract, module: app.module, exportName: app.exportName, tsconfig: app.tsconfig, check })));
+    }
+    // Then what is read off the instance itself, which importing the module
+    // builds once for all three.
+    for (const [name, app] of apps) {
+        const instance = { module: app.module, exportName: app.exportName, check };
+        if (app.signatures)
+            runs.push(await settle(`${name}: the signatures`, () => writeApiSignatures({ ...app.signatures, ...instance })));
+        if (app.options)
+            runs.push(await settle(`${name}: the options`, () => writeApiOptions({ ...app.options, ...instance })));
+        for (const guardFile of app.guardParams ?? []) {
+            runs.push(await settle(`${name}: the "${guardFile.guard}" guard parameters`, () => writeApiGuardParams({ ...guardFile, ...instance })));
+        }
+    }
+    return { ok: runs.every((run) => run.ok), lines: runs.flatMap((run) => run.lines) };
+};

package/dist/build.d.ts

@@ -5,7 +5,8 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources. Node-only and imported by nothing else
+ * from the server's sources; and generateApiFiles, every one of them for
+ * every app a script names, in one call. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
@@ -17,4 +18,6 @@ export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
 export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
 export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
+export { generateApiFiles } from "./build/generateApiFiles.js";
+export type { LambderApiFilesConfig, LambderApiFilesApp, LambderApiFilesResult } from "./build/generateApiFiles.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -5,10 +5,12 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources. Node-only and imported by nothing else
+ * from the server's sources; and generateApiFiles, every one of them for
+ * every app a script names, in one call. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export { writeApiOptions } from "./build/writeApiOptions.js";
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+export { generateApiFiles } from "./build/generateApiFiles.js";

package/dist/core/Lambder.d.ts

@@ -12,7 +12,7 @@ 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 LambderWireRefusalsOf, type LambderHandlerRefusalsOf, type LambderRefusalNamesIn, type LambderRefusalsOption, type LambderRefusalVocabulary, type LambderRefusalVocabularyChecks } from "../api/LambderApiRefusals.js";
+import { type LambderWireRefusalsOf, type LambderHandlerRefusalsOf, type LambderRefusalNamesIn, type LambderRefusalsOption, type LambderRefusalVocabularyOption, type LambderRefusalVocabularyOptionChecks, type LambderMergedRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { type LambderDeclaredRefuse } from "../shared/wire/LambderApiRefusal.js";
 import { type LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
@@ -25,10 +25,13 @@ import type { LambderContractEntry, LambderJsonOf } from "../shared/wire/Lambder
 import { type LambderActionNamesCheck, type LambderApiDeclaration, type LambderApiDeclarations, type LambderApiGroup, type LambderApiModeOf, type LambderAppTypes, type LambderContractOfGroups, type LambderGroupNameCheck, type LambderGroupPartsCheck, type LambderMergedParts, type LambderLazyApiGroup, type LambderPlainAppTypes, type LambderPublicSessionPolicyCheck, type LambderRegisteredGroupsCheck, type LambderRegistrableApiGroup, type LambderSessionModeCheck } from "../api/LambderApiDeclarations.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
 import type { LambderReadonlyDeep, MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import { type LambderCallSummary } from "./LambderCallSummary.js";
 import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderObjectOutputCheck, type LambderPayloadSliceCheck, type LambderRequirableGuardsField, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
 /** 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;
+    /** Where call summaries go instead of the app's own callSummary; null writes none. */
+    callSummary?: ((summary: LambderCallSummary) => void) | null;
 };
 /** What the instance had a place for; see LambderPipelineBackendSwap. `files` is false on an instance created without the files option. */
 export type LambderInstanceBackendSwap = LambderPipelineBackendSwap & {
@@ -146,6 +149,9 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private readonly contextTools;
     private readonly trustedClientIpHeaders;
     private readonly trustedHostHeaders;
+    private readonly originProof;
+    /** Where each API call's summary goes (the callSummary option); null writes none. Replaceable through the backend swap alone. */
+    private callSummaryWriter;
     constructor(given?: LambderCreateOptions<TApp["session"]>);
     setRouteFallbackHandler(routeFallbackHandler: LambderFallbackHandler): this;
     setApiFallbackHandler(apiFallbackHandler: LambderFallbackHandler): this;
@@ -445,7 +451,15 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      */
     private isCorsPreflight;
     private resolveRequest;
+    /**
+     * One HTTP invocation, from the event to the finalized response, under
+     * an invocation record of its own (see LambderInvocationScope): what an
+     * API call's summary line is written from once the response is final.
+     */
     render(event: LambderHttpEvent, lambdaContext: Context): Promise<LambderHttpResponse>;
+    private renderRequest;
+    /** What createContext reads this instance's requests with. */
+    private contextOptions;
     /**
      * A thrown value that is an answer rather than a crash, as the response;
      * anything else is rethrown to the crash path.
@@ -470,6 +484,12 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * failed too.
      */
     private answerCrash;
+    /**
+     * The summary line of an API call, once its response is final: nothing
+     * for an invocation that served no API call. A writer that throws costs
+     * the call its line and nothing else.
+     */
+    private writeCallSummary;
     /**
      * An answer to a crash, carrying what the call wrote and its CORS headers.
      * As on the success path, headers belong to the call: a call that wrote a
@@ -500,6 +520,7 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * so Lambda's retries and dead-letter queues still see the failure.
      */
     renderEvent(event: unknown, lambdaContext: Context): Promise<unknown>;
+    private renderEventAction;
     /**
      * The answer for a rejected input: the app's
      * setApiInputValidationErrorHandler when set, otherwise the standard 422
@@ -596,7 +617,10 @@ export declare const initLambder: <TSessionData = any>() => {
      * Declares the app's refusal vocabulary: every code once, with the schema
      * of its data (`{ data: schema }`) or none (`{}`), the status every
      * refusal with it leaves with (`status`, 200 by default) and whether it
-     * sets the notAuthorized flag (`notAuthorized: true`). Returns the init
+     * sets the notAuthorized flag (`notAuthorized: true`). One map of codes,
+     * or a list of them, as guards and rate-limit policies are declared, so
+     * each part of an app declares its own codes; a code two maps declare is
+     * refused, at compile time and at the call. Returns the init
      * bound to it: its guard() types ctx.refuse to a guard's refusals and
      * refuses a guard naming a code outside the vocabulary, its refuse is
      * typed to the whole vocabulary, and its create() hands the vocabulary to
@@ -604,7 +628,7 @@ export declare const initLambder: <TSessionData = any>() => {
      * handler, a guard or a helper is a crash rather than an answer, so every
      * "no" a client reads names a code.
      */
-    declareRefusals<const TRefusals extends LambderRefusalVocabulary, const TRequireCodes extends boolean = false>(refusals: TRefusals & LambderRefusalVocabularyChecks<TRefusals>, options?: {
+    declareRefusals<const TRefusals extends LambderRefusalVocabularyOption, const TRequireCodes extends boolean = false>(refusals: TRefusals & LambderRefusalVocabularyOptionChecks<TRefusals>, options?: {
         requireCodes?: TRequireCodes;
     }): {
         /**
@@ -615,8 +639,8 @@ export declare const initLambder: <TSessionData = any>() => {
          * refuse(). Inside an API handler ctx.refuse is narrower, that
          * endpoint's codes alone.
          */
-        refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<TRefusals, keyof TRefusals & string>, TRequireCodes>;
-        create<const TOptions extends LambderInitCreateOptions<TSessionData>>(options: TOptions & Record<Exclude<keyof TOptions, "session" | "guards" | "idempotency" | "apiVersion" | "cors" | "apiPath" | "apiSignatures" | "trustedClientIpHeaders" | "trustedHostHeaders" | "files" | "etag" | "rateLimits" | "minApiVersion" | "compression" | "maxResponseBytes" | "maxRequestPayloadBytes" | "requireApiGuards" | "crashes">, never> & LambderNestedOptionChecks<TSessionData, TOptions, TRefusals>): Lambder<{
+        refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<LambderMergedRefusalVocabulary<TRefusals>, keyof LambderMergedRefusalVocabulary<TRefusals> & string>, TRequireCodes>;
+        create<const TOptions extends LambderInitCreateOptions<TSessionData>>(options: TOptions & Record<Exclude<keyof TOptions, "session" | "guards" | "idempotency" | "apiVersion" | "cors" | "apiPath" | "apiSignatures" | "trustedClientIpHeaders" | "trustedHostHeaders" | "originProof" | "files" | "etag" | "rateLimits" | "minApiVersion" | "compression" | "maxResponseBytes" | "maxRequestPayloadBytes" | "callSummary" | "requireApiGuards" | "crashes">, never> & LambderNestedOptionChecks<TSessionData, TOptions, LambderMergedRefusalVocabulary<TRefusals>>): Lambder<{
             session: TSessionData;
             policies: TOptions["rateLimits"] extends {
                 policies: infer TPolicies;
@@ -625,10 +649,10 @@ export declare const initLambder: <TSessionData = any>() => {
             idempotency: TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false;
             guardsRequired: [LambderGivenOption<TOptions, "requireApiGuards">] extends [false | undefined] ? false : true;
             sessions: [LambderGivenOption<TOptions, "session">] extends [undefined] ? false : true;
-            refusals: TRefusals;
+            refusals: LambderMergedRefusalVocabulary<TRefusals>;
             refusalCodesRequired: TRequireCodes;
         }, {}>;
-        guard: import("../api/LambderApiGuards.js").LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>, TRefusals, TRequireCodes>;
+        guard: import("../api/LambderApiGuards.js").LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>, LambderMergedRefusalVocabulary<TRefusals>, TRequireCodes>;
         rateLimitKey: import("../api/LambderApiRateLimits.js").LambderRateLimitKeyBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>>;
     };
     /**
@@ -651,7 +675,7 @@ export declare const initLambder: <TSessionData = any>() => {
         code?: undefined;
         data?: undefined;
     }) | undefined) => never;
-    create<const TOptions extends LambderInitCreateOptions<TSessionData>>(options: TOptions & Record<Exclude<keyof TOptions, "session" | "guards" | "idempotency" | "apiVersion" | "cors" | "apiPath" | "apiSignatures" | "trustedClientIpHeaders" | "trustedHostHeaders" | "files" | "etag" | "rateLimits" | "minApiVersion" | "compression" | "maxResponseBytes" | "maxRequestPayloadBytes" | "requireApiGuards" | "crashes">, never> & LambderNestedOptionChecks<TSessionData, TOptions, {}>): Lambder<{
+    create<const TOptions extends LambderInitCreateOptions<TSessionData>>(options: TOptions & Record<Exclude<keyof TOptions, "session" | "guards" | "idempotency" | "apiVersion" | "cors" | "apiPath" | "apiSignatures" | "trustedClientIpHeaders" | "trustedHostHeaders" | "originProof" | "files" | "etag" | "rateLimits" | "minApiVersion" | "compression" | "maxResponseBytes" | "maxRequestPayloadBytes" | "callSummary" | "requireApiGuards" | "crashes">, never> & LambderNestedOptionChecks<TSessionData, TOptions, {}>): Lambder<{
         session: TSessionData;
         policies: TOptions["rateLimits"] extends {
             policies: infer TPolicies;