@agent-relay/storage 0.1.0

package/dist/dlq-adapter.js

@@ -0,0 +1,664 @@
+/**
+ * Dead Letter Queue Storage Adapter
+ *
+ * Abstract interface for DLQ storage with implementations for:
+ * - SQLite (local daemon)
+ * - PostgreSQL (cloud deployment)
+ * - In-memory (testing)
+ *
+ * Follows the adapter pattern used by the main storage layer.
+ */
+// =============================================================================
+// Default Configuration
+// =============================================================================
+export const DEFAULT_DLQ_CONFIG = {
+    enabled: true,
+    retentionHours: 168, // 7 days
+    maxEntries: 10000,
+    autoCleanup: true,
+    cleanupIntervalMinutes: 60,
+    alertThreshold: 1000,
+};
+const DLQ_SQLITE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS dead_letters (
+  id TEXT PRIMARY KEY,
+  message_id TEXT NOT NULL,
+  from_agent TEXT NOT NULL,
+  to_agent TEXT NOT NULL,
+  topic TEXT,
+  kind TEXT NOT NULL,
+  body TEXT NOT NULL,
+  data TEXT,
+  thread TEXT,
+  original_ts INTEGER NOT NULL,
+  dlq_ts INTEGER NOT NULL,
+  reason TEXT NOT NULL,
+  error_message TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_attempt_ts INTEGER,
+  dlq_retry_count INTEGER NOT NULL DEFAULT 0,
+  acknowledged INTEGER NOT NULL DEFAULT 0,
+  acknowledged_ts INTEGER,
+  acknowledged_by TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_dlq_to ON dead_letters(to_agent);
+CREATE INDEX IF NOT EXISTS idx_dlq_from ON dead_letters(from_agent);
+CREATE INDEX IF NOT EXISTS idx_dlq_reason ON dead_letters(reason);
+CREATE INDEX IF NOT EXISTS idx_dlq_ts ON dead_letters(dlq_ts);
+CREATE INDEX IF NOT EXISTS idx_dlq_acknowledged ON dead_letters(acknowledged);
+`;
+export class SQLiteDLQAdapter {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() {
+        this.db.exec(DLQ_SQLITE_SCHEMA);
+    }
+    async add(messageId, envelope, reason, attemptCount, errorMessage) {
+        const id = `dlq_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const now = Date.now();
+        const deadLetter = {
+            id,
+            messageId,
+            from: envelope.from,
+            to: envelope.to,
+            topic: envelope.topic,
+            kind: envelope.kind,
+            body: envelope.body,
+            data: envelope.data,
+            thread: envelope.thread,
+            originalTs: envelope.ts,
+            dlqTs: now,
+            reason,
+            errorMessage,
+            attemptCount,
+            lastAttemptTs: now,
+            dlqRetryCount: 0,
+            acknowledged: false,
+        };
+        const stmt = this.db.prepare(`
+      INSERT INTO dead_letters (
+        id, message_id, from_agent, to_agent, topic, kind, body, data, thread,
+        original_ts, dlq_ts, reason, error_message, attempt_count, last_attempt_ts,
+        dlq_retry_count, acknowledged
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(deadLetter.id, deadLetter.messageId, deadLetter.from, deadLetter.to, deadLetter.topic ?? null, deadLetter.kind, deadLetter.body, deadLetter.data ? JSON.stringify(deadLetter.data) : null, deadLetter.thread ?? null, deadLetter.originalTs, deadLetter.dlqTs, deadLetter.reason, deadLetter.errorMessage ?? null, deadLetter.attemptCount, deadLetter.lastAttemptTs ?? null, deadLetter.dlqRetryCount, deadLetter.acknowledged ? 1 : 0);
+        return deadLetter;
+    }
+    async get(id) {
+        const stmt = this.db.prepare('SELECT * FROM dead_letters WHERE id = ?');
+        const row = stmt.get(id);
+        return row ? this.rowToDeadLetter(row) : null;
+    }
+    async query(query = {}) {
+        const conditions = [];
+        const params = [];
+        if (query.to) {
+            conditions.push('to_agent = ?');
+            params.push(query.to);
+        }
+        if (query.from) {
+            conditions.push('from_agent = ?');
+            params.push(query.from);
+        }
+        if (query.reason) {
+            conditions.push('reason = ?');
+            params.push(query.reason);
+        }
+        if (query.acknowledged !== undefined) {
+            conditions.push('acknowledged = ?');
+            params.push(query.acknowledged ? 1 : 0);
+        }
+        if (query.afterTs) {
+            conditions.push('dlq_ts > ?');
+            params.push(query.afterTs);
+        }
+        if (query.beforeTs) {
+            conditions.push('dlq_ts < ?');
+            params.push(query.beforeTs);
+        }
+        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const orderColumn = query.orderBy === 'originalTs' ? 'original_ts' :
+            query.orderBy === 'attemptCount' ? 'attempt_count' : 'dlq_ts';
+        const orderDir = query.orderDir ?? 'DESC';
+        const limit = query.limit ?? 100;
+        const offset = query.offset ?? 0;
+        const sql = `
+      SELECT * FROM dead_letters ${whereClause}
+      ORDER BY ${orderColumn} ${orderDir}
+      LIMIT ? OFFSET ?
+    `;
+        params.push(limit, offset);
+        const stmt = this.db.prepare(sql);
+        const rows = stmt.all(...params);
+        return rows.map(row => this.rowToDeadLetter(row));
+    }
+    async acknowledge(id, acknowledgedBy = 'system') {
+        const stmt = this.db.prepare(`
+      UPDATE dead_letters SET acknowledged = 1, acknowledged_ts = ?, acknowledged_by = ?
+      WHERE id = ? AND acknowledged = 0
+    `);
+        const result = stmt.run(Date.now(), acknowledgedBy, id);
+        return result.changes > 0;
+    }
+    async acknowledgeMany(ids, acknowledgedBy = 'system') {
+        const placeholders = ids.map(() => '?').join(',');
+        const stmt = this.db.prepare(`
+      UPDATE dead_letters SET acknowledged = 1, acknowledged_ts = ?, acknowledged_by = ?
+      WHERE id IN (${placeholders}) AND acknowledged = 0
+    `);
+        const result = stmt.run(Date.now(), acknowledgedBy, ...ids);
+        return result.changes;
+    }
+    async incrementRetry(id) {
+        const stmt = this.db.prepare(`
+      UPDATE dead_letters SET dlq_retry_count = dlq_retry_count + 1, last_attempt_ts = ?
+      WHERE id = ?
+    `);
+        const result = stmt.run(Date.now(), id);
+        return result.changes > 0;
+    }
+    async remove(id) {
+        const stmt = this.db.prepare('DELETE FROM dead_letters WHERE id = ?');
+        const result = stmt.run(id);
+        return result.changes > 0;
+    }
+    async getStats() {
+        const totalRow = this.db.prepare('SELECT COUNT(*) as count FROM dead_letters').get();
+        const unackRow = this.db.prepare('SELECT COUNT(*) as count FROM dead_letters WHERE acknowledged = 0').get();
+        const reasonRows = this.db.prepare('SELECT reason, COUNT(*) as count FROM dead_letters GROUP BY reason').all();
+        const byReason = {
+            max_retries_exceeded: 0, ttl_expired: 0, connection_lost: 0, target_not_found: 0,
+            signature_invalid: 0, payload_too_large: 0, rate_limited: 0, unknown: 0,
+        };
+        for (const row of reasonRows) {
+            byReason[row.reason] = row.count;
+        }
+        const targetRows = this.db.prepare('SELECT to_agent, COUNT(*) as count FROM dead_letters GROUP BY to_agent ORDER BY count DESC LIMIT 10').all();
+        const byTarget = {};
+        for (const row of targetRows) {
+            byTarget[row.to_agent] = row.count;
+        }
+        const oldestRow = this.db.prepare('SELECT MIN(dlq_ts) as ts FROM dead_letters WHERE acknowledged = 0').get();
+        const newestRow = this.db.prepare('SELECT MAX(dlq_ts) as ts FROM dead_letters WHERE acknowledged = 0').get();
+        const avgRow = this.db.prepare('SELECT AVG(dlq_retry_count) as avg FROM dead_letters').get();
+        return {
+            totalEntries: totalRow.count,
+            unacknowledged: unackRow.count,
+            byReason,
+            byTarget,
+            oldestEntryTs: oldestRow.ts,
+            newestEntryTs: newestRow.ts,
+            avgRetryCount: avgRow.avg ?? 0,
+        };
+    }
+    async cleanup(retentionHours, maxEntries) {
+        const cutoffTs = Date.now() - retentionHours * 3600 * 1000;
+        const retentionResult = this.db.prepare('DELETE FROM dead_letters WHERE dlq_ts < ?').run(cutoffTs);
+        const countRow = this.db.prepare('SELECT COUNT(*) as count FROM dead_letters').get();
+        let maxEntriesRemoved = 0;
+        if (countRow.count > maxEntries) {
+            const excess = countRow.count - maxEntries;
+            const trimResult = this.db.prepare(`
+        DELETE FROM dead_letters WHERE id IN (
+          SELECT id FROM dead_letters WHERE acknowledged = 1 ORDER BY dlq_ts ASC LIMIT ?
+        )
+      `).run(excess);
+            maxEntriesRemoved = trimResult.changes;
+        }
+        return { removed: retentionResult.changes + maxEntriesRemoved };
+    }
+    async getRetryable(maxRetries = 3, limit = 10) {
+        const stmt = this.db.prepare(`
+      SELECT * FROM dead_letters
+      WHERE acknowledged = 0 AND dlq_retry_count < ?
+      ORDER BY dlq_ts ASC LIMIT ?
+    `);
+        const rows = stmt.all(maxRetries, limit);
+        return rows.map(row => this.rowToDeadLetter(row));
+    }
+    async close() {
+        // SQLite connection managed externally
+    }
+    rowToDeadLetter(row) {
+        let data;
+        if (row.data) {
+            try {
+                data = JSON.parse(row.data);
+            }
+            catch {
+                // Invalid JSON data, leave as undefined
+                console.warn(`[dlq] Failed to parse data for dead letter ${row.id}`);
+            }
+        }
+        return {
+            id: row.id,
+            messageId: row.message_id,
+            from: row.from_agent,
+            to: row.to_agent,
+            topic: row.topic,
+            kind: row.kind,
+            body: row.body,
+            data,
+            thread: row.thread,
+            originalTs: row.original_ts,
+            dlqTs: row.dlq_ts,
+            reason: row.reason,
+            errorMessage: row.error_message,
+            attemptCount: row.attempt_count,
+            lastAttemptTs: row.last_attempt_ts,
+            dlqRetryCount: row.dlq_retry_count,
+            acknowledged: row.acknowledged === 1,
+            acknowledgedTs: row.acknowledged_ts,
+            acknowledgedBy: row.acknowledged_by,
+        };
+    }
+}
+const DLQ_POSTGRES_SCHEMA = `
+CREATE TABLE IF NOT EXISTS dead_letters (
+  id TEXT PRIMARY KEY,
+  message_id TEXT NOT NULL,
+  from_agent TEXT NOT NULL,
+  to_agent TEXT NOT NULL,
+  topic TEXT,
+  kind TEXT NOT NULL,
+  body TEXT NOT NULL,
+  data JSONB,
+  thread TEXT,
+  original_ts BIGINT NOT NULL,
+  dlq_ts BIGINT NOT NULL,
+  reason TEXT NOT NULL,
+  error_message TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_attempt_ts BIGINT,
+  dlq_retry_count INTEGER NOT NULL DEFAULT 0,
+  acknowledged BOOLEAN NOT NULL DEFAULT FALSE,
+  acknowledged_ts BIGINT,
+  acknowledged_by TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_dlq_to ON dead_letters(to_agent);
+CREATE INDEX IF NOT EXISTS idx_dlq_from ON dead_letters(from_agent);
+CREATE INDEX IF NOT EXISTS idx_dlq_reason ON dead_letters(reason);
+CREATE INDEX IF NOT EXISTS idx_dlq_ts ON dead_letters(dlq_ts);
+CREATE INDEX IF NOT EXISTS idx_dlq_acknowledged ON dead_letters(acknowledged);
+`;
+export class PostgresDLQAdapter {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async init() {
+        const client = await this.pool.connect();
+        try {
+            await client.query(DLQ_POSTGRES_SCHEMA);
+        }
+        finally {
+            client.release();
+        }
+    }
+    async add(messageId, envelope, reason, attemptCount, errorMessage) {
+        const id = `dlq_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const now = Date.now();
+        const deadLetter = {
+            id,
+            messageId,
+            from: envelope.from,
+            to: envelope.to,
+            topic: envelope.topic,
+            kind: envelope.kind,
+            body: envelope.body,
+            data: envelope.data,
+            thread: envelope.thread,
+            originalTs: envelope.ts,
+            dlqTs: now,
+            reason,
+            errorMessage,
+            attemptCount,
+            lastAttemptTs: now,
+            dlqRetryCount: 0,
+            acknowledged: false,
+        };
+        await this.pool.query(`
+      INSERT INTO dead_letters (
+        id, message_id, from_agent, to_agent, topic, kind, body, data, thread,
+        original_ts, dlq_ts, reason, error_message, attempt_count, last_attempt_ts,
+        dlq_retry_count, acknowledged
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
+    `, [
+            deadLetter.id, deadLetter.messageId, deadLetter.from, deadLetter.to,
+            deadLetter.topic ?? null, deadLetter.kind, deadLetter.body,
+            deadLetter.data ? JSON.stringify(deadLetter.data) : null,
+            deadLetter.thread ?? null, deadLetter.originalTs, deadLetter.dlqTs,
+            deadLetter.reason, deadLetter.errorMessage ?? null, deadLetter.attemptCount,
+            deadLetter.lastAttemptTs ?? null, deadLetter.dlqRetryCount, deadLetter.acknowledged
+        ]);
+        return deadLetter;
+    }
+    async get(id) {
+        const result = await this.pool.query('SELECT * FROM dead_letters WHERE id = $1', [id]);
+        return result.rows[0] ? this.rowToDeadLetter(result.rows[0]) : null;
+    }
+    async query(query = {}) {
+        const conditions = [];
+        const params = [];
+        let paramIndex = 1;
+        if (query.to) {
+            conditions.push(`to_agent = $${paramIndex++}`);
+            params.push(query.to);
+        }
+        if (query.from) {
+            conditions.push(`from_agent = $${paramIndex++}`);
+            params.push(query.from);
+        }
+        if (query.reason) {
+            conditions.push(`reason = $${paramIndex++}`);
+            params.push(query.reason);
+        }
+        if (query.acknowledged !== undefined) {
+            conditions.push(`acknowledged = $${paramIndex++}`);
+            params.push(query.acknowledged);
+        }
+        if (query.afterTs) {
+            conditions.push(`dlq_ts > $${paramIndex++}`);
+            params.push(query.afterTs);
+        }
+        if (query.beforeTs) {
+            conditions.push(`dlq_ts < $${paramIndex++}`);
+            params.push(query.beforeTs);
+        }
+        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const orderColumn = query.orderBy === 'originalTs' ? 'original_ts' :
+            query.orderBy === 'attemptCount' ? 'attempt_count' : 'dlq_ts';
+        const orderDir = query.orderDir ?? 'DESC';
+        const limit = query.limit ?? 100;
+        const offset = query.offset ?? 0;
+        params.push(limit, offset);
+        const sql = `
+      SELECT * FROM dead_letters ${whereClause}
+      ORDER BY ${orderColumn} ${orderDir}
+      LIMIT $${paramIndex++} OFFSET $${paramIndex++}
+    `;
+        const result = await this.pool.query(sql, params);
+        return result.rows.map(row => this.rowToDeadLetter(row));
+    }
+    async acknowledge(id, acknowledgedBy = 'system') {
+        const result = await this.pool.query(`
+      UPDATE dead_letters SET acknowledged = TRUE, acknowledged_ts = $1, acknowledged_by = $2
+      WHERE id = $3 AND acknowledged = FALSE
+    `, [Date.now(), acknowledgedBy, id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async acknowledgeMany(ids, acknowledgedBy = 'system') {
+        const result = await this.pool.query(`
+      UPDATE dead_letters SET acknowledged = TRUE, acknowledged_ts = $1, acknowledged_by = $2
+      WHERE id = ANY($3) AND acknowledged = FALSE
+    `, [Date.now(), acknowledgedBy, ids]);
+        return result.rowCount ?? 0;
+    }
+    async incrementRetry(id) {
+        const result = await this.pool.query(`
+      UPDATE dead_letters SET dlq_retry_count = dlq_retry_count + 1, last_attempt_ts = $1
+      WHERE id = $2
+    `, [Date.now(), id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async remove(id) {
+        const result = await this.pool.query('DELETE FROM dead_letters WHERE id = $1', [id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async getStats() {
+        const [totalResult, unackResult, reasonResult, targetResult, oldestResult, newestResult, avgResult] = await Promise.all([
+            this.pool.query('SELECT COUNT(*) as count FROM dead_letters'),
+            this.pool.query('SELECT COUNT(*) as count FROM dead_letters WHERE acknowledged = FALSE'),
+            this.pool.query('SELECT reason, COUNT(*) as count FROM dead_letters GROUP BY reason'),
+            this.pool.query('SELECT to_agent, COUNT(*) as count FROM dead_letters GROUP BY to_agent ORDER BY count DESC LIMIT 10'),
+            this.pool.query('SELECT MIN(dlq_ts) as ts FROM dead_letters WHERE acknowledged = FALSE'),
+            this.pool.query('SELECT MAX(dlq_ts) as ts FROM dead_letters WHERE acknowledged = FALSE'),
+            this.pool.query('SELECT AVG(dlq_retry_count) as avg FROM dead_letters'),
+        ]);
+        const byReason = {
+            max_retries_exceeded: 0, ttl_expired: 0, connection_lost: 0, target_not_found: 0,
+            signature_invalid: 0, payload_too_large: 0, rate_limited: 0, unknown: 0,
+        };
+        for (const row of reasonResult.rows) {
+            byReason[row.reason] = parseInt(row.count, 10);
+        }
+        const byTarget = {};
+        for (const row of targetResult.rows) {
+            byTarget[row.to_agent] = parseInt(row.count, 10);
+        }
+        return {
+            totalEntries: parseInt(totalResult.rows[0]?.count ?? '0', 10),
+            unacknowledged: parseInt(unackResult.rows[0]?.count ?? '0', 10),
+            byReason,
+            byTarget,
+            oldestEntryTs: oldestResult.rows[0]?.ts ? parseInt(oldestResult.rows[0].ts, 10) : null,
+            newestEntryTs: newestResult.rows[0]?.ts ? parseInt(newestResult.rows[0].ts, 10) : null,
+            avgRetryCount: parseFloat(avgResult.rows[0]?.avg ?? '0'),
+        };
+    }
+    async cleanup(retentionHours, maxEntries) {
+        const cutoffTs = Date.now() - retentionHours * 3600 * 1000;
+        const retentionResult = await this.pool.query('DELETE FROM dead_letters WHERE dlq_ts < $1', [cutoffTs]);
+        const countResult = await this.pool.query('SELECT COUNT(*) as count FROM dead_letters');
+        const count = parseInt(countResult.rows[0]?.count ?? '0', 10);
+        let maxEntriesRemoved = 0;
+        if (count > maxEntries) {
+            const excess = count - maxEntries;
+            const trimResult = await this.pool.query(`
+        DELETE FROM dead_letters WHERE id IN (
+          SELECT id FROM dead_letters WHERE acknowledged = TRUE ORDER BY dlq_ts ASC LIMIT $1
+        )
+      `, [excess]);
+            maxEntriesRemoved = trimResult.rowCount ?? 0;
+        }
+        return { removed: (retentionResult.rowCount ?? 0) + maxEntriesRemoved };
+    }
+    async getRetryable(maxRetries = 3, limit = 10) {
+        const result = await this.pool.query(`
+      SELECT * FROM dead_letters
+      WHERE acknowledged = FALSE AND dlq_retry_count < $1
+      ORDER BY dlq_ts ASC LIMIT $2
+    `, [maxRetries, limit]);
+        return result.rows.map(row => this.rowToDeadLetter(row));
+    }
+    async close() {
+        // Pool managed externally
+    }
+    rowToDeadLetter(row) {
+        return {
+            id: row.id,
+            messageId: row.message_id,
+            from: row.from_agent,
+            to: row.to_agent,
+            topic: row.topic,
+            kind: row.kind,
+            body: row.body,
+            data: row.data,
+            thread: row.thread,
+            originalTs: parseInt(row.original_ts, 10),
+            dlqTs: parseInt(row.dlq_ts, 10),
+            reason: row.reason,
+            errorMessage: row.error_message,
+            attemptCount: row.attempt_count,
+            lastAttemptTs: row.last_attempt_ts ? parseInt(row.last_attempt_ts, 10) : undefined,
+            dlqRetryCount: row.dlq_retry_count,
+            acknowledged: row.acknowledged,
+            acknowledgedTs: row.acknowledged_ts ? parseInt(row.acknowledged_ts, 10) : undefined,
+            acknowledgedBy: row.acknowledged_by,
+        };
+    }
+}
+// =============================================================================
+// In-Memory Adapter (for testing)
+// =============================================================================
+export class InMemoryDLQAdapter {
+    letters = new Map();
+    async init() {
+        // No-op
+    }
+    async add(messageId, envelope, reason, attemptCount, errorMessage) {
+        const id = `dlq_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const now = Date.now();
+        const deadLetter = {
+            id,
+            messageId,
+            from: envelope.from,
+            to: envelope.to,
+            topic: envelope.topic,
+            kind: envelope.kind,
+            body: envelope.body,
+            data: envelope.data,
+            thread: envelope.thread,
+            originalTs: envelope.ts,
+            dlqTs: now,
+            reason,
+            errorMessage,
+            attemptCount,
+            lastAttemptTs: now,
+            dlqRetryCount: 0,
+            acknowledged: false,
+        };
+        this.letters.set(id, deadLetter);
+        return deadLetter;
+    }
+    async get(id) {
+        return this.letters.get(id) ?? null;
+    }
+    async query(query = {}) {
+        let results = Array.from(this.letters.values());
+        if (query.to)
+            results = results.filter(l => l.to === query.to);
+        if (query.from)
+            results = results.filter(l => l.from === query.from);
+        if (query.reason)
+            results = results.filter(l => l.reason === query.reason);
+        if (query.acknowledged !== undefined)
+            results = results.filter(l => l.acknowledged === query.acknowledged);
+        if (query.afterTs)
+            results = results.filter(l => l.dlqTs > query.afterTs);
+        if (query.beforeTs)
+            results = results.filter(l => l.dlqTs < query.beforeTs);
+        const orderDir = query.orderDir ?? 'DESC';
+        const orderBy = query.orderBy ?? 'dlqTs';
+        results.sort((a, b) => {
+            const aVal = orderBy === 'originalTs' ? a.originalTs : orderBy === 'attemptCount' ? a.attemptCount : a.dlqTs;
+            const bVal = orderBy === 'originalTs' ? b.originalTs : orderBy === 'attemptCount' ? b.attemptCount : b.dlqTs;
+            return orderDir === 'ASC' ? aVal - bVal : bVal - aVal;
+        });
+        const offset = query.offset ?? 0;
+        const limit = query.limit ?? 100;
+        return results.slice(offset, offset + limit);
+    }
+    async acknowledge(id, acknowledgedBy = 'system') {
+        const letter = this.letters.get(id);
+        if (!letter || letter.acknowledged)
+            return false;
+        letter.acknowledged = true;
+        letter.acknowledgedTs = Date.now();
+        letter.acknowledgedBy = acknowledgedBy;
+        return true;
+    }
+    async acknowledgeMany(ids, acknowledgedBy = 'system') {
+        let count = 0;
+        for (const id of ids) {
+            if (await this.acknowledge(id, acknowledgedBy))
+                count++;
+        }
+        return count;
+    }
+    async incrementRetry(id) {
+        const letter = this.letters.get(id);
+        if (!letter)
+            return false;
+        letter.dlqRetryCount++;
+        letter.lastAttemptTs = Date.now();
+        return true;
+    }
+    async remove(id) {
+        return this.letters.delete(id);
+    }
+    async getStats() {
+        const letters = Array.from(this.letters.values());
+        const byReason = {
+            max_retries_exceeded: 0, ttl_expired: 0, connection_lost: 0, target_not_found: 0,
+            signature_invalid: 0, payload_too_large: 0, rate_limited: 0, unknown: 0,
+        };
+        const byTarget = {};
+        let unacknowledged = 0;
+        let totalRetry = 0;
+        for (const l of letters) {
+            byReason[l.reason]++;
+            byTarget[l.to] = (byTarget[l.to] ?? 0) + 1;
+            if (!l.acknowledged)
+                unacknowledged++;
+            totalRetry += l.dlqRetryCount;
+        }
+        const unackLetters = letters.filter(l => !l.acknowledged);
+        const timestamps = unackLetters.map(l => l.dlqTs);
+        return {
+            totalEntries: letters.length,
+            unacknowledged,
+            byReason,
+            byTarget,
+            oldestEntryTs: timestamps.length > 0 ? Math.min(...timestamps) : null,
+            newestEntryTs: timestamps.length > 0 ? Math.max(...timestamps) : null,
+            avgRetryCount: letters.length > 0 ? totalRetry / letters.length : 0,
+        };
+    }
+    async cleanup(retentionHours, maxEntries) {
+        const cutoffTs = Date.now() - retentionHours * 3600 * 1000;
+        let removed = 0;
+        for (const [id, letter] of this.letters) {
+            if (letter.dlqTs < cutoffTs) {
+                this.letters.delete(id);
+                removed++;
+            }
+        }
+        // Enforce max entries
+        if (this.letters.size > maxEntries) {
+            const sorted = Array.from(this.letters.entries())
+                .filter(([, l]) => l.acknowledged)
+                .sort((a, b) => a[1].dlqTs - b[1].dlqTs);
+            const excess = this.letters.size - maxEntries;
+            for (let i = 0; i < excess && i < sorted.length; i++) {
+                this.letters.delete(sorted[i][0]);
+                removed++;
+            }
+        }
+        return { removed };
+    }
+    async getRetryable(maxRetries = 3, limit = 10) {
+        return Array.from(this.letters.values())
+            .filter(l => !l.acknowledged && l.dlqRetryCount < maxRetries)
+            .sort((a, b) => a.dlqTs - b.dlqTs)
+            .slice(0, limit);
+    }
+    async close() {
+        this.letters.clear();
+    }
+}
+/**
+ * Create a DLQ adapter based on configuration.
+ */
+export function createDLQAdapter(options) {
+    switch (options.type) {
+        case 'sqlite':
+            if (!options.sqlite)
+                throw new Error('SQLite database required');
+            return new SQLiteDLQAdapter(options.sqlite);
+        case 'postgres':
+            if (!options.postgres)
+                throw new Error('PostgreSQL pool required');
+            return new PostgresDLQAdapter(options.postgres);
+        case 'memory':
+            return new InMemoryDLQAdapter();
+        default:
+            throw new Error(`Unknown DLQ adapter type: ${options.type}`);
+    }
+}
+//# sourceMappingURL=dlq-adapter.js.map