lambder 7.0.2 → 7.2.0

package/CHANGELOG.md

@@ -9,6 +9,118 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [7.1.5] - 2026-09-15
+
+### Added
+
+- **`minApiVersion`**, on `create()` and on the mock runtime: a floor under
+  the signature gate. A call naming a `version` below it answers
+  `versionExpired` whatever its signature says, which is the lever for a
+  change the digest cannot see (a security fix, a field whose meaning changed
+  under the same shape). Versions compare as dotted numbers, so `1.2.10` is
+  above `1.2.9`; a call naming no version is not judged, as one carrying no
+  signature is not gated. Creation refuses a floor that is not a dotted
+  version; a floor above `apiVersion` is taken as `apiVersion`, with a
+  warning, so a mistaken floor cannot refuse the build's own clients.
+  `compareDottedVersions` and `isDottedVersion` are exported from both
+  entries.
+
+### Changed
+
+- **`apiNameKeyOf` memoizes nothing.** It hashed each name it was asked about
+  into a module-level map, kept for the life of the process. On the server
+  that name comes off the wire, in the pre-pass that runs before anything has
+  checked that it is an endpoint at all and before any rate limit, so a
+  request naming anything grew the map by an entry, and one naming a
+  megabyte's worth grew it by a megabyte. Nothing is kept now: the digest the
+  gate rests on is the generator's, computed once at build time, and what is
+  left per call is one hash of a short name against a map already in memory.
+- **`apiVersion` must be a dotted version** (`"1.2.10"`), on `create()` and on
+  the mock runtime, where any string was taken before. `minApiVersion` reads
+  it as numbers, and a stamp the comparison cannot read (`"dev"`, a commit
+  sha, a build date) counted as zero, so setting a floor answered
+  `versionExpired` to every client of the build that set it. The clamp that
+  exists to stop exactly that could not see the case. Creation refuses it
+  instead, whether or not a floor is set today.
+- **The server reads the generated map too.** `create()` takes
+  `apiSignatures`, the same file the frontend ships with, and the pipeline
+  compares a call's signature with the map's entry; nothing is digested at
+  request time any more. The one computation is the generator's, so a schema
+  digested differently on two builds costs its clients one reload per deploy
+  and can no longer leave an endpoint refused for every caller.
+  `LambderApiSignatureDigests` and the `LambderApiSignatureSource` type are
+  gone, and `LambderApiPipeline.prepare(request)` takes no definition. A
+  server given no map gates nothing, as the mock runtime does.
+- **The signature digest hashes shape, not values.** The `default` keyword
+  zod emits is dropped before hashing: a default's value is server
+  behaviour, and for a function default (`.default(() => new Date())`,
+  `.prefault`, `.catch`) zod wrote whatever the function returned at
+  conversion, so the endpoint digested differently on every computation and
+  the generated map could never match the server. Whether the field may be
+  omitted still counts, through `required`, which is now sorted as well so
+  that reordering fields changes nothing. Endpoints with a defaulted field
+  get a new signature once.
+
+## [7.1.1] - 2026-09-15
+
+The version gate is replaced by a signature gate: whether a client is stale is
+decided per endpoint, by a signature of the endpoint's client-facing shape that
+the client carries and the server digests from its own registrations. A deploy
+now forces a reload only on the clients that call an endpoint whose shape
+changed; a tab whose endpoints are unchanged keeps working. The wire format
+gains one optional request field, `signature`; answers are unchanged, and a
+caller that sends no signature is treated as before, minus the version check.
+
+### Changed
+
+- **`apiVersion` no longer gates.** A request naming another version is not
+  refused any more; the string is stamped on every answer's envelope and does
+  nothing else. `LambderApiPipeline.isVersionStale` is gone, and `create()`
+  no longer refuses `apiVersion: ""`, since there is no gate for it to turn
+  off. An app that relied on the equality gate hands its callers
+  `apiSignatures` instead (below).
+- **`LambderApiPipeline.prepare(request, definition)`** takes the definition
+  the request's name resolved to, or null, because the signature gate needs
+  it. Both adapters resolve the name before the pre-pass now, which is also
+  why a signed request for an unknown name answers `versionExpired` rather
+  than `apiNotFound`: the client was built against a contract that had it.
+- **`LambderApiRequest` carries `signature: string | null`**, so a request
+  literal built by hand needs the field. `LambderApiDefinition` gains an
+  optional `output` schema, which `addApi`/`addSessionApi` record.
+
+### Added
+
+- **`lambder.apiSignatures()`**: every registered endpoint's signature keyed
+  by its hashed name, a `LambderApiSignatureMap`. A generator imports the
+  finished instance, awaits this, and writes the object to a file the
+  frontend ships with its build. The signature covers the name, the mode, the
+  input and output schemas as JSON Schema, each declared guard's schema, and
+  whether the endpoint takes an idempotency key; rate limits, guard
+  parameters and the handler are left out, so changing them never forces a
+  reload. Keys are hashed so the file lists no endpoint names. See
+  docs/apis.md, "Signatures: when a client must update".
+- **`apiSignatures` on `LambderCaller` and `LambderInvokeCaller`**: the
+  generated map. Each call sends its endpoint's signature; a name the map
+  lacks fails the call before it is sent, as an `unknown` outcome whose error
+  says to regenerate. Optional: a caller without the map is never gated.
+- **`apiSignatures` on the mock runtime**: given the same map, the runtime
+  refuses a stale signature exactly as the server would; without it every
+  signature passes, since it holds no server schema to digest. The request
+  event carries `signature`.
+- **Reload-loop protection in `LambderCaller`.** A `versionExpired` for the
+  same endpoint and signature within five minutes of the last one means the
+  reload brought the same bundle back (a frontend shipped with a stale map, a
+  cached bundle, a server deploy that failed behind it). The handler is not
+  called again; the failure goes to `errorHandler` and the outcome still says
+  `versionExpired`. Once confirmed, every `versionExpired` inside the window
+  counts, and after it a reload is allowed again. Kept per tab in
+  `sessionStorage`, in memory where there is none. `RELOAD_LOOP_WINDOW_MS` is
+  exported.
+- `apiNameKeyOf`, `lookupApiSignature`, `readApiSignature`,
+  `API_SIGNATURE_HEX_LENGTH` and the `LambderApiSignatureMap` type from both
+  entries; `apiSignatureOf`, `LambderApiSignatureDigests` and the
+  `LambderApiSignatureSource` type from the root.
+
 ## [7.0.0] - 2026-09-15
 
 A major. The API pipeline moved out of the Lambda server into an isomorphic

package/dist/api/LambderApiDefinition.d.ts

@@ -4,9 +4,11 @@ import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRate
 /**
  * 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
- * runtime can restate from a type-only contract. The schema is optional
- * because the mock has none; when present, input validation runs and the
- * handler sees the parsed payload.
+ * 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 read by nothing at request
+ * time: it is part of the endpoint's signature (apiSignatureOf), which is
+ * what a client's build is checked against.
  */
 export type LambderApiDefinition = {
     name: string;
@@ -15,4 +17,5 @@ export type LambderApiDefinition = {
     rateLimit?: LambderRateLimitOptionValue;
     idempotency?: LambderApiIdempotencyOption;
     input?: z.ZodType;
+    output?: z.ZodType;
 };

package/dist/api/LambderApiEnvelope.d.ts

@@ -54,7 +54,7 @@ export declare const validationAnswer: (zodError: z.ZodError, logList?: unknown[
 export declare const apiNotFoundAnswer: (apiVersion: string | null | undefined, logList?: unknown[]) => LambderApiAnswer;
 /** A session API called without a live session: the protocol's sessionExpired flag, which the caller clears its cookies on. */
 export declare const sessionExpiredAnswer: (apiVersion: string | null | undefined, logList?: unknown[]) => LambderApiAnswer;
-/** The caller's version is behind the server's: the protocol's versionExpired flag, which the caller reloads on. */
+/** The caller was built against another shape of the endpoint (the signature gate), or the app judged it stale: the protocol's versionExpired flag, which the caller reloads on. */
 export declare const versionExpiredAnswer: (apiVersion: string | null | undefined) => LambderApiAnswer;
 /** A compressed request payload that could not be restored: a 400 with the reason, never a crash. */
 export declare const invalidPayloadAnswer: (apiVersion: string | null | undefined, message: string) => LambderApiAnswer;

package/dist/api/LambderApiEnvelope.js

@@ -165,7 +165,7 @@ export const apiNotFoundAnswer = (apiVersion, logList) => envelopeAnswer(buildAp
 }));
 /** A session API called without a live session: the protocol's sessionExpired flag, which the caller clears its cookies on. */
 export const sessionExpiredAnswer = (apiVersion, logList) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { sessionExpired: true, logList }));
-/** The caller's version is behind the server's: the protocol's versionExpired flag, which the caller reloads on. */
+/** The caller was built against another shape of the endpoint (the signature gate), or the app judged it stale: the protocol's versionExpired flag, which the caller reloads on. */
 export const versionExpiredAnswer = (apiVersion) => envelopeAnswer(buildApiEnvelope(apiVersion, null, { versionExpired: true }));
 /** A compressed request payload that could not be restored: a 400 with the reason, never a crash. */
 export const invalidPayloadAnswer = (apiVersion, message) => envelopeAnswer(buildApiEnvelope(apiVersion, null, {

package/dist/api/LambderApiGuards.d.ts

@@ -277,6 +277,11 @@ type GuardInputsEntries<TGuards, TOpt> = {
 };
 /** The guardInputs map an API's contract requires clients to send; never when no declared guard uses guardInput mode. */
 export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
+/** Normalize the three guards-option forms into ordered { name, param } entries. Read by the engine, and by the signature digest for the names alone. */
+export declare const toGuardEntries: (value?: LambderGuardsOptionValue) => {
+    name: string;
+    param: unknown;
+}[];
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared

package/dist/api/LambderApiGuards.js

@@ -7,8 +7,8 @@ import { LAMBDER_RESPONSE_BRAND, isLambderResponseLike } from "../shared/util/La
  * as server guards and run through the same engine.
  */
 export const lambderGuardBuilder = () => ((guard) => guard);
-/** Normalize the three guards-option forms into ordered { name, param } entries. Internal to the engine: nothing outside it reads a guards option. */
-const toGuardEntries = (value) => {
+/** Normalize the three guards-option forms into ordered { name, param } entries. Read by the engine, and by the signature digest for the names alone. */
+export const toGuardEntries = (value) => {
     if (value === undefined)
         return [];
     if (typeof value === "string")

package/dist/api/LambderApiPipeline.d.ts

@@ -4,6 +4,7 @@ import type { LambderApiAnswer } from "./LambderApiAnswer.js";
 import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import type { LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderApiGuard } from "./LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
@@ -28,8 +29,24 @@ export type LambderApiSessionsConfig<TSessionData> = {
     cookieOptions?: LambderSessionCookieOptions;
 };
 export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessionData>, TSessionData = any> = {
-    /** Enables the version gate: a request naming another version answers versionExpired. */
+    /** Stamped on every answer's envelope as apiVersion, so a client can tell which build answered; null when the app set none. */
     apiVersion?: string | null;
+    /**
+     * The floor under the signature gate: a request naming a `version` below
+     * it answers versionExpired whatever its signature says. Dotted numbers
+     * ("1.2.10"), compared segment by segment. A floor above apiVersion is
+     * taken as apiVersion, so a mistaken floor cannot refuse the build's own
+     * clients.
+     */
+    minApiVersion?: string | null;
+    /**
+     * Enables the signature gate: the generated map (Lambder.apiSignatures(),
+     * the same file the client ships with). A request carrying a signature
+     * that is not the map's entry for its endpoint answers versionExpired,
+     * and so does one for an endpoint the map does not hold: that client was
+     * built against another contract. Without a map every signature passes.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /** Ceiling on what a compressed request payload may restore to. Default: 20,000,000. */
     maxRequestPayloadBytes?: number;
     onInvalidInput?: LambderApiInputRefusal<TCtx>;
@@ -52,7 +69,7 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version gate → restore payload → rate limits that need no session
+ * version floor → signature gate → restore payload → rate limits that need no session
  * → session (session mode) → idempotency replay → the remaining rate limits
  * → guards → input validation → exec, inside the idempotency claim
  * → drain response headers → answer
@@ -71,10 +88,12 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  */
 export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSessionData>, TSessionData = any> {
     readonly apiVersion: string | null;
+    readonly minApiVersion: string | null;
     private readonly policies;
     private readonly maxRequestPayloadBytes;
     private readonly onInvalidInput;
     private readonly sessions;
+    private readonly apiSignatures;
     constructor(options?: LambderApiPipelineOptions<TCtx, TSessionData>);
     /** True when a session manager was configured. */
     get hasSessions(): boolean;
@@ -90,28 +109,39 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
     static sessionInfoOf(request: LambderApiRequest): LambderSessionRequestInfo;
     /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
     assertRegistration(definition: LambderApiDefinition): void;
-    /** True when the gate is on and the request names a different version. */
-    isVersionStale(request: LambderApiRequest): boolean;
     /**
      * The answer for a request naming no registered API: the apiNotFound
      * refusal, carrying whatever the call already wrote (a CORS header, a
-     * cookie eviction). No version gate here: both adapters run prepare() on
-     * the way in, before a name is resolved, so a stale client has already
-     * been answered by the time anything asks for an unknown name.
+     * cookie eviction). No signature gate here: both adapters run prepare()
+     * on the way in, so a signed request for a name the map does not hold (a
+     * client built against a contract that had it) has already been answered
+     * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(request: LambderApiRequest, ctx?: TCtx): LambderApiAnswer;
     /**
      * The steps that come before anything may read the request: the version
-     * gate, then the compressed-payload restore that every later reader (a
-     * rate-limit key slice, a guard, the input schema) depends on having
-     * happened.
+     * floor, the signature gate, then the compressed-payload restore that
+     * every later reader (a rate-limit key slice, a guard, the input schema)
+     * depends on having happened.
+     *
+     * The floor answers versionExpired to a request naming a version below
+     * minApiVersion whatever its signature says: the lever for a change the
+     * digest cannot see (a security fix, a field whose meaning changed under
+     * the same shape). A request naming no version is not judged by it, as
+     * one carrying no signature is not gated.
+     *
+     * The gate compares the signature the request carries with the map's
+     * entry for the endpoint it names. A match runs; anything else, another
+     * entry or none, is a client built against another shape of this
+     * endpoint or against an endpoint that no longer exists, and is answered
+     * versionExpired. A request carrying no signature is never gated.
      *
      * Public and named because the server runs them earlier than run() does,
      * on the way in, so that its hooks see a plain payload and a stale client
      * is answered before any of them, whether or not the name it asked for
      * exists. run() calls it too, so an adapter that has no such step still
      * gets the whole protocol. Calling it twice is safe by construction: the
-     * gate is a pure comparison and the restore has already removed the wire
+     * gates are comparisons and the restore has already removed the wire
      * fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is

package/dist/api/LambderApiPipeline.js

@@ -1,9 +1,11 @@
 import { restoreCompressedPayload } from "./LambderApiRequest.js";
+import { lookupApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { apiNotFoundAnswer, invalidPayloadAnswer, refusalAnswer, sessionExpiredAnswer, validationAnswer, versionExpiredAnswer, } from "./LambderApiEnvelope.js";
 import { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./LambderApiValidationRefusal.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { compareDottedVersions, isDottedVersion } from "../shared/wire/LambderVersionOrder.js";
 import { LambderApiPolicyEngine } from "./LambderApiPolicyEngine.js";
 import LambderSessionController, { assertSessionCookiePrefixes, } from "../session/LambderSessionController.js";
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
@@ -13,7 +15,7 @@ import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } fro
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version gate → restore payload → rate limits that need no session
+ * version floor → signature gate → restore payload → rate limits that need no session
  * → session (session mode) → idempotency replay → the remaining rate limits
  * → guards → input validation → exec, inside the idempotency claim
  * → drain response headers → answer
@@ -32,12 +34,37 @@ import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } fro
  */
 export class LambderApiPipeline {
     apiVersion;
+    minApiVersion;
     policies = new LambderApiPolicyEngine();
     maxRequestPayloadBytes;
     onInvalidInput;
     sessions;
+    apiSignatures;
     constructor(options = {}) {
         this.apiVersion = options.apiVersion ?? null;
+        // Dotted, always, whether or not a floor is set today: the floor reads
+        // this string as numbers, and a stamp the comparison cannot read
+        // ("dev", a commit sha) counts as 0, so setting minApiVersion later
+        // would answer versionExpired to every client of this very build.
+        if (this.apiVersion !== null && !isDottedVersion(this.apiVersion)) {
+            throw new Error(`Lambder: apiVersion must be a dotted version such as "1.2.10", got ${JSON.stringify(this.apiVersion)}.`);
+        }
+        this.minApiVersion = options.minApiVersion ?? null;
+        if (this.minApiVersion !== null) {
+            if (!isDottedVersion(this.minApiVersion)) {
+                throw new Error(`Lambder: minApiVersion must be a dotted version such as "1.2.10", got ${JSON.stringify(this.minApiVersion)}.`);
+            }
+            // A floor above the version this server stamps on its answers
+            // would refuse the very clients this build serves, and the first
+            // symptom would be every tab reloading. The lower of the two is
+            // the most a floor can mean here, so that is what it becomes, and
+            // the mistake is said once at creation.
+            if (this.apiVersion !== null && compareDottedVersions(this.minApiVersion, this.apiVersion) > 0) {
+                console.warn(`Lambder: minApiVersion ${this.minApiVersion} is above apiVersion ${this.apiVersion}; the floor is taken as ${this.apiVersion}.`);
+                this.minApiVersion = this.apiVersion;
+            }
+        }
+        this.apiSignatures = options.apiSignatures ?? null;
         this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
         this.onInvalidInput = options.onInvalidInput ?? null;
         this.sessions = options.sessions
@@ -90,16 +117,13 @@ export class LambderApiPipeline {
     assertRegistration(definition) {
         this.policies.assertRegistration(definition);
     }
-    /** True when the gate is on and the request names a different version. */
-    isVersionStale(request) {
-        return !!this.apiVersion && !!request.version && request.version !== this.apiVersion;
-    }
     /**
      * The answer for a request naming no registered API: the apiNotFound
      * refusal, carrying whatever the call already wrote (a CORS header, a
-     * cookie eviction). No version gate here: both adapters run prepare() on
-     * the way in, before a name is resolved, so a stale client has already
-     * been answered by the time anything asks for an unknown name.
+     * cookie eviction). No signature gate here: both adapters run prepare()
+     * on the way in, so a signed request for a name the map does not hold (a
+     * client built against a contract that had it) has already been answered
+     * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(request, ctx) {
         const answer = apiNotFoundAnswer(this.apiVersion, ctx?.logList);
@@ -108,24 +132,42 @@ export class LambderApiPipeline {
     }
     /**
      * The steps that come before anything may read the request: the version
-     * gate, then the compressed-payload restore that every later reader (a
-     * rate-limit key slice, a guard, the input schema) depends on having
-     * happened.
+     * floor, the signature gate, then the compressed-payload restore that
+     * every later reader (a rate-limit key slice, a guard, the input schema)
+     * depends on having happened.
+     *
+     * The floor answers versionExpired to a request naming a version below
+     * minApiVersion whatever its signature says: the lever for a change the
+     * digest cannot see (a security fix, a field whose meaning changed under
+     * the same shape). A request naming no version is not judged by it, as
+     * one carrying no signature is not gated.
+     *
+     * The gate compares the signature the request carries with the map's
+     * entry for the endpoint it names. A match runs; anything else, another
+     * entry or none, is a client built against another shape of this
+     * endpoint or against an endpoint that no longer exists, and is answered
+     * versionExpired. A request carrying no signature is never gated.
      *
      * Public and named because the server runs them earlier than run() does,
      * on the way in, so that its hooks see a plain payload and a stale client
      * is answered before any of them, whether or not the name it asked for
      * exists. run() calls it too, so an adapter that has no such step still
      * gets the whole protocol. Calling it twice is safe by construction: the
-     * gate is a pure comparison and the restore has already removed the wire
+     * gates are comparisons and the restore has already removed the wire
      * fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is
      * ready to dispatch.
      */
     async prepare(request) {
-        if (this.isVersionStale(request))
+        if (this.minApiVersion !== null && request.version !== null && compareDottedVersions(request.version, this.minApiVersion) < 0) {
             return versionExpiredAnswer(this.apiVersion);
+        }
+        if (request.signature !== null && this.apiSignatures) {
+            const expected = await lookupApiSignature(this.apiSignatures, request.apiName);
+            if (expected !== request.signature)
+                return versionExpiredAnswer(this.apiVersion);
+        }
         const restored = await restoreCompressedPayload(request, this.maxRequestPayloadBytes);
         if (!restored.ok)
             return invalidPayloadAnswer(this.apiVersion, restored.message);

package/dist/api/LambderApiRequest.d.ts

@@ -20,8 +20,10 @@ export declare const lowercaseHeaderNames: (headers: Record<string, string | und
  */
 export type LambderApiRequest = {
     apiName: string;
-    /** The caller's apiVersion, for the version gate; null when it sent none. */
+    /** The caller's apiVersion, informational; null when it sent none. */
     version: string | null;
+    /** The signature the caller carries for this endpoint (see LambderApiSignatureMap), for the signature gate; null when it sent none. */
+    signature: string | null;
     /** The CSRF token the caller posted in the envelope; "" when it holds none. */
     token: string;
     siteHost: string;

package/dist/api/LambderApiRequest.js

@@ -50,6 +50,7 @@ export const readApiEnvelope = (post, info) => {
     return {
         apiName: post.apiName,
         version: typeof post.version === "string" ? post.version : null,
+        signature: typeof post.signature === "string" ? post.signature : null,
         token: typeof post.token === "string" ? post.token : "",
         siteHost: typeof post.siteHost === "string" ? post.siteHost : "",
         payload: post.payload,

package/dist/api/LambderApiSignature.d.ts

@@ -0,0 +1,19 @@
+import type { LambderApiDefinition } from "./LambderApiDefinition.js";
+import { type LambderApiGuard } from "./LambderApiGuards.js";
+/**
+ * The digest of an endpoint's client-facing shape: its name and mode, its
+ * input and output schemas as JSON Schema, every guard it declares with the
+ * schema that guard validates (the guardInput the client sends separately,
+ * or the apiInput slice of the payload), and whether it demands an
+ * idempotency key. Anything else about the endpoint (its rate limits, a
+ * guard's parameter, the handler) changes nothing for a client and is left
+ * out, so changing it never forces a reload.
+ *
+ * The description is hashed as built, descriptions and titles included: a
+ * schema is what the server says it is, and a client built against a
+ * different one reloads once. What must hold for the digest to mean anything
+ * is that a schema is built from static values: one that reads the clock, a
+ * random source or the environment at construction digests differently in
+ * the generator's process and on the server.
+ */
+export declare const apiSignatureOf: (definition: LambderApiDefinition, guards: Record<string, LambderApiGuard<any, any, any>> | undefined) => Promise<string>;

package/dist/api/LambderApiSignature.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { toGuardEntries } from "./LambderApiGuards.js";
+import { API_SIGNATURE_HEX_LENGTH } from "../shared/wire/LambderApiSignature.js";
+import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+/*
+ * The digest of an endpoint's client-facing shape, computed once, by the
+ * generator, through Lambder.apiSignatures(). Nothing digests at request
+ * time: the server and the client both carry the generated map and the
+ * pipeline compares entries, so the one computation has nothing to agree
+ * with but itself. See LambderApiSignatureMap.
+ */
+/**
+ * JSON with object keys sorted at every level, so two descriptions of the
+ * same shape hash the same whatever order they were built in. Arrays keep
+ * their order: a tuple's positions and an enum's values are part of the
+ * shape. Undefined entries are dropped, as JSON.stringify would drop them.
+ */
+const canonicalJson = (value) => JSON.stringify(sortKeys(value));
+const sortKeys = (value) => {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort()) {
+        if (source[key] !== undefined)
+            sorted[key] = sortKeys(source[key]);
+    }
+    return sorted;
+};
+/**
+ * Two edits to every node zod emits, before it is hashed.
+ *
+ * The `default` keyword goes. Its value is server behaviour, not shape: a
+ * client never sends it, and its compiled types do not carry it. And for a
+ * function default (`.default(() => new Date())`, `.prefault`, `.catch`)
+ * zod writes whatever the function returned at conversion time, a clock
+ * reading or a random value, which would give the endpoint a different
+ * digest on every computation and a generated map that never matches the
+ * server. Nothing distinguishes such a default from a constant one once zod
+ * has evaluated it, so every default goes, and the one thing about a default
+ * a client can see, that the field may be omitted, stays through `required`.
+ *
+ * `required` is sorted. It is a set, and the order fields are declared in is
+ * not shape either; left as emitted, reordering two fields forced a reload.
+ */
+const keepShapeOnly = (node) => {
+    delete node.default;
+    if (Array.isArray(node.required))
+        node.required.sort();
+};
+/**
+ * A schema as JSON Schema, as zod emits it minus what keepShapeOnly removes.
+ * A type JSON Schema cannot express (a transform's output, a custom check)
+ * becomes `{}` rather than throwing, because a digest has to exist for every
+ * endpoint; what the digest cannot see is documented with it.
+ */
+const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema) }) : null;
+const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasOwnProperty.call(guards, name) ? guards[name] : undefined;
+/**
+ * The digest of an endpoint's client-facing shape: its name and mode, its
+ * input and output schemas as JSON Schema, every guard it declares with the
+ * schema that guard validates (the guardInput the client sends separately,
+ * or the apiInput slice of the payload), and whether it demands an
+ * idempotency key. Anything else about the endpoint (its rate limits, a
+ * guard's parameter, the handler) changes nothing for a client and is left
+ * out, so changing it never forces a reload.
+ *
+ * The description is hashed as built, descriptions and titles included: a
+ * schema is what the server says it is, and a client built against a
+ * different one reloads once. What must hold for the digest to mean anything
+ * is that a schema is built from static values: one that reads the clock, a
+ * random source or the environment at construction digests differently in
+ * the generator's process and on the server.
+ */
+export const apiSignatureOf = async (definition, guards) => {
+    const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {
+        const guard = ownGuard(guards, name);
+        return [name, {
+                apiInput: jsonSchemaOf(guard?.apiInput, "input"),
+                guardInput: jsonSchemaOf(guard?.guardInput, "input"),
+            }];
+    });
+    guardShapes.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const description = {
+        name: definition.name,
+        mode: definition.mode,
+        input: jsonSchemaOf(definition.input, "input"),
+        output: jsonSchemaOf(definition.output, "output"),
+        guards: guardShapes,
+        idempotency: definition.idempotency !== undefined && definition.idempotency !== false,
+    };
+    const hex = await sha256HexOf(canonicalJson(description));
+    return hex.slice(0, API_SIGNATURE_HEX_LENGTH);
+};

package/dist/client/LambderCaller.d.ts

@@ -4,6 +4,7 @@ import type { LambderApiContractShape } from '../shared/wire/LambderApiContract.
 import { type LambderApiOutcome, type LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from '../shared/wire/LambderCallOptions.js';
 import { type LambderApiTransport } from '../shared/transport/LambderApiTransport.js';
+import { type LambderApiSignatureMap } from '../shared/wire/LambderApiSignature.js';
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError } from '../shared/wire/LambderApiOutcome.js';
 export type { LambderProvidedGuardInputs, LambderGuardInputsProvider } from '../shared/wire/LambderCallOptions.js';
 /** A handler told that something happened, with nothing to hand it. */
@@ -56,7 +57,16 @@ export type LambderCallOptions = LambderSharedCallOptions & {
 };
 type LambderCallerBaseOptions = {
     apiPath: string;
+    /** Sent with every call as `version`, informational: the server stamps its own on every answer. */
     apiVersion?: string;
+    /**
+     * The server's signature map, generated from its instance
+     * (Lambder.apiSignatures()) and shipped with this build. Sent per call as
+     * `signature`, so the server answers versionExpired to a call built
+     * against another shape of the endpoint and runs every other call. Leave
+     * it out and no call is gated.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     isCorsEnabled: boolean;
     /** Default per-request timeout in ms (none unless set; API Gateway caps around 29s, so ~30000 is a sensible value). Overridable per call. */
     timeoutMs?: number;
@@ -101,7 +111,10 @@ export default class LambderCaller<TContract extends LambderApiContractShape = a
     private isCorsEnabled;
     private apiPath;
     private apiVersion?;
+    private apiSignatures?;
     private timeoutMs?;
+    /** What keeps a stale bundle from reloading itself forever; see the class. */
+    private readonly reloadLoopBreaker;
     /** The calls currently in flight, in the order they started. */
     fetchTrackerList: FetchTracker[];
     /** Whether any call is in flight. Derived, so it cannot drift from the list the way a separate flag did. */