@kronos-ts/messaging 0.3.0 → 0.4.0

package/dist/dead-letter-listener.d.ts

@@ -0,0 +1,36 @@
+import type { DeadLetter } from "./dead-letter-queue.js";
+/**
+ * Observability hook for dead-letter lifecycle events. Implementations receive
+ * a callback at each transition so operators can emit metrics, logs, or traces
+ * (queue depth, dead-letter rate, reprocessing outcomes, overflow/backpressure).
+ *
+ * All callbacks are best-effort and synchronous from the queue's perspective —
+ * implementations must not throw and should not block.
+ */
+export interface DeadLetterListener {
+    /** A failed event was parked. `blocked` is true when parked only because an
+     * earlier letter in its sequence failed (ordering gate), not a fresh failure. */
+    onEnqueued(letter: DeadLetter, info: {
+        blocked: boolean;
+    }): void;
+    /** A letter was removed after successful reprocessing or being given up on. */
+    onEvicted(letter: DeadLetter): void;
+    /** A letter was re-parked after a reprocess attempt left it still failing. */
+    onRequeued(letter: DeadLetter): void;
+    /** A reprocess attempt succeeded. */
+    onReprocessSuccess(letter: DeadLetter): void;
+    /** A reprocess attempt failed; `decision` is what the policy chose next. */
+    onReprocessFailure(letter: DeadLetter, cause: Error): void;
+    /** The queue rejected an enqueue because it was full (Axon backpressure). */
+    onOverflow(sequenceIdentifier: string, cause: Error): void;
+}
+/** A listener that does nothing. Default. */
+export declare function noOpDeadLetterListener(): DeadLetterListener;
+/**
+ * Logs each dead-letter transition. A reasonable default for getting visibility
+ * without wiring a metrics backend.
+ */
+export declare function loggingDeadLetterListener(processorName: string): DeadLetterListener;
+/** Fan a single notification out to several listeners. */
+export declare function multiDeadLetterListener(listeners: ReadonlyArray<DeadLetterListener>): DeadLetterListener;
+//# sourceMappingURL=dead-letter-listener.d.ts.map

package/dist/dead-letter-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-listener.d.ts","sourceRoot":"","sources":["../src/dead-letter-listener.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;qFACiF;IACjF,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IAChE,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IACnC,8EAA8E;IAC9E,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IACpC,qCAAqC;IACrC,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IAC5C,4EAA4E;IAC5E,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAC1D,6EAA6E;IAC7E,UAAU,CAAC,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAC3D;AAED,6CAA6C;AAC7C,wBAAgB,sBAAsB,IAAI,kBAAkB,CAS3D;AAMD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,kBAAkB,CA0BnF;AAED,0DAA0D;AAC1D,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAC3C,kBAAkB,CAkBpB"}

package/dist/dead-letter-listener.js

@@ -0,0 +1,69 @@
+import { qualifiedNameToString } from "@kronos-ts/common";
+/** A listener that does nothing. Default. */
+export function noOpDeadLetterListener() {
+    return {
+        onEnqueued() { },
+        onEvicted() { },
+        onRequeued() { },
+        onReprocessSuccess() { },
+        onReprocessFailure() { },
+        onOverflow() { },
+    };
+}
+function describe(letter) {
+    return `${qualifiedNameToString(letter.message.name)} (seq "${letter.sequenceIdentifier}")`;
+}
+/**
+ * Logs each dead-letter transition. A reasonable default for getting visibility
+ * without wiring a metrics backend.
+ */
+export function loggingDeadLetterListener(processorName) {
+    const tag = `Dead letter queue "${processorName}":`;
+    return {
+        onEnqueued(letter, info) {
+            if (info.blocked) {
+                console.warn(`${tag} blocked ${describe(letter)} — earlier letter in sequence failed`);
+            }
+            else {
+                console.warn(`${tag} parked ${describe(letter)}:`, letter.cause);
+            }
+        },
+        onEvicted(letter) {
+            console.info(`${tag} evicted ${describe(letter)}`);
+        },
+        onRequeued(letter) {
+            console.warn(`${tag} requeued ${describe(letter)} — still failing`);
+        },
+        onReprocessSuccess(letter) {
+            console.info(`${tag} reprocessed ${describe(letter)}`);
+        },
+        onReprocessFailure(letter, cause) {
+            console.warn(`${tag} reprocess failed for ${describe(letter)}:`, cause);
+        },
+        onOverflow(sequenceIdentifier, cause) {
+            console.error(`${tag} overflow on sequence "${sequenceIdentifier}" — applying backpressure:`, cause);
+        },
+    };
+}
+/** Fan a single notification out to several listeners. */
+export function multiDeadLetterListener(listeners) {
+    if (listeners.length === 0)
+        return noOpDeadLetterListener();
+    if (listeners.length === 1)
+        return listeners[0];
+    const fanOut = (method) => (...args) => {
+        for (const l of listeners) {
+            ;
+            l[method](...args);
+        }
+    };
+    return {
+        onEnqueued: fanOut("onEnqueued"),
+        onEvicted: fanOut("onEvicted"),
+        onRequeued: fanOut("onRequeued"),
+        onReprocessSuccess: fanOut("onReprocessSuccess"),
+        onReprocessFailure: fanOut("onReprocessFailure"),
+        onOverflow: fanOut("onOverflow"),
+    };
+}
+//# sourceMappingURL=dead-letter-listener.js.map

package/dist/dead-letter-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-listener.js","sourceRoot":"","sources":["../src/dead-letter-listener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AA2BzD,6CAA6C;AAC7C,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,UAAU,KAAI,CAAC;QACf,SAAS,KAAI,CAAC;QACd,UAAU,KAAI,CAAC;QACf,kBAAkB,KAAI,CAAC;QACvB,kBAAkB,KAAI,CAAC;QACvB,UAAU,KAAI,CAAC;KAChB,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,MAAkB;IAClC,OAAO,GAAG,qBAAqB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,kBAAkB,IAAI,CAAA;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,aAAqB;IAC7D,MAAM,GAAG,GAAG,sBAAsB,aAAa,IAAI,CAAA;IACnD,OAAO;QACL,UAAU,CAAC,MAAM,EAAE,IAAI;YACrB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,YAAY,QAAQ,CAAC,MAAM,CAAC,sCAAsC,CAAC,CAAA;YACxF,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,WAAW,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;YAClE,CAAC;QACH,CAAC;QACD,SAAS,CAAC,MAAM;YACd,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,YAAY,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACpD,CAAC;QACD,UAAU,CAAC,MAAM;YACf,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,aAAa,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;QACrE,CAAC;QACD,kBAAkB,CAAC,MAAM;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,gBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACxD,CAAC;QACD,kBAAkB,CAAC,MAAM,EAAE,KAAK;YAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,yBAAyB,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACzE,CAAC;QACD,UAAU,CAAC,kBAAkB,EAAE,KAAK;YAClC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,0BAA0B,kBAAkB,4BAA4B,EAAE,KAAK,CAAC,CAAA;QACtG,CAAC;KACF,CAAA;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,uBAAuB,CACrC,SAA4C;IAE5C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,sBAAsB,EAAE,CAAA;IAC3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,CAAE,CAAA;IAChD,MAAM,MAAM,GACV,CAAqC,MAAS,EAAE,EAAE,CAClD,CAAC,GAAG,IAAuC,EAAE,EAAE;QAC7C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,CAAC;YAAC,CAAC,CAAC,MAAM,CAA+B,CAAC,GAAG,IAAI,CAAC,CAAA;QACpD,CAAC;IACH,CAAC,CAAA;IACH,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC;QAChC,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,CAAC;QAChD,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,CAAC;QAChD,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC;KACjC,CAAA;AACH,CAAC"}

package/dist/dead-letter-queue.d.ts

@@ -39,10 +39,6 @@ export interface EnqueuePolicy {
      */
     decide(letter: DeadLetter, cause: Error): EnqueueDecision;
 }
-/**
- * Default policy: always enqueue with the original cause.
- */
-export declare function alwaysEnqueuePolicy(): EnqueuePolicy;
 /**
  * A sequenced dead letter queue that maintains ordering within sequences.
  *
@@ -100,16 +96,18 @@ export interface SequencedDeadLetterQueue {
      */
     process(sequenceFilter: (sequenceId: string) => boolean, processingTask: (letter: DeadLetter) => Promise<EnqueueDecision>): Promise<boolean>;
     /** Total number of dead letters across all sequences. */
-    size(): number;
+    size(): Promise<number>;
     /** Number of sequences with dead letters. */
-    amountOfSequences(): number;
+    amountOfSequences(): Promise<number>;
     /** Clear all dead letters. */
     clear(): Promise<void>;
     /**
      * Check if the queue is full for the given sequence.
      * Returns true if max sequences or max sequence size is reached.
+     *
+     * Async so persistent backends can answer with a count query.
      */
-    isFull(sequenceIdentifier: string): boolean;
+    isFull(sequenceIdentifier: string): Promise<boolean>;
 }
 /**
  * Creates an in-memory dead letter queue.

package/dist/dead-letter-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/dead-letter-queue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/dead-letter-queue.ts"],"names":[],"mappings":"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"}

package/dist/dead-letter-queue.js

@@ -1,13 +1,3 @@
-/**
- * Default policy: always enqueue with the original cause.
- */
-export function alwaysEnqueuePolicy() {
-    return {
-        decide() {
-            return { shouldEnqueue: true };
-        },
-    };
-}
 /**
  * Creates an in-memory dead letter queue.
  *
@@ -127,21 +117,21 @@ export function createInMemoryDeadLetterQueue(options) {
                 processing.delete(oldestId);
             }
         },
-        size() {
+        async size() {
             let total = 0;
             for (const letters of sequences.values()) {
                 total += letters.length;
             }
             return total;
         },
-        amountOfSequences() {
+        async amountOfSequences() {
             return sequences.size;
         },
         async clear() {
             sequences.clear();
             processing.clear();
         },
-        isFull(sequenceIdentifier) {
+        async isFull(sequenceIdentifier) {
             const seq = sequences.get(sequenceIdentifier);
             if (seq) {
                 return seq.length >= maxSequenceSize;

package/dist/dead-letter-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"dead-letter-queue.js","sourceRoot":"","sources":["../src/dead-letter-queue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dead-letter-queue.js","sourceRoot":"","sources":["../src/dead-letter-queue.ts"],"names":[],"mappings":"AAqIA;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAG7C;IACC,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,IAAI,CAAA;IAClD,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,IAAI,CAAA;IAExD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAA;IACjD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAA;IAEpC,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;YACpD,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,GAAG,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;oBAClC,MAAM,IAAI,4BAA4B,CACpC,aAAa,MAAM,CAAC,kBAAkB,0BAA0B,eAAe,EAAE,CAClF,CAAA;gBACH,CAAC;gBACD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAClB,CAAC;iBAAM,CAAC;gBACN,IAAI,SAAS,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;oBACnC,MAAM,IAAI,4BAA4B,CACpC,iBAAiB,YAAY,UAAU,CACxC,CAAA;gBACH,CAAC;gBACD,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;YACpD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,cAAc;YACvD,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAC7C,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAA;YACtB,IAAI,GAAG,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;gBAClC,MAAM,IAAI,4BAA4B,CACpC,aAAa,kBAAkB,0BAA0B,eAAe,EAAE,CAC3E,CAAA;YACH,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAA;YAC1B,OAAO,IAAI,CAAA;QACb,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,kBAAkB,EAAE,MAAM;YACpC,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAC7C,IAAI,CAAC,GAAG;gBAAE,OAAM;YAChB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YAC/B,IAAI,GAAG,IAAI,CAAC;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAChC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;QAC5D,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAO;YAC3B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;YACpD,IAAI,CAAC,GAAG;gBAAE,OAAM;YAEhB,MAAM,OAAO,GAAe;gBAC1B,GAAG,MAAM;gBACT,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;gBACvB,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,KAAK;gBACpC,WAAW,EAAE,MAAM,EAAE,WAAW;oBAC9B,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE;oBAClD,CAAC,CAAC,MAAM,CAAC,WAAW;aACvB,CAAA;YAED,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YAC/B,IAAI,GAAG,IAAI,CAAC;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAChC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACtB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,kBAAkB;YAC/B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAC7C,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;QAC5C,CAAC;QAED,KAAK,CAAC,kBAAkB,CAAC,kBAAkB;YACzC,OAAO,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,mBAAmB;YACvB,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;QAC9B,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,cAAc;YAC1C,+CAA+C;YAC/C,IAAI,QAA4B,CAAA;YAChC,IAAI,UAAU,GAAG,QAAQ,CAAA;YAEzB,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,SAAS,EAAE,CAAC;gBACtC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,SAAQ;gBAChC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;oBAAE,SAAQ;gBAClC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;oBAAE,SAAQ;gBAEjC,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,WAAW,CAAA;gBAC5C,IAAI,YAAY,GAAG,UAAU,EAAE,CAAC;oBAC9B,UAAU,GAAG,YAAY,CAAA;oBACzB,QAAQ,GAAG,EAAE,CAAA;gBACf,CAAC;YACH,CAAC;YAED,IAAI,CAAC,QAAQ;gBAAE,OAAO,KAAK,CAAA;YAE3B,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACxB,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;gBACvC,IAAI,CAAC,OAAO;oBAAE,OAAO,KAAK,CAAA;gBAE1B,gEAAgE;gBAChE,MAAM,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;gBAC7B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;oBAC9B,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAA;oBAC7C,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;wBAC3B,+CAA+C;wBAC/C,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;4BACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;4BACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;yBAClC,CAAC,CAAA;wBACF,OAAO,IAAI,CAAA;oBACb,CAAC;oBACD,mCAAmC;oBACnC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAS,EAAE,MAAM,CAAC,CAAA;gBACrC,CAAC;gBACD,OAAO,IAAI,CAAA;YACb,CAAC;oBAAS,CAAC;gBACT,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC7B,CAAC;QACH,CAAC;QAED,KAAK,CAAC,IAAI;YACR,IAAI,KAAK,GAAG,CAAC,CAAA;YACb,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;gBACzC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAA;YACzB,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,KAAK,CAAC,iBAAiB;YACrB,OAAO,SAAS,CAAC,IAAI,CAAA;QACvB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,SAAS,CAAC,KAAK,EAAE,CAAA;YACjB,UAAU,CAAC,KAAK,EAAE,CAAA;QACpB,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,kBAAkB;YAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAC7C,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,GAAG,CAAC,MAAM,IAAI,eAAe,CAAA;YACtC,CAAC;YACD,OAAO,SAAS,CAAC,IAAI,IAAI,YAAY,CAAA;QACvC,CAAC;KACF,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,+BAA+B,OAAO,EAAE,CAAC,CAAA;QAC/C,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC5C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAqB,EACrB,KAAY,EACZ,kBAA0B,EAC1B,WAAqC;IAErC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IACtB,OAAO;QACL,OAAO;QACP,KAAK;QACL,UAAU,EAAE,GAAG;QACf,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,WAAW,IAAI,EAAE;QAC9B,kBAAkB;KACnB,CAAA;AACH,CAAC"}

package/dist/dead-letter-reprocessor.d.ts

@@ -0,0 +1,44 @@
+import type { DeadLetter, SequencedDeadLetterQueue, EnqueuePolicy } from "./dead-letter-queue.js";
+import { type DeadLetterListener } from "./dead-letter-listener.js";
+import type { UoWRunner } from "./unit-of-work.js";
+/**
+ * Replays a single dead letter through its handlers. Resolves on success and
+ * rejects with the handler's error on failure. Supplied by the owning
+ * processor, which re-establishes the same ALS resources (state manager,
+ * command/query bus) it uses for live delivery.
+ */
+export type DeadLetterReplay = (letter: DeadLetter) => Promise<void>;
+export interface DeadLetterReprocessorOptions {
+    queue: SequencedDeadLetterQueue;
+    replay: DeadLetterReplay;
+    /** Decides requeue-vs-evict after a failed retry. Default: always requeue. */
+    policy?: EnqueuePolicy;
+    /** Runs each reprocess inside a UnitOfWork so the claim/evict/requeue and any
+     * handler side effects commit in one transaction. Default: a fresh UoW. */
+    unitOfWorkRunner?: UoWRunner;
+    listener?: DeadLetterListener;
+}
+export interface DeadLetterReprocessor {
+    /**
+     * Reprocess the oldest dead-letter sequence matching the filter, once.
+     * Walks the sequence head-to-tail: each letter that replays successfully is
+     * evicted; the first that fails is requeued (per policy) and stops the walk,
+     * keeping the sequence ordered. Returns true if a sequence was processed.
+     */
+    reprocess(filter?: (sequenceId: string) => boolean): Promise<boolean>;
+    /**
+     * One drain pass over every currently-parked sequence matching the filter,
+     * each attempted at most once (a still-failing sequence is left requeued, not
+     * retried in a hot loop). Returns the number of sequences attempted.
+     */
+    reprocessAll(filter?: (sequenceId: string) => boolean): Promise<number>;
+}
+/**
+ * Binds a {@link SequencedDeadLetterQueue} to a replay function, producing the
+ * Axon `SequencedDeadLetterProcessor` capability: drive parked events back
+ * through their handlers, evicting on success and requeuing on continued
+ * failure. Trigger it manually or on a schedule (see the processor's
+ * `dlqRetryIntervalMs`).
+ */
+export declare function createDeadLetterReprocessor(options: DeadLetterReprocessorOptions): DeadLetterReprocessor;
+//# sourceMappingURL=dead-letter-reprocessor.d.ts.map

package/dist/dead-letter-reprocessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-reprocessor.d.ts","sourceRoot":"","sources":["../src/dead-letter-reprocessor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEjG,OAAO,EAAE,KAAK,kBAAkB,EAA0B,MAAM,2BAA2B,CAAA;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGlD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEpE,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,wBAAwB,CAAA;IAC/B,MAAM,EAAE,gBAAgB,CAAA;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;+EAC2E;IAC3E,gBAAgB,CAAC,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrE;;;;OAIG;IACH,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,qBAAqB,CA2CvB"}

package/dist/dead-letter-reprocessor.js

@@ -0,0 +1,48 @@
+import { emptyMetadata } from "@kronos-ts/common";
+import { Decisions, alwaysEnqueuePolicy } from "./enqueue-policy.js";
+import { noOpDeadLetterListener } from "./dead-letter-listener.js";
+import { runInNewUoW } from "./unit-of-work.js";
+/**
+ * Binds a {@link SequencedDeadLetterQueue} to a replay function, producing the
+ * Axon `SequencedDeadLetterProcessor` capability: drive parked events back
+ * through their handlers, evicting on success and requeuing on continued
+ * failure. Trigger it manually or on a schedule (see the processor's
+ * `dlqRetryIntervalMs`).
+ */
+export function createDeadLetterReprocessor(options) {
+    const { queue, replay, policy = alwaysEnqueuePolicy(), unitOfWorkRunner = runInNewUoW, listener = noOpDeadLetterListener(), } = options;
+    async function reprocess(filter = () => true) {
+        return unitOfWorkRunner(emptyMetadata(), async () => queue.process(filter, async (letter) => {
+            try {
+                await replay(letter);
+                listener.onReprocessSuccess(letter);
+                listener.onEvicted(letter);
+                return Decisions.evict();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                listener.onReprocessFailure(letter, error);
+                const decision = policy.decide(letter, error);
+                if (decision.shouldEnqueue) {
+                    listener.onRequeued(letter);
+                }
+                else {
+                    listener.onEvicted(letter);
+                }
+                return decision;
+            }
+        }));
+    }
+    async function reprocessAll(filter = () => true) {
+        const ids = (await queue.sequenceIdentifiers()).filter(filter);
+        let attempted = 0;
+        for (const id of ids) {
+            const processed = await reprocess((s) => s === id);
+            if (processed)
+                attempted++;
+        }
+        return attempted;
+    }
+    return { reprocess, reprocessAll };
+}
+//# sourceMappingURL=dead-letter-reprocessor.js.map

package/dist/dead-letter-reprocessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-reprocessor.js","sourceRoot":"","sources":["../src/dead-letter-reprocessor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAA2B,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AAE3F,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAqC/C;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAqC;IAErC,MAAM,EACJ,KAAK,EACL,MAAM,EACN,MAAM,GAAG,mBAAmB,EAAE,EAC9B,gBAAgB,GAAG,WAAW,EAC9B,QAAQ,GAAG,sBAAsB,EAAE,GACpC,GAAG,OAAO,CAAA;IAEX,KAAK,UAAU,SAAS,CAAC,SAA0C,GAAG,EAAE,CAAC,IAAI;QAC3E,OAAO,gBAAgB,CAAC,aAAa,EAAE,EAAE,KAAK,IAAI,EAAE,CAClD,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,MAAM,CAAC,CAAA;gBACpB,QAAQ,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;gBACnC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;gBAC1B,OAAO,SAAS,CAAC,KAAK,EAAE,CAAA;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;gBACjE,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;gBAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;gBAC7C,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;oBAC3B,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;gBAC7B,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;gBAC5B,CAAC;gBACD,OAAO,QAAQ,CAAA;YACjB,CAAC;QACH,CAAC,CAAC,CACH,CAAA;IACH,CAAC;IAED,KAAK,UAAU,YAAY,CAAC,SAA0C,GAAG,EAAE,CAAC,IAAI;QAC9E,MAAM,GAAG,GAAG,CAAC,MAAM,KAAK,CAAC,mBAAmB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC9D,IAAI,SAAS,GAAG,CAAC,CAAA;QACjB,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;YAClD,IAAI,SAAS;gBAAE,SAAS,EAAE,CAAA;QAC5B,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;AACpC,CAAC"}

package/dist/dead-lettering-handler.d.ts

@@ -1,7 +1,8 @@
-import type { EventMessage } from "./message.js";
 import type { EventHandlerRegistration } from "./handler.js";
 import type { SequencedEvent } from "./event-source.js";
+import { type SequencingPolicy } from "./sequencing-policy.js";
 import { type SequencedDeadLetterQueue, type EnqueuePolicy } from "./dead-letter-queue.js";
+import { type DeadLetterListener } from "./dead-letter-listener.js";
 /**
  * Options for dead-lettering event handler wrapper.
  */
@@ -11,11 +12,13 @@ export interface DeadLetteringOptions {
     /** Policy deciding whether to dead-letter a failed event. Default: always. */
     policy?: EnqueuePolicy;
     /**
-     * Extract a sequence identifier from an event. Events in the same
+     * Decides which ordered sequence an event belongs to. Events in the same
      * sequence are ordered — if one fails, subsequent ones are blocked.
-     * Default: uses the first tag value or event name.
+     * Default: {@link defaultSequencingPolicy} (first tag value, else event name).
      */
-    sequenceIdentifier?: (event: EventMessage) => string;
+    sequencingPolicy?: SequencingPolicy;
+    /** Observability hook for dead-letter lifecycle events. Default: no-op. */
+    listener?: DeadLetterListener;
 }
 /**
  * Wraps event delivery with dead-letter support.

package/dist/dead-lettering-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dead-lettering-handler.d.ts","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAGnB,MAAM,wBAAwB,CAAA;AAE/B;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,KAAK,EAAE,wBAAwB,CAAA;IAC/B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAA;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB;IAQrE;;;;;;OAMG;4BAEe,cAAc,YACpB,KAAK,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC;EA2CnB"}
+{"version":3,"file":"dead-lettering-handler.d.ts","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAA2B,MAAM,wBAAwB,CAAA;AACvF,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAGnB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,2BAA2B,CAAA;AAElC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,KAAK,EAAE,wBAAwB,CAAA;IAC/B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB;IASrE;;;;;;OAMG;4BAEe,cAAc,YACpB,KAAK,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC;EAmEnB"}

package/dist/dead-lettering-handler.js

@@ -1,5 +1,8 @@
 import { qualifiedNameToString } from "@kronos-ts/common";
-import { alwaysEnqueuePolicy, createDeadLetter, } from "./dead-letter-queue.js";
+import { defaultSequencingPolicy } from "./sequencing-policy.js";
+import { createDeadLetter, DeadLetterQueueOverflowError, } from "./dead-letter-queue.js";
+import { alwaysEnqueuePolicy } from "./enqueue-policy.js";
+import { noOpDeadLetterListener, } from "./dead-letter-listener.js";
 /**
  * Wraps event delivery with dead-letter support.
  *
@@ -13,7 +16,7 @@ import { alwaysEnqueuePolicy, createDeadLetter, } from "./dead-letter-queue.js";
  * - This preserves ordering within the sequence
  */
 export function createDeadLetteringDelivery(options) {
-    const { queue, policy = alwaysEnqueuePolicy(), sequenceIdentifier = defaultSequenceIdentifier, } = options;
+    const { queue, policy = alwaysEnqueuePolicy(), sequencingPolicy = defaultSequencingPolicy, listener = noOpDeadLetterListener(), } = options;
     return {
         /**
          * Deliver an event to handlers, with dead-letter support.
@@ -24,11 +27,20 @@ export function createDeadLetteringDelivery(options) {
          */
         async deliver(sequencedEvent, handlers) {
             const event = sequencedEvent.event;
-            const seqId = sequenceIdentifier(event);
-            // If this sequence already has dead letters, block this event too
-            const blocked = await queue.enqueueIfPresent(seqId, () => createDeadLetter(event, new Error("Blocked: previous event in sequence failed"), seqId, { blocked: true, position: Number(sequencedEvent.sequence) }));
-            if (blocked)
+            const seqId = sequencingPolicy(event);
+            // If this sequence already has dead letters, block this event too —
+            // preserving per-sequence ordering. A full-queue rejection here
+            // propagates as backpressure (see enqueue path below).
+            let blockedLetter;
+            const blocked = await withOverflowReported(seqId, () => queue.enqueueIfPresent(seqId, () => {
+                blockedLetter = createDeadLetter(event, new Error("Blocked: previous event in sequence failed"), seqId, { blocked: true, position: Number(sequencedEvent.sequence) });
+                return blockedLetter;
+            }));
+            if (blocked) {
+                if (blockedLetter)
+                    listener.onEnqueued(blockedLetter, { blocked: true });
                 return;
+            }
             // Try to deliver to all handlers
             for (const reg of handlers) {
                 try {
@@ -42,26 +54,35 @@ export function createDeadLetteringDelivery(options) {
                     });
                     const decision = policy.decide(letter, error);
                     if (decision.shouldEnqueue) {
-                        await queue.enqueue({
+                        const enqueued = {
                             ...letter,
                             cause: decision.cause ?? letter.cause,
                             diagnostics: decision.diagnostics
                                 ? { ...letter.diagnostics, ...decision.diagnostics }
                                 : letter.diagnostics,
-                        });
+                        };
+                        // A full queue throws DeadLetterQueueOverflowError, which propagates
+                        // to stall and redeliver the batch (Axon backpressure) — surfaced
+                        // via the listener rather than silently looping.
+                        await withOverflowReported(seqId, () => queue.enqueue(enqueued));
+                        listener.onEnqueued(enqueued, { blocked: false });
                     }
-                    // Error is consumed by DLQ — don't propagate
+                    // Error is consumed by DLQ (parked or dropped) — don't propagate.
                     return;
                 }
             }
         },
     };
-}
-function defaultSequenceIdentifier(event) {
-    // Use first tag value if available, otherwise event name
-    if (event.tags && event.tags.length > 0) {
-        return event.tags[0].value;
+    async function withOverflowReported(seqId, op) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            if (err instanceof DeadLetterQueueOverflowError) {
+                listener.onOverflow(seqId, err);
+            }
+            throw err;
+        }
     }
-    return qualifiedNameToString(event.name);
 }
 //# sourceMappingURL=dead-lettering-handler.js.map

package/dist/dead-lettering-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"dead-lettering-handler.js","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAIzD,OAAO,EAGL,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,wBAAwB,CAAA;AAkB/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAA6B;IACvE,MAAM,EACJ,KAAK,EACL,MAAM,GAAG,mBAAmB,EAAE,EAC9B,kBAAkB,GAAG,yBAAyB,GAC/C,GAAG,OAAO,CAAA;IAEX,OAAO;QACL;;;;;;WAMG;QACH,KAAK,CAAC,OAAO,CACX,cAA8B,EAC9B,QAA8C;YAE9C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAA;YAClC,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;YAEvC,kEAAkE;YAClE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAC1C,KAAK,EACL,GAAG,EAAE,CAAC,gBAAgB,CACpB,KAAK,EACL,IAAI,KAAK,CAAC,4CAA4C,CAAC,EACvD,KAAK,EACL,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAC7D,CACF,CAAA;YACD,IAAI,OAAO;gBAAE,OAAM;YAEnB,iCAAiC;YACjC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,CAAC,CAAA;gBACpE,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;oBACjE,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;wBACnD,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC;wBACzC,WAAW,EAAE,qBAAqB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;qBACxD,CAAC,CAAA;oBAEF,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;oBAC7C,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;wBAC3B,MAAM,KAAK,CAAC,OAAO,CAAC;4BAClB,GAAG,MAAM;4BACT,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;4BACrC,WAAW,EAAE,QAAQ,CAAC,WAAW;gCAC/B,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,WAAW,EAAE;gCACpD,CAAC,CAAC,MAAM,CAAC,WAAW;yBACvB,CAAC,CAAA;oBACJ,CAAC;oBACD,6CAA6C;oBAC7C,OAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAmB;IACpD,yDAAyD;IACzD,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,CAAA;IAC7B,CAAC;IACD,OAAO,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AAC1C,CAAC"}
+{"version":3,"file":"dead-lettering-handler.js","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"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"}

package/dist/enqueue-policy.d.ts

@@ -0,0 +1,79 @@
+import type { EnqueueDecision, EnqueuePolicy } from "./dead-letter-queue.js";
+/**
+ * Diagnostics key under which retry policies track how many times a letter has
+ * been processed (initial failure counts as attempt 1).
+ */
+export declare const ATTEMPTS_DIAGNOSTIC = "attempts";
+/**
+ * Factory for the standard {@link EnqueueDecision}s, mirroring Axon's
+ * `Decisions`. The two lifecycle moments share one decision type:
+ *
+ * - On an **initial** handler failure, `shouldEnqueue === true` means "park the
+ *   event" and `false` means "drop it" (the error is swallowed, the token
+ *   advances anyway).
+ * - During **reprocessing**, `shouldEnqueue === true` means "requeue (keep it,
+ *   still failing)" and `false` means "evict (done — succeeded or gave up)".
+ *
+ * Hence the deliberate aliases: `evict` ≡ `doNotEnqueue`, `requeue` ≡ `enqueue`.
+ * They exist purely to read correctly at each call site.
+ */
+export declare const Decisions: {
+    /** Park / keep the letter, recording the given cause and diagnostics. */
+    readonly enqueue: (cause?: Error, diagnostics?: Record<string, unknown>) => EnqueueDecision;
+    /** Alias of {@link enqueue}, read at reprocessing time ("still failing, keep it"). */
+    readonly requeue: (cause?: Error, diagnostics?: Record<string, unknown>) => EnqueueDecision;
+    /** Drop the letter without parking it (initial failure path). */
+    readonly doNotEnqueue: () => EnqueueDecision;
+    /** Alias of {@link doNotEnqueue}, read at reprocessing time ("done — remove it"). */
+    readonly evict: () => EnqueueDecision;
+    /**
+     * Keep the letter in place without recording a new cause — used when a
+     * reprocess attempt should neither evict nor overwrite the existing failure.
+     */
+    readonly ignore: () => EnqueueDecision;
+};
+/**
+ * Default policy: always park a failed event, preserving the original cause.
+ * Matches Axon's default `(letter, cause) -> Decisions.enqueue(cause)`.
+ *
+ * With no retry cap, letters stay until reprocessed successfully or evicted by
+ * an operator — appropriate when every failure deserves manual inspection.
+ */
+export declare function alwaysEnqueuePolicy(): EnqueuePolicy;
+/**
+ * Options for {@link retryThenEvictPolicy}.
+ */
+export interface RetryThenEvictOptions {
+    /**
+     * Total processing attempts (including the first failure) before the letter
+     * is evicted/dropped. `maxAttempts: 1` means "never retry".
+     */
+    maxAttempts: number;
+    /**
+     * Classifies a cause as non-transient. Non-transient failures are parked once
+     * for manual inspection (marked `retryable: false` in diagnostics) and never
+     * counted against the retry budget — retrying a deterministic failure is
+     * pointless. Optional; when omitted, every failure is treated as transient.
+     */
+    nonTransient?: (cause: Error) => boolean;
+}
+/**
+ * Caps automatic retries by counting attempts in the letter's diagnostics,
+ * then evicting once the budget is exhausted. This is the Axon idiom: the
+ * framework holds no retry counter — the policy authors it in diagnostics.
+ *
+ * - Initial failure → park with `attempts: 1` (unless `maxAttempts <= 1`, which
+ *   evicts/drops immediately).
+ * - Each reprocess failure → increment `attempts`; once `attempts >= maxAttempts`
+ *   the letter is evicted (given up on).
+ * - A `nonTransient` cause is parked once, never retried, and flagged for an
+ *   operator.
+ *
+ * ```typescript
+ * trackingProcessor("balances")
+ *   .deadLetterQueue(dlq)
+ *   .enqueuePolicy(retryThenEvictPolicy({ maxAttempts: 5 }))
+ * ```
+ */
+export declare function retryThenEvictPolicy(options: RetryThenEvictOptions): EnqueuePolicy;
+//# sourceMappingURL=enqueue-policy.d.ts.map

package/dist/enqueue-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enqueue-policy.d.ts","sourceRoot":"","sources":["../src/enqueue-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,eAAe,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS;IACpB,yEAAyE;+BACzD,KAAK,gBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,eAAe;IAG9E,sFAAsF;+BACtE,KAAK,gBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,eAAe;IAG9E,iEAAiE;iCACjD,eAAe;IAG/B,qFAAqF;0BAC5E,eAAe;IAGxB;;;OAGG;2BACO,eAAe;CAGjB,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAMnD;AAOD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAclF"}