transactional-ai 0.1.0 → 0.2.0

package/README.md

@@ -5,13 +5,17 @@ Implement the Saga Pattern with persistent rollback and state recovery for Long-
 
 [![npm version](https://img.shields.io/npm/v/transactional-ai.svg)](https://www.npmjs.com/package/transactional-ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![CI](https://github.com/Grafikui/transactional-ai-control-plane/actions/workflows/ci.yml/badge.svg)
 
 ## Why use this?
+
 AI Agents are flaky. Steps fail, APIs time out, and hallucinations happen.
 `transactional-ai` gives you:
+
 1.  **Automatic Rollbacks**: If step 3 fails, steps 2 and 1 are compensated (undone) automatically.
-2.  **Persistence**: Transactions survive process crashes using Redis or File storage.
-3.  **Observability**: Inspect running transactions via the built-in CLI.
+2.  **Concurrency Safety**: Distributed locking prevents race conditions when scaling workers.
+3.  **Persistence**: Transactions survive process crashes using Redis, Postgres, or File storage.
+4.  **Resilience**: Built-in retry policies for flaky LLM APIs.
 
 ## Installation
 
@@ -24,63 +28,146 @@ npm install transactional-ai
 ## Quick Start
 
 ### 1. The "Litmus Test" (Basic Usage)
+
 Define a transaction where every action has a compensating rollback action.
 
 ```typescript
-import { Transaction } from 'transactional-ai';
+import { Transaction } from "transactional-ai";
 
 // 1. Create a named transaction (required for resumability)
-const agent = new Transaction('user-onboarding-123');
+const agent = new Transaction("user-onboarding-123");
 
 agent
   .step({
-    name: 'create-file',
+    name: "create-file",
     execute: async (ctx) => {
-       // Do the work
-       const file = await googleDrive.createFile('report.txt');
-       return file.id; 
+      // Do the work
+      const file = await googleDrive.createFile("report.txt");
+      return file.id;
     },
     compensate: async (fileId) => {
-       // Undo the work
-       await googleDrive.deleteFile(fileId);
-    }
+      // Undo the work
+      await googleDrive.deleteFile(fileId);
+    },
   })
   .step({
-    name: 'email-report',
+    name: "email-report",
     execute: async (ctx) => {
-       // Use previous results via context or external state
-       await emailService.send(ctx.result);
+      // Use previous results via context or external state
+      await emailService.send(ctx.result);
     },
     compensate: async () => {
-       await emailService.recallLast();
-    }
+      await emailService.recallLast();
+    },
   });
 
 // 2. Run it
-await agent.run({ initialData: 'foo' });
+await agent.run({ initialData: "foo" });
 ```
 
 ### Adding Persistence (Redis)
+
 To survive process crashes, simply provide a storage adapter.
 
 ```typescript
-import { Transaction, RedisStorage } from 'transactional-ai';
+import { Transaction, RedisStorage } from "transactional-ai";
 
-const storage = new RedisStorage('redis://localhost:6379');
-const agent = new Transaction('workflow-id-555', storage);
+const storage = new RedisStorage("redis://localhost:6379");
+const agent = new Transaction("workflow-id-555", storage);
 
 // If the process crashes here, running this code again
 // will automatically SKIP completed steps and resume at the failure point.
 agent
-  .step({ /* ... */ })
-  .step({ /* ... */ });
+  .step({
+    /* ... */
+  })
+  .step({
+    /* ... */
+  });
 
 await agent.run();
 ```
 
+## Enterprise Features (v0.2.0)
+
+### 1. Distributed Locking (Redis)
+
+Prevent race conditions when running multiple agent workers on the same Transaction ID.
+
+```typeScript
+import { Transaction, RedisStorage, RedisLock } from 'transactional-ai';
+
+const connection = 'redis://localhost:6379';
+const storage = new RedisStorage(connection);
+const lock = new RedisLock(connection);
+
+const agent = new Transaction('tx-unique-id', storage, {
+  lock: lock,
+  lockTTL: 30000 // Hold lock for 30s
+});
+
+// Safe to run across multiple processes/servers
+await agent.run();
+```
+
+### 2. Postgres Storage (SQL)
+
+Use Postgres for strict ACID compliance and auditability.
+
+Prerequisite: Run schema.sql in your database.
+
+```typeScript
+import { Transaction, PostgresStorage } from 'transactional-ai';
+
+const storage = new PostgresStorage('postgresql://user:pass@localhost:5432/mydb');
+const agent = new Transaction('tx-id', storage);
+```
+
+#### Setting Up Postgres
+
+Before using PostgresStorage, create the required table in your database:
+
+**Option 1: Run the provided schema**
+```bash
+# From project root
+psql -U your_user -d your_database -f schema.sql
+```
+
+**Option 2: Copy-paste this SQL**
+```sql
+CREATE TABLE IF NOT EXISTS transactions (
+  id VARCHAR(255) PRIMARY KEY,
+  status VARCHAR(50) NOT NULL,
+  step_stack JSONB NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_transactions_status ON transactions(status);
+```
+
+**Important:** The table must exist before running your first transaction. It will NOT be auto-created.
+
+### 3. Retry Policies
+
+Handle flaky APIs (e.g., OpenAI 500 errors) automatically without failing the transaction.
+
+```typeScript
+agent.step({
+  name: 'generate-text',
+  execute: async () => await openai.createCompletion(...),
+  compensate: async () => { /* ... */ },
+  retry: {
+    attempts: 3,      // Try 3 times
+    backoffMs: 1000   // Wait 1s between attempts
+  }
+});
+```
+
 ---
 
 ## CLI Inspector
+
 You don't need a complex dashboard to see what your agents are doing. Use the included CLI to inspect transaction logs directly from your terminal.
 
 ```bash
@@ -111,15 +198,17 @@ Output:
 ## Advanced Usage
 
 ### Audit Mode (Governance)
+
 By default, logs are cleared upon success to save storage space. To keep a permanent audit trail for compliance (e.g., "Why did the agent do this?"), enable Audit Mode:
 
 ```typescript
-const agent = new Transaction('id', storage, {
-    cleanupOnSuccess: false
+const agent = new Transaction("id", storage, {
+  cleanupOnSuccess: false,
 });
 ```
 
 ### Manual Rollbacks
+
 The library handles rollbacks automatically on error. You can trigger them manually by throwing an error inside any step:
 
 ```typescript
@@ -143,6 +232,7 @@ agent.step({
 ---
 
 ## Roadmap
+
 [x] Core Saga Engine (Execute/Compensate)
 
 [x] Persistence Adapters (File, Redis)
@@ -151,11 +241,14 @@ agent.step({
 
 [x] CLI Inspector (tai-inspect)
 
-[ ] Concurrent Transaction Locking
+[x] Concurrent Transaction Locking
+
+[x] Postgres/SQL Storage Adapter
 
-[ ] Postgres/SQL Storage Adapter
+[x] Step Retry Policies
 
 ---
 
 ## License
-MIT
+
+MIT

package/dist/engine/Lock.d.ts

@@ -0,0 +1,27 @@
+export declare class TransactionLockedError extends Error {
+    constructor(message: string);
+}
+export interface LockAdapter {
+    /**
+     * Attempts to acquire a lock for the given transaction ID.
+     * @param id The transaction ID to lock
+     * @param ttlMs How long (in ms) to hold the lock before auto-expiring (safety)
+     * @returns A "lock token" if successful, or null if the lock is busy.
+     */
+    acquire(id: string, ttlMs: number): Promise<string | null>;
+    /**
+     * Releases the lock using the token received during acquire.
+     * @param id The transaction ID
+     * @param token The token received from acquire
+     */
+    release(id: string, token: string): Promise<void>;
+}
+/**
+ * Default "No Operation" lock for single-process usage.
+ * It never blocks.
+ */
+export declare class NoOpLock implements LockAdapter {
+    acquire(id: string, ttlMs: number): Promise<string>;
+    release(id: string, token: string): Promise<void>;
+}
+//# sourceMappingURL=Lock.d.ts.map

package/dist/engine/Lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lock.d.ts","sourceRoot":"","sources":["../../engine/Lock.ts"],"names":[],"mappings":"AAAA,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3D;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,qBAAa,QAAS,YAAW,WAAW;IAEpC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAGnD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxD"}

package/dist/engine/Lock.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpLock = exports.TransactionLockedError = void 0;
+class TransactionLockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransactionLockedError';
+    }
+}
+exports.TransactionLockedError = TransactionLockedError;
+/**
+ * Default "No Operation" lock for single-process usage.
+ * It never blocks.
+ */
+class NoOpLock {
+    // FIXED: Added 'ttlMs' to match interface signature
+    async acquire(id, ttlMs) {
+        return 'dummy-token';
+    }
+    async release(id, token) {
+        // Do nothing
+    }
+}
+exports.NoOpLock = NoOpLock;
+//# sourceMappingURL=Lock.js.map

package/dist/engine/Lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lock.js","sourceRoot":"","sources":["../../engine/Lock.ts"],"names":[],"mappings":";;;AAAA,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAmBD;;;GAGG;AACH,MAAa,QAAQ;IACnB,oDAAoD;IACpD,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAa;QACrC,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAa;QACrC,aAAa;IACf,CAAC;CACF;AARD,4BAQC"}

package/dist/engine/PostgresStorage.d.ts

@@ -0,0 +1,13 @@
+import { Pool } from 'pg';
+import { StorageAdapter } from './Storage';
+import { StepContext } from './Transaction';
+export declare class PostgresStorage implements StorageAdapter {
+    private pool;
+    private tableName;
+    constructor(connectionString: string, tableName?: string, pool?: Pool);
+    save(txId: string, state: StepContext[]): Promise<void>;
+    load(txId: string): Promise<StepContext[] | null>;
+    clear(txId: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=PostgresStorage.d.ts.map

package/dist/engine/PostgresStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresStorage.d.ts","sourceRoot":"","sources":["../../engine/PostgresStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,SAAS,CAAS;gBAGd,gBAAgB,EAAE,MAAM,EAAE,SAAS,SAAiB,EAAE,IAAI,CAAC,EAAE,IAAI;IAMvE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAQjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,UAAU;CAGjB"}

package/dist/engine/PostgresStorage.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresStorage = void 0;
+const pg_1 = require("pg");
+class PostgresStorage {
+    pool;
+    tableName;
+    // CHANGED: Accept optional 'pool' for testing/sharing
+    constructor(connectionString, tableName = 'transactions', pool) {
+        this.tableName = tableName;
+        // Use provided pool OR create a new one
+        this.pool = pool || new pg_1.Pool({ connectionString });
+    }
+    async save(txId, state) {
+        const status = state.length > 0 && state[state.length - 1].status === 'completed'
+            ? 'pending'
+            : 'pending';
+        const query = `
+      INSERT INTO ${this.tableName} (id, status, step_stack, updated_at)
+      VALUES ($1, $2, $3, NOW())
+      ON CONFLICT (id)
+      DO UPDATE SET 
+        step_stack = EXCLUDED.step_stack,
+        updated_at = NOW(),
+        status = EXCLUDED.status;
+    `;
+        await this.pool.query(query, [txId, status, JSON.stringify(state)]);
+    }
+    async load(txId) {
+        const query = `SELECT step_stack FROM ${this.tableName} WHERE id = $1`;
+        const res = await this.pool.query(query, [txId]);
+        if (res.rows.length === 0)
+            return null;
+        return res.rows[0].step_stack;
+    }
+    async clear(txId) {
+        const query = `DELETE FROM ${this.tableName} WHERE id = $1`;
+        await this.pool.query(query, [txId]);
+    }
+    async disconnect() {
+        await this.pool.end();
+    }
+}
+exports.PostgresStorage = PostgresStorage;
+//# sourceMappingURL=PostgresStorage.js.map

package/dist/engine/PostgresStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresStorage.js","sourceRoot":"","sources":["../../engine/PostgresStorage.ts"],"names":[],"mappings":";;;AAAA,2BAA0B;AAI1B,MAAa,eAAe;IAClB,IAAI,CAAO;IACX,SAAS,CAAS;IAE1B,sDAAsD;IACtD,YAAY,gBAAwB,EAAE,SAAS,GAAG,cAAc,EAAE,IAAW;QAC3E,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,wCAAwC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,SAAI,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAoB;QAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW;YAC/E,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,KAAK,GAAG;oBACE,IAAI,CAAC,SAAS;;;;;;;KAO7B,CAAC;QAEF,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,KAAK,GAAG,0BAA0B,IAAI,CAAC,SAAS,gBAAgB,CAAC;QACvE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAEjD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAA2B,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,KAAK,GAAG,eAAe,IAAI,CAAC,SAAS,gBAAgB,CAAC;QAC5D,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACxB,CAAC;CACF;AA7CD,0CA6CC"}

package/dist/engine/RedisStorage.d.ts

@@ -1,5 +1,6 @@
 import { StorageAdapter } from './Storage';
 import { StepContext } from './Transaction';
+import { LockAdapter } from './Lock';
 export declare class RedisStorage implements StorageAdapter {
     private redis;
     private ttlSeconds;
@@ -13,4 +14,14 @@ export declare class RedisStorage implements StorageAdapter {
     clear(txId: string): Promise<void>;
     disconnect(): Promise<void>;
 }
+/**
+ * Distributed Lock implementation using Redis SET NX
+ */
+export declare class RedisLock implements LockAdapter {
+    private redis;
+    constructor(connectionString: string);
+    acquire(id: string, ttlMs: number): Promise<string | null>;
+    release(id: string, token: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
 //# sourceMappingURL=RedisStorage.d.ts.map

package/dist/engine/RedisStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RedisStorage.d.ts","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qBAAa,YAAa,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;gBACS,gBAAgB,EAAE,MAAM,EAAE,UAAU,SAAO;IAKjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAKjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,UAAU;CAGjB"}
+{"version":3,"file":"RedisStorage.d.ts","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,qBAAa,YAAa,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;gBACS,gBAAgB,EAAE,MAAM,EAAE,UAAU,SAAO;IAKjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAKjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,UAAU;CAGjB;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,WAAW;IAC3C,OAAO,CAAC,KAAK,CAAQ;gBAET,gBAAgB,EAAE,MAAM;IAI9B,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAU1D,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjD,UAAU;CAGjB"}

package/dist/engine/RedisStorage.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedisStorage = void 0;
+exports.RedisLock = exports.RedisStorage = void 0;
 const ioredis_1 = __importDefault(require("ioredis"));
 class RedisStorage {
     redis;
@@ -35,4 +35,37 @@ class RedisStorage {
     }
 }
 exports.RedisStorage = RedisStorage;
+/**
+ * Distributed Lock implementation using Redis SET NX
+ */
+class RedisLock {
+    redis;
+    constructor(connectionString) {
+        this.redis = new ioredis_1.default(connectionString);
+    }
+    async acquire(id, ttlMs) {
+        const token = Math.random().toString(36).substring(2);
+        const key = `lock:${id}`;
+        // FIXED: ioredis requires 'PX' (expiry) before 'NX' (condition)
+        const result = await this.redis.set(key, token, 'PX', ttlMs, 'NX');
+        return result === 'OK' ? token : null;
+    }
+    async release(id, token) {
+        const key = `lock:${id}`;
+        // Safety: Only delete the lock if *we* own it (check token).
+        // Lua script guarantees atomicity.
+        const script = `
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      else
+        return 0
+      end
+    `;
+        await this.redis.eval(script, 1, key, token);
+    }
+    async disconnect() {
+        await this.redis.quit();
+    }
+}
+exports.RedisLock = RedisLock;
 //# sourceMappingURL=RedisStorage.js.map

package/dist/engine/RedisStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"RedisStorage.js","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA4B;AAI5B,MAAa,YAAY;IACf,KAAK,CAAQ;IACb,UAAU,CAAS;IAE3B;;;OAGG;IACH,YAAY,gBAAwB,EAAE,UAAU,GAAG,IAAI;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAK,CAAC,gBAAgB,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAoB;QAC3C,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,6EAA6E;QAC7E,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF;AAjCD,oCAiCC"}
+{"version":3,"file":"RedisStorage.js","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA4B;AAK5B,MAAa,YAAY;IACf,KAAK,CAAQ;IACb,UAAU,CAAS;IAE3B;;;OAGG;IACH,YAAY,gBAAwB,EAAE,UAAU,GAAG,IAAI;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAK,CAAC,gBAAgB,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAoB;QAC3C,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,6EAA6E;QAC7E,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF;AAjCD,oCAiCC;AAED;;GAEG;AACH,MAAa,SAAS;IACZ,KAAK,CAAQ;IAErB,YAAY,gBAAwB;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAK,CAAC,gBAAgB,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAa;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,QAAQ,EAAE,EAAE,CAAC;QAEzB,gEAAgE;QAChE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAEnE,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAa;QACrC,MAAM,GAAG,GAAG,QAAQ,EAAE,EAAE,CAAC;QAEzB,6DAA6D;QAC7D,mCAAmC;QACnC,MAAM,MAAM,GAAG;;;;;;KAMd,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF;AApCD,8BAoCC"}

package/dist/engine/Transaction.d.ts

@@ -1,15 +1,23 @@
 import { StorageAdapter } from './Storage';
+import { LockAdapter } from './Lock';
 export type StepContext<T = any> = {
     name: string;
     result?: T;
     status: 'completed' | 'pending';
 };
+export type RetryPolicy = {
+    attempts: number;
+    backoffMs?: number;
+};
 export type StepDefinition<T> = {
     do: () => Promise<T> | T;
     undo: (result: T) => Promise<void> | void;
+    retry?: RetryPolicy;
 };
 type TransactionOptions = {
     cleanupOnSuccess?: boolean;
+    lock?: LockAdapter;
+    lockTTL?: number;
 };
 export declare class Transaction {
     private stepStack;
@@ -17,9 +25,12 @@ export declare class Transaction {
     private id;
     private storage?;
     private cleanupOnSuccess;
+    private lock;
+    private lockTTL;
     constructor(id: string, storage?: StorageAdapter, options?: TransactionOptions);
     run(workflow: (tx: Transaction) => Promise<void>): Promise<void>;
     step<T>(name: string, definition: StepDefinition<T>): Promise<T>;
+    private executeWithRetry;
     private rollback;
 }
 export {};

package/dist/engine/Transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transaction.d.ts","sourceRoot":"","sources":["../../engine/Transaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3C,CAAC;AASF,KAAK,kBAAkB,GAAG;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAO5E,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBhE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;YAgCxD,QAAQ;CAWvB"}
+{"version":3,"file":"Transaction.d.ts","sourceRoot":"","sources":["../../engine/Transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAoC,MAAM,QAAQ,CAAC;AAEvE,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC,CAAC;AAGF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAQF,KAAK,kBAAkB,GAAG;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,gBAAgB,CAAU;IAGlC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEZ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAU5E,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAwChE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;YAgCxD,gBAAgB;YAmBhB,QAAQ;CAUvB"}

package/dist/engine/Transaction.js

@@ -1,69 +1,106 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Transaction = void 0;
+const Lock_1 = require("./Lock");
 class Transaction {
     stepStack = [];
     history = new Map();
     id;
     storage;
     cleanupOnSuccess;
+    // Locking Props
+    lock;
+    lockTTL;
     constructor(id, storage, options = {}) {
         this.id = id;
         this.storage = storage;
-        // Default to TRUE (clean up) unless told otherwise
         this.cleanupOnSuccess = options.cleanupOnSuccess ?? true;
+        // Default to NoOpLock
+        this.lock = options.lock ?? new Lock_1.NoOpLock();
+        this.lockTTL = options.lockTTL ?? 30000;
     }
     async run(workflow) {
-        // 1. Load previous state if storage is provided
-        if (this.storage) {
-            const savedState = await this.storage.load(this.id);
-            if (savedState) {
-                console.log(`[Transaction] 🔄 Resuming ${this.id} with ${savedState.length} completed steps.`);
-                savedState.forEach(s => this.history.set(s.name, s.result));
-                // Note: We can't re-hydrate the 'undo' functions until the code runs again.
-                // The 'step' method handles re-hydrating the stack.
-            }
+        // 1. Acquire Lock
+        console.log(`🔒 [Lock] Acquiring lock for ${this.id}...`);
+        const lockToken = await this.lock.acquire(this.id, this.lockTTL);
+        if (!lockToken) {
+            throw new Lock_1.TransactionLockedError(`Transaction '${this.id}' is currently running elsewhere.`);
         }
         try {
-            await workflow(this);
-            // CHANGED: Only clear if flag is true
-            if (this.storage && this.cleanupOnSuccess) {
-                await this.storage.clear(this.id);
+            // 2. Load previous state
+            if (this.storage) {
+                const savedState = await this.storage.load(this.id);
+                if (savedState) {
+                    console.log(`[Transaction] 🔄 Resuming ${this.id} with ${savedState.length} completed steps.`);
+                    savedState.forEach(s => this.history.set(s.name, s.result));
+                }
+            }
+            // 3. Execute Workflow
+            try {
+                await workflow(this);
+                // 4. Cleanup on Success
+                if (this.storage && this.cleanupOnSuccess) {
+                    await this.storage.clear(this.id);
+                }
+            }
+            catch (error) {
+                console.error(`\n🔴 [Transaction Failed] Error: ${error instanceof Error ? error.message : error}`);
+                await this.rollback();
+                throw error;
             }
         }
-        catch (error) {
-            console.error(`\n🔴 [Transaction Failed] Error: ${error instanceof Error ? error.message : error}`);
-            await this.rollback();
-            throw error;
+        finally {
+            // 5. ALWAYS Release Lock
+            console.log(`🔓 [Lock] Releasing...`);
+            await this.lock.release(this.id, lockToken);
         }
     }
     async step(name, definition) {
-        // 1. Check if we already did this step (Resumability!)
+        // 1. Check Resumability
         if (this.history.has(name)) {
             console.log(`⏩ [Skip: ${name}] Already completed.`);
             const result = this.history.get(name);
-            // CRITICAL: We still need to push the undo handler to the stack 
-            // so we can rollback if a LATER step fails.
             this.stepStack.push({ name, undo: () => definition.undo(result) });
             return result;
         }
-        // 2. If not, Execute
         console.log(`➡️  [Do: ${name}] Executing...`);
-        const result = await definition.do();
+        // 2. Execute with Retry Logic
+        // We replace the direct 'definition.do()' call with our new helper
+        const result = await this.executeWithRetry(name, definition);
         // 3. Update State
         this.stepStack.push({ name, undo: () => definition.undo(result) });
         // 4. Persist
         if (this.storage) {
             const currentHistory = this.stepStack.map(s => ({
                 name: s.name,
-                result: s.name === name ? result : this.history.get(s.name), // simplified for demo
+                result: s.name === name ? result : this.history.get(s.name),
                 status: 'completed'
             }));
-            // In a real app, map the full history properly
             await this.storage.save(this.id, currentHistory);
         }
         return result;
     }
+    // NEW: Retry Helper
+    async executeWithRetry(name, def) {
+        const attempts = def.retry?.attempts || 1;
+        const backoff = def.retry?.backoffMs || 0;
+        for (let i = 1; i <= attempts; i++) {
+            try {
+                return await def.do();
+            }
+            catch (err) {
+                if (i < attempts) {
+                    console.warn(`   ⚠️ [Retry ${i}/${attempts}] Step '${name}' failed. Retrying in ${backoff}ms...`);
+                    if (backoff > 0)
+                        await new Promise(r => setTimeout(r, backoff));
+                }
+                else {
+                    throw err; // Final failure
+                }
+            }
+        }
+        throw new Error('Unreachable');
+    }
     async rollback() {
         const stepsToUndo = [...this.stepStack].reverse();
         for (const step of stepsToUndo) {
@@ -75,7 +112,6 @@ class Transaction {
                 console.error(`   ❌ [CRITICAL] Undo failed for '${step.name}'`, err);
             }
         }
-        // Clear storage after rollback so we don't resume into a broken state
         if (this.storage)
             await this.storage.clear(this.id);
         this.stepStack = [];

package/dist/engine/Transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../engine/Transaction.ts"],"names":[],"mappings":";;;AAyBA,MAAa,WAAW;IACd,SAAS,GAAmB,EAAE,CAAC;IAC/B,OAAO,GAAqB,IAAI,GAAG,EAAE,CAAC;IACtC,EAAE,CAAS;IACX,OAAO,CAAkB;IACzB,gBAAgB,CAAU;IAElC,YAAY,EAAU,EAAE,OAAwB,EAAE,UAA8B,EAAE;QAChF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,mDAAmD;QACnD,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAA4C;QACpD,gDAAgD;QAChD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACpD,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,CAAC,EAAE,SAAS,UAAU,CAAC,MAAM,mBAAmB,CAAC,CAAC;gBAC/F,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC5D,4EAA4E;gBAC5E,oDAAoD;YACtD,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACrB,sCAAsC;YACtC,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC1C,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oCAAoC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACpG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,UAA6B;QACvD,uDAAuD;QACvD,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,sBAAsB,CAAC,CAAC;YACpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;YAC3C,iEAAiE;YACjE,4CAA4C;YAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACnE,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,qBAAqB;QACrB,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,gBAAgB,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,EAAE,EAAE,CAAC;QAErC,kBAAkB;QAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAEnE,aAAa;QACb,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC9C,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,MAAM,EAAE,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,sBAAsB;gBACnF,MAAM,EAAE,WAAW;aACpB,CAAC,CAAC,CAAC;YACJ,+CAA+C;YAC/C,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,cAAqB,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,gBAAgB,CAAC,CAAC;YACrD,IAAI,CAAC;gBAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAAC,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,CAAC,KAAK,CAAC,oCAAoC,IAAI,CAAC,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;YAAC,CAAC;QACvF,CAAC;QACD,sEAAsE;QACtE,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;CACF;AAlFD,kCAkFC"}
+{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../engine/Transaction.ts"],"names":[],"mappings":";;;AACA,iCAAuE;AAgCvE,MAAa,WAAW;IACd,SAAS,GAAmB,EAAE,CAAC;IAC/B,OAAO,GAAqB,IAAI,GAAG,EAAE,CAAC;IACtC,EAAE,CAAS;IACX,OAAO,CAAkB;IACzB,gBAAgB,CAAU;IAElC,gBAAgB;IACR,IAAI,CAAc;IAClB,OAAO,CAAS;IAExB,YAAY,EAAU,EAAE,OAAwB,EAAE,UAA8B,EAAE;QAChF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC;QAEzD,sBAAsB;QACtB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,eAAQ,EAAE,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAA4C;QACpD,kBAAkB;QAClB,OAAO,CAAC,GAAG,CAAC,gCAAgC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,6BAAsB,CAAC,gBAAgB,IAAI,CAAC,EAAE,mCAAmC,CAAC,CAAC;QAC/F,CAAC;QAED,IAAI,CAAC;YACH,yBAAyB;YACzB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACpD,IAAI,UAAU,EAAE,CAAC;oBACf,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,CAAC,EAAE,SAAS,UAAU,CAAC,MAAM,mBAAmB,CAAC,CAAC;oBAC/F,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC9D,CAAC;YACH,CAAC;YAED,sBAAsB;YACtB,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAErB,wBAAwB;gBACxB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBAC1C,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,oCAAoC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;gBACpG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACtB,MAAM,KAAK,CAAC;YACd,CAAC;QAEH,CAAC;gBAAS,CAAC;YACT,yBAAyB;YACzB,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;YACtC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,UAA6B;QACvD,wBAAwB;QACxB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,sBAAsB,CAAC,CAAC;YACpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;YAC3C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACnE,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,gBAAgB,CAAC,CAAC;QAE9C,8BAA8B;QAC9B,mEAAmE;QACnE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAE7D,kBAAkB;QAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAEnE,aAAa;QACb,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC9C,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,MAAM,EAAE,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC3D,MAAM,EAAE,WAAW;aACpB,CAAC,CAAC,CAAC;YACJ,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,cAAqB,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,oBAAoB;IACZ,KAAK,CAAC,gBAAgB,CAAI,IAAY,EAAE,GAAsB;QACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,CAAC;QAE1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,OAAO,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC;YACxB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;oBACjB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,QAAQ,WAAW,IAAI,yBAAyB,OAAO,OAAO,CAAC,CAAC;oBAClG,IAAI,OAAO,GAAG,CAAC;wBAAE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;gBAClE,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,CAAC,CAAC,gBAAgB;gBAC7B,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACjC,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,gBAAgB,CAAC,CAAC;YACrD,IAAI,CAAC;gBAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAAC,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,CAAC,KAAK,CAAC,oCAAoC,IAAI,CAAC,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;YAAC,CAAC;QACvF,CAAC;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;CACF;AA1HD,kCA0HC"}

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export { Transaction } from './engine/Transaction';
 export type { StepContext, StepDefinition } from './engine/Transaction';
 export { StorageAdapter } from './engine/Storage';
 export { FileStorage } from './engine/FileStorage';
-export { RedisStorage } from './engine/RedisStorage';
+export { RedisStorage, RedisLock } from './engine/RedisStorage';
+export { PostgresStorage } from './engine/PostgresStorage';
+export { LockAdapter, TransactionLockedError, NoOpLock } from './engine/Lock';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGxE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGxE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedisStorage = exports.FileStorage = exports.Transaction = void 0;
+exports.NoOpLock = exports.TransactionLockedError = exports.PostgresStorage = exports.RedisLock = exports.RedisStorage = exports.FileStorage = exports.Transaction = void 0;
 // Export the core engine
 var Transaction_1 = require("./engine/Transaction");
 Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return Transaction_1.Transaction; } });
@@ -8,5 +8,11 @@ var FileStorage_1 = require("./engine/FileStorage");
 Object.defineProperty(exports, "FileStorage", { enumerable: true, get: function () { return FileStorage_1.FileStorage; } });
 var RedisStorage_1 = require("./engine/RedisStorage");
 Object.defineProperty(exports, "RedisStorage", { enumerable: true, get: function () { return RedisStorage_1.RedisStorage; } });
-// We do NOT export the internal 'examples' or 'bin' scripts.
+Object.defineProperty(exports, "RedisLock", { enumerable: true, get: function () { return RedisStorage_1.RedisLock; } });
+var PostgresStorage_1 = require("./engine/PostgresStorage");
+Object.defineProperty(exports, "PostgresStorage", { enumerable: true, get: function () { return PostgresStorage_1.PostgresStorage; } });
+// Export Locking Primitives
+var Lock_1 = require("./engine/Lock");
+Object.defineProperty(exports, "TransactionLockedError", { enumerable: true, get: function () { return Lock_1.TransactionLockedError; } });
+Object.defineProperty(exports, "NoOpLock", { enumerable: true, get: function () { return Lock_1.NoOpLock; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;AAAA,yBAAyB;AACzB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AAKpB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AACpB,sDAAqD;AAA5C,4GAAA,YAAY,OAAA;AAErB,6DAA6D"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;AAAA,yBAAyB;AACzB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AAKpB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AACpB,sDAAgE;AAAvD,4GAAA,YAAY,OAAA;AAAE,yGAAA,SAAS,OAAA;AAChC,4DAA2D;AAAlD,kHAAA,eAAe,OAAA;AAExB,4BAA4B;AAC5B,sCAA8E;AAAxD,8GAAA,sBAAsB,OAAA;AAAE,gGAAA,QAAQ,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transactional-ai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A reliability protocol for AI Agents. Saga pattern with persistent rollback.",
   "main": "dist/index.js",
   "bin": {
@@ -14,18 +14,36 @@
     "build": "tsc",
     "postbuild": "chmod +x dist/bin/inspect.js",
     "test": "jest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "example:failure": "tsx examples/demo-failure.ts",
+    "example:resume": "tsx examples/demo-resume.ts",
+    "example:openai": "tsx examples/demo-openai-stripe.ts"
   },
   "keywords": [
     "ai",
     "agent",
     "transaction",
     "saga",
+    "saga-pattern",
     "reliability",
-    "llm"
+    "llm",
+    "openai",
+    "workflow",
+    "orchestration",
+    "rollback",
+    "compensation",
+    "typescript"
   ],
-  "author": "Your Name",
+  "author": "GrafikUi <hello@grafikui.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Grafikui/Transactional-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Grafikui/Transactional-ai/issues"
+  },
+  "homepage": "https://github.com/Grafikui/Transactional-ai#readme",
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",
@@ -41,9 +59,11 @@
   },
   "dependencies": {
     "@prisma/client": "6.15.0",
+    "@types/pg": "^8.16.0",
     "ioredis": "^5.9.1",
     "node-fetch": "^3.3.2",
     "openai": "^6.15.0",
+    "pg": "^8.16.3",
     "prisma": "6.15.0"
   }
 }