@harperfast/rocksdb-js 2.11.0 → 2.13.0

package/dist/index.mjs

@@ -8,11 +8,10 @@ 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);
 /**
@@ -147,7 +146,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
@@ -185,12 +184,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 +250,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 +290,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). */
@@ -525,6 +540,14 @@ const backups = {
 	* Verifies a backup's file sizes, and optionally their checksums (which
 	* requires reading all backed-up data).
 	*
+	* Set `verifyTables: true` to also prove this build can read the backup
+	* before restoring it: every table file is opened, one at a time, and its
+	* footer (including `format_version`) and properties must be readable, and
+	* every compression algorithm it records must be supported by this build.
+	* A checksum-valid table written by a newer or differently built RocksDB
+	* otherwise passes and fails on the first read after a restore. Blob files
+	* are not checked.
+	*
 	* When the backup was created with `transactionLogs: true`, the backup's
 	* transaction log snapshot (`<backupDir>/transaction_logs/<backupId>/`) is
 	* also validated — every log file's header and entry framing must be intact
@@ -532,7 +555,9 @@ const backups = {
 	* is a verification failure). Set `verifyTransactionLogs: false` to skip.
 	*/
 	async verify(backupDir, backupId, options) {
-		await new Promise((resolve, reject) => nativeBackupVerify(resolve, reject, backupDir, backupId, options?.verifyWithChecksum ?? false));
+		const verifyTables = options?.verifyTables;
+		if (verifyTables !== void 0 && typeof verifyTables !== "boolean") throw new TypeError(`verifyTables must be a boolean, received ${verifyTables === null ? "null" : typeof verifyTables}`);
+		await new Promise((resolve, reject) => nativeBackupVerify(resolve, reject, backupDir, backupId, options?.verifyWithChecksum ?? false, verifyTables === true));
 		if (options?.verifyTransactionLogs === false) return;
 		const logsDir = join(backupDir, TRANSACTION_LOGS_DIRNAME, String(backupId));
 		if (!await exists(logsDir)) return;
@@ -549,8 +574,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.
@@ -693,8 +717,7 @@ var CountEstimator = class {
 	}
 };
 
-//#endregion
-//#region src/util.ts
+// src/util.ts
 /**
 * Parses a duration string into milliseconds.
 *
@@ -765,8 +788,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`.
@@ -1051,8 +1073,7 @@ var DBI = class DBI {
 	}
 };
 
-//#endregion
-//#region src/tar.ts
+// src/tar.ts
 /**
 * A minimal, dependency-free streaming USTAR (POSIX tar) encoder.
 *
@@ -1258,8 +1279,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;
 /**
@@ -1303,9 +1323,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
@@ -1325,10 +1358,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]() {
@@ -1336,7 +1371,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;
@@ -1344,11 +1379,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 = {};
@@ -1369,20 +1408,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.
 *
@@ -1449,8 +1491,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);
@@ -1751,6 +1792,10 @@ var Store = class {
 	*/
 	writeBufferSize;
 	/**
+	* The memtable arena block size in bytes; `0` or unset is automatic.
+	*/
+	arenaBlockSize;
+	/**
 	* The function used to encode keys using the shared `keyBuffer`.
 	*/
 	writeKey;
@@ -1803,6 +1848,7 @@ var Store = class {
 		this.timestampFloorLog = options?.timestampFloorLog;
 		this.verificationTable = options?.verificationTable;
 		this.writeBufferSize = options?.writeBufferSize;
+		this.arenaBlockSize = options?.arenaBlockSize;
 		this.writeKey = writeKey;
 		this.#columnFamilyOptions = options ? { ...options } : void 0;
 	}
@@ -2053,7 +2099,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));
@@ -2167,7 +2215,8 @@ var Store = class {
 			transactionLogsPath: this.transactionLogsPath,
 			timestampFloorLog: this.timestampFloorLog,
 			verificationTable: this.verificationTable,
-			writeBufferSize: this.writeBufferSize
+			writeBufferSize: this.writeBufferSize,
+			arenaBlockSize: this.arenaBlockSize
 		});
 		this.identityPath = this.db.identityPath;
 		return false;
@@ -2273,8 +2322,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
@@ -2298,10 +2346,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;
 	}
 };
@@ -2331,6 +2387,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 {
@@ -2345,9 +2433,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);
@@ -2373,6 +2462,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;
 		}
 	}
@@ -2441,6 +2531,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() {
@@ -2461,8 +2573,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",
@@ -2872,6 +2984,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
@@ -3340,7 +3465,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++) {
@@ -3354,7 +3482,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;
 			}
@@ -3386,10 +3514,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);
@@ -3405,7 +3536,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;
@@ -3430,7 +3561,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;
 	}
@@ -3545,10 +3676,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.
@@ -3586,6 +3717,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) {
@@ -3602,7 +3735,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,
@@ -3631,11 +3768,11 @@ 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 { 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
@@ -3671,6 +3808,32 @@ 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;
+	}
+};
+/**
 * 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
@@ -3746,6 +3909,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;
@@ -3755,11 +3926,32 @@ 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)) {
+		stopLogId = 0;
+		if (skipToTail(this, logId, position, tailLogId, tailPosition, segmentRemovals)) {
+			logId = tailLogId;
+			position = tailPosition;
+			logBuffer = tailLogBuffer ?? logBuffer;
+		}
+		tailLogBuffer = void 0;
+	}
+	let gapFloor = logId;
 	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);
@@ -3769,6 +3961,7 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 			logBuffer.size = 0;
 			logBuffer.dataView = new DataView(logBuffer.buffer);
 			size = 0;
+			if (positionedAt <= TRANSACTION_LOG_FILE_HEADER_SIZE || logId > 0 && this.getLogFileSize(logId) > 0) gapFloor = logId - 1;
 		}
 	}
 	dataView = logBuffer.dataView;
@@ -3778,7 +3971,7 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 		if (cachedSize === void 0) size = logBuffer.size = readableExtent(logBuffer);
 		else size = cachedSize;
 	}
-	return {
+	const iterator = {
 		[Symbol.iterator]() {
 			return this;
 		},
@@ -3790,13 +3983,17 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 				if (latestLogId > logBuffer.logId) {
 					size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
 					if (position >= size) {
-						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
+						const fromLogId = logBuffer.logId;
+						const nextLogBuffer = nextReadableLogBuffer(transactionLog, fromLogId, latestLogId, gapFloor);
 						if (nextLogBuffer) {
+							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);
 						}
 					}
 				}
@@ -3816,30 +4013,55 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 				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 (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
+				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;
-					} else matchesRange = false;
+						stopLogId = 0;
+					}
 				} else matchesRange = (exclusiveStart ? timestamp > start : timestamp >= start) && timestamp < end;
+				if (!matchesRange && stopLogId !== 0 && pastStop(logBuffer.logId, position + length, stopLogId, stopPosition)) {
+					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();
+				}
 				const entryStart = position;
 				position += length;
 				if (matchesRange) return {
 					done: false,
 					value: {
 						timestamp,
-						endTxn: Boolean(logBuffer[entryStart - 1] & 1),
+						endTxn: previousEndedTransaction,
 						data: logBuffer.subarray(entryStart, position)
 					}
 				};
@@ -3850,11 +4072,13 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 						size = logBuffer.size ?? readableExtent(logBuffer);
 						if (!readUncommitted) logBuffer.size = size;
 						if (position < size) continue;
-						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
+						const fromLogId = logBuffer.logId;
+						const nextLogBuffer = nextReadableLogBuffer(transactionLog, fromLogId, latestLogId, gapFloor);
 						if (!nextLogBuffer) return {
 							done: true,
 							value: void 0
 						};
+						const unavailable = unavailableLogCount;
 						logBuffer = nextLogBuffer;
 						dataView = logBuffer.dataView;
 						if (latestLogId === logBuffer.logId) size = latestSize;
@@ -3866,6 +4090,8 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 							} else size = cachedSize;
 						}
 						position = TRANSACTION_LOG_FILE_HEADER_SIZE;
+						previousEndedTransaction = true;
+						if (unavailable > 0) throw new TransactionLogGapError(Math.max(fromLogId, gapFloor), logBuffer.logId, unavailable);
 					}
 				}
 			}
@@ -3875,7 +4101,29 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 			};
 		}
 	};
+	return iterator;
 } });
+function pastStop(logId, position, stopLogId, stopPosition) {
+	return logId > stopLogId || logId === stopLogId && position >= stopPosition;
+}
+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).
@@ -3884,15 +4132,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;
 	}
 }
 /**
@@ -3946,13 +4201,11 @@ function loadLastPosition(transactionLog, readUncommitted) {
 	};
 }
 
-//#endregion
-//#region src/index.ts
+// src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.11.0"
+	"rocksdb-js": "2.13.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, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getRegistryStatus, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, steadyClockNow, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map