@optimystic/db-core 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-core",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "type": "module",
   "description": "Core database functionality for Optimystic",
   "main": "dist/src/index.js",
@@ -15,6 +15,10 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
+    },
+    "./test": {
+      "types": "./dist/test/test-transactor.d.ts",
+      "import": "./dist/test/test-transactor.js"
     }
   },
   "repository": {
@@ -36,12 +40,9 @@
     "acid"
   ],
   "scripts": {
-    "clean": "aegir clean",
-    "build": "aegir build --env node",
-    "lint": "aegir lint",
-    "test": "aegir test",
-    "test:node": "aegir test -t node",
-    "dep-check": "aegir dep-check"
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "test": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors --reporter min"
   },
   "devDependencies": {
     "@libp2p/crypto": "^5.1.13",
@@ -49,9 +50,15 @@
     "@libp2p/peer-id": "^6.0.4",
     "@libp2p/peer-id-factory": "^4.2.4",
     "@multiformats/multiaddr": "^13.0.1",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/debug": "^4.1.12",
     "@types/mocha": "^10.0.10",
     "@types/node": "^25.1.0",
-    "aegir": "^47.0.26",
+    "chai": "^6.2.2",
+    "chai-as-promised": "^8.0.2",
+    "mocha": "^11.7.5",
+    "rimraf": "^6.1.2",
+    "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/src/btree/btree.ts

@@ -4,6 +4,7 @@ import { apply, get } from "../blocks/index.js";
 import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
 import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
 import type { TreeBlock } from "./tree-block.js";
+import { AtomicProxy } from "../transform/atomic-proxy.js";
 
 export const NodeCapacity = 64;
 
@@ -15,6 +16,7 @@ export const NodeCapacity = 64;
  */
 export class BTree<TKey, TEntry> {
 	protected _version = 0;	// only for path invalidation
+	private _proxy?: AtomicProxy<ITreeNode>;
 
 	/**
 	 * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys.  The default uses < and > operators.
@@ -28,6 +30,10 @@ export class BTree<TKey, TEntry> {
 	) {
 	}
 
+	private atomic<T>(fn: () => Promise<T>): Promise<T> {
+		return this._proxy ? this._proxy.atomic(fn) : fn();
+	}
+
 	static createRoot(
 		store: BlockStore<ITreeNode>
 	) {
@@ -41,10 +47,13 @@ export class BTree<TKey, TEntry> {
 		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
 		newId?: BlockId,
 	) {
-		const root = BTree.createRoot(store as BlockStore<TreeBlock>);
-		store.insert(root);
-		const trunk = createTrunk(store as BlockStore<TreeBlock>, root.header.id, newId);
-		return new BTree(store, trunk, keyFromEntry, compare);
+		const proxy = new AtomicProxy(store);
+		const root = BTree.createRoot(proxy as BlockStore<TreeBlock>);
+		proxy.insert(root);
+		const trunk = createTrunk(proxy as BlockStore<TreeBlock>, root.header.id, newId);
+		const tree = new BTree(proxy, trunk, keyFromEntry, compare);
+		tree._proxy = proxy;
+		return tree;
 	}
 
 	/** @returns a path to the first entry (on = false if no entries) */
@@ -118,12 +127,14 @@ export class BTree<TKey, TEntry> {
 	 * Added entries are frozen to ensure immutability
 	 * @returns path to the new (on = true) or conflicting (on = false) row. */
 	async insert(entry: TEntry): Promise<Path<TKey, TEntry>> {
-		Object.freeze(entry);	// Ensure immutability
-		const path = await this.internalInsert(entry);
-		if (path.on) {
-			path.version = ++this._version;
-		}
-		return path;
+		return this.atomic(async () => {
+			Object.freeze(entry);	// Ensure immutability
+			const path = await this.internalInsert(entry);
+			if (path.on) {
+				path.version = ++this._version;
+			}
+			return path;
+		});
 	}
 
 	/** Updates the entry at the given path to the given value.  Deletes and inserts if the key changes.
@@ -135,30 +146,34 @@ export class BTree<TKey, TEntry> {
 	 * 		* wasUpdate = true, given path is not on an entry
 	 * 		* else newEntry's new key already present; returned path is "near" existing entry */
 	async updateAt(path: Path<TKey, TEntry>, newEntry: TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
-		this.validatePath(path);
-		if (path.on) {
-			Object.freeze(newEntry);
-		}
-		const result = await this.internalUpdate(path, newEntry);
-		if (result[0].on) {
-			result[0].version = ++this._version;
-		}
-		return result;
+		return this.atomic(async () => {
+			this.validatePath(path);
+			if (path.on) {
+				Object.freeze(newEntry);
+			}
+			const result = await this.internalUpdate(path, newEntry);
+			if (result[0].on) {
+				result[0].version = ++this._version;
+			}
+			return result;
+		});
 	}
 
 	/** Inserts the entry if it doesn't exist, or updates it if it does.
 	 * The entry is frozen to ensure immutability.
 	 * @returns path to the new entry.  on = true if existing; on = false if new. */
 	async upsert(entry: TEntry): Promise<Path<TKey, TEntry>> {
-		const path = await this.find(this.keyFromEntry(entry));
-		Object.freeze(entry);
-		if (path.on) {
-			this.updateEntry(path, entry);
-		} else {
-			await this.internalInsertAt(path, entry);
-		}
-		path.version = ++this._version;
-		return path;
+		return this.atomic(async () => {
+			const path = await this.find(this.keyFromEntry(entry));
+			Object.freeze(entry);
+			if (path.on) {
+				this.updateEntry(path, entry);
+			} else {
+				await this.internalInsertAt(path, entry);
+			}
+			path.version = ++this._version;
+			return path;
+		});
 	}
 
 	/** Inserts or updates depending on the existence of the given key, using callbacks to generate the new value.
@@ -167,18 +182,20 @@ export class BTree<TKey, TEntry> {
 	 * @returns path to new entry and whether an update or insert attempted.
 	 * If getUpdated callback returns a row that is already present, the resulting path will not be on. */
 	async merge(newEntry: TEntry, getUpdated: (existing: TEntry) => TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
-		const newKey = await this.keyFromEntry(newEntry);
-		const path = await this.find(newKey);
-		if (path.on) {
-			const result = await this.updateAt(path, getUpdated(this.getEntry(path)));	// Don't use internalUpdate - need to freeze and check for mutation
-			// Note: updateAt already increments version, so don't double-increment here
-			return result;
-		} else {
-			await this.internalInsertAt(path, Object.freeze(newEntry));
-			path.on = true;
-			path.version = ++this._version;
-			return [path, false];
-		}
+		return this.atomic(async () => {
+			const newKey = await this.keyFromEntry(newEntry);
+			const path = await this.find(newKey);
+			if (path.on) {
+				const result = await this.updateAt(path, getUpdated(this.getEntry(path)));	// Don't use internalUpdate - need to freeze and check for mutation
+				// Note: updateAt already increments version, so don't double-increment here
+				return result;
+			} else {
+				await this.internalInsertAt(path, Object.freeze(newEntry));
+				path.on = true;
+				path.version = ++this._version;
+				return [path, false];
+			}
+		});
 	}
 
 	/** Deletes the entry at the given path.
@@ -186,19 +203,23 @@ export class BTree<TKey, TEntry> {
 	 * @returns true if the delete succeeded (the key was found); false otherwise.
 	*/
 	async deleteAt(path: Path<TKey, TEntry>): Promise<boolean> {
-		this.validatePath(path);
-		const result = await this.internalDelete(path);
-		if (result) {
-			++this._version;
-		}
-		return result;
+		return this.atomic(async () => {
+			this.validatePath(path);
+			const result = await this.internalDelete(path);
+			if (result) {
+				++this._version;
+			}
+			return result;
+		});
 	}
 
 	async drop() {	// Node: only when a root treeBlock
-		const root = await this.trunk.get();
-		for await (const id of this.nodeIds(root)) {
-			this.store.delete(id);
-		}
+		return this.atomic(async () => {
+			const root = await this.trunk.get();
+			for await (const id of this.nodeIds(root)) {
+				this.store.delete(id);
+			}
+		});
 	}
 
 	/** Iterates forward starting from the path location (inclusive) to the end.

package/src/cluster/structs.ts

@@ -27,6 +27,13 @@ export type ClusterRecord = {
 	networkSizeHint?: number;
 	/** Confidence in the network size estimate (0-1) */
 	networkSizeConfidence?: number;
+	/** Transaction proceeded despite minority rejections */
+	disputed?: boolean;
+	/** Evidence of the dispute: which peers rejected and why */
+	disputeEvidence?: {
+		rejectingPeers: string[];
+		rejectReasons: { [peerId: string]: string };
+	};
 }
 
 export interface ClusterConsensusConfig {
@@ -42,4 +49,8 @@ export interface ClusterConsensusConfig {
 	clusterSizeTolerance: number;
 	/** Window for detecting partition in milliseconds (default 60000 = 1 min) */
 	partitionDetectionWindow: number;
+	/** Enable dispute escalation protocol (default false) */
+	disputeEnabled?: boolean;
+	/** Timeout for dispute arbitration in milliseconds (default 60000) */
+	disputeArbitrationTimeoutMs?: number;
 }

package/src/collection/collection.ts

@@ -1,6 +1,7 @@
 import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore } from "../index.js";
 import { Log, Atomic, Tracker, copyTransforms, CacheSource, isTransformsEmpty, TransactorSource } from "../index.js";
 import type { CollectionHeaderBlock, CollectionId, ICollection } from "./index.js";
+import type { ReadDependency } from "../transaction/transaction.js";
 import { randomBytes } from '@noble/hashes/utils.js';
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
 import { Latches } from "../utility/latches.js";
@@ -45,6 +46,10 @@ export class Collection<TAction> implements ICollection<TAction> {
 		const header = await source.tryGet(id) as CollectionHeaderBlock | undefined;
 
 		if (header) {	// Collection already exists
+			// Bootstrap ActionContext from the committed tail before walking the chain.
+			// This allows the transactor to serve pending non-tail blocks during Log.open.
+			await Collection.bootstrapContext(source, transactor, header);
+
 			const log = (await Log.open<Action<TAction>>(tracker, id))!;
 			source.actionContext = await log.getActionContext();
 		} else {	// Collection does not exist
@@ -100,6 +105,13 @@ export class Collection<TAction> implements ICollection<TAction> {
 		const source = new TransactorSource(this.id, this.transactor, undefined);
 		const tracker = new Tracker(source);
 
+		// Bootstrap context from committed tail so pending blocks are accessible.
+		// Read through tracker so Chain.open inside Log.open reuses the cached header.
+		const header = await tracker.tryGet(this.id);
+		if (header) {
+			await Collection.bootstrapContext(source, this.transactor, header);
+		}
+
 		// Get the latest entries from the log, starting from where we left off
 		const actionContext = this.source.actionContext;
 		const log = await Log.open<Action<TAction>>(tracker, this.id);
@@ -207,6 +219,14 @@ export class Collection<TAction> implements ICollection<TAction> {
 		}
 	}
 
+	getReadDependencies(): ReadDependency[] {
+		return this.source.getReadDependencies();
+	}
+
+	clearReadDependencies(): void {
+		this.source.clearReadDependencies();
+	}
+
 	/** Called for each local action that may be in conflict with a remote action (always called under latch).
 	 * @param action - The local action to check
 	 * @param potential - The remote action that is potentially in conflict
@@ -224,4 +244,28 @@ export class Collection<TAction> implements ICollection<TAction> {
 		}
 		return true;
 	}
+
+	/** Bootstrap ActionContext from the committed tail block's state.
+	 * The tail is always committed first (commit protocol guarantee), so it's readable
+	 * with context=undefined. Its state.latest contains the ActionRev of the most recent
+	 * committed action — exactly the proof needed for the transactor to serve pending
+	 * non-tail blocks during chain walks.
+	 */
+	private static async bootstrapContext(
+		source: TransactorSource<IBlock>,
+		transactor: ITransactor,
+		header: IBlock,
+	): Promise<void> {
+		const tailId = Object.hasOwn(header, 'tailId') ? (header as any).tailId as BlockId : undefined;
+		if (tailId) {
+			const tailResult = await transactor.get({ blockIds: [tailId] });
+			const tailState = tailResult?.[tailId]?.state;
+			if (tailState?.latest) {
+				source.actionContext = {
+					committed: [{ actionId: tailState.latest.actionId, rev: tailState.latest.rev }],
+					rev: tailState.latest.rev,
+				};
+			}
+		}
+	}
 }

package/src/index.ts

@@ -16,3 +16,4 @@ export * from "./utility/nameof.js";
 export * from "./utility/ensured.js";
 export * from "./utility/pending.js";
 export * from "./utility/block-id-to-bytes.js";
+export * from "./utility/lru-map.js";

package/src/log/log.ts

@@ -56,7 +56,7 @@ export class Log<TAction> {
 	/** Gets the action context of the log. */
 	async getActionContext(): Promise<ActionContext | undefined> {
 		const tailPath = await this.chain.getTail();
-		if (!tailPath) {
+		if (!tailPath || tailPath.block.entries.length === 0) {
 			return undefined;
 		}
 		const checkpoint = await this.findCheckpoint(tailPath);

package/src/logger.ts

@@ -0,0 +1,10 @@
+import debug from 'debug'
+
+const BASE_NAMESPACE = 'optimystic:db-core'
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
+}
+
+export const verbose = typeof process !== 'undefined'
+	&& (process.env.OPTIMYSTIC_VERBOSE === '1' || process.env.OPTIMYSTIC_VERBOSE === 'true');