@classytic/arc 2.3.0 → 2.4.2

package/dist/{eventPlugin-BEOvaDqo.mjs → eventPlugin-Ba00swHF.mjs}

@@ -1,7 +1,6 @@
-import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
-import { t as requestContext } from "./requestContext-xi6OKBL-.mjs";
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { t as requestContext } from "./requestContext-DYtmNpm5.mjs";
 import fp from "fastify-plugin";
-
 //#region src/events/EventTransport.ts
 /**
 * In-memory event transport (default)
@@ -21,7 +20,7 @@ var MemoryEventTransport = class {
 		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 + ".")) handlers.forEach((h) => patternHandlers.add(h));
+			if (event.type.startsWith(`${prefix}.`)) for (const h of handlers) patternHandlers.add(h);
 		}
 		const allHandlers = new Set([
 			...exactHandlers,
@@ -36,9 +35,13 @@ var MemoryEventTransport = class {
 	}
 	async subscribe(pattern, handler) {
 		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
-		this.handlers.get(pattern).add(handler);
+		this.handlers.get(pattern)?.add(handler);
 		return () => {
-			this.handlers.get(pattern)?.delete(handler);
+			const set = this.handlers.get(pattern);
+			if (set) {
+				set.delete(handler);
+				if (set.size === 0) this.handlers.delete(pattern);
+			}
 		};
 	}
 	async close() {
@@ -59,7 +62,6 @@ function createEvent(type, payload, meta) {
 		}
 	};
 }
-
 //#endregion
 //#region src/events/retry.ts
 /**
@@ -130,32 +132,20 @@ function createDeadLetterPublisher(events) {
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-
 //#endregion
 //#region src/events/eventPlugin.ts
-/**
-* Event Plugin
-*
-* Integrates event transport with Fastify.
-* Defaults to in-memory transport; configure durable transport for production.
-*
-* @example
-* // Development (in-memory)
-* await fastify.register(eventPlugin);
-*
-* // Production (Redis)
-* await fastify.register(eventPlugin, {
-*   transport: new RedisEventTransport({ url: process.env.REDIS_URL }),
-* });
-*/
 var eventPlugin_exports = /* @__PURE__ */ __exportAll({
 	default: () => eventPlugin_default,
 	eventPlugin: () => eventPlugin
 });
 const eventPlugin = async (fastify, opts = {}) => {
-	const { transport = new MemoryEventTransport(), logEvents = false, failOpen = true, retry: retryOpts, deadLetterQueue: dlqOpts, wal, onPublish, onPublishError } = opts;
+	const { transport = new MemoryEventTransport(), logEvents = false, failOpen = true, retry: retryOpts, deadLetterQueue: dlqOpts, wal, onPublish, onPublishError, registry, validateMode: rawValidateMode } = opts;
+	const validateMode = rawValidateMode ?? (registry ? "warn" : "off");
 	fastify.decorate("events", {
 		publish: async (type, payload, meta) => {
+			if (!type || typeof type !== "string") throw new Error("[Arc Events] Event type must be a non-empty string");
+			if (type.startsWith("$") && type !== "$deadLetter") throw new Error(`[Arc Events] Event type '${type}' uses reserved '$' prefix`);
+			if (type.length > 256) throw new Error("[Arc Events] Event type exceeds 256 characters");
 			const store = requestContext.get();
 			const event = createEvent(type, payload, {
 				...store?.requestId && !meta?.correlationId ? { correlationId: store.requestId } : {},
@@ -166,6 +156,14 @@ const eventPlugin = async (fastify, opts = {}) => {
 				eventId: event.meta.id,
 				correlationId: event.meta.correlationId
 			}, "Publishing event");
+			if (registry && validateMode !== "off") {
+				const result = registry.validate(type, payload);
+				if (!result.valid) {
+					const msg = `[Arc Events] Event '${type}' payload validation failed: ${result.errors?.join("; ")}`;
+					if (validateMode === "reject") throw new Error(msg);
+					fastify.log?.warn?.(msg);
+				}
+			}
 			try {
 				if (wal) await wal.save(event);
 				await transport.publish(event);
@@ -204,7 +202,8 @@ const eventPlugin = async (fastify, opts = {}) => {
 				return () => {};
 			}
 		},
-		transportName: transport.name
+		transportName: transport.name,
+		registry
 	});
 	fastify.addHook("onClose", async () => {
 		try {
@@ -224,6 +223,5 @@ var eventPlugin_default = fp(eventPlugin, {
 	name: "arc-events",
 	fastify: "5.x"
 });
-
 //#endregion
-export { MemoryEventTransport as a, withRetry as i, eventPlugin_exports as n, createEvent as o, createDeadLetterPublisher as r, eventPlugin as t };
+export { MemoryEventTransport as a, withRetry as i, eventPlugin_exports as n, createEvent as o, createDeadLetterPublisher as r, eventPlugin as t };

package/dist/{eventPlugin-H6wDDjGO.d.mts → eventPlugin-iGrSEmwJ.d.mts}

@@ -1,6 +1,77 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-BkUDYZEb.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-wc5hSLik.mjs";
 import { FastifyPluginAsync } from "fastify";
 
+//#region src/events/defineEvent.d.ts
+interface EventSchema {
+  type: "object";
+  properties?: Record<string, {
+    type?: string;
+    [key: string]: unknown;
+  }>;
+  required?: string[];
+  [key: string]: unknown;
+}
+interface EventDefinitionInput {
+  /** Event type name (e.g., 'order.created') */
+  name: string;
+  /** JSON Schema for payload validation */
+  schema?: EventSchema;
+  /** Event version for schema evolution (default: 1) */
+  version?: number;
+  /** Human-readable description */
+  description?: string;
+}
+interface EventDefinitionOutput<T = unknown> {
+  /** Event type name */
+  readonly name: string;
+  /** JSON Schema for payload validation */
+  readonly schema?: EventSchema;
+  /** Event version */
+  readonly version: number;
+  /** Human-readable description */
+  readonly description?: string;
+  /** Create a DomainEvent with this type + auto-generated metadata */
+  create(payload: T, meta?: Partial<DomainEvent["meta"]>): DomainEvent<T>;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors?: string[];
+}
+interface EventRegistry {
+  /** Register an event definition */
+  register(definition: EventDefinitionOutput): void;
+  /** Get event definition by name (latest version if no version specified) */
+  get(name: string, version?: number): EventDefinitionOutput | undefined;
+  /** Get full catalog of registered events */
+  catalog(): ReadonlyArray<{
+    name: string;
+    version: number;
+    description?: string;
+    schema?: EventSchema;
+  }>;
+  /** Validate a payload against a registered event's schema */
+  validate(name: string, payload: unknown): ValidationResult;
+}
+/**
+ * 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' });
+ */
+declare function defineEvent<T = unknown>(input: EventDefinitionInput): EventDefinitionOutput<T>;
+/**
+ * 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.
+ */
+declare function createEventRegistry(): EventRegistry;
+//#endregion
 //#region src/events/retry.d.ts
 interface RetryOptions {
   /**
@@ -79,8 +150,16 @@ interface EventPluginOptions {
   logEvents?: boolean;
   /**
    * Fail-open mode for runtime resilience (default: true).
-   * - true: publish/subscribe/close errors are logged and suppressed
-   * - false: errors are thrown to caller
+   * - true: publish/subscribe/close errors are logged and suppressed — the
+   *   request still succeeds even if event delivery fails. Safe for analytics
+   *   and non-critical side effects.
+   * - false: errors are thrown to caller — use this for business-critical
+   *   events where silent loss is unacceptable (e.g. billing, notifications).
+   *
+   * **Important:** With `failOpen: true` (default), a transport outage will
+   * silently drop events while requests continue succeeding. Pair with the
+   * `onPublishError` callback to monitor failures, or use `wal` for
+   * at-least-once delivery guarantees.
    */
   failOpen?: boolean;
   /**
@@ -109,16 +188,37 @@ interface EventPluginOptions {
   onPublish?: (event: DomainEvent) => void;
   /** Callback on publish failure (for metrics/alerting) */
   onPublishError?: (event: DomainEvent, error: Error) => void;
+  /**
+   * Event registry for payload validation and introspection.
+   * When provided, payloads are validated against registered schemas on publish.
+   *
+   * @example
+   * ```typescript
+   * const registry = createEventRegistry();
+   * registry.register(defineEvent({ name: 'order.created', schema: { ... } }));
+   *
+   * await fastify.register(eventPlugin, { registry, validateMode: 'warn' });
+   * ```
+   */
+  registry?: EventRegistry;
+  /**
+   * How to handle schema validation failures on publish:
+   * - `'warn'` (default when registry is provided): log a warning, still publish
+   * - `'reject'`: throw an error, do NOT publish
+   * - `'off'`: skip validation entirely (registry is only for introspection)
+   */
+  validateMode?: "warn" | "reject" | "off";
 }
 declare module "fastify" {
   interface FastifyInstance {
     events: {
       /** Publish an event */publish: <T>(type: string, payload: T, meta?: Partial<DomainEvent["meta"]>) => Promise<void>; /** Subscribe to events */
       subscribe: (pattern: string, handler: EventHandler) => Promise<() => void>; /** Get transport name */
-      transportName: string;
+      transportName: string; /** Event registry for introspection (undefined when no registry configured) */
+      registry?: EventRegistry;
     };
   }
 }
 declare const eventPlugin: FastifyPluginAsync<EventPluginOptions>;
 //#endregion
-export { withRetry as a, createDeadLetterPublisher as i, eventPlugin as n, RetryOptions as r, EventPluginOptions as t };
+export { withRetry as a, EventRegistry as c, createEventRegistry as d, defineEvent as f, createDeadLetterPublisher as i, EventSchema as l, eventPlugin as n, EventDefinitionInput as o, RetryOptions as r, EventDefinitionOutput as s, EventPluginOptions as t, ValidationResult as u };

package/dist/events/index.d.mts

@@ -1,7 +1,7 @@
-import { a as MemoryEventTransport, i as EventTransport, n as EventHandler, o as MemoryEventTransportOptions, r as EventLogger, s as createEvent, t as DomainEvent } from "../EventTransport-BkUDYZEb.mjs";
-import { a as withRetry, i as createDeadLetterPublisher, n as eventPlugin, r as RetryOptions, t as EventPluginOptions } from "../eventPlugin-H6wDDjGO.mjs";
+import { a as MemoryEventTransport, i as EventTransport, n as EventHandler, o as MemoryEventTransportOptions, r as EventLogger, s as createEvent, t as DomainEvent } from "../EventTransport-wc5hSLik.mjs";
+import { a as withRetry, c as EventRegistry, d as createEventRegistry, f as defineEvent, i as createDeadLetterPublisher, l as EventSchema, n as eventPlugin, o as EventDefinitionInput, r as RetryOptions, s as EventDefinitionOutput, t as EventPluginOptions, u as ValidationResult } from "../eventPlugin-iGrSEmwJ.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-CBg0upHI.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-BW9UKLZM.mjs";
 
 //#region src/events/eventTypes.d.ts
 /**
@@ -24,7 +24,7 @@ import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis
 /** Suffixes for auto-emitted CRUD events */
 declare const CRUD_EVENT_SUFFIXES: readonly ["created", "updated", "deleted"];
 /** Type for CRUD event suffixes */
-type CrudEventSuffix = typeof CRUD_EVENT_SUFFIXES[number];
+type CrudEventSuffix = (typeof CRUD_EVENT_SUFFIXES)[number];
 /**
  * Build a CRUD event type string.
  *
@@ -41,13 +41,78 @@ declare const ARC_LIFECYCLE_EVENTS: Readonly<{
   readonly READY: "arc.ready";
 }>;
 /** Type for Arc lifecycle event names */
-type ArcLifecycleEvent = typeof ARC_LIFECYCLE_EVENTS[keyof typeof ARC_LIFECYCLE_EVENTS];
+type ArcLifecycleEvent = (typeof ARC_LIFECYCLE_EVENTS)[keyof typeof ARC_LIFECYCLE_EVENTS];
 /** Cache-specific event types for observability and external triggers */
 declare const CACHE_EVENTS: Readonly<{
   /** Emitted when a resource's cache version is bumped */readonly VERSION_BUMPED: "arc.cache.version.bumped"; /** Emitted when a tag version is bumped */
   readonly TAG_VERSION_BUMPED: "arc.cache.tag.bumped";
 }>;
 /** Type for cache event names */
-type CacheEvent = typeof CACHE_EVENTS[keyof typeof CACHE_EVENTS];
+type CacheEvent = (typeof CACHE_EVENTS)[keyof typeof CACHE_EVENTS];
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type DomainEvent, type EventHandler, type EventLogger, type EventPluginOptions, type EventTransport, MemoryEventTransport, type MemoryEventTransportOptions, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RetryOptions, createDeadLetterPublisher, createEvent, crudEventType, eventPlugin, withRetry };
+//#region src/events/outbox.d.ts
+interface OutboxStore {
+  /** Save event to outbox (called within business transaction) */
+  save(event: DomainEvent): Promise<void>;
+  /** Get pending (unrelayed) events, ordered FIFO */
+  getPending(limit: number): Promise<DomainEvent[]>;
+  /** Mark event as successfully relayed */
+  acknowledge(eventId: string): Promise<void>;
+  /**
+   * Purge old acknowledged events (optional, DB-agnostic contract).
+   *
+   * Arc does **not** ship a concrete implementation — your store owns the
+   * cleanup strategy that fits your database:
+   *
+   * - **MongoDB:** TTL index on `acknowledgedAt` (automatic, zero-code)
+   * - **SQL:** Scheduled `DELETE FROM outbox WHERE acknowledged_at < :cutoff`
+   * - **Redis:** Key expiry (`EXPIRE`) on acknowledged entries
+   *
+   * Called by {@link EventOutbox.purge}. If not implemented, cleanup is
+   * entirely the app's responsibility via native DB tools.
+   *
+   * @param olderThanMs - Remove events acknowledged more than this many ms ago
+   * @returns Number of purged events
+   */
+  purge?(olderThanMs: number): Promise<number>;
+}
+interface EventOutboxOptions {
+  /** Outbox store for persistence */
+  store: OutboxStore;
+  /** Transport to relay events to (optional — can relay later) */
+  transport?: EventTransport;
+  /** Max events per relay batch (default: 100) */
+  batchSize?: number;
+}
+declare class EventOutbox {
+  private readonly _store;
+  private readonly _transport?;
+  private readonly _batchSize;
+  constructor(opts: EventOutboxOptions);
+  /** Store event in outbox (call within your DB transaction) */
+  store(event: DomainEvent): Promise<void>;
+  /**
+   * Relay pending events to transport.
+   *
+   * Processes events in FIFO order up to `batchSize`. Stops on the first
+   * transport failure — remaining events stay pending for the next relay call.
+   *
+   * @returns Number of successfully published events in this batch
+   */
+  relay(): Promise<number>;
+  /**
+   * Purge old acknowledged 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)
+   * @returns Number of purged events, or 0 if store doesn't support purge
+   */
+  purge(olderThanMs?: number): Promise<number>;
+}
+declare class MemoryOutboxStore implements OutboxStore {
+  private events;
+  save(event: DomainEvent): Promise<void>;
+  getPending(limit: number): Promise<DomainEvent[]>;
+  acknowledge(eventId: string): Promise<void>;
+}
+//#endregion
+export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventSchema, type EventTransport, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxStore, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RetryOptions, type ValidationResult, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, withRetry };

package/dist/events/index.mjs

@@ -1,5 +1,151 @@
-import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-BEOvaDqo.mjs";
-
+import { a as MemoryEventTransport, i as withRetry, o as createEvent, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-Ba00swHF.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
+*
+* Schema validation uses a minimal JSON Schema subset (type, required, properties)
+* to avoid pulling in AJV as a dependency. For full JSON Schema validation,
+* users can provide their own validator via the registry.
+*
+* @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.
+*/
+function createEventRegistry() {
+	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 };
+			return validatePayload(payload, latest.schema);
+		}
+	};
+}
+/**
+* Minimal JSON Schema validator — handles the common subset:
+* - type: 'object'
+* - required: string[]
+* - properties with type checks
+*
+* For full JSON Schema validation (patterns, formats, $ref, etc.),
+* use AJV directly or provide a custom validator.
+*/
+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
@@ -46,6 +192,72 @@ const CACHE_EVENTS = Object.freeze({
 	VERSION_BUMPED: "arc.cache.version.bumped",
 	TAG_VERSION_BUMPED: "arc.cache.tag.bumped"
 });
-
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, MemoryEventTransport, createDeadLetterPublisher, createEvent, crudEventType, eventPlugin, withRetry };
+//#region src/events/outbox.ts
+/** Default outbox retention — acknowledged events older than this are eligible for purge */
+const DEFAULT_OUTBOX_RETENTION_MS = 10080 * 60 * 1e3;
+var EventOutbox = class {
+	_store;
+	_transport;
+	_batchSize;
+	constructor(opts) {
+		this._store = opts.store;
+		this._transport = opts.transport;
+		this._batchSize = opts.batchSize ?? 100;
+	}
+	/** Store event in outbox (call within your DB transaction) */
+	async store(event) {
+		await this._store.save(event);
+	}
+	/**
+	* Relay pending events to transport.
+	*
+	* Processes events in FIFO order up to `batchSize`. Stops on the first
+	* transport failure — remaining events stay pending for the next relay call.
+	*
+	* @returns Number of successfully published events in this batch
+	*/
+	async relay() {
+		if (!this._transport) return 0;
+		const pending = await this._store.getPending(this._batchSize);
+		let relayed = 0;
+		for (const event of pending) {
+			if (!event.type || !event.meta?.id) {
+				if (event.meta?.id) await this._store.acknowledge(event.meta.id);
+				continue;
+			}
+			try {
+				await this._transport.publish(event);
+				await this._store.acknowledge(event.meta.id);
+				relayed++;
+			} catch {
+				break;
+			}
+		}
+		return relayed;
+	}
+	/**
+	* Purge old acknowledged 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)
+	* @returns Number of purged events, or 0 if store doesn't support purge
+	*/
+	async purge(olderThanMs = DEFAULT_OUTBOX_RETENTION_MS) {
+		if (!this._store.purge) return 0;
+		return this._store.purge(olderThanMs);
+	}
+};
+var MemoryOutboxStore = class {
+	events = [];
+	async save(event) {
+		this.events.push(event);
+	}
+	async getPending(limit) {
+		return this.events.slice(0, limit);
+	}
+	async acknowledge(eventId) {
+		this.events = this.events.filter((e) => e.meta.id !== eventId);
+	}
+};
+//#endregion
+export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, 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-CBg0upHI.mjs";
+import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-BW9UKLZM.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };

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

@@ -11,6 +11,7 @@ var RedisStreamTransport = class {
 	claimTimeoutMs;
 	deadLetterStream;
 	maxLen;
+	maxPayloadBytes;
 	logger;
 	handlers = /* @__PURE__ */ new Map();
 	running = false;
@@ -27,9 +28,12 @@ var RedisStreamTransport = class {
 		this.claimTimeoutMs = options.claimTimeoutMs ?? 3e4;
 		this.deadLetterStream = options.deadLetterStream ?? "arc:events:dlq";
 		this.maxLen = options.maxLen ?? 1e4;
+		this.maxPayloadBytes = options.maxPayloadBytes ?? 1e6;
 		this.logger = options.logger ?? console;
 	}
 	async publish(event) {
+		const serialized = JSON.stringify(event);
+		if (serialized.length > this.maxPayloadBytes) throw new Error(`[RedisStreamTransport] Event payload (${serialized.length} bytes) exceeds limit (${this.maxPayloadBytes}). Consider breaking into smaller events or increasing maxPayloadBytes.`);
 		const args = [
 			this.stream,
 			...this.maxLen > 0 ? [
@@ -41,17 +45,20 @@ var RedisStreamTransport = class {
 			"type",
 			event.type,
 			"data",
-			JSON.stringify(event)
+			serialized
 		];
 		await this.redis.xadd(...args);
 	}
 	async subscribe(pattern, handler) {
 		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
-		this.handlers.get(pattern).add(handler);
+		this.handlers.get(pattern)?.add(handler);
 		if (!this.running) {
 			await this.ensureGroup();
 			this.running = true;
-			this.pollPromise = this.pollLoop();
+			this.pollPromise = this.pollLoop().catch((err) => {
+				this.logger.error("[RedisStreamTransport] Poll loop crashed:", err);
+				this.running = false;
+			});
 		}
 		return () => {
 			const set = this.handlers.get(pattern);
@@ -124,10 +131,16 @@ var RedisStreamTransport = class {
 		}
 		let event;
 		try {
-			event = JSON.parse(rawData, (key, value) => {
+			const parsed = JSON.parse(rawData, (key, value) => {
 				if (key === "timestamp" && typeof value === "string") return new Date(value);
 				return value;
 			});
+			if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string" || !parsed.meta?.id) {
+				this.logger.warn("[RedisStreamTransport] Malformed event — missing type or meta.id, acking and skipping");
+				await this.redis.xack(this.stream, this.group, messageId);
+				return;
+			}
+			event = parsed;
 		} catch {
 			await this.redis.xack(this.stream, this.group, messageId);
 			return;
@@ -152,7 +165,7 @@ var RedisStreamTransport = class {
 		if (pattern === eventType) return true;
 		if (pattern.endsWith(".*")) {
 			const prefix = pattern.slice(0, -2);
-			return eventType.startsWith(prefix + ".");
+			return eventType.startsWith(`${prefix}.`);
 		}
 		return false;
 	}
@@ -172,6 +185,5 @@ var RedisStreamTransport = class {
 		return new Promise((resolve) => setTimeout(resolve, ms));
 	}
 };
-
 //#endregion
-export { RedisStreamTransport };
+export { RedisStreamTransport };

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-BkUDYZEb.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "../../EventTransport-wc5hSLik.mjs";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {