@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.1

package/resources/DatabaseTransaction.ts

@@ -26,6 +26,7 @@ import {
 } from './longLivedTransactions.ts';
 
 const trackedTxns = new Set<DatabaseTransaction>();
+const readTransactionOwners = new WeakMap<ReadTransaction, DatabaseTransaction>();
 // Read options for a rotated generation's native transactions; shared because they never vary.
 const SNAPSHOT_FREE = Object.freeze({ disableSnapshot: true });
 // Logical transactions the monitor supervises for their WRITES, kept apart from trackedTxns because the
@@ -292,6 +293,82 @@ export function transactionOpenTooLongError(): ServerError {
 	);
 }
 
+class ReadSnapshotExpiredError extends ServerError {
+	constructor() {
+		super('Read scan snapshot expired; retry the read without replaying previously committed writes', 503);
+		this.name = 'ReadSnapshotExpiredError';
+	}
+}
+
+export function getReadTransactionGuard(transaction: ReadTransaction): (() => void) | undefined {
+	const owner = readTransactionOwners.get(transaction);
+	if (!owner) return;
+	return function checkActive() {
+		if (owner.timedOut) throw transactionOpenTooLongError();
+		if (owner.transaction !== transaction) {
+			throw new ReadSnapshotExpiredError();
+		}
+	};
+}
+
+export function trackReadRange(transaction: ReadTransaction, createRange: () => any): any {
+	const owner = readTransactionOwners.get(transaction);
+	if (!owner) return createRange();
+	const checkActive = getReadTransactionGuard(transaction)!;
+	checkActive();
+	const range = createRange();
+	const iterate = range.iterate;
+	range.iterate = function (options) {
+		const iterator = iterate.call(this, options);
+		let done = false;
+		// Closing the underlying iterator is the one step here that can throw for a reason the caller
+		// must not see: `next()` only reaches it once the snapshot is already gone, which is the
+		// likeliest moment for the native layer to object, and an error from cleanup would replace the
+		// named 503 with exactly the raw iterator error this wrapper exists to stop surfacing. The
+		// closure reference rather than `this` so a destructured `next` still cleans up.
+		const wrapper = {
+			[Symbol.iterator]() {
+				return this;
+			},
+			next() {
+				if (done) return { done: true, value: undefined };
+				try {
+					checkActive();
+					owner.rangeReadActive = true;
+					const result = iterator.next();
+					done = result.done === true;
+					return result;
+				} catch (error) {
+					closeQuietly();
+					throw error;
+				}
+			},
+			return(value?: any) {
+				if (!done) {
+					done = true;
+					iterator.return?.(value);
+				}
+				return { done: true, value };
+			},
+			throw(error) {
+				// Not delegated to `iterator.throw`: it closes and rethrows the same error anyway, and
+				// delegating after the close below would run it against an iterator already closed.
+				closeQuietly();
+				throw error;
+			},
+		};
+		function closeQuietly() {
+			try {
+				wrapper.return();
+			} catch {
+				// the error being propagated is the actionable one
+			}
+		}
+		return wrapper;
+	};
+	return range;
+}
+
 type MaybePromise<T> = T | Promise<T>;
 
 export type CommitOptions = {
@@ -309,6 +386,11 @@ type ReadTransaction = (LMDBTransaction | RocksTransaction) & {
 	isCommitted?: boolean;
 };
 
+export type WriteGeneration = {
+	closed: boolean;
+	internalWrites: number;
+};
+
 export type TransactionWrite = {
 	key: Id;
 	store: any; // using any here because of circular dependency and complex RootDatabaseKind
@@ -381,8 +463,30 @@ export type TransactionWrite = {
 	// this settles (fire-and-forget from the if-branch), so Table.save()'s lock-writable path awaits
 	// it to ensure the write is durable before resolving to the caller.
 	innerCommit?: MaybePromise<CommitResolution>;
+	// the commit derives stored state (folds, index diffs, residency) from its base entry, so
+	// save() must reload that base through the committing transaction's snapshot
+	reloadCommitBase?: boolean;
+	writeGeneration?: WriteGeneration;
+	instanceClosed?: boolean;
 };
 
+export function closeWriteInstance(operation: TransactionWrite | null | undefined): void {
+	if (operation && !operation.instanceClosed) {
+		operation.instanceClosed = true;
+		if (operation.writeGeneration) operation.writeGeneration.closed = true;
+	}
+}
+
+export function validateWrite(operation: TransactionWrite, txnTime: number, transaction: DatabaseTransaction): any {
+	const generation = operation.writeGeneration;
+	if (generation) generation.internalWrites++;
+	try {
+		return operation.validate?.(txnTime, transaction);
+	} finally {
+		if (generation) generation.internalWrites--;
+	}
+}
+
 export function getAppliedWriteVersion(recordVersion: number | undefined, txnLogKey: number): number {
 	return recordVersion == null ? txnLogKey : Math.min(recordVersion, txnLogKey);
 }
@@ -431,6 +535,7 @@ export class DatabaseTransaction implements Transaction {
 		this.#scopeOwned = options?.scopeOwned === true;
 	}
 	writes: TransactionWrite[] = []; // the set of writes to commit if the conditions are met
+	ownedWrites?: WeakSet<TransactionWrite>;
 	// the last staged write per store and key, used to chain repeat writes to the same key (linkWrite)
 	declare writesByKey?: Map<any, Map<unknown, TransactionWrite>>;
 	completions: Promise<void>[] = []; // the set of outstanding async operations to complete
@@ -521,6 +626,15 @@ export class DatabaseTransaction implements Transaction {
 	declare commitChainHead?: DatabaseTransaction;
 	// O(1) lookup in recordLockFor; only lock() handles are registered here (no gate handles).
 	declare recordLocks?: Map<any, Map<unknown, RecordLockHandle>>;
+	/**
+	 * Whether any staged write was made through a record lock handle. The commit-time lease fence
+	 * below is skipped entirely when this is false, which is every transaction in a core-only
+	 * deployment: without it a bulk transaction of 100,000 plain writes pays 100,000 property checks
+	 * before submission, on a path that is supposed to be untouched when no lock is involved. It
+	 * latches rather than tracking a count, because a write whose handle was released or expired after
+	 * staging is exactly what the fence exists to catch.
+	 */
+	declare hasLeaseProtectedWrite?: boolean;
 	// Tracks in-flight acquireRecordKey calls so concurrent lock() calls for the same key in one
 	// link (e.g. Promise.all([T.lock(id), T.lock(id)])) can coalesce rather than self-block.
 	declare pendingLocks?: Map<any, Map<unknown, Promise<RecordLockHandle>>>;
@@ -534,8 +648,9 @@ export class DatabaseTransaction implements Transaction {
 		}
 	}
 
-	getReadTxn(disableSnapshot?: boolean): ReadTransaction {
-		this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
+	rangeReadActive = false;
+
+	renewReadTimeout(): void {
 		// The limit is an IDLE limit. Writes always re-arm it (see addWrite), but reads only do so
 		// while no uncommitted writes are held: staged writes hold write intents that other writers'
 		// coordinated-retry commits park on, so a handler that wrote once and then only reads — an
@@ -548,6 +663,25 @@ export class DatabaseTransaction implements Transaction {
 		if ((this.writes.length === 0 && !this.next) || this.open !== TRANSACTION_STATE.OPEN || !this.hasPendingWrites()) {
 			this.timeout = Math.max(txnExpiration, this.timeoutBudget);
 		}
+	}
+
+	// Each engine keeps its own expiration; LMDBTransaction overrides this with its own.
+	renewIdleTimeout(): void {
+		this.timeout = Math.max(txnExpiration, this.timeoutBudget ?? 0);
+	}
+
+	// The links after this one wait for its native commit before their own commit() is entered; each
+	// hop starts with a full idle window and a stalled native commit is still bounded by one.
+	renewChainForNativeCommit(): void {
+		for (let txn: DatabaseTransaction = this; txn; txn = txn.next) {
+			if (txn.timedOut || txn.open === TRANSACTION_STATE.CLOSED) continue;
+			txn.renewIdleTimeout();
+		}
+	}
+
+	getReadTxn(disableSnapshot?: boolean): ReadTransaction {
+		this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
+		this.renewReadTimeout();
 		if (this.transaction) {
 			if ((this.transaction as any).openTimer) (this.transaction as any).openTimer = 0;
 			return this.transaction;
@@ -582,6 +716,8 @@ export class DatabaseTransaction implements Transaction {
 	// Monitor state is not ownership state: it stays with `trackedTxns.add` in getReadTxn().
 	private attachOwnedTransaction(transaction: RocksTransactionWithRetry): void {
 		this.transaction = transaction;
+		readTransactionOwners.set(transaction, this);
+		this.rangeReadActive = false;
 		this.readTxnsUsed = 1;
 		this.baseReadRefConsumed = false;
 		this.handleOpenedAt = performance.now();
@@ -623,6 +759,7 @@ export class DatabaseTransaction implements Transaction {
 		trackedTxns.delete(this);
 		this.endWriteSupervision();
 		this.transaction = null;
+		this.rangeReadActive = false;
 		this.readTxnsUsed = 0;
 		this.readTxnRefCount = 0;
 		this.handleOpenedAt = 0;
@@ -721,6 +858,7 @@ export class DatabaseTransaction implements Transaction {
 	detachWrite(operation: TransactionWrite): void {
 		const index = this.writes.indexOf(operation);
 		if (index > -1) this.writes[index] = null;
+		this.ownedWrites?.delete(operation);
 		if (operation.key === undefined) return;
 		const writesForStore = this.writesByKey?.get(operation.store);
 		if (!writesForStore) return;
@@ -728,7 +866,7 @@ export class DatabaseTransaction implements Transaction {
 		// Membership, not `stagedIn`, which every commit handler clears and so cannot tell a takeover from a
 		// write done in place; a prior already taken over must not become this transaction's basis again.
 		let prior = operation.priorWrite;
-		while (prior && !this.writes.includes(prior)) prior = prior.priorWrite;
+		while (prior && !this.ownedWrites?.has(prior)) prior = prior.priorWrite;
 		const tail = writesForStore.get(keyId);
 		if (tail === operation) {
 			if (prior) writesForStore.set(keyId, prior);
@@ -757,9 +895,9 @@ export class DatabaseTransaction implements Transaction {
 		if (!storeMap) return undefined;
 		const h = storeMap.get(keyId);
 		if (!h) return undefined;
-		if (!h.released) return h;
-		// Prune released handles so they don't accumulate; an expired handle checking re-entrancy
-		// would otherwise be seen as the holder and incorrectly granted access.
+		if (!h.isExpired()) return h;
+		// Prune released/expired handles so they don't accumulate; a handle past its deadline checking
+		// re-entrancy would otherwise be seen as the holder and incorrectly granted access.
 		storeMap.delete(keyId);
 		return undefined;
 	}
@@ -818,9 +956,16 @@ export class DatabaseTransaction implements Transaction {
 		// fire after a commit or abort, and routing it back here would revive a write this transaction
 		// already rolled back — whose blobs abort() has reclaimed. Cleared here, save() resolves the
 		// context's current transaction as it did before `stagedIn` existed.
-		for (const write of this.writes) if (write?.stagedIn === this) write.stagedIn = undefined;
+		for (const write of this.writes) {
+			if (write?.stagedIn === this) write.stagedIn = undefined;
+			if (write) this.ownedWrites?.delete(write);
+		}
 		this.writes = [];
 		this.writesByKey = undefined;
+		// The commit-fence latch belongs to the discarded batch. A reused transaction that once staged
+		// a locked write would otherwise re-scan every write of every later unlocked batch. Assigned
+		// only when it was set, so an ordinary transaction never gains the property at all.
+		if (this.hasLeaseProtectedWrite) this.hasLeaseProtectedWrite = false;
 	}
 
 	/**
@@ -956,6 +1101,7 @@ export class DatabaseTransaction implements Transaction {
 		this.writeTick = monitorTick;
 		this.linkWrite(operation);
 		this.writes.push(operation);
+		(this.ownedWrites ??= new WeakSet()).add(operation);
 		operation.stagedIn = this;
 		// Hold this write back while any earlier same-key write has not run — out of staging order both
 		// diff against the pre-transaction record (harper#2211, DESIGN.md). The whole chain, not just the
@@ -987,15 +1133,26 @@ export class DatabaseTransaction implements Transaction {
 		const lockHandle = operation.lockHandle;
 		// Guard: a write staged through an expired or released lock handle must not land.
 		// The handle's lease timer already unlocked the native key; another holder may have taken it.
-		if (lockHandle && (lockHandle.expired || lockHandle.released)) {
-			// Remove the operation from the staged set so subsequent writes on this context do not
-			// re-throw 409 due to a stale null-saved entry sitting in this.writes.
-			const failedIdx = this.writes.indexOf(operation);
-			if (failedIdx > -1) this.writes[failedIdx] = null;
+		// isExpired() re-evaluates the deadline here rather than trusting the timer to have run: a
+		// holder whose event loop stalled past its lease would otherwise commit in the window between
+		// the deadline and its own timer callback, after peers had already granted the key onward.
+		//
+		// A RE-save is judged by the lease alone. `released` belongs to the first stage — a caller that
+		// unlocked and then saved is writing through a handle it gave back — but an operation already
+		// staged was staged while the lock was held, and an `unlock()` inside the lease leaves it valid
+		// (the same rule the pre-submit fence applies below). Without the distinction,
+		// `lock(); save(); unlock(); commit()` succeeded normally and threw 409 only when a conflict
+		// retry or an open read iterator forced the replay to re-save it.
+		if (operation.saved ? lockHandle?.isLeaseExpired() : lockHandle?.isExpired()) {
+			// Through `detachWrite`, which also repairs the per-key chain: dropping it from `writes` alone
+			// leaves `writesByKey` pointing at a write that was refused, so a caller that catches this 409
+			// and stages the same key again would take the rejected operation as its merge basis.
+			this.detachWrite(operation);
 			throw lockNotHeldError(lockHandle);
 		}
 		// Lock-write timestamp rules.
 		if (lockHandle) {
+			this.hasLeaseProtectedWrite = true;
 			if (this.open === TRANSACTION_STATE.CLOSED || this.saveCommits) {
 				// CLOSED path (second+ write per ImmediateTransaction cycle) OR the first write in
 				// an ImmediateTransaction (open=OPEN until commit sets it CLOSED, but saveCommits
@@ -1054,22 +1211,44 @@ export class DatabaseTransaction implements Transaction {
 			(transaction as RocksTransactionWithRetry).isRetry = true;
 		}
 		if (!txnTime) txnTime = this.timestamp = transaction.getTimestamp();
+		if (!operation.saved && operation.pendingPriorWrite) {
+			const pendingWrites = [];
+			for (let pending = operation.pendingPriorWrite; pending;) {
+				if (!pending.saved && this.ownedWrites?.has(pending)) pendingWrites.push(pending);
+				pending = pending.pendingPriorWrite !== undefined ? pending.pendingPriorWrite : pending.priorWrite;
+			}
+			for (let index = pendingWrites.length - 1; index >= 0; index--)
+				this.save(pendingWrites[index], transaction, false, options);
+			operation.pendingPriorWrite = null;
+		}
 		// `txnTime` is this transaction's timestamp — the key its entries take in the per-origin log.
 		// A write applied from elsewhere carries the origin's record version too, and that is what the
 		// record is stored at; the two coincide for every locally-originated write. Gated on the apply
 		// flags so an ordinary write never reads the property (harper#2412).
 		const writeVersion =
 			this.sourceApply || this.isReplay ? getAppliedWriteVersion(operation.recordVersion, txnTime) : txnTime;
-		if (reloadEntry || operation.entry === undefined) {
-			operation.entry = operation.store.getEntry(operation.key, { transaction });
+		// A base that feeds stored state must come from this transaction's snapshot, never the
+		// cross-worker cache vouch (stale when a resequenced write reused a version). That closes the
+		// lost-update window only when this transaction holds a snapshot to validate the later Put
+		// against; a snapshot-free transaction (this.snapshotFree, after a mid-scope-commit rotation)
+		// has no snapshot for rocksdb-js to validate the Put against, so it only narrows the window to
+		// the read-to-put span rather than closing it (open follow-up, tracked in the PR description).
+		// Replays keep their pre-read base — their convergence contract is the replay pass itself.
+		const reloadsCommitBase = operation.reloadCommitBase && !operation.saved && !this.isReplay;
+		if (reloadEntry || operation.entry === undefined || reloadsCommitBase) {
+			const uncachedRead = (!!operation.reloadCommitBase && !this.isReplay) || reloadEntry;
+			operation.entry = operation.store.getEntry(operation.key, { transaction, uncachedRead });
 		}
 		if (!operation.saved) {
-			operation.saved = true;
 			// immediately execute in this transaction
-			if ((operation.validate?.(writeVersion, this) as any) === false) {
+			const validated = validateWrite(operation, writeVersion, this);
+			if ((validated as any) === false) {
+				operation.saved = true;
 				operation.commit = () => {}; // noop if we try again
+				closeWriteInstance(operation);
 				return;
 			}
+			operation.saved = true;
 			let result: Promise<void> = operation.before?.() as Promise<void>;
 			if (result?.then) this.stageCompletion(result);
 			result = operation.beforeIntermediate?.() as Promise<void>;
@@ -1077,7 +1256,12 @@ export class DatabaseTransaction implements Transaction {
 		}
 		if (lockHandle || this.recordLocks) operation.trackRecordVersion = true;
 		if (operation.trackRecordVersion) operation.recordVersionApplied = false;
-		const completion = operation.commit(writeVersion, operation.entry, this.retries > 0, transaction) as Promise<void>;
+		let completion: Promise<void>;
+		try {
+			completion = operation.commit(writeVersion, operation.entry, this.retries > 0, transaction) as Promise<void>;
+		} finally {
+			closeWriteInstance(operation);
+		}
 		if (operation.trackRecordVersion)
 			operation.appliedRecordVersion = operation.recordVersionApplied ? writeVersion : undefined;
 		if (typeof completion?.then === 'function') this.stageCompletion(completion);
@@ -1149,6 +1333,7 @@ export class DatabaseTransaction implements Transaction {
 				// the local is empty: a truthy one is what the loop staged into, and the retained-handle
 				// and replay branches below deliberately commit a handle other than this.transaction.
 				if (!transaction) transaction = this.transaction;
+				if (!options.transaction && this.writes.some((write) => write)) this.renewChainForNativeCommit();
 				this.open = TRANSACTION_STATE.CLOSED;
 				// RocksTransaction.commit() resolves with RETRY_NOW_VALUE (a number) under
 				// coordinatedRetry, or void on a normal commit/abort.
@@ -1234,6 +1419,30 @@ export class DatabaseTransaction implements Transaction {
 					if (transaction) {
 						this.writes = this.writes.filter((write) => write); // filter out removed entries
 						if (this.writes.length > 0) {
+							// Commit retries can construct fresh ranges on this live handle after read ownership ends.
+							readTransactionOwners.delete(transaction);
+							// Re-fence before submitting: the loop above skips operations already marked saved, so
+							// save()'s own check cannot see a holder that stalled between staging and commit. The
+							// retry/replay path re-saves every operation and is fenced there instead. Lease expiry
+							// only: an unlock() inside the lease leaves the staged write valid, an elapsed lease
+							// does not, whether or not the caller also unlocked.
+							for (let i = 0; this.hasLeaseProtectedWrite && i < this.writes.length; i++) {
+								const lapsed = this.writes[i].lockHandle;
+								if (!lapsed?.isLeaseExpired()) continue;
+								try {
+									transaction.abort();
+								} catch {}
+								// Every other terminal exit from commit() runs the logical cleanup too. Throwing
+								// straight out would strand the OTHER locks this transaction holds, its staged
+								// blobs, and the context's back-reference to a CLOSED transaction — and
+								// transaction()'s onComplete has no rejection path to run it later.
+								try {
+									this.abort();
+								} catch (error) {
+									harperLogger.debug?.('cleaning up a transaction whose record lock lapsed', error);
+								}
+								throw lockNotHeldError(lapsed);
+							}
 							// The transaction was created with coordinatedRetry:true (see
 							// getReadTxn), so commit() can resolve to RETRY_NOW_VALUE. That
 							// sentinel (a number) is why commitResolution is typed
@@ -2032,6 +2241,10 @@ function startMonitoringTxns() {
 		reportNow: number,
 		reportBudget: LongLivedHolderReportBudget
 	) {
+		if (txn.rangeReadActive) {
+			txn.rangeReadActive = false;
+			txn.renewReadTimeout();
+		}
 		reportIfLongLived(txn, reportThresholdMs, reportNow, reportBudget);
 		{
 			const commitChainHead = txn.commitChainHead ?? txn;

package/resources/LMDBTransaction.ts

@@ -1,5 +1,7 @@
 import {
 	DatabaseTransaction,
+	closeWriteInstance,
+	validateWrite,
 	shouldSpareCommitPhase,
 	transactionOpenTooLongError,
 	type CommitOptions,
@@ -37,10 +39,14 @@ export class LMDBTransaction extends DatabaseTransaction {
 	declare overloadChecked: boolean;
 	open = TRANSACTION_STATE.OPEN;
 
+	renewIdleTimeout(): void {
+		this.timeout = Math.max(txnExpiration, this.timeoutBudget ?? 0);
+	}
+
 	getReadTxn(): any {
 		// used optimistically
 		this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
-		this.timeout = Math.max(txnExpiration, this.timeoutBudget ?? 0); // reset the timeout
+		this.renewIdleTimeout();
 		if (this.stale) this.stale = false;
 		if (this.readTxn) {
 			if ((this.readTxn as any).openTimer) (this.readTxn as any).openTimer = 0;
@@ -113,12 +119,14 @@ export class LMDBTransaction extends DatabaseTransaction {
 
 		this.linkWrite(operation);
 		this.writes.push(operation); // standard path, add to current transaction
+		(this.ownedWrites ??= new WeakSet()).add(operation);
 		operation.stagedIn = this;
 	}
 
 	removeWrite(operation: TransactionWrite) {
 		const index = this.writes.indexOf(operation);
 		if (index > -1) this.writes[index] = null;
+		this.ownedWrites?.delete(operation);
 	}
 
 	/**
@@ -140,7 +148,11 @@ export class LMDBTransaction extends DatabaseTransaction {
 				this.validated = this.writes.length;
 				for (let i = start; i < this.validated; i++) {
 					const write = this.writes[i];
-					write?.validate?.(this.timestamp, this);
+					try {
+						if (write) validateWrite(write, this.timestamp, this);
+					} finally {
+						closeWriteInstance(write);
+					}
 				}
 				let hasBefore;
 				for (let i = start; i < this.validated; i++) {
@@ -194,6 +206,7 @@ export class LMDBTransaction extends DatabaseTransaction {
 				throw error;
 			}
 		}
+		if (!retries && this.writes.some((write) => write)) this.renewChainForNativeCommit();
 		// release the read snapshot so we don't keep it open longer than necessary
 		if (!retries) this.doneReadTxn();
 		this.open = options?.doneWriting ? TRANSACTION_STATE.LINGERING : TRANSACTION_STATE.OPEN;
@@ -203,7 +216,12 @@ export class LMDBTransaction extends DatabaseTransaction {
 		let writeIndex = 0;
 		this.writes = this.writes.filter((write) => write); // filter out removed entries
 		const doWrite = (write) => {
-			const completion = write.commit(txnTime, write.entry, retries);
+			let completion;
+			try {
+				completion = write.commit(txnTime, write.entry, retries);
+			} finally {
+				closeWriteInstance(write);
+			}
 			if (typeof completion?.then === 'function') {
 				// the aggregating Promise.all is attached a turn or more later (after the conditional batch
 				// or the exclusive transaction resolves), so handle rejection here to keep the gap from

package/resources/PrimaryRocksDatabase.ts

@@ -1,9 +1,10 @@
+import { trackReadRange } from './DatabaseTransaction.ts';
 import { RocksDatabase, type RocksDatabaseOptions, constants, type Store, Transaction } from '@harperfast/rocksdb-js';
 
 const FRESH_VERSION_FLAG = constants.FRESH_VERSION_FLAG;
 import { WeakLRUCache } from 'weak-lru-cache';
 import { when } from '../utility/when.ts';
-import { assignStoredFields, entryMap, METADATA, type Entry } from './RecordEncoder.ts';
+import { assignStoredFields, entryMap, METADATA, VERSION_REUSED, type Entry } from './RecordEncoder.ts';
 
 /**
  * RocksDatabase subclass that owns all primary-store behaviour for Harper tables:
@@ -121,6 +122,13 @@ export class PrimaryRocksDatabase extends RocksDatabase {
 	 */
 	getEntry(id: any, options?: any): any {
 		this.readCount++;
+		// Commit-path base reads must reflect the caller's transaction snapshot; the cache vouch
+		// answers "latest committed" — the wrong question there, and wrong outright for a version a
+		// resequenced write reused — so read the store directly, touching neither cache nor VT.
+		if (options?.uncachedRead) {
+			if (options.async) return when(super.get(id, options), (result) => this.#processEntry(result, id));
+			return this.#processEntry(super.getSync(id, options), id);
+		}
 		const cache = this.#cache;
 		// The cache stores the record *value* (weakly, via setValue) rather than
 		// the Entry: a WeakRef-wrapped value lets the LRFU expirer release it once
@@ -158,11 +166,16 @@ export class PrimaryRocksDatabase extends RocksDatabase {
 				if (cache && cachedValue !== undefined) cache.delete(id);
 				return undefined;
 			}
-			// Only object values can be weakly cached and mapped back to their Entry;
-			// primitive/empty values fall through uncached (no fast path, still correct).
-			if (entry.version != null && cache && entry.value != null && typeof entry.value === 'object') {
-				entryMap.set(entry.value, entry);
-				cache.setValue(id, entry.value, (entry.size ?? 0) >> 10);
+			if (entry.version != null && cache) {
+				// its version no longer identifies its value, so drop any copy already held
+				if (entry.metadataFlags & VERSION_REUSED) {
+					if (cachedValue !== undefined) cache.delete(id);
+				} else if (entry.value != null && typeof entry.value === 'object') {
+					// Only object values can be weakly cached and mapped back to their Entry;
+					// primitive/empty values fall through uncached (no fast path, still correct).
+					entryMap.set(entry.value, entry);
+					cache.setValue(id, entry.value, (entry.size ?? 0) >> 10);
+				}
 			}
 			return entry;
 		});
@@ -178,7 +191,7 @@ export class PrimaryRocksDatabase extends RocksDatabase {
 	}
 
 	getRange(options?: any): any {
-		const iterable = super.getRange(options);
+		const iterable = trackReadRange(options?.transaction, () => super.getRange(options));
 		if (options?.valuesForKey) return iterable.map((v: any) => v?.value);
 		if (options?.values === false || options?.onlyCount) return iterable;
 		if (!this.#enc.isRocksDB) return iterable;

package/resources/RecordEncoder.ts

@@ -30,7 +30,7 @@ import {
 } from './blob.ts';
 import { getThisNodeId } from './nodeIdMapping.ts';
 import { recordAction } from './analytics/write.ts';
-import { RocksDatabase } from '@harperfast/rocksdb-js';
+import { constants, RocksDatabase } from '@harperfast/rocksdb-js';
 import { when } from '../utility/when.ts';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
 import * as envMngr from '../utility/environment/environmentManager.js';
@@ -124,7 +124,26 @@ export const HAS_NODE_ID = 64;
 export const PENDING_LOCAL_TIME = 1;
 export const HAS_STRUCTURE_UPDATE = 0x100;
 export const HAS_ADDITIONAL_AUDIT_REFS = 0x80;
-export const VERSION_NOT_UNIQUE_FLAG = 0x10000;
+// A resequenced write keeps the (newer) version it merged onto, so one version identifies two
+// different stored values and version equality proves nothing. The metadata word this is set in is
+// the same header word the VerificationTable reads at value offset 8 — ACTION_32_BIT is the tag
+// byte its predicate requires — so the bit is what stops the native layer vouching for the version.
+export const VERSION_REUSED = constants.VERSION_NOT_UNIQUE_FLAG;
+// The bit is persisted in every resequenced record, so a rocksdb-js that moved it down onto one of
+// the flags above (or up into the tag byte) would silently change what records already on disk
+// mean: it must stay a single bit strictly between them.
+if (
+	typeof VERSION_REUSED !== 'number' ||
+	(VERSION_REUSED & (VERSION_REUSED - 1)) !== 0 ||
+	VERSION_REUSED < 0x10000 ||
+	VERSION_REUSED > 0x800000
+)
+	throw new Error(
+		`rocksdb-js VERSION_NOT_UNIQUE_FLAG (${VERSION_REUSED}) is not a single bit in the range Harper record metadata reserves for it — requires @harperfast/rocksdb-js >= 2.8.0`
+	);
+function versionIsReused(newVersion: number, existingEntry: { version?: number } | undefined): boolean {
+	return existingEntry?.version != null && newVersion <= existingEntry.version;
+}
 
 const TRACKED_WRITE_TYPES = new Set(['put', 'patch', 'delete', 'message', 'publish']);
 // For now we use this as the private property mechanism for mapping records to entries.
@@ -885,11 +904,12 @@ export function recordUpdater(store, tableId, auditStore) {
 				: NO_TIMESTAMP;
 		const expiresAt = options?.expiresAt;
 		if (expiresAt >= 0) assignMetadata |= HAS_EXPIRATION;
-		if (isRocksDB && record !== undefined && existingEntry?.version != null && newVersion <= existingEntry.version) {
-			assignMetadata = Math.max(assignMetadata, 0) | VERSION_NOT_UNIQUE_FLAG;
-		}
 		metadataInNextEncoding = assignMetadata;
 		expiresAtNextEncoding = expiresAt;
+		// Math.max normalizes the -1 "no metadata word" sentinel to 0 first: OR-ing the flag into
+		// -1 directly would stay -1 and silently drop the metadata word (and the flag with it).
+		if (isRocksDB && record !== undefined && versionIsReused(newVersion, existingEntry))
+			metadataInNextEncoding = Math.max(metadataInNextEncoding, 0) | VERSION_REUSED;
 		const putOptions: {
 			version: number;
 			instructedWrite?: boolean;