@classytic/arc 2.11.2 → 2.11.4

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--5HIkdPU.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-BhrzxvyQ.mjs";
+import { n as createChildEvent, r as createEvent, t as MemoryEventTransport } from "../EventTransport-BFQjw9pB.mjs";
+import { n as defineEvent, t as createEventRegistry } from "../defineEvent-D1Ky9M1D.mjs";
+import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-Cts2-Tfj.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-Cp4uKC1U.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
@@ -217,12 +42,16 @@ function crudEventType(resource, suffix) {
 }
 /** Arc framework lifecycle events — emitted automatically by the framework */
 const ARC_LIFECYCLE_EVENTS = Object.freeze({
+	/** Emitted when a resource plugin is registered */
 	RESOURCE_REGISTERED: "arc.resource.registered",
+	/** Emitted when Arc is fully ready (all resources registered, onReady fired) */
 	READY: "arc.ready"
 });
 /** Cache-specific event types for observability and external triggers */
 const CACHE_EVENTS = Object.freeze({
+	/** Emitted when a resource's cache version is bumped */
 	VERSION_BUMPED: "arc.cache.version.bumped",
+	/** Emitted when a tag version is bumped */
 	TAG_VERSION_BUMPED: "arc.cache.tag.bumped"
 });
 //#endregion
@@ -489,7 +318,7 @@ function repositoryAsOutboxStore(repository) {
 				code: error.code
 			} : { message: error.message };
 			const firstFailedAt = current.firstFailedAt ?? now;
-			await r.findOneAndUpdate(filter, update({ set: {
+			if (await r.findOneAndUpdate(filter, update({ set: {
 				status: targetStatus,
 				visibleAt,
 				leaseOwner: null,
@@ -497,7 +326,11 @@ function repositoryAsOutboxStore(repository) {
 				lastFailedAt: now,
 				lastError: errorInfo,
 				firstFailedAt
-			} }), { returnDocument: "after" });
+			} }), { returnDocument: "after" })) return;
+			if (options?.consumerId) {
+				const after = await safeGetOne(baseFilter);
+				if (after && after.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, after.leaseOwner);
+			}
 		},
 		async getDeadLettered(limit) {
 			return unwrapDocs(await r.getAll({
@@ -878,4 +711,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-D1Ky9M1D.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, createChildEvent, createDeadLetterPublisher, createEvent, 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-xTGxB2bm.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };

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

@@ -13,10 +13,34 @@ var RedisStreamTransport = class {
 	maxLen;
 	maxPayloadBytes;
 	logger;
+	/** Tracks the lifecycle policy — set in constructor, read in close(). */
+	externalLifecycle;
+	closeTimeoutMs;
 	handlers = /* @__PURE__ */ new Map();
 	running = false;
 	pollPromise = null;
+	/**
+	* Monotonic counter bumped every time the poll loop should stop —
+	* `unsubscribe` (last handler removed) and `close()` increment it. Each
+	* `pollLoop` instance captures its generation at start and exits when
+	* `this.generation` no longer matches. Prevents the
+	* subscribe → unsubscribe → fast-resubscribe race where the old loop
+	* would still be in `XREADGROUP BLOCK` while a new loop started, leading
+	* to two concurrent poll loops on the same consumer name.
+	*/
+	generation = 0;
 	groupCreated = false;
+	/**
+	* Last-seen failure context per message id, populated when an in-process
+	* handler throws in {@link processEntry}. Consumed (and cleared) by
+	* {@link moveToDlq} so the dead-letter envelope carries the actual error
+	* message instead of opaque "reclaimed without context". Bounded by
+	* `maxRetries × consumer-throughput` — entries are deleted on ack and
+	* on DLQ write, so the map naturally drains.
+	*/
+	failureContext = /* @__PURE__ */ new Map();
+	/** One-shot guard so the "client lacks xrange" warning fires once per process. */
+	xrangeWarningEmitted = false;
 	constructor(redis, options = {}) {
 		this.redis = redis;
 		this.stream = options.stream ?? "arc:events";
@@ -29,6 +53,8 @@ var RedisStreamTransport = class {
 		this.deadLetterStream = options.deadLetterStream ?? "arc:events:dlq";
 		this.maxLen = options.maxLen ?? 1e4;
 		this.maxPayloadBytes = options.maxPayloadBytes ?? 1e6;
+		this.externalLifecycle = options.externalLifecycle ?? false;
+		this.closeTimeoutMs = options.closeTimeoutMs ?? 1e3;
 		this.logger = options.logger ?? console;
 	}
 	async publish(event) {
@@ -55,9 +81,10 @@ var RedisStreamTransport = class {
 		if (!this.running) {
 			await this.ensureGroup();
 			this.running = true;
-			this.pollPromise = this.pollLoop().catch((err) => {
+			const myGen = ++this.generation;
+			this.pollPromise = this.pollLoop(myGen).catch((err) => {
 				this.logger.error("[RedisStreamTransport] Poll loop crashed:", err);
-				this.running = false;
+				if (this.generation === myGen) this.running = false;
 			});
 		}
 		return () => {
@@ -66,16 +93,59 @@ var RedisStreamTransport = class {
 				set.delete(handler);
 				if (set.size === 0) this.handlers.delete(pattern);
 			}
-			if (this.handlers.size === 0 && this.running) this.running = false;
+			if (this.handlers.size === 0 && this.running) {
+				this.running = false;
+				this.generation++;
+			}
 		};
 	}
+	/**
+	* Stop polling and release transport state.
+	*
+	* **Two close contracts** — pick the one that matches your deployment:
+	*
+	* 1. **Default (`externalLifecycle: false`) — strict bounded close.**
+	*    `close()` waits up to `closeTimeoutMs` for the in-flight
+	*    `XREADGROUP BLOCK` to drain. On timeout it calls `redis.disconnect()`
+	*    (or `quit()` if the client lacks `disconnect`) to break the BLOCK
+	*    immediately, then awaits the loop's exit. After `close()` returns
+	*    the transport is fully closed and the connection is released.
+	*
+	* 2. **`externalLifecycle: true` — bounded RETURN, background drain.**
+	*    Arc must NOT touch a connection it doesn't own. `close()` returns
+	*    within `closeTimeoutMs`, but the poll loop is left to drain on its
+	*    own when its outstanding `XREADGROUP BLOCK` returns (up to
+	*    `blockTimeMs`). Arc silently absorbs the loop's eventual completion
+	*    so the host doesn't see unhandled rejections / log spam against a
+	*    transport it considers closed. The host's own `redis.quit()` /
+	*    process exit is what ultimately tears the connection down.
+	*
+	*    Practical implication: under `externalLifecycle: true`, set
+	*    `blockTimeMs` low (e.g. 500ms) so the background drain window is
+	*    short. The transport is "closed enough" to stop dispatching to
+	*    handlers (handlers map is cleared and generation is bumped) but is
+	*    not "fully closed" in the connection-lifecycle sense until the host
+	*    closes the underlying client.
+	*
+	* In both modes the generation counter is bumped, so a follow-up
+	* `subscribe()` spawns a fresh poll loop with a new generation — the
+	* stale loop exits on its next iteration and never overlaps the new one.
+	*/
 	async close() {
 		this.running = false;
+		this.generation++;
 		this.handlers.clear();
 		if (this.pollPromise) {
-			await this.pollPromise;
+			if (await Promise.race([this.pollPromise.then(() => "drained"), this.sleep(this.closeTimeoutMs).then(() => "timeout")]) === "timeout") if (!this.externalLifecycle) {
+				if (typeof this.redis.disconnect === "function") this.redis.disconnect();
+				else await this.redis.quit().catch((err) => {
+					this.logger.error("[RedisStreamTransport] quit() during close raced:", err);
+				});
+				await this.pollPromise.catch(() => void 0);
+			} else this.pollPromise.catch(() => void 0);
 			this.pollPromise = null;
 		}
+		if (!this.externalLifecycle) await this.redis.quit().catch(() => void 0);
 	}
 	async ensureGroup() {
 		if (this.groupCreated) return;
@@ -86,12 +156,12 @@ var RedisStreamTransport = class {
 		}
 		this.groupCreated = true;
 	}
-	async pollLoop() {
-		while (this.running) try {
+	async pollLoop(myGen) {
+		while (this.running && this.generation === myGen) try {
 			await this.claimPending();
 			await this.readNewMessages();
 		} catch (err) {
-			if (this.running) {
+			if (this.running && this.generation === myGen) {
 				this.logger.error("[RedisStreamTransport] Poll error:", err);
 				await this.sleep(1e3);
 			}
@@ -123,39 +193,38 @@ var RedisStreamTransport = class {
 		}
 	}
 	async processEntry(messageId, fields) {
-		const fieldMap = /* @__PURE__ */ new Map();
-		for (let i = 0; i < fields.length; i += 2) fieldMap.set(fields[i], fields[i + 1]);
-		const eventType = fieldMap.get("type");
-		const rawData = fieldMap.get("data");
-		if (!eventType || !rawData) {
-			await this.redis.xack(this.stream, this.group, messageId);
-			return;
-		}
-		let event;
-		try {
-			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 {
+		const event = parseStreamFields(fields);
+		if (!event) {
+			this.logger.warn(`[RedisStreamTransport] Malformed entry ${messageId} — missing type/data or invalid JSON, acking and skipping`);
 			await this.redis.xack(this.stream, this.group, messageId);
 			return;
 		}
 		const matchingHandlers = this.getMatchingHandlers(event.type);
 		let allSucceeded = true;
+		let lastError;
+		let lastHandlerName;
 		for (const handler of matchingHandlers) try {
 			await handler(event);
 		} catch (err) {
 			allSucceeded = false;
+			lastError = err instanceof Error ? err : new Error(String(err));
+			lastHandlerName = handler.name || lastHandlerName;
 			this.logger.error(`[RedisStreamTransport] Handler error for ${event.type}:`, err);
 		}
-		if (allSucceeded) await this.redis.xack(this.stream, this.group, messageId);
+		if (allSucceeded) {
+			await this.redis.xack(this.stream, this.group, messageId);
+			this.failureContext.delete(messageId);
+			return;
+		}
+		const now = /* @__PURE__ */ new Date();
+		const prior = this.failureContext.get(messageId);
+		this.failureContext.set(messageId, {
+			error: lastError ? toErrorRecord(lastError) : { message: "handler returned without acking — no error captured" },
+			firstFailedAt: prior?.firstFailedAt ?? now,
+			lastFailedAt: now,
+			attempts: (prior?.attempts ?? 0) + 1,
+			handlerName: lastHandlerName ?? prior?.handlerName
+		});
 	}
 	getMatchingHandlers(eventType) {
 		const matched = [];
@@ -173,19 +242,123 @@ var RedisStreamTransport = class {
 	}
 	async moveToDlq(ids) {
 		if (this.deadLetterStream === false) {
-			for (const id of ids) await this.redis.xack(this.stream, this.group, id);
+			for (const id of ids) {
+				await this.redis.xack(this.stream, this.group, id);
+				this.failureContext.delete(id);
+			}
 			return;
 		}
 		for (const id of ids) try {
-			await this.redis.xadd(this.deadLetterStream, "*", "originalStream", this.stream, "originalId", id, "group", this.group, "failedAt", (/* @__PURE__ */ new Date()).toISOString());
+			const envelope = await this.buildDlqEnvelope(id);
+			if (!envelope) {
+				this.logger.error(`[RedisStreamTransport] DLQ for ${id}: source entry missing AND no failure context — acking to drop`);
+				await this.redis.xack(this.stream, this.group, id);
+				this.failureContext.delete(id);
+				continue;
+			}
+			await this.redis.xadd(this.deadLetterStream, "*", "type", envelope.event.type, "originalStream", this.stream, "originalId", id, "group", this.group, "data", JSON.stringify(envelope));
 			await this.redis.xack(this.stream, this.group, id);
+			this.failureContext.delete(id);
 		} catch (err) {
 			this.logger.error(`[RedisStreamTransport] DLQ write failed for ${id}:`, err);
 		}
 	}
+	/**
+	* Reconstruct a `DeadLetteredEvent` for a message id. Reads the original
+	* entry via `xrange` (when the client supports it) and merges in any
+	* in-process failure context. Returns `null` only when BOTH sources are
+	* missing — callers ack-and-drop rather than re-queuing a ghost.
+	*
+	* Graceful degradation paths:
+	*   - Client lacks `xrange` (older custom wrappers) → log once, build the
+	*     envelope from `failureContext` alone. Payload is absent but the
+	*     error reason + attempt accounting still survive.
+	*   - `xrange` throws (network blip, ACL) → same fallback.
+	*   - Source entry trimmed before DLQ write → same fallback.
+	*/
+	async buildDlqEnvelope(id) {
+		const ctx = this.failureContext.get(id);
+		let event = null;
+		if (typeof this.redis.xrange === "function") try {
+			const fields = (await this.redis.xrange(this.stream, id, id))[0]?.[1];
+			if (fields) {
+				const parsed = parseStreamFields(fields);
+				if (parsed) event = parsed;
+			}
+		} catch (err) {
+			this.logger.error(`[RedisStreamTransport] xrange for DLQ source ${id} failed:`, err);
+		}
+		else if (!this.xrangeWarningEmitted) {
+			this.xrangeWarningEmitted = true;
+			this.logger.warn("[RedisStreamTransport] Redis client lacks xrange() — DLQ envelopes will not include the original event payload. Upgrade your client (ioredis ≥4 supports it) or use a wrapper that proxies xrange to enable replay.");
+		}
+		if (!event && !ctx) return null;
+		const fallbackTime = /* @__PURE__ */ new Date();
+		return {
+			event: event ?? {
+				type: "<unknown>",
+				payload: null,
+				meta: {
+					id,
+					timestamp: fallbackTime
+				}
+			},
+			error: ctx?.error ?? { message: "exhausted retries — failure occurred on a different consumer; error context not preserved across consumer-group failover" },
+			attempts: ctx?.attempts ?? this.maxRetries,
+			firstFailedAt: ctx?.firstFailedAt ?? fallbackTime,
+			lastFailedAt: ctx?.lastFailedAt ?? fallbackTime,
+			...ctx?.handlerName ? { handlerName: ctx.handlerName } : {}
+		};
+	}
 	sleep(ms) {
 		return new Promise((resolve) => setTimeout(resolve, ms));
 	}
 };
+/**
+* Convert a thrown value into the `DeadLetteredEvent.error` shape — message
+* always present, optional `code` (string only) and `stack`. Centralised so
+* the failure-context tracker and the DLQ envelope writer agree.
+*/
+function toErrorRecord(err) {
+	const e = err instanceof Error ? err : new Error(String(err));
+	const code = e.code;
+	return {
+		message: e.message,
+		...typeof code === "string" ? { code } : {},
+		...e.stack ? { stack: e.stack } : {}
+	};
+}
+/**
+* Parse a Redis Stream entry's flat `[key, value, key, value, ...]` field
+* array into a typed `DomainEvent`, or `null` when the entry is malformed
+* (missing `type` / `data`, unparseable JSON, or missing required event
+* structure).
+*
+* Pure on purpose — used by both `processEntry` (the live consumer path)
+* and `buildDlqEnvelope` (the dead-letter writer). Keeping the parse logic
+* in one place avoids the silent drift class that produced the original
+* "DLQ has no payload" bug.
+*/
+function parseStreamFields(fields) {
+	let eventType;
+	let rawData;
+	for (let i = 0; i < fields.length; i += 2) {
+		const key = fields[i];
+		const value = fields[i + 1];
+		if (key === "type") eventType = value;
+		else if (key === "data") rawData = value;
+	}
+	if (!eventType || !rawData) return null;
+	try {
+		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) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
 //#endregion
 export { RedisStreamTransport };

package/dist/events/transports/redis.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";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {