@kronos-ts/kysely 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { kyselyTransactionManager, type KyselyDatabaseLike, type KyselyTransaction, } from "./kysely-transaction-manager.js";
 export { kyselyTokenStore, type KyselyDbLike, } from "./kysely-token-store.js";
+export { kyselyDeadLetterQueue, type KyselyDeadLetterQueueConfig, } from "./kysely-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,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,GACjC,MAAM,+BAA+B,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { kyselyTransactionManager, } from "./kysely-transaction-manager.js";
 export { kyselyTokenStore, } from "./kysely-token-store.js";
+export { kyselyDeadLetterQueue, } from "./kysely-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,GAEjB,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,GAEjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,qBAAqB,GAEtB,MAAM,+BAA+B,CAAA"}

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

@@ -0,0 +1,53 @@
+import type { SequencedDeadLetterQueue } from "@kronos-ts/messaging";
+import type { KyselyDbLike } from "./kysely-token-store.js";
+/**
+ * Dead letter table interface for Kysely. Users must define this table in
+ * their Kysely database interface:
+ *
+ * ```typescript
+ * interface Database {
+ *   kronos_dead_letters: {
+ *     dead_letter_id: string
+ *     processing_group: string
+ *     sequence_identifier: string
+ *     sequence_index: number
+ *     message: string
+ *     cause_type: string | null
+ *     cause_message: string | null
+ *     diagnostics: string
+ *     enqueued_at: string
+ *     last_touched: string
+ *     processing_started: string | null
+ *   }
+ * }
+ * ```
+ *
+ * Persistent {@link SequencedDeadLetterQueue} backed by Kysely — mirrors the
+ * Drizzle reference implementation in query semantics.
+ *
+ * Like {@link kyselyTokenStore} 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 `sequence_index`; a
+ * `processing_started` lease column makes `process()` safe across multiple
+ * nodes (Axon parity).
+ */
+export interface KyselyDeadLetterQueueConfig {
+    /** The Kysely database instance (or transaction). */
+    db: KyselyDbLike;
+    /** Processing group (the processor name) this queue serves. */
+    processingGroup: string;
+    /** Table name. Default: `kronos_dead_letters`. */
+    tableName?: 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;
+}
+export declare function kyselyDeadLetterQueue(config: KyselyDeadLetterQueueConfig): SequencedDeadLetterQueue;
+//# sourceMappingURL=kysely-dead-letter-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/kysely-dead-letter-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAGjG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,2BAA2B;IAC1C,qDAAqD;IACrD,EAAE,EAAE,YAAY,CAAA;IAChB,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAA;IACvB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,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,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,2BAA2B,GAAG,wBAAwB,CA6NnG"}

package/dist/kysely-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}`;
+}
+export function kyselyDeadLetterQueue(config) {
+    const { processingGroup } = config;
+    const table = config.tableName ?? "kronos_dead_letters";
+    const maxSequences = config.maxSequences ?? 1024;
+    const maxSequenceSize = config.maxSequenceSize ?? 1024;
+    const claimDurationMs = config.claimDurationMs ?? 30000;
+    function getDb() {
+        return getActiveTransaction() ?? config.db;
+    }
+    function rowToLetter(row) {
+        const cause = new Error(row.cause_message ?? "");
+        if (row.cause_type)
+            cause.name = row.cause_type;
+        return {
+            message: JSON.parse(row.message),
+            cause,
+            enqueuedAt: Number(row.enqueued_at),
+            lastTouched: Number(row.last_touched),
+            diagnostics: { ...JSON.parse(row.diagnostics), [DL_ID]: row.dead_letter_id },
+            sequenceIdentifier: row.sequence_identifier,
+        };
+    }
+    function letterToRow(letter, sequenceIndex, deadLetterId) {
+        const { [DL_ID]: _omit, ...diagnostics } = letter.diagnostics;
+        return {
+            dead_letter_id: deadLetterId,
+            processing_group: processingGroup,
+            sequence_identifier: letter.sequenceIdentifier,
+            sequence_index: sequenceIndex,
+            message: JSON.stringify(letter.message),
+            cause_type: letter.cause.name,
+            cause_message: letter.cause.message,
+            diagnostics: JSON.stringify(diagnostics),
+            enqueued_at: String(letter.enqueuedAt),
+            last_touched: String(letter.lastTouched),
+            processing_started: null,
+        };
+    }
+    async function sequenceRows(db, seqId) {
+        return db.selectFrom(table)
+            .selectAll()
+            .where("processing_group", "=", processingGroup)
+            .where("sequence_identifier", "=", seqId)
+            .orderBy("sequence_index", "asc")
+            .execute();
+    }
+    async function distinctSequences(db) {
+        const rows = await db.selectFrom(table)
+            .select("sequence_identifier")
+            .distinct()
+            .where("processing_group", "=", processingGroup)
+            .execute();
+        return rows.map((r) => r.sequence_identifier);
+    }
+    return {
+        async enqueue(letter) {
+            const db = getDb();
+            const existing = await sequenceRows(db, letter.sequenceIdentifier);
+            if (existing.length === 0) {
+                if ((await distinctSequences(db)).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].sequence_index + 1;
+            await db.insertInto(table).values(letterToRow(letter, idx, newId(processingGroup))).execute();
+        },
+        async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+            const db = getDb();
+            const existing = await sequenceRows(db, 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].sequence_index + 1;
+            await db.insertInto(table).values(letterToRow(letterSupplier(), idx, newId(processingGroup))).execute();
+            return true;
+        },
+        async evict(_sequenceIdentifier, letter) {
+            const db = getDb();
+            const id = letter.diagnostics[DL_ID];
+            if (typeof id !== "string")
+                return;
+            await db.deleteFrom(table)
+                .where("processing_group", "=", processingGroup)
+                .where("dead_letter_id", "=", id)
+                .execute();
+        },
+        async requeue(letter, update) {
+            const db = getDb();
+            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 db.updateTable(table)
+                .set({
+                cause_type: cause.name,
+                cause_message: cause.message,
+                diagnostics: JSON.stringify(diagnostics),
+                last_touched: String(Date.now()),
+            })
+                .where("processing_group", "=", processingGroup)
+                .where("dead_letter_id", "=", id)
+                .execute();
+        },
+        async contains(sequenceIdentifier) {
+            const db = getDb();
+            const row = await db.selectFrom(table)
+                .select("dead_letter_id")
+                .where("processing_group", "=", processingGroup)
+                .where("sequence_identifier", "=", sequenceIdentifier)
+                .limit(1)
+                .executeTakeFirst();
+            return row != null;
+        },
+        async deadLetterSequence(sequenceIdentifier) {
+            const db = getDb();
+            return (await sequenceRows(db, sequenceIdentifier)).map(rowToLetter);
+        },
+        async sequenceIdentifiers() {
+            return distinctSequences(getDb());
+        },
+        async process(sequenceFilter, processingTask) {
+            const db = getDb();
+            const candidates = (await distinctSequences(db)).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(db, seqId);
+                if (rows.length === 0)
+                    continue;
+                const head = rows[0];
+                const leased = head.processing_started != null && Number(head.processing_started) > cutoff;
+                if (leased)
+                    continue;
+                if (Number(head.last_touched) < oldest) {
+                    oldest = Number(head.last_touched);
+                    chosen = seqId;
+                }
+            }
+            if (!chosen)
+                return false;
+            // Claim the sequence head's lease for the duration of this pass.
+            const headRows = await sequenceRows(db, chosen);
+            await db.updateTable(table)
+                .set({ processing_started: String(Date.now()) })
+                .where("processing_group", "=", processingGroup)
+                .where("dead_letter_id", "=", headRows[0].dead_letter_id)
+                .execute();
+            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(db, chosen);
+                if (remaining.length > 0 && remaining[0].processing_started != null) {
+                    await db.updateTable(table)
+                        .set({ processing_started: null })
+                        .where("processing_group", "=", processingGroup)
+                        .where("dead_letter_id", "=", remaining[0].dead_letter_id)
+                        .execute();
+                }
+            }
+        },
+        async size() {
+            const db = getDb();
+            const rows = await db.selectFrom(table)
+                .select("dead_letter_id")
+                .where("processing_group", "=", processingGroup)
+                .execute();
+            return rows.length;
+        },
+        async amountOfSequences() {
+            return (await distinctSequences(getDb())).length;
+        },
+        async clear() {
+            const db = getDb();
+            await db.deleteFrom(table)
+                .where("processing_group", "=", processingGroup)
+                .execute();
+        },
+        async isFull(sequenceIdentifier) {
+            const db = getDb();
+            const rows = await sequenceRows(db, sequenceIdentifier);
+            if (rows.length > 0)
+                return rows.length >= maxSequenceSize;
+            return (await distinctSequences(db)).length >= maxSequences;
+        },
+    };
+}
+//# sourceMappingURL=kysely-dead-letter-queue.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/kysely",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Kysely extension for Kronos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -48,8 +48,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": {
     "kysely": ">=0.27.0"

package/src/index.ts

@@ -8,3 +8,8 @@ export {
   kyselyTokenStore,
   type KyselyDbLike,
 } from "./kysely-token-store.js"
+
+export {
+  kyselyDeadLetterQueue,
+  type KyselyDeadLetterQueueConfig,
+} from "./kysely-dead-letter-queue.js"

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

@@ -0,0 +1,301 @@
+import type { DeadLetter, EnqueueDecision, SequencedDeadLetterQueue } from "@kronos-ts/messaging"
+import { getActiveTransaction, DeadLetterQueueOverflowError } from "@kronos-ts/messaging"
+import type { KyselyTransaction } from "./kysely-transaction-manager.js"
+import type { KyselyDbLike } from "./kysely-token-store.js"
+
+/**
+ * Dead letter table interface for Kysely. Users must define this table in
+ * their Kysely database interface:
+ *
+ * ```typescript
+ * interface Database {
+ *   kronos_dead_letters: {
+ *     dead_letter_id: string
+ *     processing_group: string
+ *     sequence_identifier: string
+ *     sequence_index: number
+ *     message: string
+ *     cause_type: string | null
+ *     cause_message: string | null
+ *     diagnostics: string
+ *     enqueued_at: string
+ *     last_touched: string
+ *     processing_started: string | null
+ *   }
+ * }
+ * ```
+ *
+ * Persistent {@link SequencedDeadLetterQueue} backed by Kysely — mirrors the
+ * Drizzle reference implementation in query semantics.
+ *
+ * Like {@link kyselyTokenStore} 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 `sequence_index`; a
+ * `processing_started` lease column makes `process()` safe across multiple
+ * nodes (Axon parity).
+ */
+export interface KyselyDeadLetterQueueConfig {
+  /** The Kysely database instance (or transaction). */
+  db: KyselyDbLike
+  /** Processing group (the processor name) this queue serves. */
+  processingGroup: string
+  /** Table name. Default: `kronos_dead_letters`. */
+  tableName?: 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 {
+  dead_letter_id: string
+  processing_group: string
+  sequence_identifier: string
+  sequence_index: number
+  message: string
+  cause_type: string | null
+  cause_message: string | null
+  diagnostics: string
+  enqueued_at: string
+  last_touched: string
+  processing_started: string | null
+}
+
+export function kyselyDeadLetterQueue(config: KyselyDeadLetterQueueConfig): SequencedDeadLetterQueue {
+  const { processingGroup } = config
+  const table = config.tableName ?? "kronos_dead_letters"
+  const maxSequences = config.maxSequences ?? 1024
+  const maxSequenceSize = config.maxSequenceSize ?? 1024
+  const claimDurationMs = config.claimDurationMs ?? 30000
+
+  function getDb(): KyselyDbLike {
+    return getActiveTransaction<KyselyTransaction>() ?? config.db
+  }
+
+  function rowToLetter(row: DeadLetterRow): DeadLetter {
+    const cause = new Error(row.cause_message ?? "")
+    if (row.cause_type) cause.name = row.cause_type
+    return {
+      message: JSON.parse(row.message),
+      cause,
+      enqueuedAt: Number(row.enqueued_at),
+      lastTouched: Number(row.last_touched),
+      diagnostics: { ...JSON.parse(row.diagnostics), [DL_ID]: row.dead_letter_id },
+      sequenceIdentifier: row.sequence_identifier,
+    }
+  }
+
+  function letterToRow(letter: DeadLetter, sequenceIndex: number, deadLetterId: string): DeadLetterRow {
+    const { [DL_ID]: _omit, ...diagnostics } = letter.diagnostics as Record<string, unknown>
+    return {
+      dead_letter_id: deadLetterId,
+      processing_group: processingGroup,
+      sequence_identifier: letter.sequenceIdentifier,
+      sequence_index: sequenceIndex,
+      message: JSON.stringify(letter.message),
+      cause_type: letter.cause.name,
+      cause_message: letter.cause.message,
+      diagnostics: JSON.stringify(diagnostics),
+      enqueued_at: String(letter.enqueuedAt),
+      last_touched: String(letter.lastTouched),
+      processing_started: null,
+    }
+  }
+
+  async function sequenceRows(db: KyselyDbLike, seqId: string): Promise<DeadLetterRow[]> {
+    return db.selectFrom(table)
+      .selectAll()
+      .where("processing_group", "=", processingGroup)
+      .where("sequence_identifier", "=", seqId)
+      .orderBy("sequence_index", "asc")
+      .execute()
+  }
+
+  async function distinctSequences(db: KyselyDbLike): Promise<string[]> {
+    const rows = await db.selectFrom(table)
+      .select("sequence_identifier")
+      .distinct()
+      .where("processing_group", "=", processingGroup)
+      .execute()
+    return rows.map((r: { sequence_identifier: string }) => r.sequence_identifier)
+  }
+
+  return {
+    async enqueue(letter) {
+      const db = getDb()
+      const existing = await sequenceRows(db, letter.sequenceIdentifier)
+      if (existing.length === 0) {
+        if ((await distinctSequences(db)).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].sequence_index + 1
+      await db.insertInto(table).values(letterToRow(letter, idx, newId(processingGroup))).execute()
+    },
+
+    async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+      const db = getDb()
+      const existing = await sequenceRows(db, 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].sequence_index + 1
+      await db.insertInto(table).values(letterToRow(letterSupplier(), idx, newId(processingGroup))).execute()
+      return true
+    },
+
+    async evict(_sequenceIdentifier, letter) {
+      const db = getDb()
+      const id = (letter.diagnostics as Record<string, unknown>)[DL_ID]
+      if (typeof id !== "string") return
+      await db.deleteFrom(table)
+        .where("processing_group", "=", processingGroup)
+        .where("dead_letter_id", "=", id)
+        .execute()
+    },
+
+    async requeue(letter, update) {
+      const db = getDb()
+      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 db.updateTable(table)
+        .set({
+          cause_type: cause.name,
+          cause_message: cause.message,
+          diagnostics: JSON.stringify(diagnostics),
+          last_touched: String(Date.now()),
+        })
+        .where("processing_group", "=", processingGroup)
+        .where("dead_letter_id", "=", id)
+        .execute()
+    },
+
+    async contains(sequenceIdentifier) {
+      const db = getDb()
+      const row = await db.selectFrom(table)
+        .select("dead_letter_id")
+        .where("processing_group", "=", processingGroup)
+        .where("sequence_identifier", "=", sequenceIdentifier)
+        .limit(1)
+        .executeTakeFirst()
+      return row != null
+    },
+
+    async deadLetterSequence(sequenceIdentifier) {
+      const db = getDb()
+      return (await sequenceRows(db, sequenceIdentifier)).map(rowToLetter)
+    },
+
+    async sequenceIdentifiers() {
+      return distinctSequences(getDb())
+    },
+
+    async process(sequenceFilter, processingTask) {
+      const db = getDb()
+      const candidates = (await distinctSequences(db)).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(db, seqId)
+        if (rows.length === 0) continue
+        const head = rows[0]
+        const leased = head.processing_started != null && Number(head.processing_started) > cutoff
+        if (leased) continue
+        if (Number(head.last_touched) < oldest) {
+          oldest = Number(head.last_touched)
+          chosen = seqId
+        }
+      }
+      if (!chosen) return false
+
+      // Claim the sequence head's lease for the duration of this pass.
+      const headRows = await sequenceRows(db, chosen)
+      await db.updateTable(table)
+        .set({ processing_started: String(Date.now()) })
+        .where("processing_group", "=", processingGroup)
+        .where("dead_letter_id", "=", headRows[0].dead_letter_id)
+        .execute()
+
+      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(db, chosen)
+        if (remaining.length > 0 && remaining[0].processing_started != null) {
+          await db.updateTable(table)
+            .set({ processing_started: null })
+            .where("processing_group", "=", processingGroup)
+            .where("dead_letter_id", "=", remaining[0].dead_letter_id)
+            .execute()
+        }
+      }
+    },
+
+    async size() {
+      const db = getDb()
+      const rows = await db.selectFrom(table)
+        .select("dead_letter_id")
+        .where("processing_group", "=", processingGroup)
+        .execute()
+      return rows.length
+    },
+
+    async amountOfSequences() {
+      return (await distinctSequences(getDb())).length
+    },
+
+    async clear() {
+      const db = getDb()
+      await db.deleteFrom(table)
+        .where("processing_group", "=", processingGroup)
+        .execute()
+    },
+
+    async isFull(sequenceIdentifier) {
+      const db = getDb()
+      const rows = await sequenceRows(db, sequenceIdentifier)
+      if (rows.length > 0) return rows.length >= maxSequenceSize
+      return (await distinctSequences(db)).length >= maxSequences
+    },
+  }
+}