@classytic/arc 2.8.0 → 2.8.1

package/dist/events/index.mjs

@@ -1,4 +1,4 @@
-import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-x4jo3sG0.mjs";
+import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-XijlQmlL.mjs";
 //#region src/events/defineEvent.ts
 /**
 * defineEvent — Typed Event Definitions with Optional Schema Validation
@@ -224,52 +224,235 @@ const CACHE_EVENTS = Object.freeze({
 });
 //#endregion
 //#region src/events/outbox.ts
-/** Default outbox retention — acknowledged events older than this are eligible for purge */
+/** 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;
+/**
+* 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;
 	_batchSize;
+	_consumerId;
+	_leaseMs;
+	_onError;
+	_usePublishMany;
 	constructor(opts) {
 		this._store = opts.store;
 		this._transport = opts.transport;
 		this._batchSize = opts.batchSize ?? 100;
+		this._consumerId = opts.consumerId ?? `relay-${Math.random().toString(36).slice(2, 10)}`;
+		this._leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS;
+		this._onError = opts.onError;
+		this._usePublishMany = opts.usePublishMany ?? true;
+	}
+	/** Unique consumer ID used for lease ownership when the store supports claims */
+	get consumerId() {
+		return this._consumerId;
 	}
-	/** Store event in outbox (call within your DB transaction) */
-	async store(event) {
-		await this._store.save(event);
+	/**
+	* Store event in outbox.
+	*
+	* Validates that `event.type` and `event.meta.id` are present — throws
+	* {@link InvalidOutboxEventError} otherwise, so corrupt rows can never
+	* be persisted via this API.
+	*
+	* Pass `options.session` to participate in a host-managed DB transaction
+	* (store must support session-aware writes). Other options (`visibleAt`,
+	* `dedupeKey`, `partitionKey`, `headers`) are forwarded to stores that
+	* implement them and ignored otherwise.
+	*/
+	async store(event, options) {
+		if (!event || typeof event !== "object") throw new InvalidOutboxEventError("event is not an object");
+		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");
+		await this._store.save(event, options);
+	}
+	_reportError(kind, error, event) {
+		if (!this._onError) return;
+		const err = error instanceof Error ? error : new Error(String(error));
+		try {
+			this._onError({
+				kind,
+				event,
+				error: err
+			});
+		} catch {}
 	}
 	/**
-	* Relay pending events to transport.
+	* Relay pending events to transport and return the number of successful
+	* publish+acknowledge pairs.
 	*
-	* Processes events in FIFO order up to `batchSize`. Stops on the first
-	* transport failure — remaining events stay pending for the next relay call.
+	* For richer observability (per-kind counts, publishMany detection, etc.)
+	* use {@link relayBatch} which returns a {@link RelayResult}. This method
+	* is the backward-compatible shortcut that returns just the count.
 	*
-	* @returns Number of successfully published events in this batch
+	* @returns Number of successfully published AND acknowledged events
 	*/
 	async relay() {
-		if (!this._transport) return 0;
-		const pending = await this._store.getPending(this._batchSize);
-		let relayed = 0;
+		return (await this.relayBatch()).relayed;
+	}
+	/**
+	* Relay a batch of pending events to the transport and return a rich
+	* {@link RelayResult} describing the outcome of each event.
+	*
+	* Behavior summary:
+	*
+	* - **Claim path**: uses {@link OutboxStore.claimPending} when the store
+	*   supports it (safe for multi-worker relay) or falls back to
+	*   {@link OutboxStore.getPending} (single-worker only).
+	*
+	* - **Publish path**: if the transport implements
+	*   {@link EventTransport.publishMany} and `usePublishMany` is not disabled,
+	*   the entire batch is sent in one call. Otherwise each event is published
+	*   individually. Either way, per-event outcomes are tracked.
+	*
+	* - **Failure path**: if the store implements `fail`, per-event failures
+	*   are reported via `store.fail(...)` and the batch continues. Without
+	*   `fail`, the batch stops on the first failure (legacy behavior).
+	*
+	* - **Malformed events**: events missing `type` or `meta.id` abort the
+	*   batch — a well-behaved store must never return them (see
+	*   {@link OutboxStore} semantics #6). The error is reported via `onError`.
+	*
+	* - **Ownership mismatches**: if `acknowledge`/`fail` throws
+	*   {@link OutboxOwnershipError} (our lease expired and another worker
+	*   claimed the event), the event is NOT counted as relayed. The other
+	*   worker will re-publish — at-least-once semantics preserved.
+	*
+	* @returns Per-kind outcome counts for the batch
+	*/
+	async relayBatch() {
+		const empty = {
+			relayed: 0,
+			attempted: 0,
+			publishFailed: 0,
+			ackFailed: 0,
+			ownershipMismatches: 0,
+			malformed: 0,
+			failHookErrors: 0,
+			usedPublishMany: false
+		};
+		if (!this._transport) return empty;
+		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 valid = [];
+		let malformed = 0;
 		for (const event of pending) {
-			if (!event.type || !event.meta?.id) {
-				if (event.meta?.id) await this._store.acknowledge(event.meta.id);
+			if (!event || !event.type || !event.meta?.id) {
+				this._reportError("malformed_event", new InvalidOutboxEventError("store returned event missing type or meta.id — batch aborted"), event);
+				malformed++;
+				break;
+			}
+			valid.push(event);
+		}
+		const counts = {
+			relayed: 0,
+			publishFailed: 0,
+			ackFailed: 0,
+			ownershipMismatches: 0,
+			failHookErrors: 0
+		};
+		const canPublishMany = this._usePublishMany && typeof this._transport.publishMany === "function";
+		const canFail = typeof this._store.fail === "function";
+		let publishOutcomes;
+		if (canPublishMany && valid.length > 0) try {
+			const result = await this._transport.publishMany(valid);
+			publishOutcomes = new Map(result);
+		} catch (batchErr) {
+			publishOutcomes = /* @__PURE__ */ new Map();
+			const err = batchErr instanceof Error ? batchErr : new Error(String(batchErr));
+			for (const ev of valid) publishOutcomes.set(ev.meta.id, err);
+		}
+		else {
+			publishOutcomes = /* @__PURE__ */ new Map();
+			for (const event of valid) try {
+				await this._transport.publish(event);
+				publishOutcomes.set(event.meta.id, null);
+			} catch (err) {
+				publishOutcomes.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+				if (!canFail) break;
+			}
+		}
+		let stopBatch = false;
+		for (const event of valid) {
+			if (stopBatch) break;
+			const publishErr = publishOutcomes.get(event.meta.id);
+			if (publishErr instanceof Error) {
+				counts.publishFailed++;
+				this._reportError("publish_failed", publishErr, event);
+				if (!canFail) {
+					stopBatch = true;
+					continue;
+				}
+				try {
+					await this._store.fail(event.meta.id, normalizeError(publishErr), { consumerId: this._consumerId });
+				} catch (failErr) {
+					if (failErr instanceof OutboxOwnershipError) {
+						counts.ownershipMismatches++;
+						this._reportError("ownership_mismatch", failErr, event);
+					} else {
+						counts.failHookErrors++;
+						this._reportError("fail_failed", failErr, event);
+					}
+				}
 				continue;
 			}
 			try {
-				await this._transport.publish(event);
-				await this._store.acknowledge(event.meta.id);
-				relayed++;
-			} catch {
-				break;
+				await this._store.acknowledge(event.meta.id, { consumerId: this._consumerId });
+				counts.relayed++;
+			} catch (ackErr) {
+				counts.ackFailed++;
+				if (ackErr instanceof OutboxOwnershipError) {
+					counts.ownershipMismatches++;
+					this._reportError("ownership_mismatch", ackErr, event);
+				} else this._reportError("acknowledge_failed", ackErr, event);
 			}
 		}
-		return relayed;
+		return {
+			relayed: counts.relayed,
+			attempted: valid.length,
+			publishFailed: counts.publishFailed,
+			ackFailed: counts.ackFailed,
+			ownershipMismatches: counts.ownershipMismatches,
+			malformed,
+			failHookErrors: counts.failHookErrors,
+			usedPublishMany: canPublishMany && valid.length > 0
+		};
 	}
 	/**
-	* Purge old acknowledged events from the outbox store.
+	* Purge old **delivered** events from the outbox store.
 	* Delegates to `store.purge()` if implemented; no-op otherwise.
-	* @param olderThanMs - Remove events acknowledged more than this many ms ago (default: 7 days)
+	* @param olderThanMs - Remove events delivered more than this many ms ago (default: 7 days)
 	* @returns Number of purged events, or 0 if store doesn't support purge
 	*/
 	async purge(olderThanMs = DEFAULT_OUTBOX_RETENTION_MS) {
@@ -277,17 +460,150 @@ var EventOutbox = class {
 		return this._store.purge(olderThanMs);
 	}
 };
+function normalizeError(err) {
+	if (err instanceof Error) return {
+		message: err.message,
+		code: err.code
+	};
+	return { message: String(err) };
+}
+/**
+* In-memory outbox store — reference implementation supporting the full
+* capability set (claim/lease, fail/retry, dedupe, visibleAt).
+*
+* For dev/testing only. Production deployments should use a durable store
+* backed by the app's database.
+*/
 var MemoryOutboxStore = class {
-	events = [];
-	async save(event) {
-		this.events.push(event);
+	entries = [];
+	seenDedupeKeys = /* @__PURE__ */ new Set();
+	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");
+		if (options?.dedupeKey) {
+			if (this.seenDedupeKeys.has(options.dedupeKey)) return;
+			this.seenDedupeKeys.add(options.dedupeKey);
+		}
+		this.entries.push({
+			event,
+			status: "pending",
+			attempts: 0,
+			visibleAt: options?.visibleAt?.getTime() ?? 0,
+			leaseOwner: null,
+			leaseExpiresAt: 0,
+			deliveredAt: null,
+			lastError: null,
+			dedupeKey: options?.dedupeKey
+		});
 	}
 	async getPending(limit) {
-		return this.events.slice(0, limit);
+		const now = Date.now();
+		return this.entries.filter((e) => e.status === "pending" && e.visibleAt <= now && (e.leaseOwner === null || e.leaseExpiresAt <= now)).slice(0, limit).map((e) => e.event);
 	}
-	async acknowledge(eventId) {
-		this.events = this.events.filter((e) => e.meta.id !== eventId);
+	async claimPending(options) {
+		const now = Date.now();
+		const limit = options?.limit ?? 100;
+		const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS;
+		const consumerId = options?.consumerId ?? "anonymous";
+		const typeFilter = options?.types ? new Set(options.types) : null;
+		const claimed = [];
+		for (const entry of this.entries) {
+			if (claimed.length >= limit) break;
+			if (entry.status !== "pending") continue;
+			if (entry.visibleAt > now) continue;
+			if (entry.leaseOwner !== null && entry.leaseExpiresAt > now) continue;
+			if (typeFilter && !typeFilter.has(entry.event.type)) continue;
+			entry.leaseOwner = consumerId;
+			entry.leaseExpiresAt = now + leaseMs;
+			entry.attempts++;
+			claimed.push(entry.event);
+		}
+		return claimed;
+	}
+	async acknowledge(eventId, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (entry.status === "delivered") return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		entry.status = "delivered";
+		entry.deliveredAt = Date.now();
+		entry.leaseOwner = null;
+	}
+	async fail(eventId, error, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		entry.lastError = error;
+		entry.leaseOwner = null;
+		entry.leaseExpiresAt = 0;
+		if (options?.deadLetter) {
+			entry.status = "dead_letter";
+			return;
+		}
+		entry.status = "pending";
+		entry.visibleAt = options?.retryAt ? options.retryAt.getTime() : 0;
+	}
+	async purge(olderThanMs) {
+		const cutoff = Date.now() - olderThanMs;
+		let purged = 0;
+		for (let i = this.entries.length - 1; i >= 0; i--) {
+			const entry = this.entries[i];
+			if (!entry) continue;
+			if (entry.status === "delivered" && entry.deliveredAt !== null && entry.deliveredAt < cutoff) {
+				if (entry.dedupeKey) this.seenDedupeKeys.delete(entry.dedupeKey);
+				this.entries.splice(i, 1);
+				purged++;
+			}
+		}
+		return purged;
+	}
+	/** Test helper: inspect entry by id */
+	_getEntry(eventId) {
+		return this.entries.find((e) => e.event.meta.id === eventId);
 	}
 };
+/**
+* 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
-export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, withRetry };
+export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, InvalidOutboxEventError, MemoryEventTransport, MemoryOutboxStore, OutboxOwnershipError, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, withRetry };

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-CF1lrKVk.mjs";
+import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-BgrYzpeq.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };

package/dist/events/transports/redis.d.mts

@@ -1,4 +1,4 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "../../EventTransport-n1KBxC_N.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "../../EventTransport-CLXJUzyT.mjs";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {

package/dist/factory/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as loadResources, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-gUxAIZHp.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as loadResources, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-BlOuKTPw.mjs";
 import { FastifyInstance } from "fastify";
 
 //#region src/factory/createApp.d.ts

package/dist/factory/index.mjs

@@ -1,4 +1,4 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-Cy8eUNKQ.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-p2OThysU.mjs";
 import { readdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as defineHook, Sn as createHookSystem, _n as afterDelete, bn as beforeDelete, cn as DefineHookOptions, dn as HookOperation, fn as HookPhase, gn as afterCreate, hn as HookSystemOptions, ln as HookContext, mn as HookSystem, pn as HookRegistration, un as HookHandler, vn as afterUpdate, xn as beforeUpdate, yn as beforeCreate } from "../interface-IJqN3pXK.mjs";
+import { An as beforeCreate, Cn as HookPhase, Dn as afterCreate, En as HookSystemOptions, Mn as beforeUpdate, Nn as createHookSystem, On as afterDelete, Pn as defineHook, Sn as HookOperation, Tn as HookSystem, bn as HookContext, jn as beforeDelete, kn as afterUpdate, wn as HookRegistration, xn as HookHandler, yn as DefineHookOptions } from "../interface-CS6d7HiB.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/{index-BpMhrFgn.d.mts → index-0zj73o2U.d.mts}

@@ -1,4 +1,4 @@
-import { Y as OpenApiSchemas, Yt as CrudRepository, Z as ParsedQuery, c as ValidationResult, n as AdapterSchemaContext, nt as QueryParserInterface, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, vt as RouteSchemaOptions } from "./interface-IJqN3pXK.mjs";
+import { Y as OpenApiSchemas, Z as ParsedQuery, Zt as CrudRepository, c as ValidationResult, n as AdapterSchemaContext, nt as QueryParserInterface, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, vt as RouteSchemaOptions } from "./interface-CS6d7HiB.mjs";
 import { Model } from "mongoose";
 
 //#region src/adapters/mongoose.d.ts

package/dist/{index-qct60lnl.d.mts → index-DadoLP51.d.mts}

@@ -1,5 +1,5 @@
 import { r as RequestScope } from "./types-CN6JvmYz.mjs";
-import { D as CrudRouterOptions, Ht as IControllerResponse, N as FastifyWithDecorators, T as CrudController, Ut as IRequestContext, Vt as IController, ct as RequestWithExtras, m as AnyRecord, ot as RequestContext, qt as ResourceDefinition, ut as ResourceConfig } from "./interface-IJqN3pXK.mjs";
+import { D as CrudRouterOptions, Ht as IControllerResponse, N as FastifyWithDecorators, T as CrudController, Ut as IRequestContext, Vt as IController, ct as RequestWithExtras, m as AnyRecord, ot as RequestContext, qt as ResourceDefinition, ut as ResourceConfig } from "./interface-CS6d7HiB.mjs";
 import { t as PermissionCheck } from "./types-BoaZHr-2.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
@@ -80,8 +80,40 @@ interface ActionRouterConfig {
    */
   readonly actionPermissions?: Record<string, PermissionCheck>;
   /**
-   * Per-action JSON schema for body validation
-   * @example { dispatch: { transport: { type: 'object' } } }
+   * Per-action schema for body validation.
+   *
+   * Accepted shapes per action:
+   *
+   * 1. **Full JSON Schema object** with `type: 'object'`, `properties`, `required` —
+   *    used verbatim. Required fields ARE enforced by Fastify's AJV.
+   *
+   * 2. **Zod v4 schema** — auto-converted via `z.toJSONSchema()`. Required fields
+   *    ARE enforced.
+   *
+   * 3. **Legacy field map** `{ fieldName: { type: 'string' } }` — each key becomes
+   *    a property and is treated as REQUIRED unless the property schema has
+   *    `nullable: true` or Arc's sentinel `required: false`. Kept for back-compat.
+   *
+   * All shapes are compiled into a single `oneOf` discriminator body schema
+   * so AJV can validate action-specific required fields at the HTTP layer.
+   *
+   * @example JSON Schema
+   * ```ts
+   * actionSchemas: {
+   *   dispatch: {
+   *     type: 'object',
+   *     properties: { carrier: { type: 'string' } },
+   *     required: ['carrier'],
+   *   },
+   * }
+   * ```
+   *
+   * @example Zod v4
+   * ```ts
+   * actionSchemas: {
+   *   dispatch: z.object({ carrier: z.string() }),
+   * }
+   * ```
    */
   readonly actionSchemas?: Record<string, Record<string, unknown>>;
   /**

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as PresetFunction, $t as QueryOptions, At as BaseController, B as InferResourceDoc, C as ConfigError, Ct as TypedResourceConfig, D as CrudRouterOptions, Dt as ValidationResult$1, E as CrudRouteKey, Et as ValidateOptions, F as GracefulShutdownOptions, H as IntrospectionPluginOptions, Ht as IControllerResponse, I as HealthCheck, Jt as defineResource, K as MiddlewareConfig, L as HealthOptions, M as FastifyWithAuth, N as FastifyWithDecorators, O as CrudSchemas, Ot as envelope, P as FieldRule, R as InferAdapterDoc, St as TypedRepository, T as CrudController, Tt as UserOrganization, U as JWTPayload, Ut as IRequestContext, V as IntrospectionData, Vt as IController, Wt as RouteHandler, X as OwnershipCheck, Yt as CrudRepository, Zt as PaginatedResult, _ as ArcInternalMetadata, a as RelationMetadata, an as PipelineContext, at as RegistryStats, b as AuthPluginOptions, c as ValidationResult, ct as RequestWithExtras, en as Guard, gt as RouteHandlerMethod, h as ApiResponse, i as FieldMetadata, in as PipelineConfig, it as RegistryEntry, j as FastifyRequestExtras, jt as BaseControllerOptions, k as EventDefinition, m as AnyRecord, nn as NextFunction, o as RepositoryLike, on as PipelineStep, ot as RequestContext, p as AdditionalRoute, pt as ResourceMetadata, q as MiddlewareHandler, qt as ResourceDefinition, r as DataAdapter, rn as OperationFilter, rt as RateLimitConfig, s as SchemaMetadata, sn as Transform, st as RequestIdOptions, tn as Interceptor, tt as PresetResult, ut as ResourceConfig, v as ArcRequest, vt as RouteSchemaOptions, xt as TypedController, yt as ServiceContext, z as InferDocType, zt as ControllerLike } from "./interface-IJqN3pXK.mjs";
+import { $ as PresetFunction, $t as DeleteOptions, At as BaseController, B as InferResourceDoc, C as ConfigError, Ct as TypedResourceConfig, D as CrudRouterOptions, Dt as ValidationResult$1, E as CrudRouteKey, Et as ValidateOptions, F as GracefulShutdownOptions, H as IntrospectionPluginOptions, Ht as IControllerResponse, I as HealthCheck, Jt as defineResource, K as MiddlewareConfig, L as HealthOptions, M as FastifyWithAuth, N as FastifyWithDecorators, O as CrudSchemas, Ot as envelope, P as FieldRule, Qt as DeleteManyResult, R as InferAdapterDoc, St as TypedRepository, T as CrudController, Tt as UserOrganization, U as JWTPayload, Ut as IRequestContext, V as IntrospectionData, Vt as IController, Wt as RouteHandler, X as OwnershipCheck, Xt as BulkWriteResult, Yt as BulkWriteOperation, Zt as CrudRepository, _ as ArcInternalMetadata, _n as PipelineStep, a as RelationMetadata, an as PaginationParams, at as RegistryStats, b as AuthPluginOptions, c as ValidationResult, cn as RepositorySession, ct as RequestWithExtras, dn as Guard, en as DeleteResult, fn as Interceptor, gn as PipelineContext, gt as RouteHandlerMethod, h as ApiResponse, hn as PipelineConfig, i as FieldMetadata, in as PaginatedResult, it as RegistryEntry, j as FastifyRequestExtras, jt as BaseControllerOptions, k as EventDefinition, ln as UpdateManyResult, m as AnyRecord, mn as OperationFilter, nn as KeysetPaginatedResult, o as RepositoryLike, on as PaginationResult, ot as RequestContext, p as AdditionalRoute, pn as NextFunction, pt as ResourceMetadata, q as MiddlewareHandler, qt as ResourceDefinition, r as DataAdapter, rn as OffsetPaginatedResult, rt as RateLimitConfig, s as SchemaMetadata, sn as QueryOptions, st as RequestIdOptions, tt as PresetResult, un as WriteOptions, ut as ResourceConfig, v as ArcRequest, vn as Transform, vt as RouteSchemaOptions, xt as TypedController, yt as ServiceContext, z as InferDocType, zt as ControllerLike } from "./interface-CS6d7HiB.mjs";
 import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, t as FieldPermission } from "./fields-DoeDgh2b.mjs";
 import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-BoaZHr-2.mjs";
-import { l as createMongooseAdapter, o as createPrismaAdapter, s as MongooseAdapter, t as PrismaAdapter } from "./index-BpMhrFgn.mjs";
-import { A as MutationOperation, C as HOOK_PHASES, D as MAX_REGEX_LENGTH, E as MAX_FILTER_DEPTH, M as SYSTEM_FIELDS, O as MAX_SEARCH_LENGTH, S as HOOK_OPERATIONS, T as HookPhase, _ as DEFAULT_LIMIT, a as getControllerScope, b as DEFAULT_TENANT_FIELD, g as DEFAULT_ID_FIELD, h as CrudOperation, j as RESERVED_QUERY_PARAMS, k as MUTATION_OPERATIONS, m as CRUD_OPERATIONS, s as defineResourceVariants, v as DEFAULT_MAX_LIMIT, w as HookOperation, x as DEFAULT_UPDATE_METHOD, y as DEFAULT_SORT } from "./index-qct60lnl.mjs";
+import { l as createMongooseAdapter, o as createPrismaAdapter, s as MongooseAdapter, t as PrismaAdapter } from "./index-0zj73o2U.mjs";
+import { A as MutationOperation, C as HOOK_PHASES, D as MAX_REGEX_LENGTH, E as MAX_FILTER_DEPTH, M as SYSTEM_FIELDS, O as MAX_SEARCH_LENGTH, S as HOOK_OPERATIONS, T as HookPhase, _ as DEFAULT_LIMIT, a as getControllerScope, b as DEFAULT_TENANT_FIELD, g as DEFAULT_ID_FIELD, h as CrudOperation, j as RESERVED_QUERY_PARAMS, k as MUTATION_OPERATIONS, m as CRUD_OPERATIONS, s as defineResourceVariants, v as DEFAULT_MAX_LIMIT, w as HookOperation, x as DEFAULT_UPDATE_METHOD, y as DEFAULT_SORT } from "./index-DadoLP51.mjs";
 import { C as authenticated, D as publicRead, E as presets_d_exports, O as publicReadAdminWrite, S as adminOnly, T as ownerWithAdminBypass, _ as requireScopeContext, a as allOf, c as createDynamicPermissionMatrix, d as requireAuth, f as requireOrgInScope, g as requireRoles, h as requireOwnership, k as readOnly, l as createOrgPermissions, m as requireOrgRole, n as DynamicPermissionMatrix, o as allowPublic, p as requireOrgMembership, r as DynamicPermissionMatrixConfig, s as anyOf, u as denyAll, v as requireServiceScope, w as fullPublic, x as when, y as requireTeamMembership } from "./index-CBru2y5Y.mjs";
 import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-BI8kEKsO.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -253,4 +253,4 @@ declare function arcLog(module: string): ArcLogger;
 //#region src/index.d.ts
 declare const version: string;
 //#endregion
-export { type ValidationResult as AdapterValidationResult, type AdditionalRoute, type AnyRecord, type ApiResponse, ArcError, type ArcInternalMetadata, type ArcLogWriter, type ArcLogger, type ArcLoggerOptions, type ArcRequest, type AuthPluginOptions, BaseController, type BaseControllerOptions, CRUD_OPERATIONS, type ConfigError, type ControllerLike, type CrudController, CrudOperation, type CrudRepository, type CrudRouteKey, type CrudRouterOptions, type CrudSchemas, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DataAdapter, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type EventDefinition, type FastifyRequestExtras, type FastifyWithAuth, type FastifyWithDecorators, type FieldMetadata, type FieldPermission, type FieldPermissionMap, type FieldRule, ForbiddenError, type GracefulShutdownOptions, type Guard, HOOK_OPERATIONS, HOOK_PHASES, type HealthCheck, type HealthOptions, HookOperation, HookPhase, type IController, type IControllerResponse, type IRequestContext, type InferAdapterDoc, type InferDocType, type InferResourceDoc, type Interceptor, type IntrospectionData, type IntrospectionPluginOptions, type JWTPayload, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, type MiddlewareConfig, MongooseAdapter, MutationOperation, type NamedMiddleware, NotFoundError, type OwnershipCheck, type PaginatedResult, type PermissionCheck, type PermissionContext, type PermissionResult, type PipelineConfig, type PipelineContext, type PipelineStep, type PresetFunction, type PresetResult, PrismaAdapter, type QueryOptions, RESERVED_QUERY_PARAMS, type RateLimitConfig, type RegistryEntry, type RegistryStats, type RelationMetadata, type RepositoryLike, type RequestContext, type RequestIdOptions, type RequestStore, type RequestWithExtras, type ResourceConfig, ResourceDefinition, type ResourceMetadata, type RouteHandler, type RouteHandlerMethod, type RouteSchemaOptions, SYSTEM_FIELDS, type SchemaMetadata, type ServiceContext, type Transform, type TypedController, type TypedRepository, type TypedResourceConfig, UnauthorizedError, type UserBase, type UserOrganization, type ValidateOptions, ValidationError, type ValidationResult$1 as ValidationResult, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_d_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };
+export { type ValidationResult as AdapterValidationResult, type AdditionalRoute, type AnyRecord, type ApiResponse, ArcError, type ArcInternalMetadata, type ArcLogWriter, type ArcLogger, type ArcLoggerOptions, type ArcRequest, type AuthPluginOptions, BaseController, type BaseControllerOptions, type BulkWriteOperation, type BulkWriteResult, CRUD_OPERATIONS, type ConfigError, type ControllerLike, type CrudController, CrudOperation, type CrudRepository, type CrudRouteKey, type CrudRouterOptions, type CrudSchemas, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DataAdapter, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type EventDefinition, type FastifyRequestExtras, type FastifyWithAuth, type FastifyWithDecorators, type FieldMetadata, type FieldPermission, type FieldPermissionMap, type FieldRule, ForbiddenError, type GracefulShutdownOptions, type Guard, HOOK_OPERATIONS, HOOK_PHASES, type HealthCheck, type HealthOptions, HookOperation, HookPhase, type IController, type IControllerResponse, type IRequestContext, type InferAdapterDoc, type InferDocType, type InferResourceDoc, type Interceptor, type IntrospectionData, type IntrospectionPluginOptions, type JWTPayload, type KeysetPaginatedResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, type MiddlewareConfig, MongooseAdapter, MutationOperation, type NamedMiddleware, NotFoundError, type OffsetPaginatedResult, type OwnershipCheck, type PaginatedResult, type PaginationParams, type PaginationResult, type PermissionCheck, type PermissionContext, type PermissionResult, type PipelineConfig, type PipelineContext, type PipelineStep, type PresetFunction, type PresetResult, PrismaAdapter, type QueryOptions, RESERVED_QUERY_PARAMS, type RateLimitConfig, type RegistryEntry, type RegistryStats, type RelationMetadata, type RepositoryLike, type RepositorySession, type RequestContext, type RequestIdOptions, type RequestStore, type RequestWithExtras, type ResourceConfig, ResourceDefinition, type ResourceMetadata, type RouteHandler, type RouteHandlerMethod, type RouteSchemaOptions, SYSTEM_FIELDS, type SchemaMetadata, type ServiceContext, type Transform, type TypedController, type TypedRepository, type TypedResourceConfig, UnauthorizedError, type UpdateManyResult, type UserBase, type UserOrganization, type ValidateOptions, ValidationError, type ValidationResult$1 as ValidationResult, type WriteOptions, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_d_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-Cxde4rpC.mjs";
-import { a as createMongooseAdapter, i as MongooseAdapter, r as createPrismaAdapter, t as PrismaAdapter } from "./adapters-BxGgSHjj.mjs";
-import { t as BaseController } from "./BaseController-CpMfCXdn.mjs";
+import { a as createMongooseAdapter, i as MongooseAdapter, r as createPrismaAdapter, t as PrismaAdapter } from "./adapters-BBqAVvPK.mjs";
+import { t as BaseController } from "./BaseController-DAGGc5Xn.mjs";
 import { envelope } from "./types/index.mjs";
 import { n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "./fields-ipsbIRPK.mjs";
-import { t as requestContext } from "./requestContext-xHIKedG6.mjs";
-import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-Cg58SLNi.mjs";
-import { a as validateResourceConfig, f as getControllerScope, i as formatValidationErrors, m as pipe, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-CovBXvTB.mjs";
+import { t as requestContext } from "./requestContext-DYvHl113.mjs";
+import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-BF2bIOIS.mjs";
+import { a as validateResourceConfig, f as getControllerScope, i as formatValidationErrors, m as pipe, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-CqeUltrW.mjs";
 import { C as publicRead, S as presets_exports, T as readOnly, _ as when, a as createOrgPermissions, b as fullPublic, c as requireOrgInScope, d as requireOwnership, f as requireRoles, h as requireTeamMembership, i as createDynamicPermissionMatrix, l as requireOrgMembership, m as requireServiceScope, n as allowPublic, o as denyAll, p as requireScopeContext, r as anyOf, s as requireAuth, t as allOf, u as requireOrgRole, v as adminOnly, w as publicReadAdminWrite, x as ownerWithAdminBypass, y as authenticated } from "./permissions-CH4cNwJi.mjs";
-import { t as defineResourceVariants } from "./core-BfrfxNqO.mjs";
+import { t as defineResourceVariants } from "./core-CrLDuqoT.mjs";
 import { n as configureArcLogger, t as arcLog } from "./logger-CDjpjySd.mjs";
 //#region src/middleware/middleware.ts
 /**
@@ -128,6 +128,6 @@ function transform(name, handlerOrOptions) {
 }
 //#endregion
 //#region src/index.ts
-const version = "2.8.0";
+const version = "2.8.1";
 //#endregion
 export { ArcError, BaseController, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MongooseAdapter, NotFoundError, PrismaAdapter, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/integrations/event-gateway.d.mts

@@ -1,4 +1,4 @@
-import { t as DomainEvent } from "../EventTransport-n1KBxC_N.mjs";
+import { t as DomainEvent } from "../EventTransport-CLXJUzyT.mjs";
 import { WebSocketClient, WebSocketMessage } from "./websocket.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
 import { WebSocketClient, WebSocketMessage, WebSocketPluginOptions } from "./websocket.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-Ct0PUUSp.mjs";
+import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-D3b7hA00.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/mcp/index.d.mts

@@ -1,5 +1,5 @@
-import { qt as ResourceDefinition } from "../../interface-IJqN3pXK.mjs";
-import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-Ct0PUUSp.mjs";
+import { qt as ResourceDefinition } from "../../interface-CS6d7HiB.mjs";
+import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-D3b7hA00.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
 

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-C_1SMiCz.mjs";
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-DNNWnZtx.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/integrations/mcp/definePrompt.ts

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { o as McpAuthResult, s as McpPluginOptions } from "../../types-Ct0PUUSp.mjs";
+import { o as McpAuthResult, s as McpPluginOptions } from "../../types-D3b7hA00.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-C_1SMiCz.mjs";
+import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-DNNWnZtx.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities