@optimystic/db-core 0.0.1

package/dist/src/transaction/session.js

@@ -0,0 +1,161 @@
+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 {
+    coordinator;
+    engine;
+    statements = [];
+    stamp;
+    committed = false;
+    rolledBack = false;
+    constructor(coordinator, engine, peerId = 'local', // TODO: Get from coordinator or config
+    schemaHash = '' // TODO: Get from engine
+    ) {
+        this.coordinator = coordinator;
+        this.engine = 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, actions) {
+        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;
+            if (actions) {
+                actionsToApply = actions;
+            }
+            else {
+                // Create a temporary transaction with just this statement for translation
+                const tempTransaction = {
+                    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() {
+        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 = {
+            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() {
+        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() {
+        return this.stamp.id;
+    }
+    /**
+     * Get the transaction stamp (full metadata).
+     */
+    getStamp() {
+        return this.stamp;
+    }
+    /**
+     * Get the list of accumulated statements.
+     */
+    getStatements() {
+        return this.statements;
+    }
+    /**
+     * Check if the transaction has been committed.
+     */
+    isCommitted() {
+        return this.committed;
+    }
+    /**
+     * Check if the transaction has been rolled back.
+     */
+    isRolledBack() {
+        return this.rolledBack;
+    }
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/transaction/session.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,156 @@
+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;
+/**
+ * Create a transaction stamp with computed id.
+ * The id is a hash of the stamp fields.
+ */
+export declare function createTransactionStamp(peerId: string, timestamp: number, schemaHash: string, engineId: string): TransactionStamp;
+/**
+ * Create a transaction id from stamp id, statements, and reads.
+ * This is the final transaction identity used in logs.
+ */
+export declare function createTransactionId(stampId: string, statements: string[], reads: ReadDependency[]): string;
+/**
+ * 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>;
+}
+//# sourceMappingURL=transaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAElB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IAEjB,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,iDAAiD;IACjD,KAAK,EAAE,gBAAgB,CAAC;IAExB;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB,2DAA2D;IAC3D,KAAK,EAAE,cAAc,EAAE,CAAC;IAExB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,gBAAgB,CAIlB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,cAAc,EAAE,GACrB,MAAM,CAGR;AAgBD;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC9B,sEAAsE;IACtE,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;IACnC,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC/B,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,EAAE,OAAO,EAAE,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEtF;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7D"}

package/dist/src/transaction/transaction.js

@@ -0,0 +1,31 @@
+/**
+ * Create a transaction stamp with computed id.
+ * The id is a hash of the stamp fields.
+ */
+export function createTransactionStamp(peerId, timestamp, schemaHash, engineId) {
+    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, statements, reads) {
+    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) {
+    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);
+}
+//# sourceMappingURL=transaction.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"AAoEA;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAAc,EACd,SAAiB,EACjB,UAAkB,EAClB,QAAgB;IAEhB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9E,MAAM,EAAE,GAAG,SAAS,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAClC,OAAe,EACf,UAAoB,EACpB,KAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,OAAO,MAAM,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,GAAW;IAC9B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QACnC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,4BAA4B;IACjD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC"}

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

@@ -0,0 +1,46 @@
+import type { CollectionId, Transforms } from '../index.js';
+import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions } from './transaction.js';
+/**
+ * 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 declare class TransactionValidator implements ITransactionValidator {
+    private readonly engines;
+    private readonly createValidationCoordinator;
+    constructor(engines: Map<string, EngineRegistration>, createValidationCoordinator: ValidationCoordinatorFactory);
+    validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
+    getSchemaHash(engineId: string): Promise<string | undefined>;
+    /**
+     * Collect all operations from transforms.
+     */
+    private collectOperations;
+    /**
+     * Compute hash of all operations.
+     * Must match TransactionCoordinator.hashOperations for consistent validation.
+     */
+    private hashOperations;
+}
+//# sourceMappingURL=validator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,YAAY,EAA2B,UAAU,EAAe,MAAM,aAAa,CAAC;AAC3G,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAapI;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,sCAAsC;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,kDAAkD;IAClD,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,MAAM;IAChD,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,mDAAmD;IACnD,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC/C,4CAA4C;IAC5C,OAAO,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,qBAAqB;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,2BAA2B;gBAD3B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACxC,2BAA2B,EAAE,4BAA4B;IAGrE,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiErF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAKlE;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;OAGG;IACH,OAAO,CAAC,cAAc;CAQtB"}

package/dist/src/transaction/validator.js

@@ -0,0 +1,97 @@
+import { Tracker } from '../transform/tracker.js';
+/**
+ * Transaction validator implementation.
+ *
+ * Validates transactions by re-executing them and comparing operations hash.
+ * Used by cluster participants when receiving PendRequests.
+ */
+export class TransactionValidator {
+    engines;
+    createValidationCoordinator;
+    constructor(engines, createValidationCoordinator) {
+        this.engines = engines;
+        this.createValidationCoordinator = createValidationCoordinator;
+    }
+    async validate(transaction, operationsHash) {
+        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) {
+        const registration = this.engines.get(engineId);
+        return registration ? await registration.getSchemaHash() : undefined;
+    }
+    /**
+     * Collect all operations from transforms.
+     */
+    collectOperations(transforms) {
+        return Array.from(transforms.entries()).flatMap(([collectionId, t]) => [
+            ...Object.entries(t.inserts).map(([blockId, block]) => ({ type: 'insert', collectionId, blockId, block })),
+            ...Object.entries(t.updates).map(([blockId, operations]) => ({ type: 'update', collectionId, blockId, operations })),
+            ...t.deletes.map(blockId => ({ type: 'delete', collectionId, blockId }))
+        ]);
+    }
+    /**
+     * Compute hash of all operations.
+     * Must match TransactionCoordinator.hashOperations for consistent validation.
+     */
+    hashOperations(operations) {
+        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)}`;
+    }
+}
+//# sourceMappingURL=validator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"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"}

package/dist/src/transactor/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./network-transactor.js";
+export * from "./transactor-source.js";
+export * from "./transactor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/transactor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transactor/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC"}

package/dist/src/transactor/index.js

@@ -0,0 +1,4 @@
+export * from "./network-transactor.js";
+export * from "./transactor-source.js";
+export * from "./transactor.js";
+//# sourceMappingURL=index.js.map

package/dist/src/transactor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/transactor/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC"}

package/dist/src/transactor/network-transactor.d.ts

@@ -0,0 +1,36 @@
+import { type PeerId } from "@libp2p/interface";
+import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, CommitRequest, ClusterNomineesResult } from "../index.js";
+type NetworkTransactorInit = {
+    timeoutMs: number;
+    abortOrCancelTimeoutMs: number;
+    keyNetwork: IKeyNetwork;
+    getRepo: (peerId: PeerId) => IRepo;
+};
+export declare class NetworkTransactor implements ITransactor {
+    private readonly keyNetwork;
+    private readonly timeoutMs;
+    private readonly abortOrCancelTimeoutMs;
+    private readonly getRepo;
+    constructor(init: NetworkTransactorInit);
+    get(blockGets: BlockGets): Promise<GetBlockResults>;
+    getStatus(blockActions: ActionBlocks[]): Promise<BlockActionStatus[]>;
+    private consolidateCoordinators;
+    pend(blockAction: PendRequest): Promise<PendResult>;
+    cancel(actionRef: ActionBlocks): Promise<void>;
+    queryClusterNominees(blockId: BlockId): Promise<ClusterNomineesResult>;
+    commit(request: CommitRequest): Promise<CommitResult>;
+    private commitBlock;
+    /** Attempts to commit a set of blocks, and handles failures and errors */
+    private commitBlocks;
+    /** Creates batches for a given payload, grouped by the coordinating peer for each block id */
+    private batchesForPayload;
+    /** Cancels a pending transaction by canceling all blocks associated with the transaction, including failed peers */
+    private cancelBatch;
+    private formatBatchStatuses;
+}
+/**
+ * Returns the block actions grouped by action id and concatenated transforms
+ */
+export declare function distinctBlockActionTransforms(blockActions: ActionTransforms[]): ActionTransforms[];
+export {};
+//# sourceMappingURL=network-transactor.d.ts.map

package/dist/src/transactor/network-transactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/network-transactor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAA6B,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAc,aAAa,EAA+B,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAM5S,KAAK,qBAAqB,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,WAAW,CAAC;IACxB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;CACnC,CAAA;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAGnD,IAAI,EAAE,qBAAqB;IAQtB,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC;IAkHnD,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAI7D,uBAAuB;IA0C/B,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA4EnD,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB9C,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOtE,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;YAkC7C,WAAW;IAezB,0EAA0E;YAC5D,YAAY;IAiC1B,8FAA8F;YAChF,iBAAiB;IAe/B,oHAAoH;YACtG,WAAW;IAqBzB,OAAO,CAAC,mBAAmB;CAY3B;AAGD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAIlG"}