@classytic/arc 2.20.0 → 2.21.0

package/dist/{storage-Co_PQpeQ.d.mts → storage-DLUZ04kK.d.mts}

@@ -98,14 +98,18 @@ interface StorageReadRange {
 type StorageReadResult = {
   kind: "stream";
   stream: NodeJS.ReadableStream;
-  contentType: string; /** Total size of the full object (NOT the ranged slice). Required for `Content-Range`. */
-  bytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  contentType: string;
+  /** Total size of the full object (NOT the ranged slice). Required for `Content-Range`. */
+  bytes?: number;
+  /** Actual byte range returned when the caller passed `range`. */
   range?: StorageReadRange;
 } | {
   kind: "buffer";
   buffer: Buffer;
-  contentType: string; /** Total size of the full object. Used for `Content-Range` on partial reads. */
-  totalBytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  contentType: string;
+  /** Total size of the full object. Used for `Content-Range` on partial reads. */
+  totalBytes?: number;
+  /** Actual byte range returned when the caller passed `range`. */
   range?: StorageReadRange;
 };
 /**

package/dist/testing/index.d.mts

@@ -1,10 +1,9 @@
-import { V as ResourceDefinition, qt as AnyRecord } from "../index-_--GyzcO.mjs";
-import { d as preloadResourcesAsync, r as CreateAppOptions, u as preloadResources } from "../types-BHMKlMBU.mjs";
+import { V as ResourceDefinition, qt as AnyRecord } from "../index-Dtrj6XZk.mjs";
+import { d as preloadResourcesAsync, r as CreateAppOptions, u as preloadResources } from "../types-DpxoNX5v.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
 import { StandardRepo } from "@classytic/repo-core/repository";
-
 //#region src/testing/assertions.d.ts
 /**
  * expectArc — Arc-specific response assertions

package/dist/testing/index.mjs

@@ -210,7 +210,10 @@ function createJwtAuthProvider(app, opts = {}) {
 			if (!config.user) throw new Error(`[jwt] role '${role}' has neither 'user' nor 'token'`);
 			const jwt = app.jwt;
 			if (!jwt?.sign) throw new Error(`[jwt] app.jwt.sign() is unavailable — register @fastify/jwt before calling createJwtAuthProvider.`);
-			return jwt.sign(config.user);
+			return jwt.sign({
+				type: "access",
+				...config.user
+			});
 		}
 	});
 }
@@ -1046,7 +1049,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-D6uwzCKu.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-Bi61XxqU.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/testing/storageContract.d.mts

@@ -1,5 +1,4 @@
-import { t as Storage } from "../storage-Co_PQpeQ.mjs";
-
+import { t as Storage } from "../storage-DLUZ04kK.mjs";
 //#region src/testing/storageContract.d.ts
 interface StorageContractSetupResult {
   storage: Storage;

package/dist/{tracing-D8jlGXP7.d.mts → tracing-CsGKQJGg.d.mts}

@@ -1,6 +1,5 @@
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Span, Tracer } from "@opentelemetry/api";
-
 //#region src/plugins/tracing.d.ts
 interface TracingOptions {
   /**

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OnTenantDeleteConfig, $t as UserOrganization, A as RequestIdOptions, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Fn as BaseControllerOptions, G as ActionsMap, Gt as JwtContext, H as ActionDefinition, Ht as AuthPluginOptions, I as MiddlewareHandler, J as CrudRouteKey, Jt as ApiResponse, K as ArcFieldRule, Kt as TokenPair, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserLike, S as QueryParserInterface, St as RouteHandler, T as CrudRouterOptions, U as ActionEntry, Ut as Authenticator, Vt as AuthHelpers, W as ActionHandlerFn, Wt as AuthenticatorContext, X as EventDefinition, Xt as JWTPayload, Y as CrudSchemas, Yt as ArcRequest, Z as FieldRule, Zt as ObjectId, _ as ControllerQueryOptions, _t as ControllerLike, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IControllerResponse, c as TypedController, ct as ResourceExtensions, d as PaginationResult, dt as ResourcePermissions, et as OpenApiSchemas, f as IntrospectionData, ft as RouteDefinition, g as ArcInternalMetadata, gt as ControllerHandler, h as ResourceMetadata, ht as RouteSchemaOptions, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHookContext, m as RegistryStats, mt as RouteMethod, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourceHooks, v as LookupOption, vt as FastifyHandler, w as ServiceContext, x as PopulateOption, xt as IRequestContext, y as OwnershipCheck, yt as IController } from "../index-_--GyzcO.mjs";
-import { i as RequestScope } from "../types-LNebCoJx.mjs";
-import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-C7ahdGYf.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-xGUBq6p_.mjs";
+import { $ as OnTenantDeleteConfig, $t as UserOrganization, A as RequestIdOptions, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Fn as BaseControllerOptions, G as ActionsMap, Gt as JwtContext, H as ActionDefinition, Ht as AuthPluginOptions, I as MiddlewareHandler, J as CrudRouteKey, Jt as ApiResponse, K as ArcFieldRule, Kt as TokenPair, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserLike, S as QueryParserInterface, St as RouteHandler, T as CrudRouterOptions, U as ActionEntry, Ut as Authenticator, Vt as AuthHelpers, W as ActionHandlerFn, Wt as AuthenticatorContext, X as EventDefinition, Xt as JWTPayload, Y as CrudSchemas, Yt as ArcRequest, Z as FieldRule, Zt as ObjectId, _ as ControllerQueryOptions, _t as ControllerLike, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IControllerResponse, c as TypedController, ct as ResourceExtensions, d as PaginationResult, dt as ResourcePermissions, et as OpenApiSchemas, f as IntrospectionData, ft as RouteDefinition, g as ArcInternalMetadata, gt as ControllerHandler, h as ResourceMetadata, ht as RouteSchemaOptions, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHookContext, m as RegistryStats, mt as RouteMethod, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourceHooks, v as LookupOption, vt as FastifyHandler, w as ServiceContext, x as PopulateOption, xt as IRequestContext, y as OwnershipCheck, yt as IController } from "../index-Dtrj6XZk.mjs";
+import { i as RequestScope } from "../types-DH0GupI7.mjs";
+import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-BGqrAa_u.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
 export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/types/storage.d.mts

@@ -1,2 +1,2 @@
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Co_PQpeQ.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-DLUZ04kK.mjs";
 export { Storage, StorageContext, StorageFile, StorageReadRange, StorageReadResult, StorageUploadInput };

package/dist/types-Cc91nXuA.d.mts

@@ -0,0 +1,132 @@
+import { FastifyRequest } from "fastify";
+//#region src/encryption/types.d.ts
+/** JWE key-management algorithm — the protected-header `alg`. */
+type JweAlg = "RSA-OAEP-256" | "RSA-OAEP-384" | "RSA-OAEP-512" | "ECDH-ES" | "ECDH-ES+A256KW" | "A256GCMKW" | "dir";
+/** JWE content-encryption algorithm — the protected-header `enc`. AEAD only. */
+type JweEnc = "A128GCM" | "A192GCM" | "A256GCM";
+/** Encryption strategy for a route's response. */
+type EncryptionMode = "jwe" | "fields";
+/**
+ * Opaque key material. For `jwe` mode this is a `jose` `KeyLike` /
+ * `CryptoKey` / `Uint8Array`; for `fields` mode a 32-byte secret
+ * (`Buffer` / `Uint8Array`). Kept `unknown` at the contract layer so the
+ * `KeyProvider` interface carries no hard `jose` type dependency — hosts
+ * without `jose` installed can still implement field-mode providers.
+ */
+type KeyMaterial = unknown;
+/** A key paired with its identifier — what encrypt operations consume. */
+interface ActiveKey {
+  /** Key id, stamped into the JWE `kid` header / field envelope for rotation. */
+  readonly kid: string;
+  /** The key material (public key for JWE, 32-byte secret for fields). */
+  readonly key: KeyMaterial;
+  /** Optional per-key `alg` override (else the plugin default applies). */
+  readonly alg?: JweAlg;
+}
+/** Context handed to the key provider so resolution can be request-scoped. */
+interface KeyContext {
+  readonly request: FastifyRequest;
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Pluggable key resolution. Arc owns the request-time plumbing — `kid` →
+ * key, algorithm allowlist enforcement; the host owns the trust store —
+ * which keys are valid and where they live (file / env / AWS KMS / GCP KMS
+ * / Vault). Encryption and decryption are deliberately separate operations
+ * because they often use DIFFERENT keys (JWE: a public key encrypts the
+ * outbound response, a private key by `kid` decrypts the inbound request —
+ * exactly Visa's two-key-pair model).
+ *
+ * Rotation mirrors `@fastify/secure-session`: the active key encrypts; any
+ * key resolvable by `kid` can decrypt, so you can roll keys without dropping
+ * in-flight traffic.
+ */
+interface KeyProvider {
+  /** Active key for encrypting OUTBOUND responses. */
+  encryptionKey(ctx: KeyContext): MaybePromise<ActiveKey>;
+  /** Resolve a DECRYPTION key by the inbound message's `kid`. */
+  decryptionKey(kid: string, ctx: KeyContext): MaybePromise<KeyMaterial | undefined>;
+}
+/**
+ * Per-resource encryption directive — the typed slice plugins register on
+ * `ResourceExtensions`. Declared on a resource via
+ * `defineResource({ extensions: { encryption: { … } } })`; arc threads it
+ * to request time on `request.routeOptions.config.arcExtensions.encryption`.
+ */
+interface EncryptionDirective {
+  /** Strategy. Defaults to the plugin-level `mode` (default `'jwe'`). */
+  readonly mode?: EncryptionMode;
+  /**
+   * For `mode: 'fields'` — dot-paths of fields to encrypt, resolved against
+   * the serialized response body (e.g. `'cardNumber'`, `'account.iban'`).
+   * Ignored for `mode: 'jwe'` (the whole body is encrypted).
+   */
+  readonly fields?: readonly string[];
+  /**
+   * Explicit opt-out — set `false` to disable encryption for this resource
+   * even when a plugin-level default (`routes`) would otherwise apply.
+   */
+  readonly enabled?: boolean;
+}
+/**
+ * Plugin-level options. `keyProvider` is the only required field; everything
+ * else has a secure default.
+ */
+interface EncryptionOptions {
+  /**
+   * Master on/off. Default `true`. Set `false` to register the plugin as a
+   * typed no-op (config-gated environments) — same pattern as
+   * `idempotencyPlugin`.
+   */
+  readonly enabled?: boolean;
+  /** Key provider — resolves `kid` → key for encrypt/decrypt. Required. */
+  readonly keyProvider: KeyProvider;
+  /** Default mode when a route opts in without naming one. Default `'jwe'`. */
+  readonly mode?: EncryptionMode;
+  /** JWE key-management algorithm. Default `'RSA-OAEP-256'`. */
+  readonly alg?: JweAlg;
+  /** JWE content-encryption algorithm. Default `'A256GCM'`. */
+  readonly enc?: JweEnc;
+  /**
+   * Inbound-decryption algorithm allowlists — block algorithm-substitution
+   * downgrade attacks. Default `[alg]` / `[enc]`. Set explicitly only when a
+   * client legitimately uses more than one algorithm.
+   */
+  readonly allowedAlgs?: readonly JweAlg[];
+  readonly allowedEncs?: readonly JweEnc[];
+  /**
+   * Fallback opt-in for routes that don't declare
+   * `extensions.encryption`. Return a directive (or `true` for the default
+   * mode) to encrypt, `false`/`undefined` to skip. The per-resource
+   * `extensions.encryption` ALWAYS wins when present. Use this to scope ALE
+   * to sensitive prefixes without touching every resource.
+   *
+   * @example confine ALE to `/payments` and `/accounts`
+   * ```ts
+   * routes: (req) => /^\/(payments|accounts)\b/.test(req.url)
+   * ```
+   */
+  readonly routes?: (request: FastifyRequest) => EncryptionDirective | boolean | undefined;
+  /** Decrypt inbound `application/jose` request bodies. Default `true`. */
+  readonly decryptRequests?: boolean;
+  /** Media type that signals an encrypted REQUEST body. Default `'application/jose'`. */
+  readonly contentType?: string;
+  /** Content-Type set on full-body JWE RESPONSES. Default `'application/jose'`. */
+  readonly responseContentType?: string;
+  /**
+   * Response header advertising that the body is encrypted, so generic
+   * client SDKs know to decrypt. Default `'x-encrypted'`; set `false` to omit.
+   */
+  readonly flagHeader?: string | false;
+}
+/** Request decorations added by the plugin. */
+declare module "fastify" {
+  interface FastifyRequest {
+    /** `true` when the inbound body was decrypted from a JWE by this plugin. */
+    requestDecrypted?: boolean;
+    /** `true` when the outbound body was encrypted by this plugin. */
+    responseEncrypted?: boolean;
+  }
+}
+//#endregion
+export { JweAlg as a, KeyMaterial as c, EncryptionOptions as i, KeyProvider as l, EncryptionDirective as n, JweEnc as o, EncryptionMode as r, KeyContext as s, ActiveKey as t };

package/dist/{types-LNebCoJx.d.mts → types-DH0GupI7.d.mts}

@@ -168,8 +168,10 @@ type RequestScope = {
   kind: "service";
   clientId: string;
   organizationId: string;
-  scopes?: readonly string[]; /** App-defined scope dimensions — see `member.context` for details. */
-  context?: Readonly<Record<string, string>>; /** Parent organizations — see `member.ancestorOrgIds` for details. */
+  scopes?: readonly string[];
+  /** App-defined scope dimensions — see `member.context` for details. */
+  context?: Readonly<Record<string, string>>;
+  /** Parent organizations — see `member.ancestorOrgIds` for details. */
   ancestorOrgIds?: readonly string[];
   /**
    * Capability mandate — narrows what the caller may do beyond OAuth `scopes`.
@@ -207,8 +209,10 @@ type RequestScope = {
   kind: "elevated";
   userId?: string;
   organizationId?: string;
-  elevatedBy: string; /** App-defined scope dimensions — see `member.context` for details. */
-  context?: Readonly<Record<string, string>>; /** Parent organizations — see `member.ancestorOrgIds` for details. */
+  elevatedBy: string;
+  /** App-defined scope dimensions — see `member.context` for details. */
+  context?: Readonly<Record<string, string>>;
+  /** Parent organizations — see `member.ancestorOrgIds` for details. */
   ancestorOrgIds?: readonly string[];
 };
 /** Check if scope is `member` kind */

package/dist/{types-C9b2HR5W.d.mts → types-DRj-Ut4n.d.mts}

@@ -1,6 +1,5 @@
-import { V as ResourceDefinition } from "./index-_--GyzcO.mjs";
+import { V as ResourceDefinition } from "./index-Dtrj6XZk.mjs";
 import { z } from "zod";
-
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
 interface ToolAnnotations {

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

@@ -1,16 +1,15 @@
-import { Ut as Authenticator } from "./index-_--GyzcO.mjs";
+import { Ut as Authenticator } from "./index-Dtrj6XZk.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-B0e-bq-O.mjs";
+import { l as ResourceLike, n as ArcModuleInput } from "./module-WeuU5jfd.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-DQ4mCvg0.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>;
@@ -95,11 +94,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>;
   };
   /**
@@ -289,9 +294,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 */
@@ -442,7 +451,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 +479,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 +863,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`.
@@ -907,7 +945,9 @@ interface UnderPressureOptions {
 }
 interface MultipartOptions {
   limits?: {
-    /** Max file size in bytes (default: Fastify default ~1MB) */fileSize?: number; /** Max number of files per request */
+    /** Max file size in bytes (default: Fastify default ~1MB) */
+    fileSize?: number;
+    /** Max number of files per request */
     files?: number;
   };
 }