@classytic/arc 2.23.0 → 2.28.0

package/dist/events/index.mjs

@@ -1,6 +1,6 @@
-import { t as __exportAll } from "../rolldown-runtime-8H4AJuhK.mjs";
-import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-DJG2D7sy.mjs";
+import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-DrQ_FesK.mjs";
 import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
+import { InvalidOutboxEventError, OutboxOwnershipError } from "@classytic/primitives/outbox";
 import { and, anyOf, eq, lte, ne, or } from "@classytic/repo-core/filter";
 import { update } from "@classytic/repo-core/update";
 //#region src/events/defineEvent.ts
@@ -61,10 +61,6 @@ import { update } from "@classytic/repo-core/update";
 * const result = registry.validate('order.created', payload);
 * ```
 */
-var defineEvent_exports = /* @__PURE__ */ __exportAll({
-	createEventRegistry: () => createEventRegistry,
-	defineEvent: () => defineEvent
-});
 /**
 * Define a typed event with optional schema validation.
 *
@@ -243,10 +239,31 @@ const CACHE_EVENTS = Object.freeze({
 });
 //#endregion
 //#region src/events/memory-outbox.ts
+/**
+* In-memory outbox store — reference implementation for dev / testing.
+*
+* Supports the full `OutboxStore` capability set (claim/lease, fail/retry,
+* dedupe, visibleAt). Production deployments should pass a `repository` to
+* `EventOutbox` instead of using this; the memory store exists for unit
+* tests and single-process dev where durable persistence is noise.
+*/
 const DEFAULT_LEASE_MS$2 = 3e4;
 var MemoryOutboxStore = class {
 	entries = [];
 	seenDedupeKeys = /* @__PURE__ */ new Set();
+	/**
+	* Drop every entry (including delivered / failed / dead-lettered rows) and
+	* the dedupe-key memory.
+	*
+	* For tests only — it is the in-memory analogue of truncating the table, and
+	* exists so a suite can isolate cases against ONE store instance (the
+	* `reset` hook of `runOutboxStoreContract`). Not part of `OutboxStore`; a
+	* production store must never expose this.
+	*/
+	clear() {
+		this.entries.length = 0;
+		this.seenDedupeKeys.clear();
+	}
 	async save(event, options) {
 		if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
 		if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
@@ -356,11 +373,117 @@ var MemoryOutboxStore = class {
 	}
 };
 //#endregion
+//#region src/events/outbox/backoff.ts
+/**
+* Compute a `retryAt` `Date` using exponential backoff with jitter.
+*
+* This is a convenience helper for store authors implementing
+* {@link OutboxStore.fail}: call it to compute the retry visibility window
+* based on the event's current attempt count.
+*
+* Formula: `delay = min(maxMs, baseMs * 2^(attempt - 1)) * (1 + random * jitter)`
+*
+* @example Basic usage inside a store's `fail()` method
+* ```typescript
+* async fail(eventId, error, options) {
+*   const entry = await this.findById(eventId);
+*   entry.attempts++;
+*   if (entry.attempts >= MAX_ATTEMPTS) {
+*     return this.deadLetter(eventId, error);
+*   }
+*   const retryAt = exponentialBackoff({ attempt: entry.attempts });
+*   entry.visibleAt = retryAt;
+*   await this.update(entry);
+* }
+* ```
+*
+* @example Tuning for a faster transport
+* ```typescript
+* exponentialBackoff({ attempt: 3, baseMs: 250, maxMs: 10_000, jitter: 0.3 });
+* // attempt=1 → ~250ms   ±30%
+* // attempt=2 → ~500ms   ±30%
+* // attempt=3 → ~1000ms  ±30%
+* // attempt=10 → capped at 10_000ms
+* ```
+*/
+function exponentialBackoff(options) {
+	const attempt = Math.max(1, Math.floor(options.attempt));
+	const baseMs = options.baseMs ?? 1e3;
+	const maxMs = options.maxMs ?? 6e4;
+	const jitter = Math.max(0, Math.min(1, options.jitter ?? .2));
+	const now = options.now ?? Date.now();
+	const exp = baseMs * 2 ** (attempt - 1);
+	const capped = Math.min(maxMs, exp);
+	const jittered = jitter > 0 ? capped * (1 + Math.random() * jitter) : capped;
+	return new Date(now + jittered);
+}
+//#endregion
 //#region src/events/repository-outbox-adapter.ts
+/**
+* RepositoryLike → OutboxStore adapter.
+*
+* Maps the `OutboxStore` vocabulary (save / claimPending / acknowledge /
+* fail / getDeadLettered / purge) onto arc's own `RepositoryLike` primitives
+* (create / getOne / findAll / deleteMany / findOneAndUpdate). `EventOutbox`
+* wraps a passed repository with this helper when you use the
+* `{ repository }` option; the function is also re-exported from
+* `@classytic/arc/events` so consumers can build and decorate the store
+* manually (metrics, tracing, multi-transport fan-out).
+*
+* Portability: filters compose via `@classytic/repo-core/filter` and
+* updates via `@classytic/repo-core/update`. The primary-key column name
+* is read from `repository.idField` — mongokit defaults to `_id`,
+* sqlitekit / pgkit / prismakit to the schema's declared PK. The adapter
+* therefore runs on any kit that implements `StandardRepo.findOneAndUpdate`
+* + `getOne` + `getAll` + `deleteMany` + `create`.
+*
+* `fail()` uses a lease-gated read-then-write pair to preserve
+* `firstFailedAt` across retries without relying on Mongo's aggregation-
+* pipeline `$ifNull`. Leases guarantee single-writer during the failure
+* window (`claimPending` filters out non-owned rows), so the two calls are
+* safe under concurrent relayers.
+*
+* Why we DON'T use `StandardRepo.claim()` (repo-core 0.4+) anywhere in this
+* adapter — design note for the next reader who wants to "modernize" us:
+*
+*   • `claimPending` (FIFO claim-next loop): `claim(id, ...)` requires the
+*     candidate id upfront, but the relayer doesn't have it — that's the
+*     whole point of `findOneAndUpdate({ filter, sort: { createdAt: 1 } })`,
+*     which finds + claims in a SINGLE round-trip per claimed event.
+*     Replacing with `getOne(filter, sort) → claim(id, ...)` doubles the
+*     round-trips, opens a TOCTOU window where the candidate state can
+*     change between read and CAS (we'd need a retry loop on null-on-race),
+*     and gains nothing — the existing call is already atomic and
+*     race-free. Throughput regression with no upside; do not adopt.
+*
+*   • `acknowledge` (pending → delivered): id is in scope, but the current
+*     filter uses `ne('status', 'delivered')` to allow ack from any
+*     non-delivered state (defensive; lease invariant means it's pending
+*     in practice). `claim` requires an exact `from` value, so adopting
+*     would tighten the source-state predicate from "not delivered" to
+*     "exactly pending". That's a behavior change — even if the new
+*     behavior is arguably tighter/safer, the constraint here is "no
+*     semantic regression". Keep `findOneAndUpdate`.
+*
+*   • `fail` (any → pending|dead_letter): the current `baseFilter` is
+*     id-only (with optional `leaseOwner` guard) — there's NO source-state
+*     predicate at all. Adopting `claim` would ADD `from: 'pending'`,
+*     blocking `fail()` calls against rows in any other state. Same "no
+*     semantic regression" concern; keep `findOneAndUpdate`. The
+*     read-then-write pair also exists here to preserve `firstFailedAt`
+*     portably (see paragraph above) — `claim` doesn't simplify that.
+*
+* No kit currently ships a filter-based `claimNext`/`claimPending` (Path C
+* in the v2.11.x evaluation) — checked mongokit 3.13.0 + sqlitekit 0.3.0.
+* If/when one appears, the FIFO loop becomes a 1-call adoption candidate.
+*/
 const DEFAULT_LEASE_MS$1 = 3e4;
 const DEFAULT_CLAIM_LIMIT = 100;
 const DEFAULT_PURGE_BATCH = 500;
-function repositoryAsOutboxStore(repository) {
+/** Column this adapter reads/writes for the visibility timestamp. */
+const DEFAULT_VISIBLE_AT_FIELD = "visibleAt";
+function repositoryAsOutboxStore(repository, options) {
+	const visibleAtField = options?.visibleAtField ?? DEFAULT_VISIBLE_AT_FIELD;
 	const missing = [];
 	if (typeof repository.create !== "function") missing.push("create");
 	if (typeof repository.getOne !== "function") missing.push("getOne");
@@ -387,7 +510,7 @@ function repositoryAsOutboxStore(repository) {
 	* lease. Used by `getPending` and `claimPending` — defined once so the
 	* two code paths stay in lockstep.
 	*/
-	const claimableFilter = (now) => and(eq("status", "pending"), lte("visibleAt", now), or(eq("leaseOwner", null), lte("leaseExpiresAt", now)));
+	const claimableFilter = (now) => and(eq("status", "pending"), lte(visibleAtField, now), or(eq("leaseOwner", null), lte("leaseExpiresAt", now)));
 	return {
 		async save(event, options) {
 			if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
@@ -399,7 +522,7 @@ function repositoryAsOutboxStore(repository) {
 				type: event.type,
 				status: "pending",
 				attempts: 0,
-				visibleAt: options?.visibleAt ?? now,
+				[visibleAtField]: options?.visibleAt ?? now,
 				leaseOwner: null,
 				leaseExpiresAt: null,
 				deliveredAt: null,
@@ -433,25 +556,26 @@ function repositoryAsOutboxStore(repository) {
 			const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS$1;
 			const consumerId = options?.consumerId ?? "anonymous";
 			const typeFilter = options?.types?.length ? anyOf("type", options.types) : null;
-			const claimed = [];
-			for (let i = 0; i < limit; i++) {
-				const now = /* @__PURE__ */ new Date();
-				const leaseExpiresAt = new Date(now.getTime() + leaseMs);
-				const filter = typeFilter ? and(claimableFilter(now), typeFilter) : claimableFilter(now);
-				const doc = await r.findOneAndUpdate(filter, update({
+			const now = /* @__PURE__ */ new Date();
+			const candidateFilter = typeFilter ? and(claimableFilter(now), typeFilter) : claimableFilter(now);
+			const candidates = unwrapDocs(await r.getAll({
+				filters: candidateFilter,
+				sort: { createdAt: 1 },
+				page: 1,
+				limit
+			}));
+			if (candidates.length === 0) return [];
+			return (await Promise.all(candidates.map((candidate) => {
+				const claimNow = /* @__PURE__ */ new Date();
+				const leaseExpiresAt = new Date(claimNow.getTime() + leaseMs);
+				return r.findOneAndUpdate(and(eq(idField, candidate.event.meta.id), claimableFilter(claimNow)), update({
 					set: {
 						leaseOwner: consumerId,
 						leaseExpiresAt
 					},
 					inc: { attempts: 1 }
-				}), {
-					sort: { createdAt: 1 },
-					returnDocument: "after"
-				});
-				if (!doc) break;
-				if (isWellFormed(doc.event)) claimed.push(doc.event);
-			}
-			return claimed;
+				}), { returnDocument: "after" });
+			}))).filter((doc) => doc !== null).map((doc) => doc.event).filter(isWellFormed);
 		},
 		async acknowledge(eventId, options) {
 			const now = /* @__PURE__ */ new Date();
@@ -484,7 +608,7 @@ function repositoryAsOutboxStore(repository) {
 			const firstFailedAt = current.firstFailedAt ?? now;
 			if (await r.findOneAndUpdate(filter, update({ set: {
 				status: targetStatus,
-				visibleAt,
+				[visibleAtField]: visibleAt,
 				leaseOwner: null,
 				leaseExpiresAt: null,
 				lastFailedAt: now,
@@ -537,7 +661,7 @@ function repositoryAsOutboxStore(repository) {
 	};
 }
 //#endregion
-//#region src/events/outbox.ts
+//#region src/events/outbox/relay.ts
 /** Default outbox retention — delivered events older than this are eligible for purge */
 const DEFAULT_OUTBOX_RETENTION_MS = 10080 * 60 * 1e3;
 const DEFAULT_LEASE_MS = 3e4;
@@ -552,34 +676,6 @@ const DEFAULT_LEASE_MS = 3e4;
 * the store).
 */
 const MAX_TRACKED_ATTEMPTS = 1e4;
-/**
-* Thrown by a store when `acknowledge` / `fail` is called by a consumer that
-* does not own the event's current lease.
-*
-* Stores that enforce lease ownership MUST throw this (not silently return)
-* so {@link EventOutbox} can detect the mismatch and avoid over-counting
-* successful deliveries. {@link EventOutbox.relay} catches it and reports
-* via {@link EventOutboxOptions.onError} instead of counting as relayed.
-*/
-var OutboxOwnershipError = class extends Error {
-	eventId;
-	attemptedBy;
-	currentOwner;
-	constructor(eventId, attemptedBy, currentOwner) {
-		super(`Outbox ownership mismatch for event "${eventId}": attempted by "${attemptedBy}", current owner is "${currentOwner ?? "none"}". The lease may have expired and been reclaimed by another worker.`);
-		this.name = "OutboxOwnershipError";
-		this.eventId = eventId;
-		this.attemptedBy = attemptedBy;
-		this.currentOwner = currentOwner;
-	}
-};
-/** Thrown by {@link EventOutbox.store} when an event is missing `type` or `meta.id`. */
-var InvalidOutboxEventError = class extends Error {
-	constructor(reason) {
-		super(`Invalid outbox event: ${reason}`);
-		this.name = "InvalidOutboxEventError";
-	}
-};
 var EventOutbox = class {
 	_store;
 	_transport;
@@ -643,7 +739,7 @@ var EventOutbox = class {
 				session: autoSession
 			};
 		}
-		if (!effective?.headers?.["traceparent"] && this._traceContextProvider) {
+		if (!effective?.headers?.traceparent && this._traceContextProvider) {
 			const traceHeaders = this._traceContextProvider();
 			if (traceHeaders && Object.keys(traceHeaders).length > 0) effective = {
 				...effective ?? {},
@@ -726,11 +822,14 @@ var EventOutbox = class {
 			usedPublishMany: false
 		};
 		if (!this._transport) return empty;
+		const claimStartedAt = Date.now();
 		const pending = this._store.claimPending ? await this._store.claimPending({
 			limit: this._batchSize,
 			consumerId: this._consumerId,
 			leaseMs: this._leaseMs
 		}) : await this._store.getPending(this._batchSize);
+		const claimMs = Date.now() - claimStartedAt;
+		const publishStartedAt = Date.now();
 		const valid = [];
 		let malformed = 0;
 		for (const event of pending) {
@@ -840,7 +939,9 @@ var EventOutbox = class {
 			malformed,
 			failHookErrors: counts.failHookErrors,
 			deadLettered: counts.deadLettered,
-			usedPublishMany: canPublishMany && valid.length > 0
+			usedPublishMany: canPublishMany && valid.length > 0,
+			claimMs,
+			publishMs: Date.now() - publishStartedAt
 		};
 	}
 	/**
@@ -874,51 +975,39 @@ function normalizeError(err) {
 	};
 	return { message: String(err) };
 }
+//#endregion
+//#region src/events/subscribe-helpers.ts
 /**
-* Compute a `retryAt` `Date` using exponential backoff with jitter.
+* Subscribe-side helpers — close the symmetry that arc's publish-side
+* already has via [`eventPlugin({ registry, validateMode: 'reject' })`](./eventPlugin.ts).
 *
-* This is a convenience helper for store authors implementing
-* {@link OutboxStore.fail}: call it to compute the retry visibility window
-* based on the event's current attempt count.
+* Two wrapper pairs, both transport-agnostic:
 *
-* Formula: `delay = min(maxMs, baseMs * 2^(attempt - 1)) * (1 + random * jitter)`
+* - `wrapWithSchema` / `subscribeWithSchema` — read the schema from a
+*   typed `EventDefinitionOutput<T>` and validate `event.payload` before
+*   the handler runs. Single source of truth for event shape: declare
+*   once at `defineEvent`, enforced on BOTH sides without parallel Zod
+*   schemas in subscriber files.
 *
-* @example Basic usage inside a store's `fail()` method
-* ```typescript
-* async fail(eventId, error, options) {
-*   const entry = await this.findById(eventId);
-*   entry.attempts++;
-*   if (entry.attempts >= MAX_ATTEMPTS) {
-*     return this.deadLetter(eventId, error);
-*   }
-*   const retryAt = exponentialBackoff({ attempt: entry.attempts });
-*   entry.visibleAt = retryAt;
-*   await this.update(entry);
-* }
-* ```
+* - `wrapWithBoundary` / `subscribeWithBoundary` — catch + log + swallow
+*   handler errors, for projection / cache-invalidation / fire-and-forget
+*   handlers where retry would just delay the next-event resync. Lighter
+*   than `withRetry` (no DLQ, no exponential backoff) and avoids the
+*   "single bad event poisons the bus" hazard.
 *
-* @example Tuning for a faster transport
-* ```typescript
-* exponentialBackoff({ attempt: 3, baseMs: 250, maxMs: 10_000, jitter: 0.3 });
-* // attempt=1 → ~250ms   ±30%
-* // attempt=2 → ~500ms   ±30%
-* // attempt=3 → ~1000ms  ±30%
-* // attempt=10 → capped at 10_000ms
+* Both pairs compose with `withRetry` and with each other:
+*
+* ```ts
+* await subscribeWithSchema(
+*   fastify,
+*   OrderPaid,
+*   withRetry(handler, { maxRetries: 3 }),
+* );
 * ```
+*
+* @see [retry.ts](./retry.ts) for the retry + DLQ wrapper.
+* @see [defineEvent.ts](./defineEvent.ts) for `defineEvent` / `EventDefinitionOutput`.
 */
-function exponentialBackoff(options) {
-	const attempt = Math.max(1, Math.floor(options.attempt));
-	const baseMs = options.baseMs ?? 1e3;
-	const maxMs = options.maxMs ?? 6e4;
-	const jitter = Math.max(0, Math.min(1, options.jitter ?? .2));
-	const now = options.now ?? Date.now();
-	const exp = baseMs * 2 ** (attempt - 1);
-	const capped = Math.min(maxMs, exp);
-	const jittered = jitter > 0 ? capped * (1 + Math.random() * jitter) : capped;
-	return new Date(now + jittered);
-}
-//#endregion
-//#region src/events/subscribe-helpers.ts
 /**
 * Pure handler wrapper — returns a new `EventHandler` that validates
 * `event.payload` against the definition's schema before invoking the handler.
@@ -947,7 +1036,6 @@ function wrapWithSchema(definition, handler, options = {}) {
 		if (validate && definition.schema) result = validate(definition.schema, event.payload);
 		else if (registry) result = registry.validate(definition.name, event.payload, eventVersion);
 		else if (definition.schema) {
-			const { createEventRegistry } = await Promise.resolve().then(() => defineEvent_exports);
 			const adhoc = createEventRegistry();
 			adhoc.register(definition);
 			result = adhoc.validate(definition.name, event.payload);
@@ -1041,4 +1129,4 @@ async function subscribeWithBoundary(fastify, pattern, handler, options) {
 	return fastify.events.subscribe(pattern, wrapWithBoundary(handler, options));
 }
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, InvalidOutboxEventError, MemoryEventTransport, MemoryOutboxStore, OutboxOwnershipError, createDeadLetterPublisher, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };
+export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };

package/dist/events/transports/redis-stream-entry.d.mts

@@ -1,2 +1,2 @@
-import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-iVR2l7aS.mjs";
+import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-uIaauNpZ.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };

package/dist/events/transports/redis-stream-entry.mjs

@@ -50,6 +50,7 @@ var RedisStreamTransport = class {
 	consumer;
 	blockTimeMs;
 	batchSize;
+	processingConcurrency;
 	maxRetries;
 	claimTimeoutMs;
 	deadLetterStream;
@@ -92,6 +93,7 @@ var RedisStreamTransport = class {
 		this.consumer = options.consumer ?? `consumer-${crypto.randomUUID().slice(0, 8)}`;
 		this.blockTimeMs = options.blockTimeMs ?? 5e3;
 		this.batchSize = options.batchSize ?? 10;
+		this.processingConcurrency = Math.max(1, Math.floor(options.processingConcurrency ?? 1));
 		this.maxRetries = options.maxRetries ?? 5;
 		this.claimTimeoutMs = options.claimTimeoutMs ?? 3e4;
 		this.deadLetterStream = options.deadLetterStream ?? "arc:events:dlq";
@@ -218,7 +220,27 @@ var RedisStreamTransport = class {
 	async readNewMessages() {
 		const result = await this.redis.xreadgroup("GROUP", this.group, this.consumer, "COUNT", this.batchSize, "BLOCK", this.blockTimeMs, "STREAMS", this.stream, ">");
 		if (!result) return;
-		for (const [, entries] of result) for (const [messageId, fields] of entries) await this.processEntry(messageId, fields);
+		for (const [, entries] of result) await this.processEntries(entries);
+	}
+	/**
+	* Process a batch's entries with bounded concurrency
+	* (`processingConcurrency`, default 1 = strict order). Worker-pool over a
+	* shared index — at most N entries in flight, each entry's own handlers
+	* still sequential inside `processEntry`.
+	*/
+	async processEntries(entries) {
+		if (this.processingConcurrency <= 1) {
+			for (const [messageId, fields] of entries) await this.processEntry(messageId, fields);
+			return;
+		}
+		let next = 0;
+		const workers = Array.from({ length: Math.min(this.processingConcurrency, entries.length) }, async () => {
+			while (next < entries.length) {
+				const entry = entries[next++];
+				if (entry) await this.processEntry(entry[0], entry[1]);
+			}
+		});
+		await Promise.all(workers);
 	}
 	async claimPending() {
 		try {
@@ -234,7 +256,7 @@ var RedisStreamTransport = class {
 			if (overRetryIds.length > 0) await this.moveToDlq(overRetryIds);
 			if (staleIds.length > 0) {
 				const claimed = await this.redis.xclaim(this.stream, this.group, this.consumer, this.claimTimeoutMs, ...staleIds);
-				for (const [messageId, fields] of claimed) await this.processEntry(messageId, fields);
+				await this.processEntries(claimed);
 			}
 		} catch (err) {
 			this.logger.error("[RedisStreamTransport] claimPending error:", err);

package/dist/factory/index.d.mts

@@ -1,7 +1,7 @@
-import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-B4u10iOJ.mjs";
-import "../fastify-augmentation-g_f9omSc.mjs";
-import { a as AuthOption, c as CustomPluginAuthOption, d as preloadResourcesAsync, i as UnderPressureOptions, l as JwtAuthOption, n as MultipartOptions, o as BetterAuthOption, r as RawBodyOptions, s as CustomAuthenticatorOption, t as CreateAppOptions, u as preloadResources } from "../index-Ba10fdKp.mjs";
-import { b as HealthCheck } from "../versioning-D6PvCwpq.mjs";
+import { a as ModuleContribution, c as ResourceModule, h as HealthCheck, i as EventHandlerDefinition, l as loadResources, n as ArcModuleInput, o as LoadResourcesOptions, r as ArcModuleRegistry, s as ResourceLike, t as ArcModule } from "../types-Cu6vVJmh.mjs";
+import { a as orderModules, c as collectModuleScheduledJobs, i as resolveModule, l as collectModuleWorkflows, n as getModuleExports, o as subscribeModuleEventHandlers, r as resolveContribution, s as collectModuleHealthChecks, t as defineModule } from "../index-CZY4EGga.mjs";
+import "../fastify-augmentation-OzYGIiU1.mjs";
+import { a as RawBodyOptions, c as BetterAuthOption, d as JwtAuthOption, i as MultipartOptions, l as CustomAuthenticatorOption, n as preloadResourcesAsync, o as UnderPressureOptions, r as CreateAppOptions, s as AuthOption, t as preloadResources, u as CustomPluginAuthOption } from "../preloadResources-CM4uUaFv.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 //#region src/factory/createApp.d.ts
 /**
@@ -133,4 +133,4 @@ declare const testingPreset: Partial<CreateAppOptions>;
 declare const edgePreset: Partial<CreateAppOptions>;
 declare function getPreset(name: "production" | "development" | "testing" | "edge" | "worker"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcWorker, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CreateWorkerOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, type WorkerHealthOptions, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcWorker, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CreateWorkerOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type EventHandlerDefinition, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type ModuleContribution, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, type WorkerHealthOptions, collectModuleHealthChecks, collectModuleScheduledJobs, collectModuleWorkflows, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveContribution, resolveModule, subscribeModuleEventHandlers, testingPreset, toFetchHandler };

package/dist/factory/index.mjs

@@ -1,20 +1,42 @@
-import { a as edgePreset, c as testingPreset, d as getModuleExports, f as orderModules, h as preloadResourcesAsync, i as developmentPreset, l as workerPreset, m as preloadResources, n as createApp, o as getPreset, p as resolveModule, s as productionPreset, t as ArcFactory, u as defineModule } from "../createApp-CjOeWJ9_.mjs";
-import { t as healthPlugin } from "../health-ScyjIVo5.mjs";
+import { r as mergeHealthChecks, t as healthPlugin } from "../health-CB_m4S32.mjs";
+import { a as edgePreset, c as testingPreset, d as subscribeModuleEventHandlers, f as collectModuleHealthChecks, g as resolveModule, h as resolveContribution, i as developmentPreset, l as workerPreset, m as collectModuleWorkflows, n as createApp, o as getPreset, p as collectModuleScheduledJobs, s as productionPreset, t as ArcFactory, u as orderModules } from "../createApp-Du5G54TM.mjs";
+import { n as getModuleExports, t as defineModule } from "../module-_-M7C5ES.mjs";
 import { t as loadResources } from "../loadResources-DpU8pfjV.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-DSY5HGpS.mjs";
 //#region src/factory/createWorker.ts
 async function createWorker(options, workerOptions = {}) {
 	const { auth: _auth, helmet: _helmet, cors: _cors, rateLimit: _rateLimit, multipart: _multipart, rawBody: _rawBody, sensible: _sensible, underPressure: _underPressure, replyHelpers: _replyHelpers, ...runtimeOptions } = options;
+	const sharedHealth = typeof runtimeOptions.arcPlugins?.health === "object" && runtimeOptions.arcPlugins.health !== null ? runtimeOptions.arcPlugins.health : {};
+	const workerArcPlugins = {
+		...workerPreset.arcPlugins,
+		...runtimeOptions.arcPlugins,
+		...workerOptions.health ? { health: false } : {}
+	};
 	const app = await createApp({
 		...runtimeOptions,
 		preset: "worker",
-		...runtimeOptions.arcPlugins ? { arcPlugins: {
-			...workerPreset.arcPlugins,
-			...runtimeOptions.arcPlugins
-		} } : {}
+		arcPlugins: workerArcPlugins
 	});
 	if (workerOptions.health) {
 		const { port, host = "0.0.0.0", checks = [] } = workerOptions.health;
-		await app.register(healthPlugin, { checks });
+		const mergedChecks = mergeHealthChecks([
+			{
+				owner: "the module graph",
+				checks: app.arc?.healthChecks ?? []
+			},
+			{
+				owner: "shared arcPlugins.health",
+				checks: sharedHealth.checks
+			},
+			{
+				owner: "the worker probe",
+				checks
+			}
+		]);
+		await app.register(healthPlugin, {
+			...sharedHealth,
+			checks: mergedChecks
+		});
 		await app.listen({
 			port,
 			host
@@ -98,4 +120,4 @@ function payloadTooLarge(limit) {
 	});
 }
 //#endregion
-export { ArcFactory, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, collectModuleHealthChecks, collectModuleScheduledJobs, collectModuleWorkflows, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveContribution, resolveModule, subscribeModuleEventHandlers, testingPreset, toFetchHandler };

package/dist/{fastify-augmentation-g_f9omSc.d.mts → fastify-augmentation-OzYGIiU1.d.mts}

@@ -1,6 +1,7 @@
-import { xn as HookSystem, z as ResourceRegistry } from "./index-BBsvQt7U.mjs";
+import { mn as HookSystem, z as ResourceRegistry } from "./index-DPRH0Cme.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { r as ArcModuleRegistry } from "./module-B4u10iOJ.mjs";
+import { h as HealthCheck, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-Cu6vVJmh.mjs";
+import "./index-CZY4EGga.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/core/arcCorePlugin.d.ts
 interface ArcCorePluginOptions {
@@ -38,6 +39,29 @@ interface ArcCore {
    * Populated lazily by `registerResources` — absent until a module exports.
    */
   modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
+  /**
+   * Module-contributed readiness checks, collected in dependency order and
+   * frozen by `createApp`. The API role merges these into its `healthPlugin`;
+   * `createWorker` reads this to give its probe listener the identical union
+   * (the worker preset disables the main health plugin, so this is how module
+   * checks reach the probe without a double registration). Empty until
+   * `createApp` populates it.
+   */
+  healthChecks?: readonly HealthCheck[];
+  /**
+   * The resolved, dependency-ordered module definitions (frozen by createApp).
+   * Integrations that collect a module arm at their OWN init time — e.g. the
+   * streamline integration calling `collectModuleWorkflows(fastify, defs)` after
+   * it has created + decorated its container — read the list from here. Empty
+   * until createApp populates it.
+   */
+  moduleDefinitions?: readonly ArcModule[];
+  /**
+   * Module-contributed recurring schedules, resolved once in dependency order
+   * and frozen after bootstraps. The same definitions are executed by Arc's
+   * schedules plugin and exposed here for introspection. Empty until collection.
+   */
+  scheduledJobs?: readonly Readonly<ScheduleDefinition>[];
 }
 declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
 declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;

package/dist/{generate-usRSdQmP.mjs → generate-D0wZupBg.mjs}

@@ -334,7 +334,7 @@ export default crudSchemas;
 			const camel = toCamelCase(name);
 			const useMongoKit = config.adapter === "mongokit" || !config.adapter;
 			const schemaGeneratorImport = useMongoKit ? `import { buildCrudSchemasFromModel } from '@classytic/mongokit';\n` : "";
-			const queryParserImport = useMongoKit ? `\nimport { QueryParser } from '@classytic/mongokit';\n\nconst queryParser = new QueryParser({\n  // Whitelist the fields this resource accepts in URL filters.\n  // Empty by default — only \`createdAt\` is implicit; add yours.\n  allowedFilterFields: [],\n});\n` : "";
+			const queryParserImport = useMongoKit ? `\nimport { QueryParser } from '@classytic/mongokit';\n\n// Fail-closed by default (mongokit >=3.25): invalid/blocked query input →\n// HTTP 400 instead of silently broadening the result set.\nconst queryParser = new QueryParser({\n  // Whitelist the fields this resource accepts in URL filters.\n  // Empty by default — only \`createdAt\` is implicit; add yours.\n  allowedFilterFields: [],\n});\n` : "";
 			const adapterCall = useMongoKit ? `createMongooseAdapter({ model: ${name}, repository: ${camel}Repository, schemaGenerator: buildCrudSchemasFromModel })` : `createMongooseAdapter({ model: ${name}, repository: ${camel}Repository })`;
 			const queryParserConfig = useMongoKit ? `\n  queryParser,` : "";
 			return isMultiTenant ? `/**

package/dist/headers-BvlQSDMB.mjs

@@ -0,0 +1,45 @@
+import { u as ValidationError } from "./errors-DkO8Nk6-.mjs";
+//#region src/utils/headers.ts
+/**
+* Canonical header typing + accessor.
+*
+* Node/Fastify header values are `string | string[] | undefined` — repeated
+* headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+* `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+* adapter passes Fastify's headers object through unchanged, so `string[]`
+* CAN appear at runtime behind the narrower type (the declared type is
+* scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+* through {@link getHeader} instead of indexing — it's honest about arrays
+* and deterministic about duplicates.
+*/
+/**
+* Read a single header value. Lowercases the name (Node normalizes incoming
+* header names to lowercase) and returns the FIRST value when the header
+* was repeated.
+*
+* Duplicate policy: first-value is deterministic, but for security-sensitive
+* headers (authorization material, forwarded-for chains, content-length) a
+* duplicate usually signals smuggling or a broken proxy — consumers that
+* care should check `Array.isArray(headers[name])` and REJECT instead of
+* picking a winner.
+*/
+function getHeader(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+/**
+* Read an identity-bearing or protocol header and reject repeated values.
+*
+* Repeated security-sensitive headers are ambiguous at proxy boundaries and
+* may indicate request smuggling. Callers must not silently choose a winner.
+*/
+function requireSingleHeaderValue(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) throw new ValidationError(`Duplicate '${name}' header`);
+	return value;
+}
+//#endregion
+export { requireSingleHeaderValue as n, getHeader as t };