@kronos-ts/prisma 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { prismaTransactionManager, type PrismaClientLike, type PrismaTransactionClient, } from "./prisma-transaction-manager.js";
 export { prismaTokenStore, } from "./prisma-token-store.js";
+export { prismaDeadLetterQueue, type PrismaDeadLetterQueueConfig, } from "./prisma-dead-letter-queue.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,GACjC,MAAM,+BAA+B,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { prismaTransactionManager, } from "./prisma-transaction-manager.js";
 export { prismaTokenStore, } from "./prisma-token-store.js";
+export { prismaDeadLetterQueue, } from "./prisma-dead-letter-queue.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAGzB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAGzB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,qBAAqB,GAEtB,MAAM,+BAA+B,CAAA"}

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

@@ -0,0 +1,63 @@
+import type { SequencedDeadLetterQueue } from "@kronos-ts/messaging";
+import type { PrismaClientLike } from "./prisma-transaction-manager.js";
+/**
+ * Persistent {@link SequencedDeadLetterQueue} backed by Prisma — a faithful
+ * translation of the Drizzle reference DLQ (`drizzle-dead-letter-queue.ts`)
+ * onto Prisma's delegate API.
+ *
+ * Like {@link prismaTokenStore} it reads the active transaction via
+ * `getActiveTransaction()`, so enqueue/evict/requeue commit in the **same
+ * transaction as the token update** — a crash cannot advance the processor's
+ * token while losing the parked letter.
+ *
+ * The table is shared across processors and partitioned by `processingGroup`.
+ * Per-sequence FIFO order is held by a monotonic `sequenceIndex`; a
+ * `processingStarted` lease column makes `process()` safe across multiple
+ * nodes (Axon parity).
+ *
+ * Expected shape of the `kronos_dead_letters` table in the Prisma schema.
+ *
+ * ```prisma
+ * model KronosDeadLetter {
+ *   deadLetterId       String  @id @map("dead_letter_id")
+ *   processingGroup    String  @map("processing_group")
+ *   sequenceIdentifier String  @map("sequence_identifier")
+ *   sequenceIndex      Int     @map("sequence_index")
+ *   message            String  @map("message")
+ *   causeType          String? @map("cause_type")
+ *   causeMessage       String? @map("cause_message")
+ *   diagnostics        String  @map("diagnostics")
+ *   enqueuedAt         String  @map("enqueued_at")
+ *   lastTouched        String  @map("last_touched")
+ *   processingStarted  String? @map("processing_started")
+ *
+ *   @@index([processingGroup, sequenceIdentifier, sequenceIndex], name: "kronos_dl_seq")
+ *   @@map("kronos_dead_letters")
+ * }
+ * ```
+ */
+export interface PrismaDeadLetterQueueConfig {
+    /** Processing group (the processor name) this queue serves. */
+    processingGroup: string;
+    /** Maximum number of sequences. Default: 1024 (Axon parity). */
+    maxSequences?: number;
+    /** Maximum letters per sequence. Default: 1024 (Axon parity). */
+    maxSequenceSize?: number;
+    /** Lease duration for in-flight processing, ms. Default: 30000 (Axon parity). */
+    claimDurationMs?: number;
+}
+/**
+ * Creates a {@link SequencedDeadLetterQueue} backed by Prisma.
+ *
+ * Uses the `kronosDeadLetter` model from the Prisma schema. Participates in
+ * the active transaction (via `getActiveTransaction()`) so dead-letter writes
+ * and token/projection updates are atomic.
+ *
+ * ```typescript
+ * import { prismaDeadLetterQueue } from "@kronos-ts/prisma"
+ *
+ * const dlq = prismaDeadLetterQueue(prisma, { processingGroup: "my-processor" })
+ * ```
+ */
+export declare function prismaDeadLetterQueue(prisma: PrismaClientLike, config: PrismaDeadLetterQueueConfig): SequencedDeadLetterQueue;
+//# sourceMappingURL=prisma-dead-letter-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prisma-dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/prisma-dead-letter-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAEjG,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,iCAAiC,CAAA;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAA;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AA0BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,2BAA2B,GAClC,wBAAwB,CAgN1B"}

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

@@ -0,0 +1,219 @@
+import { getActiveTransaction, DeadLetterQueueOverflowError } from "@kronos-ts/messaging";
+/** Reserved diagnostics key carrying the persistent row id across read → evict/requeue. */
+const DL_ID = "__dlqId";
+let idCounter = 0;
+function newId(group) {
+    // Unique within the table: time + per-process counter + group.
+    idCounter += 1;
+    return `${group}:${Date.now()}:${idCounter}`;
+}
+/**
+ * Creates a {@link SequencedDeadLetterQueue} backed by Prisma.
+ *
+ * Uses the `kronosDeadLetter` model from the Prisma schema. Participates in
+ * the active transaction (via `getActiveTransaction()`) so dead-letter writes
+ * and token/projection updates are atomic.
+ *
+ * ```typescript
+ * import { prismaDeadLetterQueue } from "@kronos-ts/prisma"
+ *
+ * const dlq = prismaDeadLetterQueue(prisma, { processingGroup: "my-processor" })
+ * ```
+ */
+export function prismaDeadLetterQueue(prisma, config) {
+    const { processingGroup } = config;
+    const maxSequences = config.maxSequences ?? 1024;
+    const maxSequenceSize = config.maxSequenceSize ?? 1024;
+    const claimDurationMs = config.claimDurationMs ?? 30000;
+    function getClient() {
+        return getActiveTransaction() ?? prisma;
+    }
+    function rowToLetter(row) {
+        const cause = new Error(row.causeMessage ?? "");
+        if (row.causeType)
+            cause.name = row.causeType;
+        return {
+            message: JSON.parse(row.message),
+            cause,
+            enqueuedAt: Number(row.enqueuedAt),
+            lastTouched: Number(row.lastTouched),
+            diagnostics: { ...JSON.parse(row.diagnostics), [DL_ID]: row.deadLetterId },
+            sequenceIdentifier: row.sequenceIdentifier,
+        };
+    }
+    function letterToRow(letter, sequenceIndex, deadLetterId) {
+        const { [DL_ID]: _omit, ...diagnostics } = letter.diagnostics;
+        return {
+            deadLetterId,
+            processingGroup,
+            sequenceIdentifier: letter.sequenceIdentifier,
+            sequenceIndex,
+            message: JSON.stringify(letter.message),
+            causeType: letter.cause.name,
+            causeMessage: letter.cause.message,
+            diagnostics: JSON.stringify(diagnostics),
+            enqueuedAt: String(letter.enqueuedAt),
+            lastTouched: String(letter.lastTouched),
+            processingStarted: null,
+        };
+    }
+    async function sequenceRows(client, seqId) {
+        return client.kronosDeadLetter.findMany({
+            where: { processingGroup, sequenceIdentifier: seqId },
+            orderBy: { sequenceIndex: "asc" },
+        });
+    }
+    async function distinctSequences(client) {
+        const rows = await client.kronosDeadLetter.findMany({
+            where: { processingGroup },
+            select: { sequenceIdentifier: true },
+            distinct: ["sequenceIdentifier"],
+        });
+        return rows.map((r) => r.sequenceIdentifier);
+    }
+    return {
+        async enqueue(letter) {
+            const client = getClient();
+            const existing = await sequenceRows(client, letter.sequenceIdentifier);
+            if (existing.length === 0) {
+                if ((await distinctSequences(client)).length >= maxSequences) {
+                    throw new DeadLetterQueueOverflowError(`max sequences ${maxSequences} reached`);
+                }
+            }
+            else if (existing.length >= maxSequenceSize) {
+                throw new DeadLetterQueueOverflowError(`sequence "${letter.sequenceIdentifier}" has reached max size ${maxSequenceSize}`);
+            }
+            const idx = existing.length === 0 ? 0 : existing[existing.length - 1].sequenceIndex + 1;
+            await client.kronosDeadLetter.create({ data: letterToRow(letter, idx, newId(processingGroup)) });
+        },
+        async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+            const client = getClient();
+            const existing = await sequenceRows(client, sequenceIdentifier);
+            if (existing.length === 0)
+                return false;
+            if (existing.length >= maxSequenceSize) {
+                throw new DeadLetterQueueOverflowError(`sequence "${sequenceIdentifier}" has reached max size ${maxSequenceSize}`);
+            }
+            const idx = existing[existing.length - 1].sequenceIndex + 1;
+            await client.kronosDeadLetter.create({
+                data: letterToRow(letterSupplier(), idx, newId(processingGroup)),
+            });
+            return true;
+        },
+        async evict(_sequenceIdentifier, letter) {
+            const client = getClient();
+            const id = letter.diagnostics[DL_ID];
+            if (typeof id !== "string")
+                return;
+            await client.kronosDeadLetter.deleteMany({
+                where: { processingGroup, deadLetterId: id },
+            });
+        },
+        async requeue(letter, update) {
+            const client = getClient();
+            const id = letter.diagnostics[DL_ID];
+            if (typeof id !== "string")
+                return;
+            const { [DL_ID]: _omit, ...baseDiag } = letter.diagnostics;
+            const cause = update?.cause ?? letter.cause;
+            const diagnostics = update?.diagnostics ? { ...baseDiag, ...update.diagnostics } : baseDiag;
+            await client.kronosDeadLetter.updateMany({
+                where: { processingGroup, deadLetterId: id },
+                data: {
+                    causeType: cause.name,
+                    causeMessage: cause.message,
+                    diagnostics: JSON.stringify(diagnostics),
+                    lastTouched: String(Date.now()),
+                },
+            });
+        },
+        async contains(sequenceIdentifier) {
+            const client = getClient();
+            const row = await client.kronosDeadLetter.findFirst({
+                where: { processingGroup, sequenceIdentifier },
+                select: { deadLetterId: true },
+            });
+            return row != null;
+        },
+        async deadLetterSequence(sequenceIdentifier) {
+            const client = getClient();
+            return (await sequenceRows(client, sequenceIdentifier)).map(rowToLetter);
+        },
+        async sequenceIdentifiers() {
+            return distinctSequences(getClient());
+        },
+        async process(sequenceFilter, processingTask) {
+            const client = getClient();
+            const candidates = (await distinctSequences(client)).filter(sequenceFilter);
+            if (candidates.length === 0)
+                return false;
+            // Pick the oldest sequence by its head letter's lastTouched, skipping
+            // sequences under an unexpired processing lease (multi-node safety).
+            const cutoff = Date.now() - claimDurationMs;
+            let chosen;
+            let oldest = Infinity;
+            for (const seqId of candidates) {
+                const rows = await sequenceRows(client, seqId);
+                if (rows.length === 0)
+                    continue;
+                const head = rows[0];
+                const leased = head.processingStarted != null && Number(head.processingStarted) > cutoff;
+                if (leased)
+                    continue;
+                if (Number(head.lastTouched) < oldest) {
+                    oldest = Number(head.lastTouched);
+                    chosen = seqId;
+                }
+            }
+            if (!chosen)
+                return false;
+            // Claim the sequence head's lease for the duration of this pass.
+            const headRows = await sequenceRows(client, chosen);
+            await client.kronosDeadLetter.updateMany({
+                where: { processingGroup, deadLetterId: headRows[0].deadLetterId },
+                data: { processingStarted: String(Date.now()) },
+            });
+            try {
+                for (const row of headRows) {
+                    const letter = rowToLetter(row);
+                    const decision = await processingTask(letter);
+                    if (decision.shouldEnqueue) {
+                        await this.requeue(letter, { cause: decision.cause, diagnostics: decision.diagnostics });
+                        return true;
+                    }
+                    await this.evict(chosen, letter);
+                }
+                return true;
+            }
+            finally {
+                // Release any lease still set on a surviving head.
+                const remaining = await sequenceRows(client, chosen);
+                if (remaining.length > 0 && remaining[0].processingStarted != null) {
+                    await client.kronosDeadLetter.updateMany({
+                        where: { processingGroup, deadLetterId: remaining[0].deadLetterId },
+                        data: { processingStarted: null },
+                    });
+                }
+            }
+        },
+        async size() {
+            const client = getClient();
+            return client.kronosDeadLetter.count({ where: { processingGroup } });
+        },
+        async amountOfSequences() {
+            return (await distinctSequences(getClient())).length;
+        },
+        async clear() {
+            const client = getClient();
+            await client.kronosDeadLetter.deleteMany({ where: { processingGroup } });
+        },
+        async isFull(sequenceIdentifier) {
+            const client = getClient();
+            const rows = await sequenceRows(client, sequenceIdentifier);
+            if (rows.length > 0)
+                return rows.length >= maxSequenceSize;
+            return (await distinctSequences(client)).length >= maxSequences;
+        },
+    };
+}
+//# sourceMappingURL=prisma-dead-letter-queue.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/prisma",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Prisma extension for Kronos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,8 +49,8 @@
     }
   },
   "dependencies": {
-    "@kronos-ts/common": "0.1.0",
-    "@kronos-ts/messaging": "0.1.0"
+    "@kronos-ts/common": "0.1.1",
+    "@kronos-ts/messaging": "0.4.0"
   },
   "peerDependencies": {
     "@prisma/client": ">=5.0.0"

package/src/index.ts

@@ -7,3 +7,8 @@ export {
 export {
   prismaTokenStore,
 } from "./prisma-token-store.js"
+
+export {
+  prismaDeadLetterQueue,
+  type PrismaDeadLetterQueueConfig,
+} from "./prisma-dead-letter-queue.js"

package/src/prisma-dead-letter-queue.ts

@@ -0,0 +1,300 @@
+import type { DeadLetter, EnqueueDecision, SequencedDeadLetterQueue } from "@kronos-ts/messaging"
+import { getActiveTransaction, DeadLetterQueueOverflowError } from "@kronos-ts/messaging"
+import type { PrismaClientLike, PrismaTransactionClient } from "./prisma-transaction-manager.js"
+
+/**
+ * Persistent {@link SequencedDeadLetterQueue} backed by Prisma — a faithful
+ * translation of the Drizzle reference DLQ (`drizzle-dead-letter-queue.ts`)
+ * onto Prisma's delegate API.
+ *
+ * Like {@link prismaTokenStore} it reads the active transaction via
+ * `getActiveTransaction()`, so enqueue/evict/requeue commit in the **same
+ * transaction as the token update** — a crash cannot advance the processor's
+ * token while losing the parked letter.
+ *
+ * The table is shared across processors and partitioned by `processingGroup`.
+ * Per-sequence FIFO order is held by a monotonic `sequenceIndex`; a
+ * `processingStarted` lease column makes `process()` safe across multiple
+ * nodes (Axon parity).
+ *
+ * Expected shape of the `kronos_dead_letters` table in the Prisma schema.
+ *
+ * ```prisma
+ * model KronosDeadLetter {
+ *   deadLetterId       String  @id @map("dead_letter_id")
+ *   processingGroup    String  @map("processing_group")
+ *   sequenceIdentifier String  @map("sequence_identifier")
+ *   sequenceIndex      Int     @map("sequence_index")
+ *   message            String  @map("message")
+ *   causeType          String? @map("cause_type")
+ *   causeMessage       String? @map("cause_message")
+ *   diagnostics        String  @map("diagnostics")
+ *   enqueuedAt         String  @map("enqueued_at")
+ *   lastTouched        String  @map("last_touched")
+ *   processingStarted  String? @map("processing_started")
+ *
+ *   @@index([processingGroup, sequenceIdentifier, sequenceIndex], name: "kronos_dl_seq")
+ *   @@map("kronos_dead_letters")
+ * }
+ * ```
+ */
+export interface PrismaDeadLetterQueueConfig {
+  /** Processing group (the processor name) this queue serves. */
+  processingGroup: string
+  /** Maximum number of sequences. Default: 1024 (Axon parity). */
+  maxSequences?: number
+  /** Maximum letters per sequence. Default: 1024 (Axon parity). */
+  maxSequenceSize?: number
+  /** Lease duration for in-flight processing, ms. Default: 30000 (Axon parity). */
+  claimDurationMs?: number
+}
+
+/** Reserved diagnostics key carrying the persistent row id across read → evict/requeue. */
+const DL_ID = "__dlqId"
+
+let idCounter = 0
+function newId(group: string): string {
+  // Unique within the table: time + per-process counter + group.
+  idCounter += 1
+  return `${group}:${Date.now()}:${idCounter}`
+}
+
+interface DeadLetterRow {
+  deadLetterId: string
+  processingGroup: string
+  sequenceIdentifier: string
+  sequenceIndex: number
+  message: string
+  causeType: string | null
+  causeMessage: string | null
+  diagnostics: string
+  enqueuedAt: string
+  lastTouched: string
+  processingStarted: string | null
+}
+
+/**
+ * Creates a {@link SequencedDeadLetterQueue} backed by Prisma.
+ *
+ * Uses the `kronosDeadLetter` model from the Prisma schema. Participates in
+ * the active transaction (via `getActiveTransaction()`) so dead-letter writes
+ * and token/projection updates are atomic.
+ *
+ * ```typescript
+ * import { prismaDeadLetterQueue } from "@kronos-ts/prisma"
+ *
+ * const dlq = prismaDeadLetterQueue(prisma, { processingGroup: "my-processor" })
+ * ```
+ */
+export function prismaDeadLetterQueue(
+  prisma: PrismaClientLike,
+  config: PrismaDeadLetterQueueConfig,
+): SequencedDeadLetterQueue {
+  const { processingGroup } = config
+  const maxSequences = config.maxSequences ?? 1024
+  const maxSequenceSize = config.maxSequenceSize ?? 1024
+  const claimDurationMs = config.claimDurationMs ?? 30000
+
+  function getClient(): any {
+    return getActiveTransaction<PrismaTransactionClient>() ?? prisma
+  }
+
+  function rowToLetter(row: DeadLetterRow): DeadLetter {
+    const cause = new Error(row.causeMessage ?? "")
+    if (row.causeType) cause.name = row.causeType
+    return {
+      message: JSON.parse(row.message),
+      cause,
+      enqueuedAt: Number(row.enqueuedAt),
+      lastTouched: Number(row.lastTouched),
+      diagnostics: { ...JSON.parse(row.diagnostics), [DL_ID]: row.deadLetterId },
+      sequenceIdentifier: row.sequenceIdentifier,
+    }
+  }
+
+  function letterToRow(letter: DeadLetter, sequenceIndex: number, deadLetterId: string): DeadLetterRow {
+    const { [DL_ID]: _omit, ...diagnostics } = letter.diagnostics as Record<string, unknown>
+    return {
+      deadLetterId,
+      processingGroup,
+      sequenceIdentifier: letter.sequenceIdentifier,
+      sequenceIndex,
+      message: JSON.stringify(letter.message),
+      causeType: letter.cause.name,
+      causeMessage: letter.cause.message,
+      diagnostics: JSON.stringify(diagnostics),
+      enqueuedAt: String(letter.enqueuedAt),
+      lastTouched: String(letter.lastTouched),
+      processingStarted: null,
+    }
+  }
+
+  async function sequenceRows(client: any, seqId: string): Promise<DeadLetterRow[]> {
+    return client.kronosDeadLetter.findMany({
+      where: { processingGroup, sequenceIdentifier: seqId },
+      orderBy: { sequenceIndex: "asc" },
+    })
+  }
+
+  async function distinctSequences(client: any): Promise<string[]> {
+    const rows = await client.kronosDeadLetter.findMany({
+      where: { processingGroup },
+      select: { sequenceIdentifier: true },
+      distinct: ["sequenceIdentifier"],
+    })
+    return rows.map((r: { sequenceIdentifier: string }) => r.sequenceIdentifier)
+  }
+
+  return {
+    async enqueue(letter) {
+      const client = getClient()
+      const existing = await sequenceRows(client, letter.sequenceIdentifier)
+      if (existing.length === 0) {
+        if ((await distinctSequences(client)).length >= maxSequences) {
+          throw new DeadLetterQueueOverflowError(`max sequences ${maxSequences} reached`)
+        }
+      } else if (existing.length >= maxSequenceSize) {
+        throw new DeadLetterQueueOverflowError(
+          `sequence "${letter.sequenceIdentifier}" has reached max size ${maxSequenceSize}`,
+        )
+      }
+      const idx = existing.length === 0 ? 0 : existing[existing.length - 1].sequenceIndex + 1
+      await client.kronosDeadLetter.create({ data: letterToRow(letter, idx, newId(processingGroup)) })
+    },
+
+    async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+      const client = getClient()
+      const existing = await sequenceRows(client, sequenceIdentifier)
+      if (existing.length === 0) return false
+      if (existing.length >= maxSequenceSize) {
+        throw new DeadLetterQueueOverflowError(
+          `sequence "${sequenceIdentifier}" has reached max size ${maxSequenceSize}`,
+        )
+      }
+      const idx = existing[existing.length - 1].sequenceIndex + 1
+      await client.kronosDeadLetter.create({
+        data: letterToRow(letterSupplier(), idx, newId(processingGroup)),
+      })
+      return true
+    },
+
+    async evict(_sequenceIdentifier, letter) {
+      const client = getClient()
+      const id = (letter.diagnostics as Record<string, unknown>)[DL_ID]
+      if (typeof id !== "string") return
+      await client.kronosDeadLetter.deleteMany({
+        where: { processingGroup, deadLetterId: id },
+      })
+    },
+
+    async requeue(letter, update) {
+      const client = getClient()
+      const id = (letter.diagnostics as Record<string, unknown>)[DL_ID]
+      if (typeof id !== "string") return
+      const { [DL_ID]: _omit, ...baseDiag } = letter.diagnostics as Record<string, unknown>
+      const cause = update?.cause ?? letter.cause
+      const diagnostics = update?.diagnostics ? { ...baseDiag, ...update.diagnostics } : baseDiag
+      await client.kronosDeadLetter.updateMany({
+        where: { processingGroup, deadLetterId: id },
+        data: {
+          causeType: cause.name,
+          causeMessage: cause.message,
+          diagnostics: JSON.stringify(diagnostics),
+          lastTouched: String(Date.now()),
+        },
+      })
+    },
+
+    async contains(sequenceIdentifier) {
+      const client = getClient()
+      const row = await client.kronosDeadLetter.findFirst({
+        where: { processingGroup, sequenceIdentifier },
+        select: { deadLetterId: true },
+      })
+      return row != null
+    },
+
+    async deadLetterSequence(sequenceIdentifier) {
+      const client = getClient()
+      return (await sequenceRows(client, sequenceIdentifier)).map(rowToLetter)
+    },
+
+    async sequenceIdentifiers() {
+      return distinctSequences(getClient())
+    },
+
+    async process(sequenceFilter, processingTask) {
+      const client = getClient()
+      const candidates = (await distinctSequences(client)).filter(sequenceFilter)
+      if (candidates.length === 0) return false
+
+      // Pick the oldest sequence by its head letter's lastTouched, skipping
+      // sequences under an unexpired processing lease (multi-node safety).
+      const cutoff = Date.now() - claimDurationMs
+      let chosen: string | undefined
+      let oldest = Infinity
+      for (const seqId of candidates) {
+        const rows = await sequenceRows(client, seqId)
+        if (rows.length === 0) continue
+        const head = rows[0]
+        const leased = head.processingStarted != null && Number(head.processingStarted) > cutoff
+        if (leased) continue
+        if (Number(head.lastTouched) < oldest) {
+          oldest = Number(head.lastTouched)
+          chosen = seqId
+        }
+      }
+      if (!chosen) return false
+
+      // Claim the sequence head's lease for the duration of this pass.
+      const headRows = await sequenceRows(client, chosen)
+      await client.kronosDeadLetter.updateMany({
+        where: { processingGroup, deadLetterId: headRows[0].deadLetterId },
+        data: { processingStarted: String(Date.now()) },
+      })
+
+      try {
+        for (const row of headRows) {
+          const letter = rowToLetter(row)
+          const decision: EnqueueDecision = await processingTask(letter)
+          if (decision.shouldEnqueue) {
+            await this.requeue(letter, { cause: decision.cause, diagnostics: decision.diagnostics })
+            return true
+          }
+          await this.evict(chosen, letter)
+        }
+        return true
+      } finally {
+        // Release any lease still set on a surviving head.
+        const remaining = await sequenceRows(client, chosen)
+        if (remaining.length > 0 && remaining[0].processingStarted != null) {
+          await client.kronosDeadLetter.updateMany({
+            where: { processingGroup, deadLetterId: remaining[0].deadLetterId },
+            data: { processingStarted: null },
+          })
+        }
+      }
+    },
+
+    async size() {
+      const client = getClient()
+      return client.kronosDeadLetter.count({ where: { processingGroup } })
+    },
+
+    async amountOfSequences() {
+      return (await distinctSequences(getClient())).length
+    },
+
+    async clear() {
+      const client = getClient()
+      await client.kronosDeadLetter.deleteMany({ where: { processingGroup } })
+    },
+
+    async isFull(sequenceIdentifier) {
+      const client = getClient()
+      const rows = await sequenceRows(client, sequenceIdentifier)
+      if (rows.length > 0) return rows.length >= maxSequenceSize
+      return (await distinctSequences(client)).length >= maxSequences
+    },
+  }
+}