lambder 8.1.1 → 8.3.1

package/CHANGELOG.md

@@ -9,6 +9,170 @@ 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.
 
+## [8.3.1] - 2026-09-27
+
+Six additions, each a thing an app otherwise writes for itself once per kind
+of token, secret, retry loop, copied declaration or store: signed claims
+tokens, one-shot secrets over a store that settles their races, the declared
+API options as generated files of plain data, a backoff timer, the digest and
+random secret behind stored secrets, and the store conformance suites for a
+store an app writes over its own database. Nothing changes on the wire, and
+every existing option keeps its meaning.
+
+### Added
+
+- **`writeApiOptions` in `lambder/build`: the declared options as a generated
+  file.** The contract carries every API's `guards`, `rateLimit` and
+  `idempotency` options as types; code that decides something at runtime with
+  them (a mock restating the server's policies, a test walking the public
+  surface, a screen asking which permission an endpoint needs) copied them by
+  hand and held the copies honest with tests that read the source.
+  `writeApiOptions({ module, exportName, file, check })` writes them once, as
+  three `as const` tables of plain data (`apiOptions`, `rateLimitPolicies`,
+  `guardDeclarations`) from the new `lambder.apiOptionEntries()`, sorted by
+  name, and `check: true` fails a stale file naming what moved per table.
+  Nothing in the file is code: a guard parameter that is not plain data fails
+  the write by API name, a policy keyed by a handler is written as `per:
+  "custom"` and no more, and a guard's schema as its input mode alone.
+  - Readers in `lambder/client`, typed to the tables' literals:
+    `LambderApisWithGuard`, `LambderApisGuardedBy`, `LambderApisWithMode`,
+    `LambderGuardParamOf` and `apiGuardParam(apiOptions, name, guard)`.
+  - `writeApiGuardParams({ module, exportName, guard, file, check })` writes
+    one guard's parameters beside it, as an `as const` table (`guardParams`)
+    of the APIs that declare the guard and what each gives it, with nothing
+    else about any API and no import: the least a browser gating a screen on
+    that guard needs, where importing `apiOptions` as a value would ship
+    every endpoint name and every guard's parameter, reasons included.
+  - `lambderMockPoliciesFrom(rateLimitPolicies, { keys })` in `lambder/mock`
+    rebuilds the policy configs `create()` takes from the table, requiring a
+    key handler for exactly the custom-keyed policies; `create()` takes a
+    `guardDeclarations` option that holds each mock guard to the server
+    guard's input mode and session requirement (`LambderMockGuardShapeOf`);
+    and an `apiOptions` option, the table itself, from which every entry's
+    guards, rate limit and idempotency are read. Given it, an entry is its
+    handler alone, a restated option is a compile error and a throw, the
+    table must cover the contract under each endpoint's mode
+    (`LambderMockApiOptionsCover`), and a `restNotMocked` answer runs under
+    the mode the table gives the name, so an unmocked session endpoint reads
+    the session first.
+  - The entry types `LambderApiOptionEntries`, `LambderApiOptionEntry`,
+    `LambderRateLimitPolicyEntry` and `LambderGuardDeclarationEntry` live in
+    `shared/wire`, with `LambderGuardRunAt`, `LambderRateLimitBudget` and
+    `LambderRateLimitChargeAt`, which moved down there unchanged.
+
+  See [the options as a generated file](./docs/apis.md#the-options-as-a-generated-file).
+
+- **`LambderSignedClaims`: signed tokens that are their own record.** One
+  instance per kind of token, built once with the secret, a version and the
+  zod schema of its claims; `sign(claims)` writes `<version>.<base64url
+  claims>.<base64url HMAC-SHA256>`, `verify(token, { now? })` answers the
+  claims or null for a forged, foreign, malformed, refused or expired token
+  alike. An optional `exp` claim in epoch seconds is judged on every verify,
+  against an injectable clock. WebCrypto only, exported from `lambder` and
+  `lambder/client` for the edge runtimes and shared backend packages that
+  verify where the secret is at hand. Beside it, `keyedDigest(secret,
+  value)`, the HMAC-SHA256 as base64url a stored secret rests as;
+  `randomSecret(bytes?)`; and `constantTimeEquals`.
+
+- **`LambderOneShotSecrets`: codes and tokens handed out once and taken back
+  once.** The code emailed to an address, the link in an activation mail, the
+  code texted before a document opens, the code read out to pair a device:
+  one life (minted, sent, stored as a digest, tried against, spent), written
+  once, over a `LambderOneShotSecretStore` that settles its races in six
+  methods. An app declares its kinds (a `code` of an alphabet and length with
+  a ceiling on tries, or a `token` redeemed by value: random bytes, or an
+  alphabet's characters for one somebody types) and names, per secret,
+  the scope it proves; `issue(kind, scope, { cooldownSeconds?, meta? })`
+  answers the plaintext exactly once, `redeem(kind, scope, candidate)` and
+  `redeemToken(kind, candidate)` answer `accepted`, `wrong` (with the tries
+  left), `expired`, `exhausted` or `none`, and `retire(scope)` ends what the
+  scope holds. One record is live per scope; a cooldown is a condition on
+  the issuing write; a token's digest is claimed by one scope at a time in
+  that same write, and a secret drawn onto a digest another scope holds is
+  drawn again (up to five times), so two scopes that drew the same short
+  code never redeem each other's; a try is counted in the write that reads
+  the digest; a redemption is a conditional consume.
+  `LambderDdbOneShotSecretStore` keeps a code as one item under `OTS#` in
+  the policy table and a token as two, written in one transaction, and sends
+  a write DynamoDB refused for a concurrent transaction on its item again, up
+  to three times; `LambderMemoryOneShotSecretStore` keeps the same in a map, and
+  `lambderOneShotSecretStoreConformance` holds both, and an app's own store,
+  to one set of rules. The class sits in a new `src/secrets/` layer beside
+  `session/`.
+
+- **`LambderBackoffTimer`: waiting longer after each failure, once.** One
+  pending wait at a time: `retry(run)` and `wait(signal?)` climb a jittered
+  ladder (`baseMs` the shortest wait, `maxMs` the longest, `factor`,
+  `jitter`), `after(ms, run)` waits off
+  it, `reset()` and `cancel()`; `wait` rejects with the signal's reason on
+  abort and with an Error when dropped, so an await on it always settles.
+  Exported from `lambder` and `lambder/client`.
+
+  See [Secrets and retries](./docs/secrets.md).
+
+- **Store conformance suites in `lambder/testing`.** The rules each store
+  interface promises its engine were asserted in Lambder's own test suite,
+  where only Lambder's stores could meet them; a store an app writes over its
+  own database had nothing to hold it to the same rules. They are now
+  exported, one suite per interface: `lambderSessionStoreConformance`,
+  `lambderIdempotencyStoreConformance`, `lambderRateLimiterConformance` and
+  `lambderOneShotSecretStoreConformance`. Each takes the runner's own `it`
+  and `expect` (any jest-style `expect`; Lambder imports no runner) and a
+  `create` that builds a store for one case, handed the case's clock as
+  `now`. The one-shot suite also takes what a store over existing rows needs
+  in place of its defaults: two `scopes` it can hold, the kind it keeps for
+  each shape it holds (`kinds: { code?, token? }`, which decides whether the
+  cases about tries or the ones about digests run), the `meta`, and the
+  `lifetimeSeconds` it derives an expiry from. Among its rules: two issues
+  racing for one scope leave exactly one live record, two scopes racing for
+  one token digest leave it with exactly one, and `attempt` and `consume`
+  name a record by its scope and id together, so a record of another scope
+  is never the one named. Lambder's memory and DynamoDB stores run through
+  the same suites.
+
+  See [A store of your own](./docs/testing.md#a-store-of-your-own).
+
+### Changed
+
+- **`LambderUploadRunner` waits on a `LambderBackoffTimer` between tries at
+  storage.** The ladder is the timer's: each wait is `baseDelayMs` plus a
+  random share of a ceiling that starts at `baseDelayMs` and doubles per
+  failed attempt, the whole never past `maxDelayMs`. The first wait is
+  unchanged (between the base and twice it); a later one may be shorter than
+  before, since the ceiling now counts from the base rather than from twice
+  it.
+- **The session crypto shares its HMAC and its constant-time comparison** with
+  the new module through `shared/util/LambderTextDigest.ts` rather than
+  keeping copies of its own. Behaviour is unchanged.
+
+## [8.1.2] - 2026-09-26
+
+### Fixed
+
+- **`writeApiContract` names no longer follow the order APIs are registered
+  in.** Two types that want one name (an interface `Row` in two modules) were
+  told apart by a number given in the order the printer met them, so
+  reordering registrations, or adding an API that reaches one of them first,
+  swapped `Row` and `Row2` and reported every API using either as changed.
+  The printer now finds every declaration first and numbers them by where
+  each is declared, the one declared first (by file, then position) keeping
+  the name, and a number never takes the name another type is declared
+  under. A file already written may be renamed once, the first time it is
+  written with this version.
+- **`LambderUploadRunner` randomises its first wait too.** The ceiling of the
+  first wait before trying storage again was the base itself, so browsers
+  dropped together all came back exactly `baseDelayMs` later. Each wait is
+  now between `baseDelayMs` and twice it, doubling with every failed attempt
+  up to `maxDelayMs`.
+- **`LambderUploadRunner` renews a ticket on `ExpiredToken`,** which S3
+  answers when the temporary credentials that signed the ticket ran out
+  before the ticket did. It is renewed like an expired ticket, at once and
+  spending no attempt; before, the upload failed as `storageRejected`.
+- **`LambderUploadRunner` no longer holds the file's bytes through the
+  upload.** The buffer it hashes, as large as the file, was kept in a local
+  for the whole post and every retry; it is now read straight into the
+  digest.
+
 ## [8.1.1] - 2026-09-26
 
 Two additions, and three breaking changes a minor line carries here on

package/README.md

@@ -113,10 +113,10 @@ The package ships five 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/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 |
-| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiContract`: the contract as plain types a client compiles instead of the server |
+| `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 |
 
 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
@@ -126,14 +126,15 @@ tree-shaking.
 Source layout mirrors this: `src/api/` (the isomorphic API core: request,
 answer, envelope, pipeline, and the declarative policies the pipeline runs),
 `src/core/` (the Lambda server adapter: routes, files, hooks, finalization),
-`src/session/` (the session manager, controller and crypto), `src/stores/`
+`src/session/` (the session manager, controller and crypto), `src/secrets/`
+(one-shot secrets over their store), `src/stores/`
 (every store and file-source implementation, DynamoDB and in-memory alike,
 and the helpers the two caches share), `src/client/`,
 `src/invoke/` (the lambda-to-lambda caller and the in-process handler
-transport), `src/mock/` (the mock runtime), `src/testing/` (the test app),
+transport), `src/mock/` (the mock runtime), `src/testing/` (the test app and the store conformance suites),
 `src/build/` (what a generator script runs at build time), and `src/shared/`
 (isomorphic modules every entry re-exports, grouped into `wire/` for the
-format both sides speak, `contracts/` for the five store and source
+format both sides speak, `contracts/` for the six store and source
 interfaces, `transport/` for the caller-to-server seam, and `util/` for
 helpers).
 Directories are layers and imports only ever point down;
@@ -156,7 +157,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 |
+| [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, store conformance suites |
 | [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` |

package/dist/api/LambderApiGuards.d.ts

@@ -37,22 +37,8 @@ type LambderGuardAnswerCheck<TOutput> = [
 type LambderGuardOf<TOutput, TGuard> = LambderGuardAnswerCheck<TOutput> extends LambderGuardMustNotAnswer ? LambderGuardMustNotAnswer : TGuard;
 /** One guard handler: the adapter's context, the validated input slice (undefined in the no-input mode), and the per-API parameter. */
 type LambderGuardHandler<TCtx, TPayload, TParam, TOutput> = (ctx: TCtx, payload: TPayload, param: TParam) => TOutput | Promise<TOutput>;
-/**
- * When a guard runs, relative to the API's input validation.
- *
- * - "beforeInputValidation" (default): an unauthorized caller learns nothing
- *   about the input, and no async refinement in the schema runs for it.
- * - "afterInputValidation": for a guard that spends something on the
- *   request, such as a single-use captcha token, which a request refused for
- *   a mistyped field would otherwise waste. The API's input schema then runs
- *   for callers this guard would refuse, so keep lookups (an "email is free"
- *   refinement) out of it, in the handler.
- *
- * Guards run in their declared order within each, and the limits keyed by
- * caller data are charged after both unless their policy says otherwise
- * (LambderRateLimitChargeAt).
- */
-export type LambderGuardRunAt = "beforeInputValidation" | "afterInputValidation";
+import type { LambderGuardRunAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderGuardRunAt };
 /** Where in the call a guard runs: see LambderGuardRunAt. */
 export type LambderGuardPlacement = {
     /** Default: "beforeInputValidation". */
@@ -331,4 +317,3 @@ export declare class LambderApiGuardsEngine {
      */
     run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace, runAt: LambderGuardRunAt): Promise<void>;
 }
-export {};

package/dist/api/LambderApiRateLimits.d.ts

@@ -78,34 +78,8 @@ export type LambderRateLimitKeyBuilder<TCtx> = {
 export declare const lambderRateLimitKeyBuilder: <TCtx>() => LambderRateLimitKeyBuilder<TCtx>;
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
 export type LambderRateLimitPer<TCtx = any> = "ip" | "session" | LambderRateLimitKeyFn<any, TCtx>;
-/**
- * What one budget spans:
- *
- * - "perApi" (default): every API referencing the policy gets its own
- *   counter, so the windows are a per-API ceiling (three APIs referencing a
- *   60/min policy allow one subject 180/min in total). An API may tune the
- *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
- * - "perPolicy": every API referencing the policy shares ONE counter, so the
- *   windows are one combined budget (e.g. one per-email allowance across
- *   send, register, and reset). The policy IS the group: to give user APIs
- *   and report APIs separate shared budgets, declare two policies.
- */
-export type LambderRateLimitBudget = "perApi" | "perPolicy";
-/**
- * When a custom-keyed policy is charged, relative to the guards and the input
- * schema.
- *
- * - "afterGuards" (default): after every guard and the input schema passed.
- *   The key is a value the caller chose (an email in the payload), so a
- *   caller who never passes a captcha guard cannot spend a victim's budget
- *   and lock them out of reset, register and send-code.
- * - "beforeGuards": before the guards and the input schema, so an attempt
- *   they refuse is counted too. For a limit on guessing a secret a guard or
- *   the schema checks (a one-time code checked by a guard, keyed per email):
- *   charged after them, a wrong guess is refused before it is ever counted.
- *   Pair it with an IP limit, since anyone may spend this budget.
- */
-export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
+import type { LambderRateLimitBudget, LambderRateLimitChargeAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderRateLimitBudget, LambderRateLimitChargeAt };
 /**
  * A named rate-limit policy: fixed windows, the key one counter tracks, and
  * what one budget spans.
@@ -357,4 +331,3 @@ export declare class LambderApiRateLimitsEngine {
      */
     private requestKeyOf;
 }
-export {};

package/dist/build/ContractTypePrinter.d.ts

@@ -22,18 +22,40 @@ export declare class ContractTypePrinter {
     private readonly program;
     private readonly checker;
     private readonly style;
-    private readonly failures;
-    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
-    private readonly declarations;
+    private failures;
+    /** Every declaration by the type it stands for. */
+    private declarations;
+    /** The name each declaration is printed under, settled from all of them; empty on the pass that finds them. */
+    private settledNames;
     /** Names a declaration may not take: the default library's, and the contract's own. */
-    private readonly takenNames;
+    private readonly reservedNames;
     /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
     private readonly inProgress;
     /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
     private readonly exactOptionalProperties;
     constructor(ts: typeof import("typescript"), program: ts.Program, checker: ts.TypeChecker, style: ContractPrintStyle, contractName: string);
-    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    /**
+     * Prints each member of the contract type, sorted by name, and every
+     * declaration they refer to.
+     *
+     * In two passes: the first finds every type that needs a declaration,
+     * and the second prints with their names settled from all of them. Named
+     * as the printer met them, two types wanting one name would trade it
+     * whenever the APIs were registered in another order, or a union's
+     * members created in another, and the file would move with no API
+     * changed.
+     */
     printContract(contract: ts.Type): PrintedContract;
+    /**
+     * A name for every declaration the first pass found. Of the types that
+     * want one name, the one declared first (by file, then position) keeps
+     * it, and the others take the lowest free number after it once every
+     * type has claimed its own name, so a number never takes the name
+     * another type is declared under. Types declared at one place (two
+     * instantiations of a generic) keep the order the entries reached them
+     * in, by entry name.
+     */
+    private settleNames;
     /**
      * `label value`, with a union too long for one line starting on the next
      * line, one member per line: what a property, an index signature and a
@@ -43,16 +65,25 @@ export declare class ContractTypePrinter {
     private print;
     /** A union, an intersection or an object: printed in place, or as a reference to a declaration of its own. */
     private printComposite;
-    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
-    private declaredNameOf;
+    /** A type's declaration, under the name it is settled to once the first pass has settled them. */
+    private declare;
+    /** The name a type is declared under and where, when it is one to print as a declaration: non-generic, and not the default library's. */
+    private ownDeclarationOf;
+    /** A symbol's name to declare a type under, and where the symbol is declared. */
+    private declaredAs;
+    /** Where a symbol is declared, as text that orders by file and then position; empty for one declared nowhere. */
+    private originOf;
     /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
     private nameOf;
     /**
      * A name for a type that refers to itself and has none of its own: what it
      * instantiates followed by its arguments (a JSON mapping of a Tree is
      * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     * Its origin is where what it instantiates is declared, then where each
+     * argument is, so two instantiations named alike are told apart by their
+     * arguments.
      */
-    private recursiveNameOf;
+    private recursiveDeclarationOf;
     private printStructure;
     private printUnion;
     private printUnionOf;
@@ -80,6 +111,5 @@ export declare class ContractTypePrinter {
     private wrapped;
     keyOf(name: string): string;
     private quoted;
-    private takeName;
     private fail;
 }

package/dist/build/ContractTypePrinter.js

@@ -37,10 +37,12 @@ export class ContractTypePrinter {
     checker;
     style;
     failures = [];
-    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    /** Every declaration by the type it stands for. */
     declarations = new Map();
+    /** The name each declaration is printed under, settled from all of them; empty on the pass that finds them. */
+    settledNames = new Map();
     /** Names a declaration may not take: the default library's, and the contract's own. */
-    takenNames = new Set();
+    reservedNames = new Set();
     /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
     inProgress = new Set();
     /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
@@ -50,7 +52,7 @@ export class ContractTypePrinter {
         this.program = program;
         this.checker = checker;
         this.style = style;
-        this.takenNames.add(contractName);
+        this.reservedNames.add(contractName);
         this.exactOptionalProperties = !!program.getCompilerOptions().exactOptionalPropertyTypes;
         // A declaration named after a global the printed text refers to by
         // name (Date) would shadow it.
@@ -60,20 +62,65 @@ export class ContractTypePrinter {
             for (const statement of sourceFile.statements) {
                 if ((ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isModuleDeclaration(statement))
                     && statement.name && ts.isIdentifier(statement.name))
-                    this.takenNames.add(statement.name.text);
+                    this.reservedNames.add(statement.name.text);
             }
         }
     }
-    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    /**
+     * Prints each member of the contract type, sorted by name, and every
+     * declaration they refer to.
+     *
+     * In two passes: the first finds every type that needs a declaration,
+     * and the second prints with their names settled from all of them. Named
+     * as the printer met them, two types wanting one name would trade it
+     * whenever the APIs were registered in another order, or a union's
+     * members created in another, and the file would move with no API
+     * changed.
+     */
     printContract(contract) {
-        const entries = this.checker.getPropertiesOfType(contract)
-            .map((entry) => ({ name: entry.name, text: this.print(this.checker.getTypeOfSymbol(entry), this.keyOf(entry.name)).text }))
-            .sort((a, b) => byCodeUnits(a.name, b.name));
+        const members = [...this.checker.getPropertiesOfType(contract)].sort((a, b) => byCodeUnits(a.name, b.name));
+        const printEntries = () => members.map((entry) => ({ name: entry.name, text: this.print(this.checker.getTypeOfSymbol(entry), this.keyOf(entry.name)).text }));
+        printEntries();
+        this.settledNames = this.settleNames();
+        this.failures = [];
+        this.declarations = new Map();
+        const entries = printEntries();
         const declarations = [...this.declarations.values()]
             .map(({ name, text }) => ({ name, text: text ?? "never" }))
             .sort((a, b) => byCodeUnits(a.name, b.name));
         return { entries, declarations, failures: this.failures };
     }
+    /**
+     * A name for every declaration the first pass found. Of the types that
+     * want one name, the one declared first (by file, then position) keeps
+     * it, and the others take the lowest free number after it once every
+     * type has claimed its own name, so a number never takes the name
+     * another type is declared under. Types declared at one place (two
+     * instantiations of a generic) keep the order the entries reached them
+     * in, by entry name.
+     */
+    settleNames() {
+        const wanting = [...this.declarations].sort(([, a], [, b]) => byCodeUnits(a.base, b.base) || byCodeUnits(a.origin, b.origin));
+        const taken = new Set(this.reservedNames);
+        const settled = new Map();
+        const numbered = [];
+        for (const [type, { base }] of wanting) {
+            if (taken.has(base)) {
+                numbered.push([type, base]);
+                continue;
+            }
+            taken.add(base);
+            settled.set(type, base);
+        }
+        for (const [type, base] of numbered) {
+            let suffix = 2;
+            while (taken.has(`${base}${suffix}`))
+                suffix++;
+            taken.add(`${base}${suffix}`);
+            settled.set(type, `${base}${suffix}`);
+        }
+        return settled;
+    }
     /**
      * `label value`, with a union too long for one line starting on the next
      * line, one member per line: what a property, an index signature and a
@@ -142,20 +189,16 @@ export class ContractTypePrinter {
         const known = this.declarations.get(type);
         if (known)
             return atom(known.name);
-        const ownName = this.declaredNameOf(type);
-        if (ownName !== undefined) {
+        const own = this.ownDeclarationOf(type);
+        if (own) {
             // Registered before the body is printed, so a reference to itself
             // inside the body finds the name.
-            const declaration = { name: this.takeName(ownName), text: null };
-            this.declarations.set(type, declaration);
+            const declaration = this.declare(type, own);
             declaration.text = this.printStructure(type, path).text;
             return atom(declaration.name);
         }
-        if (this.inProgress.has(type)) {
-            const declaration = { name: this.takeName(this.recursiveNameOf(type)), text: null };
-            this.declarations.set(type, declaration);
-            return atom(declaration.name);
-        }
+        if (this.inProgress.has(type))
+            return atom(this.declare(type, this.recursiveDeclarationOf(type)).name);
         this.inProgress.add(type);
         const printed = this.printStructure(type, path);
         this.inProgress.delete(type);
@@ -166,11 +209,17 @@ export class ContractTypePrinter {
         recursive.text = printed.text;
         return atom(recursive.name);
     }
-    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
-    declaredNameOf(type) {
+    /** A type's declaration, under the name it is settled to once the first pass has settled them. */
+    declare(type, { base, origin }) {
+        const declaration = { base, origin, name: this.settledNames.get(type) ?? base, text: null };
+        this.declarations.set(type, declaration);
+        return declaration;
+    }
+    /** The name a type is declared under and where, when it is one to print as a declaration: non-generic, and not the default library's. */
+    ownDeclarationOf(type) {
         const { ObjectFlags, TypeFlags } = this.ts;
         if (type.aliasSymbol) {
-            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.nameOf(type.aliasSymbol);
+            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.declaredAs(type.aliasSymbol);
         }
         if (!(type.flags & TypeFlags.Object))
             return undefined;
@@ -182,7 +231,17 @@ export class ContractTypePrinter {
         // it instead, and are printed in place.
         if (objectFlags & ObjectFlags.Reference && (type.target !== type || type.typeParameters?.length))
             return undefined;
-        return this.isDefaultLibrary(type.symbol) ? undefined : this.nameOf(type.symbol);
+        return this.isDefaultLibrary(type.symbol) ? undefined : this.declaredAs(type.symbol);
+    }
+    /** A symbol's name to declare a type under, and where the symbol is declared. */
+    declaredAs(symbol) {
+        const base = this.nameOf(symbol);
+        return base === undefined ? undefined : { base, origin: this.originOf(symbol) };
+    }
+    /** Where a symbol is declared, as text that orders by file and then position; empty for one declared nowhere. */
+    originOf(symbol) {
+        const declaration = symbol?.declarations?.[0];
+        return declaration ? `${declaration.getSourceFile().fileName}\0${String(declaration.pos).padStart(10, "0")}` : "";
     }
     /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
     nameOf(symbol) {
@@ -195,8 +254,11 @@ export class ContractTypePrinter {
      * A name for a type that refers to itself and has none of its own: what it
      * instantiates followed by its arguments (a JSON mapping of a Tree is
      * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     * Its origin is where what it instantiates is declared, then where each
+     * argument is, so two instantiations named alike are told apart by their
+     * arguments.
      */
-    recursiveNameOf(type) {
+    recursiveDeclarationOf(type) {
         const { ObjectFlags, TypeFlags } = this.ts;
         let instantiated;
         if (type.aliasSymbol) {
@@ -209,11 +271,14 @@ export class ContractTypePrinter {
         }
         const base = instantiated && this.nameOf(instantiated.symbol);
         if (!instantiated || !base)
-            return "RecursiveType";
+            return { base: "RecursiveType", origin: this.originOf(type.symbol) };
         const argumentNames = instantiated.typeArguments
             .map((argument) => (argument.aliasSymbol && this.nameOf(argument.aliasSymbol)) ?? (argument.symbol && this.nameOf(argument.symbol)) ?? this.checker.typeToString(argument))
             .filter((name) => IDENTIFIER.test(name));
-        return `${base}${argumentNames.map((name) => name[0].toUpperCase() + name.slice(1)).join("")}`;
+        return {
+            base: `${base}${argumentNames.map((name) => name[0].toUpperCase() + name.slice(1)).join("")}`,
+            origin: [instantiated.symbol, ...instantiated.typeArguments.map((argument) => argument.aliasSymbol ?? argument.symbol)].map((symbol) => this.originOf(symbol)).join("\n"),
+        };
     }
     printStructure(type, path) {
         const { TypeFlags } = this.ts;
@@ -388,13 +453,6 @@ export class ContractTypePrinter {
         // never the tail of an escaped backslash.
         return `'${doubleQuoted.slice(1, -1).replace(/\\"/g, "\"").replace(/'/g, "\\'")}'`;
     }
-    takeName(base) {
-        let name = base;
-        for (let suffix = 2; this.takenNames.has(name); suffix++)
-            name = `${base}${suffix}`;
-        this.takenNames.add(name);
-        return name;
-    }
     fail(path, reason) {
         this.failures.push(`${path}: ${reason}`);
         return atom("unknown");

package/dist/build/generatedTables.d.ts

@@ -0,0 +1,72 @@
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
+import { type LambderModuleLocation } from "./moduleLocation.js";
+/** What the generators read the options from: a Lambder instance, or anything else that reports them the same way. */
+export type LambderApiOptionsSource = {
+    apiOptionEntries(): LambderApiOptionEntries;
+};
+/** Which names of one table moved: entries that changed, entries the file did not have, entries the file had and the instance no longer reports. */
+export type LambderNameChanges = {
+    changed: string[];
+    added: string[];
+    removed: string[];
+};
+/** Imports the module, finds the instance under its export, and answers what it reports. `generator` names the caller in the errors. */
+export declare const loadApiOptionEntries: (location: {
+    module: LambderModuleLocation;
+    exportName?: string;
+}, generator: string) => Promise<LambderApiOptionEntries>;
+/** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
+export declare const readGeneratedTable: (contents: string, exportName: string) => Record<string, unknown> | null;
+/** How one table's entries differ from the ones a file held, by name, compared as canonical JSON so key order is not a change. */
+export declare const nameChangesOf: (current: Record<string, unknown>, previous: Record<string, unknown>) => LambderNameChanges;
+/** The opening comment of a generated file, one `//` line per line of the header. */
+export declare const headerLinesOf: (header: string) => string[];
+/**
+ * One table as a statement: its doc comment, the `// prettier-ignore` that
+ * keeps a formatter off the JSON a check reads back, and the table itself,
+ * `as const` with whatever `satisfies` clause the caller gives.
+ */
+export declare const tableStatementLines: (table: {
+    name: string;
+    doc: string;
+    value: unknown;
+    satisfies?: string;
+    semicolon: string;
+}) => string[];
+/**
+ * The end of a generator's run. With `check`, it answers whether the file
+ * holds what the instance reports and writes nothing. Otherwise it writes
+ * the file unless it already holds these tables, however it is formatted, so
+ * a watcher or an incremental build sees no change where there is none (a
+ * change of header or semicolons shows the next time a table changes).
+ * Either way the lines say what moved.
+ */
+export declare const settleGeneratedFile: (run: {
+    /** The file as the caller named it, for the lines. */
+    name: string;
+    /** The absolute path. */
+    file: string;
+    check: boolean | undefined;
+    /** The file's text before this run, or null when there was none. */
+    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. */
+    tables: readonly {
+        name: string;
+        count: number;
+        changes: LambderNameChanges;
+    }[];
+    /** What the tables hold, for the lines: "6 APIs, 4 policies, 5 guards". */
+    held: string;
+    /** What the file holds when it is as written, for the line when it is not: "the three tables". */
+    tablesNoun: string;
+    /** The line when nothing moved: "no options changed". */
+    unmovedLine: string;
+    /** The file's contents, rendered only when it is written. */
+    render: () => string;
+}) => {
+    ok: boolean;
+    written: boolean;
+    lines: string[];
+};