lambder 7.0.1 → 7.1.4

package/CHANGELOG.md

@@ -9,6 +9,66 @@ 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.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 { LambderApiSignatureSource } from "./LambderApiSignature.js";
 import type { LambderApiGuard } from "./LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
@@ -28,8 +29,15 @@ 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;
+    /**
+     * Enables the signature gate: a request carrying a signature that is not
+     * the one this source expects for its endpoint answers versionExpired.
+     * Without a source every signature passes, which is what the mock runtime
+     * does unless it is given the generated map.
+     */
+    signatures?: LambderApiSignatureSource;
     /** Ceiling on what a compressed request payload may restore to. Default: 20,000,000. */
     maxRequestPayloadBytes?: number;
     onInvalidInput?: LambderApiInputRefusal<TCtx>;
@@ -52,7 +60,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
+ * 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
@@ -75,6 +83,7 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
     private readonly maxRequestPayloadBytes;
     private readonly onInvalidInput;
     private readonly sessions;
+    private readonly signatures;
     constructor(options?: LambderApiPipelineOptions<TCtx, TSessionData>);
     /** True when a session manager was configured. */
     get hasSessions(): boolean;
@@ -90,34 +99,41 @@ 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, with the definition the name resolved to or null, so a
+     * signed request for an unknown name (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.
+     * The steps that come before anything may read the request: 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 gate compares the signature the request carries with the one the
+     * source expects for the endpoint the name resolved to (`definition`,
+     * null for a name the adapter does not know). A match runs; anything
+     * else 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
-     * fields it reads.
+     * gate compares against a memoized digest 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.
      */
-    prepare(request: LambderApiRequest): Promise<LambderApiAnswer | null>;
+    prepare(request: LambderApiRequest, definition: LambderApiDefinition | null): Promise<LambderApiAnswer | null>;
     /**
      * One call, one answer. Refusals are rendered; crashes propagate.
      *

package/dist/api/LambderApiPipeline.js

@@ -13,7 +13,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
+ * 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
@@ -36,8 +36,10 @@ export class LambderApiPipeline {
     maxRequestPayloadBytes;
     onInvalidInput;
     sessions;
+    signatures;
     constructor(options = {}) {
         this.apiVersion = options.apiVersion ?? null;
+        this.signatures = options.signatures ?? null;
         this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
         this.onInvalidInput = options.onInvalidInput ?? null;
         this.sessions = options.sessions
@@ -90,16 +92,14 @@ 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, with the definition the name resolved to or null, so a
+     * signed request for an unknown name (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);
@@ -107,25 +107,35 @@ export class LambderApiPipeline {
         return answer;
     }
     /**
-     * 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.
+     * The steps that come before anything may read the request: 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 gate compares the signature the request carries with the one the
+     * source expects for the endpoint the name resolved to (`definition`,
+     * null for a name the adapter does not know). A match runs; anything
+     * else 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
-     * fields it reads.
+     * gate compares against a memoized digest 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))
-            return versionExpiredAnswer(this.apiVersion);
+    async prepare(request, definition) {
+        if (request.signature !== null && this.signatures) {
+            const expected = await this.signatures.expectedSignatureOf(request.apiName, definition);
+            if (expected !== request.signature)
+                return versionExpiredAnswer(this.apiVersion);
+        }
         const restored = await restoreCompressedPayload(request, this.maxRequestPayloadBytes);
         if (!restored.ok)
             return invalidPayloadAnswer(this.apiVersion, restored.message);
@@ -165,7 +175,7 @@ export class LambderApiPipeline {
         return { answer, ...trace };
     }
     async execute(request, ctx, definition, exec, trace) {
-        const unprepared = await this.prepare(request);
+        const unprepared = await this.prepare(request, definition);
         if (unprepared)
             return unprepared;
         // The limits whose key is known from the request alone, before the

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,41 @@
+import type { LambderApiDefinition } from "./LambderApiDefinition.js";
+import { type LambderApiGuard } from "./LambderApiGuards.js";
+/**
+ * Where the pipeline asks what signature a request should carry. Null for
+ * an endpoint the source does not know, so a signed call for a name the
+ * server does not have is answered versionExpired rather than apiNotFound:
+ * the client was built against a contract that had it. The server answers
+ * from its own schemas (LambderApiSignatureDigests); the mock runtime, which
+ * holds no server schema, answers from the generated map when given one.
+ */
+export type LambderApiSignatureSource = {
+    expectedSignatureOf(apiName: string, definition: LambderApiDefinition | null): Promise<string | null>;
+};
+/**
+ * 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.
+ */
+export declare const apiSignatureOf: (definition: LambderApiDefinition, guards: Record<string, LambderApiGuard<any, any, any>> | undefined) => Promise<string>;
+/**
+ * The server's signature source: every registered endpoint digested from
+ * its own schemas, once per endpoint per container, on first use. What
+ * Lambder.apiSignatures() reads to build the client's map, and what the
+ * pipeline compares a request's signature against.
+ */
+export declare class LambderApiSignatureDigests implements LambderApiSignatureSource {
+    private readonly guards;
+    private readonly digests;
+    constructor(guards: Record<string, LambderApiGuard<any, any, any>> | undefined);
+    /** The endpoint's signature, computed on the first ask and kept. A digest that failed is not kept, so the next call tries again rather than failing forever. */
+    signatureOf(definition: LambderApiDefinition): Promise<string>;
+    expectedSignatureOf(apiName: string, definition: LambderApiDefinition | null): Promise<string | null>;
+}

package/dist/api/LambderApiSignature.js

@@ -0,0 +1,91 @@
+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";
+/**
+ * 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;
+};
+/**
+ * A schema as JSON Schema, exactly as zod emits it. 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" }) : 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.
+ */
+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);
+};
+/**
+ * The server's signature source: every registered endpoint digested from
+ * its own schemas, once per endpoint per container, on first use. What
+ * Lambder.apiSignatures() reads to build the client's map, and what the
+ * pipeline compares a request's signature against.
+ */
+export class LambderApiSignatureDigests {
+    guards;
+    digests = new Map();
+    constructor(guards) {
+        this.guards = guards;
+    }
+    /** The endpoint's signature, computed on the first ask and kept. A digest that failed is not kept, so the next call tries again rather than failing forever. */
+    signatureOf(definition) {
+        let pending = this.digests.get(definition.name);
+        if (!pending) {
+            pending = apiSignatureOf(definition, this.guards);
+            this.digests.set(definition.name, pending);
+            pending.catch(() => this.digests.delete(definition.name));
+        }
+        return pending;
+    }
+    async expectedSignatureOf(apiName, definition) {
+        return definition ? await this.signatureOf(definition) : null;
+    }
+}

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

package/dist/client/LambderCaller.js

@@ -7,6 +7,8 @@ import { createCallAbort } from '../shared/util/LambderCallAbort.js';
 import { coerceToError } from '../shared/wire/LambderCrashDetail.js';
 import { isLambderTransportFailure } from '../shared/transport/LambderApiTransport.js';
 import { DEFAULT_SESSION_TOKEN_COOKIE_KEY, DEFAULT_SESSION_CSRF_COOKIE_KEY } from '../shared/wire/LambderSessionCookieNames.js';
+import { readApiSignature } from '../shared/wire/LambderApiSignature.js';
+import { LambderReloadLoopBreaker, RELOAD_LOOP_WINDOW_MS } from './LambderReloadLoopBreaker.js';
 import { lambderFetchTransport } from './lambderFetchTransport.js';
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
@@ -16,7 +18,10 @@ export default class LambderCaller {
     isCorsEnabled;
     apiPath;
     apiVersion;
+    apiSignatures;
     timeoutMs;
+    /** What keeps a stale bundle from reloading itself forever; see the class. */
+    reloadLoopBreaker = new LambderReloadLoopBreaker();
     /** The calls currently in flight, in the order they started. */
     fetchTrackerList = [];
     /** Whether any call is in flight. Derived, so it cannot drift from the list the way a separate flag did. */
@@ -40,9 +45,10 @@ export default class LambderCaller {
     constructor(options) {
         // The conditional provider option is resolved per instantiation;
         // inside the class it is read through the plain shape.
-        const { apiPath, apiVersion, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
+        const { apiPath, apiVersion, apiSignatures, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
         this.apiPath = apiPath;
         this.apiVersion = apiVersion;
+        this.apiSignatures = apiSignatures;
         this.isCorsEnabled = isCorsEnabled;
         this.timeoutMs = timeoutMs;
         this.sessionCookieDomain = sessionCookieDomain;
@@ -198,6 +204,10 @@ export default class LambderCaller {
                     activeFetchList: [...this.fetchTrackerList],
                 });
             const version = this.apiVersion;
+            // The server's signature for this endpoint, when this build
+            // carries the map. A name the map lacks fails the call here, as a
+            // provider that threw would: the map predates the endpoint.
+            const signature = this.apiSignatures ? await readApiSignature(this.apiSignatures, apiName) : undefined;
             // js-cookie reads nothing without a document, and there is no
             // location outside a page: both are "" then, and a transport that
             // carries a cookie jar fills the token in from it.
@@ -228,6 +238,7 @@ export default class LambderCaller {
                 answer = await this.transport({
                     apiPath: this.apiPath,
                     apiName, version, token, siteHost,
+                    ...(signature !== undefined ? { signature } : {}),
                     csrfCookieKey: this.sessionCsrfCookieKey,
                     ...(compressedPayload ? { compressed: compressedPayload } : { payload }),
                     ...(guardInputs !== undefined ? { guardInputs } : {}),
@@ -292,6 +303,15 @@ export default class LambderCaller {
             const data = outcome.response;
             await fetchEnded(data);
             if (!outcome.ok && outcome.reason === 'versionExpired') {
+                // A repeat of a recent versionExpired for the same endpoint and
+                // signature means the reload the handler performed brought the
+                // same bundle back, and reloading again would loop. The
+                // handler is not called; the failure is reported instead, and
+                // the outcome still says versionExpired.
+                if (this.reloadLoopBreaker.isRepeat(apiName, signature ?? "")) {
+                    await reportError(new Error(`Version expired again for API "${apiName}" within ${RELOAD_LOOP_WINDOW_MS / 60000} minutes with the same signature: the bundle being served is still the stale one, so versionExpiredHandler was not called again.`));
+                    return outcome;
+                }
                 if (versionExpiredHandler) {
                     await versionExpiredHandler();
                 }

package/dist/client/LambderReloadLoopBreaker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stops a stale client from reloading forever.
+ *
+ * A versionExpired answer means "this client's signature for the endpoint is
+ * not the one the server holds", and the ordinary response is to reload and
+ * get the current bundle. When the bundle being served is itself the stale
+ * one (a frontend deployed with a signature map the server does not match, a
+ * cached bundle, a server deploy that failed behind a fresh frontend), the
+ * reload brings back the same signature, the same call fails the same way,
+ * and the page reloads again, indefinitely.
+ *
+ * The evidence of that loop is a versionExpired for the same endpoint with
+ * the same signature shortly after the last one: a bundle that had actually
+ * changed the endpoint would carry a different signature. The record lives
+ * in sessionStorage, which is per tab and survives a reload, so the new page
+ * instance sees what the previous one saw; without sessionStorage (a test, a
+ * non-browser runtime) an in-memory record does the same within one page.
+ *
+ * Once a repeat is confirmed, every versionExpired within the window from
+ * the first one counts as a repeat too, whichever endpoint it names: a stale
+ * bundle is usually stale for several endpoints, and one reload per endpoint
+ * is still a loop, only a slower one. After the window a reload is allowed
+ * again, so a client stuck on a stale bundle retries a few times an hour and
+ * recovers by itself once the deploy is fixed.
+ */
+/** How long after the first versionExpired a repeat counts as the same loop. */
+export declare const RELOAD_LOOP_WINDOW_MS: number;
+export declare class LambderReloadLoopBreaker {
+    /** The record when sessionStorage is unavailable; sessionStorage is read first wherever it exists. */
+    private memory;
+    /**
+     * Records this versionExpired and says whether it repeats a recent one,
+     * in which case the caller must not invoke versionExpiredHandler again.
+     */
+    isRepeat(apiName: string, signature: string, now?: number): boolean;
+    private read;
+    private write;
+}