lambder 7.0.2 → 7.1.4

package/dist/client/LambderReloadLoopBreaker.js

@@ -0,0 +1,71 @@
+/**
+ * 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 const RELOAD_LOOP_WINDOW_MS = 5 * 60 * 1000;
+const STORAGE_KEY = "lambder:version-expired";
+const isExpiredRecord = (value) => typeof value === "object" && value !== null
+    && typeof value.apiName === "string"
+    && typeof value.signature === "string"
+    && typeof value.at === "number"
+    && typeof value.confirmed === "boolean";
+export class LambderReloadLoopBreaker {
+    /** The record when sessionStorage is unavailable; sessionStorage is read first wherever it exists. */
+    memory = null;
+    /**
+     * Records this versionExpired and says whether it repeats a recent one,
+     * in which case the caller must not invoke versionExpiredHandler again.
+     */
+    isRepeat(apiName, signature, now = Date.now()) {
+        const last = this.read();
+        if (last && now - last.at < RELOAD_LOOP_WINDOW_MS && (last.confirmed || (last.apiName === apiName && last.signature === signature))) {
+            // `at` stays the first event's, so the window runs from the start
+            // of the loop rather than being pushed forward by every repeat.
+            this.write({ apiName, signature, at: last.at, confirmed: true });
+            return true;
+        }
+        this.write({ apiName, signature, at: now, confirmed: false });
+        return false;
+    }
+    read() {
+        try {
+            const raw = globalThis.sessionStorage?.getItem(STORAGE_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (isExpiredRecord(parsed))
+                    return parsed;
+            }
+        }
+        catch { /* a private window or blocked storage: the in-memory record stands in */ }
+        return this.memory;
+    }
+    write(record) {
+        this.memory = record;
+        try {
+            globalThis.sessionStorage?.setItem(STORAGE_KEY, JSON.stringify(record));
+        }
+        catch { /* same: the in-memory record stands in */ }
+    }
+}

package/dist/client.d.ts

@@ -15,6 +15,9 @@ export type { LambderApiTransport, LambderApiTransportRequest, LambderTransportF
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, LambderLogListHandler, } from "./client/LambderCaller.js";
 export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/dist/client.js

@@ -14,6 +14,9 @@ export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFail
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
+// The per-endpoint signature map a build ships with, how a caller reads it, and the reload-loop window.
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/dist/core/Lambder.d.ts

@@ -9,6 +9,7 @@ import type LambderSessionController from "../session/LambderSessionController.j
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import { type LambderIndexHtmlOptions } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
@@ -50,6 +51,7 @@ export type LambderCreatedHook = (lambderInstance: Lambder<any, any, any, any, a
  */
 export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false, _TPublicGuardsRequired extends boolean = false, _TSessionsEnabled extends boolean = true> {
     apiPath: string;
+    /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
     apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
     files: LambderFiles | null;
@@ -67,7 +69,10 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private actionList;
     /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
     private readonly pipeline;
-    private registeredApiNames;
+    /** Every registered API by name: what resolves a request's name to its definition ahead of the pipeline, and what apiSignatures() digests. */
+    private readonly apiDefinitions;
+    /** The signature of each endpoint as this server serves it, digested once per endpoint on first use. */
+    private readonly signatureDigests;
     private hookList;
     private createdHooks;
     private initPromise;
@@ -165,6 +170,15 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     getSessionController(ctx: LambderRenderContext | LambderSessionRenderContext<any, TSessionData>): LambderSessionController<TSessionData>;
     /** The session manager, for code that works on sessions outside a request (maintenance, tests). */
     getSessionManager(): LambderSessionManager<TSessionData>;
+    /**
+     * Every registered endpoint's signature, keyed by its hashed name: the
+     * LambderApiSignatureMap a client build ships with. A generator imports
+     * the finished instance, awaits this, and writes the result to a file the
+     * frontend passes to LambderCaller as apiSignatures; at request time the
+     * server compares each call's signature against these same digests. Keys
+     * are sorted, so the generated file diffs by endpoint.
+     */
+    apiSignatures(): Promise<LambderApiSignatureMap>;
     getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
     private getResolver;
     getHandler(): LambderHandler;

package/dist/core/Lambder.js

@@ -10,6 +10,8 @@ import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
+import { LambderApiSignatureDigests } from "../api/LambderApiSignature.js";
+import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
 import { apiNotFoundAnswer, crashAnswer, refusalAnswer, } from "../api/LambderApiEnvelope.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
@@ -45,6 +47,7 @@ export default class Lambder {
     // Everything an instance is, fixed before the first registration.
     // =====================================================================
     apiPath;
+    /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
     apiVersion;
     /** The instance's file reader (source + caches), or null without the files option. */
     files;
@@ -62,7 +65,10 @@ export default class Lambder {
     actionList = [];
     /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
     pipeline;
-    registeredApiNames = new Set();
+    /** Every registered API by name: what resolves a request's name to its definition ahead of the pipeline, and what apiSignatures() digests. */
+    apiDefinitions = new Map();
+    /** The signature of each endpoint as this server serves it, digested once per endpoint on first use. */
+    signatureDigests;
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -95,8 +101,10 @@ export default class Lambder {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
         const session = options.session;
+        this.signatureDigests = new LambderApiSignatureDigests(options.guards);
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
+            signatures: this.signatureDigests,
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             // The app's own validation handler is read at call time, since
             // setApiInputValidationErrorHandler runs after creation.
@@ -200,7 +208,8 @@ export default class Lambder {
     // Typed API with Zod
     addApi(name, schema, handler) {
         this.assertApiRegistration(name, "public", schema);
-        const definition = { name, mode: "public", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input };
+        const definition = { name, mode: "public", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
+        this.apiDefinitions.set(name, definition);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
@@ -210,7 +219,8 @@ export default class Lambder {
     // Typed Session API with Zod
     addSessionApi(name, schema, handler) {
         this.assertApiRegistration(name, "session", schema);
-        const definition = { name, mode: "session", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input };
+        const definition = { name, mode: "session", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
+        this.apiDefinitions.set(name, definition);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
@@ -276,6 +286,19 @@ export default class Lambder {
     getSessionManager() {
         return this.pipeline.sessionManager;
     }
+    /**
+     * Every registered endpoint's signature, keyed by its hashed name: the
+     * LambderApiSignatureMap a client build ships with. A generator imports
+     * the finished instance, awaits this, and writes the result to a file the
+     * frontend passes to LambderCaller as apiSignatures; at request time the
+     * server compares each call's signature against these same digests. Keys
+     * are sorted, so the generated file diffs by endpoint.
+     */
+    async apiSignatures() {
+        const entries = await Promise.all([...this.apiDefinitions.values()].map(async (definition) => [await apiNameKeyOf(definition.name), await this.signatureDigests.signatureOf(definition)]));
+        entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return Object.fromEntries(entries);
+    }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
             files: this.files,
@@ -401,8 +424,9 @@ export default class Lambder {
             // The protocol's own pre-pass, run here rather than left to the
             // pipeline so that hooks and route matching see a plain payload,
             // and so a stale client is answered before any of them, whether or
-            // not the name it asked for exists.
-            const prepared = await this.pipeline.prepare(ctx.api);
+            // not the name it asked for exists: the gate is handed the
+            // definition the name resolves to, or null.
+            const prepared = await this.pipeline.prepare(ctx.api, this.apiDefinitions.get(ctx.api.apiName) ?? null);
             if (prepared)
                 return responseFromAnswer(prepared);
             // ctx.post is the raw body view; it shows the restored payload and
@@ -583,7 +607,7 @@ export default class Lambder {
     // =====================================================================
     /** Registration-time checks shared by addApi/addSessionApi. */
     assertApiRegistration(name, mode, options) {
-        if (this.registeredApiNames.has(name)) {
+        if (this.apiDefinitions.has(name)) {
             throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
         }
         // Everything that can refuse this registration runs before the name is
@@ -603,7 +627,6 @@ export default class Lambder {
                 `Declare the guard that authorizes it, or ${optOut}.`);
         }
         this.pipeline.assertRegistration({ name, mode, guards: options.guards, rateLimit: options.rateLimit, idempotency: options.idempotency });
-        this.registeredApiNames.add(name);
     }
     /**
      * The answer for a rejected input: the app's

package/dist/core/LambderCreateOptions.d.ts

@@ -99,6 +99,12 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     files?: LambderFilesOption;
     apiPath?: string;
+    /**
+     * Stamped on every API answer's envelope as `apiVersion`, so a client can
+     * tell which build answered. Informational: whether a client is stale is
+     * decided per endpoint by the signature it sends (see
+     * Lambder.apiSignatures()), not by this string.
+     */
     apiVersion?: string;
     /**
      * Automatic compression for compressible responses. `true` (the default)

package/dist/core/LambderCreateOptions.js

@@ -23,11 +23,6 @@ export const assertCreateOptions = (options) => {
     if (options.apiPath !== undefined && (options.apiPath === "" || !options.apiPath.startsWith("/"))) {
         throw new Error(`Lambder: apiPath must be a path starting with "/", got ${JSON.stringify(options.apiPath)}.`);
     }
-    // "" is the one string that turns the version gate off while looking like
-    // it was set; say so rather than accepting every version a client names.
-    if (options.apiVersion === "") {
-        throw new Error("Lambder: apiVersion must not be empty. Leave it out to run without the version gate.");
-    }
     // 0 or a negative ceiling turned every response into the size guard's own 500.
     if (options.maxResponseBytes !== undefined)
         assertPositiveInteger(options.maxResponseBytes, "maxResponseBytes");

package/dist/index.d.ts

@@ -25,6 +25,11 @@ export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
 export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderApiCallContext.js";
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
+export { apiSignatureOf, LambderApiSignatureDigests } from "./api/LambderApiSignature.js";
+export type { LambderApiSignatureSource } from "./api/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export type { LambderApiEnvelopeConfig, LambderValidationAnswerBody } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";

package/dist/index.js

@@ -16,6 +16,10 @@ export { readApiEnvelope, restoreCompressedPayload } from "./api/LambderApiReque
 export { toHttpAnswer } from "./api/LambderApiAnswer.js";
 export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader } from "./shared/wire/LambderAnswerHeaders.js";
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
+// Per-endpoint signatures: what a client build ships with, digested from the server's own registrations.
+export { apiSignatureOf, LambderApiSignatureDigests } from "./api/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
 // Calling a Lambder app from another lambda (server-only: the Lambda SDK, zlib)

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -22,6 +22,7 @@
  */
 import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
 import { type LambderInvokeFailure, type LambderInvokeOutcome } from "./LambderInvokeOutcome.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambdaClient, LambdaClientConfig } from "@aws-sdk/client-lambda";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from "../shared/wire/LambderCallOptions.js";
@@ -92,8 +93,15 @@ type LambderInvokeCallerBaseOptions = {
     clientConfig?: LambdaClientConfig;
     /** Must match the callee's apiPath. Default: "/api". */
     apiPath?: string;
-    /** Sent as `version`; the callee answers versionExpired on a mismatch when it has one too. Default: none. */
+    /** Sent as `version`, informational: the callee stamps its own on every answer. Default: none. */
     apiVersion?: string;
+    /**
+     * The callee's signature map, generated from its instance
+     * (Lambder.apiSignatures()) when this caller was built. Sent per call as
+     * `signature`, so the callee answers versionExpired to a call built
+     * against another shape of the endpoint. Default: none, and no gate.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /** The Host the callee sees (ctx.host). Default: functionName. */
     host?: string;
     /**
@@ -146,6 +154,8 @@ export type LambderInvokeEventInit = {
     /** Default: "lambder-invoke". */
     host?: string;
     apiVersion?: string;
+    /** The caller's signature for the endpoint, out of the callee's map. */
+    signature?: string;
     guardInputs?: Record<string, unknown>;
     idempotencyKey?: string;
     clientIp?: string;
@@ -161,6 +171,7 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
     private readonly functionName;
     private readonly apiPath;
     private readonly apiVersion?;
+    private readonly apiSignatures?;
     private readonly host;
     private readonly requestCompression;
     private readonly maxResponsePayloadBytes;

package/dist/invoke/LambderInvokeCaller.js

@@ -22,6 +22,7 @@
  */
 import { classifyDeliveryFailure, describeFailure, errorFromFunctionError, LambderInvokeError, parseFunctionError, } from "./LambderInvokeOutcome.js";
 import { DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
+import { readApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { resolveApiOutcome } from "../shared/wire/LambderApiOutcome.js";
 import { mergeGuardInputs, } from "../shared/wire/LambderCallOptions.js";
 import { createCallAbort, stopWaitingWhenAborted } from "../shared/util/LambderCallAbort.js";
@@ -44,6 +45,7 @@ export default class LambderInvokeCaller {
     functionName;
     apiPath;
     apiVersion;
+    apiSignatures;
     host;
     requestCompression;
     maxResponsePayloadBytes;
@@ -57,7 +59,7 @@ export default class LambderInvokeCaller {
     client;
     sdk;
     constructor(options) {
-        const { functionName, client, clientConfig, apiPath, apiVersion, host, requestCompression, maxResponsePayloadBytes, timeoutMs, onLogList, onFailure, sessionTokenCookieKey, transport, guardInputsProvider, } = options;
+        const { functionName, client, clientConfig, apiPath, apiVersion, apiSignatures, host, requestCompression, maxResponsePayloadBytes, timeoutMs, onLogList, onFailure, sessionTokenCookieKey, transport, guardInputsProvider, } = options;
         if (!functionName?.trim())
             throw new Error("LambderInvokeCaller: functionName is required");
         this.functionName = functionName;
@@ -65,6 +67,7 @@ export default class LambderInvokeCaller {
         this.clientConfig = clientConfig;
         this.apiPath = apiPath ?? "/api";
         this.apiVersion = apiVersion;
+        this.apiSignatures = apiSignatures;
         this.host = host ?? functionName;
         // `?? false`: like the browser caller, off unless asked for.
         this.requestCompression = resolveCompressionOption(requestCompression ?? false, DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS);
@@ -93,6 +96,7 @@ export default class LambderInvokeCaller {
             body: buildEnvelopeJson({
                 apiName: init.apiName,
                 version: init.apiVersion,
+                signature: init.signature,
                 csrf: init.session?.csrf,
                 siteHost: host,
                 payloadJson: init.payload !== undefined ? JSON.stringify(init.payload) : undefined,
@@ -290,6 +294,10 @@ export default class LambderInvokeCaller {
         let event;
         let eventJson;
         try {
+            // The callee's signature for this endpoint, when this caller was
+            // built with the callee's map. A name the map lacks fails here,
+            // as a provider that threw would: the map predates the endpoint.
+            const signature = this.apiSignatures ? await readApiSignature(this.apiSignatures, apiName) : undefined;
             // Provider values underneath, per-call values on top.
             const provided = this.guardInputsProvider
                 ? await this.guardInputsProvider(apiName)
@@ -314,6 +322,7 @@ export default class LambderInvokeCaller {
                 body: buildEnvelopeJson({
                     apiName,
                     version: this.apiVersion,
+                    signature,
                     csrf: options.session?.csrf,
                     siteHost: this.host,
                     payloadJson: compressed ? undefined : payloadJson,

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -57,6 +57,7 @@ export declare const synthesizeLambdaHttpEvent: (request: LambderSynthesizedRequ
 export declare const buildEnvelopeJson: (fields: {
     apiName: string;
     version?: string;
+    signature?: string;
     csrf?: string;
     siteHost: string;
     /** The payload's own JSON, when it goes plainly. */

package/dist/invoke/LambderLambdaEvent.js

@@ -117,6 +117,7 @@ export const buildEnvelopeJson = (fields) => {
     const withoutPayload = JSON.stringify(buildEnvelopeFields({
         apiName: fields.apiName,
         version: fields.version,
+        signature: fields.signature,
         token: fields.csrf ?? "",
         siteHost: fields.siteHost,
         compressed: fields.compressed,

package/dist/mock/LambderMockApp.d.ts

@@ -16,7 +16,7 @@ import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, L
  * Lambda server runs) over memory stores, with a registry of typed mock
  * handlers where the server has app handlers, and mock guards where it has
  * app guards. Everything the protocol does (envelope, refusals, sessions
- * and their cookies, guards, rate limits, idempotency, the version gate)
+ * and their cookies, guards, rate limits, idempotency, the signature gate)
  * happens in the core; this class only resolves a name to an entry, wraps
  * the handler's return into the envelope, and adds what a mock needs on
  * top: failure injection, latency, a subscription, a call log, reset.
@@ -176,7 +176,7 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      *
      * Public because the mode of an unregistered name cannot be recovered at
      * runtime, the contract being a type. Everything that precedes dispatch
-     * still runs (the version gate, the payload restore); the session read is
+     * still runs (the signature gate, the payload restore); the session read is
      * the one step this answer cannot have, which is the fidelity limit
      * restNotMocked documents.
      */

package/dist/mock/LambderMockApp.js

@@ -1,3 +1,4 @@
+import { lookupApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { createApiCallContext } from "../api/LambderApiCallContext.js";
@@ -40,7 +41,7 @@ const defaultCookieHost = () => globalThis.location?.host || "localhost";
  * Lambda server runs) over memory stores, with a registry of typed mock
  * handlers where the server has app handlers, and mock guards where it has
  * app guards. Everything the protocol does (envelope, refusals, sessions
- * and their cookies, guards, rate limits, idempotency, the version gate)
+ * and their cookies, guards, rate limits, idempotency, the signature gate)
  * happens in the core; this class only resolves a name to an entry, wraps
  * the handler's return into the envelope, and adds what a mock needs on
  * top: failure injection, latency, a subscription, a call log, reset.
@@ -116,8 +117,13 @@ export class LambderMockApp {
         const idempotencyOptions = options.idempotency === true ? {} : options.idempotency || null;
         const memoryIdempotency = idempotencyOptions && !idempotencyOptions.store ? new LambderMemoryIdempotencyStore() : null;
         this.idempotencyStore = memoryIdempotency;
+        // The generated map stands in for the server's schemas: the runtime
+        // cannot digest what it does not hold, so it answers with the map's
+        // entry for the name and the pipeline compares, as on the server.
+        const apiSignatures = options.apiSignatures;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
+            signatures: apiSignatures ? { expectedSignatureOf: (apiName) => lookupApiSignature(apiSignatures, apiName) } : undefined,
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             sessions: sessionOptions
                 ? {
@@ -351,7 +357,7 @@ export class LambderMockApp {
      *
      * Public because the mode of an unregistered name cannot be recovered at
      * runtime, the contract being a type. Everything that precedes dispatch
-     * still runs (the version gate, the payload restore); the session read is
+     * still runs (the signature gate, the payload restore); the session read is
      * the one step this answer cannot have, which is the fidelity limit
      * restNotMocked documents.
      */
@@ -549,7 +555,7 @@ export class LambderMockApp {
         return {
             phase: "request", id, apiName: request.apiName, mode,
             payload: request.payload, guardInputs: request.guardInputs, idempotencyKey: request.idempotencyKey,
-            version: request.version, headers: request.headers,
+            version: request.version, signature: request.signature, headers: request.headers,
             hasSessionCookie: (request.cookies[this.tokenCookieKey]?.length ?? 0) > 0,
             at,
         };
@@ -593,16 +599,18 @@ export class LambderMockApp {
         let outcome;
         let error;
         try {
-            // The protocol's pre-pass, run before the name is resolved, which
-            // is where the server runs it. Two things depended on it: an
-            // unknown name reached the notFound refusal without the version
-            // gate or the payload restore, so a stale client or a malformed
-            // compressed payload was answered differently here than on the
-            // server; and the request event carried the wire fields instead of
-            // the payload, so a dev panel watching calls in flight showed
-            // nothing for exactly the compressed calls someone opens a panel
-            // for. run() calls prepare again, which is safe by construction.
-            const prepared = await this.pipeline.prepare(request);
+            // The protocol's pre-pass, run ahead of dispatch with the
+            // definition the name resolved to (null for a name nothing
+            // registered), which is where the server runs it. Two things
+            // depended on it: an unknown name reached the notFound refusal
+            // without the signature gate or the payload restore, so a stale
+            // client or a malformed compressed payload was answered
+            // differently here than on the server; and the request event
+            // carried the wire fields instead of the payload, so a dev panel
+            // watching calls in flight showed nothing for exactly the
+            // compressed calls someone opens a panel for. run() calls prepare
+            // again, which is safe by construction.
+            const prepared = await this.pipeline.prepare(request, registered?.definition ?? null);
             this.emit(this.requestEvent(id, request, mode, startedAt));
             await this.failures.wait(this.failures.latencyFor(request.apiName), request.signal);
             if (this.failures.offline)

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -1,3 +1,4 @@
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderContractGuardNames } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
@@ -99,8 +100,16 @@ type LambderMockGuardShapes<S, G> = {
     [N in keyof G]: LambderMockSurplusKeys<G[N], LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
 };
 export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & {
-    /** Enables the version gate: a call naming another version answers versionExpired, exactly as the server would. */
+    /** Stamped on every answer's envelope as apiVersion, as the server's option is. */
     apiVersion?: string;
+    /**
+     * The generated signature map the caller carries, so the runtime refuses a
+     * stale signature exactly as the server would: a call whose signature is
+     * not the map's entry for its endpoint answers versionExpired. Without it
+     * every signature passes, since the runtime holds no server schema to
+     * digest.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /** Artificial latency per call; off by default. */
     latency?: LambderMockLatency;
     /** Sessions over the memory store: `true` for the defaults, or the options. Off by default: session endpoints then fail at registration. */

package/dist/mock/LambderMockCreateOptions.js

@@ -1,9 +1 @@
-/*
- * What a mock runtime is configured with, and the shapes of what a mock
- * transport takes.
- *
- * Everything create() takes lives here, beside the rules that decide which
- * keys it accepts (the guards option and the surplus-key checks under it),
- * exactly as core/LambderCreateOptions.ts holds the server's.
- */
 export {};

package/dist/mock/LambderMockTypes.d.ts

@@ -374,6 +374,8 @@ export type LambderMockRequestEvent = {
     /** Exactly as posted, so `unknown`: the key is client data and only the idempotency engine judges it. */
     idempotencyKey: unknown;
     version: string | null;
+    /** The signature the caller sent for the endpoint; null when it carries no map. */
+    signature: string | null;
     headers: Record<string, string>;
     /** True when the request carried a session cookie. */
     hasSessionCookie: boolean;

package/dist/shared/transport/LambderApiTransport.d.ts

@@ -10,6 +10,8 @@ export type LambderApiTransportRequest = {
     apiPath: string;
     apiName: string;
     version?: string;
+    /** The caller's signature for this endpoint, out of its LambderApiSignatureMap; absent when it carries no map. */
+    signature?: string;
     /** The CSRF token the caller read from its cookie; "" when it holds none. */
     token: string;
     /**
@@ -101,6 +103,7 @@ export type LambderApiTransport = (request: LambderApiTransportRequest) => Promi
 export declare const buildEnvelopeFields: (fields: {
     apiName: string;
     version?: string;
+    signature?: string;
     /** The CSRF token, as the envelope names it. */
     token: string;
     siteHost: string;

package/dist/shared/transport/LambderApiTransport.js

@@ -29,6 +29,7 @@ export const isLambderTransportFailure = (err) => err instanceof Error && err.is
 export const buildEnvelopeFields = (fields) => ({
     apiName: fields.apiName,
     version: fields.version,
+    ...(fields.signature !== undefined ? { signature: fields.signature } : {}),
     token: fields.token,
     siteHost: fields.siteHost,
     ...(fields.compressed ?? fields.payloadSlot ?? {}),
@@ -43,6 +44,7 @@ export const buildEnvelopeFields = (fields) => ({
 export const buildTransportEnvelope = (request) => buildEnvelopeFields({
     apiName: request.apiName,
     version: request.version,
+    signature: request.signature,
     token: request.token,
     siteHost: request.siteHost,
     payloadSlot: { payload: request.payload },

package/dist/shared/wire/LambderApiSignature.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The per-endpoint signatures a client carries, generated from the server's
+ * own registrations (Lambder.apiSignatures()) and shipped with the client
+ * build. The key is the endpoint's name hashed (apiNameKeyOf); the value is
+ * the digest of its client-facing shape (apiSignatureOf, computed on the
+ * server side). A caller given the map sends the value with every call, and
+ * the server answers versionExpired when it differs from the digest of what
+ * it serves now. So a client built against an endpoint that has since
+ * changed reloads, while one whose endpoint is unchanged keeps working
+ * across deploys.
+ *
+ * Keys are hashed so the map lists no endpoint names: the names a client
+ * calls are in its own code already, and the rest of the surface stays out
+ * of the bundle.
+ */
+export type LambderApiSignatureMap = Record<string, string>;
+/**
+ * How many hex characters a key and a signature keep. This is change
+ * detection, not authentication: 64 bits cannot collide by accident across
+ * the shapes one endpoint takes over its life, and the map stays small.
+ */
+export declare const API_SIGNATURE_HEX_LENGTH = 16;
+/** The key an endpoint's signature is stored under: SHA-256 over the prefixed name, cut to API_SIGNATURE_HEX_LENGTH hex characters. */
+export declare const apiNameKeyOf: (apiName: string) => Promise<string>;
+/** The map's signature for one endpoint, or null when the map holds none for it. */
+export declare const lookupApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string | null>;
+/**
+ * The signature a caller sends for one endpoint. A name the map does not
+ * hold throws: the map was generated from a server that did not have this
+ * endpoint, so the file is stale, and a call sent without a signature would
+ * run instead of saying so.
+ */
+export declare const readApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string>;