@optimystic/db-core 0.20.0 → 0.22.0

package/src/testing/test-transactor.ts

@@ -1,4 +1,6 @@
-import { type ITransactor, type GetBlockResults, type ActionBlocks, type BlockActionStatus, type PendResult, type CommitResult, type PendRequest, type BlockId, type CommitRequest, type BlockGets, type IBlock, type ActionId, type ActionTransforms, type Transform, type Transforms, ensuredMap, Latches, type ClusterNomineesResult } from "../index.js";
+import type { ITransactor, GetBlockResults, ActionBlocks, BlockActionStatus, PendResult, CommitResult, PendRequest, BlockId, CommitRequest, BlockGets, IBlock, ActionId, ActionTransforms, Transform, Transforms, ClusterNomineesResult } from "../index.js";
+import { ensuredMap } from "../utility/ensured.js";
+import { Latches } from "../utility/latches.js";
 import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
 
 type RevisionNumber = number;
@@ -61,6 +63,11 @@ export class TestTransactor implements ITransactor {
 
 				// Get the appropriate materialized block based on context
 				let block: IBlock | undefined;
+				// The revision `block` was actually materialized at, reported as
+				// GetBlockResult.materializedRev. Equals `latestRev` on every unpinned path; only a
+				// revision-pinned read of a block committed further since the pin makes them differ,
+				// and there the pinned value is what the reader observed (see the field's doc).
+				let materializedRev: number | undefined;
 				if (blockGets.context?.actionId !== undefined) {
 					// If requesting a specific action, apply pending transform if it exists
 					const pendingTransform = blockState.pendingActions.get(blockGets.context.actionId);
@@ -68,6 +75,9 @@ export class TestTransactor implements ITransactor {
 						// Read latest committed block as base for pending transform
 						const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
 						block = applyTransformSafe(baseBlock, pendingTransform);
+						// A pending carries no revision of its own — report the committed base it was
+						// applied over. Absent when there was no base (a pending-only insert).
+						if (baseBlock) materializedRev = blockState.latestRev;
 					} else {
 						// Action not pending, maybe committed? Or maybe invalid actionId for context.
 						// For simplicity, return undefined block if specific pending action not found.
@@ -83,29 +93,37 @@ export class TestTransactor implements ITransactor {
 						if (pendingTransform) {
 							const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
 							block = applyTransformSafe(baseBlock, pendingTransform);
+							if (baseBlock) materializedRev = blockState.latestRev;
 							break;
 						}
 					}
 					// Fall through to standard resolution if no pending match
 					if (block === undefined) {
 						if (blockGets.context.rev !== undefined) {
-							block = structuredClone(latestMaterializedAt(blockState, blockGets.context.rev));
+							const found = latestMaterializedAt(blockState, blockGets.context.rev);
+							block = structuredClone(found?.block);
+							materializedRev = found?.rev;
 						} else {
 							block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+							if (block) materializedRev = blockState.latestRev;
 						}
 					}
 				} else if (blockGets.context?.rev !== undefined) {
 					// Return the materialized block at the highest revision ≤ requested
-					block = structuredClone(latestMaterializedAt(blockState, blockGets.context.rev));
+					const found = latestMaterializedAt(blockState, blockGets.context.rev);
+					block = structuredClone(found?.block);
+					materializedRev = found?.rev;
 				} else {
 					// Otherwise return latest materialized block
 					block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
+					if (block) materializedRev = blockState.latestRev;
 				}
 
 
 				const actionId = blockState.revisionActions.get(blockState.latestRev);
 				results[blockId] = {
 					block,
+					...(materializedRev !== undefined ? { materializedRev } : {}),
 					state: {
 						latest: actionId !== undefined ? {
 							rev: blockState.latestRev,
@@ -457,16 +475,28 @@ function newBlockState(): BlockState {
 	};
 }
 
-/** Returns the materialized block at the highest revision ≤ the given revision */
-function latestMaterializedAt(blockState: BlockState, maxRev: number): IBlock | undefined {
+/** Returns the materialized block at the highest revision ≤ the given revision, together with
+ *  that revision — the caller reports it as {@link GetBlockResult.materializedRev}. */
+function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
 	for (let rev = maxRev; rev >= 0; rev--) {
 		const block = blockState.materializedBlocks.get(rev);
-		if (block) return block;
+		if (block) return { block, rev };
 	}
 	return undefined;
 }
 
+/**
+ * `applyTransform` over cloned inputs, so a returned block never aliases stored state.
+ *
+ * An absent base is NOT a short circuit: an insert needs no base — `applyTransform` adopts it as
+ * the block. Bailing out on `!block` made this double silently drop a pending-only insert read
+ * through the pending overlay, the one shape `StorageRepo.get` serves with content but no
+ * `materializedRev` (see docs/internals.md § the `unavailable`/`materializedRev` bullets). A
+ * pending UPDATE over an absent base still resolves to undefined, matching the real repo.
+ */
 function applyTransformSafe(block: IBlock | undefined, transform: Transform): IBlock | undefined {
-  if (!block) return undefined;
-  return applyTransform(structuredClone(block), transform);
+  return applyTransform(
+    block ? structuredClone(block) : undefined,
+    transform.insert ? { ...transform, insert: structuredClone(transform.insert) } : transform
+  );
 }

package/src/transaction/coordinator.ts

@@ -5,7 +5,8 @@ import { isConflictFailure } from "../network/stale-failure.js";
 import type { Collection } from "../collection/collection.js";
 import type { SyncOptions } from "../collection/index.js";
 import { isTransactionExpired, clampPriority } from "./transaction.js";
-import { Log, blockIdsForTransforms } from "../index.js";
+import { Log } from "../log/log.js";
+import { blockIdsForTransforms } from "../transform/helpers.js";
 import { collectOperations, hashOperations } from "./operations-hash.js";
 import { CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
 import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";

package/src/transactor/network-transactor.ts

@@ -4,7 +4,12 @@ import { highestStaleAt, isConflictFailure } from "../network/stale-failure.js";
 import { BlockUnavailableError } from "../network/struct.js";
 import type { ActionTransforms, ActionBlocks, BlockActionStatus, ITransactor, PendSuccess, StaleFailure, IKeyNetwork, BlockId, GetBlockResults, PendResult, CommitResult, PendRequest, IRepo, BlockGets, Transforms, CommitRequest, ActionId, RepoCommitRequest, ClusterNomineesResult, CollectionId, IBlock, CoordinatorIntent } from "../index.js";
 import type { IBlockChangeNotifier, CollectionChangeListener } from "./change-notifier.js";
-import { transformForBlockId, groupBy, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms, Log, Tracker, CacheSource, TransactorSource } from "../index.js";
+import { transformForBlockId, concatTransforms, concatTransform, transformsFromTransform, blockIdsForTransforms } from "../transform/helpers.js";
+import { Tracker } from "../transform/tracker.js";
+import { CacheSource } from "../transform/cache-source.js";
+import { TransactorSource } from "./transactor-source.js";
+import { Log } from "../log/log.js";
+import { groupBy } from "../utility/groupby.js";
 import { blockIdToBytes } from "../utility/block-id-to-bytes.js";
 import { isRecordEmpty } from "../utility/is-record-empty.js";
 import { type CoordinatorBatch, makeBatchesByPeer, incompleteBatches, everyBatch, allBatches, mergeBlocks, processBatches, createBatchesForPayload } from "../utility/batch-coordinator.js";
@@ -215,6 +220,13 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// absent, which beats an `unavailable` guess — one peer that positively knows the
 		// block is absent outranks another that could not find out. Non-object junk ranks
 		// below everything so any real entry replaces it.
+		// NOTE: `materializedRev` is not part of the ranking, so two peers answering the same
+		// pinned get with block-carrying entries at DIFFERENT materialized revisions resolve
+		// to whichever arrived first. Not a concern today — cohort peers share the block's
+		// revision log, so they agree on the highest committed rev at or below a pin — and the
+		// failure direction is safe (a lower recorded revision spuriously stale-rejects rather
+		// than wrongly accepting). If peers are ever seen to disagree here, break the tie on
+		// the HIGHEST materializedRev among rank-2 entries.
 		const rankOf = (r: unknown): number => {
 			if (!r || typeof r !== 'object') return -1;
 			const entry = r as GetBlockResults[BlockId];
@@ -634,7 +646,6 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 	async commit(request: CommitRequest): Promise<CommitResult> {
 		const t0 = Date.now();
 		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
-		const allBlockIds = [...new Set([...request.blockIds, request.tailId])];
 
 		// Commit the header block if provided and not already in blockIds.
 		// `request.tailId` is threaded into every per-block commit so the coordinator carries it into the
@@ -642,14 +653,14 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		// CollectionChangeEvent (the reactivity topic anchor). Without this the per-block RepoCommitRequest
 		// drops the collection tail and reactivity origination is gated off (undefined tail → non-member).
 		if (request.headerId && !request.blockIds.includes(request.headerId)) {
-			const headerResult = await this.commitBlock(request.headerId, allBlockIds, request.actionId, request.rev, request.tailId);
+			const headerResult = await this.commitBlock(request.headerId, request.actionId, request.rev, request.tailId);
 			if (!headerResult.success) {
 				return headerResult;
 			}
 		}
 
 		// Commit the tail block
-		const tailResult = await this.commitBlock(request.tailId, allBlockIds, request.actionId, request.rev, request.tailId);
+		const tailResult = await this.commitBlock(request.tailId, request.actionId, request.rev, request.tailId);
 		if (!tailResult.success) {
 			return tailResult;
 		}
@@ -672,7 +683,7 @@ export class NetworkTransactor implements ITransactor, IBlockChangeNotifier {
 		return { success: true };
 	}
 
-	private async commitBlock(blockId: BlockId, blockIds: BlockId[], actionId: ActionId, rev: number, tailId?: BlockId): Promise<CommitResult> {
+	private async commitBlock(blockId: BlockId, actionId: ActionId, rev: number, tailId?: BlockId): Promise<CommitResult> {
 		const { batches: tailBatches, error: tailError } = await this.commitBlocks({ blockIds: [blockId], actionId, rev, tailId });
 		if (tailError) {
 			// commit is a pure attempt: stale → { success:false }, transient → throw. Cancellation

package/src/transactor/transactor-source.ts

@@ -43,7 +43,7 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		// `result[id]` is undefined. Destructuring that would throw a TypeError.
 		const entry = result?.[id];
 		if (entry) {
-			const { block, state, unavailable } = entry;
+			const { block, state, materializedRev, unavailable } = entry;
 			// An entry flagged `unavailable` with no block is the repo saying "I could not find
 			// out whether this exists" — an answer that must not be read as absent. Throw rather
 			// than return undefined, and record no read dependency (dependencies are recorded
@@ -60,7 +60,13 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 				// Record read dependency for optimistic concurrency control, carrying the caller's
 				// read purpose (default `value`) so a purely-structural navigation read can later be
 				// dropped from the conflict set (see ReadDependencyCollector / Theorem 5).
-				const rev = state.latest?.rev ?? 0;
+				// Record the revision the content was MATERIALIZED at, not the newest the repo holds —
+				// see {@link GetBlockResult.materializedRev} for why `state.latest` is the wrong number
+				// and why the fallback preserves today's behaviour for repos that omit the field.
+				// Both sinks must take the SAME value: CacheSource learns it via getReadRevision on a
+				// miss-load and re-emits it on every later hit, so a split would stamp the cache
+				// differently from the collector.
+				const rev = materializedRev ?? state.latest?.rev ?? 0;
 				this.collector.record(id, rev, purpose);
 				this.readRevisions.set(id, rev);
 			}
@@ -81,6 +87,14 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
 		return this.collector.getReadDependencies();
 	}
 
+	/** The collector this source records into — the one shared with the collection's
+	 *  CacheSource. Exposed ONLY so a pinned read view built with `recordReads: true`
+	 *  can feed the same per-transaction read set (see Collection.createReadTracker);
+	 *  every other consumer should go through {@link getReadDependencies}. */
+	getCollector(): ReadDependencyCollector {
+		return this.collector;
+	}
+
 	clearReadDependencies(): void {
 		this.collector.clear();
 	}

package/src/transform/cache-source.ts

@@ -1,5 +1,5 @@
 import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
-import { applyOperation } from "../index.js";
+import { applyOperation } from "./helpers.js";
 import { LruMap } from "../utility/lru-map.js";
 import { createLogger } from "../logger.js";
 import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
@@ -44,8 +44,20 @@ export class CacheSource<T extends IBlock> implements BlockSource<T> {
 		/** Shared per-transaction read-dependency accumulator (same instance the collection's
 		 *  TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
 		private readonly collector?: ReadDependencyCollector,
+		/** Pre-warm entries for a pinned read view — the output of another cache's
+		 *  {@link snapshotEntries}. Entries are already cloned by snapshotEntries, so they are
+		 *  adopted as-is; per-id revisions ride along so a seeded HIT still records at the
+		 *  revision the block was committed at. Seeding does not bump generations (a fresh
+		 *  cache has no consumers with stale memos). */
+		seed?: ReadonlyArray<[BlockId, T, number]>,
 	) {
 		this.cache = new LruMap(maxSize);
+		if (seed) {
+			for (const [id, block, revision] of seed) {
+				this.cache.set(id, block);
+				this.revisions.set(id, revision);
+			}
+		}
 	}
 
 	private bump(id: BlockId) {
@@ -121,6 +133,19 @@ export class CacheSource<T extends IBlock> implements BlockSource<T> {
 		}
 	}
 
+	/** A cloned copy of the current cache contents with each id's committed revision, in LRU
+	 *  order (oldest first, so replaying into another LruMap preserves eviction order). For
+	 *  building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the
+	 *  result as the `seed` of a fresh, PRIVATE CacheSource. Blocks are cloned on the way out,
+	 *  so the seeded cache shares no mutable state with this one. */
+	snapshotEntries(): Array<[BlockId, T, number]> {
+		const entries: Array<[BlockId, T, number]> = [];
+		for (const [id, block] of this.cache) {
+			entries.push([id, structuredClone(block), this.revisions.get(id) ?? 0]);
+		}
+		return entries;
+	}
+
 	/** Mutates the cache without affecting the source. `revision` is the committed revision this
 	 *  transform lands at; the stored per-id revision advances to it so a later read records a
 	 *  dependency at the NEW revision (recording the old one would spuriously fail validation). */

package/src/transform/helpers.ts

@@ -148,11 +148,12 @@ export function applyTransform(block: IBlock | undefined, transform: Transform):
 	return block;
 }
 
-/** Concatenates a transform to the given transforms */
+/**
+ * Concatenates a single block's transform onto the given transforms.
+ *
+ * Delegates to `mergeTransforms` so the two helpers cannot drift: updates for a shared
+ * block id concatenate (order-preserving), deletes dedupe, inserts stay last-wins.
+ */
 export function concatTransform(transforms: Transforms, blockId: BlockId, transform: Transform): Transforms {
-	return {
-		inserts: { ...transforms.inserts, ...(transform.insert ? { [blockId]: transform.insert } : {}) },
-		updates: { ...transforms.updates, ...(transform.updates ? { [blockId]: transform.updates } : {}) },
-		deletes: [...(transforms.deletes ?? []), ...(transform.delete ? [blockId] : [])]
-	};
+	return mergeTransforms(transforms, transformsFromTransform(transform, blockId));
 }

package/src/transform/tracker.ts

@@ -1,5 +1,6 @@
 import type { IBlock, BlockId, BlockStore as IBlockStore, BlockHeader, BlockOperation, BlockType, BlockSource as IBlockSource, ReadPurpose } from "../index.js";
-import { applyOperation, applyOperations, emptyTransforms, blockIdsForTransforms, ensured } from "../index.js";
+import { applyOperation, applyOperations, emptyTransforms, blockIdsForTransforms } from "./helpers.js";
+import { ensured } from "../utility/ensured.js";
 
 /** A block store that collects transformations, without applying them to the underlying source.
  * Transformations are also applied to the retrieved blocks, making it seem like the source has been modified.