@harperfast/rocksdb-js 2.12.0 → 2.14.0

package/dist/index.mjs

@@ -3,16 +3,16 @@ import { execSync } from "node:child_process";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isMainThread } from "node:worker_threads";
 import { access, cp, mkdir, readdir, rm } from "node:fs/promises";
 import * as orderedBinary from "ordered-binary";
 import { ExtendedIterable } from "@harperfast/extended-iterable";
 import { Encoder } from "msgpackr";
 
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 
-//#endregion
-//#region src/load-binding.ts
+// src/load-binding.ts
 const nativeExtRE = /\.node$/;
 const req = createRequire(import.meta.url);
 /**
@@ -55,6 +55,18 @@ function locateBinding() {
 	throw new Error("Unable to locate rocksdb-js native binding");
 }
 const binding = req(locateBinding());
+if (isMainThread) {
+	let exitShutdownRan = false;
+	const shutdownOnExit = () => {
+		if (exitShutdownRan) return;
+		exitShutdownRan = true;
+		if (!binding.shutdownOnExit() && !process.exitCode) process.exitCode = 1;
+	};
+	process.on("exit", shutdownOnExit);
+	process.on("uncaughtExceptionMonitor", () => {
+		if (process._exiting) shutdownOnExit();
+	});
+}
 /**
 * The native `BackgroundError` constructor (a real `Error` subclass). Exported
 * as both a value — for `err instanceof BackgroundError` — and, via declaration
@@ -117,7 +129,7 @@ const getRegistryStatus = binding.registryStatus;
 */
 const registryStatus = getRegistryStatus;
 /**
-* Flushes every open database and waits for outstanding compactions, then
+* Flushes every open database and cancels its outstanding compactions, then
 * releases the registry.
 *
 * **Throws** the first failure it encounters: a close whose native teardown
@@ -127,19 +139,10 @@ const registryStatus = getRegistryStatus;
 * `database:closeFailed`; a timeout has no event, so the throw is its only
 * signal.
 *
-* A `process.on('exit')` listener must therefore wrap it: an exception thrown
-* from an `exit` listener skips every `exit` listener registered after it (and
-* sets exit code 1 unless an `uncaughtException` handler is installed).
-*
-* ```typescript
-* process.on('exit', () => {
-* 	try {
-* 		shutdown();
-* 	} catch (error) {
-* 		console.error('rocksdb-js shutdown failed', error);
-* 	}
-* });
-* ```
+* You do not need to call it at exit: when rocksdb-js loads on the main
+* thread it registers a `process.on('exit')` listener that does the same and
+* reports failures to stderr and the exit code instead of throwing (see the
+* `shutdownOnExit` config option). Calling it yourself as well is safe.
 */
 const shutdown = binding.shutdown;
 const currentThreadId = binding.currentThreadId;
@@ -147,7 +150,7 @@ const currentThreadId = binding.currentThreadId;
 * Reads the process-wide steady clock: `std::chrono::steady_clock` as
 * fractional milliseconds from an unspecified origin that is fixed for the life
 * of the process. Every sample in the process — main thread and every
-* `worker_threads` worker, whenever started or restarted, on Node, Bun and Deno
+* `worker_threads` worker, whenever started or restarted, on Node and Bun
 * — is in one domain, and the difference between two samples is real elapsed
 * time unaffected by wall-clock steps. Non-decreasing but not unique (two
 * samples may be equal; treat `==` as "not later"). Windows QPC samples from
@@ -159,6 +162,30 @@ const currentThreadId = binding.currentThreadId;
 */
 const steadyClockNow = binding.steadyClockNow;
 /**
+* Raises the process-wide monotonic timestamp clock — the one behind
+* `db.getMonotonicTimestamp()`, every transaction's initial timestamp and so
+* every transaction-log batch key — to at least `timestamp` (Unix epoch
+* milliseconds). Every timestamp the process issues after the call is strictly
+* greater than `timestamp`, across every database and `worker_threads` worker.
+* Timestamps already issued and timestamps adopted with `txn.setTimestamp()`
+* are unaffected. No open database is needed.
+*
+* Use it to carry a floor the caller persisted across a restart, which a
+* backward wall-clock step would otherwise let the new process reissue. The
+* floor is in memory only and is not a fence: restore it before the process
+* starts any transaction it originates, and pass only floors this node
+* persisted itself, since the clock stays that far ahead until wall time
+* catches up.
+*
+* @returns `true` if the clock was raised: `timestamp` was ahead of both the
+* wall clock and every timestamp already issued. `false` if the clock was
+* already at or above it.
+* @throws {TypeError} If `timestamp` is not a number.
+* @throws {RangeError} If `timestamp` is not finite, is not greater than 0, is
+* not less than 8.64e15, or is more than ten years ahead of the wall clock.
+*/
+const raiseTimestampFloor = binding.raiseTimestampFloor;
+/**
 * Advises the kernel that the file-backed pages of every mapped transaction log
 * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
 * without being freed — useful during replication catch-up, where a full read of
@@ -185,12 +212,30 @@ const transactionLogMapCount = binding.transactionLogMapCount;
 */
 const lockWakeCallbackCount = binding.lockWakeCallbackCount;
 /**
+* The calling thread's counters for the per-transaction iterator pool: pooled
+* iterators created, and idle ones reused by a later range. Internal — used by
+* tests to prove a range was served by a reused iterator.
+*/
+const iteratorPoolStats = binding.iteratorPoolStats;
+/**
+* Whether transaction `getRange()` reuses pooled native iterators (off with
+* `ROCKSDB_JS_ITERATOR_POOL=0`). Internal.
+*/
+const iteratorPoolEnabled = binding.iteratorPoolEnabled;
+/**
 * Test-only: force the next `count` transaction commits to fail with TryAgain (rolled back, so
 * no data is committed), reproducing a stranded-snapshot conflict deterministically. Pass 0 to
 * disarm. Used by the ERR_TRY_AGAIN retry regression test.
 */
 const forceTryAgainForTesting = binding.forceTryAgainForTesting;
 /**
+* Test-only: turn the RocksDB conflict check before the transaction-log write off (`true`) or back
+* on, so a test can make a logged batch conflict at commit from a stale snapshot.
+*/
+const disablePrelogConflictCheckForTesting = binding.disablePrelogConflictCheckForTesting;
+/** Test-only: run the pre-log conflict check on retries alone (`true`, the default) or on every attempt. */
+const setPrelogConflictCheckRetriesOnlyForTesting = binding.setPrelogConflictCheckRetriesOnlyForTesting;
+/**
 * Test-only seam: makes the physical column-family drop report failure.
 * `0` = inert, `1` = fail without dropping (the retry performs the drop),
 * `2` = drop for real and then report failure (the retry resolves as
@@ -233,8 +278,7 @@ const nativeValidateTransactionLog = binding.validateTransactionLog;
 const stats = binding.stats;
 const version = binding.version;
 
-//#endregion
-//#region src/validate-transaction-log.ts
+// src/validate-transaction-log.ts
 /**
 * Validates a transaction log store directory: every `<sequence>.txnlog` file
 * is checked for a valid header (token, version) and intact v1 entry framing
@@ -274,8 +318,7 @@ function validateTransactionLogStore(path, options) {
 	return new Promise((resolve, reject) => nativeValidateTransactionLog(resolve, reject, path, options?.strict ?? false));
 }
 
-//#endregion
-//#region src/backup.ts
+// src/backup.ts
 /** Subdirectory (under a backup directory) holding per-backup transaction log snapshots. */
 const TRANSACTION_LOGS_DIRNAME = "transaction_logs";
 /** Non-blocking existence check (`fs.existsSync` would block the event loop). */
@@ -559,8 +602,7 @@ const backups = {
 	}
 };
 
-//#endregion
-//#region src/count-estimator.ts
+// src/count-estimator.ts
 /**
 * Below this many traversed entries the observed density is too noisy to
 * calibrate with, so `estimate()` returns the raw statistical estimate.
@@ -703,8 +745,7 @@ var CountEstimator = class {
 	}
 };
 
-//#endregion
-//#region src/util.ts
+// src/util.ts
 /**
 * Parses a duration string into milliseconds.
 *
@@ -775,8 +816,7 @@ function when(subject, callback, errback) {
 	}
 }
 
-//#endregion
-//#region src/dbi.ts
+// src/dbi.ts
 /**
 * The base class for all database operations. This base class is shared by
 * `RocksDatabase` and `Transaction`.
@@ -1061,8 +1101,7 @@ var DBI = class DBI {
 	}
 };
 
-//#endregion
-//#region src/tar.ts
+// src/tar.ts
 /**
 * A minimal, dependency-free streaming USTAR (POSIX tar) encoder.
 *
@@ -1268,8 +1307,7 @@ var TarEncoder = class {
 	}
 };
 
-//#endregion
-//#region src/backup-stream.ts
+// src/backup-stream.ts
 /** Native event discriminator: a new file header (vs. a payload chunk). */
 const EVENT_FILE = 0;
 /**
@@ -1313,9 +1351,22 @@ async function backupToStream(db, stream, options) {
 	}
 }
 
-//#endregion
-//#region src/dbi-iterator.ts
-const { ITERATOR_RESULT_DONE, ITERATOR_RESULT_FAST } = constants;
+// src/dbi-iterator.ts
+const { ITERATOR_RESULT_DONE, ITERATOR_RESULT_FAST, ITERATOR_RESULT_RELEASED } = constants;
+const transactionsToTrim = /* @__PURE__ */ new Set();
+function trimIdleIterators() {
+	try {
+		for (const transaction of transactionsToTrim) transaction.trimIterators();
+	} finally {
+		transactionsToTrim.clear();
+	}
+}
+function scheduleTrim(transaction) {
+	if (transaction !== void 0) {
+		if (transactionsToTrim.size === 0) setImmediate(trimIdleIterators);
+		transactionsToTrim.add(transaction);
+	}
+}
 const DONE_RESULT = Object.freeze({
 	done: true,
 	value: void 0
@@ -1335,10 +1386,12 @@ var DBIterator = class {
 	#includeValues;
 	#limit;
 	#yielded = 0;
-	constructor(iterator, store, includeValues, limit) {
+	#transaction;
+	constructor(iterator, store, includeValues, limit, transaction) {
 		this.iterator = iterator;
 		this.store = store;
 		this.#includeValues = includeValues;
+		this.#transaction = transaction;
 		this.#limit = limit ?? void 0;
 	}
 	[Symbol.iterator]() {
@@ -1346,7 +1399,7 @@ var DBIterator = class {
 	}
 	next() {
 		if (this.#limit !== void 0 && this.#yielded >= this.#limit) {
-			this.iterator.return?.();
+			this.#release(this.iterator.return());
 			return DONE_RESULT;
 		}
 		let result;
@@ -1354,11 +1407,15 @@ var DBIterator = class {
 			result = this.iterator.next();
 		} catch (err) {
 			try {
-				this.iterator.return?.();
+				this.#release(this.iterator.return());
 			} catch {}
 			throw err;
 		}
 		if (result === ITERATOR_RESULT_DONE) return DONE_RESULT;
+		if (result === ITERATOR_RESULT_RELEASED) {
+			scheduleTrim(this.#transaction);
+			return DONE_RESULT;
+		}
 		this.#yielded++;
 		const includeValues = this.#includeValues;
 		const value = {};
@@ -1379,20 +1436,23 @@ var DBIterator = class {
 		};
 	}
 	return(value) {
-		this.iterator.return?.();
+		this.#release(this.iterator.return());
 		return {
 			done: true,
 			value
 		};
 	}
 	throw(err) {
-		this.iterator.throw?.(err);
+		this.#release(this.iterator.throw(err));
 		throw err;
 	}
+	#release(pooled) {
+		if (pooled) scheduleTrim(this.#transaction);
+		this.#transaction = void 0;
+	}
 };
 
-//#endregion
-//#region src/encoding.ts
+// src/encoding.ts
 /**
 * Initializes the key encoder functions.
 *
@@ -1459,8 +1519,7 @@ function createFixedBuffer(size) {
 	return buffer;
 }
 
-//#endregion
-//#region src/store.ts
+// src/store.ts
 const { ONLY_IF_IN_MEMORY_CACHE_FLAG, NOT_IN_MEMORY_CACHE_FLAG, ALWAYS_CREATE_NEW_BUFFER_FLAG, FRESH_VERSION_FLAG, POPULATE_VERSION_FLAG, ITERATOR_REVERSE_FLAG, ITERATOR_INCLUSIVE_END_FLAG, ITERATOR_EXCLUSIVE_START_FLAG, ITERATOR_INCLUDE_VALUES_FLAG, ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG, ITERATOR_CONTEXT_IS_TRANSACTION_FLAG, ITERATOR_HAS_TRANSACTION_ID_FLAG } = constants;
 const KEY_BUFFER_SIZE = 4096;
 const KEY_BUFFER = createFixedBuffer(KEY_BUFFER_SIZE);
@@ -1761,6 +1820,14 @@ var Store = class {
 	*/
 	writeBufferSize;
 	/**
+	* The memtable arena block size in bytes; `0` or unset is automatic.
+	*/
+	arenaBlockSize;
+	/**
+	* Bits per key of the whole-key filter in each SST; `0` disables filters.
+	*/
+	bloomFilterBitsPerKey;
+	/**
 	* The function used to encode keys using the shared `keyBuffer`.
 	*/
 	writeKey;
@@ -1813,6 +1880,8 @@ var Store = class {
 		this.timestampFloorLog = options?.timestampFloorLog;
 		this.verificationTable = options?.verificationTable;
 		this.writeBufferSize = options?.writeBufferSize;
+		this.arenaBlockSize = options?.arenaBlockSize;
+		this.bloomFilterBitsPerKey = options?.bloomFilterBitsPerKey;
 		this.writeKey = writeKey;
 		this.#columnFamilyOptions = options ? { ...options } : void 0;
 	}
@@ -1972,7 +2041,7 @@ var Store = class {
 		const result = context.getSync(keyParam, flags | ONLY_IF_IN_MEMORY_CACHE_FLAG, txnId, expectedVersion);
 		if (typeof result === "number") {
 			if (result === NOT_IN_MEMORY_CACHE_FLAG) return new Promise((resolve, reject) => {
-				context.get(keyParam, resolve, reject, txnId, expectedVersion);
+				context.get(keyParam, resolve, reject, txnId, expectedVersion, flags);
 			});
 			if (result === FRESH_VERSION_FLAG) return result;
 			VALUE_BUFFER.end = result;
@@ -2063,7 +2132,9 @@ var Store = class {
 		if (context !== this.db) flags |= ITERATOR_CONTEXT_IS_TRANSACTION_FLAG;
 		if (txnId !== void 0) flags |= ITERATOR_HAS_TRANSACTION_ID_FLAG;
 		const advancedOptions = options !== void 0 && (options.adaptiveReadahead !== void 0 || options.asyncIO !== void 0 || options.autoReadaheadSize !== void 0 || options.backgroundPurgeOnIteratorCleanup !== void 0 || options.fillCache !== void 0 || options.readaheadSize !== void 0 || options.tailing !== void 0) ? options : void 0;
-		return new ExtendedIterable(new DBIterator(new NativeIterator(context, flags, startKeyEnd, endKeyStart, endKeyEnd, advancedOptions, txnId), this, includeValues, options?.limit));
+		const nativeIterator = new NativeIterator(context, flags, startKeyEnd, endKeyStart, endKeyEnd, advancedOptions, txnId);
+		const transaction = context !== this.db ? context : options?.transaction?._context;
+		return new ExtendedIterable(new DBIterator(nativeIterator, this, includeValues, options?.limit, transaction));
 	}
 	getSync(context, key, alwaysCreateNewBuffer = false, options) {
 		const keyParam = getKeyParam(this.encodeKey(key));
@@ -2177,7 +2248,9 @@ var Store = class {
 			transactionLogsPath: this.transactionLogsPath,
 			timestampFloorLog: this.timestampFloorLog,
 			verificationTable: this.verificationTable,
-			writeBufferSize: this.writeBufferSize
+			writeBufferSize: this.writeBufferSize,
+			arenaBlockSize: this.arenaBlockSize,
+			bloomFilterBitsPerKey: this.bloomFilterBitsPerKey
 		});
 		this.identityPath = this.db.identityPath;
 		return false;
@@ -2283,8 +2356,7 @@ function getKeyParam(keyBuffer) {
 	return keyBuffer.length;
 }
 
-//#endregion
-//#region src/transaction.ts
+// src/transaction.ts
 /**
 * Sentinel value returned by `commit()` when `coordinatedRetry: true` and the
 * transaction encountered an IsBusy conflict. The native layer parks on VT
@@ -2308,10 +2380,18 @@ var TransactionAlreadyAbortedError = class extends Error {
 */
 var TransactionRetryableError = class extends Error {
 	hasLog;
+	/**
+	* The attempt was refused before writing its transaction-log batch (`transactionLogAbortMarkers`):
+	* an older transaction held a write intent on one of its keys (`transactionLogWriteIntents`), or, on a retry, RocksDB's conflict
+	* check found a write that already committed (see `lastConflictKind()`). Nothing of it is in the
+	* log, so a retry may stage its batch afresh.
+	*/
+	refusedBeforeLog;
 	txn;
 	constructor(error, txn) {
 		super(error.message);
 		this.hasLog = error.hasLog ?? false;
+		this.refusedBeforeLog = error.refusedBeforeLog ?? false;
 		this.txn = txn;
 	}
 };
@@ -2341,6 +2421,38 @@ var TransactionAbandonedError = class extends Error {
 	}
 };
 /**
+* `abort()` of a transaction whose transaction-log batch could not be marked aborted
+* (`transactionLogAbortMarkers`). The batch stays unresolved, so committed readers do not pass it and
+* the log store refuses appends, until a retry on the next append, database flush or store close
+* marks it.
+*/
+var TransactionAbortUnresolvedError = class extends Error {
+	code = "ERR_TRANSACTION_ABORT_UNRESOLVED";
+	txn;
+	constructor(error, txn) {
+		super(error.message);
+		this.txn = txn;
+	}
+};
+/**
+* Why a transaction's most recent attempt was refused or retried, from {@link Transaction.lastConflictKind}.
+*/
+const ConflictKind = {
+	none: 0,
+	/** Refused on an older transaction's write intent before writing its log batch. */
+	intentBeforeLog: 1,
+	/** Refused on an older transaction's write intent after its log batch was written. */
+	intentAfterLog: 2,
+	/** RocksDB found a conflict at commit. */
+	atCommit: 3,
+	/**
+	* RocksDB's conflict check, run before the log write, found a write that already committed, or,
+	* as at commit, could not validate because the memtable history it needs was flushed (needs a
+	* RocksDB build that exports the check).
+	*/
+	checkBeforeLog: 4
+};
+/**
 * Provides transaction level operations to a transaction callback.
 */
 var Transaction = class extends DBI {
@@ -2355,9 +2467,10 @@ var Transaction = class extends DBI {
 		if (store.readOnly) {
 			super(store);
 			this.#txn = { id: 0 };
-			this.abandonWrites = this.abort = this.commitSync = this.setTimestamp = () => {};
+			this.abandonWrites = this.abort = this.commitSync = this.setTimestamp = this.setParkDeadline = () => {};
 			this.commit = async () => {};
-			this.getTimestamp = () => 0;
+			this.getTimestamp = this.lastConflictKind = () => 0;
+			this.logWritten = () => false;
 		} else {
 			const txn = new NativeTransaction(store.db, options);
 			super(store, txn);
@@ -2383,6 +2496,7 @@ var Transaction = class extends DBI {
 			this.#txn.abort();
 		} catch (err) {
 			if (err instanceof Error && "code" in err && err.code === "ERR_TRANSACTION_ABANDONED") throw new TransactionAbandonedError(err, this);
+			if (err instanceof Error && "code" in err && err.code === "ERR_TRANSACTION_ABORT_UNRESOLVED") throw new TransactionAbortUnresolvedError(err, this);
 			throw err;
 		}
 	}
@@ -2451,6 +2565,28 @@ var Transaction = class extends DBI {
 		return this.#txn.getTimestamp();
 	}
 	/**
+	* Whether this transaction's batch is in the transaction log. A commit conflict after the batch
+	* was written keeps it for the retry, which must not stage it again; an attempt refused before
+	* writing it (`refusedBeforeLog`) leaves nothing.
+	*/
+	logWritten() {
+		return this.#txn.logWritten();
+	}
+	/**
+	* Why the most recent attempt was refused or retried; one of {@link ConflictKind}.
+	*/
+	lastConflictKind() {
+		return this.#txn.lastConflictKind();
+	}
+	/**
+	* Bounds coordinated-retry parks: past `deadline` (epoch milliseconds) a parked commit resolves
+	* `RETRY_NOW` at once, so a caller enforcing its own deadline can abort instead of waiting out
+	* the default park bound. 0 clears it.
+	*/
+	setParkDeadline(deadline) {
+		this.#txn.setParkDeadline(deadline);
+	}
+	/**
 	* Get the transaction id.
 	*/
 	get id() {
@@ -2471,8 +2607,8 @@ var Transaction = class extends DBI {
 	}
 };
 
-//#endregion
-//#region src/database.ts
+// src/database.ts
+const backoffCell = new Int32Array(new SharedArrayBuffer(4));
 const BACKGROUND_ERROR_SEVERITY_NAMES = [
 	"none",
 	"soft",
@@ -2882,6 +3018,19 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.flushSync(options);
 	}
 	/**
+	* Syncs the write-ahead log to stable storage (`DB::SyncWAL`), so every WAL-backed write
+	* committed before the call survives a power loss afterwards. Unlike {@link flush} it writes
+	* no SST file and never stalls writers. Not covered: writes that skipped the WAL
+	* (`disableWAL`), and transaction-log files, which keep their own durability. Runs on the
+	* libuv threadpool; RocksDB serializes concurrent syncs of one WAL, so keep one in flight
+	* per database rather than parking pool workers on a queue of them.
+	*
+	* On a read-only database the returned promise resolves without syncing.
+	*/
+	syncWal() {
+		return new Promise((resolve, reject) => this.store.db.syncWal(resolve, reject));
+	}
+	/**
 	* Returns the most recent {@link BackgroundError} observed on this database, or
 	* `null` when none has occurred. The `'error'` event is the push counterpart;
 	* this is the pull equivalent for on-demand checks (e.g. a health probe) and
@@ -3350,7 +3499,10 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	async transaction(callback, options) {
 		if (typeof callback !== "function") throw new TypeError("Callback must be a function");
 		const maxRetries = options?.maxRetries ?? 3;
-		const txn = new Transaction(this.store, options);
+		const txn = new Transaction(this.store, options?.retryOnBusy === false && options.coordinatedRetry ? {
+			...options,
+			coordinatedRetry: false
+		} : options);
 		let result;
 		this.notify("begin-transaction");
 		for (let attempt = 1; attempt <= maxRetries; attempt++) {
@@ -3364,7 +3516,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 				commitResult = await txn.commit();
 			} catch (commitErr) {
 				if (commitErr instanceof TransactionAlreadyAbortedError) return;
-				if (commitErr instanceof TransactionRetryableError && (options?.retryOnBusy ?? commitErr.hasLog) && attempt < maxRetries) continue;
+				if (commitErr instanceof TransactionRetryableError && (options?.retryOnBusy ?? (commitErr.hasLog || commitErr.refusedBeforeLog)) && attempt < maxRetries) continue;
 				this.#abandonTransaction(txn, commitErr);
 				return;
 			}
@@ -3396,10 +3548,13 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		if (typeof callback !== "function") throw new TypeError("Callback must be a function");
 		const maxRetries = options?.maxRetries ?? 3;
 		const isRetryable = (err, attempt) => {
-			return err instanceof TransactionRetryableError && (options?.retryOnBusy ?? err.hasLog) && attempt <= maxRetries;
+			if (!(err instanceof TransactionRetryableError && (options?.retryOnBusy ?? (err.hasLog || err.refusedBeforeLog)) && attempt <= maxRetries)) return false;
+			const kind = txn.lastConflictKind();
+			if (kind === ConflictKind.intentBeforeLog || kind === ConflictKind.intentAfterLog) Atomics.wait(backoffCell, 0, 0, Math.min(2 ** attempt, 50));
+			return true;
 		};
+		const txn = new Transaction(this.store, options);
 		const runAttempt = (attempt) => {
-			const txn = new Transaction(this.store, options);
 			let result;
 			try {
 				result = callback(txn, attempt);
@@ -3415,7 +3570,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 					if (isRetryable(commitErr, attempt)) return runAttempt(attempt + 1);
 					this.#abandonTransaction(txn, commitErr);
 				}
-			});
+			}, (callbackErr) => this.#abortTransaction(txn, callbackErr));
 			try {
 				txn.commitSync();
 				return result;
@@ -3440,7 +3595,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		try {
 			txn.abort();
 		} catch (abortErr) {
-			if (abortErr instanceof TransactionAbandonedError) throw abortErr;
+			if (abortErr instanceof TransactionAbandonedError || abortErr instanceof TransactionAbortUnresolvedError) throw abortErr;
 		}
 		throw commitErr;
 	}
@@ -3555,10 +3710,10 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	}
 };
 
-//#endregion
-//#region src/parse-transaction-log.ts
-const { TRANSACTION_LOG_TOKEN, TRANSACTION_LOG_ENTRY_HEADER_SIZE: TRANSACTION_LOG_ENTRY_HEADER_SIZE$1 } = constants;
+// src/parse-transaction-log.ts
+const { TRANSACTION_LOG_TOKEN, TRANSACTION_LOG_ENTRY_HEADER_SIZE: TRANSACTION_LOG_ENTRY_HEADER_SIZE$1, TRANSACTION_LOG_ENTRY_LAST_FLAG: TRANSACTION_LOG_ENTRY_LAST_FLAG$1, TRANSACTION_LOG_ENTRY_ABORTED_FLAG: TRANSACTION_LOG_ENTRY_ABORTED_FLAG$1 } = constants;
 const MIN_VALID_TIMESTAMP = Date.UTC(2026, 0, 27);
+const VALID_FLAGS_MASK = TRANSACTION_LOG_ENTRY_LAST_FLAG$1 | TRANSACTION_LOG_ENTRY_ABORTED_FLAG$1;
 /**
 * Loads an entire transaction log file into memory.
 * @param path - The path to the transaction log file.
@@ -3596,6 +3751,8 @@ function parseTransactionLog(path, options = {}) {
 		if (!Number.isFinite(timestamp) || timestamp < MIN_VALID_TIMESTAMP) anomalies.push(`Header timestamp ${timestamp} predates 2026-01-27 (possible corruption)`);
 		const entries = [];
 		let entryAnomalyCount = 0;
+		let previousEndedTransaction = true;
+		let previousTimestamp = NaN;
 		while (fileOffset < size) {
 			const timestamp = read(8).readDoubleBE(0);
 			if (timestamp === 0) {
@@ -3612,7 +3769,11 @@ function parseTransactionLog(path, options = {}) {
 			const data = read(length);
 			const entryAnomalies = [];
 			if (!Number.isFinite(timestamp) || timestamp < MIN_VALID_TIMESTAMP) entryAnomalies.push(`timestamp ${timestamp} predates 2026-01-27 (possible corruption)`);
-			if ((flags & -2) !== 0) entryAnomalies.push(`flags 0x${flags.toString(16).padStart(2, "0")} contains undefined bits (expected 0x00 or 0x01)`);
+			if ((flags & ~VALID_FLAGS_MASK) !== 0) entryAnomalies.push(`flags 0x${flags.toString(16).padStart(2, "0")} contains undefined bits (expected 0x00-0x03)`);
+			const startsTransaction = previousEndedTransaction || timestamp !== previousTimestamp;
+			if ((flags & TRANSACTION_LOG_ENTRY_ABORTED_FLAG$1) !== 0 && !startsTransaction) entryAnomalies.push("abort flag on an entry that does not start a transaction");
+			previousEndedTransaction = (flags & TRANSACTION_LOG_ENTRY_LAST_FLAG$1) !== 0;
+			previousTimestamp = timestamp;
 			const entry = {
 				timestamp,
 				length,
@@ -3641,11 +3802,45 @@ function parseTransactionLog(path, options = {}) {
 	}
 }
 
-//#endregion
-//#region src/transaction-log-reader.ts
+// src/transaction-log-reader.ts
 const FLOAT_TO_UINT32 = /* @__PURE__ */ new Float64Array(1);
 const UINT32_FROM_FLOAT = new Uint32Array(FLOAT_TO_UINT32.buffer);
-const { TRANSACTION_LOG_FILE_HEADER_SIZE, TRANSACTION_LOG_ENTRY_HEADER_SIZE } = constants;
+const EXACT_START_SPAN = /* @__PURE__ */ new Float64Array(3);
+const ITERATOR_TOKEN = Symbol("transactionLogIterator");
+const logEquals = TransactionLog.prototype.equals;
+var LogIterator = class {
+	#sourceLog;
+	#control;
+	next;
+	constructor(token, sourceLog, next, control) {
+		if (token !== ITERATOR_TOKEN) throw new TypeError("Transaction log iterators require query()");
+		this.#sourceLog = sourceLog;
+		this.next = next;
+		this.#control = control;
+	}
+	static cursor(value) {
+		if (typeof value === "object" && value !== null && #control in value) return value;
+	}
+	static isFrom(value, sourceLog) {
+		return logEquals.call(sourceLog, value.#sourceLog);
+	}
+	[Symbol.iterator]() {
+		return this;
+	}
+	peek() {
+		return this.#control("peek");
+	}
+	close() {
+		this.#control("close");
+	}
+	static reached(value, logId, position, atSegmentEnd) {
+		return value.#control("reached", logId, position, atSegmentEnd);
+	}
+	static scanEnd(value, logId, size) {
+		return value.#control("scanEnd", logId, size);
+	}
+};
+const { TRANSACTION_LOG_FILE_HEADER_SIZE, TRANSACTION_LOG_ENTRY_HEADER_SIZE, TRANSACTION_LOG_ENTRY_LAST_FLAG, TRANSACTION_LOG_ENTRY_ABORTED_FLAG } = constants;
 /**
 * Number of consecutive well-formed frames that, on their own, signal that real log data has
 * resumed after a framing break. Kept in step with `RESYNC_MIN_FRAMES` in
@@ -3681,6 +3876,43 @@ var CorruptFrameError = class extends RangeError {
 	}
 };
 /**
+* Thrown when an iterator advances past segments it never read and that can no longer be read —
+* typically ones retention purged while the reader lagged. The entries they held cannot be
+* recovered from this log, so a consumer replicating it must not treat the stream as contiguous.
+* Missing sequence numbers prove only that continuity is unknown, not that each held entries.
+*
+* The iterator is left positioned at the start of `resumeLogId`, so a caller that accepts the
+* discontinuity calls `next()` again to continue from there.
+*
+* Not a `RangeError`: this is not broken framing, and consumers classify those by class.
+*/
+var TransactionLogGapError = class extends Error {
+	/** Sequence number of the last segment this iterator read up to. */
+	logId;
+	/** Sequence number of the segment iteration resumes in. */
+	resumeLogId;
+	/** Segments between `logId` and `resumeLogId` that could not be read. Empty segments are not counted. */
+	unavailableLogCount;
+	constructor(logId, resumeLogId, unavailableLogCount) {
+		super(`Transaction log iterator skipped ${unavailableLogCount} unavailable segment(s) between log ${logId} and log ${resumeLogId}; entries in them were not read`);
+		this.name = "TransactionLogGapError";
+		this.logId = logId;
+		this.resumeLogId = resumeLogId;
+		this.unavailableLogCount = unavailableLogCount;
+	}
+};
+/** Readable input ended before the iterator's physical `until` bound. Retry after input is available. */
+var TransactionLogUntilUnreachedError = class extends Error {
+	logId;
+	position;
+	constructor(logId, position) {
+		super(`Transaction log reader stopped at position ${position.toString(16)} of log ${logId}, short of the iterator it reads until`);
+		this.name = "TransactionLogUntilUnreachedError";
+		this.logId = logId;
+		this.position = position;
+	}
+};
+/**
 * Whether a complete, in-bounds frame begins at `pos`. The only sane bound on an entry's length is
 * the written extent: a single entry can legitimately exceed the rotation threshold (the first
 * entry written to a fresh file is always written in full). A zero timestamp is the
@@ -3742,7 +3974,9 @@ function corruptFrame(message, transactionLog, dataView, logBuffer, position, li
 * exactly matches the start timestamp, and then return all subsequent transactions in the log
 * regardless of whether their timestamp is before or after the start
 */
-Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, exactStart, startFromLastFlushed, readUncommitted, exclusiveStart } = {}) {
+Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, exactStart, startFromLastFlushed, readUncommitted, exclusiveStart, until } = {}) {
+	let untilCursor = LogIterator.cursor(until);
+	if (until !== void 0 && (!untilCursor || !LogIterator.isFrom(untilCursor, this))) throw new TypeError("until must be an iterator from query() on the same transaction log");
 	if (!this._lastCommittedPosition) {
 		const lastCommittedPosition = this._getLastCommittedPosition();
 		this._lastCommittedPosition = new Float64Array(lastCommittedPosition.buffer);
@@ -3756,6 +3990,14 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 	let dataView;
 	let logBuffer = this._currentLogBuffer?.deref();
 	let foundExactStart = false;
+	let stopLogId = 0;
+	let stopPosition = 0;
+	let tailLogId = 0;
+	let tailPosition = 0;
+	let segmentRemovals = 0;
+	let previousEndedTransaction = true;
+	let previousTimestamp = NaN;
+	let skippingAborted = false;
 	if (start === void 0 && !startFromLastFlushed) {
 		position = size;
 		if (position === 0) position = TRANSACTION_LOG_FILE_HEADER_SIZE;
@@ -3765,127 +4007,304 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 			FLOAT_TO_UINT32[0] = this._getLastFlushed();
 			if (FLOAT_TO_UINT32[0] === 0) FLOAT_TO_UINT32[0] = this._findPosition(0);
 			start ??= 0;
+		} else if (exactStart) {
+			const startPosition = this._findExactStart(start, EXACT_START_SPAN);
+			FLOAT_TO_UINT32[0] = EXACT_START_SPAN[0];
+			stopLogId = UINT32_FROM_FLOAT[1];
+			stopPosition = UINT32_FROM_FLOAT[0];
+			FLOAT_TO_UINT32[0] = EXACT_START_SPAN[1];
+			tailLogId = UINT32_FROM_FLOAT[1];
+			tailPosition = UINT32_FROM_FLOAT[0];
+			segmentRemovals = EXACT_START_SPAN[2];
+			FLOAT_TO_UINT32[0] = startPosition;
 		} else FLOAT_TO_UINT32[0] = this._findPosition(start);
 		logId = UINT32_FROM_FLOAT[1];
 		position = UINT32_FROM_FLOAT[0];
 		if (position === 0) position = TRANSACTION_LOG_FILE_HEADER_SIZE;
 	}
+	const positionedAt = position;
+	if (stopLogId !== 0 && pastStop(logId, position, stopLogId, stopPosition) && mayJumpTo(untilCursor, tailLogId, tailPosition)) {
+		stopLogId = 0;
+		if (skipToTail(this, logId, position, tailLogId, tailPosition, segmentRemovals)) {
+			logId = tailLogId;
+			position = tailPosition;
+			logBuffer = tailLogBuffer ?? logBuffer;
+		}
+		tailLogBuffer = void 0;
+	}
+	let gapFloor = logId;
+	let startUnmapped = false;
+	let startMissing = false;
 	if (logBuffer === void 0 || logBuffer.logId !== logId) {
 		logBuffer = getLogMemoryMap(this, logId);
 		if (logBuffer && latestLogId === logId && !readUncommitted && this._currentLogBuffer?.deref() !== logBuffer) this._currentLogBuffer = new WeakRef(logBuffer);
 		if (logBuffer === void 0) {
 			logBuffer = Buffer.alloc(0);
-			logBuffer.logId = 0;
+			logBuffer.logId = logId;
 			logBuffer.size = 0;
 			logBuffer.dataView = new DataView(logBuffer.buffer);
 			size = 0;
+			startUnmapped = logId > 0;
+			if (positionedAt <= TRANSACTION_LOG_FILE_HEADER_SIZE || logId > 0 && this.getLogFileSize(logId) > 0) gapFloor = logId - 1;
 		}
 	}
 	dataView = logBuffer.dataView;
 	if (latestLogId < logId) size = 0;
-	else if (latestLogId > logId) {
+	else if (latestLogId > logId && !startUnmapped) {
 		const cachedSize = logBuffer.size;
 		if (cachedSize === void 0) size = logBuffer.size = readableExtent(logBuffer);
 		else size = cachedSize;
 	}
-	return {
-		[Symbol.iterator]() {
-			return this;
-		},
-		next() {
-			let timestamp;
-			if (position >= size) {
-				const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
-				size = latestLogId < logBuffer.logId ? 0 : latestSize;
-				if (latestLogId > logBuffer.logId) {
-					size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
-					if (position >= size) {
-						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
-						if (nextLogBuffer) {
-							dataView = nextLogBuffer.dataView;
-							logBuffer = nextLogBuffer;
-							if (latestLogId > logBuffer.logId) size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
-							else size = latestSize;
-							position = TRANSACTION_LOG_FILE_HEADER_SIZE;
+	let peeked;
+	let peekedLogId = 0;
+	let peekedPosition = 0;
+	let closed = false;
+	let needsCursorCheck = untilCursor !== void 0 || startUnmapped;
+	const iterator = new LogIterator(ITERATOR_TOKEN, transactionLog, function next() {
+		let scanEnd = size;
+		if (needsCursorCheck) {
+			if (peeked) {
+				const result = peeked;
+				if (!closed) {
+					peeked = void 0;
+					needsCursorCheck = untilCursor !== void 0;
+				}
+				return result;
+			}
+			if (untilCursor) {
+				const limit = LogIterator.scanEnd(untilCursor, logBuffer.logId, size);
+				if (limit === void 0) {
+					untilCursor = void 0;
+					needsCursorCheck = startUnmapped;
+				} else {
+					if (position >= limit && LogIterator.reached(untilCursor, logBuffer.logId, position, position >= size && logBuffer.length > 0 && position >= readableExtent(logBuffer))) return {
+						done: true,
+						value: void 0
+					};
+					scanEnd = limit;
+				}
+			}
+			if (startUnmapped) {
+				const mapped = getLogMemoryMap(transactionLog, logBuffer.logId);
+				if (mapped) {
+					logBuffer = mapped;
+					dataView = mapped.dataView;
+				} else {
+					const latestLogId = loadLastPosition(transactionLog, !!readUncommitted).logId;
+					const fileSize = transactionLog.getLogFileSize(logBuffer.logId);
+					if (logBuffer.logId >= latestLogId || fileSize > position) return endOfReadable(untilCursor, logBuffer, position);
+					if (fileSize === 0) startMissing = true;
+				}
+				startUnmapped = false;
+				needsCursorCheck = untilCursor !== void 0;
+				size = 0;
+			}
+		}
+		let timestamp;
+		if (position >= size) {
+			const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
+			size = latestLogId < logBuffer.logId ? 0 : latestSize;
+			if (latestLogId > logBuffer.logId) {
+				size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
+				if (position >= size) {
+					if (untilCursor && LogIterator.reached(untilCursor, logBuffer.logId, position, logBuffer.length > 0 && position >= readableExtent(logBuffer))) return {
+						done: true,
+						value: void 0
+					};
+					const fromLogId = logBuffer.logId - (startMissing ? 1 : 0);
+					const nextLogBuffer = nextReadableLogBuffer(transactionLog, fromLogId, latestLogId, gapFloor);
+					if (nextLogBuffer) {
+						startMissing = false;
+						const unavailable = unavailableLogCount;
+						dataView = nextLogBuffer.dataView;
+						logBuffer = nextLogBuffer;
+						if (latestLogId > logBuffer.logId) size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
+						else size = latestSize;
+						position = TRANSACTION_LOG_FILE_HEADER_SIZE;
+						previousEndedTransaction = true;
+						if (unavailable > 0) throw new TransactionLogGapError(Math.max(fromLogId, gapFloor), logBuffer.logId, unavailable);
+					}
+				}
+			}
+			scanEnd = untilCursor ? LogIterator.scanEnd(untilCursor, logBuffer.logId, size) ?? size : size;
+		}
+		if (position >= scanEnd) return endOfReadable(untilCursor, logBuffer, position);
+		let jumpRefused = false;
+		let limit = Math.min(size, logBuffer.length);
+		do {
+			try {
+				timestamp = dataView.getFloat64(position);
+			} catch (error) {
+				error.message += ` at position ${position.toString(16)} of log ${logBuffer.logId} (size=${size}, log buffer length=${logBuffer.length})`;
+				throw error;
+			}
+			if (!timestamp) return endOfReadable(untilCursor, logBuffer, position);
+			if (position + TRANSACTION_LOG_ENTRY_HEADER_SIZE > limit) {
+				const broken = corruptFrame(`Corrupt transaction log: truncated entry header at position ${position.toString(16)} of log ${logBuffer.logId} (available=${limit - position})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
+				position = broken.nextPosition;
+				previousEndedTransaction = true;
+				throw broken.error;
+			}
+			const length = dataView.getUint32(position + 8);
+			if (length === 0 || position + TRANSACTION_LOG_ENTRY_HEADER_SIZE + length > limit) {
+				const broken = corruptFrame(length === 0 ? `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: zero-length entry` : `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: declared length ${length} overruns the log (limit=${limit})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
+				position = broken.nextPosition;
+				previousEndedTransaction = true;
+				throw broken.error;
+			}
+			position += TRANSACTION_LOG_ENTRY_HEADER_SIZE;
+			const flags = logBuffer[position - 1];
+			const aborted = (flags & TRANSACTION_LOG_ENTRY_ABORTED_FLAG) !== 0;
+			if (previousEndedTransaction || timestamp !== previousTimestamp || aborted) skippingAborted = aborted;
+			previousEndedTransaction = (flags & TRANSACTION_LOG_ENTRY_LAST_FLAG) !== 0;
+			previousTimestamp = timestamp;
+			let matchesRange;
+			if (skippingAborted) matchesRange = false;
+			else if (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
+			else if (exactStart) {
+				matchesRange = false;
+				if (timestamp === start) {
+					matchesRange = !exclusiveStart;
+					foundExactStart = true;
+					stopLogId = 0;
+				}
+			} else matchesRange = (exclusiveStart ? timestamp > start : timestamp >= start) && timestamp < end;
+			if (!matchesRange && stopLogId !== 0 && !jumpRefused && pastStop(logBuffer.logId, position + length, stopLogId, stopPosition)) {
+				if (mayJumpTo(untilCursor, tailLogId, tailPosition)) {
+					stopLogId = 0;
+					position += length;
+					if (skipToTail(transactionLog, logBuffer.logId, position, tailLogId, tailPosition, segmentRemovals)) {
+						if (tailLogBuffer) {
+							logBuffer = tailLogBuffer;
+							dataView = tailLogBuffer.dataView;
 						}
+						position = tailPosition;
+						previousEndedTransaction = true;
+						size = 0;
 					}
+					tailLogBuffer = void 0;
+					return iterator.next();
 				}
+				jumpRefused = true;
 			}
-			while (position < size) {
-				try {
-					timestamp = dataView.getFloat64(position);
-				} catch (error) {
-					error.message += ` at position ${position.toString(16)} of log ${logBuffer.logId} (size=${size}, log buffer length=${logBuffer.length})`;
-					throw error;
+			const entryStart = position;
+			position += length;
+			if (matchesRange) return {
+				done: false,
+				value: {
+					timestamp,
+					endTxn: previousEndedTransaction,
+					data: logBuffer.subarray(entryStart, position)
 				}
-				if (!timestamp) return {
+			};
+			if (position >= scanEnd) {
+				if (untilCursor && LogIterator.reached(untilCursor, logBuffer.logId, position)) return {
 					done: true,
 					value: void 0
 				};
-				const limit = readUncommitted ? logBuffer.length : Math.min(size, logBuffer.length);
-				if (position + TRANSACTION_LOG_ENTRY_HEADER_SIZE > limit) {
-					const broken = corruptFrame(`Corrupt transaction log: truncated entry header at position ${position.toString(16)} of log ${logBuffer.logId} (available=${limit - position})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
-					position = broken.nextPosition;
-					throw broken.error;
-				}
-				const length = dataView.getUint32(position + 8);
-				if (length === 0 || position + TRANSACTION_LOG_ENTRY_HEADER_SIZE + length > limit) {
-					const broken = corruptFrame(length === 0 ? `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: zero-length entry` : `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: declared length ${length} overruns the log (limit=${limit})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
-					position = broken.nextPosition;
-					throw broken.error;
-				}
-				position += TRANSACTION_LOG_ENTRY_HEADER_SIZE;
-				let matchesRange;
-				if (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
-				else if (exactStart) {
-					if (timestamp === start) {
-						matchesRange = !exclusiveStart;
-						foundExactStart = true;
-					} else matchesRange = false;
-				} else matchesRange = (exclusiveStart ? timestamp > start : timestamp >= start) && timestamp < end;
-				const entryStart = position;
-				position += length;
-				if (matchesRange) return {
-					done: false,
-					value: {
-						timestamp,
-						endTxn: Boolean(logBuffer[entryStart - 1] & 1),
-						data: logBuffer.subarray(entryStart, position)
+				const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
+				size = latestLogId < logBuffer.logId ? 0 : latestSize;
+				if (latestLogId > logBuffer.logId) {
+					size = logBuffer.size ?? readableExtent(logBuffer);
+					if (!readUncommitted) logBuffer.size = size;
+					if (position < size) {
+						scanEnd = untilCursor ? LogIterator.scanEnd(untilCursor, logBuffer.logId, size) ?? size : size;
+						limit = Math.min(size, logBuffer.length);
+						continue;
 					}
-				};
-				if (position >= size) {
-					const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
-					size = latestLogId < logBuffer.logId ? 0 : latestSize;
-					if (latestLogId > logBuffer.logId) {
-						size = logBuffer.size ?? readableExtent(logBuffer);
-						if (!readUncommitted) logBuffer.size = size;
-						if (position < size) continue;
-						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
-						if (!nextLogBuffer) return {
-							done: true,
-							value: void 0
-						};
-						logBuffer = nextLogBuffer;
-						dataView = logBuffer.dataView;
-						if (latestLogId === logBuffer.logId) size = latestSize;
-						else {
-							const cachedSize = logBuffer.size;
-							if (cachedSize === void 0) {
-								size = readableExtent(logBuffer);
-								if (!readUncommitted) logBuffer.size = size;
-							} else size = cachedSize;
-						}
-						position = TRANSACTION_LOG_FILE_HEADER_SIZE;
+					if (untilCursor && LogIterator.reached(untilCursor, logBuffer.logId, position, logBuffer.length > 0 && position >= readableExtent(logBuffer))) return {
+						done: true,
+						value: void 0
+					};
+					const fromLogId = logBuffer.logId;
+					const nextLogBuffer = nextReadableLogBuffer(transactionLog, fromLogId, latestLogId, gapFloor);
+					if (!nextLogBuffer) return endOfReadable(untilCursor, logBuffer, position);
+					const unavailable = unavailableLogCount;
+					logBuffer = nextLogBuffer;
+					dataView = logBuffer.dataView;
+					if (latestLogId === logBuffer.logId) size = latestSize;
+					else {
+						const cachedSize = logBuffer.size;
+						if (cachedSize === void 0) {
+							size = readableExtent(logBuffer);
+							if (!readUncommitted) logBuffer.size = size;
+						} else size = cachedSize;
 					}
+					position = TRANSACTION_LOG_FILE_HEADER_SIZE;
+					previousEndedTransaction = true;
+					if (unavailable > 0) throw new TransactionLogGapError(Math.max(fromLogId, gapFloor), logBuffer.logId, unavailable);
 				}
+				scanEnd = untilCursor ? LogIterator.scanEnd(untilCursor, logBuffer.logId, size) ?? size : size;
+				limit = Math.min(size, logBuffer.length);
+			}
+		} while (position < scanEnd);
+		return endOfReadable(untilCursor, logBuffer, position);
+	}, function control(operation, fromLogId, fromPosition, atSegmentEnd) {
+		if (operation === "peek") {
+			if (peeked) return peeked;
+			const result = iterator.next();
+			if (!result.done) {
+				peeked = result;
+				needsCursorCheck = true;
+				peekedLogId = logBuffer.logId;
+				peekedPosition = position - result.value.data.length - TRANSACTION_LOG_ENTRY_HEADER_SIZE;
 			}
-			return {
+			return result;
+		}
+		if (operation === "close") {
+			closed = true;
+			needsCursorCheck = true;
+			peeked = {
 				done: true,
 				value: void 0
 			};
+			logBuffer = void 0;
+			dataView = void 0;
+			untilCursor = void 0;
+			return;
 		}
-	};
+		if (closed) return;
+		const boundLogId = peeked ? peekedLogId : logBuffer.logId;
+		const boundPosition = peeked ? peekedPosition : position;
+		if (operation === "scanEnd") {
+			if (boundLogId !== fromLogId) return boundLogId > fromLogId ? fromPosition : 0;
+			return boundPosition < fromPosition ? boundPosition : fromPosition;
+		}
+		return pastStop(fromLogId, fromPosition, boundLogId, boundPosition) || !!atSegmentEnd && boundLogId === fromLogId + 1 && boundPosition === TRANSACTION_LOG_FILE_HEADER_SIZE;
+	});
+	return iterator;
 } });
+function endOfReadable(untilCursor, logBuffer, position) {
+	if (untilCursor && LogIterator.reached(untilCursor, logBuffer.logId, position, logBuffer.length > 0 && position >= readableExtent(logBuffer)) === false) throw new TransactionLogUntilUnreachedError(logBuffer.logId, position);
+	return {
+		done: true,
+		value: void 0
+	};
+}
+function pastStop(logId, position, stopLogId, stopPosition) {
+	return logId > stopLogId || logId === stopLogId && position >= stopPosition;
+}
+function mayJumpTo(untilCursor, logId, position) {
+	return !untilCursor || LogIterator.reached(untilCursor, logId, position - 1) !== true;
+}
+let tailLogBuffer;
+/**
+* Whether an exact-start lookup at `position` of `fromLogId` may take its one-shot jump to the tail.
+* next() calls it on a frame boundary, so a mapping error leaves a resumable cursor; from query()
+* the error escapes before any iterator exists. The removal
+* check follows the mapping and holds the store's lock, so a purge either declines the jump (the
+* scan then reports the gap) or follows it like a purge of segments already read.
+*/
+function skipToTail(transactionLog, fromLogId, position, tailLogId, tailPosition, segmentRemovals) {
+	tailLogBuffer = void 0;
+	if (tailLogId === fromLogId) return tailPosition > position;
+	if (tailLogId < fromLogId) return false;
+	const mapped = getLogMemoryMap(transactionLog, tailLogId);
+	if (mapped === void 0 || transactionLog._segmentRemovals() !== segmentRemovals) return false;
+	tailLogBuffer = mapped;
+	return true;
+}
+let unavailableLogCount = 0;
 /**
 * Maps the next readable segment after `fromLogId`, skipping a run retention has deleted —
 * stopping at the hole wedges the iterator there for every later poll (invariant 30).
@@ -3894,15 +4313,22 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 * `_findPosition(0)`, which names the bottom of the contiguous run ending at the current segment
 * and so lands *past* a survivor sitting between two holes.
 */
-function nextReadableLogBuffer(transactionLog, fromLogId, latestLogId) {
+function nextReadableLogBuffer(transactionLog, fromLogId, latestLogId, gapFloor) {
+	unavailableLogCount = 0;
 	let candidateLogId = fromLogId + 1;
 	while (candidateLogId <= latestLogId) {
 		const logBuffer = getLogMemoryMap(transactionLog, candidateLogId);
 		if (logBuffer) {
 			if (candidateLogId === latestLogId || readableExtent(logBuffer) > TRANSACTION_LOG_FILE_HEADER_SIZE) return logBuffer;
-		} else if (transactionLog.getLogFileSize(candidateLogId) > TRANSACTION_LOG_FILE_HEADER_SIZE) return;
-		candidateLogId = transactionLog._nextLogId(candidateLogId);
-		if (candidateLogId === 0) return;
+		} else {
+			const fileSize = transactionLog.getLogFileSize(candidateLogId);
+			if (fileSize > TRANSACTION_LOG_FILE_HEADER_SIZE) return;
+			if (fileSize === 0 && candidateLogId > gapFloor) unavailableLogCount++;
+		}
+		const nextLogId = transactionLog._nextLogId(candidateLogId);
+		if (nextLogId === 0) return;
+		unavailableLogCount += Math.max(0, nextLogId - 1 - Math.max(candidateLogId, gapFloor));
+		candidateLogId = nextLogId;
 	}
 }
 /**
@@ -3956,13 +4382,11 @@ function loadLastPosition(transactionLog, readUncommitted) {
 	};
 }
 
-//#endregion
-//#region src/index.ts
+// src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.12.0"
+	"rocksdb-js": "2.14.0"
 };
 
-//#endregion
-export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getRegistryStatus, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, steadyClockNow, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
+export { BackgroundError, ConflictKind, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionAbortUnresolvedError, TransactionLog, TransactionLogGapError, TransactionLogUntilUnreachedError, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getRegistryStatus, getWriteBufferManagerStats, parseTransactionLog, raiseTimestampFloor, registryStatus, shutdown, stats, steadyClockNow, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map