@kronos-ts/messaging 0.3.0 → 0.4.0

package/src/dead-letter-queue.ts

@@ -43,17 +43,6 @@ export interface EnqueuePolicy {
   decide(letter: DeadLetter, cause: Error): EnqueueDecision
 }
 
-/**
- * Default policy: always enqueue with the original cause.
- */
-export function alwaysEnqueuePolicy(): EnqueuePolicy {
-  return {
-    decide() {
-      return { shouldEnqueue: true }
-    },
-  }
-}
-
 /**
  * A sequenced dead letter queue that maintains ordering within sequences.
  *
@@ -125,10 +114,10 @@ export interface SequencedDeadLetterQueue {
   ): 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>
@@ -136,8 +125,10 @@ export interface SequencedDeadLetterQueue {
   /**
    * 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>
 }
 
 /**
@@ -272,7 +263,7 @@ export function createInMemoryDeadLetterQueue(options?: {
       }
     },
 
-    size() {
+    async size() {
       let total = 0
       for (const letters of sequences.values()) {
         total += letters.length
@@ -280,7 +271,7 @@ export function createInMemoryDeadLetterQueue(options?: {
       return total
     },
 
-    amountOfSequences() {
+    async amountOfSequences() {
       return sequences.size
     },
 
@@ -289,7 +280,7 @@ export function createInMemoryDeadLetterQueue(options?: {
       processing.clear()
     },
 
-    isFull(sequenceIdentifier) {
+    async isFull(sequenceIdentifier) {
       const seq = sequences.get(sequenceIdentifier)
       if (seq) {
         return seq.length >= maxSequenceSize

package/src/dead-letter-reprocessor.ts

@@ -0,0 +1,95 @@
+import { emptyMetadata } from "@kronos-ts/common"
+import type { DeadLetter, SequencedDeadLetterQueue, EnqueuePolicy } from "./dead-letter-queue.js"
+import { Decisions, alwaysEnqueuePolicy } from "./enqueue-policy.js"
+import { type DeadLetterListener, noOpDeadLetterListener } from "./dead-letter-listener.js"
+import type { UoWRunner } from "./unit-of-work.js"
+import { runInNewUoW } 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 function createDeadLetterReprocessor(
+  options: DeadLetterReprocessorOptions,
+): DeadLetterReprocessor {
+  const {
+    queue,
+    replay,
+    policy = alwaysEnqueuePolicy(),
+    unitOfWorkRunner = runInNewUoW,
+    listener = noOpDeadLetterListener(),
+  } = options
+
+  async function reprocess(filter: (sequenceId: string) => boolean = () => true): Promise<boolean> {
+    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: (sequenceId: string) => boolean = () => true): Promise<number> {
+    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 }
+}

package/src/dead-lettering-handler.ts

@@ -1,13 +1,18 @@
 import { qualifiedNameToString } from "@kronos-ts/common"
-import type { EventMessage } from "./message.js"
 import type { EventHandlerRegistration } from "./handler.js"
 import type { SequencedEvent } from "./event-source.js"
+import { type SequencingPolicy, defaultSequencingPolicy } from "./sequencing-policy.js"
 import {
   type SequencedDeadLetterQueue,
   type EnqueuePolicy,
-  alwaysEnqueuePolicy,
   createDeadLetter,
+  DeadLetterQueueOverflowError,
 } from "./dead-letter-queue.js"
+import { alwaysEnqueuePolicy } from "./enqueue-policy.js"
+import {
+  type DeadLetterListener,
+  noOpDeadLetterListener,
+} from "./dead-letter-listener.js"
 
 /**
  * Options for dead-lettering event handler wrapper.
@@ -18,11 +23,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
 }
 
 /**
@@ -41,7 +48,8 @@ export function createDeadLetteringDelivery(options: DeadLetteringOptions) {
   const {
     queue,
     policy = alwaysEnqueuePolicy(),
-    sequenceIdentifier = defaultSequenceIdentifier,
+    sequencingPolicy = defaultSequencingPolicy,
+    listener = noOpDeadLetterListener(),
   } = options
 
   return {
@@ -57,19 +65,27 @@ export function createDeadLetteringDelivery(options: DeadLetteringOptions) {
       handlers: Array<EventHandlerRegistration<any>>,
     ): Promise<void> {
       const event = sequencedEvent.event
-      const seqId = sequenceIdentifier(event)
+      const seqId = sequencingPolicy(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 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: ReturnType<typeof createDeadLetter> | undefined
+      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) return
+      if (blocked) {
+        if (blockedLetter) listener.onEnqueued(blockedLetter, { blocked: true })
+        return
+      }
 
       // Try to deliver to all handlers
       for (const reg of handlers) {
@@ -84,26 +100,34 @@ export function createDeadLetteringDelivery(options: DeadLetteringOptions) {
 
           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: EventMessage): string {
-  // Use first tag value if available, otherwise event name
-  if (event.tags && event.tags.length > 0) {
-    return event.tags[0]!.value
+  async function withOverflowReported<T>(seqId: string, op: () => Promise<T>): Promise<T> {
+    try {
+      return await op()
+    } catch (err) {
+      if (err instanceof DeadLetterQueueOverflowError) {
+        listener.onOverflow(seqId, err)
+      }
+      throw err
+    }
   }
-  return qualifiedNameToString(event.name)
 }

package/src/enqueue-policy.ts

@@ -0,0 +1,118 @@
+import type { DeadLetter, 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 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 const Decisions = {
+  /** Park / keep the letter, recording the given cause and diagnostics. */
+  enqueue(cause?: Error, diagnostics?: Record<string, unknown>): EnqueueDecision {
+    return { shouldEnqueue: true, cause, diagnostics }
+  },
+  /** Alias of {@link enqueue}, read at reprocessing time ("still failing, keep it"). */
+  requeue(cause?: Error, diagnostics?: Record<string, unknown>): EnqueueDecision {
+    return { shouldEnqueue: true, cause, diagnostics }
+  },
+  /** Drop the letter without parking it (initial failure path). */
+  doNotEnqueue(): EnqueueDecision {
+    return { shouldEnqueue: false }
+  },
+  /** Alias of {@link doNotEnqueue}, read at reprocessing time ("done — remove it"). */
+  evict(): EnqueueDecision {
+    return { shouldEnqueue: false }
+  },
+  /**
+   * Keep the letter in place without recording a new cause — used when a
+   * reprocess attempt should neither evict nor overwrite the existing failure.
+   */
+  ignore(): EnqueueDecision {
+    return { shouldEnqueue: true }
+  },
+} as const
+
+/**
+ * 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 function alwaysEnqueuePolicy(): EnqueuePolicy {
+  return {
+    decide(_letter, cause) {
+      return Decisions.enqueue(cause)
+    },
+  }
+}
+
+function attemptsOf(letter: DeadLetter): number {
+  const raw = letter.diagnostics[ATTEMPTS_DIAGNOSTIC]
+  return typeof raw === "number" ? raw : 0
+}
+
+/**
+ * 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 function retryThenEvictPolicy(options: RetryThenEvictOptions): EnqueuePolicy {
+  const { maxAttempts, nonTransient } = options
+  return {
+    decide(letter, cause) {
+      if (nonTransient?.(cause)) {
+        return Decisions.enqueue(cause, { retryable: false })
+      }
+      const attempts = attemptsOf(letter) + 1
+      if (attempts >= maxAttempts) {
+        return Decisions.evict()
+      }
+      return Decisions.enqueue(cause, { [ATTEMPTS_DIAGNOSTIC]: attempts })
+    },
+  }
+}

package/src/event-processor-builder.ts

@@ -2,7 +2,9 @@ import type { EventHandlerDefinition } from "./event-handler.js"
 import type { TokenStore } from "./token-store.js"
 import type { UoWRunner } from "./unit-of-work.js"
 import type { EventProcessingErrorHandler } from "./tracking-event-processor.js"
-import type { SequencedDeadLetterQueue } from "./dead-letter-queue.js"
+import type { SequencedDeadLetterQueue, EnqueuePolicy } from "./dead-letter-queue.js"
+import type { SequencingPolicy } from "./sequencing-policy.js"
+import type { DeadLetterListener } from "./dead-letter-listener.js"
 
 /**
  * Base configuration shared by all event processor types.
@@ -27,6 +29,16 @@ export interface TrackingProcessorModule extends EventProcessorBase {
   readonly unitOfWorkRunner?: UoWRunner
   readonly errorHandler?: EventProcessingErrorHandler
   readonly deadLetterQueue?: SequencedDeadLetterQueue
+  /** Decides whether a failed event is enqueued in the DLQ. Default: always enqueue. */
+  readonly enqueuePolicy?: EnqueuePolicy
+  /** Decides each event's ordered sequence for the DLQ. Default: first tag value. */
+  readonly sequencingPolicy?: SequencingPolicy
+  /** Observability hook for dead-letter lifecycle events. Default: no-op. */
+  readonly deadLetterListener?: DeadLetterListener
+  /** When true, resetTokens() also clears this processor's DLQ. Default: false. */
+  readonly resetClearsDeadLetters?: boolean
+  /** When set, automatically drains the DLQ on this interval (ms). Off by default. */
+  readonly dlqRetryIntervalMs?: number
   /** Number of segments created on first startup. Default 16 (Axon Framework parity). Always set by builder.build(). */
   readonly initialSegmentCount: number
   readonly claimExtensionThresholdMs?: number
@@ -89,6 +101,11 @@ export class TrackingProcessorBuilder {
   private _unitOfWorkRunner?: UoWRunner
   private _errorHandler?: EventProcessingErrorHandler
   private _deadLetterQueue?: SequencedDeadLetterQueue
+  private _enqueuePolicy?: EnqueuePolicy
+  private _sequencingPolicy?: SequencingPolicy
+  private _deadLetterListener?: DeadLetterListener
+  private _resetClearsDeadLetters?: boolean
+  private _dlqRetryIntervalMs?: number
   private _initialSegmentCount?: number
   private _claimExtensionThresholdMs?: number
   private _tokenClaimIntervalMs?: number
@@ -109,7 +126,15 @@ export class TrackingProcessorBuilder {
     return this
   }
 
-  /** Events per batch/transaction. Default: 100. */
+  /**
+   * Events per batch/transaction (one UnitOfWork). Default: 1 (Axon parity).
+   *
+   * A batch shares one UnitOfWork, so all events in it share the per-UoW
+   * `load()` cache, DCB read-set, and a single atomic commit. Keep the default
+   * of 1 for processors that make per-entity decisions via `load()`
+   * (automations) so each decision stays isolated. Raise it for read-model
+   * projections that only apply idempotent view updates and want throughput.
+   */
   batchSize(size: number): this {
     this._batchSize = size
     return this
@@ -143,12 +168,46 @@ export class TrackingProcessorBuilder {
     return this
   }
 
-  /** Set a dead letter queue for this processor. */
+  /**
+   * Set a dead letter queue for this processor. When set, handler failures are
+   * parked in the queue and the processor advances past them (Option A) rather
+   * than redelivering the failed batch indefinitely.
+   */
   deadLetterQueue(queue: SequencedDeadLetterQueue): this {
     this._deadLetterQueue = queue
     return this
   }
 
+  /** Policy deciding whether a failed event is enqueued in the DLQ. Default: always. */
+  enqueuePolicy(policy: EnqueuePolicy): this {
+    this._enqueuePolicy = policy
+    return this
+  }
+
+  /** Policy deciding each event's ordered sequence for the DLQ. Default: first tag value. */
+  sequencingPolicy(policy: SequencingPolicy): this {
+    this._sequencingPolicy = policy
+    return this
+  }
+
+  /** Observability hook for dead-letter lifecycle events. */
+  deadLetterListener(listener: DeadLetterListener): this {
+    this._deadLetterListener = listener
+    return this
+  }
+
+  /** When true, resetTokens() also clears this processor's DLQ (Axon allowReset). */
+  resetClearsDeadLetters(enabled = true): this {
+    this._resetClearsDeadLetters = enabled
+    return this
+  }
+
+  /** Automatically drain the DLQ on this interval (ms). Omit to disable scheduled retries. */
+  dlqRetryInterval(ms: number): this {
+    this._dlqRetryIntervalMs = ms
+    return this
+  }
+
   /** Number of segments to create on first startup. Default: 16 (Axon Framework parity). */
   initialSegmentCount(count: number): this {
     this._initialSegmentCount = count
@@ -167,6 +226,11 @@ export class TrackingProcessorBuilder {
       unitOfWorkRunner: this._unitOfWorkRunner,
       errorHandler: this._errorHandler,
       deadLetterQueue: this._deadLetterQueue,
+      enqueuePolicy: this._enqueuePolicy,
+      sequencingPolicy: this._sequencingPolicy,
+      deadLetterListener: this._deadLetterListener,
+      resetClearsDeadLetters: this._resetClearsDeadLetters,
+      dlqRetryIntervalMs: this._dlqRetryIntervalMs,
       initialSegmentCount: this._initialSegmentCount ?? 16,
       claimExtensionThresholdMs: this._claimExtensionThresholdMs,
       tokenClaimIntervalMs: this._tokenClaimIntervalMs,

package/src/index.ts

@@ -304,18 +304,50 @@ export {
   type EnqueueDecision,
   type EnqueuePolicy,
   type SequencedDeadLetterQueue,
-  alwaysEnqueuePolicy,
   createDeadLetter,
   createInMemoryDeadLetterQueue,
   DeadLetterQueueOverflowError,
 } from "./dead-letter-queue.js"
 
+// Enqueue policies + decisions
+export {
+  Decisions,
+  alwaysEnqueuePolicy,
+  retryThenEvictPolicy,
+  type RetryThenEvictOptions,
+  ATTEMPTS_DIAGNOSTIC,
+} from "./enqueue-policy.js"
+
 // Dead-lettering event delivery
 export {
   type DeadLetteringOptions,
   createDeadLetteringDelivery,
 } from "./dead-lettering-handler.js"
 
+// Dead-letter reprocessing
+export {
+  type DeadLetterReprocessor,
+  type DeadLetterReprocessorOptions,
+  type DeadLetterReplay,
+  createDeadLetterReprocessor,
+} from "./dead-letter-reprocessor.js"
+
+// Dead-letter observability
+export {
+  type DeadLetterListener,
+  noOpDeadLetterListener,
+  loggingDeadLetterListener,
+  multiDeadLetterListener,
+} from "./dead-letter-listener.js"
+
+// Sequencing policy
+export {
+  type SequencingPolicy,
+  sequentialPerTag,
+  defaultSequencingPolicy,
+  fullConcurrencyPolicy,
+} from "./sequencing-policy.js"
+
 // Upcasting
 export {
   type IntermediateEventRepresentation,

package/src/processor-configuration.ts

@@ -30,7 +30,7 @@ import type { SequencedDeadLetterQueue } from "./dead-letter-queue.js"
  * with `registerEventProcessor()` instead.
  */
 export interface ProcessorConfiguration {
-  /** Events per transaction. Default: 100 */
+  /** Events per transaction (one UnitOfWork). Default: 1 (Axon parity). */
   batchSize?: number
 
   /** Number of segments to create on first startup. Default: 1 */

package/src/sequencing-policy.ts

@@ -0,0 +1,55 @@
+import { qualifiedNameToString } from "@kronos-ts/common"
+import type { EventMessage } from "./message.js"
+
+/**
+ * Decides which ordered sequence an event belongs to.
+ *
+ * Events sharing a sequence identifier are processed in order; if one is
+ * dead-lettered, subsequent events in the same sequence are parked behind it
+ * (see {@link createDeadLetteringDelivery}). This is the minimal analog of
+ * Axon's `SequencingPolicy` — a plain function rather than a class hierarchy,
+ * because Kronos does not (yet) do segmented parallel processing where the
+ * policy would also drive segment assignment. When/if it does, this same type
+ * is the seam to extend.
+ */
+export type SequencingPolicy = (event: EventMessage) => string
+
+/**
+ * Sequences events by the value of a named tag, falling back to the event name
+ * when the tag is absent. The DCB/tag-world analog of Axon's
+ * `SequentialPerAggregatePolicy` (aggregate id → sequence).
+ *
+ * Prefer this — naming the tag explicitly — over relying on tag *order*.
+ *
+ * ```typescript
+ * trackingProcessor("balances")
+ *   .deadLetterQueue(dlq)
+ *   .sequencingPolicy(sequentialPerTag("accountId"))
+ * ```
+ */
+export function sequentialPerTag(tagKey: string): SequencingPolicy {
+  return (event) => {
+    const match = event.tags.find((t) => t.key === tagKey)
+    return match ? match.value : qualifiedNameToString(event.name)
+  }
+}
+
+/**
+ * Default policy: sequence by the first tag value, else the event name.
+ *
+ * Order-dependent on the tag list, so it is a reasonable default but a poor
+ * deliberate choice — prefer {@link sequentialPerTag} with an explicit key.
+ */
+export const defaultSequencingPolicy: SequencingPolicy = (event) => {
+  if (event.tags.length > 0) {
+    return event.tags[0]!.value
+  }
+  return qualifiedNameToString(event.name)
+}
+
+/**
+ * Full concurrency: every event is its own singleton sequence (keyed by the
+ * unique message identifier), so no two events ever block each other. Use when
+ * handlers carry no cross-event ordering requirement.
+ */
+export const fullConcurrencyPolicy: SequencingPolicy = (event) => event.identifier