@hotmeshio/hotmesh 0.10.2 → 0.11.0

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

@@ -5,112 +5,20 @@ import { KeyStoreParams, StringAnyType } from '../../../../types';
 import { PostgresClientType } from '../../../../types/postgres';
 import { PublishMessageConfig, StreamConfig, StreamMessage, StreamStats } from '../../../../types/stream';
 import { ProviderClient, ProviderTransaction } from '../../../../types/provider';
+/**
+ * Resolved stream target containing the table name and simplified stream name.
+ */
+export interface StreamTarget {
+    tableName: string;
+    streamName: string;
+    isEngine: boolean;
+}
 /**
  * PostgreSQL Stream Service
  *
- * High-performance stream message provider using PostgreSQL with LISTEN/NOTIFY.
- *
- * ## Module Organization
- *
- * This service is organized into focused modules following KISS principles:
- * - `postgres.ts` (this file) - Main orchestrator and service interface
- * - `kvtables.ts` - Schema deployment and table management
- * - `messages.ts` - Message CRUD operations (publish, fetch, ack, delete)
- * - `stats.ts` - Statistics and query operations
- * - `scout.ts` - Scout role coordination for polling visible messages
- * - `notifications.ts` - LISTEN/NOTIFY notification system with static state management
- * - `lifecycle.ts` - Stream and consumer group lifecycle operations
- *
- * ## Lifecycle
- *
- * ### Initialization (`init`)
- * 1. Deploy PostgreSQL schema (tables, indexes, triggers, functions)
- * 2. Create ScoutManager for coordinating visibility timeout polling
- * 3. Create NotificationManager for LISTEN/NOTIFY event handling
- * 4. Set up notification handler (once per client, shared across instances)
- * 5. Start fallback poller (backup for missed notifications)
- * 6. Start router scout poller (for visibility timeout processing)
- *
- * ### Shutdown (`cleanup`)
- * 1. Stop router scout polling loop
- * 2. Release scout role if held
- * 3. Stop notification consumers for this instance
- * 4. UNLISTEN from channels when last instance disconnects
- * 5. Clean up fallback poller when last instance disconnects
- * 6. Remove notification handlers when last instance disconnects
- *
- * ## Notification System (LISTEN/NOTIFY)
- *
- * ### Real-time Message Delivery
- * - PostgreSQL trigger on INSERT sends NOTIFY when messages are immediately visible
- * - Messages with visibility timeout are NOT notified on INSERT
- * - Multiple service instances share the same client and notification handlers
- * - Static state ensures only ONE LISTEN per channel across all instances
- *
- * ### Components
- * - **Notification Handler**: Listens for PostgreSQL NOTIFY events
- * - **Fallback Poller**: Polls every 30s (default) for missed messages
- * - **Router Scout**: Active role-holder polls visible messages frequently (~100ms)
- * - **Visibility Function**: `notify_visible_messages()` checks for expired timeouts
- *
- * ## Scout Role (Visibility Timeout Processing)
- *
- * When messages are published with visibility timeouts (delays), they need to be
- * processed when they become visible. The scout role ensures this happens efficiently:
- *
- * 1. **Role Acquisition**: One instance per app acquires "router" scout role
- * 2. **Fast Polling**: Scout polls `notify_visible_messages()` every ~100ms
- * 3. **Notification**: Function triggers NOTIFY for streams with visible messages
- * 4. **Role Rotation**: Role expires after interval, another instance can claim it
- * 5. **Fallback**: Non-scouts sleep longer, try to acquire role periodically
- *
- * ## Message Flow
- *
- * ### Publishing
- * 1. Messages inserted into partitioned table
- * 2. If immediately visible → INSERT trigger sends NOTIFY
- * 3. If visibility timeout → no NOTIFY (scout will handle when visible)
- *
- * ### Consuming (Event-Driven)
- * 1. Consumer calls `consumeMessages` with notification callback
- * 2. Service executes LISTEN on channel `stream_{name}_{group}`
- * 3. On NOTIFY → fetch messages → invoke callback
- * 4. Initial fetch done immediately (catch any queued messages)
- *
- * ### Consuming (Polling)
- * 1. Consumer calls `consumeMessages` without callback
- * 2. Service directly queries and reserves messages
- * 3. Returns messages synchronously
- *
- * ## Reliability Guarantees
- *
- * - **Notification Fallback**: Poller catches missed notifications every 30s
- * - **Visibility Scout**: Ensures delayed messages are processed when visible
- * - **Graceful Degradation**: Falls back to polling if LISTEN fails
- * - **Shared State**: Multiple instances coordinate via static maps
- * - **Race Condition Safe**: SKIP LOCKED prevents message duplication
- *
- * @example
- * ```typescript
- * // Initialize service
- * const service = new PostgresStreamService(client, storeClient, config);
- * await service.init('namespace', 'appId', logger);
- *
- * // Event-driven consumption (recommended)
- * await service.consumeMessages('stream', 'group', 'consumer', {
- *   notificationCallback: (messages) => {
- *     // Process messages in real-time
- *   }
- * });
- *
- * // Polling consumption
- * const messages = await service.consumeMessages('stream', 'group', 'consumer', {
- *   batchSize: 10
- * });
- *
- * // Cleanup on shutdown
- * await service.cleanup();
- * ```
+ * Uses separate `engine_streams` and `worker_streams` tables for
+ * security isolation and independent scaling. The `worker_streams`
+ * table includes a `workflow_name` column for routing.
  */
 declare class PostgresStreamService extends StreamService<PostgresClientType & ProviderClient, any> {
     namespace: string;
@@ -124,9 +32,15 @@ declare class PostgresStreamService extends StreamService<PostgresClientType & P
     private checkForMissedMessages;
     private fetchAndDeliverMessages;
     private getConsumerKey;
+    /**
+     * Resolves a conjoined stream key (e.g., `hmsh:appId:x:topic`) into
+     * the correct table name and simplified stream name.
+     */
+    resolveStreamTarget(streamKey: string): StreamTarget;
     mintKey(type: KeyType, params: KeyStoreParams): string;
     transact(): ProviderTransaction;
-    getTableName(): string;
+    getEngineTableName(): string;
+    getWorkerTableName(): string;
     safeName(appId: string): string;
     createStream(streamName: string): Promise<boolean>;
     deleteStream(streamName: string): Promise<boolean>;
@@ -134,20 +48,8 @@ declare class PostgresStreamService extends StreamService<PostgresClientType & P
     deleteConsumerGroup(streamName: string, groupName: string): Promise<boolean>;
     /**
      * `publishMessages` can be roped into a transaction by the `store`
-     * service. If so, it will add the SQL and params to the
-     * transaction. [Process Overview]: The engine keeps a reference
-     * to the `store` and `stream` providers; it asks the `store` to
-     * create a transaction and then starts adding store commands to the
-     * transaction. The engine then calls the router to publish a
-     * message using the `stream` provider (which the router keeps
-     * a reference to), and provides the transaction object.
-     * The `stream` provider then calls this method to generate
-     * the SQL and params for the transaction (but, of course, the sql
-     * is not executed until the engine calls the `exec` method on
-     * the transaction object provided by `store`).
-     *
-     * NOTE: this strategy keeps `stream` and `store` operations separate but
-     * allows calls to the stream to be roped into a single SQL transaction.
+     * service. The `stream` provider generates SQL and params that are
+     * added to the transaction for atomic execution.
      */
     publishMessages(streamName: string, messages: string[], options?: PublishMessageConfig): Promise<string[] | ProviderTransaction>;
     _publishMessages(streamName: string, messages: string[], options?: PublishMessageConfig): {

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

@@ -35,109 +35,9 @@ const Lifecycle = __importStar(require("./lifecycle"));
 /**
  * PostgreSQL Stream Service
  *
- * High-performance stream message provider using PostgreSQL with LISTEN/NOTIFY.
- *
- * ## Module Organization
- *
- * This service is organized into focused modules following KISS principles:
- * - `postgres.ts` (this file) - Main orchestrator and service interface
- * - `kvtables.ts` - Schema deployment and table management
- * - `messages.ts` - Message CRUD operations (publish, fetch, ack, delete)
- * - `stats.ts` - Statistics and query operations
- * - `scout.ts` - Scout role coordination for polling visible messages
- * - `notifications.ts` - LISTEN/NOTIFY notification system with static state management
- * - `lifecycle.ts` - Stream and consumer group lifecycle operations
- *
- * ## Lifecycle
- *
- * ### Initialization (`init`)
- * 1. Deploy PostgreSQL schema (tables, indexes, triggers, functions)
- * 2. Create ScoutManager for coordinating visibility timeout polling
- * 3. Create NotificationManager for LISTEN/NOTIFY event handling
- * 4. Set up notification handler (once per client, shared across instances)
- * 5. Start fallback poller (backup for missed notifications)
- * 6. Start router scout poller (for visibility timeout processing)
- *
- * ### Shutdown (`cleanup`)
- * 1. Stop router scout polling loop
- * 2. Release scout role if held
- * 3. Stop notification consumers for this instance
- * 4. UNLISTEN from channels when last instance disconnects
- * 5. Clean up fallback poller when last instance disconnects
- * 6. Remove notification handlers when last instance disconnects
- *
- * ## Notification System (LISTEN/NOTIFY)
- *
- * ### Real-time Message Delivery
- * - PostgreSQL trigger on INSERT sends NOTIFY when messages are immediately visible
- * - Messages with visibility timeout are NOT notified on INSERT
- * - Multiple service instances share the same client and notification handlers
- * - Static state ensures only ONE LISTEN per channel across all instances
- *
- * ### Components
- * - **Notification Handler**: Listens for PostgreSQL NOTIFY events
- * - **Fallback Poller**: Polls every 30s (default) for missed messages
- * - **Router Scout**: Active role-holder polls visible messages frequently (~100ms)
- * - **Visibility Function**: `notify_visible_messages()` checks for expired timeouts
- *
- * ## Scout Role (Visibility Timeout Processing)
- *
- * When messages are published with visibility timeouts (delays), they need to be
- * processed when they become visible. The scout role ensures this happens efficiently:
- *
- * 1. **Role Acquisition**: One instance per app acquires "router" scout role
- * 2. **Fast Polling**: Scout polls `notify_visible_messages()` every ~100ms
- * 3. **Notification**: Function triggers NOTIFY for streams with visible messages
- * 4. **Role Rotation**: Role expires after interval, another instance can claim it
- * 5. **Fallback**: Non-scouts sleep longer, try to acquire role periodically
- *
- * ## Message Flow
- *
- * ### Publishing
- * 1. Messages inserted into partitioned table
- * 2. If immediately visible → INSERT trigger sends NOTIFY
- * 3. If visibility timeout → no NOTIFY (scout will handle when visible)
- *
- * ### Consuming (Event-Driven)
- * 1. Consumer calls `consumeMessages` with notification callback
- * 2. Service executes LISTEN on channel `stream_{name}_{group}`
- * 3. On NOTIFY → fetch messages → invoke callback
- * 4. Initial fetch done immediately (catch any queued messages)
- *
- * ### Consuming (Polling)
- * 1. Consumer calls `consumeMessages` without callback
- * 2. Service directly queries and reserves messages
- * 3. Returns messages synchronously
- *
- * ## Reliability Guarantees
- *
- * - **Notification Fallback**: Poller catches missed notifications every 30s
- * - **Visibility Scout**: Ensures delayed messages are processed when visible
- * - **Graceful Degradation**: Falls back to polling if LISTEN fails
- * - **Shared State**: Multiple instances coordinate via static maps
- * - **Race Condition Safe**: SKIP LOCKED prevents message duplication
- *
- * @example
- * ```typescript
- * // Initialize service
- * const service = new PostgresStreamService(client, storeClient, config);
- * await service.init('namespace', 'appId', logger);
- *
- * // Event-driven consumption (recommended)
- * await service.consumeMessages('stream', 'group', 'consumer', {
- *   notificationCallback: (messages) => {
- *     // Process messages in real-time
- *   }
- * });
- *
- * // Polling consumption
- * const messages = await service.consumeMessages('stream', 'group', 'consumer', {
- *   batchSize: 10
- * });
- *
- * // Cleanup on shutdown
- * await service.cleanup();
- * ```
+ * Uses separate `engine_streams` and `worker_streams` tables for
+ * security isolation and independent scaling. The `worker_streams`
+ * table includes a `workflow_name` column for routing.
  */
 class PostgresStreamService extends index_1.StreamService {
     constructor(streamClient, storeClient, config = {}) {
@@ -149,9 +49,9 @@ class PostgresStreamService extends index_1.StreamService {
         this.logger = logger;
         await (0, kvtables_1.deploySchema)(this.streamClient, this.appId, this.logger);
         // Initialize scout manager
-        this.scoutManager = new scout_1.ScoutManager(this.streamClient, this.appId, this.getTableName.bind(this), this.mintKey.bind(this), this.logger);
+        this.scoutManager = new scout_1.ScoutManager(this.streamClient, this.appId, this.getEngineTableName.bind(this), this.mintKey.bind(this), this.logger);
         // Initialize notification manager
-        this.notificationManager = new notifications_1.NotificationManager(this.streamClient, this.getTableName.bind(this), () => (0, notifications_1.getFallbackInterval)(this.config), this.logger);
+        this.notificationManager = new notifications_1.NotificationManager(this.streamClient, this.getEngineTableName.bind(this), () => (0, notifications_1.getFallbackInterval)(this.config), this.logger);
         // Set up notification handler if supported
         if (this.streamClient.on && this.isNotificationsEnabled()) {
             this.notificationManager.setupClientNotificationHandler(this);
@@ -185,6 +85,28 @@ class PostgresStreamService extends index_1.StreamService {
     getConsumerKey(streamName, groupName) {
         return `${streamName}:${groupName}`;
     }
+    /**
+     * Resolves a conjoined stream key (e.g., `hmsh:appId:x:topic`) into
+     * the correct table name and simplified stream name.
+     */
+    resolveStreamTarget(streamKey) {
+        const isEngine = streamKey.endsWith(':');
+        if (isEngine) {
+            return {
+                tableName: this.getEngineTableName(),
+                streamName: this.appId,
+                isEngine: true,
+            };
+        }
+        // Extract the bare topic from hmsh:appId:x:topicName
+        const parts = streamKey.split(':');
+        const topic = parts[parts.length - 1];
+        return {
+            tableName: this.getWorkerTableName(),
+            streamName: topic,
+            isEngine: false,
+        };
+    }
     mintKey(type, params) {
         if (!this.namespace)
             throw new Error('namespace not set');
@@ -196,8 +118,11 @@ class PostgresStreamService extends index_1.StreamService {
     transact() {
         return {};
     }
-    getTableName() {
-        return `${this.safeName(this.appId)}.streams`;
+    getEngineTableName() {
+        return `${this.safeName(this.appId)}.engine_streams`;
+    }
+    getWorkerTableName() {
+        return `${this.safeName(this.appId)}.worker_streams`;
     }
     safeName(appId) {
         return appId.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -206,36 +131,33 @@ class PostgresStreamService extends index_1.StreamService {
         return Lifecycle.createStream(streamName);
     }
     async deleteStream(streamName) {
-        return Lifecycle.deleteStream(this.streamClient, this.getTableName(), streamName, this.logger);
+        if (streamName === '*') {
+            // Delete from both tables
+            await Lifecycle.deleteStream(this.streamClient, this.getEngineTableName(), '*', this.logger);
+            return Lifecycle.deleteStream(this.streamClient, this.getWorkerTableName(), '*', this.logger);
+        }
+        const target = this.resolveStreamTarget(streamName);
+        return Lifecycle.deleteStream(this.streamClient, target.tableName, target.streamName, this.logger);
     }
     async createConsumerGroup(streamName, groupName) {
         return Lifecycle.createConsumerGroup(streamName, groupName);
     }
     async deleteConsumerGroup(streamName, groupName) {
-        return Lifecycle.deleteConsumerGroup(this.streamClient, this.getTableName(), streamName, groupName, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Lifecycle.deleteConsumerGroup(this.streamClient, target.tableName, target.streamName, this.logger);
     }
     /**
      * `publishMessages` can be roped into a transaction by the `store`
-     * service. If so, it will add the SQL and params to the
-     * transaction. [Process Overview]: The engine keeps a reference
-     * to the `store` and `stream` providers; it asks the `store` to
-     * create a transaction and then starts adding store commands to the
-     * transaction. The engine then calls the router to publish a
-     * message using the `stream` provider (which the router keeps
-     * a reference to), and provides the transaction object.
-     * The `stream` provider then calls this method to generate
-     * the SQL and params for the transaction (but, of course, the sql
-     * is not executed until the engine calls the `exec` method on
-     * the transaction object provided by `store`).
-     *
-     * NOTE: this strategy keeps `stream` and `store` operations separate but
-     * allows calls to the stream to be roped into a single SQL transaction.
+     * service. The `stream` provider generates SQL and params that are
+     * added to the transaction for atomic execution.
      */
     async publishMessages(streamName, messages, options) {
-        return Messages.publishMessages(this.streamClient, this.getTableName(), streamName, messages, options, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Messages.publishMessages(this.streamClient, target.tableName, target.streamName, target.isEngine, messages, options, this.logger);
     }
     _publishMessages(streamName, messages, options) {
-        return Messages.buildPublishSQL(this.getTableName(), streamName, messages, options);
+        const target = this.resolveStreamTarget(streamName);
+        return Messages.buildPublishSQL(target.tableName, target.streamName, target.isEngine, messages, options);
     }
     async consumeMessages(streamName, groupName, consumerName, options) {
         // If notification callback is provided and notifications are enabled, set up listener
@@ -248,9 +170,7 @@ class PostgresStreamService extends index_1.StreamService {
     shouldUseNotifications(options) {
         const globalEnabled = this.isNotificationsEnabled();
         const optionEnabled = options?.enableNotifications;
-        // If option is explicitly set, use that; otherwise use global setting
         const enabled = optionEnabled !== undefined ? optionEnabled : globalEnabled;
-        // Also check if client supports notifications
         return enabled && this.streamClient.on !== undefined;
     }
     async setupNotificationConsumer(streamName, groupName, consumerName, callback, options) {
@@ -271,7 +191,6 @@ class PostgresStreamService extends index_1.StreamService {
                         messageCount: initialMessages.length,
                         fetchDuration: Date.now() - fetchStart,
                     });
-                    // If we got messages, call the callback
                     if (initialMessages.length > 0) {
                         callback(initialMessages);
                     }
@@ -284,11 +203,9 @@ class PostgresStreamService extends index_1.StreamService {
                     });
                 }
             });
-            // Return empty array immediately to avoid blocking
             return [];
         }
         catch (error) {
-            // Fall back to polling if setup fails
             return this.fetchMessages(streamName, groupName, consumerName, options);
         }
     }
@@ -296,42 +213,68 @@ class PostgresStreamService extends index_1.StreamService {
         await this.notificationManager.stopNotificationConsumer(this, streamName, groupName);
     }
     async fetchMessages(streamName, groupName, consumerName, options) {
-        return Messages.fetchMessages(this.streamClient, this.getTableName(), streamName, groupName, consumerName, options || {}, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Messages.fetchMessages(this.streamClient, target.tableName, target.streamName, target.isEngine, consumerName, options || {}, this.logger);
     }
     async ackAndDelete(streamName, groupName, messageIds) {
-        return Messages.ackAndDelete(this.streamClient, this.getTableName(), streamName, groupName, messageIds, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Messages.ackAndDelete(this.streamClient, target.tableName, target.streamName, messageIds, this.logger);
     }
     async acknowledgeMessages(streamName, groupName, messageIds, options) {
         return Messages.acknowledgeMessages(messageIds);
     }
     async deleteMessages(streamName, groupName, messageIds, options) {
-        return Messages.deleteMessages(this.streamClient, this.getTableName(), streamName, groupName, messageIds, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Messages.deleteMessages(this.streamClient, target.tableName, target.streamName, messageIds, this.logger);
     }
     async retryMessages(streamName, groupName, options) {
         return Messages.retryMessages(streamName, groupName, options);
     }
     async getStreamStats(streamName) {
-        return Stats.getStreamStats(this.streamClient, this.getTableName(), streamName, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Stats.getStreamStats(this.streamClient, target.tableName, target.streamName, this.logger);
     }
     async getStreamDepth(streamName) {
-        return Stats.getStreamDepth(this.streamClient, this.getTableName(), streamName, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Stats.getStreamDepth(this.streamClient, target.tableName, target.streamName, this.logger);
     }
     async getStreamDepths(streamNames) {
-        return Stats.getStreamDepths(this.streamClient, this.getTableName(), streamNames, this.logger);
+        // Partition stream names by table type and query each table separately
+        const engineStreams = [];
+        const workerStreams = [];
+        const streamNameMap = new Map(); // resolvedName -> originalKey
+        for (const s of streamNames) {
+            const target = this.resolveStreamTarget(s.stream);
+            streamNameMap.set(target.streamName, s.stream);
+            if (target.isEngine) {
+                engineStreams.push({ stream: target.streamName });
+            }
+            else {
+                workerStreams.push({ stream: target.streamName });
+            }
+        }
+        const results = [];
+        if (engineStreams.length > 0) {
+            const engineResults = await Stats.getStreamDepths(this.streamClient, this.getEngineTableName(), engineStreams, this.logger);
+            results.push(...engineResults);
+        }
+        if (workerStreams.length > 0) {
+            const workerResults = await Stats.getStreamDepths(this.streamClient, this.getWorkerTableName(), workerStreams, this.logger);
+            results.push(...workerResults);
+        }
+        return results;
     }
     async trimStream(streamName, options) {
-        return Stats.trimStream(this.streamClient, this.getTableName(), streamName, options, this.logger);
+        const target = this.resolveStreamTarget(streamName);
+        return Stats.trimStream(this.streamClient, target.tableName, target.streamName, options, this.logger);
     }
     getProviderSpecificFeatures() {
         return Stats.getProviderSpecificFeatures(this.config);
     }
-    // Cleanup method to be called when shutting down
     async cleanup() {
-        // Stop router scout polling loop
         if (this.scoutManager) {
             await this.scoutManager.stopRouterScoutPoller();
         }
-        // Clean up notification consumers
         if (this.notificationManager) {
             await this.notificationManager.cleanup(this);
         }

package/build/services/stream/registry.d.ts

@@ -0,0 +1,62 @@
+import { ILogger } from '../logger';
+import { StreamService } from './index';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { StreamData, StreamDataResponse } from '../../types/stream';
+import { KeyType } from '../../modules/key';
+type WorkerCallback = (data: StreamData) => Promise<StreamDataResponse | void>;
+/**
+ * Process-wide singleton registry that manages one consumer per task queue (workers)
+ * and one per appId (engines). Instead of N consumers each polling independently,
+ * one consumer fetches batches from the stream and dispatches to registered callbacks
+ * based on the `workflow_name` column (workers) or round-robin (engines).
+ */
+declare class StreamConsumerRegistry {
+    private static workerConsumers;
+    private static engineConsumers;
+    /**
+     * Register a worker callback for a (taskQueue, workflowName) pair.
+     * If no consumer exists for this taskQueue, a singleton Router is created.
+     */
+    static registerWorker(namespace: string, appId: string, guid: string, taskQueue: string, workflowName: string, callback: WorkerCallback, stream: StreamService<ProviderClient, ProviderTransaction>, store: {
+        mintKey: (type: KeyType, params: any) => string;
+        getThrottleRate: (topic?: string) => Promise<number>;
+    }, logger: ILogger, config?: {
+        reclaimDelay?: number;
+        reclaimCount?: number;
+        retryPolicy?: any;
+    }): Promise<void>;
+    /**
+     * Register an engine callback for an appId.
+     * If no consumer exists for this appId, a singleton Router is created.
+     */
+    static registerEngine(namespace: string, appId: string, guid: string, callback: WorkerCallback, stream: StreamService<ProviderClient, ProviderTransaction>, store: {
+        mintKey: (type: KeyType, params: any) => string;
+        getThrottleRate: (topic?: string) => Promise<number>;
+    }, logger: ILogger, config?: {
+        reclaimDelay?: number;
+        reclaimCount?: number;
+    }): Promise<void>;
+    /**
+     * Creates a dispatch callback for worker consumers.
+     * Routes messages to the registered callback based on metadata.wfn (workflow_name).
+     */
+    private static createWorkerDispatcher;
+    /**
+     * Creates a dispatch callback for engine consumers.
+     * Engines are generic processors — the first registered callback handles the message.
+     */
+    private static createEngineDispatcher;
+    /**
+     * Unregister a worker callback.
+     */
+    static unregisterWorker(namespace: string, appId: string, taskQueue: string, workflowName: string): Promise<void>;
+    /**
+     * Unregister an engine callback.
+     */
+    static unregisterEngine(namespace: string, appId: string, callback: WorkerCallback): Promise<void>;
+    /**
+     * Stop all consumers and clear the registry.
+     */
+    static shutdown(): Promise<void>;
+}
+export { StreamConsumerRegistry };