lambder 11.1.1 → 13.0.1

package/CHANGELOG.md

@@ -9,6 +9,223 @@ 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
+instance's `defineApi`, gathers them into named groups with `defineApiGroup`,
+and registers every group in one `registerApiGroups()` call. An endpoint's
+guards decide its mode, its name is `group.action`, a call goes to
+`{apiPath}/{group}/{action}`, and every caller reaches it through its group:
+`caller.orders.place(input)`.
+
+### Changed (breaking)
+
+- **`addApi` and `addSessionApi` are replaced by `defineApi`,
+  `defineApiGroup` and `registerApiGroups`.** `defineApi(options, handler)`
+  takes the options and the handler `addApi` took, and registers nothing by
+  itself; `defineApiGroup(name, { action: declaration })` gathers a group
+  (`defineApiGroup(name, partA, partB)` for one declared across files, an
+  action two parts declare being refused); `registerApiGroups(...groups)`
+  registers them and returns the instance typed with their contract, one flat
+  mapped type. The three builders are arrow properties, so an app hands them
+  out with `export const { defineApi, defineApiGroup, lazyApiGroup } =
+  lambderApp;`.
+  - To move: turn each chain of `addApi`/`addSessionApi` calls into a group of
+    `defineApi` declarations and register the groups in one call. Handler
+    bodies do not change.
+- **An endpoint's mode is its guards'.** An endpoint declaring a guard that
+  needs a session (`session: true`) is a session endpoint: its session is read
+  first, a call without one is answered `sessionExpired`, and its handler's
+  `ctx.session` is typed present. Every other endpoint is public. A
+  per-session rate limit on an endpoint none of whose guards needs a session,
+  and a session guard on an instance created without the `session` option,
+  are compile errors and registration errors.
+  - To move: give an endpoint that was an `addSessionApi` and declares no
+    session guard one: a no-op `lambderGuard({ session: true, handler: () => {} })`
+    where the session is its whole authorization.
+- **`requireSessionApiGuards` and `requirePublicApiGuards` are replaced by
+  `requireApiGuards`**, which makes `guards` a required field of every
+  endpoint.
+- **An endpoint is named `group.action`**, both identifiers (a letter, then
+  letters, digits or underscores). A group may not take the name of a
+  caller's public member or one a runtime asks of any object
+  (`LAMBDER_RESERVED_GROUP_NAMES`), nor an action one a function or any
+  object answers for (`then`, `call`, `toString`, `valueOf`:
+  `LAMBDER_RESERVED_ACTION_NAMES`), so converting a group to a string calls
+  no endpoint. The callers keep their state in
+  `#private` fields, so a group may take any name their public members leave
+  free (`transport`, `client`, `headers`).
+- **A call is `POST {apiPath}/{group}/{action}`**, the envelope in the body
+  and no `apiName` in it, so a gateway, a CDN and a log can meter, limit and
+  read calls per endpoint. `buildTransportEnvelope` writes no `apiName`, and
+  `readApiEnvelope(post, info, apiName)` takes the name from the path. A JSON
+  POST to `apiPath` itself naming an endpoint in its body is a page built
+  before endpoints had paths, and is answered `versionExpired`, which reloads
+  it.
+  - To move: an API Gateway route or a CloudFront behavior that matches
+    `apiPath` exactly (`POST /api`) now misses every call; widen it to what
+    is under it (`/api/*`, `ANY /api/{proxy+}`). A cookie an API handler sets
+    with a raw `Set-Cookie` header and no `Path` now defaults to the call's
+    directory (`/api/orders`) rather than `/`, in a browser as in the cookie
+    jar; `ctx.setCookie` and the session cookies always write `Path=/`.
+- **A request under `apiPath` that nothing matched is the API's**: a GET to a
+  call path, or a path of another depth, is answered as an unknown API rather
+  than by the public files, the shell or the route fallback. A root `apiPath`
+  shares every path with the site, so there only `apiPath` itself and the
+  calls are.
+- **The instance takes one type parameter**, `Lambder<TApp, TContract>`,
+  where `TApp` is `LambderAppTypes` (the session data, policies, guards,
+  idempotency, the guard requirement, sessions and the refusal vocabulary),
+  in place of ten positional generics. It is readable as the type-only
+  `AppTypes` property beside `ApiContract`.
+- **`use(plugin)` registers routes, hooks and actions**, and hands back the
+  same instance: endpoints are registered as groups, so a plugin adds nothing
+  to the contract.
+- **A `registerApiGroups()` call's groups take their place in the first-match
+  chain where the call stands**, as each `addApi` did: a route registered
+  before them sees their calls first, one registered after them never does.
+  The beforeRender hooks run before a lazy group loads, and a call to an
+  action its group does not have is answered as an unmatched API call, the
+  fallback hooks first.
+- **`apiOptionEntries()` is asynchronous**, as `apiSignatures()` and
+  `apiSignatureEntries()` are: all three load lazy groups first.
+- **The mock's `publicApi` and `sessionApi` are replaced by `api`, and
+  `sessionNotMocked` by `notMocked`.** An entry's mode is the `apiOptions`
+  table's when the mock was given it, and otherwise the server's rule applied
+  to the guards the entry restates. `LambderMockPublicNames` and
+  `LambderMockSessionNames` are removed. Every session endpoint must name at
+  least one mock guard declared `session: true`, a compile error at the
+  `guards` option otherwise (`LambderMockSessionGuardsCheck`), and a session
+  endpoint left unmocked on a mock without the table restates its guards,
+  `notMocked(name, { reason, guards })`, so a signed-out call answers
+  `sessionExpired` as the server does. `lambderMockInvokeTransport(mockApp,
+  { apiPath })` answers what the callee's server reads as a call, a JSON POST
+  to a call path under `apiPath` (default `"/api"`), and 404s anything else.
+- **`LambderMergeContract` is removed**, and `LambderAllowedGuardNames`,
+  `LambderParamlessGuardNames`, `LambderGuardsOption`,
+  `LambderAllowedPolicyNames` and `LambderRateLimitOption` lose their second
+  type parameter: every guard and every policy with a `per` may be declared
+  on any endpoint, a session guard making it a session one.
+
+### Added
+
+- **Every caller reaches an endpoint through its group.**
+  `caller.orders.place(input)` is `caller.api("orders.place", input)`, and
+  `caller.orders.place.outcome(input)` its `apiOutcome`, on `LambderCaller`,
+  `LambderInvokeCaller` and the test visitor alike. The groups are read off
+  the contract's type, so a client that imports its contract as a type ships
+  no endpoint list. A name that is not `group.action` is refused before it is
+  sent.
+- **Lazy groups.** `lazyApiGroup(name, () => import(...).then((m) => m.group))`
+  registers a group loaded on the first call to one of its endpoints, so a
+  cold start parses none of it until then; `loadApiGroups()` loads every one,
+  for a build step or a boot check. A hook that answers a call spares it the
+  import; one that throws a refusal, or charges a per-API budget, loads the
+  group, so the refusal is checked and the budget counted against the
+  endpoint called, as for an eager group. A load that fails is forgotten, and
+  the next call tries again.
+- **Compile-time registration checks**: a group typed `any`, a lazy group
+  loading one, or a group whose endpoints are (its endpoints would be `any` to
+  every client), and a group name given twice, are refused where
+  `registerApiGroups()` is written, and a group registration is atomic:
+  refused anywhere, it leaves the instance as it was. A lazy group written
+  where a list of groups is expected (a `satisfies`, an annotated array)
+  keeps its loaded group's type, rather than taking the expected `any`.
+- **`beforeCall` on `LambderInvokeCaller`**: a check run before every call,
+  `api()`, `apiOutcome()`, a group's call and `request()` alike, before
+  anything is built or sent. What it throws is thrown to the caller, from
+  `apiOutcome()` too, and `onFailure` is not told, since nothing was sent. It
+  is where a rule the calling code must keep goes, such as never calling out
+  while a database transaction is open (`LambderInvokeCallCheck`).
+- **What registering endpoints costs the compiler grows linearly**: each
+  declaration is typed on its own, and eight hundred endpoints cost under four
+  times what two hundred do, which the type-cost suite holds.
+- Exports: `apiCallPath`, `apiNameOfCallPath`, `splitApiName`, `isGroupName`,
+  `isActionName`, `LAMBDER_API_NAME_SEGMENT`, `LAMBDER_CALLER_MEMBER_NAMES`,
+  `LAMBDER_RESERVED_GROUP_NAMES`, `LAMBDER_RESERVED_ACTION_NAMES`, and the
+  types of declarations, groups and group calls (see
+  [Exports](./docs/exports.md#endpoints-declarations-groups-and-names)).
+
 ## [11.1.1] - 2026-09-30
 
 A minor for an app whose shell files sit behind a shared cache: a file whose

package/README.md

@@ -10,25 +10,30 @@ per-handler boilerplate.
 import { initLambder, LambderLocalFileSource, LambderDdbSessionStore } from "lambder";
 import { z } from "zod";
 
-const lambder = initLambder<SessionData>().create({
+const app = initLambder<SessionData>().create({
     apiPath: "/api",
     files: new LambderLocalFileSource({ root: "./public" }),
     session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: process.env.SESSION_SALT! },
-}).addApi("getCompany", {
-    input: z.object({ slug: z.string() }),
-    output: z.object({ id: z.string(), name: z.string() }),
-}, async ({ apiPayload }) => await loadCompany(apiPayload.slug));
+});
 
+const companyApis = app.defineApiGroup("companies", {
+    get: app.defineApi({
+        input: z.object({ slug: z.string() }),
+        output: z.object({ id: z.string(), name: z.string() }),
+    }, async ({ apiPayload }) => await loadCompany(apiPayload.slug)),
+});
+
+export const lambder = app.registerApiGroups(companyApis);
 export type ApiContractType = typeof lambder.ApiContract;
 export const handler = lambder.getHandler();
 ```
 
-A handler returns its output, which is parsed through the output schema before
-it is sent, and says no by throwing a refusal: `ctx.refuse()`, typed to the
-codes the API declares, or `refuse()` from anywhere. Registration chains onto the
-creation call: every `addApi` returns an instance carrying the contract so
-far, so the whole backend is one declaration and `lambder.ApiContract` is the
-accumulated type.
+An endpoint is a value: declared with `defineApi`, gathered into a named
+group, registered with its groups in one call, and called at
+`/api/companies/get`. A handler returns its output, which is parsed through
+the output schema before it is sent, and says no by throwing a refusal:
+`ctx.refuse()`, typed to the codes the API declares, or `refuse()` from
+anywhere. Its guards say who may call it, and so whether it needs a session.
 
 The frontend imports that contract type and gets autocomplete, typed payloads
 and typed results with no hand-written client:
@@ -38,7 +43,7 @@ import { LambderCaller } from "lambder/client";
 import type { ApiContractType } from "./backend/handler";
 
 const caller = new LambderCaller<ApiContractType>({ apiPath: "/api" });
-const company = await caller.api("getCompany", { slug: "acme" });
+const company = await caller.companies.get({ slug: "acme" });
 ```
 
 ## Features
@@ -60,7 +65,8 @@ const company = await caller.api("getCompany", { 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
@@ -74,6 +80,10 @@ const company = await caller.api("getCompany", { 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.
@@ -130,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
@@ -166,7 +176,7 @@ guide that matches what you are building. The full index lives in
 | [Getting started](./docs/getting-started.md) | The three-step path from a first API to a typed frontend call |
 | [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
 | [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, crash reporting, and non-HTTP invocations |
-| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
+| [APIs and refusals](./docs/apis.md) | `defineApi`, groups and lazy groups, the mode the guards decide, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
 | [Responses](./docs/responses.md) | The render context and its response tools (headers, cookies, log entries), the response builder routes and hooks use, compression, ETag and the size cap |
 | [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 |

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/LambderApiDeclarations.d.ts

@@ -0,0 +1,194 @@
+import type { z } from "zod";
+import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderApiMode, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue, LambderRefusalsOptionValue } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderApiRateLimitPolicyConfig, LambderPolicyPerOf } from "./LambderApiRateLimits.js";
+import type { LambderRefusalVocabulary } from "./LambderApiRefusals.js";
+import { type LambderReservedActionName, type LambderReservedGroupName } from "../shared/wire/LambderApiNames.js";
+/**
+ * What an instance's declarations are typed against, fixed at create(): the
+ * session data, the rate-limit policies, the guards (as LambderGuardMetaMap
+ * records them), whether idempotency is configured, whether every endpoint
+ * must declare a guard, whether sessions are configured, and the refusal
+ * vocabulary with whether every refusal must name a code.
+ */
+export type LambderAppTypes = {
+    session: unknown;
+    policies: Record<string, LambderApiRateLimitPolicyConfig>;
+    guards: Record<string, any>;
+    idempotency: boolean;
+    guardsRequired: boolean;
+    sessions: boolean;
+    refusals: LambderRefusalVocabulary;
+    refusalCodesRequired: boolean;
+};
+/** The types of an instance built without create(): no policies, guards or vocabulary, sessions allowed. */
+export type LambderPlainAppTypes<TSession = any> = {
+    session: TSession;
+    policies: {};
+    guards: {};
+    idempotency: false;
+    guardsRequired: false;
+    sessions: true;
+    refusals: {};
+    refusalCodesRequired: false;
+};
+/** The guards among the names an endpoint declares that need a session (`session: true`). */
+export type LambderSessionGuardNamesIn<TGuards, TGuardsOpt> = {
+    [K in LambderGuardNamesIn<TGuardsOpt> & keyof TGuards]: TGuards[K] extends {
+        session: true;
+    } ? K : never;
+}[LambderGuardNamesIn<TGuardsOpt> & keyof TGuards];
+/**
+ * An endpoint's mode, from the guards it declares: "session" when any of
+ * them needs a session, "public" otherwise. The guard is the one place the
+ * endpoint says who may call it, and a session is part of that answer, so
+ * nothing else states the mode and nothing can disagree with it.
+ */
+export type LambderApiModeOf<TGuards, TGuardsOpt> = [
+    LambderSessionGuardNamesIn<TGuards, TGuardsOpt>
+] extends [never] ? "public" : "session";
+/** The per-session policies among the names an endpoint's rateLimit option declares. */
+type LambderSessionPolicyNamesIn<TPolicies, TRateOpt> = {
+    [K in LambderGuardNamesIn<TRateOpt> & keyof TPolicies]: [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? K : never;
+}[LambderGuardNamesIn<TRateOpt> & keyof TPolicies];
+/**
+ * A public endpoint's per-session rate limits, refused on the option: a
+ * public call carries no session to count against. The property name is the
+ * message and its value the policies at fault.
+ */
+export type LambderPublicSessionPolicyCheck<TMode extends LambderApiMode, TPolicies, TRateOpt> = TMode extends "session" ? unknown : [LambderSessionPolicyNamesIn<TPolicies, TRateOpt>] extends [never] ? unknown : {
+    rateLimit: {
+        readonly "lambder: these rate limits count per session, and none of this API's guards needs a session": LambderSessionPolicyNamesIn<TPolicies, TRateOpt>;
+    };
+};
+/** What a session endpoint needs of its instance: sessions configured at create(). */
+type LambderSessionsConfigured = {
+    readonly "lambder: a guard of this API needs a session, and sessions are not configured on this instance. Pass the session option to create().": never;
+};
+/** A session endpoint on an instance without sessions, refused where it is declared. */
+export type LambderSessionModeCheck<TMode extends LambderApiMode, TSessions extends boolean> = TMode extends "session" ? (TSessions extends true ? unknown : LambderSessionsConfigured) : unknown;
+/** One endpoint's options as registration reads them. */
+export type LambderApiDeclarationOptions = {
+    input: z.ZodType;
+    output: z.ZodType;
+    guards?: LambderGuardsOptionValue;
+    rateLimit?: LambderRateLimitOptionValue;
+    idempotency?: LambderApiIdempotencyOption;
+    refusals?: LambderRefusalsOptionValue;
+    compress?: boolean | "auto";
+};
+/** The key the contract entry of a declaration is typed under. It exists only in types: nothing reads or writes it. */
+declare const LAMBDER_CONTRACT_ENTRY: unique symbol;
+/**
+ * One endpoint, declared: its options and its handler, and in its type the
+ * contract entry a client calls it by. Built by an instance's defineApi(),
+ * registered by being put in a group.
+ */
+export type LambderApiDeclaration<TEntry = unknown> = {
+    readonly kind: "lambderApi";
+    readonly options: LambderApiDeclarationOptions;
+    readonly handler: (ctx: never) => MaybePromise<unknown>;
+    readonly [LAMBDER_CONTRACT_ENTRY]: TEntry;
+};
+/** A group's endpoints by action name. */
+export type LambderApiDeclarations = Record<string, LambderApiDeclaration<any>>;
+/** A group of endpoints: `name.action` for each of its actions. Built by defineApiGroup(). */
+export type LambderApiGroup<TName extends string = string, TApis extends LambderApiDeclarations = LambderApiDeclarations> = {
+    readonly kind: "lambderApiGroup";
+    readonly name: TName;
+    readonly apis: TApis;
+};
+/**
+ * A group loaded on the first call to one of its endpoints: its name, and
+ * how to load it. Built by lazyApiGroup(). What a cold start parses then
+ * leaves out every group no request has called yet.
+ */
+export type LambderLazyApiGroup<TName extends string = string, TGroup extends LambderApiGroup<TName, any> = LambderApiGroup<TName, any>> = {
+    readonly kind: "lambderLazyApiGroup";
+    readonly name: TName;
+    readonly load: () => Promise<TGroup>;
+};
+/** Either kind of group registerApiGroups() takes. */
+export type LambderRegistrableApiGroup = LambderApiGroup<string, any> | LambderLazyApiGroup<string, any>;
+/** A declaration's contract entry. */
+export type LambderEntryOf<TDeclaration> = TDeclaration extends {
+    readonly [LAMBDER_CONTRACT_ENTRY]: infer TEntry;
+} ? TEntry : never;
+type LambderLoadedGroupOf<TGroup> = TGroup extends LambderLazyApiGroup<string, infer TLoaded> ? TLoaded : TGroup;
+/**
+ * One group's part of the contract: `group.action` for each action, its
+ * declaration's entry. Distributed over a union of groups (the `TGroup
+ * extends unknown`), so each group is read on its own: read as one union,
+ * the actions would be only those every group shares.
+ */
+type LambderGroupContract<TGroup> = TGroup extends unknown ? (LambderLoadedGroupOf<TGroup> extends LambderApiGroup<infer TName, infer TApis> ? {
+    [TAction in keyof TApis & string as `${TName}.${TAction}`]: LambderEntryOf<TApis[TAction]>;
+} : never) : never;
+type LambderUnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+/** The contract of every group registered together, as one flat object type keyed by endpoint name. */
+export type LambderContractOfGroups<TGroups extends readonly unknown[]> = LambderUnionToIntersection<LambderGroupContract<TGroups[number]>> extends infer TMerged ? {
+    [TName in keyof TMerged]: TMerged[TName];
+} : never;
+/**
+ * Whether a group, the group a lazy one loads, or that group's endpoints is
+ * typed any. A part typed any, merged with the rest, comes out as an index
+ * signature rather than as any, and no group declared action by action has
+ * one, so that counts too.
+ */
+type LambderGroupTypedAny<TGroup> = 0 extends 1 & TGroup ? true : 0 extends 1 & LambderLoadedGroupOf<TGroup> ? true : LambderLoadedGroupOf<TGroup> extends {
+    readonly apis: infer TApis;
+} ? (0 extends 1 & TApis ? true : string extends keyof TApis ? true : false) : false;
+/** The group names one registerApiGroups() call names twice. */
+type LambderRepeatedGroupNames<TGroups extends readonly unknown[], TSeen = never> = TGroups extends readonly [infer THead, ...infer TRest] ? (THead extends {
+    name: infer TName;
+} ? ([TName] extends [TSeen] ? TName : never) | LambderRepeatedGroupNames<TRest, TSeen | TName> : never) : never;
+/**
+ * What registerApiGroups() asks of its receiver: the instance itself, unless
+ * a group, what a lazy group loads or a group's endpoints is typed `any` (a
+ * module whose types were lost would otherwise make its endpoints `any` to
+ * every client) or a group name is given twice (two
+ * groups of one name would be one namespace with two owners). Then it asks
+ * for an object no instance is, whose property name is the message, so the
+ * call is refused where it is written.
+ */
+export type LambderRegisteredGroupsCheck<TGroups extends readonly unknown[], TSelf> = true extends {
+    [TIndex in keyof TGroups]: LambderGroupTypedAny<TGroups[TIndex]>;
+}[number] ? {
+    readonly "lambder: a group given to registerApiGroups, what a lazy group loads, or a group's endpoints is typed any, which would make its part of the contract any. Build it with defineApiGroup() and let its type through.": never;
+} : [LambderRepeatedGroupNames<TGroups>] extends [never] ? TSelf : {
+    readonly "lambder: these group names are registered twice": LambderRepeatedGroupNames<TGroups>;
+};
+/** A group's name held to the rule a caller's properties need. */
+export type LambderGroupNameCheck<TName extends string> = TName extends LambderReservedGroupName ? {
+    readonly "lambder: a caller already has a member of this name, so no group may take it": TName;
+} : unknown;
+/** The actions more than one of a group's parts declare. */
+type LambderRepeatedActions<TParts extends readonly unknown[], TSeen = never> = TParts extends readonly [infer THead, ...infer TRest] ? (Extract<keyof THead, TSeen> | LambderRepeatedActions<TRest, TSeen | keyof THead>) : never;
+/** A group's parts held to declaring each action once: a part would otherwise replace another's endpoint of the same name. */
+export type LambderGroupPartsCheck<TParts extends readonly unknown[]> = [
+    LambderRepeatedActions<TParts>
+] extends [never] ? unknown : {
+    readonly "lambder: these actions are declared by more than one part of the group": LambderRepeatedActions<TParts>;
+};
+/** One group's endpoints, from the parts it was declared in. */
+export type LambderMergedParts<TParts extends readonly unknown[]> = LambderUnionToIntersection<TParts[number]> extends infer TMerged ? {
+    [TAction in keyof TMerged]: TMerged[TAction];
+} : never;
+/** A group's action names held to the rule the functions a caller hands out need. */
+export type LambderActionNamesCheck<TApis> = [
+    Extract<keyof TApis, LambderReservedActionName>
+] extends [never] ? unknown : {
+    readonly "lambder: a function already has a member of these names, so no action may take them": Extract<keyof TApis, LambderReservedActionName>;
+};
+/**
+ * Builds a group from its parts, refusing a name no caller could carry, an
+ * action two parts declare, and a value that is not an endpoint. A group is
+ * usually one part; one declared across files gives each file's part.
+ */
+export declare const buildApiGroup: <TName extends string, TApis extends LambderApiDeclarations>(name: TName, parts: readonly LambderApiDeclarations[]) => LambderApiGroup<TName, TApis>;
+/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
+export declare const buildLazyApiGroup: <TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName, load: () => Promise<TGroup>) => LambderLazyApiGroup<TName, TGroup>;
+/** Whether a value is either kind of group registerApiGroups() takes. */
+export declare const isRegistrableApiGroup: (value: unknown) => value is LambderRegistrableApiGroup;
+export {};

package/dist/api/LambderApiDeclarations.js

@@ -0,0 +1,52 @@
+import { isActionName, isGroupName, LAMBDER_API_NAME_SEGMENT } from "../shared/wire/LambderApiNames.js";
+const describeName = (name) => typeof name === "string" ? `"${name}"` : String(name);
+/**
+ * Builds a group from its parts, refusing a name no caller could carry, an
+ * action two parts declare, and a value that is not an endpoint. A group is
+ * usually one part; one declared across files gives each file's part.
+ */
+export const buildApiGroup = (name, parts) => {
+    if (typeof name !== "string" || !isGroupName(name)) {
+        throw new Error(`Lambder: ${describeName(name)} cannot name a group. A group is a letter then letters, digits or underscores, ` +
+            `and not a name a caller already answers for (api, apiOutcome, then, ...).`);
+    }
+    const apis = {};
+    for (const part of parts) {
+        if (part === null || typeof part !== "object") {
+            throw new Error(`Lambder: a part of group "${name}" is not an object of endpoints by action name.`);
+        }
+        for (const [action, declaration] of Object.entries(part)) {
+            if (Object.prototype.hasOwnProperty.call(apis, action)) {
+                throw new Error(`Lambder: "${name}.${action}" is declared by two parts of group "${name}". Each action is declared once.`);
+            }
+            apis[action] = declaration;
+        }
+    }
+    if (Object.keys(apis).length === 0) {
+        throw new Error(`Lambder: group "${name}" declares no endpoints. A group is its endpoints by action name: defineApiGroup("${name}", { action: defineApi(...) }).`);
+    }
+    for (const [action, declaration] of Object.entries(apis)) {
+        if (!isActionName(action)) {
+            throw new Error(`Lambder: "${name}.${action}" cannot name an endpoint. An action is a letter then letters, digits or underscores, ` +
+                `and not a name a function already answers for (then, outcome, call, ...).`);
+        }
+        if (declaration?.kind !== "lambderApi") {
+            throw new Error(`Lambder: "${name}.${action}" is not an endpoint declaration. Declare it with the instance's defineApi().`);
+        }
+    }
+    return { kind: "lambderApiGroup", name, apis: apis };
+};
+/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
+export const buildLazyApiGroup = (name, load) => {
+    if (typeof name !== "string" || !isGroupName(name)) {
+        throw new Error(`Lambder: ${describeName(name)} cannot name a group. A group is a letter then letters, digits or underscores, and not a name a caller already answers for.`);
+    }
+    if (typeof load !== "function")
+        throw new Error(`Lambder: lazy group "${name}" has no loader. Pass a function that imports the group: () => import("./orders.js").then((m) => m.orderApis).`);
+    return { kind: "lambderLazyApiGroup", name, load };
+};
+/** Whether a value is either kind of group registerApiGroups() takes. */
+export const isRegistrableApiGroup = (value) => {
+    const kind = value?.kind;
+    return (kind === "lambderApiGroup" || kind === "lambderLazyApiGroup") && typeof value.name === "string" && LAMBDER_API_NAME_SEGMENT.test(value.name);
+};

package/dist/api/LambderApiDefinition.d.ts

@@ -4,7 +4,7 @@ import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "../shared/wire/LambderApiOptionValues.js";
 /**
  * One endpoint's declaration as the pipeline runs it: what the server's
- * addApi/addSessionApi options carry, minus the handler, in a shape the mock
+ * defineApi options carry, minus the handler, in a shape the mock
  * runtime can restate from a type-only contract. The schemas are optional
  * because the mock has none; when input is present, validation runs and the
  * handler sees the parsed payload. Output is part of the endpoint's

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. */