lambder 12.0.1 → 14.0.1

package/dist/core/LambderInvocationScope.js

@@ -0,0 +1,21 @@
+import { invocationScope } from "../shared/util/LambderInvocationScope.js";
+/** Whether this process has started an invocation yet: the first one is its cold start. */
+let processStarted = false;
+/** Runs one invocation under a record of its own, which `currentInvocation()` finds from anything it runs. */
+export const runInvocation = (lambdaContext, run) => {
+    const record = {
+        requestId: typeof lambdaContext?.awsRequestId === "string" && lambdaContext.awsRequestId ? lambdaContext.awsRequestId : null,
+        startedAt: performance.now(),
+        coldStart: !processStarted,
+        handlerMs: null,
+        replayed: false,
+        call: null,
+        outcome: null,
+    };
+    processStarted = true;
+    return invocationScope.run(record, () => run(record));
+};
+/** The invocation the calling code runs under, or null outside one (a script, a test calling a library directly). */
+export const currentInvocation = () => 
+// Only runInvocation opens the scope, and always with a whole record.
+invocationScope.getStore() ?? null;

package/dist/core/LambderResponse.d.ts

@@ -3,6 +3,7 @@ import type { LambderCompressionOption, LambderCompressionSettingsBase, LambderE
 import type { LambderRenderContext, LambderHttpEventFormat } from "./LambderContext.js";
 import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
+import type { LambderCallOutcomeHint } from "../shared/wire/LambderCallOutcome.js";
 export type LambderHeadersInput = Record<string, string | string[]>;
 /**
  * Final Lambda response: v1 (REST API) uses multiValueHeaders, v2 (HTTP API /
@@ -31,6 +32,8 @@ type LambderResponseInit = {
     compress?: boolean | "auto";
     /** "auto": ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
+    /** What the response answers an API call with, when it was written as an API answer; see LambderResponse.callOutcome. */
+    callOutcome?: LambderCallOutcomeHint | null;
 };
 /**
  * Intermediate response object returned by all response builder methods and by
@@ -49,6 +52,14 @@ export declare class LambderResponse {
     isBodyBase64: boolean;
     compress: boolean | "auto";
     etag: boolean | "auto";
+    /**
+     * What this response answers an API call with (a success, a refusal and
+     * its code, a flag), when it was written as an API answer: the envelope
+     * builders and res.apiRefusal() set it, and the call's summary line reads
+     * it, so the line does not parse the body back. Null on any other
+     * response, which the line names `other`.
+     */
+    callOutcome: LambderCallOutcomeHint | null;
     constructor(init: LambderResponseInit);
     /**
      * A copy with its own header lists, for a request to write into. A

package/dist/core/LambderResponse.js

@@ -21,6 +21,14 @@ export class LambderResponse {
     isBodyBase64;
     compress;
     etag;
+    /**
+     * What this response answers an API call with (a success, a refusal and
+     * its code, a flag), when it was written as an API answer: the envelope
+     * builders and res.apiRefusal() set it, and the call's summary line reads
+     * it, so the line does not parse the body back. Null on any other
+     * response, which the line names `other`.
+     */
+    callOutcome;
     constructor(init) {
         this.statusCode = init.statusCode;
         this.headers = normalizeHeaders(init.headers);
@@ -28,6 +36,7 @@ export class LambderResponse {
         this.isBodyBase64 = init.isBodyBase64 ?? false;
         this.compress = init.compress ?? "auto";
         this.etag = init.etag ?? "auto";
+        this.callOutcome = init.callOutcome ?? null;
     }
     /**
      * A copy with its own header lists, for a request to write into. A
@@ -44,6 +53,7 @@ export class LambderResponse {
             isBodyBase64: this.isBodyBase64,
             compress: this.compress,
             etag: this.etag,
+            callOutcome: this.callOutcome,
         });
     }
     // The header methods delegate to the core's header helpers, so an answer
@@ -77,6 +87,7 @@ export const answerFromResponse = (response) => {
         isBodyBase64: response.isBodyBase64 || binary,
         compress: response.compress,
         etag: response.etag,
+        ...(response.callOutcome ? { outcome: response.callOutcome } : {}),
     };
 };
 /**
@@ -98,6 +109,7 @@ export const responseFromAnswer = (answer) => new LambderResponse({
     isBodyBase64: answer.isBodyBase64 ?? false,
     compress: answer.compress ?? "auto",
     etag: answer.etag ?? "auto",
+    callOutcome: answer.outcome ?? null,
 });
 const mimeOf = (contentType) => (contentType?.split(";")[0] ?? "").trim().toLowerCase();
 /** A content type whose body is text: sent as text when it is valid UTF-8 and not compressed. */

package/dist/core/LambderResponseBuilder.js

@@ -1,3 +1,4 @@
+import { outcomeOfEnvelope } from "../shared/wire/LambderCallOutcome.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { plainRefusalEnvelope } from "../api/LambderApiEnvelope.js";
 /**
@@ -145,7 +146,10 @@ export default class LambderResponseBuilder {
      * request accumulated unless the config names its own.
      */
     apiRefusal(config, options) {
-        return this.json(plainRefusalEnvelope(this.apiVersion, config, "res.apiRefusal()", this.ctx?.logList), options);
+        const envelope = plainRefusalEnvelope(this.apiVersion, config, "res.apiRefusal()", this.ctx?.logList);
+        const response = this.json(envelope, options);
+        response.callOutcome = outcomeOfEnvelope(envelope, response.statusCode);
+        return response;
     }
     ;
 }

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
 export type { LambderHandlerTransportOptions } from "./invoke/lambderHandlerTransport.js";
-export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
+export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_PARENT_REQUEST_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
 export type { LambderSynthesizedRequest, LambderLambdaHttpResult, LambderInvokeSession } from "./invoke/LambderLambdaEvent.js";
 export { LambderApiPipeline } from "./api/LambderApiPipeline.js";
 export type { LambderApiPipelineOptions, LambderApiSessionsConfig, LambderApiInputRefusal, LambderApiRunResult, LambderApiExec } from "./api/LambderApiPipeline.js";
@@ -100,7 +100,7 @@ export { refuseUnacceptedUpload } from "./shared/wire/LambderUploadRefusal.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
 export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
-export type { LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export type { LambderCreatedSession, LambderSessionDataOptions, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/wire/LambderCompressionOption.js";
 export type { LambderCompressionOption, LambderCompressionSettings, LambderCompressionSettingsBase, LambderEncoding, } from "./shared/wire/LambderCompressionOption.js";
 export { compressText, restoreBytes, restoreText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "./shared/wire/LambderCompressionCodec.js";
@@ -134,14 +134,14 @@ export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
 export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderGuardNamesInputLacks, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
 export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
-export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
+export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderRefusalVocabularyOption, LambderMergedRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
 export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderPolicyNamesInputLacks, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitMessage, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderRefusalsOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
-export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
-export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
+export { apiGuardParam, apiGuardParamExportName } from "./shared/wire/LambderApiOptionEntries.js";
+export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, LambderApiGuardParam, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiSuccessEnvelope, LambderApiRefusalEnvelope, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderContractEntry, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderContractRefusalsOf, LambderContractRefusalMessage, LambderContractRefusals, LambderContractAnyRefusalMessage, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
@@ -149,7 +149,9 @@ export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEven
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
-export type { LambderContextOptions } from "./core/LambderContext.js";
+export type { LambderContextOptions, LambderOriginProof } from "./core/LambderContext.js";
+export type { LambderCallSummary, LambderCallSummaryOption } from "./core/LambderCallSummary.js";
+export type { LambderCallOutcome, LambderCallOutcomeHint } from "./shared/wire/LambderCallOutcome.js";
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
 export type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/wire/LambderRequestPayload.js";
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
 export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
 export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
-export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
+export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_PARENT_REQUEST_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
 // The API core: the request, answer, envelope and pipeline both the server and the mock runtime run
 export { LambderApiPipeline } from "./api/LambderApiPipeline.js";
 export { readApiEnvelope, restoreCompressedPayload } from "./api/LambderApiRequest.js";
@@ -97,7 +97,7 @@ export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 // The declared options as plain data: what apiOptionEntries() reports and
 // writeApiOptions writes, and the readers over the generated tables.
-export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
+export { apiGuardParam, apiGuardParamExportName } from "./shared/wire/LambderApiOptionEntries.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -10,6 +10,7 @@
  */
 import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, Context } from "aws-lambda";
 import type { LambderHttpEventFormat } from "../core/LambderContext.js";
+import { LAMBDER_PARENT_REQUEST_HEADER } from "../shared/wire/LambderInvokeApiId.js";
 import type { LambderCompressedBrotliPayload, LambderCompressedGzipPayload } from "../shared/wire/LambderRequestPayload.js";
 /**
  * Marks a synthesized request as an invoke, for guards and hooks that want to
@@ -20,6 +21,7 @@ import type { LambderCompressedBrotliPayload, LambderCompressedGzipPayload } fro
 export declare const LAMBDER_INVOKE_HEADER = "x-lambder-invoke";
 /** The invoking function's name, when the caller runs in Lambda; for the callee's logs. */
 export declare const LAMBDER_INVOKED_BY_HEADER = "x-lambder-invoked-by";
+export { LAMBDER_PARENT_REQUEST_HEADER };
 /** The value of the marker header; a future incompatible event shape would bump it. */
 export declare const LAMBDER_INVOKE_PROTOCOL = "1";
 /** A session carried on a user's behalf: the two values a browser holds. */

package/dist/invoke/LambderLambdaEvent.js

@@ -10,8 +10,9 @@
  */
 import { restoreBytes } from "../shared/wire/LambderCompressionCodec.js";
 import { bytesToBase64 } from "../shared/util/LambderBase64.js";
-import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.js";
+import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID, LAMBDER_PARENT_REQUEST_HEADER } from "../shared/wire/LambderInvokeApiId.js";
 import { buildEnvelopeFields } from "../shared/transport/LambderApiTransport.js";
+import { currentRequestId } from "../shared/util/LambderInvocationScope.js";
 /**
  * Marks a synthesized request as an invoke, for guards and hooks that want to
  * tell. Not an authorization: over HTTP it is a header any client can send.
@@ -21,6 +22,7 @@ import { buildEnvelopeFields } from "../shared/transport/LambderApiTransport.js"
 export const LAMBDER_INVOKE_HEADER = "x-lambder-invoke";
 /** The invoking function's name, when the caller runs in Lambda; for the callee's logs. */
 export const LAMBDER_INVOKED_BY_HEADER = "x-lambder-invoked-by";
+export { LAMBDER_PARENT_REQUEST_HEADER };
 /** The value of the marker header; a future incompatible event shape would bump it. */
 export const LAMBDER_INVOKE_PROTOCOL = "1";
 /**
@@ -47,9 +49,10 @@ export function synthesizeLambdaHttpEvent(request, options) {
     // what this event is. Forwarding a browser's headers wholesale is an
     // ordinary gateway-lambda pattern, and without these deletes it would let
     // a browser-shaped request claim to be an invoke, or an invoke name an
-    // invoking function that did not send it.
+    // invoking function or invocation that did not send it.
     delete headers[LAMBDER_INVOKE_HEADER];
     delete headers[LAMBDER_INVOKED_BY_HEADER];
+    delete headers[LAMBDER_PARENT_REQUEST_HEADER];
     if (options.invoke)
         delete headers[FORWARDED_FOR_HEADER];
     headers.host = request.host;
@@ -59,6 +62,9 @@ export function synthesizeLambdaHttpEvent(request, options) {
         const invokedBy = typeof process !== "undefined" ? process.env?.AWS_LAMBDA_FUNCTION_NAME : undefined;
         if (invokedBy)
             headers[LAMBDER_INVOKED_BY_HEADER] = invokedBy;
+        const parentRequestId = currentRequestId();
+        if (parentRequestId)
+            headers[LAMBDER_PARENT_REQUEST_HEADER] = parentRequestId;
     }
     const isBinary = Buffer.isBuffer(request.body);
     if (request.contentType)

package/dist/mock/LambderMockApp.d.ts

@@ -3,7 +3,7 @@ import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import { type LambderApiAnswer } from "../api/LambderApiAnswer.js";
 import { type LambderDeclaredRefuse, type LambderRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
-import { type LambderDeclaredVocabulary, type LambderHandlerRefusalsOf, type LambderRefusalVocabulary, type LambderRefusalVocabularyChecks } from "../api/LambderApiRefusals.js";
+import { type LambderDeclaredVocabulary, type LambderHandlerRefusalsOf, type LambderRefusalVocabulary, type LambderRefusalVocabularyOption, type LambderRefusalVocabularyOptionChecks, type LambderMergedRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { type LambderApiTransport, type LambderApiTransportRequest } from "../shared/transport/LambderApiTransport.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { type LambderApiGuard, type LambderGuardBuilder } from "../api/LambderApiGuards.js";
@@ -349,16 +349,16 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
  */
 export declare const initLambderMock: <C extends LambderApiContractShape, S = any>() => {
     /**
-     * Declares the server's refusal vocabulary on the mock: the same object,
-     * and the same `requireCodes`, the server's init declares, imported from
-     * shared code (codes, zod schemas, statuses and flags hold nothing
-     * secret). Given, every refusal an entry answers with is checked and sent
+     * Declares the server's refusal vocabulary on the mock: the same map, or
+     * list of maps, and the same `requireCodes`, the server's init declares,
+     * imported from shared code (codes, zod schemas, statuses and flags hold
+     * nothing secret). Given, every refusal an entry answers with is checked and sent
      * as the server would send it: the code among the codes the tables give
      * the entry, its data parsed through the code's schema from the input
      * form, and the declaration's status and flag. An entry whose tables name
      * a code needs it.
      */
-    declareRefusals<const TVocabulary extends LambderRefusalVocabulary, const TRequireCodes extends boolean = false>(refusals: TVocabulary & LambderRefusalVocabularyChecks<TVocabulary>, options?: {
+    declareRefusals<const TVocabulary extends LambderRefusalVocabularyOption, const TRequireCodes extends boolean = false>(refusals: TVocabulary & LambderRefusalVocabularyOptionChecks<TVocabulary>, options?: {
         requireCodes?: TRequireCodes;
     }): {
         /** Builds a mock guard: the server guard's shape, the handler seeing the mock's contexts. */
@@ -376,7 +376,7 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
          * codes and `data` the schema's input form, parsed as the server parses
          * it. The free refuse() where the mock declared none.
          */
-        refuse: [TVocabulary] extends [never] ? (content: string, options?: import("../shared/wire/LambderApiRefusal.js").LambderRefuseOptions) => never : LambderDeclaredRefuse<LambderHandlerRefusalsOf<TVocabulary, keyof TVocabulary & string>, TRequireCodes>;
+        refuse: [LambderMergedRefusalVocabulary<TVocabulary>] extends [never] ? (content: string, options?: import("../shared/wire/LambderApiRefusal.js").LambderRefuseOptions) => never : LambderDeclaredRefuse<LambderHandlerRefusalsOf<LambderMergedRefusalVocabulary<TVocabulary>, keyof LambderMergedRefusalVocabulary<TVocabulary> & string>, TRequireCodes>;
         /**
          * The mock app, with the guard map and the rate-limit policies inferred
          * from the options.
@@ -388,7 +388,7 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
          * dropped. `I` exists for the same reason `P` does, and
          * LambderMockSurplusKeys puts the error back on the key.
          */
-        create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, TVocabulary, TRequireCodes>;
+        create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, LambderMergedRefusalVocabulary<TVocabulary>, TRequireCodes>;
     };
     /** Builds a mock guard: the server guard's shape, the handler seeing the mock's contexts. */
     guard: LambderGuardBuilder<LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;

package/dist/mock/LambderMockApp.js

@@ -7,7 +7,7 @@ import { envelopeAnswer, crashAnswer, plainRefusalEnvelope, refusalEnvelope, suc
 import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES, refuse as refuseApiCall } from "../shared/wire/LambderApiRefusal.js";
-import { allowedRefusalOf, readRefusalVocabulary, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { allowedRefusalOf, declaredRefusalVocabulary, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { buildTransportEnvelope } from "../shared/transport/LambderApiTransport.js";
 import { lambderCookieJarTransport } from "../shared/transport/lambderCookieJarTransport.js";
@@ -163,7 +163,9 @@ export class LambderMockApp {
                         sessionSalt: sessionOptions.sessionSalt ?? "lambder-mock",
                         enableSlidingExpiration: sessionOptions.enableSlidingExpiration,
                         slidingWriteIntervalSeconds: sessionOptions.slidingWriteIntervalSeconds,
-                        dataRefresh: sessionOptions.dataRefresh,
+                        // As given: the manager refuses dataRefresh without
+                        // the schema, which an untyped caller can still pass.
+                        ...{ dataRefresh: sessionOptions.dataRefresh, dataSchema: sessionOptions.dataSchema },
                         // A plain-http page (device testing on a LAN) has no
                         // crypto.subtle, and a memory-only store is nothing
                         // anyone can leak, so hashing there protects nothing.
@@ -957,19 +959,21 @@ const lambderMockInitOf = (declared) => ({
 export const initLambderMock = () => ({
     ...lambderMockInitOf(null),
     /**
-     * Declares the server's refusal vocabulary on the mock: the same object,
-     * and the same `requireCodes`, the server's init declares, imported from
-     * shared code (codes, zod schemas, statuses and flags hold nothing
-     * secret). Given, every refusal an entry answers with is checked and sent
+     * Declares the server's refusal vocabulary on the mock: the same map, or
+     * list of maps, and the same `requireCodes`, the server's init declares,
+     * imported from shared code (codes, zod schemas, statuses and flags hold
+     * nothing secret). Given, every refusal an entry answers with is checked and sent
      * as the server would send it: the code among the codes the tables give
      * the entry, its data parsed through the code's schema from the input
      * form, and the declaration's status and flag. An entry whose tables name
      * a code needs it.
      */
     declareRefusals(refusals, options = {}) {
-        const vocabulary = readRefusalVocabulary(refusals);
-        if (!vocabulary)
-            throw new Error("LambderMockApp: declareRefusals() takes the vocabulary, an object of codes.");
-        return lambderMockInitOf({ refusals, vocabulary, requireCodes: (options.requireCodes ?? false) });
+        const declared = declaredRefusalVocabulary(refusals, "LambderMockApp");
+        return lambderMockInitOf({
+            refusals: declared.refusals,
+            vocabulary: declared.vocabulary,
+            requireCodes: (options.requireCodes ?? false),
+        });
     },
 });

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -13,7 +13,7 @@ import type { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import type { LambderRateLimiter, LambderRateLimitWindow } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
-import type { LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
+import type { LambderSessionDataOptions } from "../session/LambderSessionManager.js";
 import type { LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import type { LambderSessionCrypto } from "../session/LambderSessionCrypto.js";
 import type { LambderMockCallContext, LambderMockGuards, LambderMockLatency, LambderMockRateLimitPolicies, LambderMockSessionCallContext, LambderMockSessionGuardsCheck, LambderMockSurplusKeys } from "./LambderMockTypes.js";
@@ -26,13 +26,12 @@ export type LambderMockSessionsOptions<S> = {
     ttlSeconds?: number;
     /** Hashing and randomness. Default: WebCrypto where the runtime offers it, the plain stand-in over a memory-only store otherwise. */
     crypto?: LambderSessionCrypto;
-    dataRefresh?: LambderSessionDataRefreshConfig<S>;
     enableSlidingExpiration?: boolean;
     slidingWriteIntervalSeconds?: number;
     tokenCookieKey?: string;
     csrfCookieKey?: string;
     cookieOptions?: LambderSessionCookieOptions;
-};
+} & LambderSessionDataOptions<S>;
 /**
  * Idempotency in the mock: the same engine the server runs, over a memory
  * store unless one is given, and carrying every knob the server's own option

package/dist/session/LambderSessionManager.d.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import type { LambderSessionCrypto } from "./LambderSessionCrypto.js";
 import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
@@ -60,6 +61,39 @@ export declare class LambderSessionDataRefreshError extends Error {
 export declare class LambderSessionReadError extends Error {
     constructor(cause: unknown);
 }
+/**
+ * The shape session.data has, and how it is kept fresh: `dataSchema` alone,
+ * or with `dataRefresh`, which then requires it.
+ *
+ * A record outlives the code that wrote it, so a read checks its data
+ * against the schema, and hands the request the schema's output (keys it
+ * does not declare stripped). Data that does not match (a record written
+ * before a deploy changed the data's shape) is refreshed on that read when
+ * dataRefresh is configured, whatever its deadline; without dataRefresh
+ * nothing can rebuild it, and the session ends. A refresh's own output is
+ * held to the schema too, and one that does not match fails the read as a
+ * LambderSessionDataRefreshError.
+ *
+ * Data is held to the schema where it is written as well: createSession and
+ * updateSessionData throw on data it refuses, rather than store a session
+ * whose next read would end it. What is stored is the data as given, and
+ * what a request is served is the schema's output, so every read of a
+ * record parses exactly what its write was checked with.
+ *
+ * Data a refresh derives from the app's state changes shape as the app
+ * does, which is why dataRefresh needs the schema: without it, a record
+ * written before the change is served in its old shape until its refresh
+ * comes due.
+ */
+export type LambderSessionDataOptions<SessionData = any> = {
+    /** The schema of session.data, checked on every read. */
+    dataSchema?: z.ZodType<SessionData>;
+    dataRefresh?: undefined;
+} | {
+    /** The schema of session.data, checked on every read and on every refresh's output. Required beside dataRefresh. */
+    dataSchema: z.ZodType<SessionData>;
+    dataRefresh: LambderSessionDataRefreshConfig<SessionData>;
+};
 export type LambderSessionManagerOptions<SessionData = any> = {
     /** Where sessions rest: LambderDdbSessionStore, LambderMemorySessionStore, or your own. */
     store: LambderSessionStore<SessionData>;
@@ -68,10 +102,9 @@ export type LambderSessionManagerOptions<SessionData = any> = {
     enableSlidingExpiration?: boolean;
     /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
     slidingWriteIntervalSeconds?: number;
-    dataRefresh?: LambderSessionDataRefreshConfig<SessionData>;
     /** Hashing and randomness. Default: WebCrypto. */
     crypto?: LambderSessionCrypto;
-};
+} & LambderSessionDataOptions<SessionData>;
 /**
  * Whether a string has the shape a minted session token has:
  * `sessionKeyHash:secret`, both hex, neither longer than 1024 characters.
@@ -105,8 +138,9 @@ export default class LambderSessionManager<SessionData = any> {
     private readonly enableSlidingExpiration;
     private readonly slidingWriteIntervalSeconds;
     private readonly dataRefresh;
+    private readonly dataSchema;
     private readonly crypto;
-    constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, crypto, }: LambderSessionManagerOptions<SessionData>);
+    constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, dataSchema, crypto, }: LambderSessionManagerOptions<SessionData>);
     /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
     private assertCryptoFitsStore;
     /**
@@ -184,6 +218,15 @@ export default class LambderSessionManager<SessionData = any> {
      * logout, a password change), which a renewal must not undo.
      */
     renewSession(session: LambderSessionRecord<SessionData>): Promise<LambderSessionRecord<SessionData> | null>;
+    /**
+     * Data about to be stored, held to the schema: what a read of it will
+     * serve, or the error `refused` builds from where it does not match.
+     * Data the schema refuses is the app breaking its own declaration, and
+     * storing it would only move the failure to the next read, far from the
+     * code that wrote it. The data is stored as given, not as the schema's
+     * output, so every later read parses exactly what this check accepted.
+     */
+    private servedDataOf;
     /**
      * Runs the dataRefresh callback immediately, regardless of
      * dataExpiresAt, and persists the result onto the same record, over the

package/dist/session/LambderSessionManager.js

@@ -28,6 +28,11 @@ export class LambderSessionReadError extends Error {
         this.name = "LambderSessionReadError";
     }
 }
+/** A schema's issues as a message may show them: each path and what was expected there, never the value found. */
+const describeSchemaIssues = (error) => error.issues.slice(0, 5).map((issue) => `${issue.path.length ? issue.path.join(".") : "(the data)"}: ${issue.message}`).join("; ")
+    + (error.issues.length > 5 ? `; and ${error.issues.length - 5} more` : "");
+/** A refresh's output the schema refuses, as the read fails with it. */
+const refreshRefused = (issues) => new LambderSessionDataRefreshError(new Error(`the refreshed data does not match session.dataSchema (${issues})`));
 /**
  * The longest either half of a session token may be. A minted token is two
  * 64-character hex halves; sixteen times that leaves a custom
@@ -95,8 +100,9 @@ export default class LambderSessionManager {
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
+    dataSchema;
     crypto;
-    constructor({ store, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, crypto, }) {
+    constructor({ store, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, dataSchema, crypto, }) {
         this.store = store;
         this.sessionSalt = sessionSalt;
         this.enableSlidingExpiration = enableSlidingExpiration;
@@ -105,7 +111,16 @@ export default class LambderSessionManager {
             : assertPositiveInteger(slidingWriteIntervalSeconds, "session.slidingWriteIntervalSeconds");
         if (dataRefresh)
             assertPositiveInteger(dataRefresh.ttlSeconds, "session.dataRefresh.ttlSeconds");
+        if (dataRefresh && !dataSchema) {
+            throw new Error("Lambder: session.dataRefresh needs session.dataSchema, the schema session.data has. Data a refresh derives " +
+                "changes shape as the app does, and without the schema a record written before the change is served in its " +
+                "old shape until its refresh comes due; with it, such a record refreshes on its next read.");
+        }
+        if (dataSchema !== undefined && typeof dataSchema?.safeParse !== "function") {
+            throw new Error("Lambder: session.dataSchema is not a zod schema.");
+        }
         this.dataRefresh = dataRefresh ?? null;
+        this.dataSchema = dataSchema ?? null;
         this.crypto = crypto ?? new LambderWebCrypto();
         this.assertCryptoFitsStore(store);
         if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
@@ -167,6 +182,9 @@ export default class LambderSessionManager {
         // logout.
         if (!sessionKey)
             throw new Error("Lambder: createSession sessionKey is empty. It names the subject the session belongs to and partitions the store, so an empty one writes a record no read accepts.");
+        // Refused for the same reason: data the schema refuses would end the
+        // session on its first read, a sign-out right after the sign-in.
+        const served = this.servedDataOf(data, (issues) => new Error(`Lambder: createSession was given data that does not match session.dataSchema (${issues}).`));
         const sessionKeyHash = await this.sessionKeyHashOf(sessionKey);
         // The sort-key SECRET goes to the client; only its hash becomes the
         // store's range key, so the store never contains a usable token.
@@ -186,7 +204,7 @@ export default class LambderSessionManager {
             dataVersion: 0,
         };
         await this.store.create(session);
-        return { session, sessionToken, csrfToken };
+        return { session: { ...session, data: served }, sessionToken, csrfToken };
     }
     /**
      * Writes new session data onto the record, and nothing else: the expiry
@@ -217,14 +235,17 @@ export default class LambderSessionManager {
     async updateSessionData(session, newData) {
         if (!session)
             throw new Error("Invalid session");
+        // Data the schema refuses would end the session on its next read
+        // (see createSession), so the write that brings it fails instead.
+        const served = this.servedDataOf(newData, (issues) => new Error(`Lambder: updateSessionData was given data that does not match session.dataSchema (${issues}).`));
         const { sessionKeyHash, secretHash } = session;
         if (!this.dataRefresh) {
             const result = await this.store.update(sessionKeyHash, secretHash, { data: newData });
-            return result === "missing" ? null : { ...session, data: newData };
+            return result === "missing" ? null : { ...session, data: served };
         }
         const result = await this.store.update(sessionKeyHash, secretHash, { data: newData }, { dataVersion: session.dataVersion });
         if (result === "updated")
-            return { ...session, data: newData, dataVersion: session.dataVersion + 1 };
+            return { ...session, data: served, dataVersion: session.dataVersion + 1 };
         if (result === "missing")
             return null;
         // The data or its deadline was written in between: a revocation was
@@ -235,7 +256,7 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         if (await this.store.update(sessionKeyHash, secretHash, { data: newData, dataExpiresAt: now }) === "missing")
             return null;
-        return { ...session, data: newData, dataExpiresAt: now };
+        return { ...session, data: served, dataExpiresAt: now };
     }
     /**
      * The record a token names, read and structurally checked, with nothing
@@ -304,10 +325,22 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         const refreshed = {};
         const slid = {};
+        // The record's data checked against the schema (see
+        // LambderSessionDataOptions). Without dataRefresh nothing can rebuild
+        // data that does not match, so the session ends.
+        const read = this.dataSchema ? this.dataSchema.safeParse(session.data) : null;
+        if (read && !read.success && !this.dataRefresh) {
+            await this.deleteSession(session);
+            return null;
+        }
+        // What the request is served: the data as the schema reads it, or,
+        // once a refresh ran, the refresh's.
+        let served = read?.success ? read.data : session.data;
         // Renew session.data once its shelf life has passed (opt-in
-        // dataRefresh). A record created while dataRefresh was off has no
-        // dataExpiresAt, so it renews on its first read.
-        if (this.dataRefresh && (session.dataExpiresAt ?? 0) <= now) {
+        // dataRefresh), or at once when it does not match the schema. A
+        // record created while dataRefresh was off has no dataExpiresAt, so
+        // it renews on its first read.
+        if (this.dataRefresh && (read?.success === false || (session.dataExpiresAt ?? 0) <= now)) {
             let newData;
             try {
                 newData = await this.dataRefresh.refresh(session);
@@ -321,6 +354,7 @@ export default class LambderSessionManager {
                 await this.deleteSession(session);
                 return null;
             }
+            served = this.servedDataOf(newData, refreshRefused);
             refreshed.data = newData;
             refreshed.dataExpiresAt = now + this.dataRefresh.ttlSeconds;
         }
@@ -335,7 +369,7 @@ export default class LambderSessionManager {
                 slid.expiresAt = now + session.ttlInSeconds;
             }
         }
-        const renewed = { ...session, ...refreshed, ...slid };
+        const renewed = { ...session, ...refreshed, ...slid, data: served };
         if (refreshed.data === undefined && slid.expiresAt === undefined)
             return renewed;
         // Awaited, so it persists before Lambda freezes. A failing write is
@@ -361,11 +395,27 @@ export default class LambderSessionManager {
         }
         catch (err) {
             console.error(`Lambder session: the renewal write failed, so this session keeps its stored expiry. ${coerceToError(err).message}`);
-            return { ...session, ...refreshed };
+            return { ...session, ...refreshed, data: served };
         }
         return renewed;
     }
     ;
+    /**
+     * Data about to be stored, held to the schema: what a read of it will
+     * serve, or the error `refused` builds from where it does not match.
+     * Data the schema refuses is the app breaking its own declaration, and
+     * storing it would only move the failure to the next read, far from the
+     * code that wrote it. The data is stored as given, not as the schema's
+     * output, so every later read parses exactly what this check accepted.
+     */
+    servedDataOf(data, refused) {
+        if (!this.dataSchema)
+            return data;
+        const checked = this.dataSchema.safeParse(data);
+        if (checked.success)
+            return checked.data;
+        throw refused(describeSchemaIssues(checked.error));
+    }
     /**
      * Runs the dataRefresh callback immediately, regardless of
      * dataExpiresAt, and persists the result onto the same record, over the
@@ -390,13 +440,14 @@ export default class LambderSessionManager {
             await this.deleteSession(session);
             return null;
         }
+        const served = this.servedDataOf(newData, refreshRefused);
         const changes = { data: newData, dataExpiresAt: Math.floor(Date.now() / 1000) + this.dataRefresh.ttlSeconds };
         const result = await this.store.update(session.sessionKeyHash, session.secretHash, changes, { dataVersion: session.dataVersion });
         if (result === "missing")
             return null;
         // "stale": served, not written, and the record keeps the version it
         // was read with (see updateSessionData).
-        return { ...session, ...changes, ...(result === "updated" ? { dataVersion: session.dataVersion + 1 } : {}) };
+        return { ...session, ...changes, data: served, ...(result === "updated" ? { dataVersion: session.dataVersion + 1 } : {}) };
     }
     ;
     /**