@hotmeshio/hotmesh 0.6.0 → 0.7.0

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -23,11 +23,13 @@
         "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/* --detectOpenHandles --forceExit --verbose",
+        "test:connect:ioredis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:postgres": "NODE_ENV=test jest ./tests/unit/services/connector/providers/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:connect:redis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:nats": "NODE_ENV=test jest ./tests/unit/services/connector/providers/nats.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:basic": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/basic/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:goodbye": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/goodbye/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:interceptor": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/interceptor/postgres.test.ts --detectOpenHandles --forceExit --verbose",
@@ -35,36 +37,44 @@
         "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug NODE_ENV=test jest ./tests/memflow/helloworld/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:nested": "NODE_ENV=test jest ./tests/memflow/nested/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:pipeline": "NODE_ENV=test jest ./tests/memflow/pipeline/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:retry": "NODE_ENV=test jest ./tests/memflow/retry/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:retrypolicy": "NODE_ENV=test jest ./tests/memflow/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:sleep": "NODE_ENV=test jest ./tests/memflow/sleep/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:signal": "NODE_ENV=test jest ./tests/memflow/signal/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:functional": "NODE_ENV=test jest ./tests/functional/* --detectOpenHandles --forceExit --verbose",
         "test:emit": "NODE_ENV=test jest ./tests/functional/emit/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:pending": "NODE_ENV=test jest ./tests/functional/pending/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:hmsh": "NODE_ENV=test jest ./tests/functional/*.test.ts --detectOpenHandles --verbose --forceExit",
-        "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:hook": "NODE_ENV=test jest ./tests/functional/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:parallel": "NODE_ENV=test jest ./tests/functional/parallel/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:reporter": "NODE_ENV=test jest ./tests/unit/services/reporter/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:retry": "NODE_ENV=test jest ./tests/functional/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:retrypolicy": "NODE_ENV=test jest ./tests/functional/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:signal": "NODE_ENV=test jest ./tests/functional/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:status": "NODE_ENV=test jest ./tests/functional/status/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:providers": "NODE_ENV=test jest ./tests/functional/*/providers/*/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:store:ioredis": "NODE_ENV=test jest ./tests/functional/store/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:store:redis": "NODE_ENV=test jest ./tests/functional/store/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:store:postgres": "NODE_ENV=test jest ./tests/functional/store/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:stream:ioredis": "NODE_ENV=test jest ./tests/functional/stream/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:stream:redis": "NODE_ENV=test jest ./tests/functional/stream/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:stream:postgres": "NODE_ENV=test jest ./tests/functional/stream/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:stream:nats": "NODE_ENV=test jest ./tests/functional/stream/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:sub:ioredis": "NODE_ENV=test jest ./tests/functional/sub/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:sub:redis": "NODE_ENV=test jest ./tests/functional/sub/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:postgres": "NODE_ENV=test jest ./tests/functional/sub/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
         "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
@@ -106,11 +116,13 @@
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-prettier": "^5.1.3",
+        "ioredis": "^5.3.2",
         "javascript-obfuscator": "^0.6.2",
         "jest": "^29.5.0",
         "nats": "^2.28.0",
         "openai": "^5.9.0",
         "pg": "^8.10.0",
+        "redis": "^4.6.13",
         "rimraf": "^4.4.1",
         "terser": "^5.37.0",
         "ts-jest": "^29.0.5",
@@ -120,7 +132,9 @@
         "typescript": "^5.0.4"
     },
     "peerDependencies": {
+        "ioredis": "^4.0.0 || ^5.0.0",
         "nats": "^2.0.0",
-        "pg": "^8.0.0"
+        "pg": "^8.0.0",
+        "redis": "^4.0.0"
     }
 }

package/build/services/connector/factory.d.ts

@@ -3,7 +3,7 @@ import { ProviderConfig, ProviderNativeClient } from '../../types/provider';
 export declare class ConnectorService {
     static disconnectAll(): Promise<void>;
     /**
-     * Connect to a provider (postgres, nats) and return the native
+     * Connect to a provider (redis, nats, postgres) and return the native
      * client. Connections are handled by the engine and worker routers at
      * initialization, but the factory method provided here is useful
      * for testing provider configurations.

package/build/services/connector/factory.js

@@ -2,15 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorService = void 0;
 const utils_1 = require("../../modules/utils");
+const ioredis_1 = require("./providers/ioredis");
 const nats_1 = require("./providers/nats");
 const postgres_1 = require("./providers/postgres");
+const redis_1 = require("./providers/redis");
 class ConnectorService {
     static async disconnectAll() {
+        await redis_1.RedisConnection.disconnectAll();
+        await ioredis_1.RedisConnection.disconnectAll();
         await postgres_1.PostgresConnection.disconnectAll();
         await nats_1.NatsConnection.disconnectAll();
     }
     /**
-     * Connect to a provider (postgres, nats) and return the native
+     * Connect to a provider (redis, nats, postgres) and return the native
      * client. Connections are handled by the engine and worker routers at
      * initialization, but the factory method provided here is useful
      * for testing provider configurations.
@@ -69,10 +73,20 @@ class ConnectorService {
         const providerClass = ProviderConfig.class;
         const options = ProviderConfig.options;
         const providerName = ProviderConfig.provider || (0, utils_1.identifyProvider)(providerClass); //e.g. 'postgres.poolclient'
+        if (!providerName) {
+            throw new Error(`Unable to identify provider type. Please explicitly set the 'provider' field in your connection config. ` +
+                `Received class: ${providerClass?.constructor?.name || 'unknown'}`);
+        }
         const providerType = providerName.split('.')[0]; //e.g. 'postgres'
         let clientInstance;
         const id = (0, utils_1.guid)();
         switch (providerType) {
+            case 'redis':
+                clientInstance = await redis_1.RedisConnection.connect(id, providerClass, options, { provider: providerName });
+                break;
+            case 'ioredis':
+                clientInstance = await ioredis_1.RedisConnection.connect(id, providerClass, options, { provider: providerName });
+                break;
             case 'nats':
                 clientInstance = await nats_1.NatsConnection.connect(id, providerClass, options, { provider: providerName });
                 break;

package/build/services/connector/providers/ioredis.d.ts

@@ -0,0 +1,9 @@
+import { AbstractConnection } from '..';
+import { IORedisClientOptions as RedisClientOptions, IORedisClassType as RedisClassType, IORedisClientType as RedisClientType } from '../../../types/redis';
+declare class RedisConnection extends AbstractConnection<RedisClassType, RedisClientOptions> {
+    defaultOptions: RedisClientOptions;
+    createConnection(Redis: RedisClassType, options: RedisClientOptions): Promise<RedisClientType>;
+    getClient(): RedisClientType;
+    closeConnection(connection: RedisClientType): Promise<void>;
+}
+export { RedisConnection };

package/build/services/connector/providers/ioredis.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisConnection = void 0;
+const __1 = require("..");
+class RedisConnection extends __1.AbstractConnection {
+    constructor() {
+        super(...arguments);
+        this.defaultOptions = {
+            host: 'localhost',
+            port: 6379,
+        };
+    }
+    async createConnection(Redis, options) {
+        return new Redis(options);
+    }
+    getClient() {
+        if (!this.connection) {
+            throw new Error('Redis client is not connected');
+        }
+        return this.connection;
+    }
+    async closeConnection(connection) {
+        await connection.quit();
+    }
+}
+exports.RedisConnection = RedisConnection;

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

@@ -121,7 +121,10 @@ class PostgresConnection extends __1.AbstractConnection {
             this.disconnecting = true;
             await this.disconnectPoolClients();
             await this.disconnectConnections();
+            // Clear taskQueue connections cache when disconnecting all
             this.taskQueueConnections.clear();
+            // Clear the base class instances cache to allow reconnection with same IDs
+            this.instances.clear();
             this.disconnecting = false;
         }
     }

package/build/services/connector/providers/redis.d.ts

@@ -0,0 +1,9 @@
+import { AbstractConnection } from '..';
+import { RedisRedisClassType as RedisClassType, RedisRedisClientType as RedisClientType, RedisRedisClientOptions as RedisClientOptions } from '../../../types/redis';
+declare class RedisConnection extends AbstractConnection<RedisClassType, RedisClientOptions> {
+    defaultOptions: RedisClientOptions;
+    createConnection(Redis: Partial<RedisClassType>, options: RedisClientOptions): Promise<Partial<RedisClientType>>;
+    getClient(): RedisClientType;
+    closeConnection(connection: any): Promise<void>;
+}
+export { RedisConnection, RedisClientType };

package/build/services/connector/providers/redis.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisConnection = void 0;
+const __1 = require("..");
+class RedisConnection extends __1.AbstractConnection {
+    constructor() {
+        super(...arguments);
+        this.defaultOptions = {
+            socket: {
+                host: 'localhost',
+                port: 6379,
+                tls: false,
+            },
+        };
+    }
+    async createConnection(Redis, options) {
+        return new Promise((resolve, reject) => {
+            const client = Redis.createClient(options);
+            client.on('error', (error) => {
+                reject(error);
+            });
+            client.on('ready', () => {
+                resolve(client);
+            });
+            client.connect();
+        });
+    }
+    getClient() {
+        if (!this.connection) {
+            throw new Error('Redis client is not connected');
+        }
+        return this.connection;
+    }
+    async closeConnection(connection) {
+        await connection.quit();
+    }
+}
+exports.RedisConnection = RedisConnection;

package/build/services/hotmesh/index.d.ts

@@ -10,30 +10,19 @@ import { StringAnyType, StringStringType } from '../../types/serializer';
 import { JobStatsInput, GetStatsOptions, IdsResponse, StatsResponse } from '../../types/stats';
 import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../types/stream';
 /**
- * HotMesh is a distributed, reentrant process orchestration engine that transforms
- * Postgres into a resilient service mesh capable of running
+ * HotMesh transforms Postgres into a durable workflow orchestration engine capable of running
  * fault-tolerant workflows across multiple services and systems.
  *
- * ## Core Concepts
- *
- * **Distributed Quorum Architecture**: HotMesh operates as a distributed quorum
- * where multiple engine and worker instances coordinate using CQRS principles.
- * Each member reads from assigned topic queues and writes results to other queues,
- * creating emergent workflow orchestration without a central controller.
- *
- * **Reentrant Process Engine**: Unlike traditional workflow engines, HotMesh
- * provides built-in retry logic, idempotency, and failure recovery. Your business
- * logic doesn't need to handle timeouts or retries - the engine manages all of that.
- *
  * ## Key Features
  *
- * - **Fault Tolerance**: Automatic retry, timeout, and failure recovery
+ * - **Fault Tolerance**: Automatic retry with exponential backoff and configurable policies
  * - **Distributed Execution**: No single point of failure
  * - **YAML-Driven**: Model-driven development with declarative workflow definitions
  * - **OpenTelemetry**: Built-in observability and tracing
  * - **Durable State**: Workflow state persists across system restarts
  * - **Pattern Matching**: Pub/sub with wildcard pattern support
  * - **Throttling**: Dynamic flow control and backpressure management
+ * - **Retry Policies**: PostgreSQL-native retry configuration with exponential backoff
  *
  * ## Architecture
  *
@@ -225,7 +214,12 @@ declare class HotMesh {
      * similarly to the engine, but as an array with
      * multiple worker objects.
      *
-     * @example
+     * ## Retry Policy Configuration
+     *
+     * HotMesh supports robust retry policies with exponential backoff for PostgreSQL.
+     * Configure retry behavior at the stream level for automatic fault tolerance.
+     *
+     * @example Basic Configuration
      * ```typescript
      * const config: HotMeshConfig = {
      *   appId: 'myapp',
@@ -241,6 +235,57 @@ declare class HotMesh {
      * };
      * const hotMesh = await HotMesh.init(config);
      * ```
+     *
+     * @example With Retry Policy (PostgreSQL)
+     * ```typescript
+     * import { HotMesh } from '@hotmeshio/hotmesh';
+     * import { Client as Postgres } from 'pg';
+     *
+     * const hotMesh = await HotMesh.init({
+     *   appId: 'my-app',
+     *   engine: {
+     *     connection: {
+     *       class: Postgres,
+     *       options: { connectionString: 'postgresql://...' }
+     *     },
+     *     // Default retry policy for engine streams
+     *     retryPolicy: {
+     *       maximumAttempts: 5,      // Retry up to 5 times
+     *       backoffCoefficient: 2,   // Exponential: 2^0, 2^1, 2^2...
+     *       maximumInterval: '300s'  // Cap delay at 5 minutes
+     *     }
+     *   },
+     *   workers: [{
+     *     topic: 'order.process',
+     *     connection: {
+     *       class: Postgres,
+     *       options: { connectionString: 'postgresql://...' }
+     *     },
+     *     // Worker-specific retry policy
+     *     retryPolicy: {
+     *       maximumAttempts: 10,
+     *       backoffCoefficient: 1.5,
+     *       maximumInterval: '600s'
+     *     },
+     *     callback: async (data) => {
+     *       // Your business logic here
+     *       // Failures will automatically retry with exponential backoff
+     *       return { status: 'success', data: processedData };
+     *     }
+     *   }]
+     * });
+     * ```
+     *
+     * **Retry Policy Options**:
+     * - `maximumAttempts` - Maximum retry attempts before failure (default: 3)
+     * - `backoffCoefficient` - Base for exponential backoff calculation (default: 10)
+     * - `maximumInterval` - Maximum delay between retries in seconds or duration string (default: '120s')
+     *
+     * **Retry Delays**: For `backoffCoefficient: 2`, delays are: 2s, 4s, 8s, 16s, 32s...
+     * capped at `maximumInterval`.
+     *
+     * **Note**: Retry policies are stored in PostgreSQL columns for efficient querying and
+     * observability. Each retry creates a new message, preserving message immutability.
      */
     static init(config: HotMeshConfig): Promise<HotMesh>;
     /**
@@ -272,6 +317,12 @@ declare class HotMesh {
      * @private
      */
     private initTaskQueue;
+    /**
+     * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
+     * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
+     * @private
+     */
+    private applyRetryPolicy;
     /**
      * Starts a workflow
      * @example

package/build/services/hotmesh/index.js

@@ -11,30 +11,19 @@ const router_1 = require("../router");
 const worker_1 = require("../worker");
 const enums_1 = require("../../modules/enums");
 /**
- * HotMesh is a distributed, reentrant process orchestration engine that transforms
- * Postgres into a resilient service mesh capable of running
+ * HotMesh transforms Postgres into a durable workflow orchestration engine capable of running
  * fault-tolerant workflows across multiple services and systems.
  *
- * ## Core Concepts
- *
- * **Distributed Quorum Architecture**: HotMesh operates as a distributed quorum
- * where multiple engine and worker instances coordinate using CQRS principles.
- * Each member reads from assigned topic queues and writes results to other queues,
- * creating emergent workflow orchestration without a central controller.
- *
- * **Reentrant Process Engine**: Unlike traditional workflow engines, HotMesh
- * provides built-in retry logic, idempotency, and failure recovery. Your business
- * logic doesn't need to handle timeouts or retries - the engine manages all of that.
- *
  * ## Key Features
  *
- * - **Fault Tolerance**: Automatic retry, timeout, and failure recovery
+ * - **Fault Tolerance**: Automatic retry with exponential backoff and configurable policies
  * - **Distributed Execution**: No single point of failure
  * - **YAML-Driven**: Model-driven development with declarative workflow definitions
  * - **OpenTelemetry**: Built-in observability and tracing
  * - **Durable State**: Workflow state persists across system restarts
  * - **Pattern Matching**: Pub/sub with wildcard pattern support
  * - **Throttling**: Dynamic flow control and backpressure management
+ * - **Retry Policies**: PostgreSQL-native retry configuration with exponential backoff
  *
  * ## Architecture
  *
@@ -229,7 +218,12 @@ class HotMesh {
      * similarly to the engine, but as an array with
      * multiple worker objects.
      *
-     * @example
+     * ## Retry Policy Configuration
+     *
+     * HotMesh supports robust retry policies with exponential backoff for PostgreSQL.
+     * Configure retry behavior at the stream level for automatic fault tolerance.
+     *
+     * @example Basic Configuration
      * ```typescript
      * const config: HotMeshConfig = {
      *   appId: 'myapp',
@@ -245,6 +239,57 @@ class HotMesh {
      * };
      * const hotMesh = await HotMesh.init(config);
      * ```
+     *
+     * @example With Retry Policy (PostgreSQL)
+     * ```typescript
+     * import { HotMesh } from '@hotmeshio/hotmesh';
+     * import { Client as Postgres } from 'pg';
+     *
+     * const hotMesh = await HotMesh.init({
+     *   appId: 'my-app',
+     *   engine: {
+     *     connection: {
+     *       class: Postgres,
+     *       options: { connectionString: 'postgresql://...' }
+     *     },
+     *     // Default retry policy for engine streams
+     *     retryPolicy: {
+     *       maximumAttempts: 5,      // Retry up to 5 times
+     *       backoffCoefficient: 2,   // Exponential: 2^0, 2^1, 2^2...
+     *       maximumInterval: '300s'  // Cap delay at 5 minutes
+     *     }
+     *   },
+     *   workers: [{
+     *     topic: 'order.process',
+     *     connection: {
+     *       class: Postgres,
+     *       options: { connectionString: 'postgresql://...' }
+     *     },
+     *     // Worker-specific retry policy
+     *     retryPolicy: {
+     *       maximumAttempts: 10,
+     *       backoffCoefficient: 1.5,
+     *       maximumInterval: '600s'
+     *     },
+     *     callback: async (data) => {
+     *       // Your business logic here
+     *       // Failures will automatically retry with exponential backoff
+     *       return { status: 'success', data: processedData };
+     *     }
+     *   }]
+     * });
+     * ```
+     *
+     * **Retry Policy Options**:
+     * - `maximumAttempts` - Maximum retry attempts before failure (default: 3)
+     * - `backoffCoefficient` - Base for exponential backoff calculation (default: 10)
+     * - `maximumInterval` - Maximum delay between retries in seconds or duration string (default: '120s')
+     *
+     * **Retry Delays**: For `backoffCoefficient: 2`, delays are: 2s, 4s, 8s, 16s, 32s...
+     * capped at `maximumInterval`.
+     *
+     * **Note**: Retry policies are stored in PostgreSQL columns for efficient querying and
+     * observability. Each retry creates a new message, preserving message immutability.
      */
     static async init(config) {
         const instance = new HotMesh();
@@ -275,6 +320,10 @@ class HotMesh {
             if (config.engine.connection.readonly) {
                 config.engine.readonly = true;
             }
+            // Apply retry policy to stream connection if provided
+            if (config.engine.retryPolicy) {
+                this.applyRetryPolicy(config.engine.connection, config.engine.retryPolicy);
+            }
             // Initialize task queue for engine
             config.engine.taskQueue = this.initTaskQueue(config.engine.taskQueue, config.taskQueue);
             await factory_1.ConnectorService.initClients(config.engine);
@@ -313,6 +362,10 @@ class HotMesh {
         // Initialize task queues for workers
         if (config.workers) {
             for (const worker of config.workers) {
+                // Apply retry policy to stream connection if provided
+                if (worker.retryPolicy) {
+                    this.applyRetryPolicy(worker.connection, worker.retryPolicy);
+                }
                 worker.taskQueue = this.initTaskQueue(worker.taskQueue, config.taskQueue);
             }
         }
@@ -337,6 +390,22 @@ class HotMesh {
         // Default queue as fallback
         return enums_1.DEFAULT_TASK_QUEUE;
     }
+    /**
+     * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
+     * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
+     * @private
+     */
+    applyRetryPolicy(connection, retryPolicy) {
+        // Check if this is ProvidersConfig (has 'stream' property)
+        if ('stream' in connection && connection.stream) {
+            // Long-form: apply to the stream sub-config
+            connection.stream.retryPolicy = retryPolicy;
+        }
+        else {
+            // Short-form: apply directly to the connection
+            connection.retryPolicy = retryPolicy;
+        }
+    }
     // ************* PUB/SUB METHODS *************
     /**
      * Starts a workflow