@hotmeshio/hotmesh 0.10.2 → 0.12.0

package/build/services/stream/providers/postgres/kvtables.js

@@ -10,11 +10,9 @@ async function deploySchema(streamClient, appId, logger) {
     const releaseClient = isPool;
     try {
         const schemaName = appId.replace(/[^a-zA-Z0-9_]/g, '_');
-        const tableName = `${schemaName}.streams`;
         // First, check if tables already exist (no lock needed)
-        const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+        const tablesExist = await checkIfTablesExist(client, schemaName);
         if (tablesExist) {
-            // Tables already exist, no need to acquire lock or create tables
             return;
         }
         // Tables don't exist, need to acquire lock and create them
@@ -24,10 +22,10 @@ async function deploySchema(streamClient, appId, logger) {
             try {
                 await client.query('BEGIN');
                 // Double-check tables don't exist (race condition safety)
-                const tablesStillMissing = !(await checkIfTablesExist(client, schemaName, tableName));
+                const tablesStillMissing = !(await checkIfTablesExist(client, schemaName));
                 if (tablesStillMissing) {
-                    await createTables(client, schemaName, tableName);
-                    await createNotificationTriggers(client, schemaName, tableName);
+                    await createTables(client, schemaName);
+                    await createNotificationTriggers(client, schemaName);
                 }
                 await client.query('COMMIT');
             }
@@ -41,7 +39,7 @@ async function deploySchema(streamClient, appId, logger) {
                 await client.release();
             }
             // Wait for the deploy process to complete
-            await waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger);
+            await waitForTablesCreation(streamClient, lockId, schemaName, logger);
             return; // Already released client, don't release again in finally
         }
     }
@@ -72,16 +70,21 @@ function hashStringToInt(str) {
     }
     return Math.abs(hash);
 }
-async function checkIfTablesExist(client, schemaName, tableName) {
-    // Check both streams table exists AND roles table (from store provider)
-    // The roles table is created by the store provider and is used for scout role coordination
-    const result = await client.query(`SELECT 
-       to_regclass($1) AS streams_table,
-       to_regclass($2) AS roles_table`, [tableName, `${schemaName}.roles`]);
-    return result.rows[0].streams_table !== null &&
+async function checkIfTablesExist(client, schemaName) {
+    // Check engine_streams, worker_streams, AND roles table
+    const result = await client.query(`SELECT
+       to_regclass($1) AS engine_table,
+       to_regclass($2) AS worker_table,
+       to_regclass($3) AS roles_table`, [
+        `${schemaName}.engine_streams`,
+        `${schemaName}.worker_streams`,
+        `${schemaName}.roles`,
+    ]);
+    return result.rows[0].engine_table !== null &&
+        result.rows[0].worker_table !== null &&
         result.rows[0].roles_table !== null;
 }
-async function waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger) {
+async function waitForTablesCreation(streamClient, lockId, schemaName, logger) {
     let retries = 0;
     const maxRetries = Math.round(enums_1.HMSH_DEPLOYMENT_DELAY / enums_1.HMSH_DEPLOYMENT_PAUSE);
     while (retries < maxRetries) {
@@ -90,17 +93,14 @@ async function waitForTablesCreation(streamClient, lockId, schemaName, tableName
             streamClient?.idleCount !== undefined;
         const client = isPool ? await streamClient.connect() : streamClient;
         try {
-            // Check if tables exist directly (most efficient check)
-            const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+            const tablesExist = await checkIfTablesExist(client, schemaName);
             if (tablesExist) {
-                // Tables now exist, deployment is complete
                 return;
             }
             // Fallback: check if the lock has been released (indicates completion)
             const lockCheck = await client.query("SELECT NOT EXISTS (SELECT 1 FROM pg_locks WHERE locktype = 'advisory' AND objid = $1::bigint) AS unlocked", [lockId]);
             if (lockCheck.rows[0].unlocked) {
-                // Lock has been released, tables should exist now
-                const tablesExistAfterLock = await checkIfTablesExist(client, schemaName, tableName);
+                const tablesExistAfterLock = await checkIfTablesExist(client, schemaName);
                 if (tablesExistAfterLock) {
                     return;
                 }
@@ -113,22 +113,23 @@ async function waitForTablesCreation(streamClient, lockId, schemaName, tableName
         }
         retries++;
     }
-    logger.error('stream-table-create-timeout', { schemaName, tableName });
+    logger.error('stream-table-create-timeout', { schemaName });
     throw new Error('Timeout waiting for stream table creation');
 }
-async function createTables(client, schemaName, tableName) {
+async function createTables(client, schemaName) {
     await client.query(`CREATE SCHEMA IF NOT EXISTS ${schemaName};`);
-    // Main table creation with partitions
+    // ---- ENGINE_STREAMS table ----
+    const engineTable = `${schemaName}.engine_streams`;
     await client.query(`
-    CREATE TABLE IF NOT EXISTS ${tableName} (
+    CREATE TABLE IF NOT EXISTS ${engineTable} (
       id BIGSERIAL,
       stream_name TEXT NOT NULL,
-      group_name TEXT NOT NULL DEFAULT 'ENGINE',
       message TEXT NOT NULL,
       created_at TIMESTAMPTZ DEFAULT NOW(),
       reserved_at TIMESTAMPTZ,
       reserved_by TEXT,
       expired_at TIMESTAMPTZ,
+      dead_lettered_at TIMESTAMPTZ,
       max_retry_attempts INT DEFAULT 3,
       backoff_coefficient NUMERIC DEFAULT 10,
       maximum_interval_seconds INT DEFAULT 120,
@@ -138,86 +139,217 @@ async function createTables(client, schemaName, tableName) {
     ) PARTITION BY HASH (stream_name);
   `);
     for (let i = 0; i < 8; i++) {
-        const partitionTableName = `${schemaName}.streams_part_${i}`;
         await client.query(`
-      CREATE TABLE IF NOT EXISTS ${partitionTableName}
-      PARTITION OF ${tableName}
+      CREATE TABLE IF NOT EXISTS ${schemaName}.engine_streams_part_${i}
+      PARTITION OF ${engineTable}
       FOR VALUES WITH (modulus 8, remainder ${i});
     `);
     }
-    // Index for active messages (includes visible_at for visibility timeout support)
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_streams_active_messages 
-    ON ${tableName} (group_name, stream_name, reserved_at, visible_at, id)
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_active_messages
+    ON ${engineTable} (stream_name, reserved_at, visible_at, id)
     WHERE reserved_at IS NULL AND expired_at IS NULL;
   `);
-    // Optimized index for the simplified fetchMessages query (includes visible_at)
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_streams_message_fetch 
-    ON ${tableName} (stream_name, group_name, visible_at, id)
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_message_fetch
+    ON ${engineTable} (stream_name, visible_at, id)
     WHERE expired_at IS NULL;
   `);
-    // Index for expired messages
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_streams_expired_at 
-    ON ${tableName} (expired_at);
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_expired_at
+    ON ${engineTable} (expired_at);
   `);
-    // New index for stream stats optimization
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_stream_name_expired_at
-    ON ${tableName} (stream_name)
+    CREATE INDEX IF NOT EXISTS idx_engine_stream_name_expired_at
+    ON ${engineTable} (stream_name)
     WHERE expired_at IS NULL;
   `);
-    // TODO: revisit this index when solving automated cleanup
-    // Optional index for querying by creation time, if needed
-    // await client.query(`
-    //   CREATE INDEX IF NOT EXISTS idx_streams_created_at
-    //   ON ${tableName} (created_at);
-    // `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_processed_volume
+    ON ${engineTable} (expired_at, stream_name)
+    WHERE expired_at IS NOT NULL;
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_dead_lettered
+    ON ${engineTable} (dead_lettered_at, stream_name)
+    WHERE dead_lettered_at IS NOT NULL;
+  `);
+    // Migration: add dead_lettered_at column to existing tables
+    await client.query(`
+    DO $$ BEGIN
+      ALTER TABLE ${engineTable} ADD COLUMN IF NOT EXISTS dead_lettered_at TIMESTAMPTZ;
+    EXCEPTION WHEN duplicate_column THEN NULL;
+    END $$;
+  `);
+    // ---- WORKER_STREAMS table ----
+    const workerTable = `${schemaName}.worker_streams`;
+    await client.query(`
+    CREATE TABLE IF NOT EXISTS ${workerTable} (
+      id BIGSERIAL,
+      stream_name TEXT NOT NULL,
+      workflow_name TEXT NOT NULL DEFAULT '',
+      jid TEXT NOT NULL DEFAULT '',
+      aid TEXT NOT NULL DEFAULT '',
+      dad TEXT NOT NULL DEFAULT '',
+      msg_type TEXT NOT NULL DEFAULT '',
+      topic TEXT NOT NULL DEFAULT '',
+      message TEXT NOT NULL,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      reserved_at TIMESTAMPTZ,
+      reserved_by TEXT,
+      expired_at TIMESTAMPTZ,
+      dead_lettered_at TIMESTAMPTZ,
+      max_retry_attempts INT DEFAULT 3,
+      backoff_coefficient NUMERIC DEFAULT 10,
+      maximum_interval_seconds INT DEFAULT 120,
+      visible_at TIMESTAMPTZ DEFAULT NOW(),
+      retry_attempt INT DEFAULT 0,
+      PRIMARY KEY (stream_name, id)
+    ) PARTITION BY HASH (stream_name);
+  `);
+    for (let i = 0; i < 8; i++) {
+        await client.query(`
+      CREATE TABLE IF NOT EXISTS ${schemaName}.worker_streams_part_${i}
+      PARTITION OF ${workerTable}
+      FOR VALUES WITH (modulus 8, remainder ${i});
+    `);
+    }
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_active_messages
+    ON ${workerTable} (stream_name, reserved_at, visible_at, id)
+    WHERE reserved_at IS NULL AND expired_at IS NULL;
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_message_fetch
+    ON ${workerTable} (stream_name, visible_at, id)
+    WHERE expired_at IS NULL;
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_expired_at
+    ON ${workerTable} (expired_at);
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_stream_name_expired_at
+    ON ${workerTable} (stream_name)
+    WHERE expired_at IS NULL;
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_processed_volume
+    ON ${workerTable} (expired_at, stream_name)
+    WHERE expired_at IS NOT NULL;
+  `);
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_dead_lettered
+    ON ${workerTable} (dead_lettered_at, stream_name)
+    WHERE dead_lettered_at IS NOT NULL;
+  `);
+    // Migration: add dead_lettered_at column to existing tables
+    await client.query(`
+    DO $$ BEGIN
+      ALTER TABLE ${workerTable} ADD COLUMN IF NOT EXISTS dead_lettered_at TIMESTAMPTZ;
+    EXCEPTION WHEN duplicate_column THEN NULL;
+    END $$;
+  `);
+    // ---- Export fidelity columns and indexes ----
+    // These columns surface stream message metadata for efficient job history queries.
+    // Migration: add columns to existing tables (no-op on fresh installs)
+    for (const col of ['jid', 'aid', 'dad', 'msg_type', 'topic']) {
+        await client.query(`
+      DO $$ BEGIN
+        ALTER TABLE ${workerTable} ADD COLUMN IF NOT EXISTS ${col} TEXT NOT NULL DEFAULT '';
+      EXCEPTION WHEN duplicate_column THEN NULL;
+      END $$;
+    `);
+    }
+    // All messages for a job, ordered by time
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_jid_created
+    ON ${workerTable} (jid, created_at)
+    WHERE jid != '';
+  `);
+    // Activity-specific lookups within a job
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_jid_aid
+    ON ${workerTable} (jid, aid, created_at)
+    WHERE jid != '';
+  `);
+    // Type-filtered queries (e.g., only worker invocations + responses)
+    await client.query(`
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_jid_type
+    ON ${workerTable} (jid, msg_type, created_at)
+    WHERE jid != '';
+  `);
 }
-async function createNotificationTriggers(client, schemaName, tableName) {
-    // Create the notification function for INSERT events
+async function createNotificationTriggers(client, schemaName) {
+    const engineTable = `${schemaName}.engine_streams`;
+    const workerTable = `${schemaName}.worker_streams`;
+    // ---- ENGINE notification trigger ----
+    await client.query(`
+    CREATE OR REPLACE FUNCTION ${schemaName}.notify_new_engine_stream_message()
+    RETURNS TRIGGER AS $$
+    DECLARE
+      channel_name TEXT;
+      payload JSON;
+    BEGIN
+      IF NEW.visible_at <= NOW() THEN
+        channel_name := 'eng_' || NEW.stream_name;
+        IF length(channel_name) > 63 THEN
+          channel_name := left(channel_name, 63);
+        END IF;
+
+        payload := json_build_object(
+          'stream_name', NEW.stream_name,
+          'table_type', 'engine'
+        );
+
+        PERFORM pg_notify(channel_name, payload::text);
+      END IF;
+
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
     await client.query(`
-    CREATE OR REPLACE FUNCTION ${schemaName}.notify_new_stream_message()
+    DROP TRIGGER IF EXISTS notify_engine_stream_insert ON ${engineTable};
+    CREATE TRIGGER notify_engine_stream_insert
+      AFTER INSERT ON ${engineTable}
+      FOR EACH ROW
+      EXECUTE FUNCTION ${schemaName}.notify_new_engine_stream_message();
+  `);
+    // ---- WORKER notification trigger ----
+    await client.query(`
+    CREATE OR REPLACE FUNCTION ${schemaName}.notify_new_worker_stream_message()
     RETURNS TRIGGER AS $$
     DECLARE
       channel_name TEXT;
       payload JSON;
     BEGIN
-      -- Only notify if message is immediately visible
-      -- Messages with visibility timeout will be notified when they become visible
       IF NEW.visible_at <= NOW() THEN
-        -- Create channel name: stream_{stream_name}_{group_name}
-        -- Truncate if too long (PostgreSQL channel names limited to 63 chars)
-        channel_name := 'stream_' || NEW.stream_name || '_' || NEW.group_name;
+        channel_name := 'wrk_' || NEW.stream_name;
         IF length(channel_name) > 63 THEN
           channel_name := left(channel_name, 63);
         END IF;
-        
-        -- Create minimal payload with only required fields
+
         payload := json_build_object(
           'stream_name', NEW.stream_name,
-          'group_name', NEW.group_name
+          'table_type', 'worker'
         );
-        
-        -- Send notification
+
         PERFORM pg_notify(channel_name, payload::text);
       END IF;
-      
+
       RETURN NEW;
     END;
     $$ LANGUAGE plpgsql;
   `);
-    // Create trigger only on the main table - it will automatically apply to all partitions
     await client.query(`
-    DROP TRIGGER IF EXISTS notify_stream_insert ON ${tableName};
-    CREATE TRIGGER notify_stream_insert
-      AFTER INSERT ON ${tableName}
+    DROP TRIGGER IF EXISTS notify_worker_stream_insert ON ${workerTable};
+    CREATE TRIGGER notify_worker_stream_insert
+      AFTER INSERT ON ${workerTable}
       FOR EACH ROW
-      EXECUTE FUNCTION ${schemaName}.notify_new_stream_message();
+      EXECUTE FUNCTION ${schemaName}.notify_new_worker_stream_message();
   `);
-    // Create helper function to notify about messages with expired visibility timeouts
-    // This is called periodically by the router scout for responsive retry processing
+    // ---- Visibility timeout notification function (queries both tables) ----
     await client.query(`
     CREATE OR REPLACE FUNCTION ${schemaName}.notify_visible_messages()
     RETURNS INTEGER AS $$
@@ -227,39 +359,60 @@ async function createNotificationTriggers(client, schemaName, tableName) {
       payload JSON;
       notification_count INTEGER := 0;
     BEGIN
-      -- Find all distinct streams with messages that are now visible
-      -- Router will drain all messages when notified, so we just notify each channel once
-      FOR msg IN 
-        SELECT DISTINCT stream_name, group_name
-        FROM ${tableName}
+      -- Engine streams
+      FOR msg IN
+        SELECT DISTINCT stream_name
+        FROM ${engineTable}
+        WHERE visible_at <= NOW()
+          AND reserved_at IS NULL
+          AND expired_at IS NULL
+        LIMIT 50
+      LOOP
+        channel_name := 'eng_' || msg.stream_name;
+        IF length(channel_name) > 63 THEN
+          channel_name := left(channel_name, 63);
+        END IF;
+
+        payload := json_build_object(
+          'stream_name', msg.stream_name,
+          'table_type', 'engine'
+        );
+
+        PERFORM pg_notify(channel_name, payload::text);
+        notification_count := notification_count + 1;
+      END LOOP;
+
+      -- Worker streams
+      FOR msg IN
+        SELECT DISTINCT stream_name
+        FROM ${workerTable}
         WHERE visible_at <= NOW()
           AND reserved_at IS NULL
           AND expired_at IS NULL
-        LIMIT 100  -- Prevent overwhelming the system
+        LIMIT 50
       LOOP
-        -- Create channel name (same logic as INSERT trigger)
-        channel_name := 'stream_' || msg.stream_name || '_' || msg.group_name;
+        channel_name := 'wrk_' || msg.stream_name;
         IF length(channel_name) > 63 THEN
           channel_name := left(channel_name, 63);
         END IF;
-        
-        -- Send minimal notification with only required fields
+
         payload := json_build_object(
           'stream_name', msg.stream_name,
-          'group_name', msg.group_name
+          'table_type', 'worker'
         );
-        
+
         PERFORM pg_notify(channel_name, payload::text);
         notification_count := notification_count + 1;
       END LOOP;
-      
+
       RETURN notification_count;
     END;
     $$ LANGUAGE plpgsql;
   `);
 }
-function getNotificationChannelName(streamName, groupName) {
-    const channelName = `stream_${streamName}_${groupName}`;
+function getNotificationChannelName(streamName, isEngine) {
+    const prefix = isEngine ? 'eng_' : 'wrk_';
+    const channelName = `${prefix}${streamName}`;
     // PostgreSQL channel names are limited to 63 characters
     return channelName.length > 63 ? channelName.substring(0, 63) : channelName;
 }

package/build/services/stream/providers/postgres/lifecycle.d.ts

@@ -6,7 +6,7 @@ import { ProviderClient } from '../../../../types/provider';
  */
 export declare function createStream(streamName: string): Promise<boolean>;
 /**
- * Delete a stream or all streams.
+ * Delete a stream or all streams from a specific table.
  */
 export declare function deleteStream(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, logger: ILogger): Promise<boolean>;
 /**
@@ -14,6 +14,7 @@ export declare function deleteStream(client: PostgresClientType & ProviderClient
  */
 export declare function createConsumerGroup(streamName: string, groupName: string): Promise<boolean>;
 /**
- * Delete a consumer group (removes all messages for that group).
+ * Delete messages for a stream from a specific table.
+ * No group_name needed since engine and worker are separate tables.
  */
-export declare function deleteConsumerGroup(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, logger: ILogger): Promise<boolean>;
+export declare function deleteConsumerGroup(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, logger: ILogger): Promise<boolean>;

package/build/services/stream/providers/postgres/lifecycle.js

@@ -9,7 +9,7 @@ async function createStream(streamName) {
 }
 exports.createStream = createStream;
 /**
- * Delete a stream or all streams.
+ * Delete a stream or all streams from a specific table.
  */
 async function deleteStream(client, tableName, streamName, logger) {
     try {
@@ -39,15 +39,16 @@ async function createConsumerGroup(streamName, groupName) {
 }
 exports.createConsumerGroup = createConsumerGroup;
 /**
- * Delete a consumer group (removes all messages for that group).
+ * Delete messages for a stream from a specific table.
+ * No group_name needed since engine and worker are separate tables.
  */
-async function deleteConsumerGroup(client, tableName, streamName, groupName, logger) {
+async function deleteConsumerGroup(client, tableName, streamName, logger) {
     try {
-        await client.query(`DELETE FROM ${tableName} WHERE stream_name = $1 AND group_name = $2`, [streamName, groupName]);
+        await client.query(`DELETE FROM ${tableName} WHERE stream_name = $1`, [streamName]);
         return true;
     }
     catch (error) {
-        logger.error(`postgres-stream-delete-group-error-${streamName}.${groupName}`, { error });
+        logger.error(`postgres-stream-delete-group-error-${streamName}`, { error });
         throw error;
     }
 }

package/build/services/stream/providers/postgres/messages.d.ts

@@ -8,20 +8,22 @@ import { ProviderClient, ProviderTransaction } from '../../../../types/provider'
  * When a transaction is provided, the SQL is added to the transaction
  * and executed atomically with other operations.
  */
-export declare function publishMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, messages: string[], options: PublishMessageConfig | undefined, logger: ILogger): Promise<string[] | ProviderTransaction>;
+export declare function publishMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, isEngine: boolean, messages: string[], options: PublishMessageConfig | undefined, logger: ILogger): Promise<string[] | ProviderTransaction>;
 /**
  * Build SQL for publishing messages with retry policies and visibility delays.
- * Optimizes the INSERT statement based on whether retry config is present.
+ * Routes to engine_streams or worker_streams based on isEngine flag.
+ * Worker messages include a workflow_name column extracted from metadata.wfn.
  */
-export declare function buildPublishSQL(tableName: string, streamName: string, messages: string[], options?: PublishMessageConfig): {
+export declare function buildPublishSQL(tableName: string, streamName: string, isEngine: boolean, messages: string[], options?: PublishMessageConfig): {
     sql: string;
     params: any[];
 };
 /**
  * Fetch messages from the stream with optional exponential backoff.
  * Uses SKIP LOCKED for high-concurrency consumption.
+ * No group_name filter needed - the table itself determines engine vs worker.
  */
-export declare function fetchMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, consumerName: string, options: {
+export declare function fetchMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, isEngine: boolean, consumerName: string, options: {
     batchSize?: number;
     blockTimeout?: number;
     autoAck?: boolean;
@@ -37,12 +39,18 @@ export declare function fetchMessages(client: PostgresClientType & ProviderClien
 export declare function acknowledgeMessages(messageIds: string[]): Promise<number>;
 /**
  * Delete messages by soft-deleting them (setting expired_at).
+ * No group_name needed - stream_name + table is sufficient.
  */
-export declare function deleteMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, messageIds: string[], logger: ILogger): Promise<number>;
+export declare function deleteMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, messageIds: string[], logger: ILogger): Promise<number>;
 /**
  * Acknowledge and delete messages in one operation.
  */
-export declare function ackAndDelete(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, messageIds: string[], logger: ILogger): Promise<number>;
+export declare function ackAndDelete(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, messageIds: string[], logger: ILogger): Promise<number>;
+/**
+ * Move messages to the dead-letter state by setting dead_lettered_at
+ * and expired_at. The message payload is preserved for inspection.
+ */
+export declare function deadLetterMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, messageIds: string[], logger: ILogger): Promise<number>;
 /**
  * Retry messages (placeholder for future implementation).
  */