lambder 14.0.1 → 14.1.1

package/CHANGELOG.md

@@ -9,6 +9,49 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [14.1.1] - 2026-09-30
+
+A minor: a refusal code can declare the `sessionExpired` flag, and
+`checkApiRefusals` holds every refusal a handler can reach to the codes its
+endpoint may send, which is what an app that requires codes needs to know
+before a call finds out.
+
+### Added
+
+- **A code declared `sessionExpired: true`** leaves with the envelope's
+  `sessionExpired` flag, as one declared `notAuthorized: true` leaves with
+  that one: for a session the pipeline found good that the handler then
+  finds gone (its login deleted, say). With `requireCodes`, a refusal that
+  meant "your session is over" had no way to carry both a code and the
+  flag. The declaration owns the flag, so a raise site that sets it on a
+  declared code is still a crash; a code may set one flag at most, since a
+  caller routes a refusal one way; and the flag counts in an endpoint's
+  signature only where a code sets it, so every existing digest stays as it
+  was. The mock sends it the same way.
+- **`checkApiRefusals`** (`lambder/build`): reads a project through the
+  TypeScript compiler and, for every handler Lambder hands a typed `refuse`
+  (an endpoint's, a guard's, a mock entry's), follows it into every function
+  it can reach (a call, a method of what it constructs, a function handed
+  along, a module loaded with `import()`, a handler the app wraps or holds
+  in an object) and holds each code raised there to the codes its
+  `ctx.refuse` takes. It names a code a handler may not send, a declared
+  code nothing reaches, a refusal with no code where codes are required, a
+  refusal whose code is any string, and a handler whose function it cannot
+  find; a project in which it finds no handler to check fails rather than
+  passes. Before it, a shared helper's code for an endpoint that did not
+  declare it compiled, and crashed only when a call reached it.
+
+### Changed
+
+- **A refusal that leaves an API call with the `sessionExpired` flag ends
+  the session the call held**, whether a declared code or the raise site set
+  the flag, and whether a handler, a guard or a hook threw it. The caller
+  stops sending a session it is told is over, and before this nothing
+  deleted it on the server until it expired. The record is deleted and the
+  cookies are left alone, as when the session read finds no session, since a
+  cookie deletion would also delete a session another response has just
+  set.
+
 ## [14.0.1] - 2026-09-30
 
 A major: `writeApiGuardParams` writes one export per API in place of one

package/dist/api/LambderApiPipeline.d.ts

@@ -5,6 +5,8 @@ import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import type { LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
+import { type LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderEndpointRefusals } from "./LambderApiRefusals.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
 import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitChargeResult, type LambderRateLimitChargeSubject } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
@@ -107,8 +109,12 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * validation error through onInvalidInput, any other refusal as the refusal
  * envelope once checked against the endpoint's declared codes
  * (checkedRefusal), and a session ended while the handler held it
- * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
- * crash means (a global error handler, a mock event).
+ * (LambderSessionNotFoundError) as sessionExpired. A refusal that leaves
+ * with the sessionExpired flag ends the session the call held
+ * (answerRefusal), so the server keeps no session its caller has been told
+ * is over. Anything else
+ * propagates, because only the adapter knows what a crash means (a global
+ * error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
  * definition is the one thing the adapters legitimately do differently (an
@@ -161,6 +167,20 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(ctx?: TCtx): LambderApiAnswer;
+    /**
+     * A thrown refusal as the answer to a call of `apiName`: checked against
+     * the codes the endpoint declares (checkedRefusal, which throws for one it
+     * may not send), then rendered. run() answers a step's, a guard's or a
+     * handler's refusal with it, and the server a hook's.
+     *
+     * A refusal telling the caller its session is over (a declared code's
+     * flag, or a raise site's own) ends the session the call held: the caller
+     * stops sending it, and nothing else would delete it before it expires.
+     * The record is deleted and the cookies left alone, which is what the
+     * pipeline's own sessionExpired leaves behind (endWithNoSession in the
+     * session controller says why the cookies stay).
+     */
+    answerRefusal(apiName: string, refusals: LambderEndpointRefusals | undefined, thrown: LambderApiRefusal, ctx: TCtx): Promise<LambderApiAnswer>;
     /**
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that

package/dist/api/LambderApiPipeline.js

@@ -37,8 +37,12 @@ const usesIdempotency = (definition) => definition.idempotency !== undefined &&
  * validation error through onInvalidInput, any other refusal as the refusal
  * envelope once checked against the endpoint's declared codes
  * (checkedRefusal), and a session ended while the handler held it
- * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
- * crash means (a global error handler, a mock event).
+ * (LambderSessionNotFoundError) as sessionExpired. A refusal that leaves
+ * with the sessionExpired flag ends the session the call held
+ * (answerRefusal), so the server keeps no session its caller has been told
+ * is over. Anything else
+ * propagates, because only the adapter knows what a crash means (a global
+ * error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
  * definition is the one thing the adapters legitimately do differently (an
@@ -185,6 +189,27 @@ export class LambderApiPipeline {
         ctx?.responseHeaders.applyInto(answer.headers);
         return answer;
     }
+    /**
+     * A thrown refusal as the answer to a call of `apiName`: checked against
+     * the codes the endpoint declares (checkedRefusal, which throws for one it
+     * may not send), then rendered. run() answers a step's, a guard's or a
+     * handler's refusal with it, and the server a hook's.
+     *
+     * A refusal telling the caller its session is over (a declared code's
+     * flag, or a raise site's own) ends the session the call held: the caller
+     * stops sending it, and nothing else would delete it before it expires.
+     * The record is deleted and the cookies left alone, which is what the
+     * pipeline's own sessionExpired leaves behind (endWithNoSession in the
+     * session controller says why the cookies stay).
+     */
+    async answerRefusal(apiName, refusals, thrown, ctx) {
+        const checked = checkedRefusal(apiName, refusals, thrown);
+        if (checked.sessionExpired && ctx.session && this.sessions) {
+            await this.sessions.manager.deleteSession(ctx.session);
+            ctx.session = null;
+        }
+        return refusalAnswer(checked, this.apiVersion, ctx.logList);
+    }
     /**
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that
@@ -250,7 +275,7 @@ export class LambderApiPipeline {
                 // idempotency engine has already released the claim, as it
                 // does for every thrown refusal: a retry runs the handler
                 // again and decides afresh.
-                answer = refusalAnswer(checkedRefusal(definition.name, definition.refusals, err), this.apiVersion, ctx.logList);
+                answer = await this.answerRefusal(definition.name, definition.refusals, err, ctx);
             }
             else if (err instanceof LambderSessionNotFoundError) {
                 // No usable session: it ended while the handler held it (a

package/dist/api/LambderApiRefusals.d.ts

@@ -8,7 +8,7 @@ import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderN
  * One code of an app's refusal vocabulary: the schema of the data it carries,
  * when it carries data, and how every refusal with the code leaves the
  * server. A code's data is an object or an array, as an API's output is. The
- * status and the flag are declared once here rather than at each raise site,
+ * status and the flags are declared once here rather than at each raise site,
  * so a code always reaches a caller the same way.
  */
 export type LambderRefusalDeclaration = {
@@ -18,6 +18,14 @@ export type LambderRefusalDeclaration = {
     status?: LambderRefusalStatusCode;
     /** Whether every refusal with this code sets the envelope's notAuthorized flag, which a caller routes to its notAuthorizedHandler. */
     notAuthorized?: true;
+    /**
+     * Whether every refusal with this code sets the envelope's sessionExpired
+     * flag, which a caller answers by clearing its session and routing to its
+     * sessionExpiredHandler: for a session the handler found no longer good
+     * (its login deleted, say), which the pipeline's own check could not know.
+     * The server ends the session the call held as the refusal leaves.
+     */
+    sessionExpired?: true;
 };
 /**
  * One code as its endpoint may send it: the status and flag its declaration
@@ -30,6 +38,8 @@ export type LambderApiAllowedRefusal = {
     status?: LambderRefusalStatusCode;
     /** Present when every refusal with the code sets the envelope's notAuthorized flag. */
     notAuthorized?: true;
+    /** Present when every refusal with the code sets the envelope's sessionExpired flag. */
+    sessionExpired?: true;
 } & ({
     data: false;
 } | {
@@ -61,7 +71,7 @@ type LambderRefusalDataRefusal = {
 };
 /**
  * The vocabulary as declareRefusals() checks it, code by code: no `lambder/`
- * prefix, no key beside data, status and notAuthorized (a `dat:` would leave
+ * prefix, no key beside data, status and the two flags (a `dat:` would leave
  * a code that carries data declared as one that does not), and data that is
  * an object or an array.
  */
@@ -154,8 +164,8 @@ export declare class LambderApiRefusalValidationError extends Error {
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
  *   provided it carries no data. Where the app requires codes, an uncoded
  *   refusal is refused too; a framework code still passes.
- * - A declared code leaves with its declaration's status and notAuthorized
- *   flag, and with data exactly when the code carries data, parsed through
+ * - A declared code leaves with its declaration's status and flags, and
+ *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults
  *   filled, transforms run. The parse is synchronous, so a data schema cannot
  *   be async.
@@ -187,8 +197,8 @@ export declare const toRefusalCodes: (value: string | readonly string[] | undefi
  * The vocabulary, checked: every code a non-empty string outside the
  * framework's `lambder/` prefix, every declaration an object whose `data`,
  * when present, is a zod schema, whose `status`, when present, is one a
- * reader files as a refusal, and whose `notAuthorized`, when present, is
- * true. A Map, so a code named for something Object.prototype carries
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are true. A Map, so a code named for something Object.prototype carries
  * ("toString") is still an ordinary code.
  */
 export declare const readRefusalVocabulary: (refusals: Record<string, LambderRefusalDeclaration> | undefined) => Map<string, LambderRefusalDeclaration> | null;

package/dist/api/LambderApiRefusals.js

@@ -18,6 +18,7 @@ export const allowedRefusalOf = (declaration) => {
     const leaves = {
         ...(declaration.status !== undefined ? { status: declaration.status } : {}),
         ...(declaration.notAuthorized ? { notAuthorized: true } : {}),
+        ...(declaration.sessionExpired ? { sessionExpired: true } : {}),
     };
     return declaration.data === undefined ? { ...leaves, data: false } : { ...leaves, data: true, schema: declaration.data };
 };
@@ -63,7 +64,7 @@ export class LambderApiRefusalValidationError extends Error {
         }
         else if ("ownStatusOrFlag" in violation) {
             message = `Lambder: API "${apiName}" refused with the declared code "${String(code)}" and a status or flag of its own, so the refusal was not sent. `
-                + "A declared code's status and notAuthorized flag are its declaration's: set them in the refusals vocabulary, and leave them off the refuse() call.";
+                + "A declared code's status and its notAuthorized and sessionExpired flags are its declaration's: set them in the refusals vocabulary, and leave them off the refuse() call.";
         }
         else if ("zodError" in violation) {
             // Paths and messages only, never the values: they may be the
@@ -95,8 +96,8 @@ export class LambderApiRefusalValidationError extends Error {
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
  *   provided it carries no data. Where the app requires codes, an uncoded
  *   refusal is refused too; a framework code still passes.
- * - A declared code leaves with its declaration's status and notAuthorized
- *   flag, and with data exactly when the code carries data, parsed through
+ * - A declared code leaves with its declaration's status and flags, and
+ *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults
  *   filled, transforms run. The parse is synchronous, so a data schema cannot
  *   be async.
@@ -145,11 +146,12 @@ export const checkedRefusal = (apiName, endpoint, thrown) => {
             throw new LambderApiRefusalValidationError(apiName, thrown, { notObject: describePayloadKind(parsed.data) });
         sent = parsed.data;
     }
-    // The declaration's status and flag, and the data as parsed: how every
+    // The declaration's status and flags, and the data as parsed: how every
     // refusal with this code leaves, wherever it was raised.
     return new LambderApiRefusal(thrown.message, {
         refusal: { ...thrown.refusal, ...(sent !== undefined ? { data: sent } : {}) },
         notAuthorized: declaration.notAuthorized,
+        sessionExpired: declaration.sessionExpired,
         statusCode: declaration.status,
         headers: thrown.headers,
         cause: thrown.cause,
@@ -195,8 +197,8 @@ export const toRefusalCodes = (value) => value === undefined ? [] : typeof value
  * The vocabulary, checked: every code a non-empty string outside the
  * framework's `lambder/` prefix, every declaration an object whose `data`,
  * when present, is a zod schema, whose `status`, when present, is one a
- * reader files as a refusal, and whose `notAuthorized`, when present, is
- * true. A Map, so a code named for something Object.prototype carries
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are true. A Map, so a code named for something Object.prototype carries
  * ("toString") is still an ordinary code.
  */
 export const readRefusalVocabulary = (refusals) => {
@@ -215,9 +217,9 @@ export const readRefusalVocabulary = (refusals) => {
         if (declaration === null || typeof declaration !== "object") {
             throw new Error(`Lambder: the refusal "${code}" is not declared as an object: write {} for a code with no data, or { data: schema }.`);
         }
-        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized");
+        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized" && key !== "sessionExpired");
         if (extra.length) {
-            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status and notAuthorized, which a refusal declaration does not take.`);
+            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status, notAuthorized and sessionExpired, which a refusal declaration does not take.`);
         }
         // Read for what it is used as rather than by class, so a schema from
         // a second copy of zod in the bundle still counts.
@@ -228,8 +230,13 @@ export const readRefusalVocabulary = (refusals) => {
         if (status !== undefined && (typeof status !== "number" || !Number.isInteger(status) || status < 200 || status >= 500 || status === 422)) {
             throw new Error(`Lambder: the refusal "${code}" declares the status ${String(status)}. A declared refusal leaves with a status from 200 to 499 other than 422: a reader files a 5xx as a server failure and a 422 as an input validation failure.`);
         }
-        if (declaration.notAuthorized !== undefined && declaration.notAuthorized !== true) {
-            throw new Error(`Lambder: the refusal "${code}" declares notAuthorized as ${String(declaration.notAuthorized)}; write true, or leave it off.`);
+        for (const flag of ["notAuthorized", "sessionExpired"]) {
+            if (declaration[flag] !== undefined && declaration[flag] !== true) {
+                throw new Error(`Lambder: the refusal "${code}" declares ${flag} as ${String(declaration[flag])}; write true, or leave it off.`);
+            }
+        }
+        if (declaration.notAuthorized && declaration.sessionExpired) {
+            throw new Error(`Lambder: the refusal "${code}" declares both notAuthorized and sessionExpired. A caller routes a refusal one way: a session that is gone is not also a session that is not allowed.`);
         }
     }
     return new Map(entries);

package/dist/api/LambderApiSignature.d.ts

@@ -18,17 +18,17 @@ export type LambderApiSignatureEntry = {
  * schema that guard validates (the guardInput the client sends separately,
  * or the apiInput slice of the payload), whether it demands an idempotency
  * key, and every refusal code it may send with its data's schema, its status
- * and its notAuthorized flag. Anything
- * else (rate limits, a guard's parameter, the handler) changes nothing for a
- * client and is left out, so changing it never forces a reload.
+ * and its flags. Anything else (rate limits, a guard's parameter, the
+ * handler) changes nothing for a client and is left out, so changing it
+ * never forces a reload.
  *
  * The refusal codes count in full: a client's refusal type lists exactly the
  * codes the endpoint declares, so one built before a code was added would be
  * handed a code its types say cannot arrive. Adding a code, or changing a
  * code's data, reloads that endpoint's clients. A code's data is received,
  * so it is digested in the output position, where an extensibleEnum's values
- * leave the digest. Its status and flag count too: a caller reads the one
- * and routes on the other.
+ * leave the digest. Its status and flags count too: a caller reads the one
+ * and routes on the others.
  *
  * Schemas are hashed as built, descriptions and titles included, so a client
  * built against a different one reloads once. The exception is an output

package/dist/api/LambderApiSignature.js

@@ -56,17 +56,17 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  * schema that guard validates (the guardInput the client sends separately,
  * or the apiInput slice of the payload), whether it demands an idempotency
  * key, and every refusal code it may send with its data's schema, its status
- * and its notAuthorized flag. Anything
- * else (rate limits, a guard's parameter, the handler) changes nothing for a
- * client and is left out, so changing it never forces a reload.
+ * and its flags. Anything else (rate limits, a guard's parameter, the
+ * handler) changes nothing for a client and is left out, so changing it
+ * never forces a reload.
  *
  * The refusal codes count in full: a client's refusal type lists exactly the
  * codes the endpoint declares, so one built before a code was added would be
  * handed a code its types say cannot arrive. Adding a code, or changing a
  * code's data, reloads that endpoint's clients. A code's data is received,
  * so it is digested in the output position, where an extensibleEnum's values
- * leave the digest. Its status and flag count too: a caller reads the one
- * and routes on the other.
+ * leave the digest. Its status and flags count too: a caller reads the one
+ * and routes on the others.
  *
  * Schemas are hashed as built, descriptions and titles included, so a client
  * built against a different one reloads once. The exception is an output
@@ -89,6 +89,8 @@ export const apiSignatureOf = async (definition, guards) => {
             data: jsonSchemaOf(declaration.data ? declaration.schema : undefined, "output"),
             status: declaration.status ?? 200,
             notAuthorized: declaration.notAuthorized === true,
+            // Written only when set, so a vocabulary with no such code digests as it did before the flag existed.
+            ...(declaration.sessionExpired ? { sessionExpired: true } : {}),
         }]);
     refusalShapes.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     const description = {

package/dist/build/checkApiRefusals.d.ts

@@ -0,0 +1,54 @@
+export type LambderApiRefusalCheckOptions = {
+    /** The tsconfig.json the project compiles under, whose options and path aliases resolve its imports. Relative to the working directory. */
+    tsconfig: string;
+    /** The files the program starts from, relative to the working directory; everything they import is read too. Default: the tsconfig's own files. */
+    files?: string[];
+    /** Whether a refusal with no code is a finding, as it is a crash in an app whose vocabulary requires codes (declareRefusals's requireCodes). Default: true. */
+    requireCodes?: boolean;
+};
+/** What one handler's check found. */
+export type LambderRefusalCheckFinding = {
+    /** The handler, as its registration names it: an endpoint's `group.action`, a mock entry's name, a guard's name. */
+    handler: string;
+    /** Where the handler is registered, as `file:line` relative to the working directory. */
+    at: string;
+    /**
+     * - `undeclared`: a code the handler can reach that it may not send.
+     * - `unused`: a code the handler's own `refusals` option names that nothing it reaches raises.
+     * - `uncoded`: a refusal with no code it can reach, where codes are required.
+     * - `unreadable`: a refusal it can reach whose code is not a string literal type.
+     * - `untraced`: a handler handed a typed refuse whose function cannot be
+     *   found (a parameter, a dependency's value), so nothing it reaches was
+     *   checked.
+     */
+    problem: "undeclared" | "unused" | "uncoded" | "unreadable" | "untraced";
+    /** The code, for `undeclared` and `unused`. */
+    code?: string;
+    /** Where the refusal is raised, as `file:line`, for `undeclared`, `uncoded` and `unreadable`. */
+    raisedAt?: string;
+};
+export type LambderApiRefusalCheckResult = {
+    /** False when the project could not be read, no handler in it could be checked, or any handler has a finding. */
+    ok: boolean;
+    /** How many handlers were checked. */
+    handlers: number;
+    findings: LambderRefusalCheckFinding[];
+    /** What happened, as lines to print: a summary, then one line per finding. */
+    lines: string[];
+};
+/**
+ * Checks every handler of a project against the codes it may send, and
+ * answers what it found.
+ *
+ * ```ts
+ * import { checkApiRefusals } from "lambder/build";
+ *
+ * const result = await checkApiRefusals({ tsconfig: "server/tsconfig.json" });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Run it where the app runs its other build checks, or from a test: it
+ * compiles the project, so it takes as long as a type check does.
+ */
+export declare const checkApiRefusals: (options: LambderApiRefusalCheckOptions) => Promise<LambderApiRefusalCheckResult>;

package/dist/build/checkApiRefusals.js

@@ -0,0 +1,415 @@
+import { dirname, relative, resolve, sep } from "path";
+import { fileURLToPath } from "url";
+import { loadTypeScriptCompiler } from "./loadTypeScriptCompiler.js";
+/** The registrations whose handler Lambder types a refuse for, by the name they are called under, and where each one's handler is. */
+const HANDLER_REGISTRATIONS = {
+    defineApi: "second",
+    guard: "optionsHandler",
+    lambderGuard: "optionsHandler",
+    api: "secondOrItsHandler",
+    override: "secondOrItsHandler",
+};
+/**
+ * Checks every handler of a project against the codes it may send, and
+ * answers what it found.
+ *
+ * ```ts
+ * import { checkApiRefusals } from "lambder/build";
+ *
+ * const result = await checkApiRefusals({ tsconfig: "server/tsconfig.json" });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Run it where the app runs its other build checks, or from a test: it
+ * compiles the project, so it takes as long as a type check does.
+ */
+export const checkApiRefusals = async (options) => {
+    const ts = await loadTypeScriptCompiler("checkApiRefusals reads the project");
+    const requireCodes = options.requireCodes ?? true;
+    const configPath = resolve(options.tsconfig);
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error)
+        return failed(`✗ ${options.tsconfig} could not be read: ${ts.flattenDiagnosticMessageText(read.error.messageText, " ")}`);
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath), undefined, configPath);
+    if (parsed.errors.length)
+        return failed(`✗ ${options.tsconfig} has errors: ${parsed.errors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, " ")).join("; ")}`);
+    const rootNames = options.files?.map((file) => resolve(file)) ?? parsed.fileNames;
+    const program = ts.createProgram({ rootNames, options: { ...parsed.options, noEmit: true, composite: false, incremental: false, declaration: false } });
+    const checker = program.getTypeChecker();
+    const lambderRoot = realPathOf(ts, resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."));
+    const ownFiles = new Map();
+    /** A file of the project itself: not a dependency's, not a declaration file, and not Lambder's own (its tests excepted, which are apps). */
+    const isOwnFile = (sourceFile) => {
+        const known = ownFiles.get(sourceFile.fileName);
+        if (known !== undefined)
+            return known;
+        const path = realPathOf(ts, sourceFile.fileName);
+        const own = !sourceFile.isDeclarationFile
+            && !path.split(sep).includes("node_modules")
+            && (!isInside(path, lambderRoot) || isInside(path, resolve(lambderRoot, "tests")));
+        ownFiles.set(sourceFile.fileName, own);
+        return own;
+    };
+    /**
+     * A declaration of Lambder's: in the declaration files of any installed
+     * copy (a workspace holds one per set of peer versions, and a package's
+     * imports resolve to its own), or in its sources when this runs over its
+     * own tests.
+     */
+    const isLambderDeclaration = (node) => {
+        if (!node)
+            return false;
+        const path = realPathOf(ts, node.getSourceFile().fileName);
+        const parts = path.split(sep);
+        if (parts.some((part, index) => part === "node_modules" && parts[index + 1] === "lambder"))
+            return true;
+        return isInside(path, lambderRoot) && !isInside(path, resolve(lambderRoot, "tests")) && !parts.slice(lambderRoot.split(sep).length).includes("node_modules");
+    };
+    const where = (node) => {
+        const sourceFile = node.getSourceFile();
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        return `${relative(process.cwd(), sourceFile.fileName)}:${line + 1}`;
+    };
+    // ── Raise sites ──────────────────────────────────────────────────────
+    /** The string literal values of a type, or null when it is not made of string literals alone. */
+    const literalsOf = (type) => {
+        const parts = type.isUnion() ? type.types : [type];
+        const values = [];
+        for (const part of parts) {
+            if (part.isStringLiteral())
+                values.push(part.value);
+            else
+                return null;
+        }
+        return values;
+    };
+    /** The code a refuse options argument names, read off its type. */
+    const codeOfOptions = (argument, property, at) => {
+        if (!argument)
+            return [{ at, uncoded: true }];
+        let optionsType = checker.getTypeAtLocation(argument);
+        if (property === "refusal") {
+            const refusal = checker.getPropertyOfType(optionsType, "refusal");
+            if (!refusal)
+                return [{ at, uncoded: true }];
+            optionsType = checker.getTypeOfSymbolAtLocation(refusal, argument);
+        }
+        const code = checker.getPropertyOfType(optionsType, "code");
+        if (!code)
+            return [{ at, uncoded: true }];
+        const codeType = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(code, argument));
+        if (codeType.flags & ts.TypeFlags.Never)
+            return [{ at, uncoded: true }];
+        const values = literalsOf(codeType);
+        if (values === null)
+            return [{ at, unreadable: true }];
+        return values.map((value) => ({ at, code: value }));
+    };
+    /**
+     * The refusal a call or construction raises, when it is one of Lambder's
+     * refuse functions or its refusal class's constructor. The constructor is
+     * told by the signature the call resolves to rather than by the name
+     * written, so it counts constructed as itself, as a class of the app's
+     * own that declares no constructor and inherits it, or as the super() of
+     * one that declares its own, which is then raised wherever that class is
+     * constructed.
+     */
+    const raiseSitesOf = (node) => {
+        const callee = node.expression;
+        const constructs = ts.isNewExpression(node) || callee.kind === ts.SyntaxKind.SuperKeyword;
+        if (!constructs) {
+            const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
+            if (name !== "refuse")
+                return [];
+        }
+        const declaration = checker.getResolvedSignature(node)?.declaration;
+        if (!isLambderDeclaration(declaration))
+            return [];
+        if (constructs && !(declaration && ts.isConstructorDeclaration(declaration) && declaration.parent.name?.text === "LambderApiRefusal"))
+            return [];
+        const args = node.arguments ?? ts.factory.createNodeArray();
+        return constructs ? codeOfOptions(args[1], "refusal", where(node)) : codeOfOptions(args[1], "code", where(node));
+    };
+    // ── The call graph ───────────────────────────────────────────────────
+    const unwrap = (expression) => {
+        let current = expression;
+        while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current)) {
+            current = current.expression;
+        }
+        return current;
+    };
+    const isFunctionWithBody = (node) => (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)
+        || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node)) && node.body !== undefined;
+    /** The functions a declaration stands for: itself, the function it is initialized to, or a class's constructor where it is constructed. */
+    const functionsOfDeclaration = (declaration, reference) => {
+        if (isFunctionWithBody(declaration))
+            return [declaration];
+        if ((ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration) || ts.isPropertyDeclaration(declaration)) && declaration.initializer) {
+            const initializer = unwrap(declaration.initializer);
+            return isFunctionWithBody(initializer) ? [initializer] : [];
+        }
+        if (ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration)) {
+            const constructed = ts.isNewExpression(reference.parent) && reference.parent.expression === reference;
+            return constructed ? declaration.members.filter((member) => ts.isConstructorDeclaration(member) && member.body !== undefined) : [];
+        }
+        return [];
+    };
+    /** The functions of the project an identifier refers to, followed through an import, a shorthand property or a destructured binding. */
+    const functionsReferredToBy = (reference) => {
+        let symbol = checker.getSymbolAtLocation(reference);
+        if (!symbol)
+            return [];
+        if (ts.isShorthandPropertyAssignment(reference.parent) && reference.parent.name === reference) {
+            symbol = checker.getShorthandAssignmentValueSymbol(reference.parent) ?? symbol;
+        }
+        if (symbol.flags & ts.SymbolFlags.Alias)
+            symbol = checker.getAliasedSymbol(symbol);
+        const found = [];
+        for (const declaration of symbol.declarations ?? []) {
+            if (!isOwnFile(declaration.getSourceFile()))
+                continue;
+            if (ts.isBindingElement(declaration)) {
+                // `const { stamp } = await import("./stamper.js")`: the binding names no
+                // function, and the type it is given does.
+                for (const signature of checker.getTypeOfSymbolAtLocation(symbol, reference).getCallSignatures()) {
+                    if (signature.declaration && isFunctionWithBody(signature.declaration) && isOwnFile(signature.declaration.getSourceFile()))
+                        found.push(signature.declaration);
+                }
+                continue;
+            }
+            found.push(...functionsOfDeclaration(declaration, reference));
+        }
+        return found;
+    };
+    const scanned = new Map();
+    /**
+     * A function's own raise sites and the functions it refers to, or an
+     * expression's (a handler written as a wrapper's call, say). A function
+     * written inside it is one it reaches, since it runs as part of it.
+     */
+    const scan = (root) => {
+        const known = scanned.get(root);
+        if (known)
+            return known;
+        const result = { raises: [], reaches: [] };
+        const visit = (node) => {
+            if (node !== root && isFunctionWithBody(node)) {
+                result.reaches.push(node);
+                return;
+            }
+            if (ts.isCallExpression(node) || ts.isNewExpression(node))
+                result.raises.push(...raiseSitesOf(node));
+            if (ts.isIdentifier(node))
+                result.reaches.push(...functionsReferredToBy(node));
+            ts.forEachChild(node, visit);
+        };
+        visit(root);
+        scanned.set(root, result);
+        return result;
+    };
+    /** Every raise site a handler can reach, through everything it refers to. */
+    const reachOf = (handler) => {
+        const seen = new Set();
+        const stack = [handler];
+        const raises = [];
+        let functions = 0;
+        while (stack.length) {
+            const node = stack.pop();
+            if (seen.has(node))
+                continue;
+            seen.add(node);
+            if (isFunctionWithBody(node))
+                functions += 1;
+            const { raises: own, reaches } = scan(node);
+            raises.push(...own);
+            stack.push(...reaches);
+        }
+        return { raises, functions };
+    };
+    // ── Handlers ─────────────────────────────────────────────────────────
+    /** The codes a handler's `ctx.refuse` takes, or null when its context carries no typed refuse. */
+    const allowedCodesOf = (handler) => {
+        const contextNode = handler;
+        // The type the registration expects the handler to have, which holds
+        // however the handler is written (a function, one held elsewhere, a
+        // wrapper's result) and whether or not it names its context. A
+        // registration that takes a handler or an entry holding one expects a
+        // union: the function member is the handler's. A method written in an
+        // options object is read off its own type, which the registration
+        // gave it.
+        const expected = ts.isMethodDeclaration(handler) ? checker.getTypeAtLocation(handler) : checker.getContextualType(handler);
+        const members = expected?.isUnion() ? expected.types : expected ? [expected] : [];
+        const parameter = members.flatMap((member) => member.getCallSignatures())[0]?.parameters[0];
+        const contextType = parameter && checker.getTypeOfSymbolAtLocation(parameter, contextNode);
+        const refuse = contextType && checker.getPropertyOfType(contextType, "refuse");
+        if (!refuse)
+            return null;
+        const codes = new Set();
+        for (const signature of checker.getTypeOfSymbolAtLocation(refuse, contextNode).getCallSignatures()) {
+            const optionsParameter = signature.parameters[1];
+            if (!optionsParameter)
+                return null;
+            const optionsType = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(optionsParameter, contextNode));
+            for (const part of optionsType.isUnion() ? optionsType.types : [optionsType]) {
+                const code = checker.getPropertyOfType(part, "code");
+                if (!code)
+                    continue;
+                const codeType = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(code, contextNode));
+                // A handler whose endpoint declares no code is handed a refuse that takes none.
+                if (codeType.flags & ts.TypeFlags.Never)
+                    continue;
+                const values = literalsOf(codeType);
+                // A refuse whose code is any string is the untyped one: it says nothing of what the handler may send.
+                if (values === null)
+                    return null;
+                for (const value of values)
+                    codes.add(value);
+            }
+        }
+        return [...codes];
+    };
+    /** The codes an options object's `refusals` property names: one code or a list, each a literal or a constant typed as one. */
+    const ownRefusalsOf = (optionsNode) => {
+        const options = optionsNode && unwrap(optionsNode);
+        if (!options || !ts.isObjectLiteralExpression(options))
+            return [];
+        const property = options.properties.find((candidate) => ts.isPropertyAssignment(candidate) && ts.isIdentifier(candidate.name) && candidate.name.text === "refusals");
+        if (!property || !ts.isPropertyAssignment(property))
+            return [];
+        const value = unwrap(property.initializer);
+        const entries = ts.isArrayLiteralExpression(value) ? [...value.elements] : [value];
+        return entries.flatMap((entry) => ts.isStringLiteralLike(entry) ? [entry.text] : literalsOf(checker.getTypeAtLocation(entry)) ?? []);
+    };
+    /** How a registration names its handler: `group.action` for an endpoint in a group, the key or variable it is held under otherwise, the name a mock entry is given, or the registration's own name when it is held under none. */
+    const handlerNameOf = (call, registration) => {
+        if (registration === "api" || registration === "override") {
+            const [name] = call.arguments;
+            if (name && ts.isStringLiteralLike(name))
+                return name.text;
+        }
+        const holder = call.parent;
+        const key = ts.isPropertyAssignment(holder) ? holder.name.getText()
+            : ts.isVariableDeclaration(holder) ? holder.name.getText() : null;
+        if (registration === "defineApi" && key && ts.isPropertyAssignment(holder)) {
+            const group = holder.parent.parent;
+            if (ts.isCallExpression(group) && group.arguments[1] === holder.parent && group.arguments[0] && ts.isStringLiteralLike(group.arguments[0])) {
+                return `${group.arguments[0].text}.${key}`;
+            }
+        }
+        // Unnamed (inside an app's own wrapper, say): the finding's `at` says where.
+        return key ?? registration;
+    };
+    const findings = [];
+    const unchecked = [];
+    let handlers = 0;
+    const checkRegistration = (call) => {
+        const callee = call.expression;
+        const registration = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
+        const form = registration ? HANDLER_REGISTRATIONS[registration] : undefined;
+        if (!registration || !form)
+            return;
+        if (!isLambderDeclaration(checker.getResolvedSignature(call)?.declaration))
+            return;
+        const [first, second] = call.arguments;
+        const handlerOf = (holder) => {
+            if (!holder || !ts.isObjectLiteralExpression(unwrap(holder)))
+                return undefined;
+            const property = unwrap(holder).properties.find((candidate) => candidate.name?.getText() === "handler");
+            if (!property)
+                return undefined;
+            if (ts.isPropertyAssignment(property))
+                return property.initializer;
+            if (ts.isMethodDeclaration(property))
+                return property;
+            if (ts.isShorthandPropertyAssignment(property))
+                return property.name;
+            return undefined;
+        };
+        const handler = form === "second" ? second
+            : form === "optionsHandler" ? handlerOf(first)
+                : second && isFunctionWithBody(unwrap(second)) ? second : handlerOf(second) ?? second;
+        const optionsNode = form === "second" ? first : form === "optionsHandler" ? first : second;
+        if (!handler)
+            return;
+        const name = handlerNameOf(call, registration);
+        const at = where(call);
+        const allowed = allowedCodesOf(handler) ?? (registration === "guard" || registration === "lambderGuard" ? ownRefusalsOfOrNull(optionsNode) : null);
+        if (allowed === null) {
+            unchecked.push(`${name} (${at})`);
+            return;
+        }
+        handlers += 1;
+        const { raises, functions } = reachOf(ts.isMethodDeclaration(handler) ? handler : unwrap(handler));
+        if (functions === 0) {
+            findings.push({ handler: name, at, problem: "untraced" });
+            return;
+        }
+        const allowedSet = new Set(allowed);
+        const reached = new Set();
+        const reported = new Set();
+        for (const raise of raises) {
+            if ("code" in raise) {
+                if (raise.code.startsWith("lambder/"))
+                    continue;
+                reached.add(raise.code);
+                if (!allowedSet.has(raise.code) && !reported.has(raise.code)) {
+                    reported.add(raise.code);
+                    findings.push({ handler: name, at, problem: "undeclared", code: raise.code, raisedAt: raise.at });
+                }
+            }
+            else if ("uncoded" in raise) {
+                if (requireCodes)
+                    findings.push({ handler: name, at, problem: "uncoded", raisedAt: raise.at });
+            }
+            else {
+                findings.push({ handler: name, at, problem: "unreadable", raisedAt: raise.at });
+            }
+        }
+        for (const code of ownRefusalsOf(optionsNode)) {
+            if (!reached.has(code))
+                findings.push({ handler: name, at, problem: "unused", code });
+        }
+    };
+    /** A guard's `refusals` option, or null when it has none: what a guard built without the vocabulary may send. */
+    const ownRefusalsOfOrNull = (optionsNode) => {
+        const own = ownRefusalsOf(optionsNode);
+        return own.length ? own : null;
+    };
+    for (const sourceFile of program.getSourceFiles()) {
+        if (!isOwnFile(sourceFile))
+            continue;
+        const visit = (node) => {
+            if (ts.isCallExpression(node))
+                checkRegistration(node);
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+    }
+    const uncheckedLine = unchecked.length ? [`  ${unchecked.length} ${unchecked.length === 1 ? "handler has" : "handlers have"} no typed refuse to check against: ${unchecked.join(", ")}`] : [];
+    if (handlers === 0) {
+        return failed(`✗ ${options.tsconfig}: no handler Lambder hands a typed refuse was found, so nothing was checked. Do its APIs come from an init that declares its refusals (declareRefusals), and do its files resolve lambder?`, uncheckedLine);
+    }
+    // Duplicate uncoded or unreadable findings of one site through two paths say the same thing once.
+    const unique = [...new Map(findings.map((finding) => [JSON.stringify(finding), finding])).values()];
+    const lines = [
+        unique.length === 0
+            ? `✓ ${handlers} handlers reach only the refusals they may send`
+            : `✗ ${unique.length} refusal ${unique.length === 1 ? "finding" : "findings"} in ${new Set(unique.map((finding) => finding.handler)).size} of ${handlers} handlers`,
+        ...unique.map(describeFinding),
+        ...uncheckedLine,
+    ];
+    return { ok: unique.length === 0, handlers, findings: unique, lines };
+};
+const describeFinding = (finding) => {
+    switch (finding.problem) {
+        case "undeclared": return `  ${finding.handler} (${finding.at}) can refuse with "${finding.code}" (${finding.raisedAt}), which it may not send: name it in its refusals, or keep the handler from reaching it`;
+        case "unused": return `  ${finding.handler} (${finding.at}) declares "${finding.code}", which nothing it reaches raises`;
+        case "uncoded": return `  ${finding.handler} (${finding.at}) can reach a refusal with no code (${finding.raisedAt})`;
+        case "unreadable": return `  ${finding.handler} (${finding.at}) can reach a refusal whose code is not a string literal (${finding.raisedAt}), so which code it sends cannot be told`;
+        case "untraced": return `  ${finding.handler} (${finding.at}) is handed a typed refuse, but its function cannot be found (a parameter, a dependency's value), so nothing it reaches was checked`;
+    }
+};
+const failed = (line, details = []) => ({ ok: false, handlers: 0, findings: [], lines: [line, ...details] });
+const isInside = (path, directory) => path === directory || path.startsWith(directory + sep);
+const realPathOf = (ts, path) => ts.sys.realpath?.(path) ?? path;

package/dist/build/loadTypeScriptCompiler.d.ts

@@ -0,0 +1,10 @@
+/** The typescript package as the build tools read it: its compiler API. */
+export type TypeScriptModule = typeof import("typescript");
+/**
+ * The compiler API a build tool reads a project through, from the typescript
+ * package installed beside lambder. TypeScript 7 ships none, so its package
+ * answers the import without one, and an app on TypeScript 7 installs a 6.x
+ * where its generator script runs. `reader` says who reads what, for the
+ * error: "writeApiContract reads the contract".
+ */
+export declare const loadTypeScriptCompiler: (reader: string) => Promise<TypeScriptModule>;

package/dist/build/loadTypeScriptCompiler.js

@@ -0,0 +1,20 @@
+/**
+ * The compiler API a build tool reads a project through, from the typescript
+ * package installed beside lambder. TypeScript 7 ships none, so its package
+ * answers the import without one, and an app on TypeScript 7 installs a 6.x
+ * where its generator script runs. `reader` says who reads what, for the
+ * error: "writeApiContract reads the contract".
+ */
+export const loadTypeScriptCompiler = async (reader) => {
+    const requirement = `${reader} through the TypeScript compiler API (typescript 5.4 to 6.x): install one beside lambder, such as in the generator's own package when the app is on TypeScript 7`;
+    let ts;
+    try {
+        ts = (await import("typescript")).default;
+    }
+    catch (err) {
+        throw new Error(requirement, { cause: err });
+    }
+    if (typeof ts?.createProgram !== "function")
+        throw new Error(`${requirement}; the typescript installed (${ts?.version ?? "unknown"}) has no compiler API`);
+    return ts;
+};

package/dist/build/writeApiContract.js

@@ -2,7 +2,27 @@ import { existsSync, readFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { ContractTypePrinter } from "./ContractTypePrinter.js";
 import { modulePathOf } from "./moduleLocation.js";
+import { loadTypeScriptCompiler } from "./loadTypeScriptCompiler.js";
 import { writeFileAtomically } from "./writeFileAtomically.js";
+/*
+ * The contract a client compiles against, written out once as plain types.
+ *
+ * A client that imports `typeof lambder.ApiContract` from the server's
+ * sources compiles the server to get it: every endpoint's schemas, the
+ * libraries they infer through, and whatever the server's entry imports
+ * besides, and it resolves every endpoint's entry out of the declarations
+ * registerApiGroups() mapped. In a large app that is most of the client's
+ * type-check time and memory, for one type. This reads the ApiContract
+ * property off the exported instance and writes it out as the structure it
+ * resolves to, one object type with plain members in a module that imports
+ * nothing, so the client compiles the contract alone.
+ *
+ * What can go wrong is the file: stale against the server, or printed as
+ * something other than the type it stands for. A check compares it with what
+ * the server's sources print now, and a write first proves the printed type
+ * the same as the server's, entry by entry, in both directions, before the
+ * file is touched.
+ */
 const DEFAULT_HEADER = [
     "Generated by writeApiContract() from lambder/build. Do not edit.",
     "",
@@ -54,7 +74,7 @@ const DIAGNOSTIC_LIMIT = 20;
  * over the old one, so a build reading it meanwhile never sees half of it.
  */
 export const writeApiContract = async (options) => {
-    const ts = await loadTypeScript();
+    const ts = await loadTypeScriptCompiler("writeApiContract reads the contract");
     const file = resolve(options.file);
     const modulePath = modulePathOf(options.module);
     const exportName = options.exportName ?? "default";
@@ -89,20 +109,6 @@ export const writeApiContract = async (options) => {
     writeFileAtomically(file, text, previous !== null);
     return result(true, true, [`✓ Wrote ${options.file} (${count} APIs)`, ...(movedSummary.length ? movedSummary : ["  no API's types changed; the header or layout did"])], moved);
 };
-/** The compiler API writeApiContract reads with. TypeScript 7 ships none, so its package answers the import without one. */
-const loadTypeScript = async () => {
-    const requirement = "writeApiContract reads the contract through the TypeScript compiler API (typescript 5.4 to 6.x): install one beside lambder, such as in the generator's own package when the app is on TypeScript 7";
-    let ts;
-    try {
-        ts = (await import("typescript")).default;
-    }
-    catch (err) {
-        throw new Error(requirement, { cause: err });
-    }
-    if (typeof ts?.createProgram !== "function")
-        throw new Error(`${requirement}; the typescript installed (${ts?.version ?? "unknown"}) has no compiler API`);
-    return ts;
-};
 /** The server's compiler options, and the root files a program over the module needs: the module, and the project's own declaration files, which may declare globals the module relies on. */
 const readProject = (ts, tsconfig, modulePath) => {
     const configPath = tsconfig ? resolve(tsconfig) : ts.findConfigFile(dirname(modulePath), ts.sys.fileExists);

package/dist/build.d.ts

@@ -5,8 +5,9 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources; and generateApiFiles, every one of them for
- * every app a script names, in one call. Node-only and imported by nothing else
+ * from the server's sources; generateApiFiles, every one of them for
+ * every app a script names, in one call; and checkApiRefusals, every
+ * refusal a handler can reach held to the codes it may send. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
@@ -18,6 +19,8 @@ export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
 export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
 export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
+export { checkApiRefusals } from "./build/checkApiRefusals.js";
+export type { LambderApiRefusalCheckOptions, LambderApiRefusalCheckResult, LambderRefusalCheckFinding, } from "./build/checkApiRefusals.js";
 export { generateApiFiles } from "./build/generateApiFiles.js";
 export type { LambderApiFilesConfig, LambderApiFilesApp, LambderApiFilesResult } from "./build/generateApiFiles.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -5,12 +5,14 @@
  * ships: the signature file both sides read, the declared options as plain
  * data, and one guard's parameters as the least a browser needs of them, all
  * from the app's own instance; and the contract a client compiles against,
- * from the server's sources; and generateApiFiles, every one of them for
- * every app a script names, in one call. Node-only and imported by nothing else
+ * from the server's sources; generateApiFiles, every one of them for
+ * every app a script names, in one call; and checkApiRefusals, every
+ * refusal a handler can reach held to the codes it may send. Node-only and imported by nothing else
  * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export { writeApiOptions } from "./build/writeApiOptions.js";
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+export { checkApiRefusals } from "./build/checkApiRefusals.js";
 export { generateApiFiles } from "./build/generateApiFiles.js";

package/dist/core/Lambder.d.ts

@@ -560,11 +560,12 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private runApi;
     /**
      * A thrown LambderApiRefusal (from a hook, say) as the structured API
-     * envelope: the core's one mapping, after the same check the pipeline
-     * applies, against the endpoint the call names, its lazy group loaded if
-     * the refusal came before the call reached it. A name no API is
-     * registered under declares no code, so only an uncoded or a framework
-     * refusal goes out for it.
+     * envelope: the pipeline's own answer to a refusal (answerRefusal), so
+     * it is checked against the endpoint the call names, its lazy group
+     * loaded if the refusal came before the call reached it, and one saying
+     * the session is over ends it. A name no API is registered under
+     * declares no code, so only an uncoded or a framework refusal goes out
+     * for it.
      */
     private apiErrorResponse;
 }

package/dist/core/Lambder.js

@@ -13,12 +13,12 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
-import { checkedRefusal, declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { refuse } from "../shared/wire/LambderApiRefusal.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.js";
 import { assertPlainData } from "../shared/util/assertPlainData.js";
-import { apiNotFoundAnswer, envelopeAnswer, refusalAnswer, sessionExpiredAnswer, successEnvelope, versionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { apiNotFoundAnswer, envelopeAnswer, sessionExpiredAnswer, successEnvelope, versionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 import { toGuardEntries } from "../api/LambderApiGuards.js";
@@ -1275,16 +1275,17 @@ export default class Lambder {
     }
     /**
      * A thrown LambderApiRefusal (from a hook, say) as the structured API
-     * envelope: the core's one mapping, after the same check the pipeline
-     * applies, against the endpoint the call names, its lazy group loaded if
-     * the refusal came before the call reached it. A name no API is
-     * registered under declares no code, so only an uncoded or a framework
-     * refusal goes out for it.
+     * envelope: the pipeline's own answer to a refusal (answerRefusal), so
+     * it is checked against the endpoint the call names, its lazy group
+     * loaded if the refusal came before the call reached it, and one saying
+     * the session is over ends it. A name no API is registered under
+     * declares no code, so only an uncoded or a framework refusal goes out
+     * for it.
      */
     async apiErrorResponse(err, ctx) {
         const apiName = ctx.apiName ?? "";
-        const refusal = checkedRefusal(apiName, (await this.registeredDefinitionOf(apiName))?.refusals ?? NO_DECLARED_REFUSALS, err);
-        return responseFromAnswer(refusalAnswer(refusal, this.apiVersion, ctx.logList));
+        const refusals = (await this.registeredDefinitionOf(apiName))?.refusals ?? NO_DECLARED_REFUSALS;
+        return responseFromAnswer(await this.pipeline.answerRefusal(apiName, refusals, err, ctx));
     }
 }
 /** The init bound to one vocabulary (or none): the policy builders, refuse and create() that share it. */

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

@@ -10,7 +10,7 @@ export type LambderApiRefusalOptions = {
     refusal?: LambderUncheckedRefusalMessage | string;
     /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
     notAuthorized?: boolean;
-    /** Sets the envelope's `sessionExpired` flag (the caller clears session cookies and calls sessionExpiredHandler). */
+    /** Sets the envelope's `sessionExpired` flag (the caller clears session cookies and calls sessionExpiredHandler); on an API call, the server also ends the session the call held. */
     sessionExpired?: boolean;
     /**
      * HTTP status of the refusal response. Default 200: the envelope is the
@@ -178,7 +178,7 @@ export type LambderRefuseOptions = {
     title?: string;
     /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). A declared code's flag is its declaration's, and a refusal with such a code that sets it here is a crash. */
     notAuthorized?: boolean;
-    /** Sets the envelope's sessionExpired flag. Not for a refusal with a declared code, whose flags are its declaration's. */
+    /** Sets the envelope's sessionExpired flag, and the server ends the session the call held. Not for a refusal with a declared code, whose flags are its declaration's. */
     sessionExpired?: boolean;
     /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). A declared code's status is its declaration's, and a refusal with such a code that sets one here is a crash. */
     statusCode?: LambderHttpStatusCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "14.0.1",
+  "version": "14.1.1",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [