@harperfast/rocksdb-js 2.8.0 → 2.9.1

package/README.md

@@ -95,10 +95,20 @@ Creates a new database instance.
   - `maxWriteBufferSizeToMaintain: number` The number of bytes of recent memtable history to keep in
     memory for transaction conflict checking. `-1` (the default) derives the value from
     `maxWriteBufferNumber * writeBufferSize` (the RocksDB-recommended default for optimistic
-    transactions) — except when a stalling [`writeBufferManager`](#dbconfigoptions) is configured
-    (`writeBufferManagerSize > 0` with `writeBufferManagerAllowStall`), in which case it resolves to
-    `0` to avoid retaining memtable history the manager will never release. An explicit non-negative
-    value is always honored as-is.
+    transactions) — except when the database has a [`writeBufferManager`](#dbconfigoptions)
+    attached, in which case it resolves to `1` so the manager is not filled with history it will
+    never release. What decides this is the manager the database itself holds, not the current
+    `writeBufferManagerSize`: a column family created later on an already-open database is clamped
+    too, because its history is still charged to that manager. It also applies to any attached
+    manager, not only a stalling one — `writeBufferManagerAllowStall` can be changed at runtime
+    while this value is fixed when a column family is created, and history the budget cannot reclaim
+    is a problem either way. `1` is the smallest target a transactional database can be given: RocksDB's transaction wrappers rewrite a `0` target to
+    the derived value, so `0` requests the _largest_ history rather than none, and an explicitly
+    requested `0` is normalized to `1` for the same reason. A positive target still retains the most
+    recent flushed memtable per column family until that family's next write. An explicit positive
+    value is honored as-is; sizing it against the budget and the column-family count is then yours,
+    and a configuration whose known families already reach the budget is reported on the
+    [`'log.warn'`](#event-api) channel.
   - `name: string` The column family name. Defaults to `"default"`.
   - `noBlockCache: boolean` When `true`, disables the block cache. Block caching is enabled by
     default and the cache is shared across all database instances.
@@ -112,6 +122,40 @@ Creates a new database instance.
     [`flushSync()`](#dbflushsyncoptions-void), [`compact()`](#dbcompactoptions-promisevoid) and
     [`compactSync()`](#dbcompactsyncoptions-void) are the exception: they have nothing to do when
     there are no writes, so they succeed as no-ops rather than throwing.
+
+    A read-only open is a **point-in-time snapshot**: it never sees later writes. It is safe
+    against a quiescent database, but **unsafe against a live writer**: the open holds no reference
+    on the files it is about to read, so a concurrent compaction, blob GC, or flush in the writing
+    process can delete one mid-open and the open throws with code `ERR_CONCURRENT_COMPACTION` — the
+    database is not corrupt; the reader lost a race, and retrying can succeed. Even a successful
+    open can fail _later reads_ the same way, because files the snapshot references are opened
+    lazily while the writer keeps deleting obsolete ones. To follow a database another process is
+    actively writing, open a secondary instead (`secondaryPath` below) — that is the supported mode
+    for a live follower.
+
+  - `secondaryPath: string` Opens the database as a **secondary instance**: a read-only follower of
+    a live primary that tolerates the primary deleting files and sees new writes on each
+    [`catchUpWithPrimary()`](#dbcatchupwithprimary-promisevoid) call. This is the supported way to
+    read a database another process is actively writing. The value is the secondary instance's own
+    workspace directory (created if missing) where RocksDB keeps the secondary's private state — it
+    must be outside `path` (enforced) and exclusive to one secondary instance. Exclusivity is
+    enforced: reusing a workspace in-process for a different database is rejected at open (the same
+    database + workspace share the one follower instance), and a kernel advisory lock on
+    `<secondaryPath>/.secondary.lock` (same discipline and caveats as the
+    [backup directory lock](#backups)) excludes other processes — with the same limits: on
+    filesystems without advisory locking (`flock` unsupported — e.g. the FUSE/9p mounts behind
+    Docker Desktop bind mounts) the lock degrades to a no-op, and on network filesystems with
+    node-local `flock` (NFS `local_lock`, CIFS, 9p) it does not exclude across hosts, so workspace
+    exclusivity is the caller's job there. Implies
+    `readOnly: true` (an explicit `readOnly: false` throws), so all read-only behavior above
+    applies. Forces `maxOpenFiles: -1`: every table and blob file is opened and held for the life
+    of each version, which is what makes the primary's deletions safe — budget file descriptors
+    accordingly on large databases (an explicit `maxOpenFiles` other than `-1` is rejected). Column
+    families created by the primary after the secondary opens are invisible until the secondary
+    reopens. Note: RocksDB upstream documents secondary instances as unsupported in combination
+    with integrated BlobDB (which this library enables for values ≥ 2KB); the pinned RocksDB build
+    handles blob files in secondary mode — covered by native regression tests — but upstream does
+    not guarantee the combination.
   - `statsLevel: StatsLevel` Controls which type of statistics to skip and reduce statistic
     overhead. Defaults to `StatsLevel.ExceptDetailedTimers`.
   - `store: Store` A custom store that handles all interaction between the `RocksDatabase` or
@@ -156,7 +200,7 @@ Returns the list of column families in the RocksDB database.
 const db = RocksDatabase.open('path/to/db');
 console.log(db.columns); // ['default']
 
-const db2 = new RocksDatabase('path/to/db', { name: 'users' });
+db.use('users');
 console.log(db.columns); // ['default', 'users']
 ```
 
@@ -191,15 +235,21 @@ Sets global database settings.
   - `writeBufferManagerAllowStall: boolean` When `true`, writes are stalled once the manager's
     `buffer_size` is exceeded, providing a hard cap on memtable memory. When `false`, memtables are
     allowed to grow past the limit and flushes are simply scheduled more aggressively. Off by
-    default to favor write throughput over hard memory bounding. Defaults to `false`.
+    default to favor write throughput over hard memory bounding. Defaults to `false`. A stall here
+    is invisible to RocksDB's own stall counters and to
+    [`db.isWriteStalled()`](#dbiswritestalled-boolean) — see
+    [`getWriteBufferManagerStats()`](#getwritebuffermanagerstats-writebuffermanagerstats),
+    which also describes the watchdog that logs a sustained stall.
   - `writeBufferManagerCostToCache: boolean` When `true`, memtable memory is "charged" against the
     shared block cache so the block cache and write buffers draw from a single pool. During write
     bursts the cache shrinks to make room for memtables; once memtables flush, the cache can grow
     back into the reclaimed space. Defaults to `false`.
   - `writeBufferManagerSize: number` Total memtable memory limit (bytes) shared across every
     database opened in this process. When set, RocksDB uses a single `WriteBufferManager` so write
-    buffers are bounded process-wide rather than per database. A value of `0` disables the manager.
-    Defaults to `0`.
+    buffers are bounded process-wide rather than per database. Defaults to `0`, which means no
+    manager. Setting `0` later stops _new_ opens from attaching one, but does not detach or resize
+    the manager a database already holds — `write_buffer_manager` is fixed for the life of an open
+    database, so its memtables stay charged against that budget.
 
 ```typescript
 RocksDatabase.config({
@@ -211,6 +261,80 @@ RocksDatabase.config({
 });
 ```
 
+### `getWriteBufferManagerStats(): WriteBufferManagerStats`
+
+Reads the live state of the `WriteBufferManager`.
+
+**Process-wide, not per-database.** The manager is a singleton shared by every database opened in
+this process, `worker_threads` included, so these values describe the whole process regardless of
+where the call was made.
+
+- `enabled: boolean` Whether a manager has been created. `bufferSize`, `memoryUsage`,
+  `mutableMemoryUsage`, `stallActive`, `stallActiveMs`, `watchdogRunning` and `columnFamilies` are
+  `0`/`false` when not; `allowStall` and `costToCache` still reflect the configured setting (a
+  manager is only created once `writeBufferManagerSize` is also set), and `inventoryAvailable` is
+  `true` (there is nothing to fail to collect).
+- `bufferSize: number` The budget in bytes (`writeBufferManagerSize`, read live).
+- `memoryUsage: number` Total memtable memory in bytes charged against the manager.
+- `mutableMemoryUsage: number` The share of `memoryUsage` held by active (mutable) memtables; the
+  rest is memtables awaiting flush plus retained write history.
+- `allowStall: boolean`, `costToCache: boolean` The manager's configuration.
+- `stallActive: boolean` Whether the manager is currently stalling writes.
+- `stallActiveMs: number` How long the current stall has been active; `0` when not stalled.
+  Sampled once a second by the watchdog, so `0` for a stall's first second and whenever
+  `watchdogRunning` is `false`.
+- `watchdogRunning: boolean` Whether the stall watchdog thread is running.
+- `columnFamilies: number` Live column families across every database attached to this manager. A
+  dropped column family keeps charging the manager until its last handle closes, so it is counted
+  until then.
+- `inventoryAvailable: boolean` `false` when the inventory could not be collected because the
+  database registry or a column-family inventory was locked. The two inventory fields are then
+  empty and everything else is still live; the call never blocks on database work that may itself
+  be stalled.
+- `maxWriteBufferSizeToMaintain: Record<string, number>` Effective per-column-family retained-history
+  target (as a decimal string) to how many of those column families carry it. Effective, not
+  requested: RocksDB rewrites a requested `0` for a transaction database.
+
+`bufferSize`, `memoryUsage`, `mutableMemoryUsage`, `stallActive` and `stallActiveMs` are also in
+[`db.getStats()`](#dbgetstatsall-boolean-rocksdbstats) and `db.getStat()` under the same
+`writeBufferManager.` prefix, for scraping; `enabled`, `allowStall`, `costToCache`,
+`watchdogRunning`, and the column-family inventory are only here, because collecting them either
+walks the database registry or isn't scrape-shaped.
+
+`stallActive` is the signal that distinguishes a stalled process from an idle one.
+[`db.isWriteStalled()`](#dbiswritestalled-boolean), the [`'writeStall'` event](#event-writestall)
+and `rocksdb.stall.micros` all track RocksDB's `WriteController`, which a `WriteBufferManager`
+stall never goes through.
+
+#### The stall watchdog
+
+While a manager exists with `writeBufferManagerAllowStall`, one low-frequency thread samples the
+manager once a second. When a stall has been continuously active past
+`ROCKSDB_JS_WBM_STALL_WARN_MS` (default `5000`; `0` disables the watchdog) it writes **one** line
+to `stderr` and emits it as a process-wide `'log.warn'` event — once per stall episode, not per
+blocked writer and not per sample:
+
+```
+[rocksdb-js] WriteBufferManager write stall active for 5.0s - no write can complete until memtable
+memory drops below the budget. budget=661.2MB usage=662.2MB (100.2%) mutable=12.4MB (1.9%)
+allowStall=true costToCache=true columnFamilies=28 maxWriteBufferSizeToMaintain={268435456:28}
+```
+
+It needs its own thread because every other candidate is blocked by the very condition it reports:
+a writer is parked inside RocksDB, RocksDB's stall callbacks are `WriteController`-only, and a JS
+timer cannot fire on a thread parked in a synchronous write. The line goes to `stderr` as well as
+the event so it is not lost when nothing has registered a `'log.warn'` listener; route one and
+ignore `stderr` if you would rather have it in your own log.
+
+```typescript
+RocksDatabase.on('log.warn', (message) => logger.warn(message));
+
+const wbm = getWriteBufferManagerStats();
+if (wbm.stallActive) {
+	logger.warn(`writes stalled for ${wbm.stallActiveMs}ms: ${wbm.memoryUsage}/${wbm.bufferSize}`);
+}
+```
+
 ### `db.isOpen(): boolean`
 
 Returns `true` if the database is open, otherwise false.
@@ -260,6 +384,20 @@ There's also a static `open()` method for convenience that performs the same thi
 const db = RocksDatabase.open('path/to/db');
 ```
 
+### `db.secondaryPath: string | undefined`
+
+The secondary instance's workspace directory when the database was opened as a
+[secondary](#new-rocksdatabasepath-options) (a read-only follower of a live primary), or
+`undefined` for a regular or plain read-only open.
+
+```typescript
+const follower = RocksDatabase.open('/path/to/database', {
+	secondaryPath: '/path/to/follower-workspace',
+});
+console.log(follower.secondaryPath); // '/path/to/follower-workspace'
+console.log(follower.readOnly); // true
+```
+
 ### `db.status: 'opened' | 'closed'`
 
 Returns a string `'opened'` or `'closed'` indicating if the database is opened or closed.
@@ -268,8 +406,95 @@ Returns a string `'opened'` or `'closed'` indicating if the database is opened o
 console.log(db.status);
 ```
 
+### `db.use(name, options?): RocksDatabase`
+
+Returns a `RocksDatabase` bound to the `name` column family of this same database, opening — and
+creating, if it does not exist — the column family on first use. This is a factory (like
+[`useLog`](#dbuselogname-transactionlog)), not a stateful switch: the returned view is an
+independent instance whose own reads and writes target its column family, while sharing the same
+underlying database. Because a single RocksDB database backs every column family, a transaction,
+backup, or checkpoint still spans all of them.
+
+- `name: string` The column family name.
+- `options?: object` Options for the column family (same shape as the constructor's, minus `name`),
+  overriding the options inherited from this database. Options only take effect when the view is
+  (re)opened.
+
+`use()` is get-or-create, backed by a weak cache: `db.use('events') === db.use('events')` while the
+view is still referenced **and open**, and calling with this database's own column-family name
+returns `this`. A view that has been closed (or garbage-collected — the cache does not pin it) is
+transparently recreated on the next `use()`. Views are independent handles: closing this database
+does not close them (and vice versa); the underlying database stays open until every handle is closed
+or collected.
+
+The view's store is derived by `Store#createColumnFamilyStore(name, options)`, which builds an
+independent store of the same class with **its own codec state** — views never share a mutable
+encoder/decoder. Consequently a database configured with a _pre-constructed_ encoder/decoder instance
+cannot derive views (its `name`/`structures` would be shared and corrupt both column families); use an
+encoder factory (`{ Encoder }`) or a named `encoding` instead. A custom `Store` whose constructor
+can't be recreated from `(path, options)` (e.g. it takes injected dependencies) should override
+`createColumnFamilyStore` to build its views.
+
+```typescript
+const db = RocksDatabase.open('path/to/db');
+
+const events = db.use('events');
+await events.put('e1', payload);
+
+await db.put('k', 'v'); // default column family, unaffected
+console.log(events.get('e1')); // payload
+console.log(db.get('e1')); // undefined — different column family
+
+events.close();
+db.close();
+```
+
 ## Data Operations
 
+### `db.catchUpWithPrimary(): Promise<void>`
+
+Advances a [secondary instance](#new-rocksdatabasepath-options) to the primary's current state by
+tailing and replaying the primary's MANIFEST and WAL. A secondary does not see the primary's
+writes — flushed or not — until it catches up. Reads through the handle remain safe while the
+catch-up runs; catch-ups on the same database are serialized internally.
+
+Throws with code `ERR_NOT_SECONDARY` on a database that was not opened with `secondaryPath`.
+Column families the primary created after the secondary opened stay invisible until the secondary
+reopens; ones the primary dropped remain readable until then. Catch-up advances the **database**
+view only: transaction-log reads through a secondary serve the stores discovered at open, and a
+store the primary creates afterward becomes visible only on reopen. Whether entries appended to an
+already-open store are visible depends on where the writer is: a cross-process primary's appends
+are not (the reader's view of the file extent is fixed at open), while a writer in the _same_
+process shares the store object, so its appends are. Either way a log entry can describe data the
+database view does not have yet — the log write completes before the RocksDB commit for every
+writer, so log-leads-database is the normal direction and a consumer has to tolerate it. Serialize
+catch-up calls per database. Each async call holds a libuv worker for the whole replay, and
+concurrent calls queue on an internal per-database mutex while holding theirs, so a handful of
+overlapping catch-ups on a backlogged follower can exhaust the default four-thread pool and stall
+unrelated `fs`/`dns`/`crypto` work in the process. Await one before starting the next rather than
+firing one per timer tick.
+
+```typescript
+const primary = RocksDatabase.open('/path/to/database');
+const follower = RocksDatabase.open('/path/to/database', {
+	secondaryPath: '/path/to/follower-workspace',
+});
+
+primary.putSync('foo', 'bar');
+console.log(follower.getSync('foo')); // undefined — not caught up yet
+await follower.catchUpWithPrimary();
+console.log(follower.getSync('foo')); // 'bar'
+```
+
+### `db.catchUpWithPrimarySync(): void`
+
+Synchronous version of `catchUpWithPrimary()`. The replay runs on the JS thread, so prefer the
+async form unless the caller is already blocking.
+
+```typescript
+follower.catchUpWithPrimarySync();
+```
+
 ### `db.clear(options?): Promise<number>`
 
 Asychronously removes all data in the current database.
@@ -571,7 +796,7 @@ const range = db.getKeysCount({ start: 'a', end: 'z' }); // exact number of keys
 ### `db.getMonotonicTimestamp(): number`
 
 Returns the current timestamp as a monotonically increasing timestamp in milliseconds represented as
-a decimal number.
+a decimal number. This process-wide clock also supplies each transaction's initial timestamp.
 
 ```typescript
 const ts = db.getMonotonicTimestamp();
@@ -631,6 +856,25 @@ const blobFiles = db.getDBIntProperty('rocksdb.num-blob-files');
 const numKeys = db.getDBIntProperty('rocksdb.estimate-num-keys');
 ```
 
+### `db.isWriteStalled(): boolean`
+
+Whether RocksDB is currently applying write backpressure to this database —
+delaying (rate-limiting) or fully stopping writes. Reads the live
+`rocksdb.is-write-stopped` and `rocksdb.actual-delayed-write-rate` properties.
+
+This is the authoritative, live pull counterpart to the
+[`'writeStall'` event](#event-writestall): the event pushes per-column-family
+entries into a stall (rate-limited), while this reports the current state on
+demand and can never be stale. It is **database-wide** — the write controller is
+shared across every column family, so it answers "are writes stalled anywhere"
+rather than for one column family.
+
+```typescript
+if (db.isWriteStalled()) {
+	console.warn('writes are currently throttled or blocked');
+}
+```
+
 ### `db.getRange(options?: IteratorOptions): ExtendedIterable`
 
 Retrieves a range of keys and their values. Supports both synchronous and asynchronous iteration.
@@ -652,6 +896,23 @@ for (const { key, value } of db.getRange({ start: 'a', end: 'z' })) {
 }
 ```
 
+Pass `transaction: txn` to iterate this column family through that transaction, exactly as
+`get()` does with the same option: the iterator sees the transaction's staged writes and reads on its
+snapshot, and range bounds apply to staged keys too. `getKeys()` and `getKeysCount()` accept it as
+well. On a transaction (`txn.getRange()`) the transaction itself is the context and takes precedence
+over a `transaction` option, as it does for `txn.get()`. Such an iterator is closed when the
+transaction commits or aborts: a later `next()` throws, while `return()` stays a no-op. Opening a
+range or counting through a transaction that has already started committing throws as well.
+
+```typescript
+await db.transaction(async (txn) => {
+	await txn.put('c', 'staged');
+	for (const { key, value } of db.getRange({ start: 'a', end: 'z', transaction: txn })) {
+		console.log({ key, value }); // includes { key: "c", value: "staged" }
+	}
+});
+```
+
 ### `db.getUserSharedBuffer(key: Key, defaultBuffer: ArrayBuffer, options?)`
 
 Creates a new buffer with the contents of `defaultBuffer` that can be accessed across threads. This
@@ -848,13 +1109,14 @@ operations methods as the `RocksDatabase` instance plus:
   no further transaction operations are permitted. Calling this method multiple times has no effect.
 - `txn.commit(): Promise<void>` Asynchronously commits the transaction and closes the transaction.
 - `txn.commitSync()` Synchronously commits and closes the transaction.
-- `txn.getTimestamp(): number` Retrieves the transaction start timestamp in seconds as a decimal. It
-  defaults to the time at which the transaction was created.
+- `txn.getTimestamp(): number` Retrieves the transaction timestamp in milliseconds as a decimal. It
+  defaults to a process-wide monotonic value assigned when the transaction was created.
 - `txn.id: number` The read-only transaction ID. Transaction IDs are unique to the RocksDB database
   path, regardless the database name/column family.
-- `txn.setTimestamp(ts?: number): void` Overrides the transaction start timestamp. If called without
-  a timestamp, it will set the timestamp to the current time. The value must be in seconds with
-  higher precision in the decimal.
+- `txn.setTimestamp(ts?: number): void` Overrides the transaction timestamp in milliseconds. If
+  called without a timestamp, it claims a fresh monotonic value. It must be called before staging
+  any write or transaction-log entry, and a supplied value must be finite, positive, and below
+  `8.64e15`.
 
 #### `txn.abandonWrites(): void`
 
@@ -890,24 +1152,35 @@ Once called, no further transaction operations are permitted.
 
 #### `txn.getTimestamp(): number`
 
-Retrieves the transaction start timestamp in seconds as a decimal. It defaults to the time at which
-the transaction was created.
+Retrieves the transaction timestamp in milliseconds since the Unix epoch as a decimal. It defaults
+to a process-wide monotonic value assigned when the transaction was created. The transaction log
+uses this timestamp as the batch key; producers may also encode it into their own record format.
 
 #### `txn.id`
 
 Type: `number`
 
-The transaction ID represented as a 32-bit unsigned integer. Transaction IDs are unique to the
-RocksDB database path, regardless the database name/column family.
+The transaction ID, a positive integer no greater than `Number.MAX_SAFE_INTEGER`. Transaction IDs
+are unique to the RocksDB database path, regardless the database name/column family.
+
+#### `txn.setTimestamp(ts?: number): void`
 
-#### `txn.setTimestamp(ts: number?): void`
+Overrides the transaction timestamp in milliseconds since the Unix epoch. Replication receivers and
+crash replay can use this to adopt an origin transaction's log key. If called without a timestamp,
+it claims a fresh monotonic value.
 
-Overrides the transaction start timestamp. If called without a timestamp, it will set the timestamp
-to the current time. The value must be in seconds with higher precision in the decimal.
+The override must happen while the transaction is pending and before any database write or
+transaction-log entry is staged. A log batch that has already been written keeps its timestamp
+across a coordinated retry; reapplying that same timestamp remains idempotent while pending. A
+supplied value must be finite, positive, and below `8.64e15`.
+
+rocksdb-js does not define a record's value layout or version metadata. A producer that copies the
+transaction timestamp into record bytes is responsible for calling `setTimestamp()` before reading
+and encoding it.
 
 ```typescript
 await db.transaction(async (txn) => {
-	txn.setTimestamp(Date.now() / 1000);
+	txn.setTimestamp(Date.now());
 });
 ```
 
@@ -1055,6 +1328,38 @@ db.on('error', (err) => {
 });
 ```
 
+### Event: `'writeStall'`
+
+Emitted when a column family **enters** a RocksDB write-stall — the push signal that writes are being
+throttled or blocked (for example when `dbWriteBufferSize` is too small for the number of column
+families and RocksDB thrashes on premature flushes). Listeners receive three string arguments:
+
+- `columnFamily: string` — the column family that entered the stall (`'default'` for the primary).
+- `previousCondition: string` — `'normal' | 'delayed' | 'stopped'`.
+- `currentCondition: string` — `'delayed'` (writes rate-limited) or `'stopped'` (writes blocked until
+  a flush frees a memtable/L0 slot).
+
+The event is **rising-edge only and rate-limited** per column family. RocksDB oscillates a CF's stall
+condition many times per second during a sustained stall, so the event fires when a CF _enters_ a
+stall and then at most once per `ROCKSDB_JS_WRITE_STALL_DEBOUNCE_MS` (default 1000 ms) while it stays
+stalling — never a flood. **Recovery is not pushed**: reliably distinguishing a brief dip from a real
+recovery isn't possible without a timer, so for current state use the pull below rather than waiting
+for a `'normal'` event.
+
+For "are writes stalled right now?", call [`db.isWriteStalled()`](#dbiswritestalled-boolean) — it
+reads the live write-controller state and is authoritative. Note it is **database-wide** (the write
+controller is shared across all column families), so it answers "is anything stalling writes" while
+the event names _which_ CF; a listener attached mid-stall should consult it rather than expect a
+missed rising edge.
+
+```typescript
+db.on('writeStall', (cf, prev, cur) => {
+	console.warn(`RocksDB write stall entered on ${cf}: ${prev} -> ${cur}`);
+});
+// ...and to check the current state on demand:
+if (db.isWriteStalled()) console.warn('writes are currently throttled or blocked');
+```
+
 ## Event API
 
 `rocksdb-js` provides a EventEmitter-like API that lets you asynchronously notify events to one or
@@ -1195,8 +1500,11 @@ Column family and ticker stat values are 64-bit unsigned integers and histogram
 `StatsHistogramData` objects.
 
 The result also always includes a summarized, aggregate set of `txnlog.*` keys covering all of
-the database's transaction logs. These are present regardless of whether statistics are enabled
-and can be fetched individually with `db.getStat('txnlog.…')`. For detailed, per-log statistics —
+the database's transaction logs, and a set of `writeBufferManager.*` keys describing the
+process-wide `WriteBufferManager`
+([`getWriteBufferManagerStats()`](#getwritebuffermanagerstats-writebuffermanagerstats)
+carries the same values plus its column-family inventory). Both sets are present regardless of
+whether statistics are enabled and can be fetched individually with `db.getStat()`. For detailed, per-log statistics —
 including memory-map usage — use [`log.getStats()`](#loggetstats-transactionlogstats). All stat
 names are documented in [docs/stats.md](docs/stats.md).
 
@@ -1503,6 +1811,14 @@ holds the last-known version for that key. Because slots are addressed by a hash
 share a slot; a collision only ever causes a conservative miss (a real read), never a stale value to
 be treated as fresh.
 
+This first word is the only version the table derives on its own: it is what a read with
+`populateVersion: true` publishes and what a transaction write invalidates against. A producer whose
+record format also carries a separately assigned version elsewhere in the value must keep using the
+first word on both sides of the check — as `expectedVersion`, and as the argument to any explicit
+[`db.populateVersion()`](#dbpopulateversionkey-key-version-number-void) call, which publishes
+whatever it is given. Comparing against the other value would miss the fast path, and publishing it
+would make the slot disagree with what the next write invalidates.
+
 The freshness check works as follows:
 
 1. Pass `{ expectedVersion }` to `get()` / `getSync()`. If the slot currently records that version,
@@ -1620,9 +1936,19 @@ const names = db.listLogs();
 ### `db.purgeLogs({ includeEntryCounts: true, ...options }): { path: string; entries: number }[]`
 
 Deletes transaction log files older than the `transactionLogRetention` (defaults to 3 days).
+Ordinary retention keeps the sequence file named by `txn.state` and every newer file as the live
+store's retention floor, or the highest sequence file when there is no persisted flush position. It
+removes only an eligible contiguous prefix below that floor. An idle store can therefore retain one
+file past the cutoff until a later write rotates and flushes it; that extra file is bounded by the
+store's `transactionLogMaxSize` (except when a single transaction exceeds the target). That bound
+covers only the floor file: when the flush position lags — `txn.state` stuck at an old sequence
+because RocksDB flushing is behind — every file above the floor is retained too, which
+`transactionLogMaxSize` does not bound. `purge.retainedUnflushedFiles` reports that case. Use
+`destroy: true` only to remove the store itself.
 
 - `options: object`
-  - `before?: number` Remove all transaction log files older than the specified timestamp.
+  - `before?: number` Remove transaction log files older than the specified timestamp, subject to
+    the retention floor and contiguous-prefix rules above.
   - `destroy?: boolean` When `true`, deletes transaction log stores including all log sequence files
     on disk.
   - `includeEntryCounts?: boolean` When `true`, counts the entries in each deleted log file and
@@ -1796,7 +2122,9 @@ stats.totals.transactionsWritten; // lifetime count of transactions written
 
 The `purge.retainedUnflushedFiles` gauge is useful for diagnosing why logs are not being cleaned
 up: a file can be older than the retention period but still retained because its transactions have
-not yet been flushed to RocksDB (purging it would be unsafe for crash recovery).
+not yet been flushed to RocksDB (purging it would be unsafe for crash recovery). The retention
+floor — the sequence named by `txn.state`, or the highest sequence when there is no persisted flush
+position — is not counted as purgeable even when it is old and fully flushed.
 
 ### Transaction Log Initialization
 
@@ -2275,7 +2603,9 @@ Options for `get()`, `getSync()`, and the `getBinary*` methods.
   - `tailing: boolean` When `true`, creates a "tailing iterator" which is a special iterator that
     has a view of the complete database including newly added data and is optimized for sequential
     reads. This will return records that were inserted into the database after the creation of the
-    iterator. Defaults to `false`.
+    iterator. Defaults to `false`. A tailing iterator ignores a transaction's snapshot: through a
+    transaction it still reads the latest committed state, merged with that transaction's staged
+    writes.
 
 ### `RangeOptions`