@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/dist/resources/Table.js

@@ -41,7 +41,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVICTED = exports.INVALIDATED = void 0;
+exports.EVICTED = exports.INVALIDATED = exports.UPDATE_ATTRIBUTES_LOCK_SLOW_WAIT = exports.UPDATE_ATTRIBUTES_LOCK_TIMEOUT = void 0;
+exports.acquireUpdateAttributesLock = acquireUpdateAttributesLock;
+exports.releaseUpdateAttributesLock = releaseUpdateAttributesLock;
+exports.withUpdateAttributesLock = withUpdateAttributesLock;
 exports.ignoreAlreadyDropped = ignoreAlreadyDropped;
 exports.freezeRecord = freezeRecord;
 exports.frozenRecordView = frozenRecordView;
@@ -50,6 +53,7 @@ exports.coerceType = coerceType;
 const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
 const node_vm_1 = require("node:vm");
 const node_crypto_1 = require("node:crypto");
+const node_perf_hooks_1 = require("node:perf_hooks");
 const commonUtility_ts_1 = require("../utility/lmdb/commonUtility.js");
 const nodeIdMapping_ts_1 = require("./nodeIdMapping.js");
 const lodash_1 = __importDefault(require("lodash"));
@@ -58,6 +62,7 @@ const lmdbProcessRows_js_1 = __importDefault(require("../dataLayer/harperBridge/
 const Resource_ts_1 = require("./Resource.js");
 const when_ts_1 = require("../utility/when.js");
 const DatabaseTransaction_ts_1 = require("./DatabaseTransaction.js");
+const recordLock_ts_1 = require("./recordLock.js");
 const envMngr = __importStar(require("../utility/environment/environmentManager.js"));
 const transactionBroadcast_ts_1 = require("./transactionBroadcast.js");
 const hdbError_ts_1 = require("../utility/errors/hdbError.js");
@@ -93,7 +98,10 @@ const { validateAttribute } = lmdbProcessRows_js_1.default;
 const NULL_WITH_TIMESTAMP = new Uint8Array(9);
 NULL_WITH_TIMESTAMP[8] = 0xc0; // null
 const UNCACHEABLE_TIMESTAMP = Infinity; // we use this when dynamic content is accessed that we can't safely cache, and this prevents earlier timestamps from change the "last" modification
+const MAX_DATE_TIMESTAMP = 8.64e15;
 const RECORD_PRUNING_INTERVAL = 60000; // one minute
+const MAX_CONCURRENT_HISTORY_REMOVALS = 10;
+const MAX_CONCURRENT_LMDB_HISTORY_REMOVALS = 1000;
 // RocksDB-only: number of eviction/tombstone removals coalesced into a single transaction commit.
 // Each evict otherwise pays a full transaction commit, so batching amortizes that cost. LMDB already
 // coalesces async writes per event turn (eventTurnBatching), so it keeps the per-record path.
@@ -102,9 +110,75 @@ const EVICTION_BATCH_SIZE = 100;
 // letting an unbounded number of open transactions (and their snapshots) accumulate.
 const MAX_INFLIGHT_EVICTION_BATCHES = 4;
 const CACHEABLE_STATUS_CODES = new Set([200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501]);
+// Guardrails for `Prefer: count=exact`: once the requested page has been collected, counting the rest
+// of the match set is bounded by BOTH a row cap and a wall-clock budget, so a paginated read can't turn
+// into an unbounded scan. Exceeding either reports an unknown total (Content-Range `.../*`) rather than
+// truncating the page. These bound the count tail, not the page itself; a genuinely expensive query
+// (large filtered full-scan, in-memory sort) should still be gated by config before broad exposure.
+const MAX_EXACT_COUNT_SCAN = 1_000_000;
+const MAX_EXACT_COUNT_MS = 1_000;
+// Largest page a `Prefer: count=` request will materialize. A request whose limit exceeds this (or is
+// not a finite, non-negative integer, e.g. `limit(Infinity)`/`limit(foo)`) falls through to the normal
+// streaming path with no count, so a count request can't be coerced into buffering an unbounded page.
+const MAX_COUNT_PAGE = 10_000;
+// How often the exact-count drain yields to the macrotask queue (must be a power of two for the bit-mask
+// check). Keeps a large scan from monopolizing the event loop without adding a yield per row.
+const COUNT_YIELD_INTERVAL = 2_048;
 envMngr.initSync();
 const LMDB_PREFETCH_WRITES = envMngr.get(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_PREFETCHWRITES);
 const LOCK_TIMEOUT = 10000;
+// This bounds schema-lock acquisition; LOCK_TIMEOUT bounds in-flight record writes during a drop.
+exports.UPDATE_ATTRIBUTES_LOCK_TIMEOUT = 10000;
+const UPDATE_ATTRIBUTES_LOCK = 'update-attributes';
+// Contention is otherwise only visible once it becomes a timeout (harper#2251).
+exports.UPDATE_ATTRIBUTES_LOCK_SLOW_WAIT = 1000;
+// raw ASCII bytes are ordered-binary's encoding of the string, so this addresses the same native
+// lock as string-keyed tryLock/unlock calls
+const updateAttributesLockKey = Buffer.from(UPDATE_ATTRIBUTES_LOCK);
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+/** The wait blocks the event loop, so the locked section must stay synchronous. */
+function acquireUpdateAttributesLock(rootStore, scopeDescription, timeout = exports.UPDATE_ATTRIBUTES_LOCK_TIMEOUT) {
+    if (rootStore.tryLock(updateAttributesLockKey))
+        return;
+    const startTime = node_perf_hooks_1.performance.now();
+    let waitTime = 1;
+    while (!rootStore.tryLock(updateAttributesLockKey)) {
+        const elapsed = node_perf_hooks_1.performance.now() - startTime;
+        if (elapsed >= timeout) {
+            throw new hdbError_ts_1.UpdateAttributesLockTimeoutError(`Timed out after ${Math.round(elapsed)}ms waiting for the exclusive '${UPDATE_ATTRIBUTES_LOCK}' lock on ${scopeDescription}; the lock holder did not release it before the deadline, so this schema/attribute update cannot proceed`);
+        }
+        if (elapsed >= 2) {
+            Atomics.wait(lockWait, 0, 0, Math.min(waitTime, timeout - elapsed));
+            if (waitTime < 16)
+                waitTime *= 2;
+        }
+    }
+    const waited = node_perf_hooks_1.performance.now() - startTime;
+    // The caller cannot register its release until we return, so a throw here would leak the lock
+    // with no `finally` able to reach it.
+    if (waited >= exports.UPDATE_ATTRIBUTES_LOCK_SLOW_WAIT)
+        try {
+            logger_ts_1.logger.warn?.(`Acquired the exclusive '${UPDATE_ATTRIBUTES_LOCK}' lock on ${scopeDescription} after waiting ${Math.round(waited)}ms; this worker's event loop was blocked for that wait, and a holder that runs past ${exports.UPDATE_ATTRIBUTES_LOCK_TIMEOUT}ms fails the update outright`);
+        }
+        catch { }
+}
+function releaseUpdateAttributesLock(rootStore) {
+    rootStore.unlock(updateAttributesLockKey);
+}
+function withUpdateAttributesLock(rootStore, scopeDescription, callback) {
+    acquireUpdateAttributesLock(rootStore, scopeDescription);
+    try {
+        const result = callback();
+        if (typeof result?.then === 'function') {
+            Promise.resolve(result).catch((error) => logger_ts_1.logger.error?.(`Async update-attributes callback rejected after its lock was released (${scopeDescription})`, error));
+            throw new TypeError(`withUpdateAttributesLock callback must be synchronous (${scopeDescription}); asynchronous work may continue after the lock is released`);
+        }
+        return result;
+    }
+    finally {
+        releaseUpdateAttributesLock(rootStore);
+    }
+}
 // Tolerate a redundant column family drop. Drops are broadcast to every worker
 // thread and each holds its own handle to the same underlying family, so a
 // concurrent worker may already have dropped it; the storage engine reports
@@ -335,8 +409,24 @@ function detectCyclicEnumerable(start) {
 function chainKeyForId(id) {
     return typeof id === 'string' ? 's' + id : 'k' + (0, DatabaseTransaction_ts_1.writeKeyId)(id);
 }
+/** Normalizes a passed `context` argument as `transactional()` does; undefined means fall back to ambient. */
+function contextArgument(context) {
+    if (!context || (0, DatabaseTransaction_ts_1.isReleasedTransaction)(context))
+        return undefined;
+    const resolved = context.getContext?.() || context;
+    return resolved instanceof DatabaseTransaction_ts_1.DatabaseTransaction ? { transaction: resolved } : resolved;
+}
+/** Distinguishes bare lock options from a record target (id, URL, {id:...}). */
+function isPlainOptions(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof URLSearchParams) &&
+        value.id === undefined);
+}
 function makeTable(options) {
-    const { primaryKey, indices, tableId, tableName, primaryStore, databasePath, databaseName, auditStore, schemaDefined, dbisDB: dbisDb, sealed, splitSegments, replicate, description, hidden, cacheControl, } = options;
+    var _a;
+    const { primaryKey, indices, tableId, tableName, primaryStore, databasePath, databaseName, auditStore, schemaDefined, dbisDB: dbisDb, sealed, splitSegments, replicate, description, hidden, cacheControl, isBranch, } = options;
     let { expirationMS: expirationMs, evictionMS: evictionMs, audit, trackDeletes } = options;
     evictionMs ??= 0;
     // Eviction without explicit expiration means expiration:0. Apply at construction so
@@ -350,6 +440,7 @@ function makeTable(options) {
         properties = (0, jsonSchemaTypes_ts_1.projectAttributesToProperties)(attributes);
     const updateRecord = (0, RecordEncoder_ts_1.recordUpdater)(primaryStore, tableId, auditStore);
     let warnedNullSourcePut = false; // latched: one warn per table per worker (see _writeUpdate)
+    let warnedFutureSourceVersion = false; // likewise (see getFromSource)
     let sourceLoad; // if a source has a load function (replicator), record it here
     let hasSourceGet;
     let primaryKeyAttribute;
@@ -383,6 +474,10 @@ function makeTable(options) {
     let cleanupPriority = 0;
     let lastCleanupInterval;
     let cleanupTimer;
+    let recordExpirationInterval;
+    // a reclamation pass awaits a scheduled cleanup, which only settles from its timer
+    const pendingCleanupResolvers = new Set();
+    let disposed = false;
     // true once a table-level expiration/eviction/scanInterval has armed the periodic cleanup scan at setup
     let expirationScanScheduled = false;
     // set on the first expiring write so the unscheduled-expiration warning is evaluated at most once per table
@@ -431,10 +526,11 @@ function makeTable(options) {
     const MAX_PREFETCH_BUNDLE = 6;
     if (audit)
         addDeleteRemoval();
-    (0, storageReclamation_ts_1.onStorageReclamation)(primaryStore.path, (priority) => {
+    const reclamationHandler = (priority) => {
         if (hasSourceGet)
             return scheduleCleanup(priority);
-    });
+    };
+    (0, storageReclamation_ts_1.onStorageReclamation)(primaryStore.path, reclamationHandler);
     class Updatable extends tracked_ts_1.GenericTrackedObject {
         getUpdatedTime() {
             return RecordEncoder_ts_1.entryMap.get(this.getRecord())?.version;
@@ -533,12 +629,68 @@ function makeTable(options) {
             },
         });
     }
+    function resolveAuditHead(id, version, nodeId, refs) {
+        if (!refs?.length)
+            return { txnLogKey: version, nodeId };
+        const visited = new Set();
+        function findHead(candidateRefs) {
+            if (!candidateRefs)
+                return;
+            const pending = candidateRefs.slice().reverse();
+            while (pending.length > 0) {
+                const ref = pending.pop();
+                const identity = `${ref.nodeId ?? 0}:${ref.version}`;
+                if (visited.has(identity))
+                    continue;
+                visited.add(identity);
+                const entry = auditStore.getSync(ref.version, tableId, id, ref.nodeId);
+                if (!entry)
+                    continue;
+                if (entry.version === version && (nodeId == null || (entry.nodeId ?? 0) === nodeId))
+                    return { txnLogKey: ref.version, nodeId: ref.nodeId };
+                const previousRefs = entry.previousAdditionalAuditRefs;
+                if (previousRefs) {
+                    for (let index = previousRefs.length - 1; index >= 0; index--)
+                        pending.push(previousRefs[index]);
+                }
+            }
+        }
+        const referencedHead = findHead(refs);
+        if (referencedHead)
+            return referencedHead;
+        if (version != null) {
+            const directHead = auditStore.getSync(version, tableId, id, nodeId);
+            if (directHead?.version === version && (nodeId == null || (directHead.nodeId ?? 0) === nodeId))
+                return { txnLogKey: version, nodeId };
+        }
+        return { txnLogKey: version, nodeId };
+    }
     class TableResource extends Resource_ts_1.Resource {
         #record; // the stored/frozen record from the database and stored in the cache (should not be modified directly)
         #changes; // the changes to the record that have been made (should not be modified directly)
         #version; // version of the record
         #entry; // the entry from the database
         #savingOperation; // operation for the record is currently being saved
+        #lockHandle; // the record lock acquired by lock() — scoped or hold
+        #lockWritable; // set by #reloadLocked to let save() stage lock-writable updates
+        /**
+         * Shared guard: if this instance is lock-writable but the handle is gone (expired or
+         * released), throw 409 before staging any write. Covers update/invalidate/relocate/delete
+         * in addition to the save() path. Every lock-writable instance carries its own handle in
+         * #lockHandle (scoped and hold alike), so we never need to search the registry here.
+         */
+        #assertLiveHandle(id) {
+            if (!this.#lockWritable)
+                return;
+            const handle = this.#lockHandle;
+            // Off-key writes through the same resource instance are ordinary; only guard the
+            // exact key the lock was acquired for.
+            if (handle.keyId !== (0, DatabaseTransaction_ts_1.writeKeyId)(id))
+                return;
+            if (handle.expired || handle.released) {
+                throw (0, recordLock_ts_1.lockNotHeldError)(handle);
+            }
+        }
         // #section: static-config
         static name = tableName; // for display/debugging purposes
         static primaryStore = primaryStore;
@@ -635,7 +787,7 @@ function makeTable(options) {
                 // perform the write of an individual write event
                 const writeUpdate = async (event, context) => {
                     const value = event.value;
-                    const Table = event.table ? databases_ts_1.databases[databaseName][event.table] : TableResource;
+                    const Table = event.table ? databases_ts_1.databases[databaseName][event.table] : _a;
                     if (databaseName === hdbTerms_ts_1.SYSTEM_SCHEMA_NAME &&
                         (event.table === hdbTerms_ts_1.SYSTEM_TABLE_NAMES.ROLE_TABLE_NAME || event.table === hdbTerms_ts_1.SYSTEM_TABLE_NAMES.USER_TABLE_NAME)) {
                         userRoleUpdate = true;
@@ -652,6 +804,9 @@ function makeTable(options) {
                         ensureLoaded: false,
                         nodeId: event.nodeId,
                         viaNodeId: event.viaNodeId,
+                        // the origin's record version, stored as-is so every replica holds the version the
+                        // origin holds; the transaction's own timestamp stays the origin's log key
+                        version: event.version,
                         // use per-event expiresAt: batched txn context only holds the first event's expiration
                         expiresAt: event.expiresAt,
                         // bulk base-copy snapshot frame: apply current-state directly, without an audit/transaction-log
@@ -690,7 +845,7 @@ function makeTable(options) {
                 const stageWrite = (event, context) => {
                     let chainKey;
                     try {
-                        const Table = event.table ? databases_ts_1.databases[databaseName][event.table] : TableResource;
+                        const Table = event.table ? databases_ts_1.databases[databaseName][event.table] : _a;
                         const id = event.id ?? (event.value ? event.value[Table?.primaryKey] : undefined);
                         if (id != null && typeof id !== 'symbol')
                             chainKey = `${event.table ?? tableName} ${chainKeyForId(id)}`;
@@ -890,7 +1045,9 @@ function makeTable(options) {
                                         continue;
                                     }
                                 }
-                                // use the version as the transaction timestamp
+                                // A source that reports no log position of its own (no `timestamp`) has only one clock,
+                                // so its record version doubles as the apply transaction's timestamp. A replication
+                                // receiver always sets `timestamp` from the origin's log key and never reaches this.
                                 if (!event.timestamp && event.version)
                                     event.timestamp = event.version;
                                 const commitResolution = (0, transaction_ts_1.transaction)(event, () => {
@@ -991,7 +1148,7 @@ function makeTable(options) {
         /** Indicates if the events should be revalidated when they are received. By default we do this if the get
          * method is overriden */
         static get shouldRevalidateEvents() {
-            return this.prototype.get !== TableResource.prototype.get;
+            return this.prototype.get !== _a.prototype.get;
         }
         /**
          * Gets a resource instance, as defined by the Resource class, adding the table-specific handling
@@ -1027,7 +1184,7 @@ function makeTable(options) {
                 }
                 return loadLocalRecord(id, request, { transaction: readTxn, ensureLoaded: resourceOptions?.ensureLoaded }, sync, (entry) => {
                     if (entry) {
-                        TableResource._updateResource(this, entry);
+                        _a._updateResource(this, entry);
                     }
                     else
                         this.#record = null;
@@ -1045,7 +1202,7 @@ function makeTable(options) {
                         if (loadingFromSource) {
                             txn?.disregardReadTxn(); // this could take some time, so don't keep the transaction open if possible
                             return (0, when_ts_1.when)(loadingFromSource, (entry) => {
-                                TableResource._updateResource(this, entry);
+                                _a._updateResource(this, entry);
                                 return this;
                             });
                         }
@@ -1265,7 +1422,7 @@ function makeTable(options) {
             return dbisDb.getSync([Symbol.for('residency_by_id'), id]);
         }
         static setResidency(getResidency) {
-            TableResource.getResidency =
+            _a.getResidency =
                 getResidency &&
                     ((record, context) => {
                         try {
@@ -1278,7 +1435,7 @@ function makeTable(options) {
                     });
         }
         static setResidencyById(getResidencyById) {
-            TableResource.getResidencyById =
+            _a.getResidencyById =
                 getResidencyById &&
                     ((id) => {
                         try {
@@ -1291,8 +1448,8 @@ function makeTable(options) {
                     });
         }
         static getResidency(record, context) {
-            if (TableResource.getResidencyById) {
-                return TableResource.getResidencyById(record[primaryKey]);
+            if (_a.getResidencyById) {
+                return _a.getResidencyById(record[primaryKey]);
             }
             let count = replicateToCount;
             if (context.replicateTo != undefined) {
@@ -1334,7 +1491,7 @@ function makeTable(options) {
                 return; // already enabled
             audit = true;
             addDeleteRemoval();
-            TableResource.audit = true;
+            _a.audit = true;
         }
         /**
          * Coerce the id as a string to the correct type for the primary key
@@ -1346,7 +1503,24 @@ function makeTable(options) {
                 return null;
             return coerceType(id, primaryKeyAttribute);
         }
+        /**
+         * A branch's Table classes deliberately carry the BASE's logical database name so an
+         * application's schema and code resolve unchanged (harper#643). That makes every schema
+         * mutation resolve against the global catalog — a `dropTable()` through a branch would delete
+         * the live base table. Reads and writes are per-branch and unaffected; DDL is refused until a
+         * branch owns a schema identity of its own.
+         */
+        static assertSchemaMutable(operation) {
+            if (!isBranch)
+                return;
+            const error = new Error(`Cannot ${operation} through a branched database: '${tableName}' resolves to the schema of base ` +
+                `database '${databaseName}', so the change would apply to the base rather than the branch`);
+            error.statusCode = 400;
+            throw error;
+        }
         static async dropTable() {
+            _a.assertSchemaMutable('drop a table');
+            const rootStore = primaryStore.rootStore;
             if (databaseName === databasePath) {
                 // Persist a drop tombstone on the primary catalog entry BEFORE any
                 // destructive work. If the process dies or a column family drop fails
@@ -1354,9 +1528,11 @@ function makeTable(options) {
                 // the next startup (or a same-name create) completes the drop via
                 // completeInterruptedDrop in databases.ts instead of resurrecting
                 // the table.
-                const primaryCatalogKey = TableResource.tableName + '/';
-                const primaryMeta = dbisDb.getSync(primaryCatalogKey);
-                if (primaryMeta && !primaryMeta.dropping) {
+                const primaryCatalogKey = _a.tableName + '/';
+                const writeTombstone = () => {
+                    const primaryMeta = dbisDb.getSync(primaryCatalogKey);
+                    if (!primaryMeta || primaryMeta.dropping)
+                        return;
                     primaryMeta.dropping = true;
                     // Stamps this drop's identity so the interrupted-drop retry budget in
                     // databases.ts can be scoped to THIS drop rather than the table name: a
@@ -1366,11 +1542,23 @@ function makeTable(options) {
                     // the budget by generation instead makes the new drop's tombstone carry
                     // its own fresh key regardless of what any worker last observed.
                     primaryMeta.dropGeneration = (0, node_crypto_1.randomUUID)();
-                    // put is rebound to putSync on RocksDB stores; on LMDB it returns
-                    // a promise, so await it to make the tombstone durable before the
-                    // destructive work below
-                    const tombstoneWrite = dbisDb.put(primaryCatalogKey, primaryMeta);
-                    if (tombstoneWrite?.then)
+                    return dbisDb.put(primaryCatalogKey, primaryMeta);
+                };
+                if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+                    // withUpdateAttributesLock's locked section cannot be held across an await, so a durable
+                    // tombstone depends on put being rebound to putSync for RocksDB primary stores (see
+                    // createOpenDBIObject). Check that BEFORE writing anything: a tombstone left behind by a
+                    // refused drop would delete the table on the next load.
+                    if (dbisDb.put !== dbisDb.putSync)
+                        throw new Error(`Cannot drop ${databaseName}.${_a.tableName}: the catalog store's put is asynchronous, so the drop tombstone cannot be made durable before the column families are dropped`);
+                    withUpdateAttributesLock(rootStore, `drop table '${databaseName}.${_a.tableName}'`, writeTombstone);
+                }
+                else {
+                    let tombstoneWrite;
+                    rootStore.transactionSync(() => {
+                        tombstoneWrite = writeTombstone();
+                    });
+                    if (typeof tombstoneWrite?.then === 'function')
                         await tombstoneWrite;
                 }
             }
@@ -1441,28 +1629,25 @@ function makeTable(options) {
                 // same-name create completes the interrupted drop and writes fresh
                 // catalog rows, and clobbering those would orphan the new table.
                 const removeTombstonedCatalog = () => {
-                    const currentPrimary = dbisDb.getSync(TableResource.tableName + '/');
+                    const currentPrimary = dbisDb.getSync(_a.tableName + '/');
                     if (!currentPrimary?.dropping)
                         return false;
                     for (const attribute of attributes) {
-                        dbisDb.remove(TableResource.tableName + '/' + attribute.name);
+                        dbisDb.remove(_a.tableName + '/' + attribute.name);
                     }
-                    dbisDb.remove(TableResource.tableName + '/');
+                    dbisDb.remove(_a.tableName + '/');
                     return true;
                 };
-                const rootStore = primaryStore.rootStore;
                 if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
                     // Serialize the drops + catalog removal against a concurrent
                     // same-name create (and completeInterruptedDrop) under the database's
                     // 'update-attributes' exclusive lock - the same lock the create path
-                    // holds. It is a synchronous spin lock that blocks the event loop, so
+                    // holds. It is a synchronous lock wait that blocks the event loop, so
                     // the locked section MUST stay synchronous: drop with dropSync (as
                     // completeInterruptedDrop does), never an awaited drop(), or a
-                    // concurrent create's spin would deadlock waiting on a drop that the
-                    // blocked event loop can never resolve.
-                    while (!rootStore.tryLock('update-attributes')) { }
-                    let removed = false;
-                    try {
+                    // concurrent create's wait would be stuck on a drop that the blocked
+                    // event loop can never resolve, burning its full deadline before failing.
+                    const removed = withUpdateAttributesLock(rootStore, `table '${databaseName}.${tableName}'`, () => {
                         for (const attribute of attributes) {
                             const index = indices[attribute.name];
                             if (index)
@@ -1479,11 +1664,8 @@ function makeTable(options) {
                         catch (error) {
                             ignoreAlreadyDropped(error);
                         }
-                        removed = removeTombstonedCatalog();
-                    }
-                    finally {
-                        rootStore.unlock('update-attributes');
-                    }
+                        return removeTombstonedCatalog();
+                    });
                     if (removed)
                         await dbisDb.committed;
                 }
@@ -1504,7 +1686,12 @@ function makeTable(options) {
                 }
             }
             else {
-                // legacy table per database
+                // legacy table per database. The store to retire is this table's own audit store: nothing
+                // assigns `primaryStore.auditStore` — openAuditStore() assigns `rootStore.auditStore`, and
+                // this is the reference makeTable() was handed. Awaited so a pass suspended mid-removal has
+                // released the primary DBI before it is closed and unlinked.
+                await auditStore?.stopAuditCleanup?.();
+                (0, storageReclamation_ts_1.removeStorageReclamation)(primaryStore.path);
                 await primaryStore.close();
                 node_fs_1.default.unlinkSync(primaryStore.path);
             }
@@ -1535,7 +1722,7 @@ function makeTable(options) {
                     estimatedRecordRange: undefined,
                 };
                 if (this.getContext()?.includeExpensiveRecordCountEstimates) {
-                    return TableResource.getRecordCount().then((recordCount) => {
+                    return _a.getRecordCount().then((recordCount) => {
                         description.recordCount = recordCount.recordCount;
                         description.estimatedRecordRange = recordCount.estimatedRange;
                         return description;
@@ -1819,14 +2006,71 @@ function makeTable(options) {
          * Save any changes into this instance to the current transaction
          */
         save() {
-            if (this.#savingOperation) {
-                try {
-                    return this.#saveOperation(this.#savingOperation);
+            this.#assertLiveHandle(this.getId()); // a write through a released or expired lock never lands
+            const operation = this.#savingOperation;
+            if ((!operation || operation.dropped) && this.#lockWritable && this.#lockHandle?.hold) {
+                // A held lock's record stages its update here rather than at lock() time: it is often
+                // written after the acquiring transaction has already completed, which would have
+                // dropped an update staged then. Nothing set means nothing to stage — a held-but-untouched
+                // id stays untouched. Scoped locks do not take this branch: #reloadLocked stages their
+                // TransactionWrite at lock() time (exactly like update()), so #savingOperation is always
+                // set for a live scoped lock and the ordinary path below applies.
+                // Verify the hold is still alive: if #lockWritable is set but the handle expired or was
+                // released between lock acquisition and this save(), throw 409 rather than silently
+                // committing stale data. Every lock-writable instance carries its own handle.
+                const saveHandle = this.#lockHandle;
+                if (saveHandle.expired || saveHandle.released) {
+                    throw (0, recordLock_ts_1.lockNotHeldError)(saveHandle);
+                }
+                const changes = this.#changes;
+                if (changes && Object.keys(changes).length > 0) {
+                    this.#savingOperation = null;
+                    return (0, when_ts_1.when)(this._writeUpdate(this.getId(), changes, false), () => {
+                        const op = this.#savingOperation;
+                        if (op?.dropped) {
+                            this.#changes = undefined;
+                            return;
+                        }
+                        // Clear #savingOperation so the next sequential save() enters the lock-writable
+                        // path and creates a fresh write (otherwise a non-null #savingOperation makes
+                        // save() take the #saveOperation branch with an already-committed write, which
+                        // is a no-op, silently dropping the new change).
+                        // op.innerCommit is the real native-transaction commit Promise set on the
+                        // immediateCommit path in DatabaseTransaction.save(); await it to ensure
+                        // durability before resolving to the caller.
+                        if (op?.saved) {
+                            this.#savingOperation = null;
+                            return op?.innerCommit;
+                        }
+                        // op.saved = false means addWrite deferred the save; #saveOperation commits it
+                        // synchronously but ImmediateTransaction.save() returns undefined while the
+                        // inner rocksdb commit is still pending — return innerCommit so the caller
+                        // actually waits for durability.
+                        return (0, when_ts_1.when)(this.save(), () => op?.innerCommit);
+                    });
                 }
-                finally {
+                // No changes: nothing to stage. A dropped operation (detached at a scoped→hold
+                // upgrade — see detachScopedUpgradeWrite) must not fall through to the ordinary
+                // #saveOperation path below with its now-detached reference.
+                if (!operation || operation.dropped) {
                     this.#savingOperation = null;
+                    return;
                 }
             }
+            if (this.#savingOperation) {
+                const operation = this.#savingOperation;
+                this.#savingOperation = null;
+                // A write that lands via a nested immediateCommit (e.g. a second sequential save() on
+                // the same ImmediateTransaction context, once the first has already closed it) sets
+                // operation.innerCommit to the real native-commit promise, but the commit() sweep loop
+                // that triggers it discards its own return value — #saveOperation()'s result can
+                // resolve before that native commit actually settles. Chain on innerCommit (as the
+                // lock-writable hold branch above already does) so callers awaiting save() see the
+                // write durably land, not just the outer (possibly premature) resolution.
+                const result = this.#saveOperation(operation);
+                const innerCommit = operation.innerCommit;
+                return innerCommit ? (0, when_ts_1.when)(innerCommit, () => result) : result;
+            }
         }
         #saveOperation(operation) {
             const transaction = txnForContext(this.getContext());
@@ -1904,6 +2148,7 @@ function makeTable(options) {
             });
         }
         _writeInvalidate(id, partialRecord, options) {
+            this.#assertLiveHandle(id);
             const context = this.getContext();
             checkValidId(id);
             const transaction = txnForContext(this.getContext());
@@ -1912,9 +2157,12 @@ function makeTable(options) {
                 store: primaryStore,
                 invalidated: true,
                 entry: this.#entry,
+                recordVersion: options?.version,
+                lockHandle: this.#lockHandle && this.#lockHandle.keyId === (0, DatabaseTransaction_ts_1.writeKeyId)(id) ? this.#lockHandle : undefined,
                 commit: (txnTime, existingEntry, _retry, transaction) => {
+                    const txnLogKey = isRocksDB && options?.version != null ? (transaction?.getTimestamp?.() ?? txnTime) : txnTime;
                     write.skipped = false; // reset on each retry; cleanup happens after commit if still true
-                    if (precedesExistingVersion(txnTime, existingEntry, options?.nodeId) <= 0) {
+                    if (precedesExistingVersion(txnTime, existingEntry, options?.nodeId) < 0) {
                         write.skipped = true;
                         return;
                     }
@@ -1935,7 +2183,13 @@ function makeTable(options) {
                         viaNodeId: options?.viaNodeId,
                         transaction,
                         tableToTrack: tableName,
+                        recordVersion: txnTime,
+                        additionalAuditRefs: isRocksDB && audit && txnLogKey !== txnTime
+                            ? [{ version: txnLogKey, nodeId: options?.nodeId }]
+                            : undefined,
                     }, 'invalidate');
+                    if (write.trackRecordVersion)
+                        write.recordVersionApplied = true;
                     // TODO: recordDeletion?
                 },
             };
@@ -1943,21 +2197,25 @@ function makeTable(options) {
             transaction.addWrite(write);
         }
         _writeRelocate(id, options) {
+            this.#assertLiveHandle(id);
             const context = this.getContext();
             checkValidId(id);
             const transaction = txnForContext(this.getContext());
-            transaction.addWrite({
+            const write = {
                 key: id,
                 store: primaryStore,
                 invalidated: true,
                 entry: this.#entry,
+                recordVersion: options?.version,
+                lockHandle: this.#lockHandle && this.#lockHandle.keyId === (0, DatabaseTransaction_ts_1.writeKeyId)(id) ? this.#lockHandle : undefined,
                 before: this.constructor.source?.relocate && !context?.source
                     ? this.constructor.source.relocate.bind(this.constructor.source, id, undefined, context)
                     : undefined,
                 commit: (txnTime, existingEntry, _retry, transaction) => {
-                    if (precedesExistingVersion(txnTime, existingEntry, options?.nodeId) <= 0)
+                    const txnLogKey = isRocksDB && options?.version != null ? (transaction?.getTimestamp?.() ?? txnTime) : txnTime;
+                    if (precedesExistingVersion(txnTime, existingEntry, options?.nodeId) < 0)
                         return;
-                    const residency = TableResource.getResidencyRecord(options.residencyId);
+                    const residency = _a.getResidencyRecord(options.residencyId);
                     let metadata = 0;
                     let newRecord = null;
                     const existingRecord = existingEntry?.value;
@@ -1981,9 +2239,16 @@ function makeTable(options) {
                         viaNodeId: options?.viaNodeId,
                         expiresAt: options.expiresAt,
                         transaction,
+                        recordVersion: txnTime,
+                        additionalAuditRefs: isRocksDB && audit && txnLogKey !== txnTime
+                            ? [{ version: txnLogKey, nodeId: options?.nodeId }]
+                            : undefined,
                     }, 'relocate', false, null);
+                    if (write.trackRecordVersion)
+                        write.recordVersionApplied = true;
                 },
-            });
+            };
+            transaction.addWrite(write);
         }
         /**
          * Record the relocation of an entry (when a record is moved to a different node), return true if it is now located locally
@@ -2102,10 +2367,253 @@ function makeTable(options) {
             }
         }
         /**
-         * This is intended to acquire a lock on a record from the whole cluster.
+         * Static entry point: `Table.lock(id, options?, context?)` — creates an instance in the given,
+         * ambient, or a fresh context and delegates to the instance lock(). This shadows Resource.static
+         * lock so that both callers share the same transaction link (required for cross-instance upgrade
+         * detection).  lock() is an in-process API with no authorization hook of its own; it is not
+         * protocol-dispatched, so no allowUpdate/allowCreate check runs on acquisition.
+         *
+         * Dropping the trailing `context` leaks the key: the bare `{}` fallback is an
+         * ImmediateTransaction, which releases no record locks.
+         */
+        static async lock(target, options, context) {
+            if (!isRocksDB)
+                throw new hdbError_ts_1.ClientError('Record locks are not supported on LMDB', 501);
+            if (options === undefined && isPlainOptions(target)) {
+                options = target;
+                target = undefined;
+            }
+            const id = target != null ? requestTargetToId(target) : null;
+            const resolvedContext = contextArgument(context) ?? transaction_ts_1.contextStorage.getStore() ?? {};
+            const resource = new _a(id, resolvedContext);
+            return resource.lock(target, options);
+        }
+        /**
+         * Acquire an exclusive lock on this record (or on `target`'s) and return it ready for updates
+         * (harper#483, Phase 0: exclusive across every worker thread of this node). The lock is held
+         * in process memory only — no durable writes. Phase 0 contract: lock() is mutually exclusive
+         * with other lock() calls on the same key; plain writes (put/patch/delete/create) are never
+         * gated or blocked. The generation expires after `lease` if it is never released.
+         *
+         * Transaction-scoped (default): write through the returned record (or the table's static verbs
+         * in the same transaction), and the commit or abort releases it. `{ hold: true }`: the lock
+         * outlives the transaction; write through the returned record and release with `unlock()`, or
+         * let the lease expire.
+         */
+        // async so option/id validation rejects rather than throwing past a caller's `.catch()`; the
+        // body still runs to completion synchronously, which is what keeps concurrent lock() calls
+        // on one key coalescing instead of racing to tryLock.
+        async lock(target, options) {
+            if (!isRocksDB)
+                throw new hdbError_ts_1.ClientError('Record locks are not supported on LMDB', 501);
+            if (options === undefined && isPlainOptions(target)) {
+                options = target;
+                target = undefined;
+            }
+            const id = target != null ? requestTargetToId(target) : this.getId();
+            checkValidId(id);
+            const resolved = (0, recordLock_ts_1.resolveLockOptions)(options);
+            const context = this.getContext();
+            const link = txnForContext(context);
+            const keyId = (0, DatabaseTransaction_ts_1.writeKeyId)(id);
+            const held = this.#lockHandle;
+            if (held && !held.released && !held.expired && held.keyId === keyId) {
+                // Re-entrant: upgrade to hold if requested, then preserve staged changes.
+                if (resolved.hold && !held.hold) {
+                    held.upgradeToHold(resolved.lease);
+                    // The scoped phase eagerly staged a TransactionWrite (see #reloadLocked); hold
+                    // staging is deferred and explicit-save-only, so an unsaved scoped write left
+                    // dangling here would otherwise auto-commit at the transaction sweep and clobber
+                    // whatever the hold write lands. detachScopedUpgradeWrite marks it .dropped so a
+                    // later save() on this instance falls through to the hold branch instead of the
+                    // dead #savingOperation reference.
+                    detachScopedUpgradeWrite(link, keyId, held);
+                }
+                return Promise.resolve(this.#reloadLocked(id, undefined, true));
+            }
+            const scoped = link.recordLockFor(primaryStore, keyId);
+            if (scoped && !scoped.released && !scoped.expired) {
+                if (resolved.hold && !scoped.hold) {
+                    // Upgrade scoped → hold: flip the existing handle object to hold mode so every
+                    // instance that already references this handle stays valid.  Retiring and creating a
+                    // new handle would invalidate those other references (their save() would then throw
+                    // 409 against a released handle).  The native key stays locked throughout.
+                    scoped.upgradeToHold(resolved.lease);
+                    detachScopedUpgradeWrite(link, keyId, scoped);
+                    return Promise.resolve(this.#reloadLocked(id, scoped, true));
+                }
+                // Already held with the same type: re-entrant return. Preserve any staged changes.
+                return Promise.resolve(this.#reloadLocked(id, scoped, true));
+            }
+            const key = (0, recordLock_ts_1.lockAttemptKey)(tableId, id);
+            // Coalesce concurrent lock() calls for the same key inside one link so they don't
+            // self-block: Promise.all([T.lock(id), T.lock(id)]) would otherwise have both calls
+            // reach tryLock before either registers, making the second park against the first.
+            const pending = link.pendingLockFor(primaryStore, keyId);
+            if (pending) {
+                // Wait for the in-flight acquisition, then take the re-entrant path as if
+                // recordLockFor had found it.  If the first attempt timed out, re-enter so
+                // the second caller gets its own timeout.
+                // The follower waits on the leader's acquisition, but only for its own timeout.
+                let followerTimer;
+                const followerTimedOut = Symbol('follower timeout');
+                const followerStart = Date.now();
+                const followerDeadline = new Promise((_, reject) => {
+                    followerTimer = setTimeout(() => reject(followerTimedOut), resolved.timeout).unref();
+                });
+                // Try again on this caller's own terms with the budget it has left.
+                const retryOnRemainingBudget = () => {
+                    // The enclosing transaction ended while we were parked. A retry re-resolves the
+                    // context, which no longer points at this link, so the handle it acquired would be
+                    // registered on a fresh transaction that no commit or abort ever releases — the
+                    // same abandonment the leader's own post-acquisition guard below rejects.
+                    if (link.open === DatabaseTransaction_ts_1.TRANSACTION_STATE.CLOSED && !link.saveCommits)
+                        throw new hdbError_ts_1.ServerError('Transaction was closed while waiting for a record lock', 500);
+                    const remaining = resolved.timeout - (Date.now() - followerStart);
+                    if (remaining <= 0)
+                        throw new hdbError_ts_1.ClientError(`Record is locked and was not released in time`, 423);
+                    return this.lock(target, { ...resolved, timeout: remaining });
+                };
+                return Promise.race([pending, followerDeadline]).then(() => {
+                    clearTimeout(followerTimer);
+                    const acquired = link.recordLockFor(primaryStore, keyId);
+                    if (acquired && !acquired.released && !acquired.expired) {
+                        if (resolved.hold && !acquired.hold) {
+                            detachScopedUpgradeWrite(link, keyId, acquired);
+                            acquired.upgradeToHold(resolved.lease);
+                        }
+                        return this.#reloadLocked(id, acquired, true);
+                    }
+                    return retryOnRemainingBudget();
+                }, (error) => {
+                    clearTimeout(followerTimer);
+                    if (error === followerTimedOut)
+                        throw new hdbError_ts_1.ClientError(`Record is locked and was not released in time`, 423);
+                    return retryOnRemainingBudget();
+                });
+            }
+            const pendingPromise = (0, recordLock_ts_1.acquireRecordKey)(link, primaryStore, key, keyId, resolved.timeout, resolved.lease, resolved.hold);
+            link.registerPendingLock(primaryStore, keyId, pendingPromise);
+            return pendingPromise.then((handle) => {
+                link.unregisterPendingLock(primaryStore, keyId);
+                if (link.open === DatabaseTransaction_ts_1.TRANSACTION_STATE.CLOSED && !link.saveCommits) {
+                    // The transaction was aborted while this call waited; nothing would ever release the handle.
+                    handle.release();
+                    throw new hdbError_ts_1.ServerError('Transaction was closed while waiting for a record lock', 500);
+                }
+                link.registerRecordLock(handle);
+                if (link.saveCommits && context?.timestamp)
+                    handle.noteCandidateFloor(context.timestamp);
+                if (link.open === DatabaseTransaction_ts_1.TRANSACTION_STATE.OPEN && !link.saveCommits) {
+                    // Explicit transaction() (not ImmediateTransaction): pin the clock to
+                    // acquiredAt when no writes have been staged yet.  When writes already
+                    // exist, leave the clock alone (ordering is best-effort; write held records
+                    // in their own transaction for the guarantee).  ImmediateTransaction is
+                    // excluded (saveCommits=true) — its clock is never pinned in lock();
+                    // each save() stamps from the handle's committed version floor instead.
+                    if (link.writes.length === 0 && !link.timestamp) {
+                        link.timestamp = handle.acquiredAt;
+                    }
+                    if (!resolved.hold && link.transaction) {
+                        // Scoped lock: the read snapshot may predate the lock; drop it so the
+                        // scope reads what it locked.  Hold locks use acquiredAt directly and
+                        // do not update the read snapshot.
+                        // The timestamp guard matches DatabaseTransaction's own setTimestamp calls: a
+                        // deferred update() write leaves the clock at 0, which rocksdb-js rejects.
+                        if (link.writes.length === 0 && link.readTxnsUsed <= 1) {
+                            link.releaseReadTxn();
+                            link.snapshotFree = true;
+                        }
+                        else if (link.timestamp)
+                            link.transaction.setTimestamp(link.timestamp);
+                    }
+                }
+                // ImmediateTransaction: no clock pinning in lock(); save() stamps each write
+                // from the committed handle floor for both scoped and hold handles.
+                return this.#reloadLocked(id, handle);
+            }, (err) => {
+                link.unregisterPendingLock(primaryStore, keyId);
+                throw err;
+            });
+        }
+        #reloadLocked(id, holdHandle, preserveChanges = false) {
+            // For freshness, read the committed entry (snapshot-free) so a hold lock sees concurrent
+            // committed writes rather than a stale snapshot.  A write earlier in THIS explicit
+            // transaction has not landed in that committed entry yet (harper#1968: Harper defers an
+            // explicit transaction's writes until the writing call actually runs them), so pull the
+            // current value the same way a chained write picks up its basis (priorStagedWrite): the
+            // record comes from the prior staged write, the rest of the entry (version, audit chain,
+            // blob metadata) stays the pre-transaction one.
+            const link = txnForContext(this.getContext());
+            let entryForReload = primaryStore.getEntry(id);
+            if (link.open === DatabaseTransaction_ts_1.TRANSACTION_STATE.OPEN) {
+                const keyId = (0, DatabaseTransaction_ts_1.writeKeyId)(id);
+                const tailWrite = link.writesByKey?.get(primaryStore)?.get(keyId);
+                const priorStaged = tailWrite && (tailWrite.stagedEntry !== undefined ? tailWrite : (0, DatabaseTransaction_ts_1.priorStagedWrite)(tailWrite));
+                if (priorStaged?.stagedEntry !== undefined) {
+                    entryForReload = entryForReload
+                        ? { ...entryForReload, value: priorStaged.stagedEntry.value }
+                        : { value: priorStaged.stagedEntry.value };
+                    if (entryForReload.value && typeof entryForReload.value === 'object') {
+                        // Register the merged entry in entryMap so getUpdatedTime() works.
+                        RecordEncoder_ts_1.entryMap.set(entryForReload.value, entryForReload);
+                    }
+                }
+            }
+            if ((0, DatabaseTransaction_ts_1.writeKeyId)(id) !== (0, DatabaseTransaction_ts_1.writeKeyId)(this.getId())) {
+                // lock(target) where target differs from this record: return a separate instance.
+                const fresh = new this.constructor(id, this.getContext());
+                _a._updateResource(fresh, entryForReload);
+                if (holdHandle != null) {
+                    fresh.#lockHandle = holdHandle;
+                    // Do not clear this.#lockHandle: the original instance keeps its own lock on its
+                    // own id; the fresh instance owns the lock on the target id independently.
+                }
+                fresh.#lockWritable = true;
+                // Scoped (not hold) stages exactly like update(): create the TransactionWrite now so
+                // save() is the ordinary #savingOperation path.  Hold keeps deferred staging (the
+                // acquiring transaction may commit before the holder ever writes).
+                if (!fresh.#lockHandle.hold)
+                    fresh._writeUpdate(id, fresh.#changes, false);
+                return fresh;
+            }
+            // Store the handle for both scoped and hold locks; undefined (re-entrant hold fast-path)
+            // must not clear a handle already set.
+            if (holdHandle != null)
+                this.#lockHandle = holdHandle;
+            _a._updateResource(this, entryForReload);
+            // Preserve staged changes when upgrading the same instance from scoped to hold so that
+            // set() calls made under the scoped lock survive the reload.
+            if (!preserveChanges)
+                this.#changes = undefined;
+            this.#lockWritable = true;
+            // Scoped (not hold): stage now, same as update() would.  Skip if a write from an earlier
+            // lock() cycle on this instance is still pending (re-entrant call before its save()).
+            if (!this.#lockHandle.hold && !this.#savingOperation)
+                this._writeUpdate(id, this.#changes, false);
+            return this;
+        }
+        /**
+         * Release the lock this instance holds. Resolves true when this call cleared the native key lock.
+         * Works for both held (`{ hold: true }`) and transaction-scoped locks. After unlock() the
+         * instance is no longer lock-writable; writes through it require a fresh lock.
          */
-        lock() {
-            throw new Error('Not yet implemented');
+        unlock() {
+            // Always clear the local lock-writable state so subsequent writes on this instance are
+            // ungated, regardless of whether the handle was already released.
+            const handle = this.#lockHandle;
+            this.#lockHandle = undefined;
+            this.#lockWritable = false;
+            if (!handle || handle.released)
+                return Promise.resolve(false);
+            const link = txnForContext(this.getContext());
+            // A scoped lock staged its write at lock() time; released before commit, that write must not
+            // run into the released-handle guard at the sweep.
+            if (this.#savingOperation && !this.#savingOperation.saved && this.#savingOperation.lockHandle === handle)
+                this.#savingOperation = null;
+            detachScopedUpgradeWrite(link, (0, DatabaseTransaction_ts_1.writeKeyId)(this.getId()), handle);
+            link.unregisterRecordLock(handle);
+            return Promise.resolve(handle.release());
         }
         static operation(operation, context) {
             operation.table ||= tableName;
@@ -2221,8 +2729,10 @@ function makeTable(options) {
         // a notification that a write has already occurred in the canonical data source, we need to update our
         // local copy
         _writeUpdate(id, recordUpdate, fullUpdate, options) {
+            this.#assertLiveHandle(id);
             const context = this.getContext();
             const transaction = txnForContext(context);
+            const replaying = transaction.isReplay === true;
             checkValidId(id);
             if (fullUpdate && recordUpdate == null && options?.isNotification) {
                 // A source/replication-applied put must carry the record; these applies skip record
@@ -2265,6 +2775,13 @@ function makeTable(options) {
                 nodeName: context?.nodeName,
                 fullUpdate,
                 deferSave: true,
+                // the origin's record version on an applied write; absent for a locally-originated one
+                recordVersion: options?.version,
+                // Include the lock handle (if any) so the expired-handle guard in
+                // DatabaseTransaction.save() can throw 409 when the lease has lapsed.
+                // Only attach the hold handle when it covers exactly this key; off-key writes
+                // are ordinary and must not carry an unrelated hold's handle.
+                lockHandle: this.#lockHandle && this.#lockHandle.keyId === (0, DatabaseTransaction_ts_1.writeKeyId)(id) ? this.#lockHandle : undefined,
                 validate: (txnTime, committedBy = transaction) => {
                     if (!recordUpdate)
                         recordUpdate = this.#changes;
@@ -2389,6 +2906,7 @@ function makeTable(options) {
                     this.#savingOperation = null;
                     write.stagedIn = undefined; // nothing may pin this write's transaction past its commit
                     let omitLocalRecord = false;
+                    const txnLogKey = isRocksDB && options?.version != null ? (transaction?.getTimestamp?.() ?? txnTime) : txnTime;
                     // we use optimistic locking to only commit if the existing record state still holds true.
                     // this is superior to using an async transaction since it doesn't require JS execution
                     //  during the write transaction.
@@ -2449,8 +2967,8 @@ function makeTable(options) {
                             // best-effort keyed lookup in the capped block below — see #1148. precedesExistingVersion(...)
                             // === 0 is the identity tie: same version AND same node (the local node is id 0, so an undefined
                             // options?.nodeId resolves to the same 0 the ref stored).
-                            if (existingEntry.additionalAuditRefs?.some((ref) => ref.version === txnTime &&
-                                precedesExistingVersion(txnTime, { version: txnTime, localTime: txnTime, key: id, nodeId: ref.nodeId }, options?.nodeId) === 0)) {
+                            if (existingEntry.additionalAuditRefs?.some((ref) => ref.version === txnLogKey &&
+                                precedesExistingVersion(txnTime, { version: txnTime, localTime: txnLogKey, key: id, nodeId: ref.nodeId }, options?.nodeId) === 0)) {
                                 write.skipped = true;
                                 return; // out-of-order write already folded into this record
                             }
@@ -2478,10 +2996,10 @@ function makeTable(options) {
                                 if (!oldestRetainedAuditTimeResolved) {
                                     oldestRetainedAuditTimeResolved = true;
                                     // getRange yields ascending by audit-log key, so the first entry is the oldest retained.
-                                    // Mirror replicationConnection's retention check and the cleanup key basis (localTime ??
-                                    // version). Fall back to the nominal time-based purge floor when the log is empty/unavailable.
+                                    // Mirror replicationConnection's retention check and the cleanup key basis (`txnLogKey`).
+                                    // Fall back to the nominal time-based purge floor when the log is empty/unavailable.
                                     for (const entry of auditStore.getRange({ start: 1, log: options?.nodeId })) {
-                                        oldestRetainedAuditTime = entry.localTime ?? entry.version;
+                                        oldestRetainedAuditTime = entry.txnLogKey;
                                         break;
                                     }
                                     oldestRetainedAuditTime ??= Date.now() - auditStore_ts_1.auditRetention;
@@ -2494,43 +3012,67 @@ function makeTable(options) {
                             // depth-cap block. This is the same keyed lookup that block performs, hoisted ahead of the walk.
                             // It is what catches transitive/proxied re-deliveries: they arrive buried below the record head
                             // (so replication's head-tie fast-skip can't see them) yet are exact duplicates. Keyed by nodeId,
-                            // so it is correct across multiple source nodes. RocksDB-only: LMDB audit entries are keyed by
-                            // local audit time, not version, so this version-keyed lookup doesn't apply there (LMDB keeps the
-                            // exact unbounded walk). A miss (the keyed lookup can lag a back-to-back re-delivery — #1137)
+                            // so it is correct across multiple source nodes. The lookup key is this write's LOG key, not its
+                            // record version — a replication apply commits under the origin's log key while storing the
+                            // origin's version, and only the log key addresses the entry (harper#2412).
+                            // RocksDB-only: LMDB audit entries are keyed by local audit time, so this lookup doesn't apply
+                            // there (LMDB keeps the exact unbounded walk). A miss (the keyed lookup can lag a back-to-back re-delivery — #1137)
                             // simply falls through to the walk, so this never changes correctness; the additionalAuditRefs
                             // check above remains the read-your-writes guard. Never when this write staged in a prior
                             // failed attempt: that attempt already appended this write's own audit entry, so the lookup
                             // would find it and skip the write as "already applied" when the record was never committed.
                             // A recommit of the same transaction survived that skip only because the old write batch
                             // still carried the put; a fresh-transaction replay (ERR_TRY_AGAIN) would drop the write.
-                            if (isRocksDB && !stagedOwnAuditEntry && dedupVersionCouldBeRetained(txnTime)) {
-                                const priorAudit = auditStore.get(txnTime, tableId, id, options?.nodeId);
+                            if (isRocksDB && !replaying && !stagedOwnAuditEntry && dedupVersionCouldBeRetained(txnLogKey)) {
+                                const priorAudit = auditStore.get(txnLogKey, tableId, id, options?.nodeId);
                                 if (priorAudit &&
-                                    priorAudit.version === txnTime &&
-                                    precedesExistingVersion(txnTime, { version: txnTime, localTime: txnTime, key: id, nodeId: priorAudit.nodeId }, options?.nodeId) === 0) {
+                                    priorAudit.txnLogKey === txnLogKey &&
+                                    precedesExistingVersion(txnTime, { version: txnTime, localTime: txnLogKey, key: id, nodeId: priorAudit.nodeId }, options?.nodeId) === 0) {
                                     write.skipped = true;
                                     return; // duplicate already applied; avoid the resequencing walk
                                 }
                             }
                             // incremental CRDT updates are only available with audit logging on
-                            let localTime = existingEntry.localTime;
+                            const initialAuditHead = isRocksDB
+                                ? resolveAuditHead(id, existingEntry.version, existingEntry.nodeId, existingEntry.additionalAuditRefs)
+                                : { txnLogKey: existingEntry.localTime, nodeId: existingEntry.nodeId };
+                            let localTime = initialAuditHead.txnLogKey;
                             let auditedVersion = existingEntry.version;
                             logger_ts_1.logger.debug?.('Applying CRDT update to record with id: ', id, 'txn time', new Date(txnTime), 'applying later update from:', new Date(auditedVersion), 'local recorded time', new Date(localTime));
-                            let nodeId = existingEntry.nodeId;
+                            let nodeId = initialAuditHead.nodeId;
                             const succeedingUpdates = []; // record the "future" updates, as we need to apply the updates in reverse order
                             const auditRefsToVisit = existingEntry.additionalAuditRefs
                                 ? existingEntry.additionalAuditRefs.map((ref) => ({ localTime: ref.version, nodeId: ref.nodeId }))
                                 : [];
-                            // Collect any existing audit refs that should be preserved (those older than current transaction)
+                            // Out-of-order merges retain every existing branch head; per-origin log keys are not globally ordered.
                             if (existingEntry.additionalAuditRefs) {
                                 for (const ref of existingEntry.additionalAuditRefs) {
-                                    if (ref.version <= txnTime) {
-                                        additionalAuditRefs.push(ref);
-                                    }
+                                    additionalAuditRefs.push(ref);
                                 }
                             }
                             let addedAuditRef = false;
                             let nextRef;
+                            const visitedAuditRefs = new Set();
+                            const queuePreviousAuditRefs = (auditRecord) => {
+                                const previousRefs = auditRecord.previousAdditionalAuditRefs;
+                                if (previousRefs) {
+                                    for (const ref of previousRefs) {
+                                        auditRefsToVisit.push({ localTime: ref.version, nodeId: ref.nodeId });
+                                        logger_ts_1.logger.debug?.('Adding audit ref from audit record to visit queue', {
+                                            version: ref.version,
+                                            nodeId: ref.nodeId,
+                                        });
+                                    }
+                                }
+                            };
+                            const advanceToPreviousAudit = (auditRecord) => {
+                                const previousRefs = auditRecord.previousAdditionalAuditRefs;
+                                const previousHead = isRocksDB && previousRefs?.length
+                                    ? resolveAuditHead(id, auditRecord.previousVersion, auditRecord.previousNodeId, previousRefs)
+                                    : { txnLogKey: auditRecord.previousVersion, nodeId: auditRecord.previousNodeId };
+                                localTime = previousHead.txnLogKey;
+                                nodeId = previousHead.nodeId;
+                            };
                             let walkSteps = 0;
                             let auditWalkCapped = false;
                             // Early-out residual: as we walk the chain newest-first, fold each succeeding patch into a
@@ -2549,17 +3091,21 @@ function makeTable(options) {
                             // appended this write's own audit entry, so the lookup would match it while the record was
                             // never committed (see the up-front keyed dedup above).
                             const isReDeliveredDuplicate = () => {
-                                if (stagedOwnAuditEntry)
+                                if (replaying || stagedOwnAuditEntry)
                                     return false;
-                                if (!dedupVersionCouldBeRetained(txnTime))
-                                    return false; // pre-retention version — skip the end-of-log scan (best-effort; see above)
-                                const duplicate = auditStore.get(txnTime, tableId, id, options?.nodeId);
+                                if (!dedupVersionCouldBeRetained(txnLogKey))
+                                    return false; // pre-retention log key — skip the end-of-log scan (best-effort; see above)
+                                const duplicate = auditStore.get(txnLogKey, tableId, id, options?.nodeId);
                                 return (duplicate &&
-                                    duplicate.version === txnTime &&
-                                    precedesExistingVersion(txnTime, { version: txnTime, localTime: txnTime, key: id, nodeId: duplicate.nodeId }, options?.nodeId) === 0);
+                                    duplicate.txnLogKey === txnLogKey &&
+                                    precedesExistingVersion(txnTime, { version: txnTime, localTime: txnLogKey, key: id, nodeId: duplicate.nodeId }, options?.nodeId) === 0);
                             };
                             do {
                                 while (localTime > txnTime || (auditedVersion >= txnTime && localTime > 0)) {
+                                    const auditIdentity = `${nodeId ?? 0}:${localTime}`;
+                                    if (visitedAuditRefs.has(auditIdentity))
+                                        break;
+                                    visitedAuditRefs.add(auditIdentity);
                                     // Bound the walk only for RocksDB, where the OOM was observed (issue #1114): each step
                                     // is a transaction-log range scan + msgpackr decode, and the per-node logs can be huge.
                                     // LMDB audit entries are keyed by local audit time (not version), so the duplicate
@@ -2571,19 +3117,39 @@ function makeTable(options) {
                                     const auditRecord = auditStore.get(localTime, tableId, id, nodeId);
                                     if (!auditRecord)
                                         break;
+                                    queuePreviousAuditRefs(auditRecord);
+                                    if (isRocksDB &&
+                                        !replaying &&
+                                        !stagedOwnAuditEntry &&
+                                        localTime === txnLogKey &&
+                                        precedesExistingVersion(txnTime, { version: txnTime, localTime: txnLogKey, key: id, nodeId: auditRecord.nodeId }, options?.nodeId) === 0) {
+                                        write.skipped = true;
+                                        return;
+                                    }
                                     auditedVersion = auditRecord.version;
                                     if (auditedVersion >= txnTime) {
                                         if (auditedVersion === txnTime) {
                                             precedesExisting = precedesExistingVersion(txnTime, { version: auditedVersion, localTime: localTime, key: id, nodeId: auditRecord.nodeId }, options?.nodeId);
                                             if (precedesExisting === 0) {
-                                                logger_ts_1.logger.debug?.('The transaction time is equal to the existing version, treating as duplicate', id);
-                                                write.skipped = true;
-                                                return; // treat a tie as a duplicate and drop it
+                                                if (isRocksDB && localTime !== txnLogKey) {
+                                                    // Same origin and record version, but a distinct write. Its per-origin log key
+                                                    // orders the otherwise non-unique record clock without comparing keys across origins.
+                                                    precedesExisting = txnLogKey > localTime ? 1 : -1;
+                                                }
+                                                else if (replaying || stagedOwnAuditEntry) {
+                                                    // The log entry being replayed (or staged by this write's failed attempt) is
+                                                    // the write itself, not proof that its primary-store mutation committed.
+                                                    precedesExisting = 1;
+                                                }
+                                                else {
+                                                    logger_ts_1.logger.debug?.('The transaction time and log key match the existing write, treating as duplicate', id);
+                                                    write.skipped = true;
+                                                    return;
+                                                }
                                             }
                                             if (precedesExisting > 0) {
                                                 // if the existing version is older, we can skip this update
-                                                localTime = auditRecord.previousVersion;
-                                                nodeId = auditRecord.previousNodeId;
+                                                advanceToPreviousAudit(auditRecord);
                                                 continue;
                                             }
                                         }
@@ -2618,23 +3184,16 @@ function makeTable(options) {
                                     }
                                     if (!addedAuditRef && isRocksDB) {
                                         addedAuditRef = true;
-                                        // Add a reference to this older audit record if we had out-of-order writes
-                                        additionalAuditRefs.push({ version: txnTime, nodeId: options?.nodeId });
+                                        // Add a reference to this older audit record if we had out-of-order writes. The stored
+                                        // value is a LOG key, not a record version: every consumer follows it straight into
+                                        // `auditStore.get` (see the `auditRefsToVisit` mapping above and below), and on an
+                                        // applied write those two clocks differ.
+                                        additionalAuditRefs.push({ version: txnLogKey, nodeId: options?.nodeId });
                                         logger_ts_1.logger.debug?.('Adding additional audit ref for out-of-order write', {
-                                            version: txnTime,
+                                            txnLogKey,
                                             nodeId: options?.nodeId,
                                         });
                                     }
-                                    // Collect any additional audit refs from this audit record to traverse other branches
-                                    if (auditRecord.previousAdditionalAuditRefs) {
-                                        for (const ref of auditRecord.previousAdditionalAuditRefs) {
-                                            auditRefsToVisit.push({ localTime: ref.version, nodeId: ref.nodeId });
-                                            logger_ts_1.logger.debug?.('Adding audit ref from audit record to visit queue', {
-                                                version: ref.version,
-                                                nodeId: ref.nodeId,
-                                            });
-                                        }
-                                    }
                                     // Every field of this write is overwritten by newer writes, and there is no alternate
                                     // audit branch left to scan, so it is fully superseded — the same outcome as walking to
                                     // the end and taking the `writeCommit(false)` escape below, reached without paying the rest
@@ -2652,8 +3211,7 @@ function makeTable(options) {
                                         }
                                         return writeCommit(false);
                                     }
-                                    localTime = auditRecord.previousVersion;
-                                    nodeId = auditRecord.previousNodeId;
+                                    advanceToPreviousAudit(auditRecord);
                                 }
                                 // Check if we need to scan additional audit refs from this record
                                 if (auditWalkCapped)
@@ -2748,14 +3306,14 @@ function makeTable(options) {
                         throw new Error('Can not assign a record to a record, check for circular references');
                     if (residencyId == undefined) {
                         if (entry?.residencyId)
-                            context.previousResidency = TableResource.getResidencyRecord(entry.residencyId);
-                        const residency = residencyFromFunction(TableResource.getResidency(recordToStore, context));
+                            context.previousResidency = _a.getResidencyRecord(entry.residencyId);
+                        const residency = residencyFromFunction(_a.getResidency(recordToStore, context));
                         if (residency) {
                             if (!residency.includes(server.hostname)) {
                                 // if we aren't in the residency list, specify that our local record should be omitted or be partial
                                 auditRecordToStore ??= recordToStore;
                                 omitLocalRecord = true;
-                                if (TableResource.getResidencyById) {
+                                if (_a.getResidencyById) {
                                     // complete omission of the record that doesn't belong here
                                     recordToStore = undefined;
                                 }
@@ -2825,7 +3383,17 @@ function makeTable(options) {
                         }
                     })());
                     updateIndices(id, existingRecord, recordToStore, transaction && { transaction });
+                    // Preserve an addressable audit head when the record and log clocks diverge.
+                    if (isRocksDB && audit && !isCopyApply && txnLogKey !== txnTime) {
+                        const headIndex = additionalAuditRefs.findIndex((ref) => ref.version === txnLogKey && (ref.nodeId ?? 0) === (options?.nodeId ?? 0));
+                        if (headIndex > 0)
+                            additionalAuditRefs.unshift(additionalAuditRefs.splice(headIndex, 1)[0]);
+                        else if (headIndex < 0)
+                            additionalAuditRefs.unshift({ version: txnLogKey, nodeId: options?.nodeId });
+                    }
                     writeCommit(true);
+                    if (write.trackRecordVersion)
+                        write.recordVersionApplied = true;
                     if (expiresAt >= 0) {
                         scheduleCleanup(); // arm for replicated writes too, not just local-context writes
                         // A runtime per-record expiresAt on a table with no table-level expiration/eviction, no expiresAt
@@ -2852,6 +3420,8 @@ function makeTable(options) {
                             user: context?.user,
                             residencyId,
                             expiresAt,
+                            recordVersion: txnTime,
+                            recordNodeId: precedesExisting < 0 ? existingEntry?.nodeId : options?.nodeId,
                             nodeId: options?.nodeId,
                             viaNodeId: options?.viaNodeId,
                             originatingOperation: context?.originatingOperation,
@@ -2889,7 +3459,7 @@ function makeTable(options) {
             // calls the backend, and a tracked-instance mutation (update(id,{}); row.source=…;
             // save()) that sets the source via accessors after update() won't re-embed. A
             // resource-layer re-embed is the proper fix; tracked as a follow-up.
-            const embedBefore = (0, embedHook_ts_1.buildEmbedBefore)(recordUpdate, context, options, TableResource.embedAttributes, TableResource.userEmbedders);
+            const embedBefore = (0, embedHook_ts_1.buildEmbedBefore)(recordUpdate, context, options, _a.embedAttributes, _a.userEmbedders);
             const proceed = () => {
                 // On a source/replication apply (`isNotification`), the record's already-saved blobs were
                 // received out-of-band for THIS write, so track them for skip/abort cleanup (harper-pro#406).
@@ -2945,6 +3515,7 @@ function makeTable(options) {
             return Boolean(this.#record);
         }
         _writeDelete(id, options) {
+            this.#assertLiveHandle(id);
             const context = this.getContext();
             const transaction = txnForContext(context);
             checkValidId(id);
@@ -2955,6 +3526,8 @@ function makeTable(options) {
                 entry,
                 chainsStagedState: true,
                 nodeName: context?.nodeName,
+                recordVersion: options?.version,
+                lockHandle: this.#lockHandle && this.#lockHandle.keyId === (0, DatabaseTransaction_ts_1.writeKeyId)(id) ? this.#lockHandle : undefined,
                 before: this.constructor.source?.delete && !context?.source
                     ? this.constructor.source.delete.bind(this.constructor.source, id, undefined, context)
                     : undefined,
@@ -2966,10 +3539,11 @@ function makeTable(options) {
                     const priorStagedOp = (0, DatabaseTransaction_ts_1.priorStagedWrite)(write);
                     const priorStaged = priorStagedOp?.stagedEntry;
                     const existingRecord = priorStaged ? priorStaged.value : existingEntry?.value;
+                    const txnLogKey = isRocksDB && options?.version != null ? (transaction?.getTimestamp?.() ?? txnTime) : txnTime;
                     if (retry) {
                         if (context && existingEntry?.version > (context.lastModified || 0))
                             context.lastModified = existingEntry.version;
-                        TableResource._updateResource(this, existingEntry);
+                        _a._updateResource(this, existingEntry);
                     }
                     // a strictly newer record exists locally, so this delete loses. An earlier write in this
                     // transaction can never trip this guard — it shares this transaction's timestamp and
@@ -2987,6 +3561,10 @@ function makeTable(options) {
                             viaNodeId: options?.viaNodeId,
                             transaction,
                             tableToTrack: tableName,
+                            recordVersion: txnTime,
+                            additionalAuditRefs: isRocksDB && audit && txnLogKey !== txnTime
+                                ? [{ version: txnLogKey, nodeId: options?.nodeId }]
+                                : undefined,
                         }, 'delete');
                         if (!audit || isRocksDB)
                             scheduleCleanup();
@@ -2996,6 +3574,8 @@ function makeTable(options) {
                         (0, RecordEncoder_ts_1.removeEntry)(primaryStore, existingEntry, isRocksDB && transaction ? { transaction } : undefined);
                     }
                     write.stagedEntry = { value: undefined }; // the key holds no record for the rest of this transaction
+                    if (write.trackRecordVersion)
+                        write.recordVersionApplied = true;
                     // the removal supersedes the nearest record an earlier write in this transaction stored
                     // (older ones were already marked by their staged successors), so its saved blobs are
                     // cleaned up post-commit unless its audit entry references them
@@ -3254,7 +3834,7 @@ function makeTable(options) {
                 // Note, that we do allow users to disable condition re-ordering, in case they have knowledge of a preferred
                 // order for their query.
                 if (conditions.length > 1 && operator !== 'or')
-                    return sortBy(conditions, (0, search_ts_1.estimateCondition)(TableResource));
+                    return sortBy(conditions, (0, search_ts_1.estimateCondition)(_a));
                 else
                     return conditions;
             }
@@ -3329,6 +3909,10 @@ function makeTable(options) {
                 }
             }
             const select = target.select;
+            // Whether the caller supplied real filter conditions — read from the raw request, NOT the
+            // planner-augmented `conditions` (which by now may carry a synthetic `sort` pseudo-condition and
+            // injected full-scan condition). Used to pick the count-estimate source below.
+            const hasUserConditions = Array.isArray(target.conditions) && target.conditions.length > 0;
             if (conditions.length === 0) {
                 conditions = [{ attribute: primaryKey, comparator: 'greater_than', value: true }];
             }
@@ -3365,7 +3949,7 @@ function makeTable(options) {
             const recordAccess = boundRowFilter || typeof target.vectorFilter === 'function'
                 ? { rowFilter: boundRowFilter, vectorFilter: target.vectorFilter }
                 : undefined;
-            const entries = (0, search_ts_1.executeConditions)(conditions, operator, TableResource, readTxn, target, context, (results, filters) => transformToEntries(results, select, context, readTxn, filters), filtered, recordAccess);
+            const entries = (0, search_ts_1.executeConditions)(conditions, operator, _a, readTxn, target, context, (results, filters) => transformToEntries(results, select, context, readTxn, filters), filtered, recordAccess);
             const ensure_loaded = target.ensureLoaded !== false;
             // The guards inside executeConditions evaluate the
             // LOCAL record, but on a caching table transformEntryForSelect may then revalidate an
@@ -3382,11 +3966,126 @@ function makeTable(options) {
             // since those never run the ensureLoaded-gated freshness check this transform
             // otherwise applies unconditionally to every read.
             const includeExpired = target.includeExpired === true;
-            const transformToRecord = TableResource.transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, true, boundRowFilter, includeExpired, postOrdering);
-            let results = TableResource.transformToOrderedSelect(entries, select, postOrdering, context, readTxn, transformToRecord);
+            const transformToRecord = _a.transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, true, boundRowFilter, includeExpired, postOrdering);
+            let results = _a.transformToOrderedSelect(entries, select, postOrdering, context, readTxn, transformToRecord);
+            const offset = target.offset || 0;
+            const end = target.limit !== undefined ? offset + target.limit : undefined;
+            // `Prefer: count=` (REST pagination): materialize the requested page and attach a total record
+            // count so the HTTP layer can emit a Content-Range. `exact` drains the full matched set once,
+            // windowing the page in the same pass; `estimated` returns just the page plus a cheap planner/
+            // table estimate. Opt-in only — the default streaming path below is untouched.
+            //
+            // Requires a bounded page AND window. Counting is a pagination feature; both the limit and the
+            // offset must be finite, non-negative integers, the limit no larger than MAX_COUNT_PAGE, and the
+            // window (offset + limit) no larger than MAX_EXACT_COUNT_SCAN. Anything else — a missing/
+            // oversized/non-finite/negative limit or offset (a bare collection GET, limit(Infinity),
+            // limit(foo), limit(-5,10)) or a deep-page window past the scan budget — falls through to the
+            // normal streaming path with no count. This bounds the offset too: without it a huge offset would
+            // postpone the exact guardrail (which only engages past the page) until that offset was scanned.
+            const pageLimit = target.limit;
+            if (target.count &&
+                Number.isInteger(pageLimit) &&
+                pageLimit >= 0 &&
+                pageLimit <= MAX_COUNT_PAGE &&
+                Number.isInteger(offset) &&
+                offset >= 0 &&
+                offset + pageLimit <= MAX_EXACT_COUNT_SCAN) {
+                const wantExact = target.count === 'exact';
+                const pageEnd = offset + pageLimit;
+                const countStart = node_perf_hooks_1.performance.now();
+                // A custom-index (vector/HNSW) traversal returns a bounded, approximate candidate set whose size is
+                // chosen from `minResults` (offset + limit), so `scanned` over it tracks the requested page size, not
+                // the true match count — the same query at limit(5) vs limit(200) would otherwise advertise two
+                // different `count=exact` totals. Any query whose execution touches a custom index is affected: a
+                // custom-index sort (its aligned pseudo-condition lands in `conditions`), a custom-index threshold
+                // filter (an HNSW `lt`/`le` is the same minResults-widened traversal as a sort), or an opaque vector
+                // filter. Report the total as unavailable for those rather than advertising it as count=exact
+                // (mirroring how the estimated branch below bails to null for an opaque row/vector filter). A vector
+                // sort applied as in-memory post-ordering leaves no custom-index condition here and stays exact.
+                const touchesCustomIndex = (conds) => conds.some((c) => {
+                    if (!c)
+                        return false;
+                    if (c.conditions)
+                        return touchesCustomIndex(c.conditions);
+                    const attr = Array.isArray(c.attribute) ? c.attribute[0] : (c.attribute ?? c[0]);
+                    return typeof attr === 'string' && Boolean(indices[attr]?.customIndex);
+                });
+                const approximateResultSet = typeof target.vectorFilter === 'function' || touchesCustomIndex(conditions);
+                return (async () => {
+                    const page = [];
+                    let scanned = 0;
+                    let exact = true;
+                    try {
+                        for await (const record of results) {
+                            if (scanned >= offset && scanned < pageEnd)
+                                page.push(record);
+                            scanned++;
+                            // A store whose async iterator settles synchronously (the common indexed-scan case) would
+                            // otherwise let this drain spin as one uninterrupted microtask run, blocking the event loop
+                            // for the whole count. Yield to the macrotask queue periodically so concurrent requests and
+                            // I/O still make progress during a large exact scan.
+                            if ((scanned & (COUNT_YIELD_INTERVAL - 1)) === 0)
+                                await new Promise((resolve) => setImmediate(resolve));
+                            // The page window [offset, pageEnd) is always collected in full first — the guardrail
+                            // only ever abandons the running TOTAL, never truncates the page body.
+                            if (scanned >= pageEnd) {
+                                // `estimated` needs nothing past the page; an approximate (vector) exact total is going to
+                                // be reported unavailable anyway, so don't drain its tail for a number we won't publish.
+                                if (!wantExact || approximateResultSet)
+                                    break;
+                                // `exact` keeps counting the tail, bounded by a row cap AND a time budget so a
+                                // large match set can't turn a bounded page fetch into an unbounded scan.
+                                if (scanned > MAX_EXACT_COUNT_SCAN || node_perf_hooks_1.performance.now() - countStart > MAX_EXACT_COUNT_MS) {
+                                    exact = false;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        // We own the iteration here (no results.onDone consumer), so release the read
+                        // transaction unconditionally — including when the drain throws — or the snapshot leaks.
+                        txn.doneReadTxn();
+                    }
+                    let total;
+                    if (wantExact) {
+                        // `scanned` is only an authoritative total when the iteration was exhaustive and deterministic;
+                        // an approximate (vector/HNSW) result set is neither, so report the total as unavailable.
+                        total = exact && !approximateResultSet ? scanned : null;
+                    }
+                    else if (boundRowFilter || typeof target.vectorFilter === 'function') {
+                        // An opaque row/vector filter shapes the result but isn't reflected in the index/condition
+                        // estimate; guessing would both mislead and disclose cardinality the filter hides.
+                        total = null;
+                    }
+                    else if (!hasUserConditions) {
+                        total = (0, search_ts_1.estimatedEntryCount)(primaryStore);
+                    }
+                    else {
+                        // Estimate from the real conditions only — drop the planner's synthetic `sort`
+                        // pseudo-condition, which otherwise contributes a bogus (entryCount/2) cardinality.
+                        const est = (0, search_ts_1.estimateCondition)(_a)({
+                            conditions: conditions.filter((c) => c.comparator !== 'sort'),
+                            operator: operator ? String(operator).toLowerCase() : 'and',
+                        });
+                        total = isFinite(est) ? Math.round(est) : null;
+                    }
+                    // For an estimate, never report a total below the last row actually returned — keeps the
+                    // Content-Range valid (start-end/total) when an estimate undershoots a non-empty page.
+                    // Exact totals are authoritative (and an empty page past the end must not be clamped up).
+                    if (!wantExact && total != null && page.length > 0 && total < offset + page.length) {
+                        total = offset + page.length;
+                    }
+                    page.recordCount = total;
+                    page.recordCountExact = wantExact && exact && !approximateResultSet;
+                    page.selectApplied = true;
+                    page.getColumns = getColumns;
+                    return page;
+                })();
+            }
             // apply any offset/limit after all the sorting and filtering
             if (target.offset || target.limit !== undefined)
-                results = results.slice(target.offset, target.limit !== undefined ? (target.offset || 0) + target.limit : undefined);
+                results = results.slice(offset, end);
             results.onDone = () => {
                 results.onDone = null; // ensure that it isn't called twice
                 txn.doneReadTxn();
@@ -3701,12 +4400,12 @@ function makeTable(options) {
                                 if (resolver.directReturn)
                                     return callback(value, attribute_name);
                                 if (value && typeof value === 'object') {
-                                    const targetTable = resolver.definition?.tableClass || TableResource;
+                                    const targetTable = resolver.definition?.tableClass || _a;
                                     if (!transformCache)
                                         transformCache = {};
                                     // Use the target table's own read transaction; each table's readTxn is
                                     // scoped to its RocksDB column family and cannot read another table's store.
-                                    const targetReadTxn = targetTable === TableResource ? readTxn : targetTable._readTxnForContext(context);
+                                    const targetReadTxn = targetTable === _a ? readTxn : targetTable._readTxnForContext(context);
                                     const transform = transformCache[attribute_name] ||
                                         (transformCache[attribute_name] = targetTable.transformEntryForSelect(
                                         // if it is a simple string, there is no select for the next level,
@@ -3759,7 +4458,7 @@ function makeTable(options) {
                         else {
                             value = record[attribute_name];
                             if (value && typeof value === 'object' && attribute_name !== attribute) {
-                                const subTransform = TableResource.transformEntryForSelect(attribute.select || attribute, context, readTxn, null);
+                                const subTransform = _a.transformEntryForSelect(attribute.select || attribute, context, readTxn, null);
                                 // Plain JSON nested values: arrays project per-element so that
                                 // `select: [{ name: 'addresses', select: ['city'] }]` returns
                                 // `addresses: [{ city }, { city }]` rather than a single object.
@@ -3838,6 +4537,10 @@ function makeTable(options) {
             if (!auditStore)
                 throw new Error('Can not subscribe to a table without an audit log');
             if (!audit) {
+                // Turning auditing on is a schema write, and a branch's Table classes carry the base's
+                // logical name: without this a subscribe through a branched application would enable
+                // auditing on the live base table for every other consumer, with no DDL call involved.
+                _a.assertSchemaMutable('enable auditing for a subscription');
                 (0, databases_ts_1.table)({ table: tableName, database: databaseName, schemaDefined, attributes, audit: true });
             }
             const getFullRecord = !request.rawEvents;
@@ -3893,7 +4596,7 @@ function makeTable(options) {
                     return evaluateFilter(rowFilter, event.value, 'rowFilter');
                 }
                 : null;
-            const subscription = (0, transactionBroadcast_ts_1.addSubscription)(TableResource, thisId, function (id, auditRecord, localTime, beginTxn) {
+            const subscription = (0, transactionBroadcast_ts_1.addSubscription)(_a, thisId, function (id, auditRecord, txnLogKey, beginTxn) {
                 if (dropDuringReplay)
                     return;
                 try {
@@ -3920,8 +4623,7 @@ function makeTable(options) {
                         // been written, so are fresh in memory.
                         const entry = primaryStore.getEntry(id);
                         if (entry) {
-                            // staleness is a record-version comparison; auditRecord.version is the log key on RocksDB
-                            if (entry.version !== (auditRecord.recordVersion ?? auditRecord.version))
+                            if (entry.version !== auditRecord.version)
                                 return; // out of order event, with old update, don't send anything
                             value = entry.value;
                             type = entry.metadataFlags & exports.INVALIDATED ? 'invalidate' : value ? 'put' : 'delete';
@@ -3932,7 +4634,7 @@ function makeTable(options) {
                     }
                     const event = {
                         id,
-                        localTime,
+                        localTime: txnLogKey,
                         value,
                         version: auditRecord.version,
                         type,
@@ -4001,10 +4703,10 @@ function makeTable(options) {
                                     continue;
                                 const id = auditRecord.recordId;
                                 if (thisId == null || isDescendantId(thisId, id)) {
-                                    const value = auditRecord.getValue(primaryStore, getFullRecord, auditRecord.localTime);
+                                    const value = auditRecord.getValue(primaryStore, getFullRecord, auditRecord.txnLogKey);
                                     if (!send({
                                         id,
-                                        localTime: auditRecord.localTime,
+                                        localTime: auditRecord.txnLogKey,
                                         value,
                                         version: auditRecord.version,
                                         type: auditRecord.type,
@@ -4017,7 +4719,7 @@ function makeTable(options) {
                                             return;
                                     }
                                 }
-                                subscription.startTime = auditRecord.localTime ?? auditRecord.version; // update so we don't double send
+                                subscription.startTime = auditRecord.txnLogKey; // update so we don't double send
                             }
                         }
                         finally {
@@ -4051,10 +4753,10 @@ function makeTable(options) {
                                         logger_ts_1.logger.warn?.(`previousCount backfill on ${tableName} stopped after inspecting ${MAX_PREVIOUS_COUNT_SCAN} in-scope audit records without collecting ${request.previousCount} accepted event(s); returning ${history.length} instead`);
                                         break;
                                     }
-                                    const value = auditRecord.getValue(primaryStore, getFullRecord, auditRecord.localTime);
+                                    const value = auditRecord.getValue(primaryStore, getFullRecord, auditRecord.txnLogKey);
                                     const historyEntry = {
                                         id,
-                                        localTime: auditRecord.localTime,
+                                        localTime: auditRecord.txnLogKey,
                                         value,
                                         version: auditRecord.version,
                                         type: auditRecord.type,
@@ -4071,7 +4773,7 @@ function makeTable(options) {
                                 }
                             }
                             catch (error) {
-                                logger_ts_1.logger.error?.('Error getting history entry', auditRecord.localTime, error);
+                                logger_ts_1.logger.error?.('Error getting history entry', auditRecord.txnLogKey, error);
                             }
                         }
                         for (let i = history.length; i > 0;) {
@@ -4159,6 +4861,12 @@ function makeTable(options) {
                         logger_ts_1.logger.trace?.('re-retrieved record', localTime, this.#entry?.localTime);
                         localTime = entry?.localTime;
                     }
+                    let nodeId = entry?.nodeId;
+                    if (isRocksDB && entry) {
+                        const head = resolveAuditHead(thisId, entry.version, nodeId, entry.additionalAuditRefs);
+                        localTime = head.txnLogKey;
+                        nodeId = head.nodeId;
+                    }
                     logger_ts_1.logger.trace?.('Subscription from', startTime, 'from', thisId, localTime);
                     if (startTime < localTime) {
                         // start time specified, get the audit history for this record. Set startTime up
@@ -4169,7 +4877,6 @@ function makeTable(options) {
                         const history = [];
                         let inspected = 0;
                         let nextTime = localTime;
-                        let nodeId = entry?.nodeId;
                         do {
                             if (++recordsSinceYield >= REPLAY_YIELD_INTERVAL) {
                                 recordsSinceYield = 0;
@@ -4200,8 +4907,11 @@ function makeTable(options) {
                                     else if (!isActive())
                                         return;
                                 }
-                                nextTime = auditRecord.previousVersion;
-                                nodeId = auditRecord.previousNodeId;
+                                const previousHead = isRocksDB
+                                    ? resolveAuditHead(thisId, auditRecord.previousVersion, auditRecord.previousNodeId, auditRecord.previousAdditionalAuditRefs)
+                                    : { txnLogKey: auditRecord.previousVersion, nodeId: auditRecord.previousNodeId };
+                                nextTime = previousHead.txnLogKey;
+                                nodeId = previousHead.nodeId;
                             }
                             else
                                 break;
@@ -4396,6 +5106,7 @@ function makeTable(options) {
                 store: primaryStore,
                 entry: this.#entry,
                 nodeName: context?.nodeName,
+                recordVersion: options?.version,
                 validate: () => {
                     if (!context?.source) {
                         transaction.checkOverloaded();
@@ -4609,6 +5320,7 @@ function makeTable(options) {
             return this.#version;
         }
         static async addAttributes(attributesToAdd) {
+            _a.assertSchemaMutable('add attributes');
             const new_attributes = attributes.slice(0);
             for (const attribute of attributesToAdd) {
                 if (!attribute.name)
@@ -4624,9 +5336,10 @@ function makeTable(options) {
                 schemaDefined,
                 attributes: new_attributes,
             });
-            return TableResource.indexingOperation;
+            return _a.indexingOperation;
         }
         static async removeAttributes(names) {
+            _a.assertSchemaMutable('remove attributes');
             const new_attributes = attributes.filter((attribute) => !names.includes(attribute.name));
             (0, databases_ts_1.table)({
                 table: tableName,
@@ -4634,7 +5347,7 @@ function makeTable(options) {
                 schemaDefined,
                 attributes: new_attributes,
             });
-            return TableResource.indexingOperation;
+            return _a.indexingOperation;
         }
         /**
          * Get the size of the table in bytes (based on amount of pages stored in the database)
@@ -4647,6 +5360,10 @@ function makeTable(options) {
             const stats = primaryStore.getStats();
             return (stats.treeBranchPageCount + stats.treeLeafPageCount + stats.overflowPages) * stats.pageSize;
         }
+        /** Sizes of this table's durable record-structure dictionaries. */
+        static getStructureCounts() {
+            return primaryStore.encoder?.getStructureCounts?.();
+        }
         static getAuditSize() {
             const stats = auditStore?.getStats();
             return (stats &&
@@ -4665,7 +5382,7 @@ function makeTable(options) {
             // iterate through the metadata entries to exclude their count and exclude the deletion counts
             const exactCount = options?.exactCount;
             const TIME_LIMIT = options?.timeLimit ?? 1000 / 2; // one second time limit, enforced by seeing if we are halfway through at 500ms
-            const start = performance.now();
+            const start = node_perf_hooks_1.performance.now();
             // `entryCount` (the exact key count) is only needed once the scan blows the time budget --
             // to decide whether to estimate and as the extrapolation base. On RocksDB it is a full
             // key-only scan, so we defer it: tables that finish within budget (the common case) and
@@ -4682,7 +5399,7 @@ function makeTable(options) {
                     recordCount++;
                 entriesScanned++;
                 await rest();
-                if (!exactCount && !completeForExact && performance.now() - start > TIME_LIMIT) {
+                if (!exactCount && !completeForExact && node_perf_hooks_1.performance.now() - start > TIME_LIMIT) {
                     if (!counted) {
                         counted = true;
                         entryCount = isRocksDB
@@ -4806,7 +5523,7 @@ function makeTable(options) {
                 const computed = attribute.computed;
                 // Register the default embedder unless an author override is set. Sits outside
                 // the resolver chain below so `@embed` fields still flow through auto-HNSW indexing.
-                if (attribute.embed && !TableResource.userSetEmbedders.has(attribute.name)) {
+                if (attribute.embed && !_a.userSetEmbedders.has(attribute.name)) {
                     this.userEmbedders[attribute.name] = (0, embedHook_ts_1.createDefaultEmbedder)(attribute.embed);
                 }
                 if (relationship) {
@@ -4872,7 +5589,7 @@ function makeTable(options) {
                                     const options = { transaction: txnForContext(context).getReadTxn() };
                                     const results = normalizedIds.map((id) => {
                                         const value = store[method](id, options);
-                                        if (TableResource.loadAsInstance === false)
+                                        if (_a.loadAsInstance === false)
                                             freezeRecord(returnEntry ? value?.value : value);
                                         return value;
                                     });
@@ -4881,7 +5598,7 @@ function makeTable(options) {
                                 const value = definition.tableClass.primaryStore[returnEntry ? 'getEntry' : 'getSync'](ids, {
                                     transaction: txnForContext(context).getReadTxn(),
                                 });
-                                if (TableResource.loadAsInstance === false)
+                                if (_a.loadAsInstance === false)
                                     freezeRecord(returnEntry ? value?.value : value);
                                 return value;
                             };
@@ -5036,30 +5753,85 @@ function makeTable(options) {
             this.userSetEmbedders.add(attribute_name);
         }
         static async deleteHistory(endTime = 0, cleanupDeletedRecords = false) {
-            let completion;
+            const maxConcurrentRemovals = isRocksDB ? MAX_CONCURRENT_HISTORY_REMOVALS : MAX_CONCURRENT_LMDB_HISTORY_REMOVALS;
+            const inFlightRemovals = new Set();
+            const removalSlotWaiters = [];
+            let removalsAttempted = 0;
+            let removalsSucceeded = 0;
+            let firstRemovalError;
+            function startRemoval(remove, errorMessage, onSuccess) {
+                removalsAttempted++;
+                const removal = new Promise((resolve) => resolve(remove()))
+                    .then(() => {
+                    removalsSucceeded++;
+                    onSuccess?.();
+                }, (error) => {
+                    // capture before logging: a throwing logger must not cost us the error we may rethrow
+                    if (firstRemovalError === undefined)
+                        firstRemovalError = error;
+                    harper_logger_ts_1.default.warn(errorMessage, error);
+                })
+                    .catch(() => undefined)
+                    .finally(() => {
+                    inFlightRemovals.delete(removal);
+                    removalSlotWaiters.shift()?.();
+                });
+                inFlightRemovals.add(removal);
+            }
+            function queueRemoval(remove, errorMessage, onSuccess) {
+                if (inFlightRemovals.size >= maxConcurrentRemovals) {
+                    return new Promise((resolve) => {
+                        removalSlotWaiters.push(resolve);
+                    }).then(() => startRemoval(remove, errorMessage, onSuccess));
+                }
+                startRemoval(remove, errorMessage, onSuccess);
+            }
+            const drainRemovals = () => Promise.all(inFlightRemovals);
             let entriesDeleted = 0;
-            for (const auditRecord of auditStore.getRange({
-                start: 0,
-                end: endTime,
-            })) {
-                await rest(); // yield to other async operations
-                if (auditRecord.tableId !== tableId)
-                    continue;
-                completion = (0, auditStore_ts_1.removeAuditEntry)(auditStore, auditRecord);
-                entriesDeleted++;
+            try {
+                for (const auditRecord of auditStore.getRange({
+                    start: 1, // must not be zero; see getHistory below for why
+                    end: endTime,
+                })) {
+                    await rest(); // yield to other async operations
+                    if (auditRecord.tableId !== tableId)
+                        continue;
+                    const backpressure = queueRemoval(() => (0, auditStore_ts_1.removeAuditEntry)(auditStore, auditRecord), 'Error removing audit entry during deleteHistory', () => {
+                        entriesDeleted++;
+                    });
+                    if (backpressure)
+                        await backpressure;
+                }
+            }
+            finally {
+                await drainRemovals();
             }
             if (cleanupDeletedRecords) {
                 // this is separate procedure we can do if the records are not being cleaned up by the audit log. This shouldn't
                 // ever happen, but if there are cleanup failures for some reason, we can run this to clean up the records
-                for (const entry of primaryStore.getRange({ start: 0, versions: true })) {
-                    const { value, localTime } = entry;
-                    await rest(); // yield to other async operations
-                    if (value === null && localTime < endTime) {
-                        completion = (0, RecordEncoder_ts_1.removeEntry)(primaryStore, entry);
+                try {
+                    for (const entry of primaryStore.getRange({ start: 0, versions: true })) {
+                        const { key, value, localTime, version } = entry;
+                        await rest(); // yield to other async operations
+                        const auditTime = isRocksDB && version != null
+                            ? resolveAuditHead(key, version, entry.nodeId, entry.additionalAuditRefs).txnLogKey
+                            : localTime;
+                        if (value === null && version != null && auditTime < endTime) {
+                            const backpressure = queueRemoval(() => primaryStore.remove(key, version), 'Error removing deleted record during deleteHistory');
+                            if (backpressure)
+                                await backpressure;
+                        }
                     }
                 }
+                finally {
+                    await drainRemovals();
+                }
+            }
+            if (removalsAttempted > 0 && removalsSucceeded === 0) {
+                // zero progress must not report the same success as "nothing was eligible" (see DESIGN.md);
+                // partial failures stay best-effort, logged and excluded from the returned count
+                throw firstRemovalError ?? new Error('Every removal attempted during deleteHistory failed');
             }
-            await completion;
             return entriesDeleted;
         }
         static async *getHistory(startTime = 0, endTime = Infinity) {
@@ -5072,10 +5844,11 @@ function makeTable(options) {
                     continue;
                 yield {
                     id: auditRecord.recordId,
-                    localTime: auditRecord.version,
+                    // Compatibility-facing LMDB history has always reported/grouped by record version.
+                    localTime: isRocksDB ? auditRecord.txnLogKey : auditRecord.version,
                     version: auditRecord.version,
                     type: auditRecord.type,
-                    value: auditRecord.getValue(primaryStore, true, auditRecord.version),
+                    value: auditRecord.getValue(primaryStore, true, auditRecord.txnLogKey),
                     user: auditRecord.user,
                     operation: auditRecord.originatingOperation,
                 };
@@ -5088,7 +5861,9 @@ function makeTable(options) {
             const entry = primaryStore.getEntry(id);
             if (!entry)
                 return history;
-            let nextVersion = entry.localTime;
+            let nextVersion = isRocksDB
+                ? resolveAuditHead(id, entry.version, entry.nodeId, entry.additionalAuditRefs).txnLogKey
+                : entry.localTime;
             if (!nextVersion)
                 throw new Error('The entry does not have a local audit time');
             const count = 0;
@@ -5102,17 +5877,20 @@ function makeTable(options) {
                     if (auditRecord.tableId === tableId && (0, ordered_binary_1.compareKeys)(auditRecord.recordId, id) === 0) {
                         history.splice(insertionPoint, 0, {
                             id: auditRecord.recordId,
-                            localTime: auditRecord.version,
+                            localTime: isRocksDB ? auditRecord.txnLogKey : auditRecord.version,
                             version: auditRecord.version,
                             type: auditRecord.type,
-                            // reconstruct each entry's record image as of its own version, not the audit
+                            // reconstruct each entry's record image as of its own log position, not the audit
                             // window boundary (nextVersion), matching getHistory (issue #1330)
-                            value: auditRecord.getValue(primaryStore, true, auditRecord.version),
+                            value: auditRecord.getValue(primaryStore, true, auditRecord.txnLogKey),
                             user: auditRecord.user,
                             operation: auditRecord.originatingOperation,
                         });
-                        if (auditRecord.previousVersion > highestPreviousVersion && auditRecord.previousVersion < start) {
-                            highestPreviousVersion = auditRecord.previousVersion;
+                        const previousVersion = isRocksDB
+                            ? resolveAuditHead(id, auditRecord.previousVersion, auditRecord.previousNodeId, auditRecord.previousAdditionalAuditRefs).txnLogKey
+                            : auditRecord.previousVersion;
+                        if (previousVersion > highestPreviousVersion && previousVersion < start) {
+                            highestPreviousVersion = previousVersion;
                         }
                     }
                 }
@@ -5131,13 +5909,20 @@ function makeTable(options) {
             }
             return Promise.all(promises);
         }
+        /** Release everything makeTable() registered process-wide; the class must not be used afterwards. */
         static cleanup() {
+            disposed = true;
+            clearTimeout(cleanupTimer);
+            settlePendingCleanup();
+            clearInterval(recordExpirationInterval);
             deleteCallbackHandle?.remove();
+            (0, storageReclamation_ts_1.removeStorageReclamationHandler)(primaryStore.path, reclamationHandler);
         }
         static _readTxnForContext(context) {
             return txnForContext(context).getReadTxn();
         }
     }
+    _a = TableResource;
     const throttledCallToSource = (0, throttle_ts_1.throttle)(async (source, id, sourceContext, existingEntry) => {
         // call the data source if it exists and will fulfill our request for data
         if (source && source.get && (!source.get.reliesOnPrototype || source.prototype.get)) {
@@ -5151,11 +5936,17 @@ function makeTable(options) {
     }, () => {
         throw new hdbError_ts_1.ServerError('Service unavailable, exceeded request queue limit for resolving cache record', 503);
     });
-    TableResource.updatedAttributes(); // on creation, update accessors as well
-    if (expirationMs)
-        TableResource.setTTLExpiration(expirationMs / 1000);
-    if (expiresAtProperty)
-        runRecordExpirationEviction();
+    try {
+        TableResource.updatedAttributes(); // on creation, update accessors as well
+        if (expirationMs)
+            TableResource.setTTLExpiration(expirationMs / 1000);
+        if (expiresAtProperty)
+            runRecordExpirationEviction();
+    }
+    catch (error) {
+        TableResource.cleanup();
+        throw error;
+    }
     return TableResource;
     function updateIndices(id, existingRecord, record, options) {
         let hasChanges;
@@ -5582,6 +6373,22 @@ function makeTable(options) {
             return transaction;
         }
     }
+    /**
+     * Detach an unsaved TransactionWrite that a scoped lock() eagerly staged (see #reloadLocked)
+     * once its handle upgrades to hold: hold staging is deferred and explicit-save-only, so a
+     * dangling scoped write would otherwise auto-commit at the transaction sweep and clobber
+     * whatever the hold write lands. Marking it .dropped lets a later save() on the instance that
+     * owns it (checked via #savingOperation === this write) fall through to the hold branch
+     * instead of resolving a detached, dead reference.
+     */
+    function detachScopedUpgradeWrite(link, keyId, handle) {
+        for (const write of link.writes) {
+            if (write && !write.saved && write.lockHandle === handle && (0, DatabaseTransaction_ts_1.writeKeyId)(write.key) === keyId) {
+                write.dropped = true;
+                link.detachWrite(write);
+            }
+        }
+    }
     function getAttributeValue(entry, attribute_name, context, sort) {
         if (!entry) {
             return;
@@ -5699,6 +6506,10 @@ function makeTable(options) {
     async function getFromSource(source, id, existingEntry, context, target) {
         const metadataFlags = existingEntry?.metadataFlags;
         const existingVersion = existingEntry?.version;
+        const existingRecord = existingEntry?.value;
+        const inheritedTimestamp = context?.timestamp || context?.transaction?.timestamp;
+        const sourceTimestamp = inheritedTimestamp ||
+            (isRocksDB ? primaryStore.getMonotonicTimestamp() : (0, commonUtility_ts_1.getNextMonotonicTime)());
         let whenResolved, timer;
         // We start by locking the record so that there is only one resolution happening at once;
         // if there is already a resolution in process, we want to use the results of that resolution
@@ -5733,10 +6544,8 @@ function makeTable(options) {
         }
         // lock acquired — this request will actually load from source
         setLoadedFromSource(target, true);
-        const existingRecord = existingEntry?.value;
         // it is important to remember that this is _NOT_ part of the current transaction; nothing is changing
-        // with the canonical data, we are simply fulfilling our local copy of the canonical data, but still don't
-        // want a timestamp later than the current transaction
+        // with the canonical data, we are simply fulfilling our local copy of the canonical data.
         // we create a new context for the source, we want to determine the timestamp and don't want to
         // attribute this to the current user
         const sourceContext = {
@@ -5771,15 +6580,36 @@ function makeTable(options) {
             // belt to that suspenders, at the cost of a bounded wait on a merely slow source
             // before the drain's fail-closed timeout below.
             const commitPromise = (0, transaction_ts_1.transaction)(sourceContext, async (_txn) => {
-                const start = performance.now();
-                let updatedRecord;
+                const start = node_perf_hooks_1.performance.now();
+                let updatedRecord, assignCreatedTime, sourceVersion;
                 let hasChanges, invalidated;
                 try {
                     updatedRecord = await throttledCallToSource(source, id, sourceContext, existingEntry);
                     invalidated = metadataFlags & exports.INVALIDATED;
-                    let version = sourceContext.lastModified || (invalidated && existingVersion);
-                    hasChanges = invalidated || version > existingVersion || !existingRecord;
-                    const resolveDuration = performance.now() - start;
+                    const reportedVersion = sourceContext.lastModified;
+                    const validReportedVersion = typeof reportedVersion === 'number' &&
+                        Number.isFinite(reportedVersion) &&
+                        reportedVersion > 0 &&
+                        reportedVersion <= MAX_DATE_TIMESTAMP;
+                    if (validReportedVersion) {
+                        // A record version is also this node's ordering token (precedesExistingVersion), so a
+                        // source-reported version ahead of local time would make every subsequent local write look
+                        // out-of-order and be discarded until wall-clock caught up — freezing the row. Honor what
+                        // the source reports, but never beyond now.
+                        const versionCeiling = Math.max(sourceTimestamp, Date.now());
+                        sourceVersion = Math.min(reportedVersion, versionCeiling);
+                        if (sourceVersion !== reportedVersion) {
+                            logger_ts_1.logger.trace?.(`Capping future source version for ${tableName} id ${id}: ${reportedVersion} -> ${sourceVersion}`);
+                            if (!warnedFutureSourceVersion) {
+                                warnedFutureSourceVersion = true;
+                                logger_ts_1.logger.warn?.(`The source for ${tableName} reported a lastModified ahead of local time (${new Date(reportedVersion).toISOString()}) for id ${id}; capping cached record versions at local time`);
+                            }
+                        }
+                    }
+                    else
+                        sourceVersion = sourceTimestamp;
+                    hasChanges = invalidated || (validReportedVersion && reportedVersion > existingVersion) || !existingRecord;
+                    const resolveDuration = node_perf_hooks_1.performance.now() - start;
                     (0, write_ts_1.recordAction)(resolveDuration, 'cache-resolution', tableName, null, 'success');
                     if (responseHeaders)
                         (0, Headers_ts_1.appendHeader)(responseHeaders, 'Server-Timing', `cache-resolve;dur=${resolveDuration.toFixed(2)}`, true);
@@ -5794,7 +6624,7 @@ function makeTable(options) {
                             if (status === 304) {
                                 // revalidation of our current cached record
                                 updatedRecord = existingRecord;
-                                version = existingVersion;
+                                sourceVersion = existingVersion;
                             }
                             else if (!CACHEABLE_STATUS_CODES.has(status)) {
                                 // non-cacheable status - propagate to client without caching
@@ -5872,10 +6702,14 @@ function makeTable(options) {
                         if (primaryKey && updatedRecord[primaryKey] !== id)
                             updatedRecord[primaryKey] = id;
                     }
+                    assignCreatedTime = createdTimeProperty && updatedRecord?.[createdTimeProperty.name] == null;
                     resolved = true;
+                    const resolvedVersion = isRocksDB && updatedRecord && existingVersion != null
+                        ? Math.max(sourceVersion, existingVersion)
+                        : sourceVersion;
                     const resolvedEntry = {
                         key: id,
-                        version,
+                        version: resolvedVersion,
                         value: updatedRecord,
                         expiresAt: sourceContext.expiresAt,
                         metadataFlags: 0,
@@ -5914,7 +6748,7 @@ function makeTable(options) {
                     }
                     else
                         reject(error);
-                    const resolveDuration = performance.now() - start;
+                    const resolveDuration = node_perf_hooks_1.performance.now() - start;
                     (0, write_ts_1.recordAction)(resolveDuration, 'cache-resolution', tableName, null, 'fail');
                     if (responseHeaders)
                         (0, Headers_ts_1.appendHeader)(responseHeaders, 'Server-Timing', `cache-resolve;dur=${resolveDuration.toFixed(2)}`, true);
@@ -5933,16 +6767,28 @@ function makeTable(options) {
                 const sourceWrite = {
                     key: id,
                     store: primaryStore,
-                    entry: existingEntry,
+                    entry: undefined,
                     nodeName: 'source',
-                    commit: (txnTime, existingEntry, _retry, transaction) => {
+                    commit: (_txnTime, existingEntry, _retry, transaction) => {
                         sourceWrite.skipped = false; // reset on each retry; cleanup happens after commit if still true
-                        if (existingEntry?.version !== existingVersion) {
-                            // don't do anything if the version has changed
+                        const racedVersion = existingEntry?.version;
+                        // A first fill may replace a record that raced it only when its candidate version strictly
+                        // orders after that record. The comparison has to be replica-independent, so a tie leaves the
+                        // raced record in place: precedesExistingVersion() would break the tie with *this* node's
+                        // name, and a fill from a shared source has no node identity of its own, so two replicas
+                        // resolving the same tie could keep different values at the same version.
+                        const replacesRacedRecord = racedVersion == null || sourceVersion > racedVersion;
+                        if (racedVersion !== existingVersion &&
+                            // Revalidations retain exact-CAS semantics; first fills use deterministic ordering.
+                            (existingVersion != null || !updatedRecord || !replacesRacedRecord)) {
+                            logger_ts_1.logger.trace?.(`Discarding resolved record from source with id: ${id}, source version: ${sourceVersion}, current version: ${racedVersion}`);
                             sourceWrite.skipped = true;
                             return;
                         }
-                        updateIndices(id, existingRecord, updatedRecord, transaction && { transaction });
+                        const currentRecord = existingEntry?.value;
+                        const recordVersion = isRocksDB && racedVersion != null ? Math.max(sourceVersion, racedVersion) : sourceVersion;
+                        const txnLogKey = isRocksDB ? transaction?.getTimestamp?.() : recordVersion;
+                        updateIndices(id, currentRecord, updatedRecord, transaction && { transaction });
                         if (updatedRecord) {
                             if (existingEntry) {
                                 context.previousResidency = TableResource.getResidencyRecord(existingEntry.residencyId);
@@ -5953,23 +6799,23 @@ function makeTable(options) {
                             if (updatedTimeProperty) {
                                 updatedRecord[updatedTimeProperty.name] =
                                     updatedTimeProperty.type === 'Date'
-                                        ? new Date(txnTime)
+                                        ? new Date(recordVersion)
                                         : updatedTimeProperty.type === 'String'
-                                            ? new Date(txnTime).toISOString()
-                                            : txnTime;
+                                            ? new Date(recordVersion).toISOString()
+                                            : recordVersion;
                             }
-                            if (createdTimeProperty && updatedRecord[createdTimeProperty.name] == null) {
-                                const existingCreatedTime = existingEntry?.value?.[createdTimeProperty.name];
+                            if (assignCreatedTime) {
+                                const existingCreatedTime = currentRecord?.[createdTimeProperty.name];
                                 if (existingCreatedTime != null) {
                                     updatedRecord[createdTimeProperty.name] = existingCreatedTime;
                                 }
                                 else {
                                     updatedRecord[createdTimeProperty.name] =
                                         createdTimeProperty.type === 'Date'
-                                            ? new Date(txnTime)
+                                            ? new Date(recordVersion)
                                             : createdTimeProperty.type === 'String'
-                                                ? new Date(txnTime).toISOString()
-                                                : txnTime;
+                                                ? new Date(recordVersion).toISOString()
+                                                : recordVersion;
                                 }
                             }
                             const residency = residencyFromFunction(TableResource.getResidency(updatedRecord, context));
@@ -6002,23 +6848,33 @@ function makeTable(options) {
                                 }
                                 residencyId = getResidencyId(residency);
                             }
-                            logger_ts_1.logger.trace?.(`Writing resolved record from source with id: ${id}, timestamp: ${new Date(txnTime).toISOString()}`);
+                            logger_ts_1.logger.trace?.(`Writing resolved record from source with id: ${id}, timestamp: ${new Date(recordVersion).toISOString()}`);
                             // TODO: We are doing a double check for ifVersion that should probably be cleaned out
-                            updateRecord(id, updatedRecord, existingEntry, txnTime, omitLocalRecord ? exports.INVALIDATED : 0, (audit && (hasChanges || omitLocalRecord)) || null, {
+                            const writeAudit = (audit && (hasChanges || omitLocalRecord)) || null;
+                            updateRecord(id, updatedRecord, existingEntry, recordVersion, omitLocalRecord ? exports.INVALIDATED : 0, writeAudit, {
                                 user: sourceContext?.user,
                                 expiresAt: sourceContext.expiresAt,
                                 residencyId,
                                 transaction,
                                 tableToTrack: tableName,
+                                additionalAuditRefs: writeAudit && txnLogKey !== recordVersion ? [{ version: txnLogKey, nodeId: 0 }] : undefined,
                             }, 'put', Boolean(invalidated), auditRecord);
                             // arm the eviction scanner, mirroring the .put() path
                             if (sourceContext.expiresAt)
                                 scheduleCleanup();
                         }
                         else if (existingEntry) {
-                            logger_ts_1.logger.trace?.(`Deleting resolved record from source with id: ${id}, timestamp: ${new Date(txnTime).toISOString()}`);
+                            logger_ts_1.logger.trace?.(`Deleting resolved record from source with id: ${id}, timestamp: ${new Date(recordVersion).toISOString()}`);
                             if (audit || trackDeletes) {
-                                updateRecord(id, null, existingEntry, txnTime, 0, (audit && hasChanges) || null, { user: sourceContext?.user, transaction, tableToTrack: tableName }, 'delete', Boolean(invalidated));
+                                updateRecord(id, null, existingEntry, recordVersion, 0, (audit && hasChanges) || null, {
+                                    user: sourceContext?.user,
+                                    transaction,
+                                    tableToTrack: tableName,
+                                    recordVersion,
+                                    additionalAuditRefs: audit && hasChanges && txnLogKey !== recordVersion
+                                        ? [{ version: txnLogKey, nodeId: 0 }]
+                                        : undefined,
+                                }, 'delete', Boolean(invalidated));
                             }
                             else {
                                 (0, RecordEncoder_ts_1.removeEntry)(primaryStore, existingEntry, existingVersion);
@@ -6178,7 +7034,15 @@ function makeTable(options) {
             },
         };
     }
+    function settlePendingCleanup() {
+        for (const resolve of pendingCleanupResolvers)
+            resolve();
+        pendingCleanupResolvers.clear();
+    }
     function scheduleCleanup(priority) {
+        // a reclamation run may still hold this class's handler after cleanup(); a promise here would never settle
+        if (disposed)
+            return;
         let runImmediately = false;
         if (priority) {
             // run immediately if there is a big increase in priority
@@ -6194,9 +7058,19 @@ function makeTable(options) {
             // run on the last thread so we aren't overloading lower-numbered threads
             if (cleanupTimer)
                 clearTimeout(cleanupTimer);
-            if (!cleanupInterval)
+            if (!cleanupInterval) {
+                // no replacement pass is being scheduled, so nothing is left to settle a superseded one
+                settlePendingCleanup();
                 return;
+            }
+            // This pass adopts the awaiters of the pass whose timer it just cleared: they settle when
+            // this pass's scan completes, so a reclamation run is never told the storage was reclaimed
+            // before any scan ran. It has to run now, though — that run blocks its whole path on the
+            // promise, and the replacement's own slot can be a full interval out.
+            if (pendingCleanupResolvers.size > 0)
+                runImmediately = true;
             return new Promise((resolve) => {
+                pendingCleanupResolvers.add(resolve);
                 const startOfYear = new Date();
                 startOfYear.setMonth(0);
                 startOfYear.setDate(1);
@@ -6209,6 +7083,8 @@ function makeTable(options) {
                     ? Date.now()
                     : Math.ceil((Date.now() - startOfYear.getTime()) / nextInterval) * nextInterval + startOfYear.getTime();
                 const startNextTimer = (nextScheduled) => {
+                    if (disposed)
+                        return;
                     logger_ts_1.logger.trace?.(`Scheduled next cleanup scan at ${new Date(nextScheduled)}`);
                     // noinspection JSVoidFunctionReturnValueUsed
                     cleanupTimer = setTimeout(() => (lastEvictionCompletion = lastEvictionCompletion.then(async () => {
@@ -6217,8 +7093,11 @@ function makeTable(options) {
                         const rootStore = primaryStore.rootStore;
                         if (rootStore.status !== 'open') {
                             clearTimeout(cleanupTimer);
+                            settlePendingCleanup();
                             return;
                         }
+                        // snapshot: an awaiter that arrives during this scan belongs to the pass that supersedes it
+                        const settling = [...pendingCleanupResolvers];
                         const MAX_CLEANUP_CONCURRENCY = 50;
                         const outstandingCleanupOperations = new Array(MAX_CLEANUP_CONCURRENCY);
                         let cleanupIndex = 0;
@@ -6298,7 +7177,10 @@ function makeTable(options) {
                         catch (error) {
                             logger_ts_1.logger.warn?.(`Error in cleanup scan for ${tableName}:`, error);
                         }
-                        resolve(undefined);
+                        for (const settle of settling) {
+                            pendingCleanupResolvers.delete(settle);
+                            settle();
+                        }
                         cleanupPriority = 0; // reset the priority
                     })), Math.min(nextScheduled - Date.now(), hdbTerms_ts_1.MAX_SET_TIMEOUT_MS) // make sure it can fit in 32-bit signed number
                     ).unref(); // don't let this prevent closing the thread
@@ -6309,17 +7191,17 @@ function makeTable(options) {
     }
     function addDeleteRemoval() {
         deleteCallbackHandle = auditStore?.addDeleteRemovalCallback(tableId, primaryStore, (id, version) => {
-            primaryStore.remove(id, version);
+            return primaryStore.remove(id, version);
         });
     }
     function runRecordExpirationEviction() {
         // Periodically evict expired records, searching for records who expiresAt timestamp is before now
         if ((0, manageThreads_js_1.getWorkerIndex)() === 0) {
             // we want to run the pruning of expired records on only one thread so we don't have conflicts in evicting
-            setInterval(async () => {
+            recordExpirationInterval = setInterval(async () => {
                 // go through each database and table and then search for expired entries
                 // find any entries that are set to expire before now
-                if (runningRecordExpiration)
+                if (disposed || runningRecordExpiration)
                     return;
                 runningRecordExpiration = true;
                 try {