@classytic/arc 2.11.2 → 2.11.4

package/dist/defineEvent-D1Ky9M1D.mjs

@@ -0,0 +1,188 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { r as createEvent } from "./EventTransport-BFQjw9pB.mjs";
+//#region src/events/defineEvent.ts
+/**
+* defineEvent — Typed Event Definitions with Optional Schema Validation
+*
+* Provides:
+* 1. defineEvent() — declare an event with name, schema, version, description
+* 2. EventRegistry — catalog of all known events + payload validation
+* 3. .create() helper — build DomainEvent with auto-generated metadata
+*
+* The built-in validator checks: object type, required fields, and top-level
+* property types. It does NOT recurse into nested objects, validate arrays,
+* enums, patterns, formats, or $ref. This is intentional — it's a lightweight
+* guard, not a full JSON Schema engine.
+*
+* For full validation, pass a custom `validate` function to `createEventRegistry()`:
+*
+* @example
+* ```typescript
+* import Ajv from 'ajv';
+* const ajv = new Ajv();
+*
+* const registry = createEventRegistry({
+*   validate: (schema, payload) => {
+*     const valid = ajv.validate(schema, payload);
+*     return valid
+*       ? { valid: true }
+*       : { valid: false, errors: ajv.errorsText().split(', ') };
+*   },
+* });
+* ```
+*
+* @example
+* ```typescript
+* import { defineEvent, createEventRegistry } from '@classytic/arc/events';
+*
+* const OrderCreated = defineEvent({
+*   name: 'order.created',
+*   version: 1,
+*   schema: {
+*     type: 'object',
+*     properties: {
+*       orderId: { type: 'string' },
+*       total: { type: 'number' },
+*     },
+*     required: ['orderId', 'total'],
+*   },
+* });
+*
+* // Type-safe event creation
+* const event = OrderCreated.create({ orderId: 'o-1', total: 100 });
+* await fastify.events.publish(event.type, event.payload, event.meta);
+*
+* // Registry for introspection + validation
+* const registry = createEventRegistry();
+* registry.register(OrderCreated);
+* const result = registry.validate('order.created', payload);
+* ```
+*/
+var defineEvent_exports = /* @__PURE__ */ __exportAll({
+	createEventRegistry: () => createEventRegistry,
+	defineEvent: () => defineEvent
+});
+/**
+* Define a typed event with optional schema validation.
+*
+* @example
+* const OrderCreated = defineEvent({
+*   name: 'order.created',
+*   schema: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
+* });
+*
+* const event = OrderCreated.create({ orderId: '123' });
+*/
+function defineEvent(input) {
+	const { name, schema, version = 1, description } = input;
+	return {
+		name,
+		schema,
+		version,
+		description,
+		create(payload, meta) {
+			return createEvent(name, payload, {
+				schemaVersion: version,
+				...meta
+			});
+		}
+	};
+}
+/**
+* Create an event registry for cataloging and validating events.
+*
+* The registry is opt-in — unregistered events pass validation.
+* This allows gradual adoption without breaking existing code.
+*
+* @param options.validate - Custom validator replacing the built-in minimal validator.
+*   The built-in validator only checks top-level object structure (type, required, property types).
+*   For nested objects, arrays, enums, patterns, or $ref, provide AJV or similar.
+*/
+function createEventRegistry(options) {
+	const customValidator = options?.validate;
+	const definitions = /* @__PURE__ */ new Map();
+	function registryKey(name, version) {
+		return `${name}:v${version}`;
+	}
+	return {
+		register(definition) {
+			const key = registryKey(definition.name, definition.version);
+			if (definitions.has(key)) throw new Error(`Event '${definition.name}' v${definition.version} is already registered. Use a different version number for schema evolution.`);
+			definitions.set(key, definition);
+		},
+		get(name, version) {
+			if (version !== void 0) return definitions.get(registryKey(name, version));
+			let latest;
+			let latestVersion = -1;
+			for (const def of definitions.values()) if (def.name === name && def.version > latestVersion) {
+				latest = def;
+				latestVersion = def.version;
+			}
+			return latest;
+		},
+		catalog() {
+			return Array.from(definitions.values()).map((def) => ({
+				name: def.name,
+				version: def.version,
+				description: def.description,
+				schema: def.schema
+			}));
+		},
+		validate(name, payload, version) {
+			let target = version !== void 0 ? definitions.get(registryKey(name, version)) : void 0;
+			if (!target && version === void 0) {
+				let latestVersion = -1;
+				for (const candidate of definitions.values()) if (candidate.name === name && candidate.version > latestVersion) {
+					target = candidate;
+					latestVersion = candidate.version;
+				}
+			}
+			if (!target) return { valid: true };
+			if (!target.schema) return { valid: true };
+			return customValidator ? customValidator(target.schema, payload) : validatePayload(payload, target.schema);
+		}
+	};
+}
+/**
+* Built-in minimal validator — lightweight guard, NOT a full JSON Schema engine.
+*
+* Checks:
+* - payload is an object (not null, not array)
+* - required fields are present
+* - top-level property types match (string, number, boolean, array, object)
+*
+* Does NOT check:
+* - nested object properties
+* - array item types
+* - enum, pattern, format, minLength, minimum, $ref
+*
+* For full validation, pass a custom `validate` function to `createEventRegistry()`.
+*/
+function validatePayload(payload, schema) {
+	const errors = [];
+	if (schema.type === "object") {
+		if (payload === null || payload === void 0 || typeof payload !== "object" || Array.isArray(payload)) return {
+			valid: false,
+			errors: ["Payload must be an object"]
+		};
+		const record = payload;
+		if (schema.required) {
+			for (const field of schema.required) if (!(field in record) || record[field] === void 0) errors.push(`Missing required field: '${field}'`);
+		}
+		if (schema.properties) {
+			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}`);
+				}
+			}
+		}
+	}
+	return errors.length === 0 ? { valid: true } : {
+		valid: false,
+		errors
+	};
+}
+//#endregion
+export { defineEvent as n, defineEvent_exports as r, createEventRegistry as t };

package/dist/docs/index.d.mts

@@ -1,5 +1,5 @@
-import { p as RegistryEntry } from "../index-6u4_Gg6G.mjs";
-import { t as ExternalOpenApiPaths } from "../externalPaths-Bapitwvd.mjs";
+import { p as RegistryEntry } from "../index-CXXRbnf8.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/docs/openapi.d.ts

package/dist/docs/index.mjs

@@ -1,5 +1,5 @@
 import { t as getUserRoles } from "../types-DV9WDfeg.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-C0L9ar7m.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-D7G1V7ex.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{eventPlugin--5HIkdPU.mjs → eventPlugin-Cts2-Tfj.mjs}

@@ -1,144 +1,18 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { t as requestContext } from "./requestContext-CfRkaxwf.mjs";
+import { t as requestContext } from "./requestContext-C5XeK3VA.mjs";
+import { r as createEvent, t as MemoryEventTransport } from "./EventTransport-BFQjw9pB.mjs";
 import fp from "fastify-plugin";
-//#region src/events/EventTransport.ts
-/**
-* In-memory event transport (default)
-* Events are delivered synchronously within the process.
-* Not suitable for multi-instance deployments.
-*/
-var MemoryEventTransport = class {
-	name = "memory";
-	handlers = /* @__PURE__ */ new Map();
-	logger;
-	constructor(options) {
-		this.logger = options?.logger ?? console;
-	}
-	async publish(event) {
-		const exactHandlers = this.handlers.get(event.type) ?? /* @__PURE__ */ new Set();
-		const wildcardHandlers = this.handlers.get("*") ?? /* @__PURE__ */ new Set();
-		const patternHandlers = /* @__PURE__ */ new Set();
-		for (const [pattern, handlers] of this.handlers.entries()) if (pattern.endsWith(".*")) {
-			const prefix = pattern.slice(0, -2);
-			if (event.type.startsWith(`${prefix}.`)) for (const h of handlers) patternHandlers.add(h);
-		}
-		const allHandlers = new Set([
-			...exactHandlers,
-			...wildcardHandlers,
-			...patternHandlers
-		]);
-		for (const handler of allHandlers) try {
-			await handler(event);
-		} catch (err) {
-			this.logger.error(`[EventTransport] Handler error for ${event.type}:`, err);
-		}
-	}
-	/**
-	* Reference `publishMany` implementation — delegates to `publish()` in order.
-	*
-	* Production transports (Kafka, Redis pipeline, SQS batch) should override
-	* this with a single batched network call. Memory transport has nothing to
-	* batch, so we just loop — the loop still returns a proper result map so
-	* `EventOutbox.relay` can exercise the batched code path in tests.
-	*/
-	async publishMany(events) {
-		const results = /* @__PURE__ */ new Map();
-		for (const event of events) try {
-			await this.publish(event);
-			results.set(event.meta.id, null);
-		} catch (err) {
-			results.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
-		}
-		return results;
-	}
-	async subscribe(pattern, handler) {
-		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
-		this.handlers.get(pattern)?.add(handler);
-		return () => {
-			const set = this.handlers.get(pattern);
-			if (set) {
-				set.delete(handler);
-				if (set.size === 0) this.handlers.delete(pattern);
-			}
-		};
-	}
-	async close() {
-		this.handlers.clear();
-	}
-};
-/**
-* Create a domain event with auto-generated metadata.
-*
-* `id` and `timestamp` are filled in; everything else is caller-controlled.
-* Set `schemaVersion` explicitly for any event type you plan to evolve.
-*/
-function createEvent(type, payload, meta) {
-	return {
-		type,
-		payload,
-		meta: {
-			id: crypto.randomUUID(),
-			timestamp: /* @__PURE__ */ new Date(),
-			...meta
-		}
-	};
-}
-/**
-* Create a child event that chains causation from a parent event.
-*
-* Rules:
-*  - `causationId` is set to the parent's `id` (direct cause)
-*  - `correlationId` is inherited from the parent if set, else falls back
-*    to the parent's `id` (root correlation)
-*  - `userId` / `organizationId` are inherited when not overridden so the
-*    whole chain stays scoped to the originating principal/tenant
-*
-* Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
-* to override when a subsystem acts on behalf of a different principal.
-*
-* @example
-* ```typescript
-* const orderPlaced = createEvent('order.placed', { orderId: 'o1' }, {
-*   correlationId: req.id, userId: user.id,
-* });
-* await events.publish(orderPlaced);
-*
-* // Downstream handler emits a child event:
-* const reserved = createChildEvent(orderPlaced, 'inventory.reserved', {
-*   orderId: 'o1', skus: ['sku-1', 'sku-2'],
-* });
-* // reserved.meta.causationId   === orderPlaced.meta.id
-* // reserved.meta.correlationId === orderPlaced.meta.correlationId
-* // reserved.meta.userId        === user.id   (inherited)
-* ```
-*/
-function createChildEvent(parent, type, payload, meta) {
-	const inherited = {
-		correlationId: parent.meta.correlationId ?? parent.meta.id,
-		causationId: parent.meta.id
-	};
-	if (parent.meta.userId !== void 0) inherited.userId = parent.meta.userId;
-	if (parent.meta.organizationId !== void 0) inherited.organizationId = parent.meta.organizationId;
-	if (parent.meta.source !== void 0) inherited.source = parent.meta.source;
-	if (parent.meta.idempotencyKey !== void 0) inherited.idempotencyKey = parent.meta.idempotencyKey;
-	return {
-		type,
-		payload,
-		meta: {
-			id: crypto.randomUUID(),
-			timestamp: /* @__PURE__ */ new Date(),
-			...inherited,
-			...meta
-		}
-	};
-}
-//#endregion
 //#region src/events/retry.ts
 /**
 * Wrap an event handler with retry logic and dead letter support.
 *
 * On failure, retries with exponential backoff (with jitter).
 * After all retries exhausted, calls `onDead` callback if provided.
+*
+* Generic in the payload type `T` so composing with `wrapWithSchema<T>` /
+* `subscribeWithSchema<T>` doesn't force a cast at the boundary — the inner
+* `handler: EventHandler<T>` flows through to the returned wrapper. Defaults
+* to `unknown` for raw `subscribe(pattern, withRetry(...))` call sites.
 */
 function withRetry(handler, options = {}) {
 	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, transport, onDead, name, logger = console } = options;
@@ -253,7 +127,7 @@ const eventPlugin = async (fastify, opts = {}) => {
 				correlationId: event.meta.correlationId
 			}, "Publishing event");
 			if (registry && validateMode !== "off") {
-				const result = registry.validate(type, payload);
+				const result = registry.validate(type, payload, event.meta.schemaVersion);
 				if (!result.valid) {
 					const msg = `[Arc Events] Event '${type}' payload validation failed: ${result.errors?.join("; ")}`;
 					if (validateMode === "reject") throw new Error(msg);
@@ -321,4 +195,4 @@ var eventPlugin_default = fp(eventPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { MemoryEventTransport as a, withRetry as i, eventPlugin_exports as n, createChildEvent as o, createDeadLetterPublisher as r, createEvent as s, eventPlugin as t };
+export { withRetry as i, eventPlugin_exports as n, createDeadLetterPublisher as r, eventPlugin as t };

package/dist/{eventPlugin-CUNjYYRY.d.mts → eventPlugin-DDJoNEPL.d.mts}

@@ -1,4 +1,4 @@
-import { i as EventLogger, n as DomainEvent, o as EventTransport, r as EventHandler } from "./EventTransport-CfVEGaEl.mjs";
+import { i as EventLogger, n as DomainEvent, o as EventTransport, r as EventHandler } from "./EventTransport-CYNUXdCJ.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/events/defineEvent.d.ts
@@ -73,8 +73,15 @@ interface EventRegistry {
     description?: string;
     schema?: EventSchema;
   }>;
-  /** Validate a payload against a registered event's schema */
-  validate(name: string, payload: unknown): ValidationResult;
+  /**
+   * Validate a payload against a registered event's schema.
+   *
+   * @param version - Optional schema version. When set, validation runs
+   *   against that exact version (use during migrations: producer A still
+   *   on v1 must validate against v1's schema even if v2 is registered).
+   *   When omitted, validates against the latest registered version.
+   */
+  validate(name: string, payload: unknown, version?: number): ValidationResult;
 }
 /**
  * Define a typed event with optional schema validation.
@@ -155,8 +162,13 @@ interface RetryOptions {
  *
  * On failure, retries with exponential backoff (with jitter).
  * After all retries exhausted, calls `onDead` callback if provided.
+ *
+ * Generic in the payload type `T` so composing with `wrapWithSchema<T>` /
+ * `subscribeWithSchema<T>` doesn't force a cast at the boundary — the inner
+ * `handler: EventHandler<T>` flows through to the returned wrapper. Defaults
+ * to `unknown` for raw `subscribe(pattern, withRetry(...))` call sites.
  */
-declare function withRetry(handler: EventHandler, options?: RetryOptions): EventHandler;
+declare function withRetry<T = unknown>(handler: EventHandler<T>, options?: RetryOptions): EventHandler<T>;
 /**
  * Create a dead letter publisher that sends failed events to a `$deadLetter` channel.
  *
@@ -203,9 +215,24 @@ interface EventPluginOptions {
    */
   failOpen?: boolean;
   /**
-   * Write-Ahead Log (WAL) configuration for at-least-once delivery guarantees.
-   * If provided, events will be saved to the WAL *before* passing to the transport.
-   * After a successful publish, they are acknowledged.
+   * Low-level write-ahead hook called BEFORE the transport publish, with an
+   * optional acknowledge() called AFTER a successful publish.
+   *
+   * **Important**: this is NOT at-least-once delivery on its own. If
+   * `transport.publish()` throws after `wal.save()`, the saved row stays
+   * but arc does NOT relay it on next boot — there is no replay loop here.
+   * For at-least-once you must EITHER:
+   *
+   *   1. Run a relay loop yourself (read unacknowledged WAL rows on boot,
+   *      republish, ack on success), or
+   *   2. Use `EventOutbox` ([./outbox.ts]) — `outbox.relay()` is the
+   *      production-grade at-least-once primitive with claim/lease,
+   *      retry/DLQ, multi-worker safety, and `repository`-backed durable
+   *      storage. New code should prefer `EventOutbox` over `wal`.
+   *
+   * The `wal` slot is kept for hosts that want to integrate with custom
+   * write-ahead infrastructure (Kafka producer transactions, S3 batch
+   * archives, debug audit logs) without arc's outbox claim/lease semantics.
    */
   wal?: {
     save: (event: DomainEvent) => Promise<void>;

package/dist/events/index.d.mts

@@ -1,8 +1,8 @@
-import { jn as RepositoryLike } from "../index-6u4_Gg6G.mjs";
-import { a as EventMeta, c as MemoryEventTransportOptions, d as createEvent, i as EventLogger, l as PublishManyResult, n as DomainEvent, o as EventTransport, r as EventHandler, s as MemoryEventTransport, t as DeadLetteredEvent, u as createChildEvent } from "../EventTransport-CfVEGaEl.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-CUNjYYRY.mjs";
+import { Mn as RepositoryLike } from "../index-CXXRbnf8.mjs";
+import { a as EventMeta, c as MemoryEventTransportOptions, d as createEvent, i as EventLogger, l as PublishManyResult, n as DomainEvent, o as EventTransport, r as EventHandler, s as MemoryEventTransport, t as DeadLetteredEvent, u as createChildEvent } from "../EventTransport-CYNUXdCJ.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-DDJoNEPL.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-CM8TXTix.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-xTGxB2bm.mjs";
 
 //#region src/events/eventTypes.d.ts
 /**
@@ -600,4 +600,163 @@ declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
 //#region src/events/repository-outbox-adapter.d.ts
 declare function repositoryAsOutboxStore(repository: RepositoryLike): OutboxStore;
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DeadLetteredEvent, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, type EventMeta, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, createChildEvent, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, withRetry };
+//#region src/events/subscribe-helpers.d.ts
+/**
+ * Extract the payload type from an `EventDefinitionOutput<T>`.
+ *
+ * `defineEvent<T>` already threads `T` through `.create(payload: T, ...)`, but
+ * there's no exposed way to recover `T` for use in handler signatures, factory
+ * helpers, or test fixtures. `PayloadOf<typeof OrderPaid>` closes the loop
+ * without forcing every host to define their own copy.
+ *
+ * @example
+ * ```ts
+ * const OrderPaid = defineEvent<{ orderId: string; total: number }>({
+ *   name: 'order.paid',
+ *   schema: { type: 'object', required: ['orderId', 'total'] },
+ * });
+ * type OrderPaidPayload = PayloadOf<typeof OrderPaid>;
+ * //   ^? { orderId: string; total: number }
+ * ```
+ */
+type PayloadOf<D> = D extends EventDefinitionOutput<infer T> ? T : never;
+interface WrapWithSchemaOptions<T> {
+  /**
+   * Custom validator. Overrides the built-in lookup. Use this to plug AJV /
+   * Zod / TypeBox in. Same shape as `EventRegistryOptions.validate`.
+   *
+   * Resolution order:
+   *   1. `validate` (this option)
+   *   2. `registry.validate(definition.name, payload)` — uses whatever
+   *      validator the registry was configured with
+   *   3. Built-in minimal validator (top-level `required` + property types)
+   */
+  validate?: CustomValidator;
+  /**
+   * Optional registry — when set and `validate` is omitted, validation routes
+   * through `registry.validate(definition.name, payload)`. Lets the subscriber
+   * use the same configured validator (AJV, custom) the publish side uses
+   * via `eventPlugin({ registry })`.
+   */
+  registry?: EventRegistry;
+  /**
+   * Called when payload validation fails. Default behaviour: log a warning
+   * with the event's id/type/errors and skip the handler (the event is NOT
+   * acknowledged as a failure, since the handler never ran — matches `withRetry`'s
+   * `onDead` semantics for terminal failures, but at the validation boundary).
+   *
+   * Receives the raw event (untyped — the payload is by definition not the
+   * declared shape) plus the validation errors array.
+   */
+  onInvalid?: (event: DomainEvent<unknown>, errors: string[]) => void | Promise<void>;
+  /**
+   * Logger for invalid-payload warnings. Pass `fastify.log` to integrate
+   * with the application logger. Default: `console`.
+   */
+  logger?: EventLogger;
+  /**
+   * Optional name for log output (otherwise the definition name is used).
+   */
+  name?: string;
+}
+/**
+ * Pure handler wrapper — returns a new `EventHandler` that validates
+ * `event.payload` against the definition's schema before invoking the handler.
+ *
+ * The returned handler's input is `DomainEvent<unknown>` (since the transport
+ * delivers untyped events) but the inner `handler` receives `DomainEvent<T>`.
+ * No cast at the call site.
+ *
+ * @example
+ * ```ts
+ * await fastify.events.subscribe(
+ *   OrderPaid.name,
+ *   wrapWithSchema(OrderPaid, async (event) => {
+ *     // event.payload is typed via the registered schema — no cast.
+ *     await postSalesEntry(event.payload.orderId, event.payload.total);
+ *   }),
+ * );
+ * ```
+ */
+declare function wrapWithSchema<T>(definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): EventHandler<unknown>;
+/**
+ * Convenience: validate + subscribe in one call. Equivalent to
+ * `fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options))`.
+ *
+ * Returns the unsubscribe function from the underlying transport.
+ *
+ * @example
+ * ```ts
+ * await subscribeWithSchema(fastify, OrderPaid, async (event) => {
+ *   await postSalesEntry(event.payload.orderId, event.payload.total);
+ * });
+ *
+ * // Compose with withRetry — schema validation runs FIRST, then retry on
+ * // handler failure. Invalid payloads skip without burning retry attempts.
+ * await subscribeWithSchema(
+ *   fastify,
+ *   OrderPaid,
+ *   withRetry(handler, { maxRetries: 3 }),
+ * );
+ * ```
+ */
+declare function subscribeWithSchema<T>(fastify: FastifyEventBus, definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): Promise<() => void>;
+interface WrapWithBoundaryOptions {
+  /**
+   * Called when the handler throws. Default behaviour: log the error with
+   * `{ err, event: event.type, eventId: event.meta.id }` and swallow.
+   *
+   * Use this to push metrics (`statsd.increment('handler.error', { type })`)
+   * or alert on specific event types.
+   */
+  onError?: (err: Error, event: DomainEvent) => void | Promise<void>;
+  /**
+   * Logger for handler errors. Pass `fastify.log` to integrate with the
+   * application logger. Default: `console`.
+   */
+  logger?: EventLogger;
+  /**
+   * Optional name for log output (otherwise the handler's `.name` is used).
+   */
+  name?: string;
+}
+/**
+ * Pure handler wrapper — returns a new `EventHandler` that catches handler
+ * exceptions and routes them to `onError` (or logs and swallows). For
+ * projection / cache-invalidation / fire-and-forget handlers where retry
+ * would just delay the next-event resync, and where one bad event must NOT
+ * stop processing of subsequent events.
+ *
+ * Lighter than `withRetry`: no exponential backoff, no DLQ. Composes with
+ * `withRetry` if you want both ("retry, then log if exhausted, never throw").
+ *
+ * @example
+ * ```ts
+ * await fastify.events.subscribe(
+ *   'product:variants.changed',
+ *   wrapWithBoundary(async (event) => {
+ *     cache.invalidate(event.payload.productId);
+ *   }),
+ * );
+ * ```
+ */
+declare function wrapWithBoundary(handler: EventHandler, options?: WrapWithBoundaryOptions): EventHandler;
+/**
+ * Convenience: subscribe + error-boundary in one call. Equivalent to
+ * `fastify.events.subscribe(pattern, wrapWithBoundary(handler, options))`.
+ *
+ * Returns the unsubscribe function from the underlying transport.
+ */
+declare function subscribeWithBoundary(fastify: FastifyEventBus, pattern: string, handler: EventHandler, options?: WrapWithBoundaryOptions): Promise<() => void>;
+/**
+ * Structural type — accepts anything with the `events.subscribe` method,
+ * including `FastifyInstance` (declaration-merged in `eventPlugin.ts`) and
+ * test doubles. Avoids importing the full Fastify type in this module.
+ */
+interface FastifyEventBus {
+  events: {
+    subscribe: (pattern: string, handler: EventHandler) => Promise<() => void>;
+  };
+}
+//#endregion
+export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DeadLetteredEvent, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, type EventMeta, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PayloadOf, type PublishManyResult, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createChildEvent, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };