lambder 12.0.1 → 14.0.1

package/CHANGELOG.md

@@ -9,6 +9,125 @@ 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.
 
+## [14.0.1] - 2026-09-30
+
+A major: `writeApiGuardParams` writes one export per API in place of one
+table, so a browser carries only the guard parameters its screens import,
+and none of the API names behind them.
+
+### Changed (breaking)
+
+- **`writeApiGuardParams` writes one export per API** that declares the
+  guard, in place of the `guardParams` table: `orders.list` exports
+  `ordersListGuardParam`, holding the parameter as declared (`true` for the
+  guard named without one) and typed
+  `LambderApiGuardParam<"orders.list", "store", literal>`. A bundler keeps
+  only the exports a client imports, and none of them carries its API's name,
+  which sits in the export's type and doc comment alone, so a page no longer
+  ships the name of every API behind the guard and what each asks. The
+  module imports the tag type from `lambder/client`, as a type. Two APIs
+  whose names would export under one identifier fail the write, and so does
+  a `null` parameter, which the tag cannot carry; a guard no API declares
+  writes an empty module. A file still in the table form reads as one to
+  regenerate, on a check and on a write.
+  - To move: regenerate the file, and import the exports a screen gates on
+    in place of reading `guardParams[name]`. A function that takes any of a
+    guard's parameters reads their union off the module with a type-only
+    import (`(typeof params)[keyof typeof params]`, over
+    `import type * as params`). Code that needs every API's name, a test
+    walking them all, reads it from the `writeApiOptions` file.
+
+### Added
+
+- **`LambderApiGuardParam`** (`lambder/client`, `lambder`): the type of each
+  export `writeApiGuardParams` writes, a guard's parameter tagged in types
+  alone with the API's name and the guard's, so a function typed to a
+  guard's parameters refuses a hand-written literal.
+- **`apiGuardParamExportName`** (`lambder/client`, `lambder`): the identifier
+  `writeApiGuardParams` exports an API's parameter under, for code that reads
+  a generated module by API name, such as a test comparing it with the
+  server.
+
+## [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, one export per API and nothing else, so a browser gating on that guard carries only the ones it imports; `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/generatedTables.d.ts

@@ -52,7 +52,7 @@ export declare const settleGeneratedFile: (run: {
     previousText: string | null;
     /** Whether that text held the tables as written; false for a file rewritten by hand. */
     readBack: boolean;
-    /** Each table the file holds, under its exported name: how many entries it has now, and which of them moved. */
+    /** Each table the file holds, under the name its lines print (a table's exported name): how many entries it has now, and which of them moved. */
     tables: readonly {
         name: string;
         count: number;

package/dist/build/writeApiGuardParams.d.ts

@@ -12,13 +12,13 @@ export type LambderApiGuardParamsFileOptions = {
     exportName?: string;
     /** The guard whose parameters the file holds, as the server declares it. A name the server declares no guard under throws. */
     guard: string;
-    /** The TypeScript module to write, exporting `guardParams`. Relative to the working directory. */
+    /** The TypeScript module to write, one export per API that declares the guard. Relative to the working directory. */
     file: string;
     /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
     check?: boolean;
     /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiGuardParams() and the guard. */
     header?: string;
-    /** End the generated statement with a semicolon. Default: true. The table itself is JSON, double quotes included, whatever the project's style: that is what lets a check read it back. */
+    /** End each generated statement with a semicolon. Default: true. The values are JSON, double quotes included, whatever the project's style: that is what lets a check read them back. */
     semicolons?: boolean;
 };
 export type LambderApiGuardParamsFileResult = {
@@ -26,7 +26,7 @@ export type LambderApiGuardParamsFileResult = {
     ok: boolean;
     /** The absolute path. */
     file: string;
-    /** True when the file was (re)written; a file that already holds this table is left untouched, however it is formatted. */
+    /** True when the file was (re)written; a file that already holds these parameters is left untouched, however it is formatted. */
     written: boolean;
     /** How many APIs declare the guard. */
     count: number;
@@ -36,8 +36,8 @@ export type LambderApiGuardParamsFileResult = {
     lines: string[];
 };
 /**
- * Writes one guard's parameters as a module of plain data, or checks the one
- * on disk, and says which APIs moved.
+ * Writes one guard's parameters as a module of one export per API, or checks
+ * the one on disk, and says which APIs moved.
  *
  * ```ts
  * import { writeApiGuardParams } from "lambder/build";
@@ -51,10 +51,11 @@ export type LambderApiGuardParamsFileResult = {
  * });
  * ```
  *
- * The module exports `guardParams`, `as const`, so a client reads its types
- * straight off it: `keyof typeof guardParams` is the APIs behind the guard,
- * and `(typeof guardParams)[K]` the literal API K declared, `true` for a
- * guard named without a parameter (the string and list forms). A parameter
- * that is not plain data fails the write, as it does for writeApiOptions.
+ * API `orders.list` exports `ordersListGuardParam`: the literal it declared,
+ * `true` for a guard named without a parameter (the string and list forms),
+ * typed LambderApiGuardParam<"orders.list", "store", literal>. Two APIs whose
+ * names export under one identifier fail the write, and so does a parameter
+ * that is not plain data, as it does for writeApiOptions, or that is null,
+ * which no tag can carry.
  */
 export declare const writeApiGuardParams: (options: LambderApiGuardParamsFileOptions) => Promise<LambderApiGuardParamsFileResult>;