@classytic/arc 2.20.0 → 2.22.0

package/dist/health-ScyjIVo5.mjs

@@ -0,0 +1,202 @@
+import fp from "fastify-plugin";
+//#region src/plugins/health.ts
+function createHttpMetrics() {
+	return {
+		requestsTotal: {},
+		requestDurations: [],
+		_ringIndex: 0,
+		startTime: Date.now()
+	};
+}
+const healthPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
+	const httpMetrics = createHttpMetrics();
+	fastify.get(prefix, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe (alias for /live)",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => ({
+		status: "ok",
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		...version ? { version } : {}
+	}));
+	fastify.get(`${prefix}/live`, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => {
+		return {
+			status: "ok",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...version ? { version } : {}
+		};
+	});
+	fastify.get(`${prefix}/ready`, { schema: {
+		tags: ["Health"],
+		summary: "Readiness probe",
+		description: "Returns 200 if all dependencies are healthy",
+		response: {
+			200: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["ready", "not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								name: { type: "string" },
+								healthy: { type: "boolean" },
+								duration: { type: "number" },
+								error: { type: "string" }
+							}
+						}
+					}
+				}
+			},
+			503: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: { type: "array" }
+				}
+			}
+		}
+	} }, async (_, reply) => {
+		const results = await runChecks(checks);
+		const criticalFailed = results.some((r) => !r.healthy && (checks.find((c) => c.name === r.name)?.critical ?? true));
+		const response = {
+			status: criticalFailed ? "not_ready" : "ready",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			checks: results
+		};
+		if (criticalFailed) reply.code(503);
+		return response;
+	});
+	if (metrics) fastify.get(`${prefix}/metrics`, async (_, reply) => {
+		reply.type("text/plain; charset=utf-8");
+		if (metricsCollector) return await metricsCollector();
+		const uptime = process.uptime();
+		const memory = process.memoryUsage();
+		const cpu = process.cpuUsage();
+		const lines = [
+			"# HELP process_uptime_seconds Process uptime in seconds",
+			"# TYPE process_uptime_seconds gauge",
+			`process_uptime_seconds ${uptime.toFixed(2)}`,
+			"",
+			"# HELP process_memory_heap_bytes Heap memory usage in bytes",
+			"# TYPE process_memory_heap_bytes gauge",
+			`process_memory_heap_bytes{type="used"} ${memory.heapUsed}`,
+			`process_memory_heap_bytes{type="total"} ${memory.heapTotal}`,
+			"",
+			"# HELP process_memory_rss_bytes RSS memory in bytes",
+			"# TYPE process_memory_rss_bytes gauge",
+			`process_memory_rss_bytes ${memory.rss}`,
+			"",
+			"# HELP process_memory_external_bytes External memory in bytes",
+			"# TYPE process_memory_external_bytes gauge",
+			`process_memory_external_bytes ${memory.external}`,
+			"",
+			"# HELP process_cpu_user_microseconds User CPU time in microseconds",
+			"# TYPE process_cpu_user_microseconds counter",
+			`process_cpu_user_microseconds ${cpu.user}`,
+			"",
+			"# HELP process_cpu_system_microseconds System CPU time in microseconds",
+			"# TYPE process_cpu_system_microseconds counter",
+			`process_cpu_system_microseconds ${cpu.system}`,
+			""
+		];
+		if (collectHttpMetrics && Object.keys(httpMetrics.requestsTotal).length > 0) {
+			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
+			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
+			lines.push("");
+			if (httpMetrics.requestDurations.length > 0) {
+				const sorted = [...httpMetrics.requestDurations].sort((a, b) => a - b);
+				const p50 = sorted[Math.floor(sorted.length * .5)] || 0;
+				const p95 = sorted[Math.floor(sorted.length * .95)] || 0;
+				const p99 = sorted[Math.floor(sorted.length * .99)] || 0;
+				const sum = sorted.reduce((a, b) => a + b, 0);
+				lines.push("# HELP http_request_duration_milliseconds HTTP request duration", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${sum.toFixed(2)}`, `http_request_duration_milliseconds_count ${sorted.length}`, "");
+			}
+		}
+		return lines.join("\n");
+	});
+	if (collectHttpMetrics) fastify.addHook("onResponse", async (_request, reply) => {
+		const duration = reply.elapsedTime;
+		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
+		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
+		if (httpMetrics.requestDurations.length < 1e4) httpMetrics.requestDurations.push(duration);
+		else httpMetrics.requestDurations[httpMetrics._ringIndex % 1e4] = duration;
+		httpMetrics._ringIndex = httpMetrics._ringIndex + 1;
+	});
+	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
+};
+/**
+* Run all health checks with timeout
+*/
+async function runChecks(checks) {
+	const results = [];
+	for (const check of checks) {
+		const start = Date.now();
+		const timeout = check.timeout ?? 5e3;
+		let timer;
+		try {
+			const checkPromise = Promise.resolve(check.check());
+			const timeoutPromise = new Promise((_, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Health check timeout")), timeout);
+			});
+			const healthy = await Promise.race([checkPromise, timeoutPromise]);
+			results.push({
+				name: check.name,
+				healthy: Boolean(healthy),
+				duration: Date.now() - start
+			});
+		} catch (err) {
+			results.push({
+				name: check.name,
+				healthy: false,
+				duration: Date.now() - start,
+				error: err.message
+			});
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+	return results;
+}
+var health_default = fp(healthPlugin, {
+	name: "arc-health",
+	fastify: "5.x"
+});
+//#endregion
+export { health_default as n, healthPlugin as t };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-_--GyzcO.mjs";
+import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-DbtgCOCj.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,8 +1,7 @@
 import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-Uk8ONJv7.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-C3W0qbz8.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-UDtLaNj6.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
-
 //#region src/idempotency/idempotencyPlugin.d.ts
 interface IdempotencyPluginOptions {
   /** Enable idempotency (default: false) */
@@ -60,7 +59,9 @@ declare module "fastify" {
   interface FastifyInstance {
     /** Idempotency utilities */
     idempotency: {
-      /** Manually invalidate an idempotency key */invalidate: (key: string) => Promise<void>; /** Check if a key has a cached response */
+      /** Manually invalidate an idempotency key */
+      invalidate: (key: string) => Promise<void>;
+      /** Check if a key has a cached response */
       has: (key: string) => Promise<boolean>;
       /**
        * Route-level preHandler for idempotency check + lock.

package/dist/idempotency/index.mjs

@@ -287,12 +287,14 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		});
 		fastify.decorateRequest("idempotencyKey", void 0);
 		fastify.decorateRequest("idempotencyReplayed", false);
+		fastify.decorateRequest("_idempotencyFullKey", void 0);
 		fastify.log?.debug?.("Idempotency plugin disabled");
 		return;
 	}
 	const methodSet = new Set(methods.map((m) => m.toUpperCase()));
 	fastify.decorateRequest("idempotencyKey", void 0);
 	fastify.decorateRequest("idempotencyReplayed", false);
+	fastify.decorateRequest("_idempotencyFullKey", void 0);
 	/**
 	* Check if this request should use idempotency
 	*/

package/dist/idempotency/redis.d.mts

@@ -1,2 +1,2 @@
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-C3W0qbz8.mjs";
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-UDtLaNj6.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/{types-BHMKlMBU.d.mts → index-BEu4wjbL.d.mts}

@@ -1,16 +1,15 @@
-import { Ut as Authenticator } from "./index-_--GyzcO.mjs";
+import { Ut as Authenticator } from "./index-DbtgCOCj.mjs";
 import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
-import { n as ElevationOptions } from "./elevation-xGUBq6p_.mjs";
-import { a as EventTransport } from "./EventTransport-IEn7Tn-Q.mjs";
+import { n as ElevationOptions } from "./elevation-C9s5hFP_.mjs";
+import { a as EventTransport } from "./EventTransport-QmY7A258.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-xzFyKAjT.mjs";
-import { l as ResourceLike, n as ArcModuleInput } from "./module-JYH9V0I8.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DbBFd3x_.mjs";
-import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-D_eBCfNr.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-BtUUDPEa.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-CfYWq-Ak.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-C6yv4ZTW.mjs";
+import { l as ResourceLike, n as ArcModuleInput } from "./module-B4u10iOJ.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-A6EbthXR.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DLwklPlG.mjs";
 import { r as IdempotencyStore } from "./interface-Uk8ONJv7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
-
 //#region src/testing/preloadResources.d.ts
 /** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
 type EagerGlobResult = Record<string, unknown>;
@@ -34,30 +33,7 @@ declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
  */
 declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
 //#endregion
-//#region src/factory/types.d.ts
-type CorsOptions = Record<string, unknown> & {
-  origin?: unknown;
-  credentials?: boolean;
-  methods?: string[];
-  allowedHeaders?: string[];
-};
-type HelmetOptions = Record<string, unknown>;
-type RateLimitOpts = Record<string, unknown> & {
-  max?: number;
-  timeWindow?: string | number;
-  /**
-   * Path patterns to exempt from rate limiting. Supports exact match
-   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
-   *
-   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
-   * function. When combined with a user-supplied `allowList`, both
-   * are OR-ed together (path OR ip/custom match skips the limit).
-   *
-   * Use this for endpoints that are hit frequently but independently
-   * of user traffic — session heartbeat, webhooks, health probes.
-   */
-  skipPaths?: string[];
-};
+//#region src/factory/types/auth.d.ts
 /**
  * Arc's built-in JWT auth
  *
@@ -95,11 +71,17 @@ interface JwtAuthOption {
    * If provided, jwt utilities are available in authenticator context
    */
   jwt?: {
-    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
-    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
-    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
-    refreshExpiresIn?: string; /** Additional @fastify/jwt sign options */
-    sign?: Record<string, unknown>; /** Additional @fastify/jwt verify options */
+    /** JWT secret (required for JWT features) */
+    secret: string;
+    /** Access token expiry (default: '15m') */
+    expiresIn?: string;
+    /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string;
+    /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string;
+    /** Additional @fastify/jwt sign options */
+    sign?: Record<string, unknown>;
+    /** Additional @fastify/jwt verify options */
     verify?: Record<string, unknown>;
   };
   /**
@@ -156,13 +138,29 @@ interface JwtAuthOption {
  * });
  * ```
  */
+/** The shape `createBetterAuthAdapter()` returns. */
+interface BetterAuthAdapterResult {
+  plugin: FastifyPluginAsync;
+  openapi?: ExternalOpenApiPaths;
+}
 interface BetterAuthOption {
   type: "betterAuth";
-  /** Better Auth adapter — pass the result of createBetterAuthAdapter() */
-  betterAuth: {
-    plugin: FastifyPluginAsync;
-    openapi?: ExternalOpenApiPaths;
-  };
+  /**
+   * Better Auth adapter — the result of `createBetterAuthAdapter()`, or a
+   * sync/async THUNK returning it (2.22). The thunk resolves during auth
+   * registration — AFTER `beforeBoot` — for adapters whose construction
+   * needs a live DB (Better Auth's `mongodbAdapter(mongoose.connection
+   * .getClient().db())` requires an OPEN connection, so an eager value
+   * forces hosts back into connect-before-createApp ordering dances):
+   *
+   * ```typescript
+   * createApp({
+   *   beforeBoot: () => connectDatabase(),
+   *   auth: { type: 'betterAuth', betterAuth: () => createBetterAuthAdapter({ auth: getAuth() }) },
+   * });
+   * ```
+   */
+  betterAuth: BetterAuthAdapterResult | (() => BetterAuthAdapterResult | Promise<BetterAuthAdapterResult>);
 }
 /**
  * Custom auth plugin — full control over authentication setup
@@ -229,6 +227,112 @@ interface CustomAuthenticatorOption {
  * - `CustomAuthenticatorOption` — A bare authenticate function (`type: 'authenticator'`)
  */
 type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOption | CustomAuthenticatorOption;
+//#endregion
+//#region src/factory/types/plugin-options.d.ts
+/**
+ * Plugin-specific option shapes for `createApp()` — under-pressure,
+ * multipart, and raw-body plugin configuration.
+ */
+interface UnderPressureOptions {
+  /** Expose `/_status` route for health checks (default: false) */
+  exposeStatusRoute?: boolean;
+  /** Event loop lag threshold in ms — requests rejected above this (default: 1000) */
+  maxEventLoopDelay?: number;
+  /** V8 heap usage threshold in bytes — requests rejected above this */
+  maxHeapUsedBytes?: number;
+  /** RSS memory threshold in bytes — requests rejected above this */
+  maxRssBytes?: number;
+}
+interface MultipartOptions {
+  limits?: {
+    /** Max file size in bytes (default: Fastify default ~1MB) */
+    fileSize?: number;
+    /** Max number of files per request */
+    files?: number;
+  };
+}
+interface RawBodyOptions {
+  /** Body field name to store raw body on (default: 'rawBody') */
+  field?: string;
+  /** Apply to all routes globally (default: false) */
+  global?: boolean;
+  /** Encoding for raw body string (default: 'utf8') */
+  encoding?: string;
+  /** Parse raw body before other parsers (default: false) */
+  runFirst?: boolean;
+}
+//#endregion
+//#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).
+ */
+type CorsOptions = Record<string, unknown> & {
+  origin?: unknown;
+  credentials?: boolean;
+  methods?: string[];
+  allowedHeaders?: string[];
+};
+type HelmetOptions = Record<string, unknown>;
+type RateLimitOpts = Record<string, unknown> & {
+  max?: number;
+  timeWindow?: string | number;
+  /**
+   * Path patterns to exempt from rate limiting. Supports exact match
+   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
+   *
+   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
+   * function. When combined with a user-supplied `allowList`, both
+   * are OR-ed together (path OR ip/custom match skips the limit).
+   *
+   * Use this for endpoints that are hit frequently but independently
+   * of user traffic — session heartbeat, webhooks, health probes.
+   */
+  skipPaths?: string[];
+  /**
+   * Plan-aware limits (2.22) — resolve the caller's plan per request and
+   * apply that plan's ceiling instead of the global `max`:
+   *
+   * ```typescript
+   * rateLimit: {
+   *   timeWindow: '1 minute',
+   *   plan: {
+   *     resolve: (req) => lookupPlan(req),            // 'free' | 'pro' | ...
+   *     limits: { free: { max: 60 }, pro: { max: 1000 }, enterprise: false },
+   *     default: 'free',
+   *   },
+   * }
+   * ```
+   *
+   * `false` = effectively unlimited. When `plan` is set and no
+   * `keyGenerator` is supplied, arc defaults to the tenant key chain
+   * (org → user → client → IP) so buckets follow actors, not addresses.
+   *
+   * Timing caveat: the limiter runs before route-level auth, so
+   * `req.scope` may be unresolved for token-authenticated calls —
+   * `resolve` receives the RAW request and may need to derive the plan
+   * from its own header/token/session lookup. Same caveat as
+   * `createTenantKeyGenerator`'s IP fallback (documented there).
+   */
+  plan?: RateLimitPlanConfig;
+};
+/** Plan-aware rate limiting (2.22) — see `rateLimit.plan` on CreateAppOptions. */
+interface RateLimitPlanConfig {
+  /**
+   * Name the caller's plan from the raw request. Return `undefined` to
+   * fall back to `default`. Sync or async; a throwing resolver also
+   * falls back (limits must fail-safe, not fail-open to unlimited).
+   */
+  resolve: (req: import("fastify").FastifyRequest) => string | undefined | Promise<string | undefined>;
+  /** Per-plan ceilings within the shared `timeWindow`. `false` = effectively unlimited. */
+  limits: Record<string, {
+    max: number;
+  } | false>;
+  /** Plan used when `resolve` returns undefined/unknown or throws. Default: fall back to the global `max`. */
+  default?: string;
+}
+//#endregion
+//#region src/factory/types/app-options.d.ts
 /**
  * CreateApp Options
  *
@@ -271,8 +375,18 @@ type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOpt
  * ```
  */
 interface CreateAppOptions {
-  /** Environment preset: 'production', 'development', 'testing', or 'edge' */
-  preset?: "production" | "development" | "testing" | "edge";
+  /** Environment preset: 'production', 'development', 'testing', 'edge', or 'worker' */
+  preset?: "production" | "development" | "testing" | "edge" | "worker";
+  /**
+   * Route-mounting switch (2.23) — the worker-role primitive. `false`
+   * registers every resource's shared runtime state (registry metadata +
+   * adapter, hooks, cache-invalidation rules) WITHOUT mounting any routes,
+   * so headless processes keep tenant-purge cascade, per-resource audit,
+   * and events metadata intact. Set by `preset: 'worker'` /
+   * `createWorker()`; hosts composing a custom worker shape may set it
+   * directly. Default: true (routes mount).
+   */
+  mountRoutes?: boolean;
   /**
    * Runtime profile for store backends.
    * - 'memory' (default): Uses in-memory stores. Suitable for single-instance deployments.
@@ -289,9 +403,13 @@ interface CreateAppOptions {
    * not memory-backed. Provide Redis or other durable adapters.
    */
   stores?: {
-    /** Event transport (e.g., RedisEventTransport) */events?: EventTransport; /** Cache store (e.g., RedisCacheStore) */
-    cache?: CacheStore; /** Idempotency store (e.g., RedisIdempotencyStore) */
-    idempotency?: IdempotencyStore; /** QueryCache store (e.g., RedisCacheStore). Default: MemoryCacheStore. */
+    /** Event transport (e.g., RedisEventTransport) */
+    events?: EventTransport;
+    /** Cache store (e.g., RedisCacheStore) */
+    cache?: CacheStore;
+    /** Idempotency store (e.g., RedisIdempotencyStore) */
+    idempotency?: IdempotencyStore;
+    /** QueryCache store (e.g., RedisCacheStore). Default: MemoryCacheStore. */
     queryCache?: CacheStore;
   };
   /** Fastify logger configuration */
@@ -315,10 +433,50 @@ interface CreateAppOptions {
    * ```
    */
   debug?: boolean | string;
-  /** Trust proxy headers (X-Forwarded-For, etc.) */
-  trustProxy?: boolean;
+  /**
+   * Trust proxy headers (X-Forwarded-For, etc.). Pass-through to Fastify's
+   * `trustProxy` server option — all its forms are supported, not just the
+   * boolean:
+   *
+   * - `true` — trust ALL proxies (only safe when the app is never directly
+   *   reachable; a spoofed `X-Forwarded-For` otherwise forges `request.ip`,
+   *   which feeds rate-limit keys and audit logs)
+   * - `1` — trust exactly one hop (typical single LB / reverse proxy)
+   * - `'10.0.0.0/8'` / `['10.0.0.0/8', '172.16.0.0/12']` — trust only these
+   *   CIDR ranges
+   *
+   * @example
+   * ```ts
+   * createApp({ preset: 'production', trustProxy: 1 });          // one LB hop
+   * createApp({ preset: 'production', trustProxy: '10.0.0.0/8' }); // VPC proxies
+   * ```
+   */
+  trustProxy?: boolean | string | string[] | number;
   /** Fastify plugin/onReady timeout in ms (default: 10_000). Raise for slow boot work (index materialisation, WAL replay, external warm-up). */
   pluginTimeout?: number;
+  /**
+   * Max time in ms the server waits to RECEIVE an entire request
+   * (headers + body). Pass-through to Fastify's `requestTimeout` (Node's
+   * `server.requestTimeout`). Default `0` defers to Node's own 300s bound
+   * — slow-loris requests are already cut off there, so arc doesn't
+   * override; tighten (e.g. `30_000`) for APIs that never accept slow
+   * uploads. Response duration (SSE, streaming) is NOT affected.
+   */
+  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).
+   */
+  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.
+   */
+  keepAliveTimeout?: number;
   /**
    * Maximum JSON body size in bytes. Pass-through to Fastify's
    * server-level `bodyLimit` option; default is Fastify's 1 MiB
@@ -442,7 +600,8 @@ interface CreateAppOptions {
   rawBody?: RawBodyOptions | false;
   /** Enable Arc plugins (requestId, health, gracefulShutdown, events, caching, sse) */
   arcPlugins?: {
-    /** Request ID tracking (default: true) */requestId?: boolean;
+    /** Request ID tracking (default: true) */
+    requestId?: boolean;
     /**
      * Health endpoints (default: true).
      *
@@ -469,8 +628,10 @@ interface CreateAppOptions {
      * }
      * ```
      */
-    health?: boolean | HealthOptions; /** Graceful shutdown handling (default: true) */
-    gracefulShutdown?: boolean; /** Emit events for CRUD operations (default: true) */
+    health?: boolean | HealthOptions;
+    /** Graceful shutdown handling (default: true) */
+    gracefulShutdown?: boolean;
+    /** Emit events for CRUD operations (default: true) */
     emitEvents?: boolean;
     /**
      * Event plugin configuration. Default: true (enabled with MemoryEventTransport).
@@ -851,6 +1012,32 @@ interface CreateAppOptions {
    * @default false
    */
   strictResources?: boolean;
+  /**
+   * Pre-boot hook — awaited BEFORE arc does anything else: before the
+   * Fastify instance exists, before module thunks resolve, before resource
+   * discovery imports a single host file.
+   *
+   * The canonical slot for the DB connection and anything that
+   * module-EVAL-time code depends on. Engines that register Mongoose models
+   * at import time (top-level `createXEngine(...)`) trigger eager
+   * `createIndex()` calls from schema plugins — if the connection isn't
+   * open yet those buffer and die with `buffering timed out`. Hosts used to
+   * hand-orchestrate this with `await connectDatabase()` + dynamic
+   * `await import(...)` tricks before calling `createApp`; with `beforeBoot`
+   * the ordering is arc's contract instead:
+   *
+   * ```ts
+   * const app = await createApp({
+   *   beforeBoot: async () => { await connectDatabase(); },
+   *   modules: [() => import('#modules/accounting.js')], // thunks resolve AFTER beforeBoot
+   *   resources: async () => [...],
+   * });
+   * ```
+   *
+   * Runs after option validation (config bugs fail fast without touching
+   * the DB). Cleanup stays host-owned — pair with `onClose`.
+   */
+  beforeBoot?: () => void | Promise<void>;
   /**
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.
@@ -895,31 +1082,5 @@ interface CreateAppOptions {
   /** Hook called when the app is shutting down */
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }
-interface UnderPressureOptions {
-  /** Expose `/_status` route for health checks (default: false) */
-  exposeStatusRoute?: boolean;
-  /** Event loop lag threshold in ms — requests rejected above this (default: 1000) */
-  maxEventLoopDelay?: number;
-  /** V8 heap usage threshold in bytes — requests rejected above this */
-  maxHeapUsedBytes?: number;
-  /** RSS memory threshold in bytes — requests rejected above this */
-  maxRssBytes?: number;
-}
-interface MultipartOptions {
-  limits?: {
-    /** Max file size in bytes (default: Fastify default ~1MB) */fileSize?: number; /** Max number of files per request */
-    files?: number;
-  };
-}
-interface RawBodyOptions {
-  /** Body field name to store raw body on (default: 'rawBody') */
-  field?: string;
-  /** Apply to all routes globally (default: false) */
-  global?: boolean;
-  /** Encoding for raw body string (default: 'utf8') */
-  encoding?: string;
-  /** Parse raw body before other parsers (default: false) */
-  runFirst?: boolean;
-}
 //#endregion
-export { CustomPluginAuthOption as a, RawBodyOptions as c, preloadResourcesAsync as d, CustomAuthenticatorOption as i, UnderPressureOptions as l, BetterAuthOption as n, JwtAuthOption as o, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, preloadResources as u };
+export { AuthOption as a, CustomPluginAuthOption as c, preloadResourcesAsync as d, UnderPressureOptions as i, JwtAuthOption as l, MultipartOptions as n, BetterAuthOption as o, RawBodyOptions as r, CustomAuthenticatorOption as s, CreateAppOptions as t, preloadResources as u };