@optimystic/db-core 0.20.0 → 0.21.0

package/src/network/struct.ts

@@ -162,6 +162,19 @@ export type GetBlockResult = {
 	block?: IBlock;
 	/** The latest and pending states of the repo that retrieved the block */
 	state: BlockActionState;
+	/** The revision the returned `block` was actually materialized at — the highest committed
+	 *  revision of THIS block at or below the caller's {@link BlockGets.context}`.rev`. Differs
+	 *  from `state.latest.rev` only for a revision-pinned read of a block that has committed
+	 *  further since the pin; for an unpinned read the two agree.
+	 *
+	 *  This — not `state.latest.rev` — is the revision a read observed, so it is what a read
+	 *  dependency must record (recording `latest` would claim the reader saw content it never
+	 *  read, and the validator's stale-read check would wrongly pass). `state.latest` keeps its
+	 *  own meaning: the newest revision the answering repo holds for the block.
+	 *
+	 *  Optional: a producer that does not know the materialized revision leaves it absent
+	 *  rather than guessing, and consumers fall back to `state.latest?.rev ?? 0`. */
+	materializedRev?: number;
 	/** Set when this repo could not determine whether the block exists — its answer is a
 	 *  guess, not an authoritative absent. Every producer that omits it (including
 	 *  TestTransactor) keeps meaning "authoritative". */

package/src/testing/test-transactor.ts

@@ -61,6 +61,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 +73,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 +91,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,11 +473,12 @@ 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;
 }

package/src/transactor/network-transactor.ts

@@ -215,6 +215,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];

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

@@ -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). */