@classytic/arc 2.22.0 → 2.25.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.
 *
@@ -176,8 +172,11 @@ function validatePayload(payload, schema) {
 			for (const [key, propSchema] of Object.entries(schema.properties)) if (key in record && record[key] !== void 0 && record[key] !== null) {
 				const expectedType = propSchema.type;
 				if (expectedType) {
-					const actualType = Array.isArray(record[key]) ? "array" : typeof record[key];
-					if (expectedType !== actualType) errors.push(`Field '${key}': expected ${expectedType}, got ${actualType}`);
+					const value = record[key];
+					const actualType = Array.isArray(value) ? "array" : typeof value;
+					if (expectedType === "integer") {
+						if (actualType !== "number" || !Number.isInteger(value)) errors.push(`Field '${key}': expected integer, got ${actualType}`);
+					} else if (expectedType !== actualType) errors.push(`Field '${key}': expected ${expectedType}, got ${actualType}`);
 				}
 			}
 		}
@@ -240,6 +239,14 @@ 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 = [];
@@ -353,7 +360,110 @@ 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;
@@ -430,25 +540,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();
@@ -534,7 +645,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;
@@ -549,34 +660,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;
@@ -640,7 +723,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 ?? {},
@@ -723,11 +806,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) {
@@ -837,7 +923,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
 		};
 	}
 	/**
@@ -871,51 +959,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.
@@ -944,7 +1020,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);
@@ -1038,4 +1113,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,6 @@
-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-9_fuetB4.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-BEu4wjbL.mjs";
-import { g as HealthCheck } from "../versioning-DLwklPlG.mjs";
+import { _ as ResourceModule, a as orderModules, c as collectModuleScheduledJobs, d as ArcModuleInput, f as ArcModuleRegistry, g as ResourceLike, h as LoadResourcesOptions, i as resolveModule, l as collectModuleWorkflows, m as ModuleContribution, n as getModuleExports, o as subscribeModuleEventHandlers, p as EventHandlerDefinition, r as resolveContribution, s as collectModuleHealthChecks, t as defineModule, u as ArcModule, v as loadResources, w as HealthCheck } from "../index-KUoxjIq1.mjs";
+import "../fastify-augmentation-dPNBVeIj.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-0oe-JSSS.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 //#region src/factory/createApp.d.ts
 /**
@@ -64,15 +63,31 @@ interface FetchHandlerOptions {
    * @default true
    */
   autoReady?: boolean;
+  /**
+   * Reject request bodies larger than this many bytes with 413
+   * `arc.payload_too_large`. Enforcement precision matters: bodies with a
+   * declared `Content-Length` are rejected BEFORE buffering; chunked or
+   * undeclared bodies are necessarily buffered first and checked AFTER
+   * (`arrayBuffer()` allocates the full body — a consequence of the
+   * buffered-adapter design, not a bug). Platform/gateway body limits
+   * remain the real pre-allocation protection for hostile senders.
+   * Fastify's own `bodyLimit` still applies after this gate. Set to `0`
+   * to disable the gate.
+   * @default 1_048_576 (1 MiB — matches Fastify's default bodyLimit)
+   */
+  maxRequestBytes?: number;
 }
 /**
  * Convert a Fastify app into a Web Standards fetch handler.
  *
  * The returned function accepts a Web Standard `Request` and returns
- * a Web Standard `Response` — the universal serverless/edge contract.
+ * a Web Standard `Response` — the universal serverless contract.
  *
  * Internally uses `app.inject()` which processes the request through
  * the full Fastify pipeline (hooks, plugins, routes) without TCP.
+ * Bodies are read as raw bytes (`arrayBuffer()`), so binary payloads
+ * (protobuf, images, non-UTF-8 charsets) survive intact — the
+ * content-type parser decides how to decode, same as a real socket.
  */
 declare function toFetchHandler(app: FastifyInstance, options?: FetchHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
@@ -117,4 +132,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,40 @@
-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-Ci7yG5gv.mjs";
-import { t as healthPlugin } from "../health-ScyjIVo5.mjs";
+import { r as mergeHealthChecks, t as healthPlugin } from "../health-CB_m4S32.mjs";
+import { _ as collectModuleScheduledJobs, b as resolveModule, c as getPreset, d as workerPreset, f as defineModule, g as collectModuleHealthChecks, h as subscribeModuleEventHandlers, i as createApp, l as productionPreset, m as orderModules, n as preloadResourcesAsync, o as developmentPreset, p as getModuleExports, r as ArcFactory, s as edgePreset, t as preloadResources, u as testingPreset, v as collectModuleWorkflows, y as resolveContribution } from "../preloadResources-DfyngIN9.mjs";
 import { t as loadResources } from "../loadResources-DpU8pfjV.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
@@ -37,28 +57,37 @@ async function createWorker(options, workerOptions = {}) {
 * Convert a Fastify app into a Web Standards fetch handler.
 *
 * The returned function accepts a Web Standard `Request` and returns
-* a Web Standard `Response` — the universal serverless/edge contract.
+* a Web Standard `Response` — the universal serverless contract.
 *
 * Internally uses `app.inject()` which processes the request through
 * the full Fastify pipeline (hooks, plugins, routes) without TCP.
+* Bodies are read as raw bytes (`arrayBuffer()`), so binary payloads
+* (protobuf, images, non-UTF-8 charsets) survive intact — the
+* content-type parser decides how to decode, same as a real socket.
 */
 function toFetchHandler(app, options = {}) {
-	const { autoReady = true } = options;
-	let ready = false;
+	const { autoReady = true, maxRequestBytes = 1048576 } = options;
+	let readyPromise = null;
 	return async (request) => {
-		if (autoReady && !ready) {
-			await app.ready();
-			ready = true;
+		if (autoReady) {
+			readyPromise ??= Promise.resolve(app.ready());
+			await readyPromise;
 		}
 		const url = new URL(request.url);
 		const headers = {};
 		request.headers.forEach((value, key) => {
 			headers[key] = value;
 		});
+		if (maxRequestBytes > 0) {
+			const declared = Number(request.headers.get("content-length"));
+			if (Number.isFinite(declared) && declared > maxRequestBytes) return payloadTooLarge(maxRequestBytes);
+		}
 		let payload;
-		if (request.method !== "GET" && request.method !== "HEAD") try {
-			payload = await request.text();
-		} catch {}
+		if (request.method !== "GET" && request.method !== "HEAD" && request.body !== null) {
+			const bytes = await request.arrayBuffer();
+			if (maxRequestBytes > 0 && bytes.byteLength > maxRequestBytes) return payloadTooLarge(maxRequestBytes);
+			if (bytes.byteLength > 0) payload = Buffer.from(bytes);
+		}
 		const response = await app.inject({
 			method: request.method,
 			url: url.pathname + url.search,
@@ -71,11 +100,22 @@ function toFetchHandler(app, options = {}) {
 			if (Array.isArray(value)) for (const v of value) responseHeaders.append(key, v);
 			else responseHeaders.set(key, String(value));
 		}
-		return new Response(response.payload, {
+		return new Response(response.rawPayload, {
 			status: response.statusCode,
 			headers: responseHeaders
 		});
 	};
 }
+/** Canonical ErrorContract shape for the pre-dispatch 413. */
+function payloadTooLarge(limit) {
+	return new Response(JSON.stringify({
+		code: "arc.payload_too_large",
+		message: `Request body exceeds ${limit} bytes`,
+		status: 413
+	}), {
+		status: 413,
+		headers: { "content-type": "application/json" }
+	});
+}
 //#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-9_fuetB4.d.mts → fastify-augmentation-dPNBVeIj.d.mts}

@@ -1,6 +1,6 @@
-import { bn as HookSystem, z as ResourceRegistry } from "./index-DbtgCOCj.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 { f as ArcModuleRegistry, u as ArcModule, w as HealthCheck, y as ScheduleDefinition } from "./index-KUoxjIq1.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/core/arcCorePlugin.d.ts
 interface ArcCorePluginOptions {
@@ -38,6 +38,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 ? `/**