@kronos-ts/knex 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { knexTransactionManager, type KnexInstanceLike, type KnexTransaction, } from "./knex-transaction-manager.js";
 export { knexTokenStore, type KnexQueryable, } from "./knex-token-store.js";
+export { knexDeadLetterQueue, type KnexDeadLetterQueueConfig, } from "./knex-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,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { knexTransactionManager, } from "./knex-transaction-manager.js";
 export { knexTokenStore, } from "./knex-token-store.js";
+export { knexDeadLetterQueue, } from "./knex-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,sBAAsB,GAGvB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAGvB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAA"}

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

@@ -0,0 +1,57 @@
+import type { SequencedDeadLetterQueue } from "@kronos-ts/messaging";
+import type { KnexQueryable } from "./knex-token-store.js";
+/**
+ * Persistent {@link SequencedDeadLetterQueue} backed by Knex — mirrors the
+ * Drizzle reference implementation, translated to Knex's query builder style.
+ *
+ * Like {@link knexTokenStore} 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).
+ *
+ * Expected table (`kronos_dead_letters`), columns:
+ * - `dead_letter_id` (PK) — persistent row id (varchar)
+ * - `processing_group` — the processor name partition (varchar, not null)
+ * - `sequence_identifier` — the sequence this letter belongs to (varchar, not null)
+ * - `sequence_index` — monotonic per-sequence FIFO index (integer, not null)
+ * - `message` — JSON-serialized EventMessage (text, not null)
+ * - `cause_type` — error name / type (varchar, nullable)
+ * - `cause_message` — error message (text, nullable)
+ * - `diagnostics` — JSON-serialized diagnostics map (text, not null)
+ * - `enqueued_at` — epoch-ms as string (varchar, not null)
+ * - `last_touched` — epoch-ms as string (varchar, not null)
+ * - `processing_started` — epoch-ms lease as string (varchar, nullable)
+ *
+ * A composite index on `(processing_group, sequence_identifier, sequence_index)`
+ * keeps per-sequence reads ordered.
+ */
+export interface KnexDeadLetterQueueConfig {
+    /** 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;
+}
+/**
+ * Creates a {@link SequencedDeadLetterQueue} backed by Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexDeadLetterQueue } from "@kronos-ts/knex"
+ *
+ * const dlq = knexDeadLetterQueue(knex, { processingGroup: "my-processor" })
+ * ```
+ */
+export declare function knexDeadLetterQueue(knex: KnexQueryable, config: KnexDeadLetterQueueConfig): SequencedDeadLetterQueue;
+//# sourceMappingURL=knex-dead-letter-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knex-dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/knex-dead-letter-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAGjG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,yBAAyB;IACxC,+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;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,yBAAyB,GAChC,wBAAwB,CA6M1B"}

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

@@ -0,0 +1,214 @@
+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 Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexDeadLetterQueue } from "@kronos-ts/knex"
+ *
+ * const dlq = knexDeadLetterQueue(knex, { processingGroup: "my-processor" })
+ * ```
+ */
+export function knexDeadLetterQueue(knex, 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 getKnex() {
+        return getActiveTransaction() ?? knex;
+    }
+    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(k, seqId) {
+        return k(table)
+            .where({ processing_group: processingGroup, sequence_identifier: seqId })
+            .orderBy("sequence_index", "asc");
+    }
+    async function distinctSequences(k) {
+        const rows = await k(table)
+            .where({ processing_group: processingGroup })
+            .distinct("sequence_identifier");
+        return rows.map((r) => r.sequence_identifier);
+    }
+    return {
+        async enqueue(letter) {
+            const k = getKnex();
+            const existing = await sequenceRows(k, letter.sequenceIdentifier);
+            if (existing.length === 0) {
+                if ((await distinctSequences(k)).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 k(table).insert(letterToRow(letter, idx, newId(processingGroup)));
+        },
+        async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+            const k = getKnex();
+            const existing = await sequenceRows(k, 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 k(table).insert(letterToRow(letterSupplier(), idx, newId(processingGroup)));
+            return true;
+        },
+        async evict(_sequenceIdentifier, letter) {
+            const k = getKnex();
+            const id = letter.diagnostics[DL_ID];
+            if (typeof id !== "string")
+                return;
+            await k(table)
+                .where({ processing_group: processingGroup, dead_letter_id: id })
+                .delete();
+        },
+        async requeue(letter, update) {
+            const k = getKnex();
+            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 k(table)
+                .where({ processing_group: processingGroup, dead_letter_id: id })
+                .update({
+                cause_type: cause.name,
+                cause_message: cause.message,
+                diagnostics: JSON.stringify(diagnostics),
+                last_touched: String(Date.now()),
+            });
+        },
+        async contains(sequenceIdentifier) {
+            const k = getKnex();
+            const row = await k(table)
+                .where({ processing_group: processingGroup, sequence_identifier: sequenceIdentifier })
+                .first();
+            return row != null;
+        },
+        async deadLetterSequence(sequenceIdentifier) {
+            const k = getKnex();
+            return (await sequenceRows(k, sequenceIdentifier)).map(rowToLetter);
+        },
+        async sequenceIdentifiers() {
+            return distinctSequences(getKnex());
+        },
+        async process(sequenceFilter, processingTask) {
+            const k = getKnex();
+            const candidates = (await distinctSequences(k)).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(k, 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(k, chosen);
+            await k(table)
+                .where({ processing_group: processingGroup, dead_letter_id: headRows[0].dead_letter_id })
+                .update({ processing_started: 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(k, chosen);
+                if (remaining.length > 0 && remaining[0].processing_started != null) {
+                    await k(table)
+                        .where({ processing_group: processingGroup, dead_letter_id: remaining[0].dead_letter_id })
+                        .update({ processing_started: null });
+                }
+            }
+        },
+        async size() {
+            const k = getKnex();
+            const rows = await k(table)
+                .where({ processing_group: processingGroup })
+                .select("dead_letter_id");
+            return rows.length;
+        },
+        async amountOfSequences() {
+            return (await distinctSequences(getKnex())).length;
+        },
+        async clear() {
+            const k = getKnex();
+            await k(table)
+                .where({ processing_group: processingGroup })
+                .delete();
+        },
+        async isFull(sequenceIdentifier) {
+            const k = getKnex();
+            const rows = await sequenceRows(k, sequenceIdentifier);
+            if (rows.length > 0)
+                return rows.length >= maxSequenceSize;
+            return (await distinctSequences(k)).length >= maxSequences;
+        },
+    };
+}
+//# sourceMappingURL=knex-dead-letter-queue.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/knex",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Knex 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": {
     "knex": ">=3.0.0"

package/src/index.ts

@@ -8,3 +8,8 @@ export {
   knexTokenStore,
   type KnexQueryable,
 } from "./knex-token-store.js"
+
+export {
+  knexDeadLetterQueue,
+  type KnexDeadLetterQueueConfig,
+} from "./knex-dead-letter-queue.js"

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

@@ -0,0 +1,278 @@
+import type { DeadLetter, EnqueueDecision, SequencedDeadLetterQueue } from "@kronos-ts/messaging"
+import { getActiveTransaction, DeadLetterQueueOverflowError } from "@kronos-ts/messaging"
+import type { KnexTransaction } from "./knex-transaction-manager.js"
+import type { KnexQueryable } from "./knex-token-store.js"
+
+/**
+ * Persistent {@link SequencedDeadLetterQueue} backed by Knex — mirrors the
+ * Drizzle reference implementation, translated to Knex's query builder style.
+ *
+ * Like {@link knexTokenStore} 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).
+ *
+ * Expected table (`kronos_dead_letters`), columns:
+ * - `dead_letter_id` (PK) — persistent row id (varchar)
+ * - `processing_group` — the processor name partition (varchar, not null)
+ * - `sequence_identifier` — the sequence this letter belongs to (varchar, not null)
+ * - `sequence_index` — monotonic per-sequence FIFO index (integer, not null)
+ * - `message` — JSON-serialized EventMessage (text, not null)
+ * - `cause_type` — error name / type (varchar, nullable)
+ * - `cause_message` — error message (text, nullable)
+ * - `diagnostics` — JSON-serialized diagnostics map (text, not null)
+ * - `enqueued_at` — epoch-ms as string (varchar, not null)
+ * - `last_touched` — epoch-ms as string (varchar, not null)
+ * - `processing_started` — epoch-ms lease as string (varchar, nullable)
+ *
+ * A composite index on `(processing_group, sequence_identifier, sequence_index)`
+ * keeps per-sequence reads ordered.
+ */
+export interface KnexDeadLetterQueueConfig {
+  /** 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}`
+}
+
+/**
+ * Creates a {@link SequencedDeadLetterQueue} backed by Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexDeadLetterQueue } from "@kronos-ts/knex"
+ *
+ * const dlq = knexDeadLetterQueue(knex, { processingGroup: "my-processor" })
+ * ```
+ */
+export function knexDeadLetterQueue(
+  knex: KnexQueryable,
+  config: KnexDeadLetterQueueConfig,
+): 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 getKnex(): KnexQueryable {
+    return getActiveTransaction<KnexTransaction>() ?? knex
+  }
+
+  function rowToLetter(row: any): 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) {
+    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 as string | null,
+    }
+  }
+
+  async function sequenceRows(k: KnexQueryable, seqId: string): Promise<any[]> {
+    return k(table)
+      .where({ processing_group: processingGroup, sequence_identifier: seqId })
+      .orderBy("sequence_index", "asc")
+  }
+
+  async function distinctSequences(k: KnexQueryable): Promise<string[]> {
+    const rows = await k(table)
+      .where({ processing_group: processingGroup })
+      .distinct("sequence_identifier")
+    return rows.map((r: any) => r.sequence_identifier)
+  }
+
+  return {
+    async enqueue(letter) {
+      const k = getKnex()
+      const existing = await sequenceRows(k, letter.sequenceIdentifier)
+      if (existing.length === 0) {
+        if ((await distinctSequences(k)).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 k(table).insert(letterToRow(letter, idx, newId(processingGroup)))
+    },
+
+    async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+      const k = getKnex()
+      const existing = await sequenceRows(k, 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 k(table).insert(letterToRow(letterSupplier(), idx, newId(processingGroup)))
+      return true
+    },
+
+    async evict(_sequenceIdentifier, letter) {
+      const k = getKnex()
+      const id = (letter.diagnostics as Record<string, unknown>)[DL_ID]
+      if (typeof id !== "string") return
+      await k(table)
+        .where({ processing_group: processingGroup, dead_letter_id: id })
+        .delete()
+    },
+
+    async requeue(letter, update) {
+      const k = getKnex()
+      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 k(table)
+        .where({ processing_group: processingGroup, dead_letter_id: id })
+        .update({
+          cause_type: cause.name,
+          cause_message: cause.message,
+          diagnostics: JSON.stringify(diagnostics),
+          last_touched: String(Date.now()),
+        })
+    },
+
+    async contains(sequenceIdentifier) {
+      const k = getKnex()
+      const row = await k(table)
+        .where({ processing_group: processingGroup, sequence_identifier: sequenceIdentifier })
+        .first()
+      return row != null
+    },
+
+    async deadLetterSequence(sequenceIdentifier) {
+      const k = getKnex()
+      return (await sequenceRows(k, sequenceIdentifier)).map(rowToLetter)
+    },
+
+    async sequenceIdentifiers() {
+      return distinctSequences(getKnex())
+    },
+
+    async process(sequenceFilter, processingTask) {
+      const k = getKnex()
+      const candidates = (await distinctSequences(k)).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(k, 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(k, chosen)
+      await k(table)
+        .where({ processing_group: processingGroup, dead_letter_id: headRows[0].dead_letter_id })
+        .update({ processing_started: 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(k, chosen)
+        if (remaining.length > 0 && remaining[0].processing_started != null) {
+          await k(table)
+            .where({ processing_group: processingGroup, dead_letter_id: remaining[0].dead_letter_id })
+            .update({ processing_started: null })
+        }
+      }
+    },
+
+    async size() {
+      const k = getKnex()
+      const rows = await k(table)
+        .where({ processing_group: processingGroup })
+        .select("dead_letter_id")
+      return rows.length
+    },
+
+    async amountOfSequences() {
+      return (await distinctSequences(getKnex())).length
+    },
+
+    async clear() {
+      const k = getKnex()
+      await k(table)
+        .where({ processing_group: processingGroup })
+        .delete()
+    },
+
+    async isFull(sequenceIdentifier) {
+      const k = getKnex()
+      const rows = await sequenceRows(k, sequenceIdentifier)
+      if (rows.length > 0) return rows.length >= maxSequenceSize
+      return (await distinctSequences(k)).length >= maxSequences
+    },
+  }
+}