@classytic/arc 2.22.0 → 2.25.0

package/dist/{integrations/jobs.d.mts → index-CG4yqMDB.d.mts}

@@ -1,5 +1,59 @@
 import { FastifyPluginAsync } from "fastify";
-//#region src/integrations/jobs.d.ts
+//#region src/integrations/jobs/execution.d.ts
+/**
+ * Timed handler execution — the concurrency core of the jobs worker,
+ * extracted from the BullMQ registration so the algorithm is testable
+ * without queue mocks.
+ *
+ * Contract:
+ *  - The handler receives an `AbortSignal`, aborted when `timeoutMs`
+ *    elapses. The timeout rejects THIS call; the handler itself is only
+ *    signalled — cooperative cancellation.
+ *  - `releaseSlot` (the bulkhead semaphore) fires when the handler
+ *    promise SETTLES, not when the timeout rejects — a timed-out handler
+ *    that keeps running still occupies its concurrency slot, so retries
+ *    can't stack live executions past the limit.
+ *  - `cancelGraceMs` bounds that hold: a handler ignoring its signal past
+ *    timeout + grace has its slot force-released (logged loudly — beyond
+ *    this point the bulkhead can be exceeded by the abandoned execution).
+ *  - A timed-out handler's eventual settle is logged for observability;
+ *    its result is discarded.
+ *  - `releaseSlot` is invoked exactly once, on every path (success,
+ *    failure, timeout-then-settle, grace expiry). Synchronous throws from
+ *    the handler are converted to rejections so release always fires.
+ */
+interface TimedHandlerLogger {
+  warn(obj: Record<string, unknown>, msg: string): void;
+}
+interface ExecuteTimedHandlerOptions<T> {
+  /** The work. Must treat the signal as its cancellation channel. */
+  run: (signal: AbortSignal) => Promise<T>;
+  /** Job/queue label for timeout errors and logs. */
+  label: string;
+  /** Correlation id for logs (e.g. the BullMQ job id). */
+  jobId?: string;
+  /** Reject after this many ms and abort the signal. Omit = no timeout. */
+  timeoutMs?: number;
+  /** Slot hold-bound after timeout (default: 30_000). */
+  cancelGraceMs?: number;
+  /** Bulkhead slot release — called exactly once. Omit when unguarded. */
+  releaseSlot?: () => void;
+  logger?: TimedHandlerLogger;
+}
+declare function executeTimedHandler<T>(options: ExecuteTimedHandlerOptions<T>): Promise<T>;
+//#endregion
+//#region src/integrations/jobs/types.d.ts
+/**
+ * Job queue integration — public contract (definitions, meta, dispatcher).
+ *
+ * Directory map (mechanical split of the former single file):
+ *   types.ts     — this contract + `defineJob`
+ *   execution.ts — `executeTimedHandler` (timeout / cancellation / bulkhead)
+ *   repeat.ts    — repeatable-schedule reconciliation (boot hygiene)
+ *   plugin.ts    — BullMQ wiring (queues, workers, DLQ, routes, shutdown)
+ *   index.ts     — public barrel; `src/integrations/jobs.ts` re-exports it
+ *                  so the package subpath is unchanged
+ */
 /** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
 interface JobRepeatOptions {
   /** Cron pattern (e.g. '0 9 * * *' = every day 09:00). Mutually exclusive with `every`. */
@@ -44,13 +98,37 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
    * and appear as `throttled: true` in `GET /jobs/:id/status`.
    * Distinct from BullMQ `concurrency` — use this when the constraint is a
    * downstream resource (AI model rate limit, DB connection pool, external API).
+   *
+   * The slot is held until the handler actually SETTLES — a timed-out
+   * handler that keeps running (ignoring `meta.signal`) still counts
+   * against `maxConcurrent`, so retries can't stack live executions past
+   * the limit. `cancelGraceMs` bounds how long a stuck handler may hold
+   * its slot after timeout.
    */
   maxConcurrent?: number;
+  /**
+   * How long after a TIMEOUT a still-running handler may keep its
+   * `maxConcurrent` slot before the slot is force-released (default:
+   * 30_000). The bulkhead limits LIVE handlers, not worker awaits — but a
+   * handler that ignores `meta.signal` forever must not wedge the queue.
+   * A force-release is logged loudly: past that point the bulkhead can be
+   * exceeded by the abandoned execution.
+   */
+  cancelGraceMs?: number;
 }
 interface JobMeta {
   jobId: string;
   attemptsMade: number;
   timestamp: number;
+  /**
+   * Aborted when the job's `timeout` elapses. Pass it to fetch/DB calls so
+   * timed-out work actually STOPS — the timeout alone only rejects the
+   * worker's await (releasing the concurrency slot) while the handler keeps
+   * running; a BullMQ retry can then overlap the original execution.
+   * Handlers that ignore the signal must be idempotent / compare-and-set
+   * safe under that overlap.
+   */
+  signal: AbortSignal;
 }
 interface JobDispatchOptions {
   /** Delay job execution by ms */
@@ -148,6 +226,8 @@ interface QueueStats {
  * });
  */
 declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDefinition<TData, TResult>): JobDefinition<TData, TResult>;
+//#endregion
+//#region src/integrations/jobs/plugin.d.ts
 /**
  * Pluggable BullMQ job queue integration for Arc.
  *
@@ -156,4 +236,4 @@ declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDe
  */
 declare const jobsPlugin: FastifyPluginAsync<JobsPluginOptions>;
 //#endregion
-export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobStatus, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };
+export { JobMeta as a, JobsPluginOptions as c, ExecuteTimedHandlerOptions as d, TimedHandlerLogger as f, JobDispatcher as i, QueueStats as l, JobDefinition as n, JobRepeatOptions as o, executeTimedHandler as p, JobDispatchOptions as r, JobStatus as s, jobsPlugin as t, defineJob as u };

package/dist/{index-DbtgCOCj.d.mts → index-DPRH0Cme.d.mts}

@@ -1,6 +1,6 @@
-import { a as QueryCacheConfig } from "./QueryCache-Z1B38koh.mjs";
-import { i as RequestScope } from "./types-DH0GupI7.mjs";
-import { i as UserBase, t as PermissionCheck } from "./types-Csxga7d3.mjs";
+import { a as QueryCacheConfig } from "./QueryCache-DOMT_iq7.mjs";
+import { P as ArcHeaders, i as RequestScope } from "./types-DjC-KUCz.mjs";
+import { c as AnyRecord, i as UserBase, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
 import "./elevation-C9s5hFP_.mjs";
 import { n as FieldPermissionMap } from "./fields-D3lhgzhD.mjs";
 import { n as EncryptionDirective } from "./types-Cc91nXuA.mjs";
@@ -620,9 +620,9 @@ declare class QueryResolver {
   /** Sanitize advanced populate options against allowedPopulate */
   private sanitizePopulateOptions;
   /**
-   * Sanitize lookup/join options.
-   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
-   * Validates lookup structure to prevent injection.
+   * Sanitize lookup/join options. Deny-by-default: `allowedLookups` must be
+   * configured for any client-driven lookup to pass; listed collections are
+   * then structurally validated to prevent injection.
    */
   private sanitizeLookups;
   /**
@@ -833,6 +833,26 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    * create/update, the original input (`existing`) for delete.
    */
   protected runAfterHook(req: IRequestContext, op: "create" | "update" | "delete", data: AnyRecord, meta?: Record<string, unknown>): Promise<void>;
+  /**
+   * Per-instance single-flight for cache fills — concurrent requests for
+   * the SAME cache key coalesce onto one repository query instead of each
+   * issuing its own (a popular entry expiring under 1,000 concurrent
+   * readers must produce 1 DB query, not 1,000). Keys already encode the
+   * resolved query + user/org scope + resource version, so coalescing can
+   * never cross tenants, scopes, or invalidation generations. Per-process
+   * by design; distributed refresh leases are a store-level concern
+   * (planned with the repo-core CacheEngine façade, which ships
+   * single-flight natively).
+   */
+  private readonly inFlightCacheFills;
+  private cacheSingleFlight;
+  /**
+   * Register a background SWR refresh for `key` unless one is already in
+   * flight. Registration is SYNCHRONOUS (before the deferred tick) so a
+   * burst of stale readers arriving in the same tick schedules exactly one
+   * revalidation.
+   */
+  private scheduleCacheRefresh;
   /** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
   protected withListCache(req: IRequestContext, options: ParsedQuery): Promise<IControllerResponse<ListResult<TDoc>> | null>;
   /** Cached `get()` flow with SWR semantics. Returns null when cache is disabled. */
@@ -1044,90 +1064,6 @@ declare class BaseController<TDoc extends AnyRecord = AnyRecord, _TRepository ex
   readonly _phantom?: [TDoc, _TRepository];
 }
 //#endregion
-//#region src/types/base.d.ts
-declare module "fastify" {
-  interface FastifyRequest {
-    /** Request scope — set by auth adapter, read by permissions/presets/guards */
-    scope: RequestScope;
-    /**
-     * Current user — set by auth adapter (Better Auth, JWT, custom).
-     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
-     * Guard with `if (request.user)` on routes that allow anonymous access.
-     *
-     * Kept as required (not `user?`) because `@fastify/jwt` declares it
-     * as required — declaration merges must have identical modifiers.
-     * The `| undefined` in the type achieves the same DX.
-     */
-    user: Record<string, unknown> | undefined;
-    /** Policy-injected query filters (e.g. ownership, org-scoping) */
-    _policyFilters?: Record<string, unknown>;
-    /** Field mask — fields to include/exclude in responses */
-    fieldMask?: {
-      include?: string[];
-      exclude?: string[];
-    };
-    /** Arbitrary policy metadata for downstream consumers */
-    policyMetadata?: Record<string, unknown>;
-    /** Document loaded by policy middleware for ownership checks */
-    document?: unknown;
-    /** Ownership check context (field name + user field) */
-    _ownershipCheck?: Record<string, unknown>;
-  }
-}
-type AnyRecord = Record<string, unknown>;
-/** MongoDB ObjectId — accepts string or any object with a `toString()` (e.g. mongoose ObjectId). */
-type ObjectId = string | {
-  toString(): string;
-};
-/**
- * Flexible user type that accepts any object with id/_id properties.
- * The actual user structure is defined by your app's auth system.
- */
-type UserLike = UserBase & {
-  /** User email (optional) */
-  email?: string;
-};
-interface UserOrganization {
-  userId: string;
-  organizationId: string;
-  [key: string]: unknown;
-}
-interface JWTPayload {
-  sub: string;
-  [key: string]: unknown;
-}
-/**
- * Standard API response envelope — `{ success, data?, error?, message?, meta? }`.
- * Used by Arc's default response shape.
- */
-interface ApiResponse<T = unknown> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-  meta?: Record<string, unknown>;
-}
-/**
- * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
- * instead of `(req as any).user`.
- *
- * @example
- * ```typescript
- * import type { ArcRequest } from '@classytic/arc';
- *
- * handler: async (req: ArcRequest, reply) => {
- *   req.user?.id;                    // typed
- *   req.scope.organizationId;        // typed (when member)
- *   req.signal;                      // AbortSignal (Fastify 5)
- * }
- * ```
- */
-type ArcRequest = FastifyRequest & {
-  scope: RequestScope;
-  user: Record<string, unknown> | undefined;
-  signal: AbortSignal;
-};
-//#endregion
 //#region src/types/auth.d.ts
 /**
  * JWT utilities provided to authenticator. Arc provides the helpers;
@@ -1423,8 +1359,16 @@ interface IRequestContext<TBody = unknown, TParams extends Record<string, string
   body: TBody;
   /** Authenticated user or null */
   user: TUser | null;
-  /** Request headers */
-  headers: Record<string, string | undefined>;
+  /**
+   * Request headers — `ArcHeaders` (`string | string[] | undefined` per
+   * name), the HONEST type: on the HTTP path this is Fastify's headers
+   * object passed through, and repeated headers arrive as `string[]` at
+   * runtime (2.24 widening — the previous `Record<string, string |
+   * undefined>` lied about that). Read via `getHeader(ctx.headers, name)`
+   * from `@classytic/arc/utils` for array-safe, duplicate-deterministic
+   * access, or `requireSingleHeaderValue` for security-sensitive headers.
+   */
+  headers: ArcHeaders;
   /** Organization ID (for multi-tenant apps) */
   organizationId?: string;
   /** Team ID (for team-scoped resources) */
@@ -1652,7 +1596,7 @@ interface RouteDefinition {
    * 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: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
+  readonly handler?: string | ControllerHandler | RouteHandlerMethod | ((request: never, reply: never) => unknown);
   /**
    * Typed function-reference handler (2.16). Receives the live controller
    * instance and returns the method to invoke — TypeScript catches typos
@@ -4055,6 +3999,14 @@ interface RegistryEntry extends ResourceMetadata {
     roles?: readonly string[];
     redactValue?: unknown;
   }>;
+  /**
+   * The LIVE field-permission map (2.22) — the same object `defineResource`
+   * consumes, surfaced so request-time consumers (the realtime change feed)
+   * can apply `applyFieldReadPermissions` masking to event payloads without
+   * re-reading the resource definition. `fieldPermissions` above stays the
+   * introspection-safe metadata twin.
+   */
+  fields?: FieldPermissionMap;
   /** Pipeline step names (for OpenAPI data) */
   pipelineSteps?: Array<{
     type: string;
@@ -4237,4 +4189,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, UserOrganization as $t, RequestIdOptions as A, ArcCreateResult as An, RouteDefinition as At, defineResource as B, BodySanitizerConfig as Bn, RouteHandler as Bt, RequestContext as C, afterDelete as Cn, PipelineStep as Ct, HealthCheck as D, beforeUpdate as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, beforeDelete as En, ActionDefinition as Et, FastifyWithDecorators as F, BaseControllerOptions as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, JwtContext as Gt, CrudController as H, AuthPluginOptions as Ht, MiddlewareHandler as I, ControllerConfigurableOptions as In, FastifyHandler as It, PresetHook as J, ApiResponse as Jt, ResolvedTenantPurge as K, TokenPair as Kt, RequestWithExtras as L, ControllerConstructionOptions as Ln, IController as Lt, EventsDecorator as M, ArcGetResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ArcListResult as Nn, RateLimitConfig as Nt, HealthOptions as O, createHookSystem as On, ActionHandlerFn as Ot, FastifyWithAuth as P, ArcUpdateResult as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, UserLike as Qt, RegisterOptions as R, ListResult as Rn, IControllerResponse as Rt, QueryParserInterface as S, afterCreate as Sn, PipelineContext as St, CrudRouterOptions as T, beforeCreate as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, Authenticator as Ut, ResourceDefinition as V, AuthHelpers as Vt, ResourcePermissions as W, AuthenticatorContext as Wt, CrudRouteKey as X, JWTPayload as Xt, PresetResult as Y, ArcRequest as Yt, CrudSchemas as Z, ObjectId as Zt, ControllerQueryOptions as _, HookOperation as _n, Guard as _t, InferAdapterDoc as a, SlugExt as an, ResourceExtensions as at, ParsedQuery as b, HookSystem as bn, OperationFilter as bt, TypedController as c, BulkMixin as cn, AggMeasureShorthand as ct, PaginationResult as d, QueryResolverConfig as dn, AggregationDateRangeRequirement as dt, BaseController as en, RouteSchemaOptions as et, IntrospectionData as f, AccessControl as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookHandler as gn, AggregationsMap as gt, ResourceMetadata as h, HookContext as hn, AggregationRateLimit as ht, ValidationResult as i, TreeMixin as in, ResourceHooks as it, ArcDecorator as j, ArcDeleteResult as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, defineHook as kn, ActionsMap as kt, TypedRepository as l, BaseCrudController as ln, AggregationCacheConfig as lt, RegistryStats as m, DefineHookOptions as mn, AggregationMaterializedResult as mt, ConfigError as n, SoftDeleteMixin as nn, FieldRule$1 as nt, InferDocType as o, SlugMixin as on, EventDefinition as ot, RegistryEntry as p, AccessControlConfig as pn, AggregationMaterializedContext as pt, PresetFunction as q, AnyRecord as qt, ValidateOptions as r, TreeExt as rn, ResourceHookContext as rt, InferResourceDoc as s, BulkExt as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, SoftDeleteExt as tn, ArcFieldRule as tt, TypedResourceConfig as u, QueryResolver as un, AggregationConfig as ut, LookupOption as v, HookPhase as vn, Interceptor as vt, ServiceContext as w, afterUpdate as wn, Transform as wt, PopulateOption as x, HookSystemOptions as xn, PipelineConfig as xt, OwnershipCheck as y, HookRegistration as yn, NextFunction as yt, ResourceRegistry as z, BodySanitizer as zn, IRequestContext as zt };
+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 };

package/dist/{module-B4u10iOJ.d.mts → index-KUoxjIq1.d.mts}

@@ -1,5 +1,106 @@
+import { r as EventHandler } from "./EventTransport-QmY7A258.mjs";
 import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
-import { FastifyInstance } from "fastify";
+import { FastifyInstance, FastifyPluginAsync } from "fastify";
+import { LockAdapter } from "@classytic/repo-core/lock";
+//#region src/plugins/health.d.ts
+interface HealthCheck {
+  /** Name of the dependency */
+  name: string;
+  /**
+   * Function that returns true if healthy, false otherwise.
+   *
+   * Receives an `AbortSignal` aborted when the check's timeout elapses —
+   * pass it to fetch/driver calls so a stalled dependency probe actually
+   * STOPS instead of accumulating an abandoned operation per readiness
+   * poll. Ignoring the parameter is fine (back-compat): the timeout still
+   * bounds how long the PROBE waits, just not the underlying work.
+   */
+  check: (signal?: AbortSignal) => Promise<boolean> | boolean;
+  /** Optional timeout in ms (default: 5000) */
+  timeout?: number;
+  /** Whether this check is critical for readiness (default: true) */
+  critical?: boolean;
+}
+interface HealthOptions {
+  /** Route prefix (default: '/_health') */
+  prefix?: string;
+  /** Health check dependencies */
+  checks?: readonly HealthCheck[];
+  /** Enable metrics endpoint (default: false) */
+  metrics?: boolean;
+  /** Custom metrics collector function */
+  metricsCollector?: () => Promise<string> | string;
+  /** Version info to include in responses */
+  version?: string;
+  /** Collect HTTP request metrics (default: true if metrics enabled) */
+  collectHttpMetrics?: boolean;
+}
+declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
+declare const _default$1: FastifyPluginAsync<HealthOptions>;
+//#endregion
+//#region src/plugins/schedules.d.ts
+interface ScheduleDefinition {
+  /** Unique name — also the lock key (`arc:schedule:<name>`). */
+  name: string;
+  /** Interval in milliseconds between the END of one run and the next tick. */
+  every: number;
+  /** The work. Receives the Fastify instance; errors are logged, never fatal. */
+  handler: (fastify: FastifyInstance) => void | Promise<void>;
+  /** Fire once immediately when the app becomes ready (default: false). */
+  runOnStart?: boolean;
+  /**
+   * Random extra delay in `[0, jitterMs)` added to the FIRST tick only.
+   * Spreads boot-aligned jobs so multiple same-cadence schedules don't all
+   * fire at exactly `boot + every` after every restart (and, with a lock,
+   * de-synchronizes replicas competing for the same lease). Ignored when
+   * `runOnStart` is true.
+   */
+  jitterMs?: number;
+  /**
+   * Lease duration when a `lock` is configured. Default: `every * 0.9`
+   * (capped at 5 minutes) — long enough that other replicas skip the same
+   * tick, short enough that a crashed leader fails over within one cycle.
+   */
+  leaseMs?: number;
+  /** Per-schedule kill switch (default: true). */
+  enabled?: boolean;
+}
+interface SchedulesPluginOptions {
+  schedules: readonly ScheduleDefinition[];
+  /**
+   * Ecosystem lock adapter (`LockAdapter` from `@classytic/repo-core/lock`)
+   * for multi-replica deployments. Omit for single-instance apps — every
+   * tick runs locally.
+   */
+  lock?: LockAdapter;
+  /**
+   * Identity of this replica for lease ownership. Default: a random id per
+   * process (repo-core's `getInstanceId()` is a good explicit value).
+   */
+  holderId?: string;
+  /**
+   * Master switch — `false` registers a typed no-op (config-gated
+   * environments), same pattern as `idempotencyPlugin`.
+   */
+  enabled?: boolean;
+}
+/** Per-schedule runtime counters, readable via `fastify.getScheduleStats()`. */
+interface ScheduleStats {
+  name: string;
+  runs: number;
+  failures: number;
+  skippedByLock: number;
+  lastRunAt: string | null;
+  lastError: string | null;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    getScheduleStats?: () => ScheduleStats[];
+  }
+}
+declare const schedulesPlugin: FastifyPluginAsync<SchedulesPluginOptions>;
+declare const _default: FastifyPluginAsync<SchedulesPluginOptions>;
+//#endregion
 //#region src/factory/loadResources.d.ts
 /**
  * loadResources — Auto-discover resource files from a directory.
@@ -218,7 +319,31 @@ interface LoadResourcesOptions<TContext = unknown> {
  */
 declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
 //#endregion
-//#region src/factory/module.d.ts
+//#region src/factory/module/types.d.ts
+/**
+ * A module's contribution of some arm (event handlers, scheduled jobs, …).
+ * Either a static array or a factory resolved AFTER all module bootstraps, so a
+ * contribution can close over booted engines / the Fastify instance instead of
+ * reaching for a global getter (the coupling the module contract removes).
+ */
+type ModuleContribution<T> = readonly T[] | ((fastify: FastifyInstance) => readonly T[] | Promise<readonly T[]>);
+/**
+ * A domain-event subscription a module owns. Subscribed in dependency order
+ * during the `afterResources` phase (routes mounted, engines booted) and
+ * auto-unsubscribed at shutdown BEFORE module `onClose` (deps still alive).
+ */
+interface EventHandlerDefinition {
+  /** Event pattern(s) to subscribe — same matcher as `fastify.events.subscribe`. */
+  event: string | readonly string[];
+  /** The subscriber. */
+  handler: EventHandler;
+  /**
+   * Optional stable name — enables duplicate detection + teardown diagnostics.
+   * Third-party modules should prefix it with their module name, for example
+   * `inventory.order-created`; Arc does not silently rewrite public names.
+   */
+  name?: string;
+}
 interface ArcModule<TExports = unknown> {
   /** Stable identifier — appears in boot logs and duplicate-module detection. */
   readonly name: string;
@@ -344,6 +469,74 @@ interface ArcModule<TExports = unknown> {
    * module owns.
    */
   afterResources?: (fastify: FastifyInstance) => void | Promise<void>;
+  /**
+   * Readiness checks this module contributes to the app's
+   * `healthPlugin` (`/_health/ready`). Collected across ALL modules in
+   * dependency order and merged BEFORE the host's app-level `arcPlugins.health`
+   * checks (modules-first, host-last) — the same additive convention arc uses
+   * for resources and error mappers. Check `name`s must be unique across the
+   * module graph (arc fails at boot on a collision, attributing both owners).
+   *
+   * STATIC by design (not a factory): declare the check up front and let its
+   * `check()` closure resolve dependencies LAZILY at probe time, so collection
+   * can happen before the health plugin registers and the worker probe
+   * (`createWorker`) receives the identical union without a second registration.
+   *
+   * ```ts
+   * defineModule({ name: "inventory", healthChecks: [
+   *   { name: "flow-engine", check: () => flow.isReady() },
+   * ] })
+   * ```
+   */
+  readonly healthChecks?: readonly HealthCheck[];
+  /**
+   * Domain-event subscriptions this module owns — the declarative replacement
+   * for imperative `fastify.events.subscribe(...)` calls inside
+   * `afterResources`. Subscribed in dependency order during the
+   * `afterResources` phase (routes mounted, engines booted), and arc RETAINS
+   * every unsubscribe and invokes it at shutdown BEFORE module `onClose` (while
+   * module deps are still alive). Named handlers must be unique across the
+   * module graph; a module that declares handlers while the event subsystem is
+   * disabled (`arcPlugins.events: false`) fails at boot. Array or factory (the
+   * factory runs after bootstraps, so it can close over booted engines).
+   *
+   * ```ts
+   * defineModule({ name: "party", eventHandlers: [
+   *   { name: "party.link-customer", event: ["customer:created"], handler: onCustomer },
+   * ] })
+   * ```
+   */
+  readonly eventHandlers?: ModuleContribution<EventHandlerDefinition>;
+  /**
+   * Durable workflows this module owns. OPAQUE to arc core — arc never imports
+   * `@classytic/streamline`; the value flows through untouched and the
+   * streamline integration (`@classytic/arc/integrations/streamline`, a peer)
+   * gives it meaning (name/shape validation, registration). Collected via
+   * `collectModuleWorkflows` at integration-init time (after module bootstraps),
+   * so a factory can close over the shared workflow container the integration
+   * decorates on the instance.
+   *
+   * ```ts
+   * defineModule({ name: "invoice",
+   *   workflows: (f) => createInvoiceWorkflows(f.streamlineContainer) })
+   * ```
+   */
+  readonly workflows?: ModuleContribution<unknown>;
+  /**
+   * Recurring interval schedules this module owns. Arc composes them into its
+   * existing `schedulesPlugin` after bootstraps, in dependency order. Names
+   * must be unique across the module graph. Configure multi-replica locking via
+   * `arcPlugins.schedules`; explicitly disabling that runner while a module
+   * declares schedules fails boot instead of silently dropping work. Array or
+   * factory (the factory runs once after bootstraps and may close over engines).
+   *
+   * ```ts
+   * defineModule({ name: "loyalty", scheduledJobs: [
+   *   { name: "loyalty.point.expiration", every: 3_600_000, handler: () => sweep() },
+   * ] })
+   * ```
+   */
+  readonly scheduledJobs?: ModuleContribution<ScheduleDefinition>;
   /**
    * Teardown — registered as a Fastify `onClose` hook. Destroy engines, stop
    * timers, flush the module's outbox. Modules close in REVERSE list order
@@ -376,11 +569,64 @@ interface ArcModule<TExports = unknown> {
  */
 type ArcModuleInput<TExports = unknown> = ArcModule<TExports> | Promise<ArcModule<TExports>> | (() => ArcModule<TExports> | Promise<ArcModule<TExports>>);
 /**
- * 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.
+ * Typed module registry — hosts augment this via declaration merging so
+ * `getModuleExports(f, "order")` infers the export type without a manual type
+ * argument (the fastify / awilix pattern):
+ *
+ * ```ts
+ * declare module "@classytic/arc/factory" {
+ *   interface ArcModuleRegistry {
+ *     order: OrderEngine;
+ *     accounting: AccountingEngine;
+ *   }
+ * }
+ * ```
+ *
+ * Left empty here so the fallback `getModuleExports<T>(f, name: string)` stays
+ * available for apps that don't augment it.
  */
-declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
+interface ArcModuleRegistry {}
+//#endregion
+//#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[]): Promise<ScheduleDefinition[]>;
+//#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[]): 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
@@ -400,24 +646,18 @@ declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
  *   - 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
 /**
- * Typed module registry — hosts augment this via declaration merging so
- * `getModuleExports(f, "order")` infers the export type without a manual type
- * argument (the fastify / awilix pattern):
- *
- * ```ts
- * declare module "@classytic/arc/factory" {
- *   interface ArcModuleRegistry {
- *     order: OrderEngine;
- *     accounting: AccountingEngine;
- *   }
- * }
- * ```
- *
- * Left empty here so the fallback `getModuleExports<T>(f, name: string)` stays
- * available for apps that don't augment it.
+ * 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.
  */
-interface ArcModuleRegistry {}
+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/index.d.ts
 /**
  * Identity helper for authoring a typed module — mirrors `defineResource`.
  * Gives inference + a single obvious construction site; does no work.
@@ -451,4 +691,4 @@ declare function defineModule<TExports = unknown>(module: ArcModule<TExports>):
 declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
 declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
 //#endregion
-export { getModuleExports as a, LoadResourcesOptions as c, loadResources as d, defineModule as i, ResourceLike as l, ArcModuleInput as n, orderModules as o, ArcModuleRegistry as r, resolveModule as s, ArcModule as t, ResourceModule as u };
+export { schedulesPlugin as C, healthPlugin as D, _default$1 as E, _default as S, HealthOptions as T, ResourceModule as _, orderModules as a, ScheduleStats as b, collectModuleScheduledJobs as c, ArcModuleInput as d, ArcModuleRegistry as f, ResourceLike as g, LoadResourcesOptions as h, resolveModule as i, collectModuleWorkflows as l, ModuleContribution as m, getModuleExports as n, subscribeModuleEventHandlers as o, EventHandlerDefinition as p, resolveContribution as r, collectModuleHealthChecks as s, defineModule as t, ArcModule as u, loadResources as v, HealthCheck as w, SchedulesPluginOptions as x, ScheduleDefinition as y };