@classytic/arc 2.34.0 → 2.35.0

package/dist/plugins/index.mjs

@@ -1,20 +1,22 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { p as MUTATION_OPERATIONS } from "../constants-BxCoxmiN.mjs";
-import { c as getOrgId } from "../types-CoqIRrkY.mjs";
-import { n as requestContext } from "../requestContext-uYE35JxI.mjs";
-import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
-import { t as HookSystem } from "../HookSystem-DqXkMXkB.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-DoALUlOO.mjs";
-import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-CasG2A28.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-BcGmvnHh.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-C7xBqHsI.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-D7uchLjN.mjs";
-import { n as realtime_default, t as realtimePlugin } from "../realtime-G1TC6Yzc.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-BSBVCwL3.mjs";
-import { n as schedules_default, t as schedulesPlugin } from "../schedules-CAcZgia0.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-Cf0jUHsh.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-rZbyLVD-.mjs";
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS } from "../constants-BhzLXCfN.mjs";
+import { arcLog } from "../logger/index.mjs";
+import { c as getOrgId } from "../types-GY4kATJb.mjs";
+import { n as requestContext } from "../requestContext-DzOUGNdY.mjs";
+import { t as hasEvents } from "../typeGuards-B-_jqaMi.mjs";
+import { t as HookSystem } from "../HookSystem-LlPm3Anm.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-yuD1Ra53.mjs";
+import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-_Zs3R_Sb.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-cN5X9VEL.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-BbQ1nQdk.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-5LNPvL3P.mjs";
+import { n as realtime_default, t as realtimePlugin } from "../realtime-Cfl2bVjj.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-2jfmMnnV.mjs";
+import { n as schedules_default, t as schedulesPlugin } from "../schedules-BLpZLWGF.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-DUIP1XH6.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-BbTs4pwM.mjs";
 import fp from "fastify-plugin";
+import { performance as performance$1 } from "node:perf_hooks";
 //#region src/core/arcCorePlugin.ts
 const arcCorePlugin = async (fastify, opts = {}) => {
 	const { emitEvents = true, hookSystem, registry } = opts;
@@ -205,4 +207,153 @@ var gracefulShutdown_default = fp(gracefulShutdownPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, realtime_default as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, schedules_default as schedulesPlugin, schedulesPlugin as schedulesPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };
+//#region src/plugins/pressure.ts
+/**
+* Admission control — ONE place that decides "are we saturated?".
+*
+* Arc already sheds on event-loop lag (`@fastify/under-pressure`), but lag is
+* LATE: by the time the loop is behind, the work causing it is already
+* admitted. What actually saturates a backend — a drained pool, an undrained
+* queue, an outbox falling behind — is invisible to it. Rate limiting is a
+* different axis: it bounds request FREQUENCY, this bounds concurrent
+* EXPENSIVE WORK.
+*
+* Signals are REGISTERED, not enumerated, because only ELU has a source arc
+* can read today — no kit exposes pool stats, no queue exposes depth. Arc owns
+* the DECISION; signals come from whoever can produce them.
+*
+* `read()` returns SATURATION in [0,1]. Each signal normalises itself: 90% of
+* a pool is nearly fatal, 90% ELU is merely busy, and only the signal's author
+* knows which.
+*
+* @example
+* ```typescript
+* await app.register(pressurePlugin, {
+*   signals: [{ name: 'db-pool', read: () => pool.borrowed / pool.size }],
+*   shed: true,
+* });
+* ```
+*/
+const log = arcLog("pressure");
+/**
+* Event-loop utilisation as saturation — already a [0,1] ratio, and measured
+* ACROSS the interval rather than instantaneously: one lag reading is a spike,
+* utilisation over a second is load.
+*/
+function eluSignal() {
+	let previous = performance$1.eventLoopUtilization();
+	return {
+		name: "event-loop",
+		read() {
+			const current = performance$1.eventLoopUtilization();
+			const delta = performance$1.eventLoopUtilization(current, previous);
+			previous = current;
+			return delta.utilization;
+		}
+	};
+}
+const clamp = (n) => Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+const pressurePlugin = async (fastify, options) => {
+	const degradedAt = options.thresholds?.degraded ?? .8;
+	const saturatedAt = options.thresholds?.saturated ?? .95;
+	if (degradedAt > saturatedAt) throw new Error(`pressurePlugin: thresholds.degraded (${degradedAt}) is above thresholds.saturated (${saturatedAt}) — 'saturated' would be unreachable and the app would never shed.`);
+	const signals = [...options.eventLoopUtilization === false ? [] : [eluSignal()], ...options.signals ?? []];
+	/** Signals that threw. Logged once each — a broken reader must not spam. */
+	const broken = /* @__PURE__ */ new Set();
+	let snapshot = {
+		state: "ok",
+		worst: void 0,
+		signals: {}
+	};
+	async function sample() {
+		const values = {};
+		let worst;
+		for (const signal of signals) {
+			let value = 0;
+			try {
+				value = clamp(await signal.read());
+				broken.delete(signal.name);
+			} catch (error) {
+				if (!broken.has(signal.name)) {
+					broken.add(signal.name);
+					log.warn("pressure signal failed to read; treating as 0", {
+						signal: signal.name,
+						error
+					});
+				}
+			}
+			values[signal.name] = value;
+			if (!worst || value > worst.value) worst = {
+				name: signal.name,
+				value
+			};
+		}
+		const peak = worst?.value ?? 0;
+		const next = peak >= saturatedAt ? "saturated" : peak >= degradedAt ? "degraded" : "ok";
+		const previous = snapshot.state;
+		snapshot = {
+			state: next,
+			worst,
+			signals: values
+		};
+		if (next !== previous) {
+			log.info("pressure state changed", {
+				from: previous,
+				to: next,
+				worst
+			});
+			options.onStateChange?.(next, snapshot);
+		}
+	}
+	const timer = setInterval(() => {
+		sample();
+	}, options.intervalMs ?? 1e3);
+	timer.unref?.();
+	fastify.addHook("onClose", async () => clearInterval(timer));
+	fastify.decorate("pressure", {
+		state: () => snapshot.state,
+		snapshot: () => snapshot,
+		register: (signal) => {
+			signals.push(signal);
+		},
+		shouldShed: () => snapshot.state === "saturated",
+		readinessCheck: (checkOptions) => ({
+			name: checkOptions?.name ?? "pressure",
+			critical: checkOptions?.critical ?? true,
+			check: () => snapshot.state !== "saturated"
+		})
+	});
+	if (options.shed) {
+		const shedConfig = options.shed === true ? {} : options.shed;
+		const statusCode = shedConfig.statusCode ?? 503;
+		const retryAfter = shedConfig.retryAfterSeconds ?? 1;
+		const exempt = [
+			"/_health",
+			"/health",
+			...shedConfig.exclude ?? []
+		];
+		fastify.addHook("onRequest", async (request, reply) => {
+			if (snapshot.state !== "saturated") return;
+			const url = request.url;
+			if (exempt.some((prefix) => url.startsWith(prefix))) return;
+			reply.header("Retry-After", String(retryAfter));
+			return reply.code(statusCode).send({
+				code: "arc.unavailable",
+				message: "Server is at capacity — retry shortly.",
+				status: statusCode
+			});
+		});
+	}
+	await sample();
+};
+/**
+* `fp()`-wrapped so `fastify.pressure` is visible to the whole app rather than
+* trapped in this plugin's encapsulation context — the named export above is
+* the raw plugin, matching every other arc plugin entry.
+*/
+var pressure_default = fp(pressurePlugin, {
+	name: "arc-pressure",
+	fastify: "5.x"
+});
+//#endregion
+export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, pressure_default as pressurePlugin, pressurePlugin as pressurePluginFn, realtime_default as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, schedules_default as schedulesPlugin, schedulesPlugin as schedulesPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/response-cache.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
+import { t as hasEvents } from "../typeGuards-B-_jqaMi.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
 import { createRequire } from "node:module";
 import fp from "fastify-plugin";
 //#region src/plugins/tracing.ts
@@ -59,7 +59,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.34.0";
+	const resolvedVersion = serviceVersion ?? "2.35.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-B7xf8qZF.mjs → pluralize-DGAQQKL8.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
 //#region src/utils/pluralize.ts
 /**
 * Lightweight English pluralization for the Arc CLI.

package/dist/{preloadResources-g07ldtzh.d.mts → preloadResources--ZtY9pe9.d.mts}

@@ -1,14 +1,14 @@
 
-import { It as Authenticator } from "./index-BcR2bFZQ.mjs";
+import { It as Authenticator } from "./index-C5K78SXo.mjs";
 import { r as CacheStore } from "./interface-BOk3YnTz.mjs";
 import { n as ElevationOptions } from "./elevation-BXCfVcNG.mjs";
 import { a as EventTransport } from "./EventTransport-BEVP50ka.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-BzqxconG.mjs";
 import { t as ErrorHandlerOptions } from "./errorHandler-DI5AN2b5.mjs";
-import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-BcTumAz_.mjs";
-import "./index-C5NnMEKF.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DSNEZWfV.mjs";
+import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-DDD5RKTu.mjs";
+import "./index-C50BUxKs.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-B47sfCJ8.mjs";
 import { g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-DEs-_hFi.mjs";
 import { r as IdempotencyStore } from "./interface-DEWNOMza.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
@@ -331,7 +331,7 @@ interface RawBodyOptions {
 //#region src/factory/types/security.d.ts
 /**
  * Security-plugin option shapes — CORS / Helmet / rate-limit config for
- * `createApp()`, including plan-aware rate limiting (2.22).
+ * `createApp()`, including plan-aware rate limiting.
  */
 type CorsOptions = Record<string, unknown> & {
   origin?: unknown;
@@ -400,43 +400,14 @@ interface RateLimitPlanConfig {
 //#endregion
 //#region src/factory/types/app-options.d.ts
 /**
- * CreateApp Options
- *
- * Configuration for creating an Arc application.
+ * Configuration for `createApp()`.
  *
  * @example
  * ```typescript
- * // Minimal setup
- * const app = await createApp({
- *   preset: 'development',
- *   auth: {
- *     type: 'jwt',
- *     jwt: { secret: process.env.JWT_SECRET },
- *   },
- * });
- *
- * // With custom authenticator
  * const app = await createApp({
  *   preset: 'production',
- *   auth: {
- *     type: 'jwt',
- *     jwt: { secret: process.env.JWT_SECRET },
- *     authenticate: async (request, { jwt }) => {
- *       // Check API key first
- *       const apiKey = request.headers['x-api-key'];
- *       if (apiKey) {
- *         const result = await apiKeyService.verify(apiKey);
- *         if (result) return { _id: result.userId, isApiKey: true };
- *       }
- *       // Then check JWT
- *       const token = request.headers.authorization?.split(' ')[1];
- *       if (token) {
- *         const decoded = jwt.verify(token);
- *         return userRepo.findById(decoded.id);
- *       }
- *       return null;
- *     },
- *   },
+ *   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+ *   resources: [productResource],
  * });
  * ```
  */
@@ -540,13 +511,20 @@ interface CreateAppOptions {
    * proxy's address; a boot warning fires when the production preset's
    * default is inherited without an explicit choice.
    *
+   * ⚠ **A hop COUNT is no longer accepted.** Fastify 5.12.1 removed `number`
+   * from this option and made hop-count trust fail closed, because it cannot
+   * validate the immediate peer — a direct client could spoof `X-Forwarded-*`
+   * simply by supplying enough hops. Name the proxies instead; arc warns at
+   * boot if a number reaches it from untyped (JavaScript) config.
+   *
    * @example
    * ```ts
-   * createApp({ preset: 'production', trustProxy: 1 });          // one LB hop
-   * createApp({ preset: 'production', trustProxy: '10.0.0.0/8' }); // VPC proxies
+   * createApp({ preset: 'production', trustProxy: 'loopback' });    // local proxy
+   * createApp({ preset: 'production', trustProxy: '10.0.0.0/8' });  // VPC proxies
+   * createApp({ preset: 'production', trustProxy: true });          // every hop trusted
    * ```
    */
-  trustProxy?: boolean | string | string[] | number;
+  trustProxy?: boolean | string | string[];
   /** Fastify plugin/onReady timeout in ms (default: 10_000). Raise for slow boot work (index materialisation, WAL replay, external warm-up). */
   pluginTimeout?: number;
   /**
@@ -559,102 +537,33 @@ interface CreateAppOptions {
    */
   requestTimeout?: number;
   /**
-   * Max time in ms to establish a connection before the socket is
-   * destroyed. Pass-through to Fastify's `connectionTimeout` (Node's
-   * `server.timeout`). Default `0` = no limit (Node's `headersTimeout`
-   * ~60s still bounds idle pre-request sockets).
+   * Connection-establishment timeout in ms (Fastify `connectionTimeout`).
+   * Default `0` = unbounded; Node's ~60s `headersTimeout` still caps idle
+   * pre-request sockets.
    */
   connectionTimeout?: number;
   /**
-   * Keep-alive idle timeout in ms (Node's `server.keepAliveTimeout`,
-   * default 72_000). MUST be longer than the idle timeout of any load
-   * balancer in front of the app (ALB default 60s) or the LB reuses
-   * sockets the server just closed → intermittent 502s.
+   * Keep-alive idle timeout in ms (default 72_000). MUST exceed the idle
+   * timeout of any LB in front (ALB default 60s), or the LB reuses sockets
+   * the server just closed — intermittent 502s.
    */
   keepAliveTimeout?: number;
   /**
-   * Maximum JSON body size in bytes. Pass-through to Fastify's
-   * server-level `bodyLimit` option; default is Fastify's 1 MiB
-   * (1_048_576 bytes). Raise for hosts shipping bulk-import / CSV ingest
-   * / JSON-RPC batch endpoints — without this, Fastify rejects oversized
-   * payloads with `FST_ERR_CTP_BODY_TOO_LARGE` (413) before any route
-   * handler runs. File uploads on `multipart` routes are governed
-   * separately by `multipart.limits.fileSize`. (2.15.1)
+   * Max JSON body in bytes. Fastify default 1 MiB; over it is a 413
+   * (`FST_ERR_CTP_BODY_TOO_LARGE`) raised BEFORE any handler runs.
+   * Multipart uploads are bounded separately by `multipart.limits.fileSize`.
    */
   bodyLimit?: number;
   /**
-   * Maximum length of a single URL path parameter (in characters).
-   *
-   * 2.16 — Fastify's default is `100`, which silently 404s modern signed-
-   * token URLs: HMAC tracking tokens (~250 chars), JWT-in-URL, OAuth state
-   * parameters, password-reset / magic-link tokens, etc. Arc's default
-   * is **400** to match the everything-is-a-signed-token reality of
-   * production apps; hosts that need longer params can raise it further
-   * (`1024` for very long JWTs).
-   *
-   * Pass-through to Fastify's `maxParamLength` constructor option — see
-   * https://fastify.dev/docs/latest/Reference/Server/#maxparamlength.
-   *
-   * @example
-   * ```ts
-   * // App expects long HMAC tokens in the URL path
-   * createApp({ preset: 'production', maxParamLength: 1024 });
-   *
-   * // Constrain tighter than arc's default for audit reasons
-   * createApp({ preset: 'production', maxParamLength: 256 });
-   * ```
+   * Max characters in one URL path param. Arc defaults to 400; Fastify's own
+   * 100 silently 404s signed-token URLs (HMAC ~250 chars, JWT, OAuth state).
+   * Raise to ~1024 for long JWTs.
    */
   maxParamLength?: number;
   /**
-   * Auth configuration
-   *
-   * Set to false to disable authentication entirely.
-   * Each auth strategy requires a `type` discriminant field.
-   *
-   * @example
-   * ```typescript
-   * // Disable auth
-   * auth: false,
-   *
-   * // Arc JWT
-   * auth: {
-   *   type: 'jwt',
-   *   jwt: { secret: process.env.JWT_SECRET },
-   * },
-   *
-   * // Arc JWT + custom authenticator
-   * auth: {
-   *   type: 'jwt',
-   *   jwt: { secret: process.env.JWT_SECRET },
-   *   authenticate: async (request, { jwt }) => {
-   *     const token = request.headers.authorization?.split(' ')[1];
-   *     if (!token) return null;
-   *     const decoded = jwt.verify(token);
-   *     return userRepo.findById(decoded.id);
-   *   },
-   * },
-   *
-   * // Better Auth adapter
-   * auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth: myBetterAuth }) },
-   *
-   * // Custom auth plugin
-   * auth: {
-   *   type: 'custom',
-   *   plugin: async (fastify) => {
-   *     fastify.decorate('authenticate', async (req, reply) => { ... });
-   *   },
-   * },
-   *
-   * // Custom authenticator function
-   * auth: {
-   *   type: 'authenticator',
-   *   authenticate: async (request, reply) => {
-   *     const session = await validateSession(request);
-   *     if (!session) reply.code(401).send({ error: 'Unauthorized' });
-   *     request.user = session.user;
-   *   },
-   * },
-   * ```
+   * Auth configuration, or `false` to disable entirely. Each strategy is a
+   * discriminated union on `type` (`'jwt'` | `'better-auth'` | custom); see
+   * [[auth]] for the strategy matrix and `authenticate` override.
    */
   auth?: AuthOption;
   /**
@@ -886,162 +795,37 @@ interface CreateAppOptions {
    */
   replyHelpers?: boolean;
   /**
-   * Serialize `bigint` values in JSON responses.
-   *
-   * `JSON.stringify` throws on `bigint` by default. This option installs a
-   * `preSerialization` hook that converts them on the way out:
-   *
-   * - `false` (default) — no conversion. JSON serialization throws if a
-   *   `bigint` reaches the wire. Safest when no codepath produces bigints.
-   * - `'string'` — **recommended for IDs / money / counters / ledgers.**
-   *   Converts every `bigint` to a decimal string. Lossless: every digit
-   *   survives the wire. Clients parse with `BigInt(value)` to reconstitute.
-   * - `'number'` — converts every `bigint` to `Number(value)`.
-   *   **Lossy above 2^53 - 1 (`Number.MAX_SAFE_INTEGER` = 9007199254740991).**
-   *   Use ONLY when you've audited the value range — e.g. small enums,
-   *   bounded counters that physically can't exceed the safe range. For
-   *   anything that could be an ID, monetary amount, or unbounded counter,
-   *   `Number()` corruption silently rounds digits and there is no
-   *   recovery. arc emits a one-shot startup warning when you opt into
-   *   this mode.
-   * - `true` — back-compat alias for `'number'`. Will be removed in a
-   *   future major. Migrate to `'string'` (lossless) or explicit
-   *   `'number'` (acknowledges the precision risk).
-   *
-   * Default: `false` (opt-in — most apps don't use bigint).
+   * Serialize `bigint` in JSON responses — `JSON.stringify` throws on it.
    *
-   * @example
-   * ```typescript
-   * // Lossless — recommended path
-   * const app = await createApp({
-   *   serializeBigInt: 'string',
-   * });
-   * // { totalSatoshis: "9007199254740999" }
-   *
-   * // Lossy — only when value range is bounded
-   * const app = await createApp({
-   *   serializeBigInt: 'number',
-   * });
-   * // { totalSatoshis: 9007199254740999 }  // precision lost above MAX_SAFE_INTEGER
-   * });
-   * ```
+   * - `false` (default) — no conversion; a bigint reaching the wire throws.
+   * - `'string'` — lossless decimal string. The choice for IDs, money,
+   *   counters, ledgers. Clients reconstitute with `BigInt(value)`.
+   * - `'number'` — LOSSY above `Number.MAX_SAFE_INTEGER` (2^53-1). Only for
+   *   an audited, bounded range.
    */
   serializeBigInt?: boolean | "number" | "string";
   /**
-   * Domain modules — compose whole domains into the app, one entry each.
-   *
-   * Where a `resources` entry is a single route group, a module is a self-
-   * contained domain package's full contribution (engine init + resources +
-   * post-wiring) bundled as one `ArcModule`. A package exports
-   * `createXModule(deps): ArcModule`; the host lists it here instead of hand-
-   * threading the package's pieces across `bootstrap` / `resources` /
-   * `afterResources`.
-   *
-   * Modules are pure sugar over the existing lifecycle — each expands into the
-   * SAME phases, in `dependsOn` order, running BEFORE the app-level entry in
-   * every phase:
-   * ```
-   * app plugins()  → modules[].plugins         (infra registration)
-   * modules[].bootstrap      → options.bootstrap
-   * modules[].resources      → options.resources / resourceDir  (see note ↓)
-   * modules[].afterResources → options.afterResources
-   * modules[].onClose (REVERSE order) → options.onClose   (one hook; see below)
-   * ```
-   * RESOURCES — two orderings, both intentional: app `resources`/`resourceDir`
-   * RESOLVE first (semantics untouched), but module resources REGISTER first
-   * (prepended, so their routes mount ahead of app resources). Teardown runs
-   * module `onClose` (reverse composition order) then app `onClose` in a single
-   * close hook, so module teardown (flush outboxes, drain queues, close a
-   * module-owned connection) sees live shared infra — the app/plugin
-   * connections close last. Module resources flow through arc's normal
-   * registration (prefix, dedup, docs, audit) — they are not special-cased.
-   *
-   * Entries may be eager modules, promises, or **thunks of dynamic imports**
-   * (the `next/dynamic` idea, backend-shaped) — thunks resolve once at boot,
-   * so region/tier-gated packs are only imported when selected:
-   *
-   * @example
-   * ```ts
-   * const taxPack = region === 'BD'
-   *   ? () => import('@classytic/bd-tax/module').then((m) => m.createBdTaxModule(deps))
-   *   : () => import('@classytic/us-tax/module').then((m) => m.createUsTaxModule(deps));
-   *
-   * const app = await createApp({
-   *   resourcePrefix: '/api/v1',
-   *   modules: [accountingModule({ permissions }), taxPack],
-   *   resources: [healthResource], // app-local resources still compose alongside
-   * });
-   * ```
+   * Domain modules — one entry per self-contained domain package.
    *
-   * See `wiki/modules.md` for the full design (authoring convention, events/
-   * outbox integration, microservices path).
+   * A `resources` entry is a route group; an `ArcModule` is a package's whole
+   * contribution (engine init + resources + post-wiring), so the host stops
+   * hand-threading pieces across `bootstrap` / `resources` / `afterResources`.
+   * Modules expand into the SAME lifecycle phases in `dependsOn` order,
+   * always before the app-level entry for that phase. See [[modules]].
    */
   modules?: ReadonlyArray<ArcModuleInput>;
   /**
-   * Resources to register automatically. Accepts two shapes:
+   * Resources to register. An ARRAY is resolved at module import, so every
+   * adapter must be constructible synchronously. A FACTORY (sync or async,
+   * receiving the Fastify instance) is resolved after `bootstrap[]` and before
+   * routes are wired — the answer when an adapter depends on an engine that
+   * boots asynchronously, since `defineResource()` then runs with that engine
+   * already live. Boot order lives in CLAUDE.md; do not restate it here.
    *
-   *   1. **Array** — each resource's `.toPlugin()` is called and registered.
-   *      Defined at module-import time, so the resource's adapter must be
-   *      constructible without any async state.
-   *
-   *   2. **Factory function** (sync or async) — called AFTER `bootstrap[]`
-   *      but BEFORE routes are wired. Use this when a resource's adapter
-   *      depends on an engine / singleton that boots asynchronously
-   *      (e.g. `await ensureCatalogEngine()` / `await createFlowEngine()`).
-   *      The factory receives the Fastify instance for symmetry with
-   *      `plugins` and `bootstrap`.
-   *
-   * Arc's lifecycle contract:
-   * ```
-   * 1. Arc core (security, auth, events)
-   * 2. plugins()            ← infra (DB, SSE, data)
-   * 3. bootstrap[]          ← domain init (engines, singletons)
-   * 4. resources resolution ← (factory form: call it here)
-   * 5. resources registered ← plugins mounted on Fastify
-   * 6. afterResources()     ← post-registration wiring
-   * ```
-   *
-   * The factory form is the canonical answer to "my repository lives in an
-   * engine that boots asynchronously." Before this shape existed, hosts had
-   * to write per-resource lazy-bridge adapters that awaited the engine on
-   * every CRUD call — pure boilerplate. With a factory, `defineResource(...)`
-   * runs with the engine already live, so `createMongooseAdapter(engine.models.X, engine.repositories.X)`
-   * works directly.
-   *
-   * @example Static array (most resources)
-   * ```ts
-   * const app = await createApp({
-   *   resources: [productResource, orderResource, userResource],
-   *   auth: { type: 'jwt', jwt: { secret: 'xxx' } },
-   * });
-   * ```
-   *
-   * @example Factory with async-booted engine
-   * ```ts
-   * import { createApp, defineResource } from '@classytic/arc';
-   * import { createMongooseAdapter } from '@classytic/mongokit/adapter';
-   *
-   * const app = await createApp({
-   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
-   *   resources: async () => {
-   *     const cat = await ensureCatalogEngine();
-   *     return [
-   *       defineResource({
-   *         name: 'product',
-   *         adapter: createMongooseAdapter(cat.models.Product, cat.repositories.product),
-   *         // ...
-   *       }),
-   *     ];
-   *   },
-   * });
-   * ```
-   *
-   * @example Factory delegating to auto-discovery
+   * @example
    * ```ts
-   * const app = await createApp({
-   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
-   *   resources: async () => loadResources(import.meta.url),
-   * });
+   * resources: [productResource]                       // static
+   * resources: async () => [defineResource({ ... })]   // engine-dependent
    * ```
    */
   resources?: ReadonlyArray<ResourceLike> | ((fastify: FastifyInstance) => ReadonlyArray<ResourceLike> | Promise<ReadonlyArray<ResourceLike>>);