@harperfast/harper 5.2.10 → 5.3.0-alpha.1

package/resources/replayLogsGuards.ts

@@ -132,16 +132,66 @@ export function shouldAbortSlowReplay(totalElapsedMs: number, timeLimitMs = REPL
 }
 
 /**
- * Wraps a transaction-log query iterator so a corrupt/torn frame ends that log's iteration
- * cleanly instead of escaping as an uncaughtException. rocksdb-js throws a bounded RangeError
- * when an entry's framing is broken; framing loss means the next entry can't be located, so the
- * frame marks end-of-log (entries before it were already yielded) and startup replay /
- * replication broadcast continue. `onCorruptFrame` fires once, latched — kept a callback (not a
- * direct log) so this module stays out of the Harper module graph and is unit-testable.
+ * A corrupt transaction-log frame from rocksdb-js. `resyncPosition` is set only when intact entries
+ * follow the break, which is what distinguishes lost entries from a merely truncated tail; its
+ * absence is also all that any rocksdb-js predating that field can report.
+ */
+export type CorruptFrameError = RangeError & {
+	logId?: number | null;
+	position?: number | null;
+	resyncPosition?: number | null;
+	unreadableBytes?: number | null;
+};
+
+/**
+ * Corrupt frames hit by one `getRange` call, shared by its per-log iterators.
+ *
+ * `truncatedVersions` is what a consumer has to act on: a break destroys the framing after the last
+ * entry the broken log yielded, and whether the entries it swallowed continued that entry's version
+ * is exactly what can no longer be read — UNLESS that last entry's own `endTxn` already closed its
+ * transaction, in which case nothing of it was left open to swallow. That version's transaction is
+ * therefore incomplete only when it wasn't already known-closed, and replay must discard it rather
+ * than commit the part of it that was still readable. A log that broke before yielding anything
+ * truncates no transaction.
+ *
+ * `midLogBreak` is coarser: true once any break in this range left intact entries unreadable behind
+ * it (see {@link isMidLogBreak}), regardless of which version they belonged to. A consumer that must
+ * never serve a range with lost entries — an elected branch replay publishing itself as a trustworthy
+ * point-in-time copy — rejects on this rather than on `truncatedVersions`, since a mid-log break can
+ * strand entries whose version this range never even attributes to one log (harper#2016, #2063).
+ */
+export interface CorruptFrameStop {
+	breaks: number;
+	truncatedVersions: Set<number>;
+	midLogBreak: boolean;
+}
+
+/**
+ * Whether a corrupt frame is a mid-log break — intact entries followed it, so entries were lost
+ * rather than the log merely being torn at its tail. Shared by the reporter below and by
+ * `RocksTransactionLogStore.getRange`'s `CorruptFrameStop.midLogBreak`, so the two can't drift on
+ * what counts as a mid-log break.
+ */
+export function isMidLogBreak(error: CorruptFrameError): boolean {
+	return error.resyncPosition != null;
+}
+
+/**
+ * Wraps a transaction-log query iterator so a corrupt/torn frame ends that log's iteration cleanly
+ * instead of escaping as an uncaughtException.
+ *
+ * Iteration stops at the break whether or not intact entries follow it. Resuming past a mid-log
+ * break would recover those entries, but a transaction log carries no frame-level transaction
+ * boundaries: replay groups equal-version entries into one source transaction, so skipping a frame
+ * inside such a group applies and checkpoints the surviving subset of a transaction that never
+ * committed that way at the source. Availability loss is visible and recoverable; a silently torn
+ * transaction is neither. Recovery is deferred until the engine can resume at a proven boundary
+ * (harper#2016, harper#2063); `resyncPosition` is used only to report the break as lost entries
+ * rather than as a truncated tail.
  */
 export function endIteratorOnCorruptFrame<T>(
 	iterator: Iterator<T>,
-	onCorruptFrame: (error: RangeError) => void
+	onCorruptFrame: (error: CorruptFrameError) => void
 ): IterableIterator<T> {
 	let stopped = false;
 	return {
@@ -157,7 +207,7 @@ export function endIteratorOnCorruptFrame<T>(
 				// version-dependent (1.4.2 added hex offsets). Anything else re-throws.
 				if (!(error instanceof RangeError)) throw error;
 				stopped = true;
-				onCorruptFrame(error);
+				onCorruptFrame(error as CorruptFrameError);
 				return { done: true, value: undefined };
 			}
 		},
@@ -175,3 +225,116 @@ export function endIteratorOnCorruptFrame<T>(
 		},
 	};
 }
+
+/**
+ * A corrupt frame, accumulated for the life of the process. The same frame is re-encountered by
+ * every reader until each consumer's resume cursor has passed it, so this is deduplicated by
+ * location and the repeats become a count.
+ */
+export interface CorruptFrameReport {
+	log: string;
+	logId?: number;
+	position?: number;
+	/** Intact entries followed the break, so entries were lost rather than merely truncated. */
+	midLog: boolean;
+	/** Extent of the unreadable region, when the engine reports it; 0 when nothing valid follows it. */
+	unreadableBytes: number;
+	firstSeen: number;
+	lastSeen: number;
+	occurrences: number;
+}
+
+/** Distinct break sites retained. One physical corruption yields one site, so this is generous. */
+export const MAX_CORRUPT_FRAME_REPORTS = 256;
+
+// Re-encounters move a site to the end, so the first key is the least recently seen. Full means
+// evicting that one rather than refusing a new site, which could not then be deduplicated.
+const corruptFrameReports = new Map<string, CorruptFrameReport>();
+let evictedCorruptFrameReports = 0;
+
+/**
+ * Every corrupt frame seen by this worker. This is not yet consumed by cluster/health status;
+ * callers must aggregate it across worker threads before exposing a node-wide signal.
+ *
+ * Mid-log breaks are immediately logged at error level even without that consumer.
+ */
+export function getCorruptFrameReports(): CorruptFrameReport[] {
+	return [...corruptFrameReports.values()];
+}
+
+/** Break sites evicted because {@link MAX_CORRUPT_FRAME_REPORTS} was reached. */
+export function getEvictedCorruptFrameReportCount(): number {
+	return evictedCorruptFrameReports;
+}
+
+export function clearCorruptFrameReports() {
+	corruptFrameReports.clear();
+	evictedCorruptFrameReports = 0;
+}
+
+// `logId`/`position` are absent on any rocksdb-js predating the resync support, and every break on
+// a stream would then collapse onto one key — folding genuinely different corruptions into a single
+// count that only ever logs once. The message carries the offset and file in text, so it separates
+// them when the fields can't.
+function corruptFrameKey(logName: string, error: CorruptFrameError): string {
+	const { logId, position } = error;
+	return logId != null && position != null
+		? `${logName}\u0000${logId}:${position}`
+		: `${logName}\u0000${error.message}`;
+}
+
+/**
+ * Records a corrupt frame and logs it once per distinct break.
+ *
+ * A mid-log break is an `error`, not a `warn`: entries after it were acknowledged and are now
+ * quarantined behind it. Severity follows the break's own shape, never this pass's outcome — every
+ * pass stops, so keying on that would report the #2063 signature with the benign torn-tail `warn`.
+ * A site first seen as a torn tail can escalate later, since only a rocksdb-js that reports
+ * `resyncPosition` can tell the two apart.
+ */
+export function createCorruptFrameReporter(logger: {
+	warn: (message: string, error?: unknown) => void;
+	error: (message: string, error?: unknown) => void;
+}) {
+	return (logName: string) => (error: CorruptFrameError) => {
+		const midLog = isMidLogBreak(error);
+		const unreadableBytes = error.unreadableBytes ?? 0;
+		const now = Date.now();
+		const key = corruptFrameKey(logName, error);
+		const existing = corruptFrameReports.get(key);
+		if (existing) {
+			corruptFrameReports.delete(key);
+			corruptFrameReports.set(key, existing);
+			existing.occurrences++;
+			existing.lastSeen = now;
+			if (!midLog || existing.midLog) return;
+			existing.midLog = true;
+			existing.unreadableBytes = unreadableBytes;
+		} else {
+			if (corruptFrameReports.size >= MAX_CORRUPT_FRAME_REPORTS) {
+				corruptFrameReports.delete(corruptFrameReports.keys().next().value);
+				evictedCorruptFrameReports++;
+			}
+			corruptFrameReports.set(key, {
+				log: logName,
+				logId: error.logId ?? undefined,
+				position: error.position ?? undefined,
+				midLog,
+				unreadableBytes,
+				firstSeen: now,
+				lastSeen: now,
+				occurrences: 1,
+			});
+		}
+		if (midLog) {
+			logger.error(
+				`Corrupt entry in transaction log "${logName}"; ${unreadableBytes} byte(s) are unreadable and the entries within them are lost. ` +
+					'Intact entries follow the break, but reading stops there rather than skipping the frame, which could tear a source transaction: ' +
+					'they are quarantined until the log is repaired or this node is re-cloned, and they are neither replayed nor replicated meanwhile.',
+				error
+			);
+		} else {
+			logger.warn(`Stopping transaction log "${logName}" at a corrupt entry during replay`, error);
+		}
+	};
+}

package/resources/search.ts

@@ -1,11 +1,12 @@
 import { ClientError, IndexRebuildingError, Violation } from '../utility/errors/hdbError.ts';
 import { OVERFLOW_MARKER, MAX_SEARCH_KEY_LENGTH, SEARCH_TYPES } from '../utility/lmdb/terms.ts';
 import { compareKeys, MAXIMUM_KEY, writeKey } from 'ordered-binary';
-import { SKIP } from '@harperfast/extended-iterable';
+import { SKIP, ExtendedIterable } from '@harperfast/extended-iterable';
 import { INVALIDATED, EVICTED, freezeRecord } from './Table.ts';
 import type { DirectCondition, Id } from './ResourceInterface.ts';
 import { RequestTarget } from './RequestTarget.ts';
 import { lastMetadata } from './RecordEncoder.ts';
+import { writeKeyId } from './DatabaseTransaction.ts';
 import { recordAction } from './analytics/write';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
 
@@ -232,6 +233,41 @@ function composeRecordFilter(recordFilters, table, context): (primaryKey: Id) =>
 	};
 }
 
+/**
+ * A record's index entries are not adjacent — the composite `[indexedValue, primaryKey]` key sorts
+ * on the indexed value first — so comparing neighbours cannot collapse them and the scan has to
+ * remember what it already yielded (#2434).
+ *
+ * Heap cost is one key per distinct record in the scanned range, held for the life of the scan, and
+ * a page window does not cap it: sibling-condition and row filters run downstream, so a selective
+ * filter keeps the scan running and the set growing while the page fills. On a multi-million-row
+ * range that is hundreds of MB where main streamed at O(1). Accepted for #2434 over the bounded
+ * alternative, which costs a primary read per index entry.
+ */
+function distinctRecords(entries: any): AsyncIterable<Id> {
+	const distinct = new ExtendedIterable();
+	(distinct as any).iterate = (options) => {
+		// A non-scalar key decodes to a fresh instance per entry, so identity never matches it;
+		// `writeKeyId` is the store's own key equality. Its bytes get their own set because a scalar
+		// string id can legitimately carry exactly those bytes, and one set would fold the two —
+		// the collision `flattenKey` has, and the reason Table.ts prefixes its key ids.
+		const yieldedKeys = new Set();
+		const yieldedEncodedKeys = new Set();
+		// map rather than filter: filter clears `continueOnRecoverableError` for everything below it
+		return entries
+			.map((primaryKey) => {
+				const isEncoded = typeof primaryKey === 'object' && primaryKey !== null;
+				const yielded = isEncoded ? yieldedEncodedKeys : yieldedKeys;
+				const identity = isEncoded ? writeKeyId(primaryKey) : primaryKey;
+				if (yielded.has(identity)) return SKIP;
+				yielded.add(identity);
+				return primaryKey;
+			})
+			.iterate(options);
+	};
+	return distinct as any;
+}
+
 /**
  * Search for records or keys, based on the search condition, using an index if available
  * @param searchCondition
@@ -261,6 +297,9 @@ export function searchByIndex(
 		throw new ClientError(`Search condition for ${attribute_name} must have a value`);
 	}
 	let needFullScan;
+	// `[indexedValue, primaryKey]` is unique, so a scan that stays inside one indexed value cannot
+	// reach a record twice and skips the collapse below
+	let scansOneIndexedValue;
 	if (Array.isArray(attribute_name)) {
 		const firstAttributeName = attribute_name[0];
 		// get the potential relationship attribute
@@ -388,6 +427,7 @@ export function searchByIndex(
 				start = value;
 				end = value;
 				inclusiveEnd = true;
+				scansOneIndexedValue = true;
 				break;
 			case 'in':
 				// Phase 1: route through filter — index-merge optimization is a Phase 2 follow-up.
@@ -531,7 +571,7 @@ export function searchByIndex(
 			}
 			return loaded;
 		}
-		return index.getRange(rangeOptions).map(
+		const scanned = index.getRange(rangeOptions).map(
 			filter
 				? function ({ key, value }) {
 						let recordMatcher: any;
@@ -554,6 +594,14 @@ export function searchByIndex(
 					}
 				: ({ value }) => value
 		);
+		// Collapsing AFTER the map is required, not incidental: the condition's own filter tests one
+		// element at a time, so a record whose first entry fails it and whose second passes must
+		// still be reached. Collapsing first would settle that record on the failing entry and drop
+		// it. Scoped to attributes the schema declares multi-valued; a runtime array under an
+		// undeclared attribute repeats the same way but stays outside this boundary.
+		return scansOneIndexedValue || !findAttribute(Table.attributes, attribute_name)?.elements
+			? scanned
+			: distinctRecords(scanned);
 	} else {
 		return Table.primaryStore
 			.getRange(reverse ? { end: true, transaction, reverse: true } : { start: true, transaction })
@@ -1055,7 +1103,7 @@ export function filterByType(searchCondition, Table, context, filtered, isPrimar
 		canUseIndex =
 			canUseIndex && // is it a comparator that makes sense to use index
 			!isPrimaryKey && // no need to use index for primary keys, since we will be iterating over the primary keys
-			!!(Table && usableIndex(Table, attribute)) && // is there a usable (complete) index for this attribute
+			Table?.indices[attribute] && // is there an index for this attribute
 			estimatedIncomingCount > 3; // do we have a valid estimate of multiple incoming records (that is worth using an index for)
 		if (canUseIndex) {
 			if (searchCondition.estimated_count == undefined) estimateCondition(Table)(searchCondition);
@@ -1112,26 +1160,89 @@ export function filterByType(searchCondition, Table, context, filtered, isPrimar
 	}
 }
 
-/** The index a condition can be driven by; searchByIndex refuses a rebuilding one, so it reads as absent. */
-function usableIndex(table, attributeName): any {
-	const index = attributeName == null ? undefined : table.indices[attributeName];
-	return index?.isIndexing ? undefined : index;
-}
-
 /**
- * True when an index this attribute would have to be driven by is still being built, following a
- * relationship path to the local join index and on to the related table's leaf index.
+ * Estimates a range comparator's entry count from the store's statistical estimate, blended with
+ * the table-fraction heuristic by the estimate's confidence so low-confidence estimates degrade
+ * to the old behavior. Returns undefined (caller falls back to the heuristic) when the store
+ * cannot estimate, the shape is unexpected, or the executed range wouldn't match this one.
  */
-function drivesRebuildingIndex(table, attributeName, relationshipOffset = 0): boolean {
-	if (!Array.isArray(attributeName))
-		return attributeName != null && attributeName !== table.primaryKey && !!table.indices[attributeName]?.isIndexing;
-	if (relationshipOffset >= attributeName.length - 1)
-		return drivesRebuildingIndex(table, attributeName[relationshipOffset]);
-	const attribute = findAttribute(table.attributes, attributeName[relationshipOffset]);
-	if (!attribute) return false;
-	if (table.indices[attribute.relationship?.from]?.isIndexing) return true;
-	const relatedTable = attribute.definition?.tableClass || attribute.elements?.definition?.tableClass;
-	return !!relatedTable && drivesRebuildingIndex(relatedTable, attributeName, relationshipOffset + 1);
+function estimateRangeCondition(table, condition, searchType, fraction) {
+	const attributeName = condition[0] ?? condition.attribute;
+	const isPrimaryKey = attributeName === table.primaryKey;
+	const store = isPrimaryKey ? table.primaryStore : table.indices[attributeName];
+	// LMDB-backed and custom index stores do not implement estimateCount
+	if (typeof store?.estimateCount !== 'function') return undefined;
+	let value = condition[1] ?? condition.value;
+	if (value instanceof Date) value = value.getTime();
+	let range;
+	switch (searchType) {
+		case 'lt':
+			// `start: true` mirrors searchByIndex: `true` sorts above `null`, so an indexNulls
+			// index's `[null, primaryKey]` entries are outside the executed range
+			range = { start: true, end: value };
+			break;
+		case 'le':
+			range = { start: true, end: value, inclusiveEnd: true };
+			break;
+		case 'gt':
+			range = { start: value, exclusiveStart: true };
+			break;
+		case 'ge':
+			range = { start: value };
+			break;
+		case 'between':
+		case 'gele':
+		case 'gelt':
+		case 'gtlt':
+		case 'gtle': {
+			if (!Array.isArray(value)) return undefined;
+			let [start, end] = value;
+			if (start instanceof Date) start = start.getTime();
+			if (end instanceof Date) end = end.getTime();
+			range = {
+				start,
+				end,
+				inclusiveEnd: searchType === 'between' || searchType === 'gele' || searchType === 'gtle',
+				exclusiveStart: searchType === 'gtlt' || searchType === 'gtle',
+			};
+			break;
+		}
+		case 'starts_with': {
+			const prefix = value?.toString();
+			if (!prefix) return undefined;
+			range = { start: prefix, end: getStringPrefixUpperBound(prefix) };
+			break;
+		}
+		case 'prefix': {
+			let start = Array.isArray(value) ? value : [value, null];
+			if (start[start.length - 1] != null) start = start.concat(null);
+			const end = start.slice(0);
+			end[end.length - 1] = MAXIMUM_KEY;
+			range = { start, end };
+			break;
+		}
+		default:
+			return undefined;
+	}
+	// Long string bounds get truncated + filtered at execution (searchByIndex), so the
+	// executed range is wider than this one; don't estimate what won't be iterated.
+	if (
+		(typeof range.start === 'string' && range.start.length > MAX_SEARCH_KEY_LENGTH) ||
+		(typeof range.end === 'string' && range.end.length > MAX_SEARCH_KEY_LENGTH)
+	) {
+		return undefined;
+	}
+	let count, confidence;
+	try {
+		({ count, confidence } = store.estimateCount(range) ?? {});
+	} catch {
+		// a concurrently closing/dropped store must degrade the plan, not fail the query
+		return undefined;
+	}
+	if (!Number.isFinite(count) || count < 0 || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)
+		return undefined;
+	const heuristic = fraction * estimatedEntryCount(table.primaryStore) + 1;
+	return Math.max(1, Math.round(confidence * count + (1 - confidence) * heuristic));
 }
 
 export function estimateCondition(table) {
@@ -1163,8 +1274,12 @@ export function estimateCondition(table) {
 			// skip if it is cached
 			let searchType = condition.comparator || condition.search_type;
 			searchType = ALTERNATE_COMPARATOR_NAMES[searchType] || searchType;
-			// before comparator dispatch: several branches fall back to a finite table-fraction heuristic
-			if (drivesRebuildingIndex(table, condition[0] ?? condition.attribute)) {
+			if (condition.negated) {
+				// a negated condition always executes as a full scan (searchByIndex forces
+				// needFullScan), so follow the filter-only convention used by contains/ends_with:
+				// estimate Infinity so its positive-range estimate can never win the driving-condition
+				// ordering. Short-circuit here rather than computing (and discarding) a positive-range
+				// estimate that would cross the native FFI boundary for nothing.
 				condition.estimated_count = Infinity;
 			} else if (searchType === SEARCH_TYPES.EQUALS || !searchType) {
 				const attribute_name = condition[0] ?? condition.attribute;
@@ -1192,12 +1307,12 @@ export function estimateCondition(table) {
 					}
 				} else {
 					// we only attempt to estimate count on equals operator because that's really all that LMDB supports (some other key-value stores like libmdbx could be considered if we need to do estimated counts of ranges at some point)
-					const index = usableIndex(table, attribute_name);
+					const index = table.indices[attribute_name];
 					condition.estimated_count = index ? index.getValuesCount(condition[1] ?? condition.value) : Infinity;
 				}
 			} else if (searchType === 'contains' || searchType === 'ends_with' || searchType === 'ne') {
 				const attribute_name = condition[0] ?? condition.attribute;
-				const index = usableIndex(table, attribute_name);
+				const index = table.indices[attribute_name];
 				if (condition.value === null && searchType === 'ne') {
 					condition.estimated_count = Math.max(
 						estimatedEntryCount(table.primaryStore) - (index ? index.getValuesCount(null) : 0),
@@ -1206,7 +1321,7 @@ export function estimateCondition(table) {
 				} else condition.estimated_count = Infinity;
 			} else if (searchType === 'in') {
 				const attribute_name = condition[0] ?? condition.attribute;
-				const index = usableIndex(table, attribute_name);
+				const index = table.indices[attribute_name];
 				if (Array.isArray(condition.value) && index) {
 					// Sum of per-value matches (over-counts duplicates but is a fine ceiling)
 					let estimate = 0;
@@ -1217,14 +1332,17 @@ export function estimateCondition(table) {
 				} else if (Array.isArray(condition.value)) {
 					condition.estimated_count = Infinity;
 				} else condition.estimated_count = Infinity;
-				// for range queries (betweens, startsWith, greater, etc.), just arbitrarily guess
 			} else if (searchType === 'starts_with' || searchType === 'prefix')
-				condition.estimated_count = STARTS_WITH_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
+				condition.estimated_count =
+					estimateRangeCondition(table, condition, searchType, STARTS_WITH_ESTIMATE) ??
+					STARTS_WITH_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
 			else if (searchType === 'between')
-				condition.estimated_count = BETWEEN_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
+				condition.estimated_count =
+					estimateRangeCondition(table, condition, searchType, BETWEEN_ESTIMATE) ??
+					BETWEEN_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
 			else if (searchType === 'sort') {
 				const attribute_name = condition[0] ?? condition.attribute;
-				const index = usableIndex(table, attribute_name);
+				const index = table.indices[attribute_name];
 				if (index?.customIndex?.estimateCountAsSort)
 					// allow custom index to define its own estimation of counts
 					condition.estimated_count = index.customIndex.estimateCountAsSort(condition);
@@ -1232,11 +1350,14 @@ export function estimateCondition(table) {
 			} else {
 				// for the search types that use the broadest range, try do them last
 				const attribute_name = condition[0] ?? condition.attribute;
-				const index = usableIndex(table, attribute_name);
+				const index = table.indices[attribute_name];
 				if (index?.customIndex?.estimateCount)
 					// allow custom index to define its own estimation of counts
 					condition.estimated_count = index.customIndex.estimateCount(condition.value);
-				else condition.estimated_count = OPEN_RANGE_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
+				else
+					condition.estimated_count =
+						estimateRangeCondition(table, condition, searchType, OPEN_RANGE_ESTIMATE) ??
+						OPEN_RANGE_ESTIMATE * estimatedEntryCount(table.primaryStore) + 1;
 			}
 			// we give a condition significantly more weight/preference if we will be ordering by it
 			if (typeof condition.descending === 'boolean') condition.estimated_count /= 2;
@@ -1422,6 +1543,7 @@ function parseBlock(query, expectedEnd) {
 						break;
 					case 'group-by':
 						recordError('group by is not implemented yet');
+						break;
 					case 'sort':
 						query.sort = toSortObject(args);
 						break;

package/resources/transactionBroadcast.ts

@@ -95,7 +95,7 @@ export function addSubscription(table, key, listener?: (key) => any, startTime?:
  * subscription and get the initial state.
  */
 class Subscription extends IterableEventQueue {
-	listener: (recordId: Id, auditEntry: any, localTime: number, beginTxn: boolean) => void;
+	listener: (recordId: Id, auditEntry: any, txnLogKey: number, beginTxn: boolean) => void;
 	subscriptions: any;
 	startTime?: number;
 	includeDescendants?: boolean;
@@ -178,10 +178,10 @@ function notifyFromTransactionData(subscriptions, auditLogIterable?, allowYield
 			}
 			if (result.done) break;
 			const auditRecord = result.value;
-			const timestamp: number = auditRecord.localTime ?? auditRecord.version;
+			const timestamp: number = auditRecord.txnLogKey;
 			subscriptions.lastTxnTime = timestamp;
 			// the transaction extent: RocksDB entries committed together share the log key (record
-			// versions may differ); LMDB's localTime is a per-entry audit key, so version delimits there
+			// versions may differ); LMDB's transaction-log key is per-entry, so version delimits there
 			const txnKey = auditStore.reusableIterable ? timestamp : auditRecord.version;
 			if (ACTIONS_OF_INTEREST.includes(auditRecord.type)) {
 				const tableSubscriptions = subscriptions[auditRecord.tableId];