@classytic/arc 2.11.3 → 2.13.1

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

@@ -1,4 +1,4 @@
-import { i as EventLogger, n as DomainEvent, o as EventTransport, r as EventHandler } from "./EventTransport-CfVEGaEl.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-CT_52aWU.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>;
@@ -248,6 +275,29 @@ interface EventPluginOptions {
    * - `'off'`: skip validation entirely (registry is only for introspection)
    */
   validateMode?: "warn" | "reject" | "off";
+  /**
+   * Dev-mode duplicate-publish detector (v2.12).
+   *
+   * When enabled, arc keeps a 5-second LRU on `(eventType, correlationId)`
+   * and emits an `arcLog("events").warn(...)` the second time a request
+   * publishes the same event with the same correlation id within the
+   * window. Catches the dual-publish trap where a domain service holds
+   * BOTH a publisher AND a notification helper that internally publishes
+   * to the same bus — every subscriber fires twice for one logical event.
+   *
+   * Defaults:
+   *   - `undefined` → enabled when `process.env.NODE_ENV !== 'production'`.
+   *   - `true` → always enabled (catches duplicates in prod too — overhead
+   *     is one Map lookup per publish).
+   *   - `false` → always disabled.
+   *
+   * When a duplicate is detected, arc logs once and **still publishes** —
+   * the detector is observability, not enforcement. Pair with the outbox
+   * for at-most-once delivery.
+   *
+   * Documented in `wiki/gotchas.md` (#20).
+   */
+  warnOnDuplicate?: boolean;
 }
 declare module "fastify" {
   interface FastifyInstance {

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 { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-CT_52aWU.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-qXpqTebY.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-D6HzR1Z_.mjs";
+import { RepositoryLike } from "@classytic/repo-core/adapter";
 
 //#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 EventDefinitionInput, type EventDefinitionOutput, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, 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 RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };

package/dist/events/index.mjs

@@ -1,184 +1,9 @@
-import { a as MemoryEventTransport, i as withRetry, o as createChildEvent, r as createDeadLetterPublisher, s as createEvent, t as eventPlugin } from "../eventPlugin-KrFIQ097.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-BhrzxvyQ.mjs";
+import { t as MemoryEventTransport } from "../EventTransport-DLWoUMHy.mjs";
+import { n as defineEvent, t as createEventRegistry } from "../defineEvent-D5h7EvAx.mjs";
+import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-CaKTYkYM.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-BkIN9-vu.mjs";
 import { and, anyOf, eq, lte, ne, or } from "@classytic/repo-core/filter";
 import { update } from "@classytic/repo-core/update";
-//#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);
-* ```
-*/
-/**
-* 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, 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) {
-			let latest;
-			let latestVersion = -1;
-			for (const def of definitions.values()) if (def.name === name && def.version > latestVersion) {
-				latest = def;
-				latestVersion = def.version;
-			}
-			if (!latest) return { valid: true };
-			if (!latest.schema) return { valid: true };
-			if (customValidator) return customValidator(latest.schema, payload);
-			return validatePayload(payload, latest.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
 //#region src/events/eventTypes.ts
 /**
 * Event Type Constants and Helpers
@@ -345,30 +170,6 @@ var MemoryOutboxStore = class {
 };
 //#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.
-*/
 const DEFAULT_LEASE_MS$1 = 3e4;
 const DEFAULT_CLAIM_LIMIT = 100;
 const DEFAULT_PURGE_BATCH = 500;
@@ -383,12 +184,12 @@ function repositoryAsOutboxStore(repository) {
 	const r = repository;
 	const idField = repository.idField ?? "_id";
 	/**
-	* Unwrap mongokit's pagination envelope ({ docs, total, ... }) — some
+	* Unwrap mongokit's pagination envelope ({ data, total, ... }) — some
 	* kits may return a bare array when pagination is disabled. Handle both.
 	*/
 	const unwrapDocs = (result) => {
 		if (Array.isArray(result)) return result;
-		return result?.docs ?? [];
+		return result?.data ?? [];
 	};
 	const isDuplicateKeyError = createIsDuplicateKeyError(repository);
 	const safeGetOne = createSafeGetOne(repository);
@@ -707,7 +508,7 @@ var EventOutbox = class {
 		const valid = [];
 		let malformed = 0;
 		for (const event of pending) {
-			if (!event || !event.type || !event.meta?.id) {
+			if (!event?.type || !event.meta?.id) {
 				this._reportError("malformed_event", new InvalidOutboxEventError("store returned event missing type or meta.id — batch aborted"), event);
 				malformed++;
 				break;
@@ -726,7 +527,7 @@ var EventOutbox = class {
 		const canFail = typeof this._store.fail === "function";
 		let publishOutcomes;
 		if (canPublishMany && valid.length > 0) try {
-			const result = await this._transport.publishMany(valid);
+			const result = await this._transport.publishMany?.(valid);
 			publishOutcomes = new Map(result);
 		} catch (batchErr) {
 			publishOutcomes = /* @__PURE__ */ new Map();
@@ -771,7 +572,7 @@ var EventOutbox = class {
 					this._reportError("fail_failed", policyErr, event);
 				}
 				try {
-					await this._store.fail(event.meta.id, normalizeError(publishErr), failOpts);
+					await this._store.fail?.(event.meta.id, normalizeError(publishErr), failOpts);
 					if (failOpts.deadLetter) {
 						counts.deadLettered++;
 						this._attempts.delete(event.meta.id);
@@ -886,4 +687,127 @@ function exponentialBackoff(options) {
 	return new Date(now + jittered);
 }
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, InvalidOutboxEventError, MemoryEventTransport, MemoryOutboxStore, OutboxOwnershipError, createChildEvent, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, withRetry };
+//#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.
+*
+* 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);
+*   }),
+* );
+* ```
+*/
+function wrapWithSchema(definition, handler, options = {}) {
+	const { validate, registry, onInvalid, logger = console, name } = options;
+	const label = name ?? definition.name;
+	return async (event) => {
+		const eventVersion = typeof event.meta?.schemaVersion === "number" ? event.meta.schemaVersion : definition.version;
+		let result;
+		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 import("../defineEvent-D5h7EvAx.mjs").then((n) => n.r);
+			const adhoc = createEventRegistry();
+			adhoc.register(definition);
+			result = adhoc.validate(definition.name, event.payload);
+		} else result = { valid: true };
+		if (!result.valid) {
+			const errors = result.errors ?? ["payload failed validation"];
+			if (onInvalid) try {
+				await onInvalid(event, errors);
+			} catch (cbErr) {
+				logger.error(`[Arc Events] '${label}' onInvalid callback threw:`, cbErr);
+			}
+			else logger.warn(`[Arc Events] '${label}' skipped event ${event.meta?.id ?? "<no-id>"} — payload failed validation: ${errors.join("; ")}`);
+			return;
+		}
+		await handler(event);
+	};
+}
+/**
+* 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 }),
+* );
+* ```
+*/
+async function subscribeWithSchema(fastify, definition, handler, options) {
+	return fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options));
+}
+/**
+* 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);
+*   }),
+* );
+* ```
+*/
+function wrapWithBoundary(handler, options = {}) {
+	const { onError, logger = console, name } = options;
+	const label = name ?? handler.name ?? "anonymous";
+	return async (event) => {
+		try {
+			await handler(event);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (onError) try {
+				await onError(error, event);
+			} catch (cbErr) {
+				logger.error(`[Arc Events] '${label}' onError callback threw:`, cbErr);
+			}
+			else logger.error(`[Arc Events] '${label}' threw on ${event.type} — swallowed (boundary): ${error.message}`, {
+				err: error,
+				event: event.type,
+				eventId: event.meta?.id,
+				handler: label
+			});
+		}
+	};
+}
+/**
+* Convenience: subscribe + error-boundary in one call. Equivalent to
+* `fastify.events.subscribe(pattern, wrapWithBoundary(handler, options))`.
+*
+* Returns the unsubscribe function from the underlying transport.
+*/
+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 };

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