@optimystic/db-core 0.0.1

package/src/log/struct.ts

@@ -0,0 +1,40 @@
+import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev } from "../index.js";
+
+/** A log entry - either an action or a checkpoint */
+export type LogEntry<TAction> = {
+	/** Linux timestamp of the entry */
+	readonly timestamp: number;
+	/** Revision number - monotonically increasing from the prior entry's rev.  Starts at 1. */
+	readonly rev: number;
+	readonly action?: ActionEntry<TAction>;
+	readonly checkpoint?: CheckpointEntry;
+};
+
+/** An action entry represents a unit of work that is atomic */
+export type ActionEntry<TAction> = {
+	/** Generated unique identifier for the action */
+	readonly actionId: ActionId;
+	/** Actions to be applied */
+	readonly actions: TAction[];
+	/** Block ids affected by the action - includes the log related blocks */
+	blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
+	/** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
+	readonly collectionIds?: CollectionId[];
+};
+
+/** A checkpoint entry restates the currently uncheckpointed actions */
+export type CheckpointEntry = {
+	/** The current set of pending action/revs
+	 * - actions implicitly increase the set of pending Ids
+	 * - this restates the entire current set
+	 * - missing from the set are the implicitly checkpointed ones */
+	readonly pendings: ActionRev[];
+};
+
+export const LogDataBlockType = "LGD";
+export const LogHeaderBlockType = "LGH";
+
+export type GetFromResult<TAction> = {
+	context: ActionContext | undefined;
+	entries: ActionEntry<TAction>[];
+};

package/src/network/i-key-network.ts

@@ -0,0 +1,24 @@
+import type { PeerId } from "@libp2p/interface";
+import type { ClusterPeers } from "../cluster/structs.js";
+
+export type FindCoordinatorOptions = {
+	/** Peers that have already been tried (and failed) */
+	excludedPeers?: PeerId[];
+};
+
+
+export type IKeyNetwork = {
+	/**
+	 * Find a coordinator node responsible for a given key and establish connection
+	 * @param key The key to find coordinator for
+	 * @returns Promise resolving to ID of coordinator node
+	 */
+	findCoordinator<T>(key: Uint8Array, options?: Partial<FindCoordinatorOptions>): Promise<PeerId>;
+
+	/**
+	 * Find the peers in the cluster responsible for a given key
+	 * @param key The key to find peers for
+	 * @returns Promise resolving to the peers in the cluster
+	 */
+	findCluster(key: Uint8Array): Promise<ClusterPeers>;
+}

package/src/network/i-peer-network.ts

@@ -0,0 +1,8 @@
+import type { AbortOptions, PeerId, Stream } from "@libp2p/interface";
+
+export type IPeerNetwork = {
+  /**
+   * Dial a peer and establish a protocol stream
+   */
+  connect(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<Stream>;
+}

package/src/network/i-repo.ts

@@ -0,0 +1,19 @@
+import type { ActionBlocks, CommitResult, GetBlockResults, PendResult, PendRequest, CommitRequest, BlockGets, BlockId, ActionId } from "../index.js";
+
+export type MessageOptions = {
+	expiration?: number;
+	signal?: AbortSignal;
+}
+
+export type RepoCommitRequest = {
+	blockIds: BlockId[];
+	actionId: ActionId;
+	rev: number;
+};
+
+export type IRepo = {
+	get(blockGets: BlockGets, options?: MessageOptions): Promise<GetBlockResults>;
+	pend(request: PendRequest, options?: MessageOptions): Promise<PendResult>;
+	cancel(actionRef: ActionBlocks, options?: MessageOptions): Promise<void>;
+	commit(request: RepoCommitRequest, options?: MessageOptions): Promise<CommitResult>;
+}

package/src/network/index.ts

@@ -0,0 +1,5 @@
+export * from "./i-key-network.js";
+export * from "./i-peer-network.js";
+export * from "./i-repo.js";
+export * from "./repo-protocol.js";
+export * from "./struct.js";

package/src/network/repo-protocol.ts

@@ -0,0 +1,12 @@
+import type { ActionBlocks, PendRequest, CommitRequest, BlockGets } from "../index.js";
+
+export type RepoMessage = {
+	operations: [
+		{ get: BlockGets } |
+		{ pend: PendRequest } |
+		{ cancel: { actionRef: ActionBlocks } } |
+		{ commit: CommitRequest }
+	],
+	expiration?: number,
+	coordinatingBlockIds?: string[],
+};

package/src/network/struct.ts

@@ -0,0 +1,137 @@
+import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } from "../index.js";
+import type { ActionContext, ActionRev } from "../collection/action.js";
+import type { Transaction } from "../transaction/transaction.js";
+import type { PeerId } from "@libp2p/interface";
+
+export type ActionBlocks = {
+	blockIds: BlockId[];
+	actionId: ActionId;
+};
+
+export type ActionTransforms = {
+	actionId: ActionId;
+	rev?: number;
+	transforms: Transforms;
+};
+
+export type ActionTransform = {
+	actionId: ActionId;
+	rev?: number;
+	transform: Transform;
+};
+
+export type ActionPending = {
+	blockId: BlockId;
+	actionId: ActionId;
+	transform?: Transform;
+};
+
+export type PendRequest = ActionTransforms & {
+	/** What to do if there are any pending actions.
+	 * 'c' is continue normally,
+	 * 'f' is fail, returning the pending ActionIds,
+	 * 'r' is return, which fails but returns the pending ActionIds and their transforms */
+	policy: 'c' | 'f' | 'r';
+	/** For multi-collection transactions: the full transaction for replay/validation */
+	transaction?: Transaction;
+	/** For multi-collection transactions: hash of ALL operations across all blocks */
+	operationsHash?: string;
+	/** For multi-collection transactions: supercluster nominees for consensus */
+	superclusterNominees?: PeerId[];
+};
+
+export type BlockActionStatus = ActionBlocks & {
+	statuses: ('pending' | 'committed' | 'checkpointed' | 'aborted')[];
+};
+
+export type PendSuccess = {
+	success: true;
+	/** List of already pending actions that were found on blocks touched by this pend */
+	pending: ActionPending[];
+	/** The affected blocks */
+	blockIds: BlockId[];
+};
+
+export type StaleFailure = {
+	success: false;
+	/** The reason for the failure */
+	reason?: string;
+	/** List of actions that have already been committed and are newer than our known revision */
+	missing?: ActionTransforms[];
+	/** List of actions that are pending on the blocks touched by this pend */
+	pending?: ActionPending[];
+};
+
+export type PendResult = PendSuccess | StaleFailure;
+
+export type CommitRequest = ActionBlocks & {
+	/** The header block of the collection, if this is a new collection (commit first) */
+	headerId?: BlockId;
+	/** The tail block of the log (commit next) */
+	tailId: BlockId;
+	/** The new revision for the committed action */
+	rev: number;
+};
+
+export type CommitResult = CommitSuccess | StaleFailure;
+
+export type CommitSuccess = {
+	success: true;
+	/** If present, the identified collection acts as the coordinator for the multi-collection transaction */
+	coordinatorId?: CollectionId;
+};
+
+export type BlockActionState = {
+	/** The latest action that has been committed */
+	latest?: ActionRev;
+	/** If present, the specified actions are pending */
+	pendings?: ActionId[];
+};
+
+export type BlockGets = {
+	blockIds: BlockId[];
+	context?: ActionContext;	// Latest if this is omitted
+};
+
+export type GetBlockResult = {
+	/** The retrieved block - undefined if the block was deleted	 */
+	block?: IBlock;
+	/** The latest and pending states of the repo that retrieved the block */
+	state: BlockActionState;
+};
+
+export type GetBlockResults = Record<BlockId, GetBlockResult>;
+
+/**
+ * Result of validating a transaction in a PendRequest.
+ */
+export type PendValidationResult = {
+	/** Whether validation passed */
+	valid: boolean;
+	/** Reason for validation failure (if valid=false) */
+	reason?: string;
+};
+
+/**
+ * Hook for validating transactions in PendRequests.
+ *
+ * This hook is called by the storage layer when receiving a PendRequest
+ * that includes a transaction and operationsHash. If validation fails,
+ * the pend operation is rejected.
+ *
+ * If the hook is not provided, validation is skipped (storage-only nodes).
+ */
+export type PendValidationHook = (
+	transaction: Transaction,
+	operationsHash: string
+) => Promise<PendValidationResult>;
+
+// Backward compatibility aliases (deprecated - use Action* names)
+/** @deprecated Use ActionBlocks instead */
+export type TrxBlocks = ActionBlocks;
+/** @deprecated Use ActionTransforms instead */
+export type TrxTransforms = ActionTransforms;
+/** @deprecated Use ActionTransform instead */
+export type TrxTransform = ActionTransform;
+/** @deprecated Use ActionPending instead */
+export type TrxPending = ActionPending;

package/src/transaction/actions-engine.ts

@@ -0,0 +1,83 @@
+import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
+import type { TransactionCoordinator } from './coordinator.js';
+
+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 implements ITransactionEngine {
+	constructor(private coordinator: TransactionCoordinator) {}
+
+	async execute(transaction: Transaction): Promise<ExecutionResult> {
+		try {
+			// Parse each statement as a CollectionActions object
+			const allActions: CollectionActions[] = [];
+
+			for (const statement of transaction.statements) {
+				const collectionActions = JSON.parse(statement) as CollectionActions;
+
+				// 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)}`
+			};
+		}
+	}
+}
+
+/**
+ * Statement format for the actions engine (array of CollectionActions).
+ * @deprecated Use CollectionActions[] directly
+ */
+export type ActionsStatement = {
+	collections: CollectionActions[];
+};
+
+/**
+ * Helper to create an actions-based transaction statements array.
+ * Each CollectionActions becomes a separate statement.
+ */
+export function createActionsStatements(collections: CollectionActions[]): string[] {
+	return collections.map(c => JSON.stringify(c));
+}
+

package/src/transaction/context.ts

@@ -0,0 +1,103 @@
+import type { CollectionId, ActionId } 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 class TransactionContext {
+	private readonly collectionActions: Map<CollectionId, Action<any>[]> = new Map();
+	private readonly reads: ReadDependency[] = [];
+
+	constructor(
+		private readonly coordinator: TransactionCoordinator,
+		public readonly transactionId: string,
+		public readonly engine: string
+	) {}
+
+	/**
+	 * Add an action to a collection.
+	 *
+	 * Actions are collection-specific:
+	 * - Tree: 'insert', 'delete', 'get', 'scan'
+	 * - Diary: 'append', 'read'
+	 * - etc.
+	 */
+	async addAction(collectionId: CollectionId, action: Action<any>): Promise<void> {
+		// 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: ReadDependency): void {
+		this.reads.push(read);
+	}
+
+	/**
+	 * Commit the transaction.
+	 *
+	 * This executes all accumulated actions across all affected collections,
+	 * coordinating with the network as needed.
+	 */
+	async commit(): Promise<ExecutionResult> {
+		return await this.coordinator.commitTransaction(this);
+	}
+
+	/**
+	 * Rollback the transaction (just discard accumulated state).
+	 */
+	rollback(): void {
+		this.collectionActions.clear();
+		this.reads.length = 0;
+	}
+
+	/**
+	 * Get all accumulated actions by collection.
+	 * Used by coordinator during commit.
+	 */
+	getCollectionActions(): Map<CollectionId, Action<any>[]> {
+		return this.collectionActions;
+	}
+
+	/**
+	 * Get all accumulated read dependencies.
+	 * Used by coordinator during commit.
+	 */
+	getReads(): ReadDependency[] {
+		return this.reads;
+	}
+
+	/**
+	 * Get the set of affected collection IDs.
+	 */
+	getAffectedCollections(): Set<CollectionId> {
+		return new Set(this.collectionActions.keys());
+	}
+}
+