@optimystic/db-core 0.0.1

package/dist/src/transaction/actions-engine.js

@@ -0,0 +1,67 @@
+export const ACTIONS_ENGINE_ID = "actions@1.0.0";
+/**
+ * Built-in action-based transaction engine for testing.
+ *
+ * This engine treats each statement as a JSON-encoded CollectionActions object.
+ * It's useful for testing the transaction infrastructure without needing SQL.
+ *
+ * Each statement format:
+ * ```json
+ * {
+ *   "collectionId": "users",
+ *   "actions": [
+ *     { "type": "insert", "data": { "id": 1, "name": "Alice" } }
+ *   ]
+ * }
+ * ```
+ */
+export class ActionsEngine {
+    coordinator;
+    constructor(coordinator) {
+        this.coordinator = coordinator;
+    }
+    async execute(transaction) {
+        try {
+            // Parse each statement as a CollectionActions object
+            const allActions = [];
+            for (const statement of transaction.statements) {
+                const collectionActions = JSON.parse(statement);
+                // Validate structure
+                if (!collectionActions.collectionId || typeof collectionActions.collectionId !== 'string') {
+                    return {
+                        success: false,
+                        error: 'Invalid statement: missing collectionId'
+                    };
+                }
+                if (!collectionActions.actions || !Array.isArray(collectionActions.actions)) {
+                    return {
+                        success: false,
+                        error: `Invalid statement: collection ${collectionActions.collectionId} missing or invalid actions array`
+                    };
+                }
+                allActions.push(collectionActions);
+                // Apply actions through coordinator (for validation/replay)
+                await this.coordinator.applyActions([collectionActions], transaction.stamp.id);
+            }
+            // Return success (actions already applied)
+            return {
+                success: true,
+                actions: allActions
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to execute transaction: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+}
+/**
+ * Helper to create an actions-based transaction statements array.
+ * Each CollectionActions becomes a separate statement.
+ */
+export function createActionsStatements(collections) {
+    return collections.map(c => JSON.stringify(c));
+}
+//# sourceMappingURL=actions-engine.js.map

package/dist/src/transaction/actions-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions-engine.js","sourceRoot":"","sources":["../../../src/transaction/actions-engine.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAa;IACL;IAApB,YAAoB,WAAmC;QAAnC,gBAAW,GAAX,WAAW,CAAwB;IAAG,CAAC;IAE3D,KAAK,CAAC,OAAO,CAAC,WAAwB;QACrC,IAAI,CAAC;YACJ,qDAAqD;YACrD,MAAM,UAAU,GAAwB,EAAE,CAAC;YAE3C,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;gBAChD,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAsB,CAAC;gBAErE,qBAAqB;gBACrB,IAAI,CAAC,iBAAiB,CAAC,YAAY,IAAI,OAAO,iBAAiB,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;oBAC3F,OAAO;wBACN,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,yCAAyC;qBAChD,CAAC;gBACH,CAAC;gBAED,IAAI,CAAC,iBAAiB,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC7E,OAAO;wBACN,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,iCAAiC,iBAAiB,CAAC,YAAY,mCAAmC;qBACzG,CAAC;gBACH,CAAC;gBAED,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBAEnC,4DAA4D;gBAC5D,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChF,CAAC;YAED,2CAA2C;YAC3C,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,UAAU;aACnB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO;gBACN,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,kCAAkC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aACjG,CAAC;QACH,CAAC;IACF,CAAC;CACD;AAUD;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAgC;IACvE,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/src/transaction/context.d.ts

@@ -0,0 +1,60 @@
+import type { CollectionId } from "../index.js";
+import type { TransactionCoordinator } from "./coordinator.js";
+import type { ReadDependency, ExecutionResult } from "./transaction.js";
+import type { Action } from "../collection/action.js";
+/**
+ * Transaction context for accumulating actions and reads.
+ *
+ * Usage:
+ *   const txn = coordinator.begin();
+ *   txn.addAction('users', { type: 'insert', data: {...} });
+ *   txn.addAction('users', { type: 'get', data: { key: 1 } });
+ *   const result = await txn.commit();
+ */
+export declare class TransactionContext {
+    private readonly coordinator;
+    readonly transactionId: string;
+    readonly engine: string;
+    private readonly collectionActions;
+    private readonly reads;
+    constructor(coordinator: TransactionCoordinator, transactionId: string, engine: string);
+    /**
+     * Add an action to a collection.
+     *
+     * Actions are collection-specific:
+     * - Tree: 'insert', 'delete', 'get', 'scan'
+     * - Diary: 'append', 'read'
+     * - etc.
+     */
+    addAction(collectionId: CollectionId, action: Action<any>): Promise<void>;
+    /**
+     * Add a read dependency for optimistic concurrency control.
+     */
+    addRead(read: ReadDependency): void;
+    /**
+     * Commit the transaction.
+     *
+     * This executes all accumulated actions across all affected collections,
+     * coordinating with the network as needed.
+     */
+    commit(): Promise<ExecutionResult>;
+    /**
+     * Rollback the transaction (just discard accumulated state).
+     */
+    rollback(): void;
+    /**
+     * Get all accumulated actions by collection.
+     * Used by coordinator during commit.
+     */
+    getCollectionActions(): Map<CollectionId, Action<any>[]>;
+    /**
+     * Get all accumulated read dependencies.
+     * Used by coordinator during commit.
+     */
+    getReads(): ReadDependency[];
+    /**
+     * Get the set of affected collection IDs.
+     */
+    getAffectedCollections(): Set<CollectionId>;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/src/transaction/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/transaction/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAK7B,OAAO,CAAC,QAAQ,CAAC,WAAW;aACZ,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,MAAM;IAN/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA+C;IACjF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;gBAG5B,WAAW,EAAE,sBAAsB,EACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;IAG/B;;;;;;;OAOG;IACG,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/E;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAInC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC;IAIxC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAKhB;;;OAGG;IACH,oBAAoB,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAIxD;;;OAGG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACH,sBAAsB,IAAI,GAAG,CAAC,YAAY,CAAC;CAG3C"}

package/dist/src/transaction/context.js

@@ -0,0 +1,91 @@
+/**
+ * Transaction context for accumulating actions and reads.
+ *
+ * Usage:
+ *   const txn = coordinator.begin();
+ *   txn.addAction('users', { type: 'insert', data: {...} });
+ *   txn.addAction('users', { type: 'get', data: { key: 1 } });
+ *   const result = await txn.commit();
+ */
+export class TransactionContext {
+    coordinator;
+    transactionId;
+    engine;
+    collectionActions = new Map();
+    reads = [];
+    constructor(coordinator, transactionId, engine) {
+        this.coordinator = coordinator;
+        this.transactionId = transactionId;
+        this.engine = engine;
+    }
+    /**
+     * Add an action to a collection.
+     *
+     * Actions are collection-specific:
+     * - Tree: 'insert', 'delete', 'get', 'scan'
+     * - Diary: 'append', 'read'
+     * - etc.
+     */
+    async addAction(collectionId, action) {
+        // Tag action with transaction reference
+        const taggedAction = {
+            ...action,
+            transaction: this.transactionId
+        };
+        // Get the collection and immediately execute the action to update local snapshot
+        const collection = this.coordinator['collections'].get(collectionId);
+        if (collection) {
+            // Execute through collection to update tracker and pending buffer
+            await collection.act(taggedAction);
+        }
+        // If no collection registered, just buffer the action (for testing or deferred collection creation)
+        // Record in transaction context
+        if (!this.collectionActions.has(collectionId)) {
+            this.collectionActions.set(collectionId, []);
+        }
+        this.collectionActions.get(collectionId).push(taggedAction);
+    }
+    /**
+     * Add a read dependency for optimistic concurrency control.
+     */
+    addRead(read) {
+        this.reads.push(read);
+    }
+    /**
+     * Commit the transaction.
+     *
+     * This executes all accumulated actions across all affected collections,
+     * coordinating with the network as needed.
+     */
+    async commit() {
+        return await this.coordinator.commitTransaction(this);
+    }
+    /**
+     * Rollback the transaction (just discard accumulated state).
+     */
+    rollback() {
+        this.collectionActions.clear();
+        this.reads.length = 0;
+    }
+    /**
+     * Get all accumulated actions by collection.
+     * Used by coordinator during commit.
+     */
+    getCollectionActions() {
+        return this.collectionActions;
+    }
+    /**
+     * Get all accumulated read dependencies.
+     * Used by coordinator during commit.
+     */
+    getReads() {
+        return this.reads;
+    }
+    /**
+     * Get the set of affected collection IDs.
+     */
+    getAffectedCollections() {
+        return new Set(this.collectionActions.keys());
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/src/transaction/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/transaction/context.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IAKZ;IACD;IACA;IANA,iBAAiB,GAAqC,IAAI,GAAG,EAAE,CAAC;IAChE,KAAK,GAAqB,EAAE,CAAC;IAE9C,YACkB,WAAmC,EACpC,aAAqB,EACrB,MAAc;QAFb,gBAAW,GAAX,WAAW,CAAwB;QACpC,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAQ;IAC5B,CAAC;IAEJ;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,YAA0B,EAAE,MAAmB;QAC9D,wCAAwC;QACxC,MAAM,YAAY,GAAG;YACpB,GAAG,MAAM;YACT,WAAW,EAAE,IAAI,CAAC,aAAa;SAC/B,CAAC;QAEF,iFAAiF;QACjF,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACrE,IAAI,UAAU,EAAE,CAAC;YAChB,kEAAkE;YAClE,MAAM,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACpC,CAAC;QACD,oGAAoG;QAEpG,gCAAgC;QAChC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAoB;QAC3B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM;QACX,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,oBAAoB;QACnB,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,sBAAsB;QACrB,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;CACD"}

package/dist/src/transaction/coordinator.d.ts

@@ -0,0 +1,118 @@
+import type { ITransactor, CollectionId } from "../index.js";
+import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions } from "./transaction.js";
+import type { Collection } from "../collection/collection.js";
+import { TransactionContext } from "./context.js";
+/**
+ * Coordinates multi-collection transactions.
+ *
+ * This is the ONLY interface for all mutations (single or multi-collection).
+ *
+ * Responsibilities:
+ * - Manage collections (create as needed)
+ * - Apply actions to collections (run handlers, write to logs)
+ * - Commit transactions by running consensus phases (GATHER, PEND, COMMIT)
+ */
+export declare class TransactionCoordinator {
+    private readonly transactor;
+    private readonly collections;
+    constructor(transactor: ITransactor, collections: Map<CollectionId, Collection<any>>);
+    /**
+     * Apply actions to collections (called by engines during statement execution).
+     *
+     * This is the core method that engines call to apply actions to collections.
+     * Actions are tagged with the stamp ID and executed immediately through collections
+     * to update the local snapshot.
+     *
+     * @param actions - The actions to apply (per collection)
+     * @param stampId - The transaction stamp ID to tag actions with
+     */
+    applyActions(actions: CollectionActions[], stampId: string): Promise<void>;
+    /**
+     * Commit a transaction (actions already applied, orchestrate PEND/COMMIT).
+     *
+     * This is called by TransactionSession.commit() after all statements have been executed.
+     * Actions have already been applied to collections via applyActions(), so this method
+     * just orchestrates the distributed consensus.
+     *
+     * @param transaction - The transaction to commit
+     */
+    commit(transaction: Transaction): Promise<void>;
+    /**
+     * Rollback a transaction (undo applied actions).
+     *
+     * This is called by TransactionSession.rollback() to undo all actions
+     * that were applied via applyActions().
+     *
+     * @param _stampId - The transaction stamp ID to rollback (currently unused - we clear all trackers)
+     */
+    rollback(_stampId: string): Promise<void>;
+    /**
+     * Compute hash of all operations in a transaction.
+     * This hash is used for validation - validators re-execute the transaction
+     * and compare their computed operations hash with this one.
+     */
+    private hashOperations;
+    /**
+     * Commit a transaction context.
+     *
+     * @deprecated Use TransactionSession instead of TransactionContext
+     * This is called by TransactionContext.commit().
+     *
+     * @param context - The transaction context to commit
+     * @returns Execution result with actions and results
+     */
+    commitTransaction(context: TransactionContext): Promise<ExecutionResult>;
+    /**
+     * Execute a fully-formed transaction.
+     *
+     * This can be called directly with a complete transaction (e.g., from Quereus),
+     * or indirectly via commitTransaction().
+     *
+     * @param transaction - The transaction to execute
+     * @param engine - The engine to use for executing the transaction
+     * @returns Execution result with actions and results
+     */
+    execute(transaction: Transaction, engine: ITransactionEngine): Promise<ExecutionResult>;
+    /**
+     * Apply actions to a collection.
+     *
+     * This runs the action handlers, writes to the log, and collects transforms.
+     */
+    private applyActionsToCollection;
+    /**
+     * Coordinate a transaction across multiple collections.
+     *
+     * @param transaction - The transaction to coordinate
+     * @param operationsHash - Hash of all operations for validation
+     * @param collectionTransforms - Map of collectionId to its transforms
+     * @param criticalBlocks - Map of collectionId to its log tail blockId
+     */
+    private coordinateTransaction;
+    /**
+     * GATHER phase: Collect nominees from critical clusters.
+     *
+     * Skip if only one collection affected (single-collection consensus).
+     *
+     * @param criticalBlockIds - Block IDs of all log tails
+     * @returns Set of peer IDs to use for consensus, or null for single-collection
+     */
+    private gatherPhase;
+    /**
+     * PEND phase: Distribute transaction to all affected block clusters.
+     *
+     * @param transaction - The full transaction for replay/validation
+     * @param operationsHash - Hash of all operations for validation
+     * @param collectionTransforms - Map of collectionId to its transforms
+     * @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
+     */
+    private pendPhase;
+    /**
+     * COMMIT phase: Commit to all critical blocks.
+     */
+    private commitPhase;
+    /**
+     * CANCEL phase: Cancel pending actions on all affected blocks.
+     */
+    private cancelPhase;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/src/transaction/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAW,YAAY,EAA6E,MAAM,aAAa,CAAC;AACjJ,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE5G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAalD;;;;;;;;;GASG;AACH,qBAAa,sBAAsB;IAEjC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IAGjE;;;;;;;;;OASG;IACG,YAAY,CACjB,OAAO,EAAE,iBAAiB,EAAE,EAC5B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;OAQG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoErD;;;;;;;OAOG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;;OAQG;IACG,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAoC9E;;;;;;;;;OASG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsE7F;;;;OAIG;YACW,wBAAwB;IAyDtC;;;;;;;OAOG;YACW,qBAAqB;IAuCnC;;;;;;;OAOG;YACW,WAAW;IAgCzB;;;;;;;OAOG;YACW,SAAS;IAmDvB;;OAEG;YACW,WAAW;IAgDzB;;OAEG;YACW,WAAW;CAsBzB"}