@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/resources/auditStore.js

@@ -33,12 +33,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Decoder = exports.LOCAL_ONLY = exports.HAS_ADDITIONAL_AUDIT_REFS = exports.HAS_BLOBS = exports.HAS_EXPIRATION_EXTENDED_TYPE = exports.HAS_ORIGINATING_OPERATION = exports.HAS_PREVIOUS_RESIDENCY_ID = exports.HAS_CURRENT_RESIDENCY_ID = exports.REMOTE_SEQUENCE_UPDATE = exports.ACTION_64_BIT = exports.ACTION_32_BIT = exports.auditRetention = exports.AUDIT_STORE_OPTIONS = exports.transactionKeyEncoder = exports.ENTRY_DATAVIEW = void 0;
+exports.Decoder = exports.LOCAL_ONLY = exports.HAS_ADDITIONAL_AUDIT_REFS = exports.HAS_BLOBS = exports.HAS_EXPIRATION_EXTENDED_TYPE = exports.HAS_ORIGINATING_OPERATION = exports.HAS_PREVIOUS_RESIDENCY_ID = exports.HAS_CURRENT_RESIDENCY_ID = exports.LOCK_BARRIER = exports.LOCK_RELEASE = exports.REMOTE_SEQUENCE_UPDATE = exports.ACTION_64_BIT = exports.ACTION_32_BIT = exports.auditRetention = exports.AUDIT_STORE_OPTIONS = exports.transactionKeyEncoder = exports.ENTRY_DATAVIEW = void 0;
 exports.openAuditStore = openAuditStore;
+exports.isAuditEntryWrite = isAuditEntryWrite;
 exports.removeAuditEntry = removeAuditEntry;
 exports.getLastRemoved = getLastRemoved;
+exports.boundedAuditPruneEnd = boundedAuditPruneEnd;
+exports.raiseAuditFloor = raiseAuditFloor;
+exports.establishAuditFloor = establishAuditFloor;
+exports.getAuditFloor = getAuditFloor;
 exports.setAuditRetention = setAuditRetention;
 exports.purgeAgedLogs = purgeAgedLogs;
+exports.isLockControlType = isLockControlType;
 exports.createAuditEntry = createAuditEntry;
 exports.readAuditEntry = readAuditEntry;
 const ordered_binary_1 = require("ordered-binary");
@@ -53,6 +59,7 @@ const crdt_ts_1 = require("./crdt.js");
 const blob_ts_1 = require("./blob.js");
 const storageReclamation_ts_1 = require("../server/storageReclamation.js");
 const rocksdb_js_1 = require("@harperfast/rocksdb-js");
+const lmdb_1 = require("lmdb");
 const RocksTransactionLogStore_ts_1 = require("./RocksTransactionLogStore.js");
 const databases_ts_1 = require("./databases.js");
 /**
@@ -127,8 +134,40 @@ const MAX_CLEANUP_DELAY = 2 ** 31 - 1;
 // mint latch keyed per (table, type) so one entry type can't silence another's producer stack
 const warnedBodylessMints = new Set();
 const warnedBodylessTables = new Set();
+// legacy-format latches, mirroring the bodyless ones above: a range scan over millions of pre-#2247
+// entries must not turn a recovered read into a log flood. Recovery latches per table (the table is
+// known by then); an undecodable header has no table, so it latches once per process.
+const warnedRecoveredTables = new Set();
+let warnedUndecodableHeader = false;
+// keyed per (table, type) like warnedBodylessMints, so one entry type cannot silence another's stack
+const warnedPendingPreviousVersion = new Set();
 const FLOAT_TARGET = new Float64Array(1);
 const FLOAT_BUFFER = new Uint8Array(FLOAT_TARGET.buffer);
+/**
+ * Key of this database's audit retention floor — the staleness horizon `getAuditFloor` reports.
+ * Its *presence* is what marks the floor trustworthy, which is why it is not the `last-removed`
+ * marker above: that one is written after its removals and by only one of the five prune paths, so a
+ * value found there cannot be told apart from one carrying the write-ahead and monotonicity
+ * guarantees `raiseAuditFloor` provides. The two coexist deliberately and answer different
+ * questions.
+ */
+const AUDIT_FLOOR_KEY = Symbol.for('audit-floor');
+// The epoch `establishAuditFloor` stamped, never raised or removed. Its PRESENCE marks the floor as
+// unverified provenance — a guess bounded by what survived, blind to history a legacy prune removed
+// before tracking began — until a database generation (#2451) retires the mark. No comparison does:
+// a later prune certifies only what it removed, so `floor > bootstrap` says nothing about the older
+// gap. The value records how far the guess reached, for that repair. See `establishAuditFloor`.
+const AUDIT_FLOOR_BOOTSTRAP_KEY = Symbol.for('audit-floor-bootstrap');
+/**
+ * The floor's own eight bytes, deliberately NOT the FLOAT_TARGET/FLOAT_BUFFER pair the `last-removed`
+ * marker uses: decoding a floor writes into its buffer on every read, including the pre-check on each
+ * prune, while `updateLastRemoved` hands the shared buffer to an async `put` it has not yet consumed.
+ * Sharing them would let a floor read rewrite a marker still in flight.
+ */
+const FLOOR_TARGET = new Float64Array(1);
+const FLOOR_BUFFER = new Uint8Array(FLOOR_TARGET.buffer);
+/** No trustworthy floor: the highest possible floor, so every cursor compares as stale. */
+const AUDIT_FLOOR_UNKNOWN = Infinity;
 /** Last resort on a detached path: a failing log sink must not itself become an unhandled rejection. */
 function warnContained(message, error) {
     try {
@@ -160,13 +199,14 @@ function openAuditStore(rootStore) {
             if (options.values === false)
                 return superGetRange(options); // getKeys shouldn't be modified
             return superGetRange(options).map(({ key, value }) => {
-                value.key = value.localTime = key;
+                value.key = value.txnLogKey = key;
                 return value;
             });
         };
     }
     rootStore.auditStore = auditStore;
     auditStore.rootStore = rootStore;
+    establishAuditFloor(auditStore);
     auditStore.tableStores = [];
     const deleteCallbacks = [];
     auditStore.addDeleteRemovalCallback = function (tableId, table, callback) {
@@ -176,6 +216,8 @@ function openAuditStore(rootStore) {
         return {
             remove() {
                 delete deleteCallbacks[tableId];
+                if (auditStore.tableStores[tableId] === table)
+                    delete auditStore.tableStores[tableId];
             },
         };
     };
@@ -240,26 +282,40 @@ function openAuditStore(rootStore) {
                 let lastKey;
                 try {
                     if (isRocksAuditStore) {
-                        auditStore.rootStore.purgeLogs({
-                            before: Date.now() - exports.auditRetention / (1 + passCleanupPriority * passCleanupPriority),
-                        });
+                        const before = retentionCutoff(1 + passCleanupPriority * passCleanupPriority);
+                        raiseAuditFloor(auditStore, before);
+                        auditStore.rootStore.purgeLogs({ before });
                     }
                     else {
                         // Driven explicitly rather than with for-of: this loop suspends on the awaits below, and a
                         // close landing mid-pass closes the env under it. for-of calls next() before the body, so a
                         // check inside the body advances the cursor first — the guard has to precede every next().
+                        // remove up until the audit retention time, reducing audit retention time if cleanup is higher priority
+                        const end = retentionCutoff(1 + passCleanupPriority * passCleanupPriority);
+                        // Probe before raising, so an idle database does not write a floor transaction on every
+                        // pass forever. `end` is fixed and audit keys only move forward, so an empty probe means
+                        // the loop below finds nothing either.
                         const entries = auditStore
                             .getRange({
                             start: 1, // must not be zero or it will be interpreted as null and overlap with symbols in search
                             snapshot: false,
-                            end: Date.now() - exports.auditRetention / (1 + passCleanupPriority * passCleanupPriority), // remove up until the audit retention time, reducing audit retention time if cleanup is higher priority
+                            end,
                         })[Symbol.iterator]();
                         try {
+                            // Raised off the first eligible entry rather than a separate probe range: one cursor,
+                            // so a pass over an idle database writes no floor at all, and nothing else observing
+                            // this range sees an extra advance. Still strictly before any removal — see
+                            // raiseAuditFloor.
+                            let floorRaised = false;
                             while (!cleanupStopped && !storeClosing()) {
                                 const entry = entries.next();
                                 if (entry.done)
                                     break;
                                 const auditRecord = entry.value;
+                                if (!floorRaised) {
+                                    raiseAuditFloor(auditStore, end);
+                                    floorRaised = true;
+                                }
                                 try {
                                     // awaited so a rejection (not just a synchronous throw) is caught here instead of
                                     // escaping as an unhandled rejection once a later iteration's promise replaces this one
@@ -338,7 +394,7 @@ function openAuditStore(rootStore) {
                         // sites already restrict Rocks to the last worker
                         if (!cleanupStopped &&
                             !storeClosing() &&
-                            (!isRocksAuditStore || ((0, manageThreads_js_1.getWorkerIndex)() === (0, manageThreads_js_1.getWorkerCount)() - 1 && !pendingCleanupResolve))) {
+                            (!isRocksAuditStore || ((0, manageThreads_js_1.ownsStoreMaintenance)(rootStore.path) && !pendingCleanupResolve))) {
                             scheduleAuditCleanup();
                         }
                     }
@@ -374,7 +430,7 @@ function openAuditStore(rootStore) {
         pendingCleanupResolve = null;
         return lastCleanupResolution ?? Promise.resolve();
     };
-    if ((0, manageThreads_js_1.getWorkerIndex)() === (0, manageThreads_js_1.getWorkerCount)() - 1) {
+    if ((0, manageThreads_js_1.ownsStoreMaintenance)(rootStore.path)) {
         scheduleAuditCleanup();
     }
     if ((0, manageThreads_js_1.getWorkerIndex)() === 0 && !timestampErrored) {
@@ -388,16 +444,42 @@ function openAuditStore(rootStore) {
     }
     return auditStore;
 }
+/**
+ * Whether `entry` is the very write `auditRecord` describes. Write identity is (origin node, log key),
+ * never the record version: a version is legitimately non-unique, so a version match can name a
+ * different write and authorize destroying live state (a tombstone, a still-referenced blob).
+ *
+ * On LMDB this is exact — the audit-store key IS the record's `txnLogKey`. On RocksDB a record stores
+ * its version in the compatibility word and keeps a divergent log key in `additionalAuditRefs`.
+ * Absent identity answers false. The direction is deliberate: uncertainty retains.
+ */
+function isAuditEntryWrite(entry, auditRecord) {
+    if (entry == null || auditRecord.txnLogKey == null)
+        return false;
+    const auditNodeId = auditRecord.nodeId ?? 0;
+    return ((entry.localTime === auditRecord.txnLogKey && (entry.nodeId ?? 0) === auditNodeId) ||
+        entry.additionalAuditRefs?.some((ref) => ref.version === auditRecord.txnLogKey && (ref.nodeId ?? 0) === auditNodeId) === true);
+}
 function removeAuditEntry(auditStore, auditRecord) {
+    let tombstoneRemoval;
     if (auditRecord.type === 'delete') {
         // if this is a delete, we remove the delete entry from the primary table
-        // at the same time so the audit table the primary table are in sync, assuming the entry matches this audit record version
+        // at the same time so the audit table the primary table are in sync, assuming the entry is still
+        // the record state this audit record wrote
         const tableId = auditRecord.tableId;
         const primaryStore = auditStore.tableStores[auditRecord.tableId];
-        if (primaryStore?.getEntry(auditRecord.recordId)?.version === auditRecord.version)
-            auditStore.deleteCallbacks?.[tableId]?.(auditRecord.recordId, auditRecord.version);
+        const tombstone = primaryStore?.getEntry(auditRecord.recordId);
+        if (isAuditEntryWrite(tombstone, auditRecord))
+            // a failed tombstone removal doesn't mean the audit entry removal failed — only
+            // auditStore.remove() below decides this function's outcome
+            tombstoneRemoval = new Promise((resolve) => {
+                resolve(auditStore.deleteCallbacks?.[tableId]?.(auditRecord.recordId, tombstone.version));
+            }).catch((error) => {
+                harperLogger.warn('Error removing deleted record while removing its audit entry', error);
+            });
     }
-    return auditStore.remove(auditRecord.key);
+    const auditRemoval = auditStore.remove(auditRecord.key);
+    return tombstoneRemoval ? Promise.all([tombstoneRemoval, auditRemoval]).then(() => undefined) : auditRemoval;
 }
 function updateLastRemoved(auditStore, lastKey) {
     FLOAT_TARGET[0] = lastKey;
@@ -410,10 +492,371 @@ function getLastRemoved(auditStore) {
         return FLOAT_TARGET[0];
     }
 }
+/**
+ * Read the recorded floor, normalizing anything we cannot trust to AUDIT_FLOOR_UNKNOWN. Reads bytes
+ * rather than going through the store's value decoder, which would read these eight raw float bytes
+ * as an audit entry (and as msgpack on RocksDB). Callers get a number in every case: a NaN or
+ * negative floor read as a number would make one of `cursor >= floor` / `cursor < floor` report
+ * safety, and which of the two a consumer writes must not decide whether corrupt metadata fails
+ * closed.
+ */
+function decodeAuditFloor(stored) {
+    // RocksDB's getBinarySync is typed to also return a length; anything that is not exactly the
+    // eight bytes we write is metadata written by something else.
+    if (stored?.byteLength !== 8)
+        return AUDIT_FLOOR_UNKNOWN;
+    FLOOR_BUFFER.set(stored);
+    const floor = FLOOR_TARGET[0];
+    // `Object.is` for -0, which passes `>= 0` and would then read as a permissive zero — every cursor
+    // safe — from bytes with the sign bit set that nothing here writes. raiseAuditFloor rejects the
+    // same value as a cutoff; the read side has to agree or corrupt metadata fails open.
+    if (!Number.isFinite(floor) || floor < 0 || Object.is(floor, -0))
+        return AUDIT_FLOOR_UNKNOWN;
+    return floor;
+}
+/**
+ * Did the floor write land? A record has to be PRESENT, not merely decode to the value we wrote:
+ * `decodeAuditFloor(undefined)` is the unknown sentinel too, so on a floorless store — where the
+ * resolver writes exactly that sentinel — comparing decoded values alone reported a commit for a
+ * write that never happened, and the caller pruned with nothing persisted.
+ */
+function floorWriteLanded(stored, floor) {
+    return stored !== undefined && decodeAuditFloor(stored) === floor;
+}
+/** Own eight bytes per write: the store must never be handed a live view of the reused module buffer. */
+function encodeAuditFloor(floor) {
+    FLOOR_TARGET[0] = floor;
+    return FLOOR_BUFFER.slice();
+}
+/**
+ * Read-modify-write the floor under one store transaction. `resolve` receives the recorded floor
+ * (AUDIT_FLOOR_UNKNOWN when there is none) and returns the value to store, or undefined to leave it
+ * alone. `key` selects the record: the floor itself, or the bootstrap-provenance record beside it,
+ * which wants the same verified commit rather than a second write path.
+ *
+ * The transaction is the point: several paths advance the floor from different workers, and two
+ * unsynchronized read-then-writes can interleave so the lower cutoff lands last — a floor below
+ * history the higher one already removed. Read-only mode writes nothing, and prunes nothing.
+ */
+function updateAuditFloor(auditStore, resolve, key = AUDIT_FLOOR_KEY) {
+    // A legacy `auditPath` layout is opened as its own standalone LMDB root (databases.ts) and has no
+    // `.rootStore`, so it owns the transaction itself.
+    const transactionOwner = auditStore?.rootStore ?? auditStore;
+    if (!transactionOwner?.transactionSync)
+        throw new Error('Cannot record the audit retention floor: this database has no audit store');
+    // Both branches read their own write back and report `false` on mismatch, and the caller demands an
+    // explicit `true`. Both halves are load-bearing: a RocksDB transactionSync returns undefined for a
+    // swallowed abort rather than throwing (see RecordEncoder.saveStructures), and a write that fails
+    // without throwing is otherwise indistinguishable from one that landed — a caller pruning against a
+    // floor never recorded. Reads inside a write transaction see their own writes on both engines, so
+    // the read-back observes what commit will make durable.
+    const committed = auditStore instanceof RocksTransactionLogStore_ts_1.RocksTransactionLogStore
+        ? transactionOwner.transactionSync((txn) => {
+            const stored = txn.getBinarySync(key);
+            const floor = resolve(decodeAuditFloor(stored), stored !== undefined);
+            if (floor !== undefined) {
+                txn.putSync(key, (0, lmdb_1.asBinary)(encodeAuditFloor(floor)));
+                if (!floorWriteLanded(txn.getBinarySync(key), floor))
+                    return false;
+            }
+            return true;
+        }, { retryOnBusy: true })
+        : transactionOwner.transactionSync(() => {
+            const stored = auditStore.getBinary(key);
+            const floor = resolve(decodeAuditFloor(stored), stored !== undefined);
+            // `put` rather than `putSync`, and inside the transaction: lmdb's putSync is
+            // `put(...) === SYNC_PROMISE_SUCCESS`, so it drops whatever put returns, and a rejected put
+            // would leak with no owner. Within a write transaction put writes synchronously and returns
+            // an already-resolved sentinel, so the value is visible immediately either way and this
+            // only takes ownership of the failure case.
+            // asBinary: a legacy standalone audit root's encoder has no Uint8Array passthrough, so raw
+            // bytes would reach createAuditEntry and throw. This bypasses both encoders.
+            if (floor !== undefined) {
+                auditStore
+                    .put(key, (0, lmdb_1.asBinary)(encodeAuditFloor(floor)))
+                    ?.catch?.((error) => warnContained('Error writing the audit retention floor', error));
+                if (!floorWriteLanded(auditStore.getBinary(key), floor))
+                    return false;
+            }
+            return true;
+        });
+    if (committed !== true)
+        throw new Error('The audit retention floor transaction did not commit');
+}
+/**
+ * The bound a prune should use — and record — in place of an unbounded cutoff.
+ *
+ * `Infinity` is a legitimate thing for a caller to *mean* ("remove all of it") and a ruinous thing to
+ * store: it is the unknown sentinel, and the sentinel is absorbing. `raiseAuditFloor`'s lock-free
+ * pre-check skips any present record no cutoff exceeds, and `establishAuditFloor` skips any store that
+ * has one, so a floor at `Infinity` never comes back down — for the whole database, including sibling
+ * tables whose own history was never touched. One `deleteHistory(Infinity)` would otherwise retire the
+ * accessor for that database permanently (#2458).
+ *
+ * So bound it by what exists: strictly above the newest key currently in the log, and never below the
+ * clock. Nothing already written can escape that bound, and a caller that passes it as the prune's
+ * range end as well as its floor cannot remove anything the floor does not cover — which is what makes
+ * the write-ahead ordering hold without an infinite bound. An entry written *after* this returns is
+ * simply not history the call asked to remove.
+ *
+ * `Infinity` is only the extreme case. Any cutoff above this bound is the same defect by degree: a
+ * finite year-2286 bound (`Date.now() * 1000`, or a bare `'9999999999999'`) is equally unreachable
+ * and equally permanent, and entries written after the prune then land *below* the recorded floor,
+ * so the floor's promise — nothing after it was pruned — is false about history that is still there.
+ * Every cutoff is therefore clamped, not just the unbounded one.
+ *
+ * Non-numbers, NaN, negatives and `-0` fall through unchanged to `raiseAuditFloor`, which rejects
+ * them: the numeric ones are ordered keys the prune range would honor, not bounds anyone meant, and a
+ * non-number is guarded explicitly because `>` would otherwise coerce it into a bound the floor
+ * accepts. `cutoff > bound` rather than `Math.min` keeps NaN falling through too.
+ *
+ * On RocksDB `getKeys` is unimplemented and returns `[]`, so the bound reduces to `Date.now()`. A
+ * key above the clock therefore survives a purge that asked for it on that engine. That is the safe
+ * direction: the entry is kept and the floor stays honest, where the alternative removes history the
+ * floor does not cover.
+ */
+function boundedAuditPruneEnd(auditStore, cutoff) {
+    // Non-numbers pass through untouched for `raiseAuditFloor` to reject. `>` coerces, so without this
+    // a numeric STRING ('9999999999999', 'Infinity') or a future Date compares true against the bound
+    // and comes back AS the bound — a number raiseAuditFloor accepts — turning a type error into a
+    // whole-log prune.
+    if (typeof cutoff !== 'number')
+        return cutoff;
+    let bound = Date.now();
+    for (const newest of auditStore.getKeys({ reverse: true, limit: 1 })) {
+        if (typeof newest === 'number' && newest >= bound)
+            bound = newest + 1;
+    }
+    return cutoff > bound ? bound : cutoff;
+}
+/**
+ * Raise the floor to `cutoff`, the exclusive lower bound of the history a prune is about to make
+ * unreachable.
+ *
+ * **Call this before removing anything.** A floor written after the removal is lost if the process
+ * dies in between, and the surviving lower floor then certifies a cursor whose history is gone.
+ * Ordering it first also covers a prune that removes less than `cutoff` spans (a RocksDB purge with
+ * no whole droppable file, a retention pass stopping at MAX_DELETES_PER_CLEANUP): over-reporting costs
+ * one unnecessary resync, under-reporting loses data silently. The retention paths bound that
+ * over-report at the configured horizon (`Date.now() - auditRetention`, never below 0); the two
+ * operator-supplied bounds have no ceiling of their own and go through `boundedAuditPruneEnd` first,
+ * since a bound above everything reachable would be recorded verbatim and never come down.
+ *
+ * Throws if the floor cannot be persisted, which is why it is called first — the throw is what stops
+ * the prune from proceeding unrecorded. Never lowers the floor, so a narrower prune cannot undo a
+ * wider one, and a store whose floor is unknown stays unknown rather than being talked down to a
+ * cutoff that says nothing about the history it has already lost.
+ */
+function raiseAuditFloor(auditStore, cutoff) {
+    // Throw rather than no-op on a bound we will not store: audit keys are raw float64, so NaN and
+    // negatives (sign bit set) sort ABOVE every real timestamp and a range ending there spans the whole
+    // log — declining the floor silently would leave the prune deleting everything. `-0` and a non-number
+    // slip past a naive `< 0` check but are still ordered keys the range honors, so they are rejected too.
+    // Infinity is accepted and stored, decoding back to "unknown": every production caller clamps before
+    // reaching here (`boundedAuditPruneEnd`, the bridge's 400), so it stays reachable only for a caller
+    // that genuinely cannot bound its prune.
+    if (typeof cutoff !== 'number' || Number.isNaN(cutoff) || cutoff < 0 || Object.is(cutoff, -0))
+        throw new Error(`Invalid audit prune bound: ${String(cutoff)}`);
+    // Read-only mode does not exempt a prune from recording its floor; it means the prune must not
+    // happen. Only scheduleAuditCleanup and purgeAgedLogs check read-only themselves, so for
+    // deleteHistory and the whole-database purge this throw is the guard.
+    if ((0, databases_ts_1.isReadOnlyMode)())
+        throw new Error('Cannot record the audit retention floor: the database is read-only');
+    // Lock-free pre-check, getBinary-guarded so this optimization never decides the error a store with
+    // no audit store reports. Most calls cannot move the floor (a RocksDB reclamation pass on an idle
+    // database, a cutoff below one a wider prune already set), and taking the env write lock to
+    // discover that serializes every worker's boot and reclamation on it. The in-transaction guards
+    // below stay authoritative.
+    // Skips only the case it can prove is a no-op: a record that exists and already sits at or above
+    // the cutoff. An absent record is NOT decided here — the presence question is settled inside the
+    // transaction below, because another worker's establishAuditFloor can land between this read and
+    // that write.
+    if (auditStore?.getBinary) {
+        const stored = auditStore.getBinary(AUDIT_FLOOR_KEY);
+        if (stored !== undefined && !(cutoff > decodeAuditFloor(stored)))
+            return;
+    }
+    updateAuditFloor(auditStore, (current, recorded) => {
+        // Still no record, and we are about to prune: persist the unknown sentinel. Leaving no marker
+        // lets the next open stamp a FINITE epoch, and a prune bound above that epoch (a future
+        // `endTime`, or a rolled-back clock) then certifies cursors whose history this prune deleted.
+        // Unknown is the honest value, because a store with no record may have been pruned before this
+        // run too.
+        if (!recorded)
+            return AUDIT_FLOOR_UNKNOWN;
+        // A record appeared while we were getting here, so this is an ordinary monotonic raise: pruning
+        // to `cutoff` against a floor left below it is exactly the silent gap this function prevents.
+        return cutoff > current ? cutoff : undefined;
+    });
+}
+/**
+ * Give a database a trustworthy floor if it has none: the current time, as a one-time resync epoch.
+ *
+ * The floor record's *presence* is the trust marker, so a store without one is a store whose
+ * retention history we cannot account for. It may have been pruned by a version that recorded no
+ * floor; it may be the empty audit store an LMDB→RocksDB migration deliberately leaves behind
+ * (`bin/copyDb.ts` does not migrate it, so the records and their resumable cursors outlive their
+ * history); or it may be a database restored from a table-scoped backup taken without
+ * `include_audit`, which carries records but no audit DBI. Cursors from before this moment are
+ * therefore reported stale — not because we know they are, but because we do not know they are not.
+ *
+ * There is no "brand new store, use a permissive baseline" case: creating the audit DBI proves only
+ * that the DBI was absent, which the audit-less backup above also produces. Being conservative on a
+ * genuinely new database costs nothing, since its entries are all written after this instant.
+ *
+ * In read-only mode nothing is written and the floor stays unknown — the fail-closed answer for a
+ * process that cannot record what it does not know.
+ *
+ * **The epoch is also recorded under its own key, so this bootstrap is repairable.** The epoch is a
+ * guess bounded by surviving state, and surviving state cannot see history a selective prune already
+ * removed (see the clock note below). The record marks the store as one that carried a guess, and
+ * preserves the value guessed — the two facts a later release needs to raise such a floor to
+ * something it can stand behind. See "Audit retention floor" in DESIGN.md for the full reading.
+ *
+ * **The mark is the signal, not a comparison against the floor.** A store carrying this record has an
+ * unverified pre-tracking window for as long as it exists, however far the floor has since moved: a
+ * prune raising the floor above the epoch certifies only what that prune removed, and says nothing
+ * about history removed before tracking began — which may sit above the epoch, since that is exactly
+ * the case the guess cannot see. Retiring the mark takes a database generation (harper#2451), not a
+ * floor that has climbed past it.
+ *
+ * Ordering. The provenance record is written **first**, so a crash between the two writes leaves a
+ * record with no floor — which the next open retries, since the early return above tests the floor.
+ * The epoch actually stamped is always read back from the record rather than taken from this call's
+ * own `Date.now()`, so a worker whose record lost the race adopts the winner's value and the two
+ * always agree. Re-adopting an older record is sound: nothing was pruned in the meantime, or a prune
+ * would have written the floor this function returns early on.
+ */
+function establishAuditFloor(auditStore) {
+    if ((0, databases_ts_1.isReadOnlyMode)())
+        return;
+    // Every read and write in here is inside the try: the contract is that a database open never fails
+    // over this metadata, and a throwing getBinary/getKeys would escape to initStores just as a
+    // throwing write would.
+    try {
+        // Absence of the record, not `getAuditFloor() === AUDIT_FLOOR_UNKNOWN`: a record that exists but
+        // decodes to unknown — corrupt bytes, or the Infinity a prune-everything stored — is already the
+        // fail-closed answer, and stamping over it would LOWER a floor that is never supposed to lower.
+        // The check is repeated inside the transaction (the `recorded` argument), because between this
+        // read and that write another worker's prune can store exactly such a value; this read only keeps
+        // the common case — a floor already established, every worker, every database, every boot — off
+        // the env write lock.
+        if (auditStore.getBinary(AUDIT_FLOOR_KEY) !== undefined)
+            return;
+        // Not bare Date.now(): a clock that has rolled back would bootstrap a floor BELOW history this
+        // database may already have pruned, certifying a stale cursor. The newest retained entry is a
+        // lower bound the clock cannot argue with — everything at or above it is demonstrably still here —
+        // so take whichever is later.
+        //
+        // It narrows that hole; it does not close it, because the bound covers what SURVIVES rather than
+        // what existed. A legacy `deleteHistory` removes one table's entries below its endTime out of the
+        // shared log, so a table whose entries were the newest and all fell below that bound leaves the
+        // log's newest survivor being a sibling's OLDER entry — removed history above every surviving key.
+        // A clock rolled back to between the two then stamps an epoch below entries that are gone, and a
+        // cursor in that window resumes over the gap (#2458). Also unclosed:
+        // RocksTransactionLogStore.getKeys() is unimplemented, so on that engine this reduces to
+        // Date.now() outright.
+        //
+        // Neither is a reason to refuse to stamp — the unknown sentinel is absorbing, so that would make
+        // every upgraded deployment fail closed forever. They are the reason
+        // the guess is RECORDED as a guess: written first, so it cannot be lost behind a floor that
+        // outlives it, and left in place afterwards so the repair reading stays available.
+        let fresh = Date.now();
+        for (const newest of auditStore.getKeys({ reverse: true, limit: 1 })) {
+            if (typeof newest === 'number' && newest > fresh)
+                fresh = newest;
+        }
+        // A READABLE record is kept, so the epoch read back below is whatever landed first and the floor
+        // always matches it. An unreadable one is replaced: unlike the floor, where a present record may
+        // be a deliberate AUDIT_FLOOR_UNKNOWN and overwriting it would lower a floor, this record is only
+        // a comparison basis, and undecodable bytes carry nothing worth keeping. Declining to replace
+        // them pinned the store's floor to unknown forever — the resolver would skip the write on every
+        // later open, the read back would fail identically, and no retry could ever succeed, which is the
+        // fail-closed-forever state this bootstrap exists to avoid.
+        updateAuditFloor(auditStore, (current, recorded) => (recorded && Number.isFinite(current) ? undefined : fresh), AUDIT_FLOOR_BOOTSTRAP_KEY);
+        const epoch = decodeAuditFloor(auditStore.getBinary(AUDIT_FLOOR_BOOTSTRAP_KEY));
+        // Never stamp a floor whose provenance cannot be read: that is the one state a later repair cannot
+        // act on. Unreachable in principle, since `updateAuditFloor` throws if its write did not land.
+        if (!Number.isFinite(epoch))
+            return;
+        updateAuditFloor(auditStore, (_current, recorded) => (recorded ? undefined : epoch));
+    }
+    catch (error) {
+        // An unrecorded floor already reads as unknown, which is the fail-closed answer; aborting startup
+        // instead would turn a metadata failure into an outage. The next open retries.
+        warnContained('Error initializing the audit retention floor', error);
+    }
+}
+/**
+ * The floor of this database's retained audit history: every audit entry at or after the returned
+ * time is still retained, so a consumer whose last-processed audit-log cursor is `>=` it can resume
+ * incrementally, and one below it must resync — it may have lost nothing, but the floor cannot
+ * certify it either way. Returns `Infinity` when
+ * the floor is unknown, which fails closed — no cursor compares as safe.
+ *
+ * **One exception, and it is the only one: history removed before the floor existed.** Every prune
+ * that runs with a floor recorded is covered — it raises the floor first, so it cannot remove an entry
+ * the floor does not cover. But the first open stamps a floor from what *survives*
+ * (`establishAuditFloor`), and a legacy `Table.deleteHistory` that removed a table's newest entries,
+ * followed by a clock rollback, leaves that stamp below history that is gone; a cursor in the window
+ * is then certified over the gap. So the guarantee is one-directional for tracked prunes and silent
+ * about untracked ones. Only a database generation can close that (harper#2451).
+ *
+ * The time domain is the audit-log key: what `subscribe`'s events carry as `localTime` and what MQTT
+ * durable sessions persist as `startTime`, so those compare against the floor directly.
+ * **`getHistory` is not in that domain** — it reports each entry's origin `version` under the name
+ * `localTime`, which a backdated or replicated write makes differ from the audit-log key. A cursor
+ * saved from `getHistory` is not comparable to this floor.
+ *
+ * **Database-scoped**, and deliberately conservative: the audit store is per-database and its
+ * entries carry a `tableId`, so a per-table floor would need a scan for the first entry matching
+ * that table. For a valid cursor, `cursor >= floor` therefore means no entry of *any* table in the
+ * database was removed *after* the cursor. What it never promises is anything below the FLOOR — that
+ * history is exactly what a prune takes. Below the *cursor* is not the same set: for a cursor strictly
+ * above the floor, `[floor, cursor)` sits below the cursor and is still covered by the guarantee. `Table.deleteHistory`
+ * prunes one table out of that shared log and raises the whole database's floor, which can overstate
+ * the floor for its siblings.
+ *
+ * **A moment-in-time observation.** Retention can advance between this call and whatever the caller
+ * does with the answer, so a check-then-resume sequence has a window where the floor moves under it.
+ * Closing that requires validating the cursor inside the resume itself (harper#2448); until then a
+ * lost race degrades to the truncation that happens today, never to anything worse.
+ *
+ * **On RocksDB the floor tracks the configured horizon, not retained reality.** That branch purges at
+ * whole-log-file granularity, so it cannot know before the fact which entries a purge will drop, and
+ * the floor has to be written first — so every retention pass advances it to
+ * `Date.now() - auditRetention / (1 + priority²)` whether or not a file was dropped. Entries below
+ * that horizon are routinely still on disk, and a consumer holding a cursor among them is told to
+ * resync. Conservative in the one safe direction, and the reason the LMDB branch (which can see a
+ * single eligible entry) instead raises off the first one it finds.
+ *
+ * **Not covered: copying a database's state without its history.** `restore_backup` replaces a
+ * database with the backup's, floor and all, and a RocksDB checkpoint (a branch database) copies the
+ * floor record but no transaction logs — so in both cases a cursor from after the copy point sits
+ * above a floor that is present, and therefore trusted, for history that is not there. Nothing here
+ * can detect that on its own, and it is not the audit log's problem alone: the same copy rolls back
+ * record versions and per-node replication sequence state, so making this one field honest while
+ * those stay stale would not give a consumer a coherent answer. It needs a database-level epoch —
+ * harper#2451.
+ */
+function getAuditFloor(auditStore) {
+    return decodeAuditFloor(auditStore.getBinary(AUDIT_FLOOR_KEY));
+}
 function setAuditRetention(retentionTime, defaultDelay = DEFAULT_AUDIT_CLEANUP_DELAY) {
     exports.auditRetention = retentionTime;
     DEFAULT_AUDIT_CLEANUP_DELAY = defaultDelay;
 }
+/**
+ * The retention cutoff a prune uses: `Date.now() - auditRetention`, scaled down by `divisor` for a
+ * higher-priority pass, and never below 0. A retention above ~55.7 years (or `Infinity`, to keep
+ * logs indefinitely) would otherwise go negative, and a negative bound is not "nothing eligible" —
+ * `raiseAuditFloor` rejects it, so every boot purge and retention pass would warn and the floor
+ * would never be raised on that install. At 0 the pass is a harmless no-op: nothing sits before
+ * the epoch, and a floor that already exists is never lowered to it.
+ */
+function retentionCutoff(divisor = 1) {
+    return Math.max(0, Date.now() - exports.auditRetention / divisor);
+}
 /**
  * One-shot purge of transaction-log files already older than the audit retention window,
  * intended to run during startup/recovery before transaction-log replay. The steady-state
@@ -427,7 +870,10 @@ function purgeAgedLogs(rootStore) {
     // Mirror the read-only guard in scheduleAuditCleanup: never delete log files in read-only mode.
     if ((0, databases_ts_1.isReadOnlyMode)())
         return [];
-    return rootStore.purgeLogs({ before: Date.now() - exports.auditRetention });
+    const before = retentionCutoff();
+    // The audit store is reachable this early because initStores opens it before replayLogs runs this.
+    raiseAuditFloor(rootStore.auditStore, before);
+    return rootStore.purgeLogs({ before });
 }
 const HAS_RECORD = 16;
 const HAS_PARTIAL_RECORD = 32; // will be used for CRDTs
@@ -441,13 +887,31 @@ const STRUCTURES = 7;
 // Whole-table "reload" marker: a control entry (no record) signalling that a table was bulk-reloaded
 // and subscribers should re-read it. Used after a copyApply base copy, whose per-row snapshot writes
 // carry no audit entry (harper-pro#489). The entry type lives in the low nibble of the action byte
-// (decoded via `action & 0xf`); 1–7 are the record actions above, 8 is reload, leaving 9–15 free for
-// future actions. Markers are always written LOCAL_ONLY so an unknown type never reaches a peer.
+// (decoded via `action & 0xf`); 1–7 are the record actions above, 8 is reload, 9 is eviction, leaving 10–15 free for
+// future actions. Reload markers are always written LOCAL_ONLY so an unknown type never reaches a
+// peer; the lock control entries below deliberately are not, and rely on the capability gate instead.
 const RELOAD = 8;
+const EVICT = 9;
 exports.ACTION_32_BIT = 14;
 exports.ACTION_64_BIT = 15;
 /** Used to indicate we have received a remote local time update */
 exports.REMOTE_SEQUENCE_UPDATE = 11;
+/**
+ * Cluster record-lock coordination (harper#483 Phase 1). This replicates — unlike the reload marker
+ * it is NOT `LOCAL_ONLY` — and carries a control payload rather than a record, so it is written with
+ * `recordId: null`: an entry sharing a real record's `(version, tableId, recordId, nodeId)` would be
+ * returned by `RocksTransactionLogStore.getSync` ahead of that record's own audit entry and make
+ * `_writeUpdate`'s keyed dedup drop the holder's write.
+ *
+ * Two entries exist: the release, and the barrier — a replicated no-op a member commits on request
+ * so its own log position can serve as the §7.2 recovery fence (harper#2625). Nibbles 9 and 10
+ * briefly held `lockRequest`/`lockGrant` for the Ricart–Agrawala arbitration rule that
+ * `docs/record-lock-ownership.md` replaces; that rule never shipped enabled, so they were retired
+ * rather than migrated — and 9 has since been taken by eviction. 10 is spare; 14/15 are the width
+ * flags.
+ */
+exports.LOCK_RELEASE = 12;
+exports.LOCK_BARRIER = 13;
 exports.HAS_CURRENT_RESIDENCY_ID = 512;
 exports.HAS_PREVIOUS_RESIDENCY_ID = 1024;
 exports.HAS_ORIGINATING_OPERATION = 2048;
@@ -481,16 +945,84 @@ const EVENT_TYPES = {
     [STRUCTURES]: 'structures',
     reload: RELOAD,
     [RELOAD]: 'reload',
+    evict: EVICT,
+    [EVICT]: 'evict',
     remoteSequenceUpdate: exports.REMOTE_SEQUENCE_UPDATE,
     [exports.REMOTE_SEQUENCE_UPDATE]: 'remoteSequenceUpdate',
+    lockRelease: exports.LOCK_RELEASE | HAS_RECORD,
+    [exports.LOCK_RELEASE]: 'lockRelease',
+    lockBarrier: exports.LOCK_BARRIER | HAS_RECORD,
+    [exports.LOCK_BARRIER]: 'lockBarrier',
 };
+/**
+ * The LMDB audit entry states the presence of its leading 8-byte previousVersion field with that
+ * field's own first byte. The same test is what harperdb 4.x's reader uses and what both versions'
+ * replication senders use to strip the field before framing an entry for the wire, so it is a
+ * cross-version contract, not a local convention: a field written with any other leading byte is
+ * skipped by every reader and shifts action/nodeId/tableId/recordId/version by 8. See harper#2247.
+ */
+const PREVIOUS_VERSION_FIRST_BYTE = 66;
+/**
+ * Which first bytes can begin an action, and so cannot be a previousVersion field. Derived from what
+ * the encoding can express, not from the types defined today: nibbles 9-15 are reserved for future
+ * entry types, and a peer one version ahead must keep decoding rather than look corrupt here.
+ */
+const ACTION_FIRST_BYTE = new Uint8Array(256);
+// single-byte form; 0 is not an entry type, so a zero low nibble cannot start one
+for (let firstByte = 1; firstByte <= (HAS_RECORD | HAS_PARTIAL_RECORD | 0xf); firstByte++) {
+    if (firstByte & 0xf)
+        ACTION_FIRST_BYTE[firstByte] = 1;
+}
+// extended form, written as `action | extendedType | 0xc0000000`; 0xff is the five-byte readInt form
+for (let firstByte = 0xc0; firstByte < 0xff; firstByte++)
+    ACTION_FIRST_BYTE[firstByte] = 1;
+let knownActionFlags;
+/**
+ * Whether an action word decodes wholly into what this version understands. Consulted only to accept
+ * or reject a legacy prefix recovery — never to validate a normally-framed entry, where an unknown
+ * future flag must stay forwards-compatible rather than corrupt. The mask is built on first use
+ * because HAS_STRUCTURE_UPDATE crosses the RecordEncoder import cycle: read at module scope it
+ * resolves to undefined whenever RecordEncoder is the cycle's entry, silently dropping that bit.
+ */
+function isDecodableAction(action) {
+    knownActionFlags ??=
+        0xf |
+            HAS_RECORD |
+            HAS_PARTIAL_RECORD |
+            RecordEncoder_ts_1.HAS_STRUCTURE_UPDATE |
+            exports.HAS_CURRENT_RESIDENCY_ID |
+            exports.HAS_PREVIOUS_RESIDENCY_ID |
+            exports.HAS_ORIGINATING_OPERATION |
+            exports.HAS_EXPIRATION_EXTENDED_TYPE |
+            exports.HAS_BLOBS |
+            exports.HAS_ADDITIONAL_AUDIT_REFS |
+            exports.LOCAL_ONLY;
+    return (action & 0xf) !== 0 && !(action & ~knownActionFlags);
+}
+/**
+ * Cluster lock coordination entries. They ride the replicated audit stream but describe no record,
+ * so every consumer that surfaces audit entries as record activity — subscriber fan-out, the
+ * `startTime` replay, the `previousCount` backfill, the replicated-event sink — must exclude them.
+ * An equality chain rather than a Set: this runs once per audit entry on the replay and fan-out
+ * paths, where the common answer is false on the first comparison.
+ */
+function isLockControlType(type) {
+    return type === 'lockRelease' || type === 'lockBarrier';
+}
 const ORIGINATING_OPERATIONS = {
     insert: 1,
     update: 2,
     upsert: 3,
+    // `put` must be persisted, not inferred: the physical write type is also `put` for an `upsert`
+    // that happened to create a record, so the history readers cannot tell the two apart from the
+    // type alone. Without an id here the originating operation decoded as undefined, the readers fell
+    // back to the physical type, and replication catch-up replayed a `put` as an `upsert` — patching
+    // the replica and RETAINING attributes the source had removed.
+    put: 4,
     1: 'insert',
     2: 'update',
     3: 'upsert',
+    4: 'put',
 };
 /**
  * Creates a binary audit entry
@@ -523,14 +1055,42 @@ function createAuditEntry(auditRecord, start = 0) {
         }
         action &= ~HAS_RECORD;
     }
-    let position = start + 1;
-    if (previousVersion) {
-        if (previousVersion > 1)
+    let hasPreviousVersion;
+    if (start > 0) {
+        // RocksTransactionLogStore states presence with its own prelude flag, derived from this same
+        // truthiness, so this container's field stays unconditional and its value is unconstrained.
+        hasPreviousVersion = !!previousVersion;
+        if (hasPreviousVersion)
             exports.ENTRY_DATAVIEW.setFloat64(start, previousVersion);
-        else
-            ENTRY_HEADER.set(RecordEncoder_ts_1.PREVIOUS_TIMESTAMP_PLACEHOLDER, start);
-        position = start + 9;
     }
+    else if (previousVersion == null || previousVersion === 0) {
+        // absence is stated, not inferred from truthiness: NaN is falsy and would otherwise be
+        // silently dropped rather than rejected below
+        hasPreviousVersion = false;
+    }
+    else if (previousVersion === RecordEncoder_ts_1.PENDING_LOCAL_TIME) {
+        // The previous entry has no log position yet, and a format whose presence signal is the value's
+        // own first byte cannot express "to be filled in at commit". The superseded code deferred to
+        // lmdb-js's instructed-write substitution, which resolves to 2.0 whenever no previous time was
+        // recorded — the unreadable entry behind harper-pro#737. It resolved correctly when one was, so
+        // this trades a lost link on that path for never minting the unreadable form. Not a throw: a
+        // pending previous is a producer state, unlike a value the format cannot hold.
+        hasPreviousVersion = false;
+        if (!warnedPendingPreviousVersion.has(`${tableId}:${type}`)) {
+            warnedPendingPreviousVersion.add(`${tableId}:${type}`);
+            warnContained(`Audit entry (${type}) for record ${recordId} in table ${tableId} has a pending previous version; recording it without a previous-version link`, new Error('pending audit previousVersion'));
+        }
+    }
+    else {
+        exports.ENTRY_DATAVIEW.setFloat64(start, previousVersion);
+        if (ENTRY_HEADER[start] !== PREVIOUS_VERSION_FIRST_BYTE) {
+            throw new Error(`Audit entry previousVersion ${previousVersion} for record ${recordId} in table ${tableId} is not representable. ` +
+                'The LMDB audit format signals this field with its own leading 0x42 byte, so only values in [2**33, 2**49) can be written; ' +
+                'writing any other value produces an entry every reader parses 8 bytes off.');
+        }
+        hasPreviousVersion = true;
+    }
+    let position = start + (hasPreviousVersion ? 9 : 1);
     if (extendedType) {
         if (extendedType & 0xff) {
             throw new Error('Illegal extended type');
@@ -572,10 +1132,11 @@ function createAuditEntry(auditRecord, start = 0) {
         writeValue(user);
     else
         ENTRY_HEADER[position++] = 0;
+    const actionPosition = start + (hasPreviousVersion ? 8 : 0);
     if (extendedType)
-        exports.ENTRY_DATAVIEW.setUint32(start + (previousVersion ? 8 : 0), action | extendedType | 0xc0000000);
+        exports.ENTRY_DATAVIEW.setUint32(actionPosition, action | extendedType | 0xc0000000);
     else
-        ENTRY_HEADER[start + (previousVersion ? 8 : 0)] = action;
+        ENTRY_HEADER[actionPosition] = action;
     const header = ENTRY_HEADER.subarray(0, position);
     if (encodedRecord) {
         return Buffer.concat([header, encodedRecord]);
@@ -638,13 +1199,42 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
             (buffer.decoder = new Decoder(buffer.buffer, buffer.byteOffset, buffer.byteLength));
         decoder.position = start;
         let previousVersion;
-        if (buffer[decoder.position] == 66) {
-            // 66 is the first byte in a date double.
+        let entryStart = start;
+        const firstByte = buffer[start];
+        if (firstByte === PREVIOUS_VERSION_FIRST_BYTE) {
             previousVersion = decoder.readFloat64();
         }
+        else if (ACTION_FIRST_BYTE[firstByte] !== 1) {
+            // Written before the writer enforced the leading-0x42 contract (harper#2247): the field is
+            // physically here but does not announce itself, so the action sits 8 bytes further on.
+            // Recover only when the bytes cannot be anything else, and never for the RocksDB container,
+            // whose prelude flag already consumed its previousVersion before this offset.
+            if (start !== 0 || start + 9 > buffer.byteLength || ACTION_FIRST_BYTE[buffer[start + 8]] !== 1) {
+                return corruptEntry(buffer, start, end, firstByte);
+            }
+            // > 1 is exactly what the superseded writer's own guard could emit, the tightest available
+            // bound on "these bytes really are an old previousVersion"
+            if (!(decoder.getFloat64(start) > 1))
+                return corruptEntry(buffer, start, end, firstByte);
+            entryStart = decoder.position = start + 8;
+            // The value itself is dropped, not reported. It cannot lead with 0x42 (that is the branch
+            // above), and audit keys carry the same constraint, so it could never have addressed a
+            // retrievable entry; reporting it would only feed an unrepresentable value back to
+            // createAuditEntry through the resolveRecord re-mint in RecordEncoder, which now rejects it.
+        }
         const action = decoder.readInt();
+        if (entryStart !== start && !isDecodableAction(action)) {
+            return corruptEntry(buffer, start, end, firstByte);
+        }
         const nodeId = decoder.readInt();
         const tableId = decoder.readInt();
+        if (entryStart !== start && !warnedRecoveredTables.has(tableId)) {
+            warnedRecoveredTables.add(tableId);
+            warnContained('Audit entry carries an unannounced previousVersion field; recovering its field offsets', {
+                tableId,
+                firstByte,
+            });
+        }
         let length = decoder.readInt();
         // A corrupt length field (e.g., a 0xff-prefixed uint32) would otherwise push
         // decoder.position hundreds of megabytes past the buffer; the next readFloat64
@@ -690,10 +1280,11 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
         const usernameEnd = (decoder.position += length);
         let value;
         return {
-            // The entry type is the low nibble of the action byte (1–7 record actions, 8 reload, 9–15
+            // The entry type is the low nibble of the action byte (1–7 record actions, 8 reload, 9 eviction, 10–15
             // reserved); the flag bits (HAS_RECORD, HAS_PARTIAL_RECORD, …) sit above it. `& 0xf` is
             // identical to the historical `& 7` for every pre-reload entry (bit 3 was always clear).
             type: EVENT_TYPES[action & 0xf],
+            logName: undefined,
             tableId,
             nodeId,
             get recordId() {
@@ -714,7 +1305,6 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
                 return buffer.subarray(recordIdStart, recordIdEnd);
             },
             version,
-            recordVersion: version,
             previousVersion,
             get user() {
                 try {
@@ -728,10 +1318,14 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
                 }
             },
             get encoded() {
-                return start ? buffer.subarray(start, end) : buffer;
+                // On a recovered entry this drops the unannounced prefix, so a replication sender —
+                // which strips by the same leading-0x42 test and frames by encoded.length — forwards a
+                // clean entry instead of passing the same misparse to the next hop.
+                return entryStart ? buffer.subarray(entryStart, end) : buffer;
             },
             get size() {
-                return start !== undefined && end !== undefined ? end - start : buffer.byteLength;
+                // only the recovered prefix is discounted; every other case keeps its existing basis
+                return (end !== undefined ? end - start : buffer.byteLength) - (entryStart - start);
             },
             getValue(store, fullRecord, auditTime) {
                 if (action & HAS_RECORD || (action & HAS_PARTIAL_RECORD && !fullRecord)) {
@@ -776,6 +1370,22 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
         return createCorruptAuditSentinel(buffer, start, end);
     }
 }
+/**
+ * Reject a header whose first byte can be neither an action nor a previousVersion field. Returns the
+ * sentinel directly rather than throwing into readAuditEntry's catch, whose error log is not
+ * contained: a throwing log sink there would escape the decoder and stall the iteration it runs in.
+ */
+function corruptEntry(buffer, start, end, firstByte) {
+    if (!warnedUndecodableHeader) {
+        warnedUndecodableHeader = true;
+        warnContained('Audit entry header begins with neither an action nor a previousVersion; treating as corrupt', {
+            firstByte,
+            // the 8 prefix bytes plus the action byte: the classifying bytes, stopping before the recordId
+            header: Buffer.from(buffer.subarray(start, Math.min(start + 9, buffer.byteLength))).toString('hex'),
+        });
+    }
+    return createCorruptAuditSentinel(buffer, start, end);
+}
 /**
  * Build a structurally complete audit record for an entry that failed to decode. The fields
  * mirror the happy-path shape so downstream consumers that access (e.g.) `getValue` or the
@@ -788,6 +1398,7 @@ function readAuditEntry(buffer, start = 0, end = undefined) {
 function createCorruptAuditSentinel(buffer, start, end) {
     return {
         type: undefined,
+        logName: undefined,
         tableId: undefined,
         nodeId: undefined,
         recordId: undefined,