@classytic/arc 2.30.0 → 2.32.0

package/dist/{index-Q5gzEIWY.d.mts → index-CpzxqePp.d.mts}

@@ -1,10 +1,11 @@
-import { a as QueryCacheConfig } from "./QueryCache-DOMT_iq7.mjs";
-import { P as ArcHeaders, i as RequestScope } from "./types-DjC-KUCz.mjs";
-import { a as UserBase, l as AnyRecord, r as PermissionCheck } from "./types-ChvvVNP8.mjs";
-import "./elevation-C9s5hFP_.mjs";
-import { n as FieldPermissionMap } from "./fields-D3lhgzhD.mjs";
-import { n as EncryptionDirective } from "./types-Cc91nXuA.mjs";
-import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
+
+import { a as QueryCacheConfig } from "./QueryCache-DFA-QrU9.mjs";
+import { P as ArcHeaders, i as RequestScope } from "./types-ChuShpCP.mjs";
+import { a as UserBase, l as AnyRecord, r as PermissionCheck } from "./types-B7XeLEgK.mjs";
+import "./elevation-BXCfVcNG.mjs";
+import { n as FieldPermissionMap } from "./fields-I_EeRWND.mjs";
+import { n as EncryptionDirective } from "./types-ByHn9rEO.mjs";
+import { n as DomainEvent } from "./EventTransport-2uVV34WU.mjs";
 import { Filter } from "@classytic/repo-core/filter";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
@@ -1238,11 +1239,27 @@ interface AuthPluginOptions {
   strictTokenType?: boolean;
 }
 //#endregion
+//#region src/core/middlewares/rateLimit.d.ts
+/**
+ * Per-route CORS override, read by `@fastify/cors` off `routeOptions.config.cors`.
+ *
+ * The app-wide policy cannot serve both an API and public assets: an API wants
+ * `credentials: true` with a pinned origin list, while a public asset wants
+ * `origin: "*"` — and `*` with credentials is forbidden by the CORS spec (arc
+ * throws at boot on that combination). Per-route is the granularity that
+ * resolves it. `false` disables CORS for the route entirely.
+ *
+ * Arc does not interpret the value; `@fastify/cors` owns the semantics. Typed
+ * loosely on purpose so a host is never blocked by arc lagging the plugin's
+ * option surface.
+ */
+type RouteCorsConfig = Record<string, unknown> | false;
+//#endregion
 //#region src/types/handlers.d.ts
 /**
  * Minimal server accessor — exposes safe, read-only server decorators.
  * Allows controller handlers to publish events, log, and audit
- * without switching to `raw: true`.
+ * without switching to `rawHandler`.
  */
 interface ServerAccessor {
   /** Event bus — publish domain events from any handler */
@@ -1396,7 +1413,7 @@ interface IRequestContext<TBody = unknown, TParams extends Record<string, string
   metadata?: TMetadata;
   /**
    * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `raw: true`.
+   * from any handler without switching to `rawHandler`.
    *
    * @example
    * ```typescript
@@ -1431,7 +1448,7 @@ interface IControllerResponse<T = unknown> {
  * Controller handler — Arc's standard pattern.
  *
  * Receives a request context object, returns IControllerResponse.
- * Use with `raw: false` in routes.
+ * Use with `handler` in routes.
  *
  * **Generic parameters:**
  * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
@@ -1468,7 +1485,6 @@ interface IControllerResponse<T = unknown> {
  *   path: '/products',
  *   handler: createProduct,
  *   permissions: requireAuth(),
- *   raw: false,  // Arc wraps this into Fastify handler
  * }]
  * ```
  */
@@ -1477,7 +1493,7 @@ type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Rec
  * Fastify native handler
  *
  * Standard Fastify request/reply pattern.
- * Use with `raw: true` in routes.
+ * Use with `rawHandler` in routes.
  *
  * @example
  * ```typescript
@@ -1490,12 +1506,31 @@ type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Rec
  * routes: [{
  *   method: 'GET',
  *   path: '/files/:id/download',
- *   handler: downloadFile,
+ *   rawHandler: downloadFile,
  *   permissions: requireAuth(),
- *   raw: true,  // Use as-is, no wrapping
  * }]
  * ```
  */
+type RawRouteHandler = {
+  /**
+   * Fastify-native route handler — the type behind `RouteDefinition.rawHandler`.
+   *
+   * Declared with METHOD syntax and read back through an indexed access, which
+   * buys two properties a plain arrow alias can't have at once:
+   *
+   * - **Bivariant parameters.** `strictFunctionTypes` exempts method
+   *   declarations, so a handler annotated `FastifyRequest<{ Body: CreateBody }>`
+   *   assigns without a cast. Fastify's own `RouteHandlerMethod` is an arrow
+   *   alias, so it rejects those — hosts used to write `as any`.
+   * - **One call signature.** TypeScript contextually types parameters only
+   *   when a single constituent is callable, so inline
+   *   `rawHandler: async (request, reply) => …` infers instead of reporting
+   *   TS7006.
+   *
+   * The runtime always passes the real `(request, reply)` pair.
+   */
+  handler(this: FastifyInstance, request: FastifyRequest, reply: FastifyReply): unknown;
+}["handler"];
 type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
 /**
  * Union type for route handlers
@@ -1574,7 +1609,7 @@ interface RouteMcpConfig {
  *
  * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
  * - `handler: function` → inline handler → full Arc pipeline + MCP tool
- * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
+ * - `rawHandler` → raw Fastify handler → no pipeline, no MCP by default
  */
 interface RouteDefinition {
   readonly method: RouteMethod;
@@ -1583,14 +1618,14 @@ interface RouteDefinition {
   /**
    * Route handler.
    * - String: controller method name (Arc pipeline) — runtime lookup, no TS coverage on typos.
-   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
-   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
+   * - Function: receives IRequestContext, returns IControllerResponse (Arc pipeline)
+   * - For a raw Fastify handler `(request, reply)`, use {@link rawHandler}
    *
    * Prefer `controllerMethod` (2.16) over the string form when you want the
    * compiler to catch typos. `handler` stays optional when `controllerMethod`
    * is set — exactly one of the two must be declared.
    */
-  readonly handler?: string | ControllerHandler | RouteHandlerMethod | ((request: never, reply: never) => unknown);
+  readonly handler?: string | ControllerHandler;
   /**
    * Typed function-reference handler (2.16). Receives the live controller
    * instance and returns the method to invoke — TypeScript catches typos
@@ -1602,11 +1637,15 @@ interface RouteDefinition {
    * handlers go through), so there's no per-request lookup overhead.
    * The returned method is bound to the controller before dispatch.
    *
+   * PIPELINE-ONLY: the referenced method is invoked as a `ControllerHandler`
+   * (one `IRequestContext`), because the router derives "is this raw?" from
+   * {@link rawHandler} alone and this field is mutually exclusive with it.
+   * There is no flag that could make a `controllerMethod` route raw. For a
+   * Fastify-native controller method, put its NAME in `rawHandler` — the
+   * lookup is the same, and the field states the calling convention.
+   *
    * Mutually exclusive with `handler` — passing both throws at boot
-   * with a clear "pick one" message. The runtime contract on what the
-   * returned function accepts mirrors the `handler` rules: a plain
-   * `ControllerHandler` for pipeline routes, a raw Fastify handler when
-   * the route is `raw: true`.
+   * with a clear "pick one" message.
    *
    * Typed loosely (`(controller: unknown) => …`) at the type-system
    * boundary because `RouteDefinition` is not generic over the
@@ -1630,14 +1669,33 @@ interface RouteDefinition {
    * });
    * ```
    */
-  readonly controllerMethod?: (controller: unknown) => ControllerHandler | RouteHandlerMethod;
+  readonly controllerMethod?: (controller: unknown) => ControllerHandler;
   /** Permission check — REQUIRED */
   readonly permissions: PermissionCheck;
   /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
-   * request/reply. Default: false.
-   */
-  readonly raw?: boolean;
+   * Fastify-native handler — receives `(request, reply)` and owns the response.
+   * Bypasses arc's pipeline entirely: no `IControllerResponse` shaping, no
+   * field-write sanitization.
+   *
+   * Mutually exclusive with {@link handler}. The FIELD carries the intent, so
+   * there is no flag to forget: the previous `raw: boolean` let a Fastify-shaped
+   * function sit in `handler` without it (silently run through the pipeline) or
+   * a pipeline handler sit there with it (silently unwrapped), and neither
+   * mismatch was a type error.
+   *
+   * Splitting the two also restores inference. One field carrying both shapes
+   * meant a union of several function types, which has no single contextual
+   * signature — so an inline `handler: async (req) => …` reported TS7006 and
+   * every author annotated `req` by hand. Fastify types its own
+   * `RouteOptions.handler` as ONE function type for exactly this reason; see
+   * {@link RawRouteHandler} for why arc declares its own rather than reusing
+   * `RouteHandlerMethod` directly.
+   *
+   * Accepts a controller-method NAME as well, same as {@link handler} — the
+   * lookup is identical and only the calling convention differs, so a
+   * Fastify-native controller method stays reachable by name.
+   */
+  readonly rawHandler?: string | RawRouteHandler;
   /** Logical operation name (pipeline keys, MCP tool naming). */
   readonly operation?: string;
   /** OpenAPI summary */
@@ -1669,7 +1727,8 @@ interface RouteDefinition {
    */
   readonly tenantScope?: boolean;
   /**
-   * SSE streaming mode. Two handler shapes work:
+   * SSE streaming mode. Requires {@link rawHandler} — the handler is invoked
+   * with `(request, reply)` and owns the response. Two shapes work:
    *
    * - Write to `reply.raw` directly (NDJSON, custom SSE — historical contract).
    * - Return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`,
@@ -1700,7 +1759,7 @@ interface RouteDefinition {
    * `onFieldWriteDenied: 'reject' | 'strip'` setting governs how denials
    * are surfaced.
    *
-   * `raw: true` routes ALWAYS bypass this — they've opted out of the
+   * `rawHandler` routes ALWAYS bypass this — they've opted out of the
    * pipeline entirely.
    */
   readonly fieldWrite?: boolean;
@@ -1723,6 +1782,22 @@ interface RouteDefinition {
    * it to a dedicated `routes:` entry, or rely on the resource-level limit.
    */
   readonly rateLimit?: RateLimitConfig | false;
+  /**
+   * Per-route CORS override, forwarded to `@fastify/cors` as
+   * `routeOptions.config.cors`. `undefined` inherits the app policy; `false`
+   * disables CORS for this route; an object replaces the app policy for it.
+   *
+   * Needed because one app-wide policy cannot serve both an API and a public
+   * asset: an API wants `credentials: true` with a pinned origin list, a public
+   * asset wants `origin: "*"`, and `*` + credentials is forbidden by the spec
+   * (arc throws at boot on that pair).
+   *
+   * ```ts
+   * { method: "GET", path: "/manifest.json", permissions: allowPublic(),
+   *   cors: { origin: "*", credentials: false }, handler }
+   * ```
+   */
+  readonly cors?: RouteCorsConfig;
   /**
    * Fastify route schema. Each slot (`body`, `querystring`, `params`,
    * `headers`, `response[status]`) accepts a plain JSON Schema object
@@ -2829,7 +2904,7 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * object, primitive) is supported via auto-envelope (2.17+) but the
    * explicit envelope is the canonical contract — declared `fields:`
    * permissions, custom `status`, `meta`, and `headers` only work when
-   * you return the envelope. Set `raw: true` on a route to opt out of
+   * you return the envelope. Declare a route's function via `rawHandler` to opt out of
    * arc's pipeline entirely (custom streaming, SSE, manual `reply.send()`).
    *
    * **Path collisions with auto-CRUD are detected at `defineResource()` time.**
@@ -2844,7 +2919,7 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * ```typescript
    * routes: [
    *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
-   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
+   *   { method: 'POST', path: '/webhook', rawHandler: webhookFn, permissions: auth() },
    * ]
    * ```
    *
@@ -4220,4 +4295,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, SlugExt as $t, RequestIdOptions as A, ControllerConfigurableOptions as An, RouteDefinition as At, defineResource as B, RouteHandler as Bt, RequestContext as C, defineHook as Cn, PipelineStep as Ct, HealthCheck as D, ArcListResult as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, ArcGetResult as En, ActionDefinition as Et, FastifyWithDecorators as F, ControllerLike as Ft, OnTenantDeleteConfig as G, AuthenticatorContext as Gt, CrudController as H, AuthHelpers as Ht, MiddlewareHandler as I, FastifyHandler as It, PresetHook as J, BaseController as Jt, ResolvedTenantPurge as K, JwtContext as Kt, RequestWithExtras as L, IController as Lt, EventsDecorator as M, ListResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, BodySanitizer as Nn, RateLimitConfig as Nt, HealthOptions as O, ArcUpdateResult as On, ActionHandlerFn as Ot, FastifyWithAuth as P, BodySanitizerConfig as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, TreeMixin as Qt, RegisterOptions as R, IControllerResponse as Rt, QueryParserInterface as S, createHookSystem as Sn, PipelineContext as St, CrudRouterOptions as T, ArcDeleteResult as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, AuthPluginOptions as Ut, ResourceDefinition as V, ServerAccessor as Vt, ResourcePermissions as W, Authenticator as Wt, CrudRouteKey as X, SoftDeleteMixin as Xt, PresetResult as Y, SoftDeleteExt as Yt, CrudSchemas as Z, TreeExt as Zt, ControllerQueryOptions as _, afterDelete as _n, Guard as _t, InferAdapterDoc as a, QueryResolverConfig as an, ResourceExtensions as at, ParsedQuery as b, beforeDelete as bn, OperationFilter as bt, TypedController as c, DefineHookOptions as cn, AggMeasureShorthand as ct, PaginationResult as d, HookOperation as dn, AggregationDateRangeRequirement as dt, SlugMixin as en, RouteSchemaOptions as et, IntrospectionData as f, HookPhase as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, afterCreate as gn, AggregationsMap as gt, ResourceMetadata as h, HookSystemOptions as hn, AggregationRateLimit as ht, ValidationResult as i, QueryResolver as in, ResourceHooks as it, ArcDecorator as j, ControllerConstructionOptions as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, BaseControllerOptions as kn, ActionsMap as kt, TypedRepository as l, HookContext as ln, AggregationCacheConfig as lt, RegistryStats as m, HookSystem as mn, AggregationMaterializedResult as mt, ConfigError as n, BulkMixin as nn, FieldRule$1 as nt, InferDocType as o, AccessControl as on, EventDefinition as ot, RegistryEntry as p, HookRegistration as pn, AggregationMaterializedContext as pt, PresetFunction as q, TokenPair as qt, ValidateOptions as r, BaseCrudController as rn, ResourceHookContext as rt, InferResourceDoc as s, AccessControlConfig as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, BulkExt as tn, ArcFieldRule as tt, TypedResourceConfig as u, HookHandler as un, AggregationConfig as ut, LookupOption as v, afterUpdate as vn, Interceptor as vt, ServiceContext as w, ArcCreateResult as wn, Transform as wt, PopulateOption as x, beforeUpdate as xn, PipelineConfig as xt, OwnershipCheck as y, beforeCreate as yn, NextFunction as yt, ResourceRegistry as z, IRequestContext as zt };
+export { OpenApiSchemas as $, TreeMixin as $t, RequestIdOptions as A, BaseControllerOptions as An, RouteDefinition as At, defineResource as B, RawRouteHandler as Bt, RequestContext as C, createHookSystem as Cn, PipelineStep as Ct, HealthCheck as D, ArcGetResult as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, ArcDeleteResult as En, ActionDefinition as Et, FastifyWithDecorators as F, BodySanitizerConfig as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, Authenticator as Gt, CrudController as H, ServerAccessor as Ht, MiddlewareHandler as I, FastifyHandler as It, PresetHook as J, TokenPair as Jt, ResolvedTenantPurge as K, AuthenticatorContext as Kt, RequestWithExtras as L, IController as Lt, EventsDecorator as M, ControllerConstructionOptions as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ListResult as Nn, RateLimitConfig as Nt, HealthOptions as O, ArcListResult as On, ActionHandlerFn as Ot, FastifyWithAuth as P, BodySanitizer as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, TreeExt as Qt, RegisterOptions as R, IControllerResponse as Rt, QueryParserInterface as S, beforeUpdate as Sn, PipelineContext as St, CrudRouterOptions as T, ArcCreateResult as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, AuthHelpers as Ut, ResourceDefinition as V, RouteHandler as Vt, ResourcePermissions as W, AuthPluginOptions as Wt, CrudRouteKey as X, SoftDeleteExt as Xt, PresetResult as Y, BaseController as Yt, CrudSchemas as Z, SoftDeleteMixin as Zt, ControllerQueryOptions as _, afterCreate as _n, Guard as _t, InferAdapterDoc as a, QueryResolver as an, ResourceExtensions as at, ParsedQuery as b, beforeCreate as bn, OperationFilter as bt, TypedController as c, AccessControlConfig as cn, AggMeasureShorthand as ct, PaginationResult as d, HookHandler as dn, AggregationDateRangeRequirement as dt, SlugExt as en, RouteSchemaOptions as et, IntrospectionData as f, HookOperation as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookSystemOptions as gn, AggregationsMap as gt, ResourceMetadata as h, HookSystem as hn, AggregationRateLimit as ht, ValidationResult as i, BaseCrudController as in, ResourceHooks as it, ArcDecorator as j, ControllerConfigurableOptions as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, ArcUpdateResult as kn, ActionsMap as kt, TypedRepository as l, DefineHookOptions as ln, AggregationCacheConfig as lt, RegistryStats as m, HookRegistration as mn, AggregationMaterializedResult as mt, ConfigError as n, BulkExt as nn, FieldRule$1 as nt, InferDocType as o, QueryResolverConfig as on, EventDefinition as ot, RegistryEntry as p, HookPhase as pn, AggregationMaterializedContext as pt, PresetFunction as q, JwtContext as qt, ValidateOptions as r, BulkMixin as rn, ResourceHookContext as rt, InferResourceDoc as s, AccessControl as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, SlugMixin as tn, ArcFieldRule as tt, TypedResourceConfig as u, HookContext as un, AggregationConfig as ut, LookupOption as v, afterDelete as vn, Interceptor as vt, ServiceContext as w, defineHook as wn, Transform as wt, PopulateOption as x, beforeDelete as xn, PipelineConfig as xt, OwnershipCheck as y, afterUpdate as yn, NextFunction as yt, ResourceRegistry as z, IRequestContext as zt };

package/dist/{index-Cx7bro4R.d.mts → index-DXlHwvuE.d.mts}

@@ -1,7 +1,8 @@
-import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-Q5gzEIWY.mjs";
-import { i as RequestScope } from "./types-DjC-KUCz.mjs";
-import { l as AnyRecord, r as PermissionCheck } from "./types-ChvvVNP8.mjs";
-import "./fastify-augmentation-0WhPnUH7.mjs";
+
+import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-CpzxqePp.mjs";
+import { i as RequestScope } from "./types-ChuShpCP.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "./types-B7XeLEgK.mjs";
+import "./fastify-augmentation-BppG5bMT.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";

package/dist/index-ZWhLTp_s.d.mts

@@ -0,0 +1,290 @@
+
+import { _ as HealthCheck, a as ModuleContribution, f as ScheduleDefinition, n as ArcModuleInput, r as ArcModuleRegistry, s as ModuleSetupContext, t as ArcModule } from "./types-CT5vu6M0.mjs";
+import { FastifyInstance } from "fastify";
+//#region src/factory/module/contributions.d.ts
+/**
+ * Collect every module's `healthChecks` in the caller's order. Fails at boot
+ * on a duplicate check `name` across modules, naming BOTH owning modules.
+ * The host's app-level checks are appended AFTER this (modules-first,
+ * host-last) by the caller.
+ */
+declare function collectModuleHealthChecks(modules: readonly ArcModule[]): HealthCheck[];
+/**
+ * Collect every module's `workflows`. Resolves factory contributions (so a
+ * factory can close over a container the caller has already decorated on
+ * `fastify`) and flattens to a single opaque array. Arc core deliberately
+ * does NOT validate or interpret the values — the streamline integration
+ * owns name/shape checks and registration. Called by the integration at init
+ * time, not by arc's boot pipeline (workflows depend on the integration's
+ * container).
+ */
+declare function collectModuleWorkflows(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<unknown[]>;
+/**
+ * Collect every module's `scheduledJobs`. Resolves factory contributions
+ * (after bootstraps) and fails at boot on a duplicate job `name` across
+ * modules. The caller passes the returned definitions to the canonical
+ * schedules plugin; factories must therefore be resolved only once.
+ */
+declare function collectModuleScheduledJobs(fastify: FastifyInstance, modules: readonly ArcModule[],
+/**
+ * Optional sink for per-module counts, filled as each arm resolves.
+ *
+ * Exists so `arc.moduleDescriptors` can report real numbers without
+ * resolving the factories a SECOND time — a contribution factory closes over
+ * booted engines and may register or allocate, so running it twice is not a
+ * free read. One resolution feeds both activation and introspection.
+ */
+countsByModule?: Map<string, number>): Promise<ScheduleDefinition[]>;
+//#endregion
+//#region src/factory/module/extend.d.ts
+/**
+ * What a caller may add. Every mergeable arm of `ArcModule`, plus `bootstrap`
+ * in wrapper form only.
+ *
+ * `name` is absent on purpose: renaming a module mid-composition breaks the
+ * `dependsOn` graph and the registry key its consumers read, and it is the one
+ * "extension" that is never additive.
+ */
+interface ModuleExtension<TExports = unknown> {
+  dependsOn?: readonly string[];
+  owns?: readonly string[] | "provided";
+  resources?: ArcModule<TExports>["resources"];
+  eventHandlers?: ArcModule<TExports>["eventHandlers"];
+  scheduledJobs?: ArcModule<TExports>["scheduledJobs"];
+  workflows?: ArcModule<TExports>["workflows"];
+  healthChecks?: ArcModule<TExports>["healthChecks"];
+  errorMappers?: ArcModule<TExports>["errorMappers"];
+  plugins?: ArcModule<TExports>["plugins"];
+  afterResources?: ArcModule<TExports>["afterResources"];
+  onClose?: ArcModule<TExports>["onClose"];
+  /**
+   * WRAP the module's bootstrap — it is never replaced.
+   *
+   * Bootstrap returns the module's exports, so two of them cannot be
+   * concatenated: one value has to win, and a host silently winning is the gym
+   * failure (`{ ...mod, bootstrap }` overwrote the factory's own, so the engine
+   * the module published was never created). The wrapper form makes the
+   * relationship explicit — call `inner` and decorate its result, or
+   * deliberately do not.
+   *
+   * `inner` is `undefined` when the module has no bootstrap of its own.
+   */
+  bootstrap?: (inner: ((f: FastifyInstance, c: ModuleSetupContext) => TExports | Promise<TExports>) | undefined) => (f: FastifyInstance, c: ModuleSetupContext) => TExports | Promise<TExports>;
+}
+/**
+ * Merge a host's additions onto a module. Nothing the module declared is lost.
+ *
+ * ```ts
+ * return extendModule(createOrderModule({ … }), {
+ *   eventHandlers: () => hostHandlers(),      // appended after the module's
+ *   dependsOn: ["outbox"],                    // unioned
+ *   bootstrap: (inner) => async (f, c) => {   // wraps, never replaces
+ *     const exports = await inner?.(f, c);
+ *     return decorate(exports);
+ *   },
+ * });
+ * ```
+ */
+declare function extendModule<TExports = unknown>(mod: ArcModule<TExports>, extension: ModuleExtension<TExports>): ArcModule<TExports>;
+//#endregion
+//#region src/factory/module/lifecycle.d.ts
+/**
+ * Subscribe every module's `eventHandlers` in dependency order (pass the
+ * `orderModules`-sorted list). Returns the ordered list of unsubscribe
+ * functions so the caller can tear them down at shutdown BEFORE module
+ * `onClose` (while module deps are still alive). Fails at boot on:
+ *   - a duplicate NAMED handler across modules (attributing both owners);
+ *   - a module declaring handlers while the event subsystem is unavailable.
+ * Resolves factory contributions (after bootstraps) so a handler can close over
+ * booted engines rather than a global getter.
+ */
+declare function subscribeModuleEventHandlers(fastify: FastifyInstance, modules: readonly ArcModule[],
+/**
+ * Optional sink for per-module handler counts, filled as each arm resolves.
+ * Lets `arc.moduleDescriptors` report real numbers without resolving the
+ * factories a SECOND time — see the note on `collectModuleScheduledJobs`.
+ */
+countsByModule?: Map<string, number>): Promise<Array<() => void | Promise<void>>>;
+//#endregion
+//#region src/factory/module/order.d.ts
+/**
+ * Order modules for composition by their `dependsOn` edges — a STABLE
+ * topological sort. Called once at the start of the bootstrap phase; every
+ * subsequent phase (bootstrap, resources, afterResources, and reverse-order
+ * onClose) iterates the returned list, so a module's declared dependencies are
+ * always composed before it.
+ *
+ * "Stable" = modules with no edge between them keep their original list order,
+ * so declaring `dependsOn` on one module never silently reorders an unrelated
+ * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+ * returned unchanged.
+ *
+ * Fail-fast — throws (never reorders past a broken contract) on:
+ *   - duplicate module names (the name is the graph key)
+ *   - a `dependsOn` name not present in the composed set
+ *   - a self-reference (`dependsOn` includes the module's own name)
+ *   - a dependency cycle (reports the concrete `a → b → … → a` path)
+ */
+declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
+//#endregion
+//#region src/factory/module/resolve.d.ts
+/**
+ * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+ * (this is where a dynamic `import()` fires); a promise (or plain module) is
+ * awaited. Called once per module at the start of the bootstrap phase.
+ */
+declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
+/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
+declare function resolveContribution<T>(contribution: ModuleContribution<T> | undefined, fastify: FastifyInstance): Promise<readonly T[]>;
+//#endregion
+//#region src/factory/module/state.d.ts
+type ModuleState = "resolved" | "bootstrapping" | "ready" | "closing" | "closed" | "failed";
+/**
+ * Is `name` in the composed module graph? TRUE for resource-only modules and
+ * modules that exported nothing — the question `hasModuleExports()` cannot
+ * answer. FALSE before registerResources runs (no graph yet) and for
+ * uncomposed names.
+ */
+declare function hasModule(fastify: FastifyInstance, name: string): boolean;
+/**
+ * The module's current lifecycle state, or `undefined` when the module is not
+ * composed (or no graph has been composed on this instance). See the state
+ * machine in the file header.
+ */
+declare function getModuleState(fastify: FastifyInstance, name: string): ModuleState | undefined;
+//#endregion
+//#region src/factory/module/index.d.ts
+/**
+ * Identity helper for authoring a typed module — mirrors `defineResource`.
+ * Gives inference + a single obvious construction site; does no work.
+ *
+ * `TExports` is inferred from the `bootstrap` return value, so a module
+ * author gets a typed public export for free:
+ *
+ * ```ts
+ * export const accountingModule = (deps: Deps) =>
+ *   defineModule({
+ *     name: "accounting",
+ *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+ *   });
+ * ```
+ */
+declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
+/**
+ * Typed accessor for a module's public export (its `bootstrap` return value),
+ * recorded at `fastify.arc.modules[name]`.
+ *
+ * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
+ * accessors): a missing entry means the module either isn't composed, is
+ * composed AFTER the caller (list order = init order), or returned nothing —
+ * all wiring bugs that must surface at boot, not as `undefined` downstream.
+ *
+ * The type parameter is an assertion, not a proof. Two ways to type it:
+ *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
+ *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
+ *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
+ *
+ * Siblings, for the two shapes this one is wrong for:
+ *   - `getOptionalModuleExports` — the module is genuinely OPTIONAL.
+ *   - `lazyModuleExports` / `lazyRequiredModuleExports` — the read happens at
+ *     composition time, where boot order decides the answer.
+ */
+declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
+declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
+/**
+ * Non-throwing sibling of `getModuleExports`: `undefined` when the module is
+ * not composed (or has not bootstrapped yet).
+ *
+ * Exists because OPTIONAL sibling modules are a first-class composition shape —
+ * a deployment that turns `inventory` off still sells services, so its POS
+ * module must ask "is inventory here?" rather than fail-fast. Hosts were
+ * spelling that question as
+ *
+ * ```ts
+ * (fastify as unknown as { arc?: { modules?: Record<string, unknown> } })
+ *   .arc?.modules?.inventory;
+ * ```
+ *
+ * — a double cast that (a) defeats `ArcModuleRegistry` inference, (b) silently
+ * survives a typo in the module name, and (c) is impossible to grep for. Use
+ * `getModuleExports` when the dependency is REQUIRED (boot must fail), this
+ * when it is genuinely optional.
+ *
+ * Prefer `lazyModuleExports` whenever the read happens at COMPOSITION time —
+ * see its doc for why a value read once can latch `undefined` forever.
+ */
+declare function getOptionalModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K] | undefined;
+declare function getOptionalModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports | undefined;
+/**
+ * Is a module's public export recorded yet? The predicate form of
+ * `getOptionalModuleExports`, for readiness gates (`ready: () => ...`) that
+ * should not have to reason about falsy-but-present exports.
+ */
+declare function hasModuleExports(fastify: FastifyInstance, name: string): boolean;
+/**
+ * A DEFERRED reader of a sibling module's export: returns a getter that reads
+ * the registry at CALL time, not now.
+ *
+ * ── Why this exists (the bug it removes) ─────────────────────────────────────
+ *
+ * Module composition runs bootstraps in dependency/list order, but a lot of
+ * wiring is *registered* earlier than it *runs*: an `eventHandlers` factory, a
+ * bridge accessor handed to another module, a hook added during bootstrap and
+ * fired per request. Such a factory can execute BEFORE the sibling it needs has
+ * bootstrapped — so a sibling engine captured into a local at that moment is
+ * `undefined`, and stays `undefined` for the life of the process even though the
+ * sibling came up milliseconds later.
+ *
+ * That failure is SILENT by construction: the consumer sees a null bridge and
+ * treats it as "this deployment has no inventory / no revenue engine", which is
+ * a legitimate configuration. Real cost in this codebase: orders were created
+ * and never payment-confirmed (no entitlement, no card, no door) and nothing
+ * errored anywhere.
+ *
+ * The getter therefore:
+ *   - re-reads while the module is ABSENT, so boot order cannot matter;
+ *   - memoizes the FIRST resolved value, so the steady-state read is a closure
+ *     variable rather than a registry lookup per request;
+ *   - never memoizes absence — that is precisely the latch this replaces.
+ *
+ * ```ts
+ * const inventory = lazyModuleExports<FlowEngine>(fastify, "inventory");
+ * return {
+ *   flowBridge: () => (inventory() ? createFlowEngineBridge({ getFlowEngine: () => inventory()! }) : null),
+ *   ready: () => inventory() !== undefined,
+ * };
+ * ```
+ */
+declare function lazyModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): () => ArcModuleRegistry[K] | undefined;
+declare function lazyModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): () => TExports | undefined;
+/**
+ * Required counterpart of `lazyModuleExports`: defers the read, then throws
+ * `getModuleExports`' error if the module is still absent at first use.
+ *
+ * The pair matters because "required" and "readable now" are different
+ * questions. A hook registered at bootstrap that needs the `order` engine at
+ * REQUEST time is a hard dependency, but reading it eagerly turns a correct
+ * composition into a boot crash purely because of list order. Deferring keeps
+ * the fail-fast guarantee and moves it to the first moment the answer is
+ * actually needed.
+ *
+ * Deferred does NOT mean unvalidated: a lazily-required module is still a
+ * HARD dependency, so PRESENCE is checked eagerly. When the composed module
+ * graph is known (any `createApp`/`registerResources` boot — the normal
+ * case), a name that is not in the graph throws HERE, at composition time,
+ * instead of surviving startup and failing on the first request or event.
+ * Only the EXPORT read (does bootstrap's return value exist yet?) is
+ * deferred to first call.
+ *
+ * Convention for hard sibling access: also declare the target in the
+ * consumer's `dependsOn`. That orders composition (the sibling's bootstrap
+ * runs first), while this accessor merely defers the read — the two are
+ * complementary, not alternatives:
+ *   - hard dependency, read during bootstrap → `dependsOn` + `getModuleExports`
+ *   - hard dependency, read at request/event time → `dependsOn` + this
+ *   - optional integration → `lazyModuleExports` (no `dependsOn` needed)
+ */
+declare function lazyRequiredModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): () => ArcModuleRegistry[K];
+declare function lazyRequiredModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): () => TExports;
+//#endregion
+export { collectModuleScheduledJobs as _, lazyModuleExports as a, getModuleState as c, resolveModule as d, orderModules as f, collectModuleHealthChecks as g, extendModule as h, hasModuleExports as i, hasModule as l, ModuleExtension as m, getModuleExports as n, lazyRequiredModuleExports as o, subscribeModuleEventHandlers as p, getOptionalModuleExports as r, ModuleState as s, defineModule as t, resolveContribution as u, collectModuleWorkflows as v };