@optimystic/db-core 0.0.1

package/src/transaction/session.ts

@@ -0,0 +1,182 @@
+import type { TransactionCoordinator } from "./coordinator.js";
+import type { Transaction, ExecutionResult, ITransactionEngine, TransactionStamp, CollectionActions } from "./transaction.js";
+import { createTransactionStamp, createTransactionId } from "./transaction.js";
+
+/**
+ * TransactionSession manages incremental transaction building.
+ *
+ * This is the high-level API for building transactions incrementally:
+ * - Stamp is created at BEGIN (stable throughout transaction)
+ * - Execute statements one at a time
+ * - Engine translates statements to actions (if not already provided)
+ * - Actions are immediately applied to collections via coordinator.applyActions()
+ * - On commit, all statements are compiled into a complete Transaction
+ * - The Transaction is then committed through coordinator.commit() for PEND/COMMIT orchestration
+ *
+ * Usage:
+ *   const session = new TransactionSession(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();
+ *
+ * For validation/replay, use engine.execute() directly with a complete Transaction.
+ */
+export class TransactionSession {
+	private readonly statements: string[] = [];
+	private readonly stamp: TransactionStamp;
+	private committed = false;
+	private rolledBack = false;
+
+	constructor(
+		private readonly coordinator: TransactionCoordinator,
+		private readonly engine: ITransactionEngine,
+		peerId: string = 'local', // TODO: Get from coordinator or config
+		schemaHash: string = '' // TODO: Get from engine
+	) {
+		// Create stamp at BEGIN (stable throughout transaction)
+		this.stamp = createTransactionStamp(
+			peerId,
+			Date.now(),
+			schemaHash,
+			'unknown' // TODO: Get engine ID from engine
+		);
+	}
+
+	/**
+	 * Execute a statement.
+	 *
+	 * If actions are provided, they are applied directly.
+	 * Otherwise, the engine translates the statement to actions.
+	 *
+	 * @param statement - The statement to execute (engine-specific, e.g., SQL statement)
+	 * @param actions - Optional pre-computed actions (for Quereus module case)
+	 * @returns Execution result with any returned values
+	 */
+	async execute(statement: string, actions?: CollectionActions[]): Promise<{ success: boolean; error?: string }> {
+		if (this.committed) {
+			return { success: false, error: 'Transaction already committed' };
+		}
+		if (this.rolledBack) {
+			return { success: false, error: 'Transaction already rolled back' };
+		}
+
+		try {
+			// If actions not provided, enlist engine to translate statement
+			let actionsToApply: CollectionActions[];
+			if (actions) {
+				actionsToApply = actions;
+			} else {
+				// Create a temporary transaction with just this statement for translation
+				const tempTransaction: Transaction = {
+					stamp: this.stamp,
+					statements: [statement],
+					reads: [],
+					id: 'temp' // Temporary ID for translation only
+				};
+				const result = await this.engine.execute(tempTransaction);
+				if (!result.success || !result.actions) {
+					return { success: false, error: result.error || 'Failed to translate statement' };
+				}
+				actionsToApply = result.actions;
+			}
+
+			// Apply actions through coordinator
+			await this.coordinator.applyActions(actionsToApply, this.stamp.id);
+
+			// Accumulate the statement for later compilation
+			this.statements.push(statement);
+
+			return { success: true };
+		} catch (error) {
+			return {
+				success: false,
+				error: `Failed to execute statement: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+	}
+
+	/**
+	 * Commit the transaction.
+	 *
+	 * Compiles all statements into a complete Transaction and commits through coordinator.
+	 */
+	async commit(): Promise<ExecutionResult> {
+		if (this.committed) {
+			return { success: false, error: 'Transaction already committed' };
+		}
+		if (this.rolledBack) {
+			return { success: false, error: 'Transaction already rolled back' };
+		}
+
+		// 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, [])
+		};
+
+		// Commit through coordinator (which will orchestrate PEND/COMMIT)
+		await this.coordinator.commit(transaction);
+
+		this.committed = true;
+		return { success: true };
+	}
+
+	/**
+	 * Rollback the transaction (discard local state).
+	 *
+	 * Note: Actions have already been applied to collections' trackers.
+	 * Rollback just prevents commit and clears session state.
+	 * Collections will discard tracker state when they sync or update.
+	 */
+	async rollback(): Promise<void> {
+		if (this.committed) {
+			throw new Error('Cannot rollback: transaction already committed');
+		}
+		if (this.rolledBack) {
+			throw new Error('Transaction already rolled back');
+		}
+
+		// Rollback through coordinator
+		await this.coordinator.rollback(this.stamp.id);
+		this.rolledBack = true;
+		this.statements.length = 0;
+	}
+
+	/**
+	 * Get the transaction stamp ID (stable throughout transaction).
+	 */
+	getStampId(): string {
+		return this.stamp.id;
+	}
+
+	/**
+	 * Get the transaction stamp (full metadata).
+	 */
+	getStamp(): TransactionStamp {
+		return this.stamp;
+	}
+
+	/**
+	 * Get the list of accumulated statements.
+	 */
+	getStatements(): readonly string[] {
+		return this.statements;
+	}
+
+	/**
+	 * Check if the transaction has been committed.
+	 */
+	isCommitted(): boolean {
+		return this.committed;
+	}
+
+	/**
+	 * Check if the transaction has been rolled back.
+	 */
+	isRolledBack(): boolean {
+		return this.rolledBack;
+	}
+}
+

package/src/transaction/transaction.ts

@@ -0,0 +1,205 @@
+import type { BlockId } from "../blocks/index.js";
+import type { CollectionId } from "../collection/index.js";
+
+/**
+ * Transaction Stamp: Created at BEGIN, stable throughout transaction lifecycle.
+ *
+ * The stamp contains metadata about the transaction's origin and context.
+ * The id is computed as a hash of these fields.
+ */
+export type TransactionStamp = {
+	/** Peer that initiated the transaction */
+	peerId: string;
+
+	/** When transaction started (milliseconds since epoch) */
+	timestamp: number;
+
+	/** Hash of schema version(s) for validation */
+	schemaHash: string;
+
+	/** Which engine (e.g., 'quereus@0.5.3', 'actions@1.0.0') */
+	engineId: string;
+
+	/** Hash of the stamp fields (computed) - stable identifier throughout transaction */
+	id: string;
+};
+
+/**
+ * Transaction: Finalized at COMMIT with complete statement history.
+ *
+ * Transactions span multiple collections and use pluggable engines for interpreting the statements.
+ * The engine re-executes the statements to verify the resulting operations match what was proposed.
+ */
+export type Transaction = {
+	/** The transaction stamp (includes stable id) */
+	stamp: TransactionStamp;
+
+	/** Engine-specific statements (for replay/validation)
+	 * Array of statements executed during the transaction.
+	 * - For Quereus: SQL statements
+	 * - For ActionsEngine: JSON-encoded actions
+	 */
+	statements: string[];
+
+	/** Read dependencies for optimistic concurrency control */
+	reads: ReadDependency[];
+
+	/** Transaction identifier (hash of stamp.id + statements + reads)
+	 * Final transaction identity, used in logs
+	 */
+	id: string;
+};
+
+/**
+ * Read dependency for optimistic concurrency control.
+ * Tracks which block revisions were read during transaction execution.
+ */
+export type ReadDependency = {
+	blockId: BlockId;
+	/** Expected revision number at time of read */
+	revision: number;
+};
+
+/**
+ * Transaction reference embedded in actions.
+ * Just the transaction ID - full transaction can be looked up separately if needed.
+ */
+export type TransactionRef = string; // The transaction ID
+
+/**
+ * Create a transaction stamp with computed id.
+ * The id is a hash of the stamp fields.
+ */
+export 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 };
+}
+
+/**
+ * Create a transaction id from stamp id, statements, and reads.
+ * This is the final transaction identity used in logs.
+ */
+export function createTransactionId(
+	stampId: string,
+	statements: string[],
+	reads: ReadDependency[]
+): string {
+	const txData = JSON.stringify({ stampId, statements, reads });
+	return `tx:${hashString(txData)}`;
+}
+
+/**
+ * Simple hash function for creating IDs.
+ * Uses a basic hash for now - can be replaced with proper cryptographic hash later.
+ */
+function hashString(str: string): string {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = ((hash << 5) - hash) + char;
+		hash = hash & hash; // Convert to 32-bit integer
+	}
+	return Math.abs(hash).toString(36);
+}
+
+/**
+ * Transaction engine interface.
+ * Pluggable engines implement this to process transaction statements.
+ *
+ * Engines are responsible for:
+ * 1. Parsing the engine-specific statements
+ * 2. Executing/re-executing to produce actions
+ * 3. Returning the resulting actions per collection
+ */
+export interface ITransactionEngine {
+	/**
+	 * Process a transaction statements to produce actions.
+	 *
+	 * Used both for:
+	 * - Initial execution (client creating transaction)
+	 * - Re-execution (validators verifying transaction)
+	 *
+	 * @param transaction - The transaction to process
+	 * @returns The resulting actions from execution
+	 */
+	execute(transaction: Transaction): Promise<ExecutionResult>;
+}
+
+/**
+ * Result of transaction execution.
+ */
+export type ExecutionResult = {
+	/** Whether execution succeeded */
+	success: boolean;
+	/** Actions produced by executing the transaction */
+	actions?: CollectionActions[];
+	/** Results from executing actions (e.g., return values from reads) */
+	results?: Map<CollectionId, any[]>;
+	/** Error message if execution failed */
+	error?: string;
+};
+
+/**
+ * Actions for a specific collection resulting from transaction execution.
+ */
+export type CollectionActions = {
+	/** Collection identifier */
+	collectionId: string;
+	/** Actions to apply to this collection */
+	actions: unknown[];
+};
+
+/**
+ * Result of transaction validation.
+ */
+export type ValidationResult = {
+	/** Whether validation succeeded */
+	valid: boolean;
+	/** Reason for validation failure (if valid=false) */
+	reason?: string;
+	/** The operations hash computed during validation (for debugging) */
+	computedHash?: string;
+};
+
+/**
+ * Transaction validator interface.
+ * Pluggable validators implement this to verify transaction integrity.
+ *
+ * Validators are invoked when a node receives a PendRequest with a transaction.
+ * They re-execute the transaction and verify the operations match.
+ */
+export interface ITransactionValidator {
+	/**
+	 * Validate a transaction by re-executing and comparing operations hash.
+	 *
+	 * Validation steps:
+	 * 1. Verify stamp.engineId matches a known engine
+	 * 2. Verify stamp.schemaHash matches local schema
+	 * 3. Verify read dependencies (no stale reads)
+	 * 4. Re-execute transaction.statements through engine (isolated state)
+	 * 5. Collect operations from re-execution
+	 * 6. Compute hash of operations
+	 * 7. Compare with sender's operationsHash
+	 *
+	 * @param transaction - The transaction to validate
+	 * @param operationsHash - The hash to compare against
+	 * @returns Validation result
+	 */
+	validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
+
+	/**
+	 * Get the schema hash for a given engine.
+	 * Used to verify the sender's schema matches local schema.
+	 *
+	 * @param engineId - The engine identifier
+	 * @returns The schema hash, or undefined if engine not found
+	 */
+	getSchemaHash(engineId: string): Promise<string | undefined>;
+}
+

package/src/transaction/validator.ts

@@ -0,0 +1,150 @@
+import type { BlockId, CollectionId, IBlock, BlockOperations, Transforms, ITransactor } from '../index.js';
+import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions } from './transaction.js';
+import type { Collection } from '../collection/collection.js';
+import { Tracker } from '../transform/tracker.js';
+
+/**
+ * Represents an operation on a block within a collection.
+ * Must match the Operation type in coordinator.ts for consistent hashing.
+ */
+type Operation =
+	| { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
+	| { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
+	| { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
+
+/**
+ * Engine registration for validation.
+ */
+export type EngineRegistration = {
+	/** The transaction engine instance */
+	engine: ITransactionEngine;
+	/** Get the current schema hash for this engine */
+	getSchemaHash: () => Promise<string>;
+};
+
+/**
+ * Factory function to create a validation coordinator.
+ * This allows isolated execution of transactions for validation.
+ */
+export type ValidationCoordinatorFactory = () => {
+	/** Apply actions to collections in isolated state */
+	applyActions(actions: CollectionActions[], stampId: string): Promise<void>;
+	/** Get all transforms from the validation state */
+	getTransforms(): Map<CollectionId, Transforms>;
+	/** Dispose of the validation coordinator */
+	dispose(): void;
+};
+
+/**
+ * Transaction validator implementation.
+ *
+ * Validates transactions by re-executing them and comparing operations hash.
+ * Used by cluster participants when receiving PendRequests.
+ */
+export class TransactionValidator implements ITransactionValidator {
+	constructor(
+		private readonly engines: Map<string, EngineRegistration>,
+		private readonly createValidationCoordinator: ValidationCoordinatorFactory
+	) {}
+
+	async validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult> {
+		const { stamp, statements } = transaction;
+
+		// 1. Verify engine exists
+		const registration = this.engines.get(stamp.engineId);
+		if (!registration) {
+			return {
+				valid: false,
+				reason: `Unknown engine: ${stamp.engineId}`
+			};
+		}
+
+		// 2. Verify schema hash matches
+		const localSchemaHash = await registration.getSchemaHash();
+		if (localSchemaHash !== stamp.schemaHash) {
+			return {
+				valid: false,
+				reason: `Schema mismatch: local=${localSchemaHash}, sender=${stamp.schemaHash}`
+			};
+		}
+
+		// 3. Verify read dependencies (optimistic concurrency)
+		// TODO: Implement read dependency validation
+		// For now, we skip this check - will be implemented with proper block versioning
+
+		// 4. Create isolated validation coordinator
+		const validationCoordinator = this.createValidationCoordinator();
+
+		try {
+			// 5. Re-execute transaction through engine
+			const result = await registration.engine.execute(transaction);
+			if (!result.success) {
+				return {
+					valid: false,
+					reason: `Re-execution failed: ${result.error}`
+				};
+			}
+
+			// 6. Apply actions to validation coordinator (builds transforms)
+			if (result.actions && result.actions.length > 0) {
+				await validationCoordinator.applyActions(result.actions, stamp.id);
+			}
+
+			// 7. Collect operations from validation coordinator
+			const transforms = validationCoordinator.getTransforms();
+			const allOperations = this.collectOperations(transforms);
+
+			// 8. Compute hash
+			const computedHash = this.hashOperations(allOperations);
+
+			// 9. Compare with sender's hash
+			if (computedHash !== operationsHash) {
+				return {
+					valid: false,
+					reason: `Operations hash mismatch`,
+					computedHash
+				};
+			}
+
+			return { valid: true, computedHash };
+		} finally {
+			validationCoordinator.dispose();
+		}
+	}
+
+	async getSchemaHash(engineId: string): Promise<string | undefined> {
+		const registration = this.engines.get(engineId);
+		return registration ? await registration.getSchemaHash() : undefined;
+	}
+
+	/**
+	 * Collect all operations from transforms.
+	 */
+	private collectOperations(transforms: Map<CollectionId, Transforms>): readonly Operation[] {
+		return Array.from(transforms.entries()).flatMap(([collectionId, t]) => [
+			...Object.entries(t.inserts).map(([blockId, block]) =>
+				({ type: 'insert' as const, collectionId, blockId, block })
+			),
+			...Object.entries(t.updates).map(([blockId, operations]) =>
+				({ type: 'update' as const, collectionId, blockId, operations })
+			),
+			...t.deletes.map(blockId =>
+				({ type: 'delete' as const, collectionId, blockId })
+			)
+		]);
+	}
+
+	/**
+	 * Compute hash of all operations.
+	 * Must match TransactionCoordinator.hashOperations for consistent validation.
+	 */
+	private hashOperations(operations: readonly Operation[]): string {
+		const operationsData = JSON.stringify(operations);
+		const hash = Array.from(operationsData).reduce((acc, char) => {
+			const charCode = char.charCodeAt(0);
+			return ((acc << 5) - acc + charCode) & acc;
+		}, 0);
+		return `ops:${Math.abs(hash).toString(36)}`;
+	}
+}
+

package/src/transactor/index.ts

@@ -0,0 +1,4 @@
+export * from "./network-transactor.js";
+export * from "./transactor-source.js";
+export * from "./transactor.js";
+