lambder 7.3.1 → 8.0.2

package/dist/api/LambderApiSignature.js

@@ -2,56 +2,35 @@ import { z } from "zod";
 import { toGuardEntries } from "./LambderApiGuards.js";
 import { API_SIGNATURE_HEX_LENGTH, EXTENSIBLE_ENUM_META_KEY } from "../shared/wire/LambderApiSignature.js";
 import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+import { canonicalJson } from "../shared/util/canonicalJson.js";
 /*
  * The digest of an endpoint's client-facing shape, computed once, by the
  * generator, through Lambder.apiSignatures(). Nothing digests at request
- * time: the server and the client both carry the generated map and the
- * pipeline compares entries, so the one computation has nothing to agree
- * with but itself. See LambderApiSignatureMap.
+ * time: server and client both carry the generated map and the pipeline
+ * compares entries, so there is no second computation to disagree with.
+ * See LambderApiSignatureMap.
  */
-/**
- * JSON with object keys sorted at every level, so two descriptions of the
- * same shape hash the same whatever order they were built in. Arrays keep
- * their order: a tuple's positions and an enum's values are part of the
- * shape. Undefined entries are dropped, as JSON.stringify would drop them.
- */
-const canonicalJson = (value) => JSON.stringify(sortKeys(value));
-const sortKeys = (value) => {
-    if (Array.isArray(value))
-        return value.map(sortKeys);
-    if (value === null || typeof value !== "object")
-        return value;
-    const source = value;
-    const sorted = {};
-    for (const key of Object.keys(source).sort()) {
-        if (source[key] !== undefined)
-            sorted[key] = sortKeys(source[key]);
-    }
-    return sorted;
-};
 /**
  * Three edits to every node zod emits, before it is hashed.
  *
  * The `default` keyword goes. Its value is server behaviour, not shape: a
- * client never sends it, and its compiled types do not carry it. And for a
- * function default (`.default(() => new Date())`, `.prefault`, `.catch`)
- * zod writes whatever the function returned at conversion time, a clock
- * reading or a random value, which would give the endpoint a different
- * digest on every computation and a generated map that never matches the
- * server. Nothing distinguishes such a default from a constant one once zod
- * has evaluated it, so every default goes, and the one thing about a default
- * a client can see, that the field may be omitted, stays through `required`.
+ * client never sends it. For a function default (`.default(() => new
+ * Date())`, `.prefault`, `.catch`) zod writes whatever the function returned
+ * at conversion time, a clock reading or a random value, so the digest would
+ * differ on every computation and the generated map would never match the
+ * server. Once evaluated, such a default looks like a constant one, so every
+ * default goes; what a client can see of it, that the field may be omitted,
+ * stays through `required`.
  *
- * `required` is sorted. It is a set, and the order fields are declared in is
- * not shape either; left as emitted, reordering two fields forced a reload.
+ * `required` is sorted: it is a set, and declaration order is not shape.
+ * Left as emitted, reordering two fields would force a reload.
  *
- * An enum marked with extensibleEnum() loses its values in an output. Its
- * clients tolerate a value they do not know, so a response carrying one they
- * were not built with, or no longer carrying one they were, changes nothing
- * they can see; the node still says it holds a string. In an input the values
- * stay, since a value dropped from the list is a request an older client may
- * still send and the server now refuses. The mark itself goes in both, so
- * marking an enum changes no input's digest.
+ * An enum marked with extensibleEnum() loses its values in an output: its
+ * clients tolerate unknown values, so adding or removing one changes nothing
+ * they can see, and the node still says it holds a string. In an input the
+ * values stay, since a value dropped from the list is one an older client
+ * may still send and the server would refuse. The mark itself goes in both,
+ * so marking an enum changes no input's digest.
  */
 const keepShapeOnly = (node, io) => {
     delete node.default;
@@ -76,18 +55,16 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  * input and output schemas as JSON Schema, every guard it declares with the
  * schema that guard validates (the guardInput the client sends separately,
  * or the apiInput slice of the payload), and whether it demands an
- * idempotency key. Anything else about the endpoint (its rate limits, a
- * guard's parameter, the handler) changes nothing for a client and is left
- * out, so changing it never forces a reload.
+ * idempotency key. 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 description is hashed as built, descriptions and titles included: a
- * schema is what the server says it is, and a client built against a
- * different one reloads once, with one exception the schema declares itself:
- * the values of an extensibleEnum() in an output (see keepShapeOnly). What
- * must hold for the digest to mean anything is that a schema is built from
- * static values: one that reads the clock, a random source or the environment
- * at construction digests differently in the generator's process and on the
- * server.
+ * Schemas are hashed as built, descriptions and titles included, so a client
+ * built against a different one reloads once. The exception is an output
+ * extensibleEnum()'s values (see keepShapeOnly). Schemas must be built from
+ * static values: one that reads the clock, a random source or the
+ * environment at construction digests differently in the generator's process
+ * and on the server.
  */
 export const apiSignatureOf = async (definition, guards) => {
     const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {

package/dist/api/LambderApiValidationRefusal.d.ts

@@ -5,13 +5,12 @@ import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
  * response. The API's own schema and every preflight slice (a guard's input,
  * a rate-limit key's fields) throw this when a value fails to parse, and the
  * pipeline renders it in one place: through the app's input validation
- * handler when it set one, otherwise as the standard 422 body. The engines
- * therefore never build a response and never see a resolver, which is what
- * lets them run outside a Lambda.
+ * handler when set, otherwise as the standard 422 body. The engines never
+ * build a response or see a resolver, which lets them run outside a Lambda.
  *
- * A LambderApiRefusal, so every catch that maps refusals already handles it;
- * the brand tells the pipeline to route it through the validation handler
- * instead of the refusal envelope.
+ * It is a LambderApiRefusal, so every catch that maps refusals handles it;
+ * the brand routes it through the validation handler instead of the refusal
+ * envelope.
  */
 export declare class LambderApiValidationRefusal extends LambderApiRefusal {
     /** Brand for detection across duplicate lambder installs, like LambderApiRefusal's. */
@@ -26,7 +25,8 @@ export declare const isLambderApiValidationRefusal: (err: unknown) => err is Lam
  * a guardInput value from the raw guardInputs map). Runs before the API's
  * own validation; a failure throws the same LambderApiValidationRefusal the
  * API's schema throws, so the pipeline answers every rejected input alike.
- * Shared by the guards engine and the rate-limit engine, and living here
- * beside the error it throws rather than in one of the two.
+ * Shared by the guards and rate-limit engines, so it lives beside the error
+ * it throws. Parsed asynchronously, so a slice with an async refinement (a
+ * lookup, say) validates instead of making zod throw on every call.
  */
-export declare const parsePreflightSlice: (input: z.ZodType, value: unknown) => unknown;
+export declare const parsePreflightSlice: (input: z.ZodType, value: unknown) => Promise<unknown>;

package/dist/api/LambderApiValidationRefusal.js

@@ -4,13 +4,12 @@ import { LambderApiRefusal, isLambderApiRefusal } from "../shared/wire/LambderAp
  * response. The API's own schema and every preflight slice (a guard's input,
  * a rate-limit key's fields) throw this when a value fails to parse, and the
  * pipeline renders it in one place: through the app's input validation
- * handler when it set one, otherwise as the standard 422 body. The engines
- * therefore never build a response and never see a resolver, which is what
- * lets them run outside a Lambda.
+ * handler when set, otherwise as the standard 422 body. The engines never
+ * build a response or see a resolver, which lets them run outside a Lambda.
  *
- * A LambderApiRefusal, so every catch that maps refusals already handles it;
- * the brand tells the pipeline to route it through the validation handler
- * instead of the refusal envelope.
+ * It is a LambderApiRefusal, so every catch that maps refusals handles it;
+ * the brand routes it through the validation handler instead of the refusal
+ * envelope.
  */
 export class LambderApiValidationRefusal extends LambderApiRefusal {
     /** Brand for detection across duplicate lambder installs, like LambderApiRefusal's. */
@@ -29,11 +28,12 @@ export const isLambderApiValidationRefusal = (err) => isLambderApiRefusal(err) &
  * a guardInput value from the raw guardInputs map). Runs before the API's
  * own validation; a failure throws the same LambderApiValidationRefusal the
  * API's schema throws, so the pipeline answers every rejected input alike.
- * Shared by the guards engine and the rate-limit engine, and living here
- * beside the error it throws rather than in one of the two.
+ * Shared by the guards and rate-limit engines, so it lives beside the error
+ * it throws. Parsed asynchronously, so a slice with an async refinement (a
+ * lookup, say) validates instead of making zod throw on every call.
  */
-export const parsePreflightSlice = (input, value) => {
-    const parsed = input.safeParse(value);
+export const parsePreflightSlice = async (input, value) => {
+    const parsed = await input.safeParseAsync(value);
     if (!parsed.success)
         throw new LambderApiValidationRefusal(parsed.error);
     return parsed.data;

package/dist/build/freshProcessVerifier.d.ts

@@ -0,0 +1,13 @@
+/** What the parent asks for: which export of which module to digest, and the file to compare it with. */
+export type FreshProcessRequest = {
+    moduleUrl: string;
+    exportName: string;
+    file: string;
+};
+/** The comparison, or why none could be made. */
+export type FreshProcessVerdict = {
+    same: boolean;
+    lines: string[];
+} | {
+    failure: string;
+};

package/dist/build/freshProcessVerifier.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "fs";
+import { describeSignatureChanges, readSignatureMap, VERIFY_REPORT_PREFIX } from "./writeApiSignatures.js";
+const request = JSON.parse(process.argv[2] ?? "null");
+const namespace = await import(request.moduleUrl);
+const source = namespace[request.exportName];
+let verdict;
+if (typeof source?.apiSignatureEntries !== "function") {
+    verdict = { failure: `${request.moduleUrl} has no export "${request.exportName}" that lists API signatures: name the export holding the instance in exportName` };
+}
+else {
+    const { movedLines, summary } = describeSignatureChanges(await source.apiSignatureEntries(), readSignatureMap(readFileSync(request.file, "utf8")));
+    verdict = { same: movedLines.length === 0, lines: [summary, ...movedLines] };
+}
+// Waited for: a write to a pipe can still be pending when the process exits,
+// and the parent reads the pipe.
+await new Promise((resolveWrite) => process.stdout.write(`\n${VERIFY_REPORT_PREFIX}${JSON.stringify(verdict)}\n`, () => resolveWrite()));
+// The app's module may hold the process open (a client's sockets, a timer),
+// and this process exists for the one comparison.
+process.exit(0);

package/dist/build/writeApiSignatures.d.ts

@@ -0,0 +1,109 @@
+import type { LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
+/**
+ * How the fresh process reports its comparison: one line on stdout starting
+ * with this, then the verdict as JSON. The line, not the exit status, is the
+ * answer: the app's module prints what it likes while it loads, and a
+ * process that fails before the line never compared anything.
+ */
+export declare const VERIFY_REPORT_PREFIX = "lambder-api-signatures-verified:";
+/** This process's execArgv, less the flags only it may run with (see PARENT_ONLY_FLAG). */
+export declare const freshProcessNodeFlags: (execArgv: readonly string[]) => string[];
+/** What writeApiSignatures reads the signatures from: a Lambder instance, or anything else that lists them the same way. */
+export type LambderApiSignatureSource = {
+    apiSignatureEntries(): Promise<LambderApiSignatureEntry[]>;
+};
+export type LambderApiSignatureFileOptions = {
+    /** The TypeScript module to write, exporting `apiSignatures`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk is what the registrations produce now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiSignatures(). */
+    header?: string;
+    /** Quotes in the generated module. Default: "double". */
+    quotes?: "single" | "double";
+    /** End the generated statements with semicolons. Default: true. */
+    semicolons?: boolean;
+    /**
+     * After writing, or after a check that found the file current, load the
+     * module that holds the instance in a fresh Node process and check the
+     * file against what it digests there. A schema built from the clock or a
+     * random source digests differently in every process; this catches it by
+     * endpoint name instead of letting signatures change on every build. Only
+     * that module is loaded, never the calling script, so nothing the script
+     * does runs twice; the module's own top-level code does run again. The
+     * fresh process gets this process's Node flags (`--import`, `--require`,
+     * `--loader`, `--conditions`) less the inspector, watch mode, the test
+     * runner and the eval flags (`-e`, `-p`, `--input-type`), so a TypeScript
+     * module loads there as it did here when its loader is on the command
+     * line or in NODE_OPTIONS. Default: not verified.
+     */
+    verifyInFreshProcess?: {
+        /**
+         * The module that exports the instance: a path relative to the
+         * working directory, or a file URL, as a URL such as
+         * `new URL("../backend/index.js", import.meta.url)` beside the
+         * generator's own import of it, or as the string
+         * `import.meta.resolve()` answers.
+         */
+        module: string | URL;
+        /** The export that holds the instance. Default: "default", the module's default export. */
+        exportName?: string;
+    };
+};
+export type LambderApiSignatureFileResult = {
+    /** False when a check found the file stale, or a fresh process digested different signatures or never compared them. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** How many APIs the file holds. */
+    count: number;
+    /** True when the file was (re)written; a file that already holds these signatures is left untouched, however it is formatted. */
+    written: boolean;
+    /** Endpoints whose signature differs from the file that was on disk, by name. */
+    changed: string[];
+    added: string[];
+    /** Endpoints the file held and the registrations no longer have. Named by key only: a key is a one-way hash of a name that is gone. */
+    removedKeys: string[];
+    /** What happened, as lines to print: a summary, then one line per endpoint that moved. */
+    lines: string[];
+};
+/**
+ * The map a generated file holds, read back by its hex pairs. Either quote
+ * style parses, and so does a key without quotes: a formatter that quotes
+ * properties only as needed (Prettier's default, Biome's, ESLint's
+ * quote-props) unquotes every key that starts with a letter.
+ */
+export declare const readSignatureMap: (contents: string) => Record<string, string>;
+/** How the registrations differ from a map read off a file, by endpoint, as the lines both this process and a fresh one print. */
+export declare const describeSignatureChanges: (entries: LambderApiSignatureEntry[], previousMap: Record<string, string>) => {
+    changed: string[];
+    added: string[];
+    removedKeys: string[];
+    movedLines: string[];
+    summary: string;
+};
+/**
+ * Writes the signature map both sides ship (see Lambder.apiSignatures()) to
+ * a TypeScript module, or checks the one on disk, and says which endpoints
+ * moved: every changed signature is a forced reload for the tabs calling
+ * that endpoint, so this is the line that says how wide a deploy's reload
+ * will be.
+ *
+ * Call it from a generator script that imports the app's instance:
+ *
+ * ```ts
+ * import { writeApiSignatures } from "lambder/build";
+ * import { lambder } from "../server/src/index.js";
+ *
+ * const result = await writeApiSignatures(lambder, { file: "shared/generated/apiSignatures.generated.ts", check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Signatures are compared as the map the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it or unquoted
+ * its keys is neither stale nor rewritten. `verifyInFreshProcess` also
+ * checks the file, written or found current, against the instance's module
+ * loaded in a fresh process.
+ */
+export declare const writeApiSignatures: (source: LambderApiSignatureSource, options: LambderApiSignatureFileOptions) => Promise<LambderApiSignatureFileResult>;

package/dist/build/writeApiSignatures.js

@@ -0,0 +1,222 @@
+import { spawnSync } from "child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+/*
+ * The signature file every app with apiSignatures needs, written and checked
+ * by the framework that defines it.
+ *
+ * The digests are computed once, by the generator, into this file, and both
+ * sides read the file: the frontend hands it to LambderCaller and the server
+ * hands it to create(), so the two can never disagree. What can still go wrong is the file itself (stale against the
+ * registrations, or different in every process because a schema reads the
+ * clock), and both are checked here.
+ */
+/**
+ * How the fresh process reports its comparison: one line on stdout starting
+ * with this, then the verdict as JSON. The line, not the exit status, is the
+ * answer: the app's module prints what it likes while it loads, and a
+ * process that fails before the line never compared anything.
+ */
+export const VERIFY_REPORT_PREFIX = "lambder-api-signatures-verified:";
+/** How long a fresh-process verification may run before it counts as failed. */
+const VERIFY_TIMEOUT_MS = 5 * 60 * 1000;
+/** What a fresh process may print before its verdict line: a chatty module must not fill the pipe and fail the check. */
+const VERIFY_OUTPUT_BYTES = 64 * 1024 * 1024;
+/** The fresh process's entry, beside this module in the build. */
+const FRESH_PROCESS_ENTRY = new URL("./freshProcessVerifier.js", import.meta.url);
+/**
+ * This process's own Node flags that the fresh process must not inherit,
+ * because they make it something other than a plain run of the verifier: the
+ * inspector (`--inspect-brk` waits for a debugger forever, and a fixed port
+ * collides with this process's), watch mode (a watched process never exits),
+ * the test runner (`--test` runs the entry as a test file), and the eval
+ * flags: `-e`, `-p` and a cluster of them such as `-pe` (which run their code
+ * in place of the entry), and `--input-type` (which Node refuses beside an
+ * entry file). Everything else, `--import`, `--require`, `--loader`,
+ * `--conditions` and the rest, is how this process loads the app's modules,
+ * and the fresh one needs it to load the same way.
+ */
+const PARENT_ONLY_FLAG = /^(--(inspect|debug-port|watch|test)([-=].*)?|--(eval|print|input-type)(=.*)?|-[a-z]*[ep][a-z]*)$/;
+/** This process's execArgv, less the flags only it may run with (see PARENT_ONLY_FLAG). */
+export const freshProcessNodeFlags = (execArgv) => {
+    const kept = [];
+    for (let index = 0; index < execArgv.length; index++) {
+        const flag = execArgv[index];
+        if (!PARENT_ONLY_FLAG.test(flag)) {
+            kept.push(flag);
+            continue;
+        }
+        // execArgv holds only Node's own options (the script and its
+        // arguments are argv), so an element that is not a flag is the value
+        // of the flag before it, and goes with it.
+        const next = execArgv[index + 1];
+        if (!flag.includes("=") && next !== undefined && !next.startsWith("-"))
+            index++;
+    }
+    return kept;
+};
+const DEFAULT_HEADER = [
+    "Generated by writeApiSignatures() from lambder/build. Do not edit.",
+    "",
+    "Every API the server registers, keyed by the hash of its name, with the",
+    "digest of its client-facing shape. The client sends the value with every",
+    "call and the server compares it with its own copy of this file, so a",
+    "deploy reloads only the tabs that call an endpoint whose shape changed.",
+].join("\n");
+/**
+ * The map a generated file holds, read back by its hex pairs. Either quote
+ * style parses, and so does a key without quotes: a formatter that quotes
+ * properties only as needed (Prettier's default, Biome's, ESLint's
+ * quote-props) unquotes every key that starts with a letter.
+ */
+export const readSignatureMap = (contents) => {
+    const map = {};
+    for (const match of contents.matchAll(/(?<![\w$])(['"]?)([0-9a-f]+)\1\s*:\s*['"]([0-9a-f]+)['"]/g))
+        map[match[2]] = match[3];
+    return map;
+};
+/** How the registrations differ from a map read off a file, by endpoint, as the lines both this process and a fresh one print. */
+export const describeSignatureChanges = (entries, previousMap) => {
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const changed = entries.filter(({ key, signature }) => key in previousMap && previousMap[key] !== signature).sort(byName).map(({ name }) => name);
+    const added = entries.filter(({ key }) => !(key in previousMap)).sort(byName).map(({ name }) => name);
+    const keys = new Set(entries.map(({ key }) => key));
+    const removedKeys = Object.keys(previousMap).filter((key) => !keys.has(key));
+    const movedLines = [
+        ...changed.map((name) => `  ~ ${name}`),
+        ...added.map((name) => `  + ${name}`),
+        ...removedKeys.map((key) => `  - ${key} (removed: a key cannot be resolved back to its name)`),
+    ];
+    const summary = `${changed.length} changed, ${added.length} added, ${removedKeys.length} removed (${entries.length - changed.length - added.length} unchanged)`;
+    return { changed, added, removedKeys, movedLines, summary };
+};
+const renderSignatureFile = (entries, options) => {
+    const quote = options.quotes === "single" ? "'" : "\"";
+    const semicolon = options.semicolons === false ? "" : ";";
+    const header = (options.header ?? DEFAULT_HEADER).split("\n").map((line) => line ? `// ${line}` : "//");
+    // Keys and signatures are hex, so swapping the quote character touches nothing inside them.
+    const map = JSON.stringify(Object.fromEntries(entries.map(({ key, signature }) => [key, signature])), null, 4).replace(/"/g, quote);
+    return [
+        ...header,
+        `import type { LambderApiSignatureMap } from ${quote}lambder/client${quote}${semicolon}`,
+        "",
+        // Kept as written by a formatter that honours it, so a format pass
+        // after every generation has nothing to change. One that does not
+        // honour it changes the text only: the map reads back the same.
+        "// prettier-ignore",
+        `export const apiSignatures: LambderApiSignatureMap = ${map}${semicolon}`,
+        "",
+    ].join("\n");
+};
+/**
+ * Writes the signature map both sides ship (see Lambder.apiSignatures()) to
+ * a TypeScript module, or checks the one on disk, and says which endpoints
+ * moved: every changed signature is a forced reload for the tabs calling
+ * that endpoint, so this is the line that says how wide a deploy's reload
+ * will be.
+ *
+ * Call it from a generator script that imports the app's instance:
+ *
+ * ```ts
+ * import { writeApiSignatures } from "lambder/build";
+ * import { lambder } from "../server/src/index.js";
+ *
+ * const result = await writeApiSignatures(lambder, { file: "shared/generated/apiSignatures.generated.ts", check: process.argv.includes("--check") });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Signatures are compared as the map the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it or unquoted
+ * its keys is neither stale nor rewritten. `verifyInFreshProcess` also
+ * checks the file, written or found current, against the instance's module
+ * loaded in a fresh process.
+ */
+export const writeApiSignatures = async (source, options) => {
+    const file = resolve(options.file);
+    const entries = await source.apiSignatureEntries();
+    const previous = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const { changed, added, removedKeys, movedLines, summary } = describeSignatureChanges(entries, previous === null ? {} : readSignatureMap(previous));
+    const unchanged = previous !== null && movedLines.length === 0;
+    const result = (ok, written, lines) => ({ ok, file, count: entries.length, written, changed, added, removedKeys, lines });
+    // A stale file is the answer by itself: a fresh process could only find
+    // it stale again. A current one goes on to the verification, as a write
+    // does, so a check that names verifyInFreshProcess verifies.
+    let written = false;
+    let lines;
+    if (options.check) {
+        if (!unchanged)
+            return result(false, false, [`✗ ${options.file} is stale: regenerate it`, `  ${summary}`, ...movedLines]);
+        lines = [`✓ ${options.file} matches the ${entries.length} registered APIs`];
+    }
+    else {
+        // A file that already holds this map is left as it is, however it is
+        // formatted, so a watcher or an incremental build sees no change
+        // where there is none, and a formatter's or a checkout's version of
+        // the file is not rewritten back on every run. A change of header,
+        // quotes or semicolons shows the next time the map changes. The write
+        // goes to a file beside the target and is renamed over it, so a build
+        // reading the file meanwhile sees the old map or the new one, never
+        // half of one. A symlink is followed to the file it names: renamed
+        // over, the link itself would become the new file and its target
+        // would keep the old map.
+        written = !unchanged;
+        if (written) {
+            const target = previous === null ? file : realpathSync(file);
+            mkdirSync(dirname(target), { recursive: true });
+            const partial = `${target}.${process.pid}.tmp`;
+            try {
+                writeFileSync(partial, renderSignatureFile(entries, options));
+                renameSync(partial, target);
+            }
+            catch (err) {
+                rmSync(partial, { force: true });
+                throw err;
+            }
+        }
+        lines = [
+            written ? `✓ Wrote ${options.file} (${entries.length} APIs)` : `✓ ${options.file} is up to date (${entries.length} APIs)`,
+            ...(movedLines.length ? [`  ${summary}`, ...movedLines] : ["  no signatures changed: this build forces no reloads"]),
+        ];
+    }
+    if (!options.verifyInFreshProcess)
+        return result(true, written, lines);
+    const { module: instanceModule, exportName = "default" } = options.verifyInFreshProcess;
+    const request = {
+        // A string that is already a file URL (what import.meta.resolve()
+        // answers) is taken as one: resolved as a path, it would name a
+        // directory called "file:" under the working directory.
+        moduleUrl: typeof instanceModule === "string" && !/^file:/i.test(instanceModule)
+            ? pathToFileURL(resolve(instanceModule)).href
+            : new URL(instanceModule).href,
+        exportName,
+        file,
+    };
+    const child = spawnSync(process.execPath, [...freshProcessNodeFlags(process.execArgv), fileURLToPath(FRESH_PROCESS_ENTRY), JSON.stringify(request)], {
+        encoding: "utf8",
+        timeout: VERIFY_TIMEOUT_MS,
+        maxBuffer: VERIFY_OUTPUT_BYTES,
+    });
+    const reportLine = (child.stdout ?? "").split("\n").findLast((line) => line.startsWith(VERIFY_REPORT_PREFIX));
+    if (reportLine === undefined) {
+        const stderrTail = (child.stderr ?? "").trim().split("\n").slice(-20).filter(Boolean);
+        return result(false, written, [
+            ...lines,
+            child.error
+                ? `✗ the fresh process that verifies ${options.file} could not finish: ${child.error.message}`
+                : `✗ the fresh process that verifies ${options.file} never compared it: loading ${request.moduleUrl} failed (exit status ${child.status ?? "none"})`,
+            ...stderrTail.map((line) => `  ${line}`),
+        ]);
+    }
+    const verdict = JSON.parse(reportLine.slice(VERIFY_REPORT_PREFIX.length));
+    if ("failure" in verdict)
+        return result(false, written, [...lines, `✗ the fresh process that verifies ${options.file} never compared it: ${verdict.failure}`]);
+    if (verdict.same)
+        return result(true, written, [...lines, "✓ a fresh process digests the same signatures"]);
+    return result(false, written, [
+        ...lines,
+        `✗ a fresh process digests different signatures for ${options.file}: a schema reads the clock or a random source`,
+        ...verdict.lines.map((line) => `  ${line}`),
+    ]);
+};

package/dist/build.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Build entry point (`import ... from "lambder/build"`).
+ *
+ * What a generator script runs at build time over the app's own instance to
+ * write the signature file both sides ship. Node-only and imported by nothing
+ * else in the package, so no deployment or bundle carries it.
+ */
+export { writeApiSignatures } from "./build/writeApiSignatures.js";
+export type { LambderApiSignatureSource, LambderApiSignatureFileOptions, LambderApiSignatureFileResult, } from "./build/writeApiSignatures.js";

package/dist/build.js

@@ -0,0 +1,8 @@
+/**
+ * Build entry point (`import ... from "lambder/build"`).
+ *
+ * What a generator script runs at build time over the app's own instance to
+ * write the signature file both sides ship. Node-only and imported by nothing
+ * else in the package, so no deployment or bundle carries it.
+ */
+export { writeApiSignatures } from "./build/writeApiSignatures.js";