@optimystic/db-core 0.5.1 → 0.6.0

package/src/transaction/coordinator.ts

@@ -1,11 +1,14 @@
 import type { ITransactor, BlockId, CollectionId, Transforms, PendRequest, CommitRequest, ActionId, IBlock, BlockOperations } from "../index.js";
-import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions } from "./transaction.js";
+import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
 import type { PeerId } from "../network/types.js";
 import type { Collection } from "../collection/collection.js";
 import { TransactionContext } from "./context.js";
-import { createActionsStatements } from "./actions-engine.js";
-import { createTransactionStamp, createTransactionId } from "./transaction.js";
+import { ActionsEngine } from "./actions-engine.js";
+import { createActionsStatements, createTransactionStamp, createTransactionId, isTransactionExpired } from "./transaction.js";
 import { Log, blockIdsForTransforms, transformsFromTransform, hashString } from "../index.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('trx:coordinator');
 
 /**
  * Represents an operation on a block within a collection.
@@ -70,6 +73,10 @@ export class TransactionCoordinator {
 	 * @param transaction - The transaction to commit
 	 */
 	async commit(transaction: Transaction): Promise<void> {
+		if (isTransactionExpired(transaction.stamp)) {
+			throw new Error(`Transaction expired at ${transaction.stamp.expiration}`);
+		}
+
 		// Collect transforms and determine critical blocks for each affected collection
 		const collectionData = Array.from(this.collections.entries())
 			.map(([collectionId, collection]) => ({
@@ -122,7 +129,7 @@ export class TransactionCoordinator {
 			)
 		]);
 
-		const operationsHash = this.hashOperations(allOperations);
+		const operationsHash = await this.hashOperations(allOperations);
 
 		// Execute consensus phases (GATHER, PEND, COMMIT)
 		const coordResult = await this.coordinateTransaction(
@@ -190,14 +197,34 @@ export class TransactionCoordinator {
 		}
 	}
 
+	/**
+	 * Collect read dependencies from all participating collections.
+	 */
+	getReadDependencies(): ReadDependency[] {
+		const reads: ReadDependency[] = [];
+		for (const collection of this.collections.values()) {
+			reads.push(...collection.getReadDependencies());
+		}
+		return reads;
+	}
+
+	/**
+	 * Clear read dependencies from all collections.
+	 */
+	clearReadDependencies(): void {
+		for (const collection of this.collections.values()) {
+			collection.clearReadDependencies();
+		}
+	}
+
 	/**
 	 * 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(operations: readonly Operation[]): string {
+	private async hashOperations(operations: readonly Operation[]): Promise<string> {
 		const operationsData = JSON.stringify(operations);
-		return `ops:${hashString(operationsData)}`;
+		return `ops:${await hashString(operationsData)}`;
 	}
 
 	/**
@@ -223,7 +250,7 @@ export class TransactionCoordinator {
 		const reads = context.getReads();
 
 		// Create stamp from context
-		const stamp = createTransactionStamp(
+		const stamp = await createTransactionStamp(
 			'local', // TODO: Get from context or coordinator
 			Date.now(),
 			'', // TODO: Get from engine
@@ -234,11 +261,9 @@ export class TransactionCoordinator {
 			stamp,
 			statements,
 			reads,
-			id: createTransactionId(stamp.id, statements, reads)
+			id: await createTransactionId(stamp.id, statements, reads)
 		};
 
-		// Create ActionsEngine for execution (TransactionContext only supports actions)
-		const { ActionsEngine } = await import('./actions-engine.js');
 		const engine = new ActionsEngine(this);
 
 		// Execute through standard path
@@ -256,12 +281,22 @@ export class TransactionCoordinator {
 	 * @returns Execution result with actions and results
 	 */
 	async execute(transaction: Transaction, engine: ITransactionEngine): Promise<ExecutionResult> {
+		const trxId = transaction.id;
+		const t0 = Date.now();
+
+		if (isTransactionExpired(transaction.stamp)) {
+			return { success: false, error: `Transaction expired at ${transaction.stamp.expiration}` };
+		}
+
 		// 1. Validate engine matches transaction
 		// Note: We don't enforce this strictly since the engine is passed in explicitly
 		// The caller is responsible for ensuring the correct engine is used
 
+		const tEngine = Date.now();
 		const result = await engine.execute(transaction);
+		const engineMs = Date.now() - tEngine;
 		if (!result.success) {
+			log('execute:done trxId=%s engine=%dms success=false total=%dms', trxId, engineMs, Date.now() - t0);
 			return result;
 		}
 
@@ -270,6 +305,7 @@ export class TransactionCoordinator {
 		}
 
 		// 2. Apply actions to collections and collect transforms
+		const tApply = Date.now();
 		const collectionTransforms = new Map<CollectionId, Transforms>();
 		const criticalBlocks = new Map<CollectionId, BlockId>();
 		const actionResults = new Map<CollectionId, any[]>();
@@ -303,9 +339,12 @@ export class TransactionCoordinator {
 				({ type: 'delete' as const, collectionId, blockId })
 			)
 		]);
-		const operationsHash = this.hashOperations(allOperations);
+		const operationsHash = await this.hashOperations(allOperations);
+
+		const applyMs = Date.now() - tApply;
 
 		// 4. Coordinate (GATHER if multi-collection)
+		const tCoord = Date.now();
 		const coordResult = await this.coordinateTransaction(
 			transaction,
 			operationsHash,
@@ -313,11 +352,31 @@ export class TransactionCoordinator {
 			criticalBlocks
 		);
 
+		const coordMs = Date.now() - tCoord;
 		if (!coordResult.success) {
+			log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms success=false total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
 			return coordResult;
 		}
 
-		// 4. Return results from actions
+		// 5. Update actionContext and reset trackers after successful commit
+		for (const collectionActions of result.actions) {
+			const collection = this.collections.get(collectionActions.collectionId);
+			if (collection) {
+				const newRev = (collection['source'].actionContext?.rev ?? 0) + 1;
+				const actionId = transaction.id;
+				collection['source'].actionContext = {
+					committed: [
+						...(collection['source'].actionContext?.committed ?? []),
+						{ actionId, rev: newRev }
+					],
+					rev: newRev,
+				};
+				collection.tracker.reset();
+			}
+		}
+
+		// 6. Return results from actions
+		log('execute:done trxId=%s engine=%dms apply=%dms coordinate=%dms total=%dms', trxId, engineMs, applyMs, coordMs, Date.now() - t0);
 		return {
 			success: true,
 			actions: result.actions,
@@ -401,36 +460,48 @@ export class TransactionCoordinator {
 		collectionTransforms: Map<CollectionId, Transforms>,
 		criticalBlocks: Map<CollectionId, BlockId>
 	): Promise<{ success: boolean; error?: string }> {
+		const trxId = transaction.id;
+		const t0 = Date.now();
+
 		// 1. GATHER phase: collect critical cluster nominees (skip if single collection)
 		const criticalBlockIds = Array.from(criticalBlocks.values());
+		const tGather = Date.now();
 		const superclusterNominees = await this.gatherPhase(criticalBlockIds);
+		const gatherMs = Date.now() - tGather;
 
 		// 2. PEND phase: distribute to all block clusters
+		const tPend = Date.now();
 		const pendResult = await this.pendPhase(
 			transaction,
 			operationsHash,
 			collectionTransforms,
 			superclusterNominees
 		);
+		const pendMs = Date.now() - tPend;
 		if (!pendResult.success) {
+			log('trx:phases trxId=%s gather=%dms pend=%dms (failed) total=%dms', trxId, gatherMs, pendMs, Date.now() - t0);
 			return pendResult;
 		}
 
 		// 3. COMMIT phase: commit to all critical blocks
+		const tCommit = Date.now();
 		const commitResult = await this.commitPhase(
 			transaction.id as ActionId,
 			criticalBlockIds,
 			pendResult.pendedBlockIds!
 		);
+		const commitMs = Date.now() - tCommit;
 		if (!commitResult.success) {
 			// Cancel pending actions on failure
 			await this.cancelPhase(transaction.id as ActionId, collectionTransforms);
+			log('trx:phases trxId=%s gather=%dms pend=%dms commit=%dms (failed) total=%dms', trxId, gatherMs, pendMs, commitMs, Date.now() - t0);
 			return commitResult;
 		}
 
 		// 4. PROPAGATE and CHECKPOINT phases are handled by clusters automatically
 		// (as per user's note: "managed by each cluster, the client doesn't have to worry about them")
 
+		log('trx:phases trxId=%s gather=%dms pend=%dms commit=%dms total=%dms', trxId, gatherMs, pendMs, commitMs, Date.now() - t0);
 		return { success: true };
 	}
 
@@ -520,6 +591,10 @@ export class TransactionCoordinator {
 			// Pend the transaction
 			const pendResult = await this.transactor.pend(pendRequest);
 			if (!pendResult.success) {
+				// Cancel any already-pended collections before returning
+				for (const [pendedCollectionId, pendedBlockIdList] of pendedBlockIds.entries()) {
+					await this.transactor.cancel({ actionId, blockIds: pendedBlockIdList });
+				}
 				return {
 					success: false,
 					error: `Pend failed for collection ${collectionId}: ${pendResult.reason}`

package/src/transaction/index.ts

@@ -7,24 +7,25 @@ export type {
 	ExecutionResult,
 	CollectionActions,
 	ValidationResult,
-	ITransactionValidator
+	ITransactionValidator,
+	ActionsStatement
 } from './transaction.js';
 
 export {
 	createTransactionStamp,
-	createTransactionId
+	createTransactionId,
+	createActionsStatements,
+	DEFAULT_TRANSACTION_TTL_MS,
+	isTransactionExpired
 } from './transaction.js';
 
 export {
 	ActionsEngine,
 	ACTIONS_ENGINE_ID,
-	createActionsStatements
 } from './actions-engine.js';
 
-export type { ActionsStatement } from './actions-engine.js';
-
 export { TransactionCoordinator } from './coordinator.js';
 export { TransactionContext } from './context.js';
 export { TransactionSession } from './session.js';
 export { TransactionValidator } from './validator.js';
-export type { EngineRegistration, ValidationCoordinatorFactory } from './validator.js';
+export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';

package/src/transaction/session.ts

@@ -1,6 +1,6 @@
 import type { TransactionCoordinator } from "./coordinator.js";
 import type { Transaction, ExecutionResult, ITransactionEngine, TransactionStamp, CollectionActions } from "./transaction.js";
-import { createTransactionStamp, createTransactionId } from "./transaction.js";
+import { createTransactionStamp, createTransactionId, isTransactionExpired } from "./transaction.js";
 
 /**
  * TransactionSession manages incremental transaction building.
@@ -14,7 +14,7 @@ import { createTransactionStamp, createTransactionId } from "./transaction.js";
  * - The Transaction is then committed through coordinator.commit() for PEND/COMMIT orchestration
  *
  * Usage:
- *   const session = new TransactionSession(coordinator, engine);
+ *   const session = await TransactionSession.create(coordinator, engine);
  *   await session.execute('INSERT INTO users (id, name) VALUES (?, ?)', [1, 'Alice']);
  *   await session.execute('SELECT * FROM orders WHERE user_id = ?', [1]);
  *   const result = await session.commit();
@@ -27,19 +27,33 @@ export class TransactionSession {
 	private committed = false;
 	private rolledBack = false;
 
-	constructor(
+	private constructor(
 		private readonly coordinator: TransactionCoordinator,
 		private readonly engine: ITransactionEngine,
-		peerId: string = 'local', // TODO: Get from coordinator or config
-		schemaHash: string = '' // TODO: Get from engine
+		stamp: TransactionStamp
 	) {
-		// Create stamp at BEGIN (stable throughout transaction)
-		this.stamp = createTransactionStamp(
+		this.stamp = stamp;
+	}
+
+	/**
+	 * Create a new TransactionSession.
+	 * Uses async factory because stamp creation requires SHA-256 hashing.
+	 */
+	static async create(
+		coordinator: TransactionCoordinator,
+		engine: ITransactionEngine,
+		peerId: string = 'local',
+		schemaHash: string = '',
+		ttlMs?: number
+	): Promise<TransactionSession> {
+		const stamp = await createTransactionStamp(
 			peerId,
 			Date.now(),
 			schemaHash,
-			'unknown' // TODO: Get engine ID from engine
+			'unknown', // TODO: Get engine ID from engine
+			ttlMs
 		);
+		return new TransactionSession(coordinator, engine, stamp);
 	}
 
 	/**
@@ -107,18 +121,27 @@ export class TransactionSession {
 		if (this.rolledBack) {
 			return { success: false, error: 'Transaction already rolled back' };
 		}
+		if (isTransactionExpired(this.stamp)) {
+			return { success: false, error: `Transaction expired at ${this.stamp.expiration}` };
+		}
+
+		// Collect read dependencies from all participating collections
+		const reads = this.coordinator.getReadDependencies();
 
 		// Create the complete transaction
 		const transaction: Transaction = {
 			stamp: this.stamp,
 			statements: this.statements,
-			reads: [], // TODO: Track reads during statement execution
-			id: createTransactionId(this.stamp.id, this.statements, [])
+			reads,
+			id: await createTransactionId(this.stamp.id, this.statements, reads)
 		};
 
 		// Commit through coordinator (which will orchestrate PEND/COMMIT)
 		await this.coordinator.commit(transaction);
 
+		// Clear read dependencies after successful commit
+		this.coordinator.clearReadDependencies();
+
 		this.committed = true;
 		return { success: true };
 	}
@@ -140,6 +163,7 @@ export class TransactionSession {
 
 		// Rollback through coordinator
 		await this.coordinator.rollback(this.stamp.id);
+		this.coordinator.clearReadDependencies();
 		this.rolledBack = true;
 		this.statements.length = 0;
 	}

package/src/transaction/transaction.ts

@@ -21,6 +21,9 @@ export type TransactionStamp = {
 	/** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
 	engineId: string;
 
+	/** Absolute ms epoch after which transaction is invalid */
+	expiration: number;
+
 	/** Hash of the stamp fields (computed) - stable identifier throughout transaction */
 	id: string;
 };
@@ -67,32 +70,42 @@ export type ReadDependency = {
  */
 export type TransactionRef = string; // The transaction ID
 
+/** Default transaction time-to-live in milliseconds (30 seconds). */
+export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
+
+/** Check whether a transaction stamp has expired. */
+export function isTransactionExpired(stamp: TransactionStamp): boolean {
+	return Date.now() > stamp.expiration;
+}
+
 /**
  * Create a transaction stamp with computed id.
- * The id is a hash of the stamp fields.
+ * The id is a hash of the stamp fields (including expiration).
  */
-export function createTransactionStamp(
+export async function createTransactionStamp(
 	peerId: string,
 	timestamp: number,
 	schemaHash: string,
-	engineId: string
-): TransactionStamp {
-	const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId });
-	const id = `stamp:${hashString(stampData)}`;
-	return { peerId, timestamp, schemaHash, engineId, id };
+	engineId: string,
+	ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
+): Promise<TransactionStamp> {
+	const expiration = timestamp + ttlMs;
+	const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration });
+	const id = `stamp:${await hashString(stampData)}`;
+	return { peerId, timestamp, schemaHash, engineId, expiration, id };
 }
 
 /**
  * Create a transaction id from stamp id, statements, and reads.
  * This is the final transaction identity used in logs.
  */
-export function createTransactionId(
+export async function createTransactionId(
 	stampId: string,
 	statements: string[],
 	reads: ReadDependency[]
-): string {
+): Promise<string> {
 	const txData = JSON.stringify({ stampId, statements, reads });
-	return `tx:${hashString(txData)}`;
+	return `tx:${await hashString(txData)}`;
 }
 
 
@@ -144,6 +157,22 @@ export type CollectionActions = {
 	actions: unknown[];
 };
 
+/**
+ * Helper to create an actions-based transaction statements array.
+ * Each CollectionActions becomes a separate JSON-encoded statement.
+ */
+export function createActionsStatements(collections: CollectionActions[]): string[] {
+	return collections.map(c => JSON.stringify(c));
+}
+
+/**
+ * Statement format for the actions engine (array of CollectionActions).
+ * @deprecated Use CollectionActions[] directly
+ */
+export type ActionsStatement = {
+	collections: CollectionActions[];
+};
+
 /**
  * Result of transaction validation.
  */

package/src/transaction/validator.ts

@@ -1,5 +1,7 @@
 import type { BlockId, CollectionId, IBlock, BlockOperations, Transforms, ITransactor } from '../index.js';
-import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions } from './transaction.js';
+import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions, ReadDependency } from './transaction.js';
+import type { BlockActionState } from '../network/struct.js';
+import { isTransactionExpired } from './transaction.js';
 import type { Collection } from '../collection/collection.js';
 import { Tracker } from '../transform/tracker.js';
 import { hashString } from '../utility/hash-string.js';
@@ -36,6 +38,12 @@ export type ValidationCoordinatorFactory = () => {
 	dispose(): void;
 };
 
+/**
+ * Provides current block state for read dependency validation.
+ * Returns the latest BlockActionState for a given block, or undefined if the block doesn't exist.
+ */
+export type BlockStateProvider = (blockId: BlockId) => Promise<BlockActionState | undefined>;
+
 /**
  * Transaction validator implementation.
  *
@@ -45,12 +53,21 @@ export type ValidationCoordinatorFactory = () => {
 export class TransactionValidator implements ITransactionValidator {
 	constructor(
 		private readonly engines: Map<string, EngineRegistration>,
-		private readonly createValidationCoordinator: ValidationCoordinatorFactory
+		private readonly createValidationCoordinator: ValidationCoordinatorFactory,
+		private readonly blockStateProvider?: BlockStateProvider
 	) {}
 
 	async validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult> {
 		const { stamp, statements } = transaction;
 
+		// 0. Check expiration before any other work
+		if (isTransactionExpired(stamp)) {
+			return {
+				valid: false,
+				reason: `Transaction expired at ${stamp.expiration}`
+			};
+		}
+
 		// 1. Verify engine exists
 		const registration = this.engines.get(stamp.engineId);
 		if (!registration) {
@@ -70,8 +87,18 @@ export class TransactionValidator implements ITransactionValidator {
 		}
 
 		// 3. Verify read dependencies (optimistic concurrency)
-		// TODO: Implement read dependency validation
-		// For now, we skip this check - will be implemented with proper block versioning
+		if (this.blockStateProvider && transaction.reads.length > 0) {
+			for (const read of transaction.reads) {
+				const currentState = await this.blockStateProvider(read.blockId);
+				const currentRev = currentState?.latest?.rev ?? 0;
+				if (currentRev !== read.revision) {
+					return {
+						valid: false,
+						reason: `Stale read: block ${read.blockId} was at revision ${read.revision} but is now at ${currentRev}`
+					};
+				}
+			}
+		}
 
 		// 4. Create isolated validation coordinator
 		const validationCoordinator = this.createValidationCoordinator();
@@ -96,7 +123,7 @@ export class TransactionValidator implements ITransactionValidator {
 			const allOperations = this.collectOperations(transforms);
 
 			// 8. Compute hash
-			const computedHash = this.hashOperations(allOperations);
+			const computedHash = await this.hashOperations(allOperations);
 
 			// 9. Compare with sender's hash
 			if (computedHash !== operationsHash) {
@@ -139,9 +166,9 @@ export class TransactionValidator implements ITransactionValidator {
 	 * Compute hash of all operations.
 	 * Must match TransactionCoordinator.hashOperations for consistent validation.
 	 */
-	private hashOperations(operations: readonly Operation[]): string {
+	private async hashOperations(operations: readonly Operation[]): Promise<string> {
 		const operationsData = JSON.stringify(operations);
-		return `ops:${hashString(operationsData)}`;
+		return `ops:${await hashString(operationsData)}`;
 	}
 }