lambder 7.2.5 → 8.0.2

package/dist/api/LambderApiIdempotency.js

@@ -1,70 +1,132 @@
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
-import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
+import { boundKeyField } from "../shared/util/boundKeyField.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import { canonicalJson } from "../shared/util/canonicalJson.js";
+import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+import { crashAnswer } from "./LambderApiEnvelope.js";
+import { LambderApiOutputValidationError } from "./LambderApiOutputValidationError.js";
 /**
- * A crashed original must not block retries forever, so a pending claim
- * expires on its own. The default is five minutes, which covers the great
- * majority of handlers.
- *
- * It has to outlive the handler, though, and that is the app's business to
- * know: a Lambda may run for fifteen minutes, and a claim that expires while
- * its own handler is still working hands the next retry a free scope, so the
- * operation runs a second time, which is the one thing idempotency exists to
- * prevent. An app whose handlers can run long should raise it to just past
- * its own timeout through `idempotency: { pendingTtlSeconds }`, or per API.
+ * A pending claim expires on its own so a crashed original cannot block
+ * retries forever. Five minutes covers most handlers, but the claim must
+ * outlive its handler: a Lambda may run for fifteen minutes, and a claim that
+ * expires mid-run hands the next retry a free scope, so the operation runs
+ * twice. Apps with long handlers raise it past their timeout through
+ * `idempotency: { pendingTtlSeconds }`, or per API.
  */
 const DEFAULT_IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
 /**
  * Keys must be unguessable: without a session, the replay scope is the key
  * itself, so a guessable key would let one client read another's stored
- * response. LambderCaller.createIdempotencyKey() returns 36 chars.
+ * response. createIdempotencyKey() returns 36 chars.
  */
 const IDEMPOTENCY_MIN_KEY_LENGTH = 16;
 const IDEMPOTENCY_MAX_KEY_LENGTH = 200;
-/** A stored record as an answer: the three fields, nothing else. */
+/**
+ * An answer's headers with the map and every value list copied, on the way
+ * into a store and on the way out of one. The pipeline applies the CALL's
+ * headers into the answer's own map as the call ends, so a custom store that
+ * kept the object it was given, or handed back the one it keeps (the
+ * interface asks for copies both ways, but nothing enforces it), would store
+ * one call's Set-Cookie and replay it to everyone.
+ */
+const copyAnswerHeaders = (headers) => Object.fromEntries(Object.entries(headers).map(([name, values]) => [name, [...values]]));
+/**
+ * A stored record as an answer: the three fields, nothing else, and the
+ * headers copied (see copyAnswerHeaders). The pipeline applies the replaying
+ * call's own headers into the answer's map, so a store that handed back the
+ * object it keeps would have this call's Set-Cookie written into its record
+ * and replayed to the next caller.
+ */
 const answerFromRecord = (record) => ({
     statusCode: record.statusCode,
-    headers: record.headers,
+    headers: copyAnswerHeaders(record.headers),
     body: record.body,
 });
 /**
- * A replay window a store can act on, checked where the rate limiter checks
- * its own windows. NaN was the one that mattered: it survives every
+ * A replay window a store can act on. NaN matters most: it survives every
  * comparison an expiry test makes, so an in-memory record with a NaN expiry
- * outlives every sweep, while DynamoDB rejects the same number outright. Zero
- * is rejected too, because a record that expires the instant it is written
- * silently turns replay off for the API that asked for it.
+ * outlives every sweep, while DynamoDB rejects the number outright. Zero is
+ * refused too, since a record that expires as it is written silently turns
+ * replay off for the API that asked for it.
  */
 const assertReplayTtl = (subject, ttlSeconds) => {
     if (ttlSeconds === undefined)
         return;
-    // The shared positive-integer check, with the subject naming the option;
-    // the wording "a replay window is a positive whole number of seconds"
-    // lived here alone and said the same thing in different words.
     assertPositiveInteger(ttlSeconds, `${subject} (a replay window in whole seconds)`);
 };
-/** A per-API replay window, falling back to the configured default. Written once: the two windows resolve the same way. */
+/** A per-API replay window, falling back to the configured default. */
 const resolveWindowSeconds = (config, field, fallback) => (typeof config === "object" ? config[field] : undefined) ?? fallback;
 /**
- * Headers the store may keep: the map and every value list copied, so what
- * the engine hands complete() cannot be rewritten afterwards.
- *
- * The pipeline applies the CALL's headers onto the answer on the way out,
- * into the very object handed here. A store that keeps the reference it was
- * given (the interface asks for a copy, and the shipped stores make one, but
- * a custom store is under no compiler's supervision) would have this call's
- * Set-Cookie become part of the stored record and replay to everyone.
+ * Whether a handler's answer is stored for replays. A 5xx is not: the
+ * operation may not have happened, and a retry should try it. Nor is a
+ * Set-Cookie (replaying another request's session cookies would be wrong),
+ * or a binary body.
  */
-const copyAnswerHeaders = (headers) => Object.fromEntries(Object.entries(headers).map(([name, values]) => [name, [...values]]));
+const isReplayableAnswer = (answer) => answer.statusCode < 500
+    && !answer.isBodyBase64
+    && getAnswerHeader(answer.headers, "Set-Cookie") === undefined;
+/**
+ * The refusal for a key that already belongs to a different request. Without
+ * it the second request would get the first one's stored answer: a corrected
+ * order (qty 2 after a refused qty 10) would get the stale refusal for a day,
+ * and an edited retry after a timeout (qty 4 after a processed qty 3) would
+ * get the first order's success though only the first was placed.
+ */
+const keyReusedRefusal = (apiName) => new LambderApiRefusal(`Idempotency key reused for a different request to "${apiName}".`, {
+    statusCode: 409,
+    errorMessage: {
+        type: "error",
+        code: LAMBDER_REFUSAL_CODES.idempotencyKeyReused,
+        content: "This request key was already used for a different request. Start the operation again.",
+    },
+});
+/**
+ * A request's fingerprint: what makes two requests under one key the same
+ * request. The payload as it was posted, as canonical JSON so key order does
+ * not matter, digested so a record keeps 64 characters rather than the
+ * payload. Guard inputs stay out: a captcha or proof token is single use, so
+ * a genuine retry carries a new one, and a fingerprint over it would refuse
+ * that retry as another request. A runtime without
+ * WebCrypto (the mock on a page served over plain http, a phone on the LAN)
+ * keeps the canonical JSON itself: a fingerprint is only compared with ones
+ * the same runtime took, so its form does not matter, only that one payload
+ * always gives the same one. Either form is non-empty (canonical JSON is at
+ * least `null`), which is what lets a store report the empty string for a
+ * record it cannot tie to any request.
+ */
+const requestFingerprintOf = async (payload) => {
+    let canonical;
+    try {
+        canonical = canonicalJson(payload ?? null);
+    }
+    catch {
+        // Sorting the keys recurses once per nesting level, so a payload
+        // nested deep enough to exhaust the stack is refused as the caller's
+        // error rather than answered as a crash: nothing an app posts nests
+        // that deep, and the schema would refuse it a step later anyway.
+        const content = "Invalid request payload: nested too deep to fingerprint.";
+        throw new LambderApiRefusal(content, {
+            statusCode: 400,
+            errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidRequestPayload, content },
+        });
+    }
+    try {
+        return await sha256HexOf(canonical);
+    }
+    catch {
+        return canonical;
+    }
+};
 /**
  * A store failure the engine decided to ignore, said out loud. Failing open
- * is the right default (a store outage should not take the app down with it),
- * but it is also indistinguishable from working: the failure class includes
- * permanent ones (a missing table, a missing IAM action, an SDK that would
- * not install), and an app can run for months executing every retry twice
- * with nothing in its logs. The scope key never appears, since it carries the
- * caller's identity and their posted key.
+ * is the right default, but silently it looks exactly like working: permanent
+ * failures (a missing table, a missing IAM action, an SDK that would not
+ * install) could have an app execute every retry twice for months with
+ * nothing in its logs. The scope key is left out, since it carries the
+ * caller's identity and posted key.
  */
 const reportFailOpen = (apiName, attempted, err) => {
     console.error(`Lambder idempotency: "${apiName}" could not ${attempted}; the request is being executed as if it carried no idempotency key. ` +
@@ -73,24 +135,20 @@ const reportFailOpen = (apiName, attempted, err) => {
 /**
  * Runtime side of the idempotency subsystem: claims a per-operation scope
  * around handler execution, replays stored answers, and settles claims.
- * Composed into LambderApiPolicyEngine. Works on plain answers, so it runs
+ * Held by LambderApiPipeline. Works on plain answers, so it runs
  * unchanged under the server and the mock runtime.
  */
 export class LambderApiIdempotencyEngine {
+    /** Stamped on the crash answer the engine records for an answer that broke its output schema. */
+    apiVersion;
     store = null;
     defaultTtlSeconds = 24 * 3600;
     defaultPendingTtlSeconds = DEFAULT_IDEMPOTENCY_PENDING_TTL_SECONDS;
     failOpen = true;
     callerIdentity = undefined;
-    /**
-     * The scope this call resolved to, keyed by its context, which is the one
-     * object per call the engine is handed. A keyed request asks for it
-     * twice, at the replay lookup and at the claim, and callerIdentity is app
-     * code that may verify a token or read a store: running it twice per
-     * request is a cost the app never asked for, and one it cannot see.
-     * Entries go when the call's context does.
-     */
-    scopeByCall = new WeakMap();
+    constructor(apiVersion) {
+        this.apiVersion = apiVersion;
+    }
     configure(config) {
         if (this.store)
             throw new Error("Lambder: idempotency was already configured.");
@@ -102,6 +160,17 @@ export class LambderApiIdempotencyEngine {
         this.failOpen = config.failOpen ?? true;
         this.callerIdentity = config.callerIdentity;
     }
+    /**
+     * Puts the engine over another store, for `lambder/testing`; the replay
+     * TTLs, failOpen and callerIdentity stay as configured. False when
+     * idempotency was never configured.
+     */
+    [LAMBDER_BACKEND_SWAP](store) {
+        if (!this.store)
+            return false;
+        this.store = store;
+        return true;
+    }
     /** Startup validation of one API registration's idempotency option. */
     assertRegistration(apiName, config) {
         if (typeof config !== "object")
@@ -130,61 +199,69 @@ export class LambderApiIdempotencyEngine {
         return rawKey;
     }
     /**
-     * The record's scope. Session APIs scope per session, so even a leaked
-     * key cannot cross users. Public APIs scope by the key alone unless the
-     * app supplies callerIdentity, because the key is required to be long
-     * (and documented to be random), and identity proxies like the client IP
-     * are deliberately NOT part of the scope: the retry idempotency exists
-     * for (a timeout followed by a network change) frequently arrives from a
-     * different IP. An app whose public APIs are authorized by a guard should
-     * give callerIdentity, since the replay is served before guards run.
+     * The record's scope. Session APIs scope per user (the sessionKey, which
+     * every session of one user shares), so even a leaked key cannot cross
+     * users. Public APIs scope by the key alone (it must be
+     * long and is documented to be random) unless the app supplies
+     * callerIdentity. The client IP is deliberately NOT part of the scope:
+     * the retry idempotency exists for (a timeout, then a network change)
+     * often arrives from a different IP. Apps whose public APIs are
+     * authorized by a guard should give callerIdentity, since the replay is
+     * served before guards run.
      *
-     * Fields are escaped and joined through joinKeyFields, so no two distinct
-     * scopes can produce one string.
+     * joinKeyFields escapes the fields, so no two distinct scopes collide.
+     * The identity field is the caller's (a device token in the docs' own
+     * example), so it is bounded first (boundKeyField): an over-long one
+     * would push the scope past a store's key limit, and the store's refusal
+     * is a throw that failOpen turns into no idempotency for that caller.
      */
     async scopeOf(apiName, ctx, request, key) {
-        const cached = this.scopeByCall.get(ctx);
-        if (cached)
-            return await cached;
-        const computed = this.computeScope(apiName, ctx, request, key);
-        this.scopeByCall.set(ctx, computed);
-        return await computed;
-    }
-    async computeScope(apiName, ctx, request, key) {
         const sessionKey = ctx.session?.sessionKey;
         if (sessionKey)
-            return joinKeyFields(`s:${sessionKey}`, apiName, key);
+            return joinKeyFields(await boundKeyField("s", sessionKey), apiName, key);
         // No session to scope by. The app may still say who this is, through
         // callerIdentity; without one the key alone is the scope, which is
         // what makes it a bearer token for its own answer.
         const identity = this.callerIdentity ? await this.callerIdentity(ctx, request) : null;
         return identity
-            ? joinKeyFields(`i:${identity}`, apiName, key)
+            ? joinKeyFields(await boundKeyField("i", identity), apiName, key)
             : joinKeyFields("k", apiName, key);
     }
     /**
-     * Replay fast path, run before the remaining rate limits and before
-     * guards: a completed record answers with its stored answer, so a
-     * legitimate retry neither burns rate-limit quota nor re-runs guards (the
-     * original already passed them, and no handler executes). The `per: "ip"`
-     * limits are the exception and are checked ahead of this, since the store
-     * read a replay costs is one of the things they exist to bound. Misses
-     * fall through to the normal pipeline; store errors follow the failOpen
-     * setting.
+     * The call's key worked out, once per call: its scope and its request's
+     * fingerprint, for findReplay and withIdempotency. Null for a call that
+     * sends no key, or when idempotency is not configured; a malformed key
+     * refuses with a 400. Taken at the replay lookup, before input validation
+     * replaces the payload with its parsed form, so the fingerprint is of the
+     * request as it was posted, and callerIdentity (app code that may verify
+     * a token or read a store) runs once.
      */
-    async findReplay(apiName, request, ctx, trace) {
-        const store = this.store;
-        if (!store)
+    async resolveKeyedCall(apiName, request, ctx) {
+        if (!this.store)
             return null;
         const key = this.readKey(request);
         if (key === null)
             return null;
+        return {
+            scopeKey: await this.scopeOf(apiName, ctx, request, key),
+            fingerprint: await requestFingerprintOf(request.payload),
+        };
+    }
+    /**
+     * Replay fast path, run before guards and all rate limits except
+     * `per: "ip"`: a completed record returns its stored answer, so a
+     * legitimate retry neither burns quota nor re-runs guards (the original
+     * passed them, and no handler executes). The IP limits run first because
+     * the store read a replay costs is one of the things they bound. Misses
+     * fall through to the normal pipeline; store errors follow failOpen.
+     */
+    async findReplay(apiName, call, trace) {
+        const store = this.store;
+        if (!store)
+            return null;
+        let done;
         try {
-            const done = await store.peek(await this.scopeOf(apiName, ctx, request, key));
-            if (!done)
-                return null;
-            trace.replayed = true;
-            return answerFromRecord(done);
+            done = await store.peek(call.scopeKey);
         }
         catch (err) {
             if (!this.failOpen)
@@ -192,36 +269,36 @@ export class LambderApiIdempotencyEngine {
             reportFailOpen(apiName, "look its replay record up", err);
             return null;
         }
+        if (!done)
+            return null;
+        if (done.fingerprint !== call.fingerprint)
+            throw keyReusedRefusal(apiName);
+        trace.replayed = true;
+        return answerFromRecord(done);
     }
     /**
-     * Idempotency wrapper around validation-passed handler execution. Without
-     * a client idempotencyKey the handler just runs; with one, the scope
-     * (identity + api + key) is claimed atomically: duplicates of an
-     * in-flight original refuse with 409, replays of a completed one return
-     * the stored answer verbatim, and a crashed original releases its claim
-     * so a retry actually retries.
+     * Idempotency wrapper around validation-passed handler execution, for a
+     * call resolveKeyedCall found a key on (a keyless call runs its handler
+     * without one): the scope (identity + api + key) is claimed atomically: duplicates of an in-flight original
+     * refuse with 409, replays of a completed one return the stored answer
+     * verbatim, and a crashed original releases its claim so a retry retries.
      *
-     * `exec` must hand back the handler's own answer, the headers the handler
-     * itself wrote included: the pipeline applies those before returning here,
-     * so a Set-Cookie the handler set is visible to the caching rule below.
+     * `exec` returns the handler's own answer with the headers the handler
+     * wrote, so a Set-Cookie it set is visible to the caching rule below.
      * Headers written EARLIER in the call (a session read evicting a stale
-     * cookie) are deliberately not on it: they are the call's, they reach the
-     * client either way, and charging them to this answer would make an
-     * idempotent operation silently stop being idempotent.
+     * cookie) are deliberately left off: they reach the client either way,
+     * and charging them to this answer would make it uncacheable, silently
+     * ending the operation's idempotency.
      */
-    async withIdempotency(apiName, request, ctx, config, trace, exec) {
+    async withIdempotency(apiName, { scopeKey, fingerprint }, config, trace, exec) {
         const store = this.store;
         if (!store)
             return await exec();
-        const rawKey = this.readKey(request);
-        if (rawKey === null)
-            return await exec();
         const ttlSeconds = resolveWindowSeconds(config, "ttlSeconds", this.defaultTtlSeconds);
         const pendingTtlSeconds = resolveWindowSeconds(config, "pendingTtlSeconds", this.defaultPendingTtlSeconds);
-        const scopeKey = await this.scopeOf(apiName, ctx, request, rawKey);
         let begun;
         try {
-            begun = await store.begin(scopeKey, { pendingTtlSeconds });
+            begun = await store.begin(scopeKey, { pendingTtlSeconds, fingerprint });
         }
         catch (err) {
             if (!this.failOpen)
@@ -229,6 +306,8 @@ export class LambderApiIdempotencyEngine {
             reportFailOpen(apiName, "claim its scope", err);
             return await exec();
         }
+        if (begun.state !== "new" && begun.fingerprint !== fingerprint)
+            throw keyReusedRefusal(apiName);
         if (begun.state === "pending") {
             throw new LambderApiRefusal(`Duplicate request for "${apiName}": the original is still processing.`, {
                 statusCode: 409,
@@ -236,43 +315,34 @@ export class LambderApiIdempotencyEngine {
             });
         }
         // The other replay path: the original settled between this request's
-        // peek and its claim, which is the race the "done" answer exists for.
-        // No handler runs here either, so it is a replay like any other.
+        // peek and its claim. No handler runs, so it is a replay like any
+        // other.
         if (begun.state === "done") {
             trace.replayed = true;
             return answerFromRecord(begun);
         }
         const ownerToken = begun.ownerToken;
         // Store the answer for replays when it qualifies, release the claim
-        // otherwise. A Set-Cookie makes an answer uncacheable (replaying
-        // another request's cookies, e.g. session tokens, would be wrong), and
-        // so does a binary body.
+        // otherwise.
         //
-        // Settling happens after the handler has already run, so a store
-        // failure here can no longer prevent anything: the work is done and
-        // the answer is owed to the caller. failOpen governs the decision
-        // BEFORE execution, at begin(), where refusing still means refusing to
-        // act. Applying it here would turn a completed operation into a 500
-        // and hand the retry a released claim, which is exactly the double
-        // execution idempotency exists to prevent, so a settle failure is
-        // reported and swallowed.
-        const settleClaim = async (answer) => {
-            const cacheable = answer.statusCode < 500
-                && !answer.isBodyBase64
-                && getAnswerHeader(answer.headers, "Set-Cookie") === undefined;
+        // A settle failure is reported and swallowed, not subject to
+        // failOpen: the work is done and the answer is owed to the caller.
+        // failOpen governs begin(), where refusing still means not acting.
+        // Here it would turn a completed operation into a 500 and hand the
+        // retry a released claim, which is the double execution idempotency
+        // exists to prevent.
+        const settleClaim = async (answer, replayable) => {
             try {
-                if (cacheable) {
-                    // The store owns the size decision: bodies may be compressed
-                    // there, and only ones exceeding its budget even compressed
-                    // come back as "too-large".
+                if (replayable) {
+                    // The store owns the size decision: it may compress bodies,
+                    // and answers "too-large" only when even that exceeds its
+                    // budget.
                     const completion = await store.complete(scopeKey, ownerToken, {
                         statusCode: answer.statusCode,
-                        // Copied, not handed over: the pipeline is about to
-                        // apply this call's own headers into answer.headers,
-                        // and a store that kept the reference would have them
-                        // in the record.
+                        // Copied: see copyAnswerHeaders.
                         headers: copyAnswerHeaders(answer.headers),
                         body: answer.body,
+                        fingerprint,
                         ttlSeconds,
                     });
                     if (completion !== "too-large")
@@ -283,41 +353,46 @@ export class LambderApiIdempotencyEngine {
                 await store.abandon(scopeKey, ownerToken);
             }
             catch (storeErr) {
-                // Two cases, one release. A complete() that never landed must
-                // not leave the pending claim dangling: it would 409 the
-                // caller's genuine retries until the pending TTL runs out. A
-                // complete() whose write DID land and then timed out is
-                // released too, so the record stops replaying and a retry
-                // re-executes rather than replaying. That is the safe
-                // direction of the two: the work has already been done once
-                // and its answer is with the caller, so a retry that runs
-                // again costs an execution, while a claim nobody can clear is
-                // a caller who cannot get through at all.
+                // The failed call may have landed anyway (a complete() whose
+                // answer was lost), and abandon() releases only a claim still
+                // pending, so one more release settles every case. A
+                // complete() that never landed frees the scope, where the
+                // pending claim would 409 genuine retries until
+                // pendingTtlSeconds ran out; one that landed keeps its record,
+                // and the retry replays it rather than running the operation
+                // a second time.
                 try {
                     await store.abandon(scopeKey, ownerToken);
                 }
                 catch { /* claim expires on its own */ }
-                console.warn(`Lambder idempotency: "${apiName}" ran and answered, but its record could not be stored. ` +
-                    "The caller keeps this answer; a retry under the same key will execute again.", storeErr);
+                console.warn(`Lambder idempotency: "${apiName}" ran and answered, but storing its record failed. ` +
+                    "The caller keeps this answer; a retry under the same key replays it if the write landed after all, and executes again if it did not.", storeErr);
             }
         };
         try {
             const answer = await exec();
-            await settleClaim(answer);
+            await settleClaim(answer, isReplayableAnswer(answer));
             return answer;
         }
         catch (err) {
-            // A real crash, or a thrown refusal (LambderApiRefusal, refuse()),
-            // releases the claim so a retry actually retries. This is the
-            // deliberate rule: ANSWERS are stored and replayed, refusals
-            // delivered as returned envelopes included; EXCEPTIONS are not, so
-            // a thrown refusal re-executes on retry and the handler decides
-            // afresh. Pick the idiom accordingly. (On the server, a response
-            // delivered by throwing, res.die.api(), is an answer: the adapter
-            // catches it before it reaches here.)
-            // Whatever happens to the claim, the handler's own failure is the
-            // one worth reporting: replacing it with a cleanup error would
-            // hide the reason the call failed.
+            // The handler ran to its answer, and the answer broke its output
+            // schema: whatever the operation wrote or charged is done, so a
+            // released claim would run it again on every retry. The
+            // framework's crash answer is recorded as the key's answer
+            // instead, and a retry is told the same thing.
+            if (err instanceof LambderApiOutputValidationError) {
+                await settleClaim(crashAnswer(this.apiVersion), true);
+                throw err;
+            }
+            // A crash or a thrown refusal (LambderApiRefusal, refuse())
+            // releases the claim so a retry retries. The rule is deliberate:
+            // ANSWERS are stored and replayed, returned refusal envelopes
+            // included; EXCEPTIONS are not, so a thrown refusal re-executes
+            // on retry and the handler decides afresh. (On the server,
+            // res.die.api() is an answer: the adapter catches it before it
+            // reaches here.) The handler's own error is what gets rethrown,
+            // since a cleanup error in its place would hide why the call
+            // failed.
             try {
                 await store.abandon(scopeKey, ownerToken);
             }

package/dist/api/LambderApiOutputValidationError.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/**
+ * A handler answered a payload its API's output schema could not turn into
+ * the declared shape, so the payload was not sent and the call is answered
+ * as a crash. Either the schema rejected the payload, or the parse threw: an
+ * async refinement or transform (the output is parsed synchronously, so an
+ * output schema cannot be async), or a transform that threw. The output
+ * side's counterpart of LambderApiValidationRefusal, with the API it happened
+ * in, for a crash reporter.
+ *
+ * Its own class because it is a crash after the fact: the handler ran to
+ * its answer, whatever it wrote or charged along the way included. The
+ * idempotency engine reads it that way and keeps the key's record, so a
+ * retry is told the same thing instead of running the operation again.
+ */
+export declare class LambderApiOutputValidationError extends Error {
+    readonly apiName: string;
+    /**
+     * The schema's issues when it rejected the payload. Null when the parse
+     * threw instead; what it threw is the `cause`.
+     */
+    readonly zodError: z.ZodError | null;
+    /**
+     * `failure` is how the parse ended: `{ zodError }` when the schema
+     * rejected the payload, `{ thrown }` when parsing it threw.
+     */
+    constructor(apiName: string, failure: {
+        zodError: z.ZodError;
+    } | {
+        thrown: unknown;
+    });
+}

package/dist/api/LambderApiOutputValidationError.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * A handler answered a payload its API's output schema could not turn into
+ * the declared shape, so the payload was not sent and the call is answered
+ * as a crash. Either the schema rejected the payload, or the parse threw: an
+ * async refinement or transform (the output is parsed synchronously, so an
+ * output schema cannot be async), or a transform that threw. The output
+ * side's counterpart of LambderApiValidationRefusal, with the API it happened
+ * in, for a crash reporter.
+ *
+ * Its own class because it is a crash after the fact: the handler ran to
+ * its answer, whatever it wrote or charged along the way included. The
+ * idempotency engine reads it that way and keeps the key's record, so a
+ * retry is told the same thing instead of running the operation again.
+ */
+export class LambderApiOutputValidationError extends Error {
+    apiName;
+    /**
+     * The schema's issues when it rejected the payload. Null when the parse
+     * threw instead; what it threw is the `cause`.
+     */
+    zodError;
+    /**
+     * `failure` is how the parse ended: `{ zodError }` when the schema
+     * rejected the payload, `{ thrown }` when parsing it threw.
+     */
+    constructor(apiName, failure) {
+        let message;
+        if ("zodError" in failure) {
+            // Paths and messages only: an issue's message names the expected
+            // type, and the values themselves stay out of a crash report.
+            const issues = failure.zodError.issues.slice(0, 3).map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+            message = `Lambder: API "${apiName}" answered a payload its output schema does not accept, so it was not sent. ${issues}`;
+        }
+        else if (failure.thrown instanceof z.core.$ZodAsyncError) {
+            message = `Lambder: API "${apiName}" has an async refinement or transform in its output schema, and an output schema cannot be async: `
+                + "a payload is parsed synchronously on its way out. The payload was not sent.";
+        }
+        else {
+            // The thrown error's own message stays in the cause: it is the
+            // app's text and may carry the value the transform was given.
+            message = `Lambder: API "${apiName}" answered a payload its output schema threw on while parsing it (a transform that threw, `
+                + "or an async step a synchronous parse cannot run), so it was not sent. What the schema threw is the cause.";
+        }
+        super(message, { cause: "zodError" in failure ? failure.zodError : failure.thrown });
+        this.name = "LambderApiOutputValidationError";
+        this.apiName = apiName;
+        this.zodError = "zodError" in failure ? failure.zodError : null;
+    }
+}