@classytic/arc 2.30.0 → 2.31.0

package/dist/{index-Cx7bro4R.d.mts → index-Bc2ox8_U.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-zh0_AYHa.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";

package/dist/{index-CG4yqMDB.d.mts → index-C-481Zf2.d.mts}

@@ -1,3 +1,5 @@
+
+import { r as PermissionCheck } from "./types-B7XeLEgK.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/integrations/jobs/execution.d.ts
 /**
@@ -43,18 +45,6 @@ interface ExecuteTimedHandlerOptions<T> {
 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`. */
   pattern?: string;
@@ -177,6 +167,61 @@ interface JobsPluginOptions {
   jobs: JobDefinition[];
   /** URL prefix for job management endpoints (default: '/jobs') */
   prefix?: string;
+  /**
+   * Job management HTTP endpoints (`GET <prefix>/stats`,
+   * `GET <prefix>/:queue/:id/status`).
+   *
+   * **Disabled by default.** A job status carries `returnValue` and
+   * `failedReason` — the handler's own output and error text, which routinely
+   * hold export URLs, billing results, model output, recipient addresses, or
+   * internal stack detail. Serving that unauthenticated turns a job id into a
+   * read primitive over other tenants' work.
+   *
+   * Enable it deliberately, with a permission check:
+   *
+   * ```ts
+   * managementRoutes: { operatorPermission: requireRoles(["platform-ops"]) }
+   * ```
+   *
+   * Queue-level counts are also available through the metrics/health
+   * integration, which does not expose individual jobs.
+   */
+  managementRoutes?: false | {
+    /**
+     * REQUIRED — arc will not mount an unguarded management surface.
+     *
+     * **This is an OPERATOR surface, not a tenant-facing one.** A BullMQ job
+     * carries no framework-level tenant identity, and `getStatus` fetches
+     * straight by queue + id, so a row-level `policy` on the decision has
+     * nothing to filter: `requireOrgRole("manager")` would let a manager in
+     * org A read a known job handle from org B. `/stats` is inherently
+     * global for the same reason.
+     *
+     * Gate it on an operator role — `requireRoles(["platform-ops"])` — and
+     * keep tenant-facing job status in a resource that owns its own row
+     * policy. Arc REFUSES a request whose decision carries a `policy`
+     * rather than silently ignoring it.
+     */
+    operatorPermission: PermissionCheck;
+    /**
+     * Accept an `operatorPermission` that arc cannot prove is platform-only.
+     *
+     * By default the gate must carry `_platformOnly` (i.e. come from
+     * `requirePlatformRole`), because that property is unprovable from
+     * outside: `requireOrgRole("manager")` and the default
+     * `requireRoles(["ops"])` both return a bare allow with no policy, so a
+     * manager in org A passes and reads a known handle from org B. Boot fails
+     * rather than serving a surface whose guard reads as tenant-scoped.
+     *
+     * Set this only for a custom check you have verified consults platform
+     * identity alone.
+     */
+    allowUnverifiedOperatorPermission?: boolean;
+    /** Include the handler's return value in a status response. Default `false`. */
+    exposeResult?: boolean;
+    /** Include `failedReason` in a status response. Default `false`. */
+    exposeFailureReason?: boolean;
+  };
   /** Bridge job events to Arc's event bus (default: true) */
   bridgeEvents?: boolean;
   /** Default job options applied to all jobs */
@@ -192,19 +237,30 @@ interface JobsPluginOptions {
   };
 }
 interface JobDispatcher {
-  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<{
-    jobId: string;
-  }>;
+  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<JobHandle>;
   getQueue(name: string): unknown | null;
   getStats(): Promise<Record<string, QueueStats>>;
   /**
    * Fetch a point-in-time status snapshot for a job by its ID.
-   * Searches across all registered queues.
-   * Returns `null` if the job doesn't exist or has been removed by retention policy.
+   * QUEUE-QUALIFIED: BullMQ job ids are local to their queue, so an id alone
+   * cannot identify a job. `dispatch()` returns the queue name alongside the id
+   * for exactly this reason.
+   *
+   * Returns `null` if the queue is not registered, or the job doesn't exist /
+   * has been removed by retention policy.
    */
-  getStatus(jobId: string): Promise<JobStatus | null>;
+  getStatus(queue: string, jobId: string): Promise<JobStatus | null>;
   close(): Promise<void>;
 }
+/**
+ * A dispatched job's address. The queue is part of the identity because BullMQ
+ * ids are queue-local — two queues can both hold `"123"`.
+ */
+interface JobHandle {
+  /** Registered job name (= queue name). */
+  queue: string;
+  jobId: string;
+}
 interface QueueStats {
   waiting: number;
   active: number;

package/dist/{index-Ch16aAah.d.mts → index-CEJNZFtX.d.mts}

@@ -1,6 +1,7 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-BGZCzOGL.mjs";
-import { i as RequestScope, n as Mandate } from "./types-DjC-KUCz.mjs";
-import { i as PermissionContext, r as PermissionCheck, t as AuthorizationDecision } from "./types-ChvvVNP8.mjs";
+
+import { r as CacheStore, t as CacheLogger } from "./interface-BOk3YnTz.mjs";
+import { i as RequestScope, n as Mandate } from "./types-ChuShpCP.mjs";
+import { i as PermissionContext, r as PermissionCheck, t as AuthorizationDecision } from "./types-B7XeLEgK.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -162,7 +163,7 @@ interface RequireAgentScopeOptions<TDoc = Record<string, unknown>> extends Requi
  */
 declare function requireAgentScope<TDoc = Record<string, unknown>>(opts: RequireAgentScopeOptions<TDoc>): PermissionCheck<TDoc>;
 //#endregion
-//#region src/permissions/applyPermissionResult.d.ts
+//#region src/permissions/authorizationDecision.d.ts
 /**
  * A permission check returns either a bare boolean (terse allow/deny sugar) or
  * a full {@link AuthorizationDecision}. There is no legacy `PermissionResult` —
@@ -222,12 +223,6 @@ type RequestSink = FastifyRequest & {
  * installed (and the obligation seam lives).
  */
 declare function applyAuthorizationDecision(decision: AuthorizationDecision, request: RequestSink): void;
-/**
- * @deprecated Renamed to {@link applyAuthorizationDecision} — the contract is an
- * `AuthorizationDecision`, not a `PermissionResult`. This alias is kept for
- * back-compat and will be removed in a future major.
- */
-declare const applyPermissionResult: typeof applyAuthorizationDecision;
 //#endregion
 //#region src/permissions/context.d.ts
 /**
@@ -307,6 +302,24 @@ declare function requireRoles(roles: readonly string[], options?: {
    */
   includeOrgRoles?: boolean;
 }): PermissionCheck;
+/**
+ * Require a PLATFORM role — global roles only. An organization role can never
+ * satisfy this gate.
+ *
+ * `requireRoles(["ops"])` also accepts an ORG role named `ops` (that is its
+ * documented default), and `requireOrgRole("manager")` grants ANY organization's
+ * manager. Both return a bare allow with no policy, so a surface that is global
+ * by construction — a queue dashboard, a cluster-wide operations endpoint —
+ * cannot distinguish them from a real operator gate by looking at the decision.
+ * That makes "platform-only" a property the check has to DECLARE, which is what
+ * `_platformOnly` records and what such a surface can then require.
+ *
+ * Elevated scope passes: platform admin is the identity this gate is for.
+ *
+ * @example
+ * permissions: { list: requirePlatformRole("platform-ops") }
+ */
+declare function requirePlatformRole(...args: string[] | [readonly string[]]): PermissionCheck;
 /**
  * Short-form alias of `requireRoles()`. Identical behavior — checks both
  * platform roles AND org roles. Prefer `requireRoles` for new code; this
@@ -522,22 +535,45 @@ declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixCo
  * - `public` — `allowPublic()`; anyone passes.
  * - `roles` — grants if the caller holds ANY of these (platform OR org roles,
  *   unioned — matches how `requireRoles`/`requireOrgRole`/`anyOf` compose).
+ * - `scoped` — grants only within a caller SCOPE dimension (`_scopeContext`,
+ *   e.g. `{ branchRole: "head_office" }`), optionally combined with `roles`. The
+ *   scope dimensions are known statically even though their per-request VALUES
+ *   aren't, so a consumer that holds the caller's scope (a FE that knows the
+ *   active branch's role) can decide it client-side — the piece a flat `roles`
+ *   requirement could not express.
  * - `authenticated` — the check reads request-time facts (custom auth, service
- *   scope, ownership, scope-context, grants) that no static analysis can decide;
- *   the definitive answer is computed per request. Treat as "server decides".
+ *   scope, ownership, grants) that no static analysis can decide; the definitive
+ *   answer is computed per request. Treat as "server decides".
  */
 type PermissionRequirement = {
   readonly kind: "public";
 } | {
   readonly kind: "roles";
   readonly roles: readonly string[];
+  /**
+   * `true` when these roles are NECESSARY but not SUFFICIENT — the gate is an
+   * `allOf(...)` that also carries an opaque runtime branch (ownership /
+   * custom / dynamic / flow-mode …). A role MATCH is then `conditional`, not a
+   * definitive `allow`; a MISMATCH is still a definitive `deny`.
+   */
+  readonly conditional?: boolean;
+} | {
+  readonly kind: "scoped";
+  /** Required scope dimensions: `value` string = must equal; `undefined` = must be present. */
+  readonly scope: Readonly<Record<string, string | undefined>>;
+  /** Roles ALSO required alongside the scope (union of platform + org roles), if any. */
+  readonly roles?: readonly string[];
+  /** See `roles.conditional` — the composite also has an opaque/contradictory branch. */
+  readonly conditional?: boolean;
 } | {
   readonly kind: "authenticated";
 };
 /**
  * Extract a check's static requirement from its `PermissionCheckMeta`. Public
- * wins; then the union of platform + org roles a role gate declares; otherwise
- * "authenticated" (auth-required / custom / request-time checks).
+ * wins; then a scope-context gate (optionally with roles); then the union of
+ * platform + org roles a role gate declares; otherwise "authenticated"
+ * (auth-required / custom / request-time checks). An `allOf` that couldn't be
+ * fully captured statically carries `conditional: true` (see `_conditional`).
  */
 declare function describePermission(check: PermissionCheck): PermissionRequirement;
 /** Result of {@link explainAccess}. */
@@ -566,6 +602,8 @@ interface AccessExplanation {
 declare function explainAccess(check: PermissionCheck, principal?: {
   roles?: readonly string[];
   orgRoles?: readonly string[];
+  /** The caller's scope-context values (e.g. `{ branchRole: "head_office" }`) — supply to decide a `scoped` gate. */
+  scope?: Readonly<Record<string, string | undefined>>;
 }): AccessExplanation;
 /**
  * Introspect a whole permission map (`{ list, get, create, ... }` or any
@@ -952,4 +990,4 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { evaluatePermissionDecision as $, explainAccess as A, anyOf as B, requireGrant as C, collectPublicSurface as D, PermissionRequirement as E, createDynamicPermissionMatrix as F, requireOwnership as G, denyAll as H, createOrgPermissions as I, when as J, requireRoles as K, allOf as L, DynamicPermissionMatrix as M, DynamicPermissionMatrixConfig as N, describePermission as O, PermissionEventBus as P, applyPermissionResult as Q, allow as R, modeSatisfies as S, AccessExplanation as T, not as U, deny as V, requireAuth as W, PermissionCheckReturn as X, scopeOf as Y, applyAuthorizationDecision as Z, createRoleHierarchy as _, permissionMatrix as a, requireMandate as at, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, normalizeToDecision as et, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireDPoP as it, ConnectEventsOptions as j, describePermissionMap as k, readOnly as l, requireServiceScope as m, authenticated as n, RequireMandateOptions as nt, presets_d_exports as o, requireScopeContext as p, roles as q, fullPublic as r, requireAgentScope as rt, publicRead as s, adminOnly as t, RequireAgentScopeOptions as tt, requireOrgInScope as u, GRANT_MODES as v, conjoinPolicyFilters as w, RequireGrantOptions as x, GrantMode as y, allowPublic as z };
+export { evaluatePermissionDecision as $, explainAccess as A, anyOf as B, requireGrant as C, collectPublicSurface as D, PermissionRequirement as E, createDynamicPermissionMatrix as F, requireOwnership as G, denyAll as H, createOrgPermissions as I, roles as J, requirePlatformRole as K, allOf as L, DynamicPermissionMatrix as M, DynamicPermissionMatrixConfig as N, describePermission as O, PermissionEventBus as P, applyAuthorizationDecision as Q, allow as R, modeSatisfies as S, AccessExplanation as T, not as U, deny as V, requireAuth as W, scopeOf as X, when as Y, PermissionCheckReturn as Z, createRoleHierarchy as _, permissionMatrix as a, requireMandate as at, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, normalizeToDecision as et, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireDPoP as it, ConnectEventsOptions as j, describePermissionMap as k, readOnly as l, requireServiceScope as m, authenticated as n, RequireMandateOptions as nt, presets_d_exports as o, requireScopeContext as p, requireRoles as q, fullPublic as r, requireAgentScope as rt, publicRead as s, adminOnly as t, RequireAgentScopeOptions as tt, requireOrgInScope as u, GRANT_MODES as v, conjoinPolicyFilters as w, RequireGrantOptions as x, GrantMode as y, allowPublic as z };

package/dist/index-CFThn1K9.d.mts

@@ -0,0 +1,224 @@
+
+import { a as ModuleContribution, h as HealthCheck, n as ArcModuleInput, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-CBgvkp8O.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[]): 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
+ * 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 { lazyModuleExports as a, getModuleState as c, resolveModule as d, orderModules as f, collectModuleWorkflows as g, collectModuleScheduledJobs as h, hasModuleExports as i, hasModule as l, collectModuleHealthChecks as m, getModuleExports as n, lazyRequiredModuleExports as o, subscribeModuleEventHandlers as p, getOptionalModuleExports as r, ModuleState as s, defineModule as t, resolveContribution as u };