@peerbit/shared-log 16.0.1 → 16.0.3

package/dist/src/index.js

@@ -76,7 +76,7 @@ import { AbsoluteReplicas, AddedReplicationInfoV2Message, AddedReplicationSegmen
 import { ReplicatorLivenessMonitor } from "./replicator-liveness.js";
 import { createSyncronizer } from "./sync/factory.js";
 import { emitSyncProfileDuration, emitSyncProfileEvent, syncProfileStart, } from "./sync/profile.js";
-import { ConfirmEntriesMessage, SYNC_MESSAGE_PRIORITY, SimpleSyncronizer, } from "./sync/simple.js";
+import { ConfirmEntriesMessage, RECENT_KNOWN_EXCHANGE_HEAD_SUPPRESSION_MS, SYNC_MESSAGE_PRIORITY, SimpleSyncronizer, } from "./sync/simple.js";
 import { groupByGid, tryGroupByGidSync } from "./utils.js";
 const getSharedLogFanoutService = (services) => services.fanout;
 const createOneShotPeerReceiveLease = (releaseFn) => {
@@ -449,6 +449,13 @@ const JOIN_AUTHORITATIVE_RETRY_SCHEDULE_MS = [
 ];
 const APPEND_BACKFILL_RETRY_SCHEDULE_MS = [0, 1_000, 3_000, 7_000];
 const RECENT_KNOWN_REPAIR_SUPPRESSION_MS = 30_000;
+// `_entryKnownPeerObservedAt` is read ONLY through isEntryRecentlyKnownByPeer,
+// which treats an over-age row and an absent row identically (both false). So
+// rows older than the longest horizon any caller asks about are dead weight,
+// and dropping them is behaviour-identical rather than merely safe. Derived
+// from the horizons themselves -- never hardcode it -- so a future caller with
+// a longer window cannot silently outlive the retention that serves it.
+const ENTRY_KNOWN_PEER_OBSERVED_AT_RETENTION_MS = Math.max(RECENT_KNOWN_REPAIR_SUPPRESSION_MS, RECENT_KNOWN_EXCHANGE_HEAD_SUPPRESSION_MS);
 const JOIN_AUTHORITATIVE_REPAIR_DELAY_MS = 2_000;
 const JOIN_AUTHORITATIVE_REPAIR_SWEEP_DELAYS_MS = [
     JOIN_AUTHORITATIVE_REPAIR_DELAY_MS,
@@ -1511,8 +1518,23 @@ let SharedLog = (() => {
                     };
                     for (const coordinate of intent.coordinates) {
                         rollback.hashes.add(coordinate.hash);
-                        const generation = (mutationGenerations.get(coordinate.hash) ?? 0) + 1;
-                        mutationGenerations.set(coordinate.hash, generation);
+                        // Same hold-counted row shape the coordinator's own
+                        // snapshot writes: one hold per hash, released by the
+                        // settle after the replay consumes the token below.
+                        // RELIES ON `intent.coordinates` HOLDING UNIQUE HASHES —
+                        // it is built from the token's `hashes` Set (see
+                        // setNativeStrictDurableTransactionOperation). Holds are
+                        // taken per element here but released per unique hash by
+                        // the settle, so a duplicate would take two and release
+                        // one and retain that row forever. That is the safe
+                        // direction (a retained row, never a fail-open rollback),
+                        // but keep the source a Set.
+                        const row = mutationGenerations.get(coordinate.hash);
+                        const generation = (row?.generation ?? 0) + 1;
+                        mutationGenerations.set(coordinate.hash, {
+                            generation,
+                            holds: (row?.holds ?? 0) + 1,
+                        });
                         rollback.generations.set(coordinate.hash, generation);
                         if (coordinate.value) {
                             const number = (value) => (this.domain.resolution === "u32"
@@ -1530,6 +1552,9 @@ let SharedLog = (() => {
                         }
                     }
                     await this._coordinates.rollbackNativeBackboneCoordinateAppendDurably("", rollback);
+                    // The replay fabricated these generations itself one turn
+                    // earlier and has now consumed them, so the rows are dead.
+                    this._coordinates.settleResidentCoordinateSnapshot(rollback);
                 }
                 for (const document of intent.documents) {
                     this.restoreNativeBackboneDocument({
@@ -1633,6 +1658,7 @@ let SharedLog = (() => {
         _repairSweepOptimisticGidsByPeer;
         _entryKnownPeers;
         _entryKnownPeerObservedAt;
+        _entryKnownPeerObservedAtSweptAt = 0;
         _joinAuthoritativeRepairTimersByDelay;
         _joinAuthoritativeRepairPeersByDelay;
         _assumeSyncedRepairSuppressedUntil;
@@ -1885,6 +1911,7 @@ let SharedLog = (() => {
             this._repairSweepOptimisticGidsByPeer = new Map();
             this._entryKnownPeers = new Map();
             this._entryKnownPeerObservedAt = new Map();
+            this._entryKnownPeerObservedAtSweptAt = 0;
             this._joinAuthoritativeRepairTimersByDelay = new Map();
             this._joinAuthoritativeRepairPeersByDelay = new Map();
             this._appendBackfillPendingByTarget = new Map();
@@ -4830,6 +4857,14 @@ let SharedLog = (() => {
             this._nativeSharedLogState?.markEntriesKnownByPeer(hashArray, peer);
             this._nativeBackbone?.markEntriesKnownByPeer(hashArray, peer);
             const now = Date.now();
+            // Growth is driven by writes, so the sweep rides the write path rather
+            // than a timer or the rebalance pass: cost stays proportional to the
+            // traffic that creates rows. Rate-limited to one pass per retention
+            // window, over a map that after the first pass holds one window of marks.
+            if (now - this._entryKnownPeerObservedAtSweptAt >=
+                ENTRY_KNOWN_PEER_OBSERVED_AT_RETENTION_MS) {
+                this.sweepEntryKnownPeerObservedAt(now);
+            }
             for (const hash of hashArray) {
                 let peers = this._entryKnownPeers.get(hash);
                 if (!peers) {
@@ -4889,6 +4924,27 @@ let SharedLog = (() => {
             const observedAt = this._entryKnownPeerObservedAt.get(hash)?.get(peer);
             return observedAt != null && Date.now() - observedAt <= maxAgeMs;
         }
+        /** Drop recency marks no reader can still act on.
+         *
+         * Touches ONLY `_entryKnownPeerObservedAt`. `_entryKnownPeers` carries
+         * membership, not recency, and its rows stay until the peer dimension
+         * clears them; the native mirrors have no recency dimension at all
+         * (mark/remove/removePeer only), so this must not call into them or the
+         * two sides would disagree.
+         */
+        sweepEntryKnownPeerObservedAt(now) {
+            for (const [hash, observedAt] of this._entryKnownPeerObservedAt) {
+                for (const [peer, timestamp] of observedAt) {
+                    if (now - timestamp > ENTRY_KNOWN_PEER_OBSERVED_AT_RETENTION_MS) {
+                        observedAt.delete(peer);
+                    }
+                }
+                if (observedAt.size === 0) {
+                    this._entryKnownPeerObservedAt.delete(hash);
+                }
+            }
+            this._entryKnownPeerObservedAtSweptAt = now;
+        }
         markRepairSweepOptimisticPeer(gid, peer, session) {
             let peers = this._repairSweepOptimisticGidPeersPending.get(gid);
             if (!peers) {
@@ -7043,10 +7099,15 @@ let SharedLog = (() => {
                 return rollbackLowerPublication(error);
             }
             if (!result) {
+                // Abandon arm: the token was minted but nothing downstream can
+                // roll it back from here.
+                this._coordinates.settleResidentCoordinateSnapshot(lowerPublicationRollback?.coordinateEntries);
                 return this.completeNativeStrictDurableTransaction(nativeStrictTransaction).then(() => undefined);
             }
             return mapMaybePromise(result, async (prepared) => {
                 if (!prepared) {
+                    // Abandon arm: same shape as the `!result` arm above.
+                    this._coordinates.settleResidentCoordinateSnapshot(lowerPublicationRollback?.coordinateEntries);
                     await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
                     return undefined;
                 }
@@ -7067,6 +7128,9 @@ let SharedLog = (() => {
                     }
                     try {
                         await this._coordinates.rollbackNativeBackboneCoordinateAppendDurably(prepared.appendFacts.hash, lowerPublicationRollback?.coordinateEntries);
+                        // Terminal: this is the last rollback consumer for the
+                        // token. A throw above leaves the row, which is safe.
+                        this._coordinates.settleResidentCoordinateSnapshot(lowerPublicationRollback?.coordinateEntries);
                         for (const document of lowerPublicationRollback?.documents ?? []) {
                             this.restoreNativeBackboneDocument(document);
                         }
@@ -7126,6 +7190,12 @@ let SharedLog = (() => {
                 catch (error) {
                     return rollback(error);
                 }
+                // Success seam. The last await inside the protected try is the
+                // finalizer acknowledge; `finish()` is synchronous, so no async
+                // boundary separates the catch above from this statement and
+                // `rollback` can no longer fire. Nothing downstream rolls back
+                // (the retire below only warns), so the token is terminal here.
+                this._coordinates.settleResidentCoordinateSnapshot(lowerPublicationRollback?.coordinateEntries);
                 this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(prepared.appendFacts, prepared.removed, prepared.materializeEntry, { removedHashes: prepared.removedHashes });
                 try {
                     await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
@@ -7428,6 +7498,10 @@ let SharedLog = (() => {
                 }
                 return mapMaybePromise(result, async (prepared) => {
                     if (!prepared || !backboneAppend) {
+                        // Abandon arm: the token was minted inside
+                        // `prepareBackboneAppend` and nothing downstream of
+                        // this return can roll it back.
+                        this._coordinates.settleResidentCoordinateSnapshot(nativeCoordinateRollback);
                         await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
                         return undefined;
                     }
@@ -7495,6 +7569,8 @@ let SharedLog = (() => {
                         }
                         try {
                             await this._coordinates.rollbackNativeBackboneCoordinateAppendDurably(prepared.appendFacts.hash, rollbackCoordinateEntries);
+                            // Terminal: last rollback consumer for the token.
+                            this._coordinates.settleResidentCoordinateSnapshot(rollbackCoordinateEntries);
                         }
                         catch (rollbackError) {
                             rollbackFailures.push(rollbackError);
@@ -7556,6 +7632,10 @@ let SharedLog = (() => {
                     catch (error) {
                         return rollback(error);
                     }
+                    // Success seam: the finalizer acknowledge above is the last
+                    // await inside the protected try, so `rollback` can no
+                    // longer fire and the retire below only warns.
+                    this._coordinates.settleResidentCoordinateSnapshot(rollbackCoordinateEntries);
                     this.applyPreparedAppendFactsWithDeferredCoordinateDeletes(prepared.appendFacts, prepared.removed, prepared.materializeEntry, {
                         forgetNativeCoordinates: false,
                         removedHashes: prepared.removedHashes,
@@ -8110,6 +8190,8 @@ let SharedLog = (() => {
                 throw error;
             }
             if (!appended || !backboneAppends) {
+                // Abandon arm: no consumer downstream of this return.
+                this._coordinates.settleResidentCoordinateSnapshot(batchCoordinateRollback);
                 await this.completeNativeStrictDurableTransaction(nativeStrictTransaction);
                 this.throwIfReplicationOwnershipLifecycleInactive(ownershipLifecycleController);
                 return undefined;
@@ -8132,6 +8214,8 @@ let SharedLog = (() => {
                 }
                 try {
                     await this._coordinates.rollbackNativeBackboneCoordinateAppendDurably(appended.appendFacts[0]?.hash ?? "", batchCoordinateRollback);
+                    // Terminal: last rollback consumer for the batch token.
+                    this._coordinates.settleResidentCoordinateSnapshot(batchCoordinateRollback);
                 }
                 catch (rollbackError) {
                     rollbackFailures.push(rollbackError);
@@ -8222,6 +8306,9 @@ let SharedLog = (() => {
             catch (error) {
                 return rollbackBatch(error);
             }
+            // Success seam: `rollbackBatch` has exactly one call site (the catch
+            // above), and everything from here on escapes without any rollback.
+            this._coordinates.settleResidentCoordinateSnapshot(batchCoordinateRollback);
             this.throwIfReplicationOwnershipLifecycleInactive(ownershipLifecycleController);
             const appendCommits = [];
             for (let i = 0; i < coordinateRows.length; i++) {
@@ -9160,6 +9247,7 @@ let SharedLog = (() => {
             this._repairSweepOptimisticGidsByPeer = new Map();
             this._entryKnownPeers = new Map();
             this._entryKnownPeerObservedAt = new Map();
+            this._entryKnownPeerObservedAtSweptAt = 0;
             this._joinAuthoritativeRepairTimersByDelay = new Map();
             this._joinAuthoritativeRepairPeersByDelay = new Map();
             this._assumeSyncedRepairSuppressedUntil = 0;
@@ -12886,221 +12974,233 @@ let SharedLog = (() => {
                             const nativeReceiveCoordinateBatch = canUsePreparedAppendFacts
                                 ? this._coordinates.createBackboneOnlyReceiveCoordinateBatch(reusableCoordinatePersistItems)
                                 : undefined;
-                            const nativePreparedJoinCommit = canUsePreparedAppendFacts
-                                ? this._coordinates.createNativeBackbonePreparedJoinCommit(nativeReceiveCoordinateBatch, (batch) => {
-                                    nativePreparedCoordinateBatch = batch;
-                                }, nativeCommitVerifyHashes, nativeCommitVerifyAllHashes, syncProfile, (committedHashes) => {
-                                    nativePreparedCommittedHashes = new Set(committedHashes);
-                                })
-                                : undefined;
-                            const finishNativePreparedCoordinates = async (properties) => {
-                                if (!properties.nativePreparedCommitted ||
-                                    !nativePreparedCoordinateBatch) {
-                                    return;
-                                }
-                                try {
-                                    nativeBackboneOnlyPersistedHashes =
-                                        await this._coordinates.finishBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch, syncProfile);
-                                    nativePreparedCoordinatesFinished = true;
-                                }
-                                catch (error) {
-                                    this._coordinates.rollbackBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch);
-                                    throw error;
+                            try {
+                                const nativePreparedJoinCommit = canUsePreparedAppendFacts
+                                    ? this._coordinates.createNativeBackbonePreparedJoinCommit(nativeReceiveCoordinateBatch, (batch) => {
+                                        nativePreparedCoordinateBatch = batch;
+                                    }, nativeCommitVerifyHashes, nativeCommitVerifyAllHashes, syncProfile, (committedHashes) => {
+                                        nativePreparedCommittedHashes = new Set(committedHashes);
+                                    })
+                                    : undefined;
+                                const finishNativePreparedCoordinates = async (properties) => {
+                                    if (!properties.nativePreparedCommitted ||
+                                        !nativePreparedCoordinateBatch) {
+                                        return;
+                                    }
+                                    try {
+                                        nativeBackboneOnlyPersistedHashes =
+                                            await this._coordinates.finishBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch, syncProfile);
+                                        nativePreparedCoordinatesFinished = true;
+                                    }
+                                    catch (error) {
+                                        this._coordinates.rollbackBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch);
+                                        throw error;
+                                    }
+                                };
+                                const preparedAppendCanValidateAppend = canAppendAlreadyValidated ||
+                                    (nativeCommitCanValidateAppend && !!nativePreparedJoinCommit);
+                                if (!preparedAppendCanValidateAppend) {
+                                    canUsePreparedAppendFacts = false;
                                 }
-                            };
-                            const preparedAppendCanValidateAppend = canAppendAlreadyValidated ||
-                                (nativeCommitCanValidateAppend && !!nativePreparedJoinCommit);
-                            if (!preparedAppendCanValidateAppend) {
-                                canUsePreparedAppendFacts = false;
-                            }
-                            const nativePreparedJoinCommitValidatesPlan = !!nativePreparedJoinCommit &&
-                                (nativeCommitVerifyHashes && nativeCommitVerifyHashes.length > 0
-                                    ? nativeCommitVerifyAllHashes
-                                        ? !!this._nativeBackbone?.graph
-                                            .commitVerifiedAllPreparedRawReceiveJoinBatch ||
-                                            !!this._nativeBackbone?.graph
+                                const nativePreparedJoinCommitValidatesPlan = !!nativePreparedJoinCommit &&
+                                    (nativeCommitVerifyHashes && nativeCommitVerifyHashes.length > 0
+                                        ? nativeCommitVerifyAllHashes
+                                            ? !!this._nativeBackbone?.graph
+                                                .commitVerifiedAllPreparedRawReceiveJoinBatch ||
+                                                !!this._nativeBackbone?.graph
+                                                    .commitVerifiedPreparedRawReceiveJoinBatch
+                                            : !!this._nativeBackbone?.graph
                                                 .commitVerifiedPreparedRawReceiveJoinBatch
                                         : !!this._nativeBackbone?.graph
-                                            .commitVerifiedPreparedRawReceiveJoinBatch
-                                    : !!this._nativeBackbone?.graph
-                                        .commitPreparedRawReceiveJoinBatch);
-                            const trustedLowerLog = this.log;
-                            // With a program-level onChange consumer the hash-only
-                            // sink is not used: the lower-log join dispatches the
-                            // change event (lazy entry views over the prepared raw
-                            // facts) so per-entry consumers observe every commit.
-                            const joinOnAppendHashes = programOnChange
-                                ? undefined
-                                : onAppendHashes;
-                            const joinedPreparedFacts = canUsePreparedAppendFacts &&
-                                (await trustedLowerLog.joinPreparedAppendFactsBatch(preparedAppendFacts, {
-                                    __peerbitEntriesAlreadyMissing: true,
-                                    __peerbitCanAppendAlreadyValidated: true,
-                                    __peerbitDeferIndexWrite: true,
-                                    __peerbitOnAppendHashes: joinOnAppendHashes,
-                                    __peerbitProfile: syncProfile,
-                                    __peerbitNativePreparedJoinCommit: nativePreparedJoinCommit,
-                                    __peerbitNativePreparedJoinCommitValidatesPlan: nativePreparedJoinCommitValidatesPlan,
-                                    __peerbitOnPreparedJoinCommitted: nativePreparedJoinCommit
-                                        ? finishNativePreparedCoordinates
-                                        : undefined,
-                                }));
-                            if (!joinedPreparedFacts) {
-                                await trustedLowerLog.join(materializeAllToMergeEntries(), {
-                                    __peerbitBatchIndependent: true,
-                                    __peerbitEntriesAlreadyMissing: true,
-                                    __peerbitCanAppendAlreadyValidated: fallbackCanAppendAlreadyValidated,
-                                    __peerbitDeferIndexWrite: true,
-                                    __peerbitOnAppendHashes: joinOnAppendHashes,
-                                    __peerbitProfile: syncProfile,
-                                });
-                            }
-                            // A recursive lower-log join can resolve successfully while declining
-                            // an individual top-level entry (for example, when one of its parents
-                            // is temporarily unavailable). The public Log.join() API intentionally
-                            // does not expose that per-entry result, so make local index presence the
-                            // authority before publishing any SharedLog-side effects. A successful
-                            // prepared-facts batch is atomic and already proves every input hash.
-                            const admittedHashes = joinedPreparedFacts
-                                ? new Set(allToMergeHashes)
-                                : await this.log.hasMany(allToMergeHashes);
-                            admittedMergeHashes = admittedHashes;
-                            const admittedShallowEntries = admittedHashes.size === allToMergeShallowEntries.length
-                                ? allToMergeShallowEntries
-                                : allToMergeShallowEntries.filter((entry) => admittedHashes.has(entry.hash));
-                            if (!joinedPreparedFacts) {
-                                reusableCoordinatePersistItems =
-                                    reusableCoordinatePersistItems.filter((item) => admittedHashes.has(item.entry.hash));
-                                coordinatePersistFallbackEntries =
-                                    coordinatePersistFallbackEntries.filter((entry) => admittedHashes.has(entry.hash));
-                            }
-                            const reusableCoordinatePersistItemCount = reusableCoordinatePersistItems.length;
-                            if (syncProfile) {
-                                emitSyncProfileDuration(syncProfile, lowerLogJoinStartedAt, {
-                                    name: "sharedLog.receive.lowerLogJoin",
-                                    component: "shared-log",
-                                    entries: allToMerge.length,
-                                    messages: 1,
-                                    details: {
-                                        hashOnlyEntryAdded,
-                                        batchHashOnlyEntryAdded,
-                                        programOnChange,
-                                        joinedPreparedFacts,
-                                        admittedEntries: admittedHashes.size,
-                                        nativePreparedCoordinatesFinished,
-                                    },
-                                });
-                            }
-                            const coordinatePersistStartedAt = syncProfileStart(syncProfile);
-                            if (nativePreparedCoordinatesFinished) {
-                                // The lower-log prepared receive transaction already finished
-                                // the native coordinate mirror/journal after entry-index commit.
-                            }
-                            else if (nativePreparedCoordinateBatch) {
-                                try {
-                                    nativeBackboneOnlyPersistedHashes =
-                                        await this._coordinates.finishBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch, syncProfile);
+                                            .commitPreparedRawReceiveJoinBatch);
+                                const trustedLowerLog = this.log;
+                                // With a program-level onChange consumer the hash-only
+                                // sink is not used: the lower-log join dispatches the
+                                // change event (lazy entry views over the prepared raw
+                                // facts) so per-entry consumers observe every commit.
+                                const joinOnAppendHashes = programOnChange
+                                    ? undefined
+                                    : onAppendHashes;
+                                const joinedPreparedFacts = canUsePreparedAppendFacts &&
+                                    (await trustedLowerLog.joinPreparedAppendFactsBatch(preparedAppendFacts, {
+                                        __peerbitEntriesAlreadyMissing: true,
+                                        __peerbitCanAppendAlreadyValidated: true,
+                                        __peerbitDeferIndexWrite: true,
+                                        __peerbitOnAppendHashes: joinOnAppendHashes,
+                                        __peerbitProfile: syncProfile,
+                                        __peerbitNativePreparedJoinCommit: nativePreparedJoinCommit,
+                                        __peerbitNativePreparedJoinCommitValidatesPlan: nativePreparedJoinCommitValidatesPlan,
+                                        __peerbitOnPreparedJoinCommitted: nativePreparedJoinCommit
+                                            ? finishNativePreparedCoordinates
+                                            : undefined,
+                                    }));
+                                if (!joinedPreparedFacts) {
+                                    await trustedLowerLog.join(materializeAllToMergeEntries(), {
+                                        __peerbitBatchIndependent: true,
+                                        __peerbitEntriesAlreadyMissing: true,
+                                        __peerbitCanAppendAlreadyValidated: fallbackCanAppendAlreadyValidated,
+                                        __peerbitDeferIndexWrite: true,
+                                        __peerbitOnAppendHashes: joinOnAppendHashes,
+                                        __peerbitProfile: syncProfile,
+                                    });
                                 }
-                                catch (error) {
-                                    this._coordinates.rollbackBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch);
-                                    throw error;
+                                // A recursive lower-log join can resolve successfully while declining
+                                // an individual top-level entry (for example, when one of its parents
+                                // is temporarily unavailable). The public Log.join() API intentionally
+                                // does not expose that per-entry result, so make local index presence the
+                                // authority before publishing any SharedLog-side effects. A successful
+                                // prepared-facts batch is atomic and already proves every input hash.
+                                const admittedHashes = joinedPreparedFacts
+                                    ? new Set(allToMergeHashes)
+                                    : await this.log.hasMany(allToMergeHashes);
+                                admittedMergeHashes = admittedHashes;
+                                const admittedShallowEntries = admittedHashes.size === allToMergeShallowEntries.length
+                                    ? allToMergeShallowEntries
+                                    : allToMergeShallowEntries.filter((entry) => admittedHashes.has(entry.hash));
+                                if (!joinedPreparedFacts) {
+                                    reusableCoordinatePersistItems =
+                                        reusableCoordinatePersistItems.filter((item) => admittedHashes.has(item.entry.hash));
+                                    coordinatePersistFallbackEntries =
+                                        coordinatePersistFallbackEntries.filter((entry) => admittedHashes.has(entry.hash));
                                 }
-                            }
-                            else {
-                                nativeBackboneOnlyPersistedHashes =
-                                    await this._coordinates.persistBackboneOnlyReceiveCoordinateBatch(reusableCoordinatePersistItems);
-                            }
-                            if (nativeBackboneOnlyPersistedHashes &&
-                                nativeBackboneOnlyPersistedHashes.size > 0) {
-                                for (let i = reusableCoordinatePersistItems.length - 1; i >= 0; i--) {
-                                    if (nativeBackboneOnlyPersistedHashes.has(reusableCoordinatePersistItems[i].entry.hash)) {
-                                        reusableCoordinatePersistItems.splice(i, 1);
+                                const reusableCoordinatePersistItemCount = reusableCoordinatePersistItems.length;
+                                if (syncProfile) {
+                                    emitSyncProfileDuration(syncProfile, lowerLogJoinStartedAt, {
+                                        name: "sharedLog.receive.lowerLogJoin",
+                                        component: "shared-log",
+                                        entries: allToMerge.length,
+                                        messages: 1,
+                                        details: {
+                                            hashOnlyEntryAdded,
+                                            batchHashOnlyEntryAdded,
+                                            programOnChange,
+                                            joinedPreparedFacts,
+                                            admittedEntries: admittedHashes.size,
+                                            nativePreparedCoordinatesFinished,
+                                        },
+                                    });
+                                }
+                                const coordinatePersistStartedAt = syncProfileStart(syncProfile);
+                                if (nativePreparedCoordinatesFinished) {
+                                    // The lower-log prepared receive transaction already finished
+                                    // the native coordinate mirror/journal after entry-index commit.
+                                }
+                                else if (nativePreparedCoordinateBatch) {
+                                    try {
+                                        nativeBackboneOnlyPersistedHashes =
+                                            await this._coordinates.finishBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch, syncProfile);
+                                    }
+                                    catch (error) {
+                                        this._coordinates.rollbackBackboneOnlyReceiveCoordinateBatch(nativePreparedCoordinateBatch);
+                                        throw error;
                                     }
                                 }
-                            }
-                            if (reusableCoordinatePersistItems.length > 0) {
-                                await this._coordinates.persistCoordinatesBatch(reusableCoordinatePersistItems);
-                            }
-                            if (coordinatePersistFallbackEntries.length > 0) {
-                                await this.planEntryLeaderBatch(coordinatePersistFallbackEntries.map((entry) => ({
-                                    entry,
-                                    replicas: receiveReplicaCounts.get(entry.hash) ??
-                                        decodeReplicas(entry).getValue(this),
-                                    options: { roleAge: 0, persist: {} },
-                                })));
-                            }
-                            if (syncProfile) {
-                                emitSyncProfileDuration(syncProfile, coordinatePersistStartedAt, {
-                                    name: "sharedLog.receive.coordinatePersist",
-                                    component: "shared-log",
-                                    entries: entriesToPersist.length,
-                                    messages: 1,
-                                    details: {
-                                        reusedLeaderPlans: reusableCoordinatePersistItemCount,
-                                        nativeBackboneOnly: nativeBackboneOnlyPersistedHashes?.size ?? 0,
-                                    },
-                                });
-                            }
-                            for (const hash of admittedHashes) {
-                                confirmedHashes.add(hash);
-                            }
-                            const checkedPruneStartedAt = syncProfileStart(syncProfile);
-                            const ownershipChangedDuringReceive = !this.isReceiveOwnershipSnapshotStable(receiveOwnershipRevision);
-                            if (ownershipChangedDuringReceive) {
-                                const freshAuditRevision = this._instanceLifecycle?._receiveOwnershipRevision ?? 0;
-                                const armFreshAuditRetry = () => {
-                                    for (const entry of admittedShallowEntries) {
-                                        this.scheduleCheckedPruneRetry({ entry, leaders: new Map() }, receiveOwnershipLifecycleController);
+                                else {
+                                    nativeBackboneOnlyPersistedHashes =
+                                        await this._coordinates.persistBackboneOnlyReceiveCoordinateBatch(reusableCoordinatePersistItems);
+                                }
+                                if (nativeBackboneOnlyPersistedHashes &&
+                                    nativeBackboneOnlyPersistedHashes.size > 0) {
+                                    for (let i = reusableCoordinatePersistItems.length - 1; i >= 0; i--) {
+                                        if (nativeBackboneOnlyPersistedHashes.has(reusableCoordinatePersistItems[i].entry.hash)) {
+                                            reusableCoordinatePersistItems.splice(i, 1);
+                                        }
                                     }
-                                };
-                                try {
+                                }
+                                if (reusableCoordinatePersistItems.length > 0) {
+                                    await this._coordinates.persistCoordinatesBatch(reusableCoordinatePersistItems);
+                                }
+                                if (coordinatePersistFallbackEntries.length > 0) {
+                                    await this.planEntryLeaderBatch(coordinatePersistFallbackEntries.map((entry) => ({
+                                        entry,
+                                        replicas: receiveReplicaCounts.get(entry.hash) ??
+                                            decodeReplicas(entry).getValue(this),
+                                        options: { roleAge: 0, persist: {} },
+                                    })));
+                                }
+                                if (syncProfile) {
+                                    emitSyncProfileDuration(syncProfile, coordinatePersistStartedAt, {
+                                        name: "sharedLog.receive.coordinatePersist",
+                                        component: "shared-log",
+                                        entries: entriesToPersist.length,
+                                        messages: 1,
+                                        details: {
+                                            reusedLeaderPlans: reusableCoordinatePersistItemCount,
+                                            nativeBackboneOnly: nativeBackboneOnlyPersistedHashes?.size ?? 0,
+                                        },
+                                    });
+                                }
+                                for (const hash of admittedHashes) {
+                                    confirmedHashes.add(hash);
+                                }
+                                const checkedPruneStartedAt = syncProfileStart(syncProfile);
+                                const ownershipChangedDuringReceive = !this.isReceiveOwnershipSnapshotStable(receiveOwnershipRevision);
+                                if (ownershipChangedDuringReceive) {
+                                    const freshAuditRevision = this._instanceLifecycle?._receiveOwnershipRevision ?? 0;
+                                    const armFreshAuditRetry = () => {
+                                        for (const entry of admittedShallowEntries) {
+                                            this.scheduleCheckedPruneRetry({ entry, leaders: new Map() }, receiveOwnershipLifecycleController);
+                                        }
+                                    };
+                                    try {
+                                        await this.pruneJoinedEntriesNoLongerLed(admittedShallowEntries, {
+                                            decodedReplicaCounts: receiveReplicaCounts,
+                                            freshReceiveOwnerAudit: true,
+                                            preserveExistingPruneOnLocalResult: true,
+                                            profile: syncProfile,
+                                        }, receiveOwnershipLifecycleController);
+                                        this.throwIfReplicationOwnershipLifecycleInactive(receiveOwnershipLifecycleController);
+                                        if (!this.isReceiveOwnershipSnapshotStable(freshAuditRevision)) {
+                                            armFreshAuditRetry();
+                                        }
+                                    }
+                                    catch {
+                                        // The lower-log and coordinate commits are already durable. A
+                                        // sender retry will filter these hashes as present, so retain a
+                                        // bounded local obligation instead of failing the admitted receive.
+                                        this.throwIfReplicationOwnershipLifecycleInactive(receiveOwnershipLifecycleController);
+                                        armFreshAuditRetry();
+                                    }
+                                }
+                                else {
                                     await this.pruneJoinedEntriesNoLongerLed(admittedShallowEntries, {
                                         decodedReplicaCounts: receiveReplicaCounts,
-                                        freshReceiveOwnerAudit: true,
                                         preserveExistingPruneOnLocalResult: true,
+                                        reusableLeaderPlans: reusableCoordinatePlans,
                                         profile: syncProfile,
                                     }, receiveOwnershipLifecycleController);
-                                    this.throwIfReplicationOwnershipLifecycleInactive(receiveOwnershipLifecycleController);
-                                    if (!this.isReceiveOwnershipSnapshotStable(freshAuditRevision)) {
-                                        armFreshAuditRetry();
-                                    }
                                 }
-                                catch {
-                                    // The lower-log and coordinate commits are already durable. A
-                                    // sender retry will filter these hashes as present, so retain a
-                                    // bounded local obligation instead of failing the admitted receive.
-                                    this.throwIfReplicationOwnershipLifecycleInactive(receiveOwnershipLifecycleController);
-                                    armFreshAuditRetry();
+                                if (syncProfile) {
+                                    emitSyncProfileDuration(syncProfile, checkedPruneStartedAt, {
+                                        name: "sharedLog.receive.checkedPrune",
+                                        component: "shared-log",
+                                        entries: allToMerge.length,
+                                        messages: 1,
+                                    });
                                 }
+                                for (const plan of joinPlans) {
+                                    plan.toDelete
+                                        ?.filter((entry) => admittedMergeHashes.has(entry.hash))
+                                        .map((entry) => this.pruneDebouncedFnAddIfNotKeeping({
+                                        key: entry.hash,
+                                        value: {
+                                            entry,
+                                            leaders: plan.leaders,
+                                        },
+                                    }));
+                                }
+                                this.rebalanceParticipationDebounced?.call();
                             }
-                            else {
-                                await this.pruneJoinedEntriesNoLongerLed(admittedShallowEntries, {
-                                    decodedReplicaCounts: receiveReplicaCounts,
-                                    preserveExistingPruneOnLocalResult: true,
-                                    reusableLeaderPlans: reusableCoordinatePlans,
-                                    profile: syncProfile,
-                                }, receiveOwnershipLifecycleController);
-                            }
-                            if (syncProfile) {
-                                emitSyncProfileDuration(syncProfile, checkedPruneStartedAt, {
-                                    name: "sharedLog.receive.checkedPrune",
-                                    component: "shared-log",
-                                    entries: allToMerge.length,
-                                    messages: 1,
-                                });
-                            }
-                            for (const plan of joinPlans) {
-                                plan.toDelete
-                                    ?.filter((entry) => admittedMergeHashes.has(entry.hash))
-                                    .map((entry) => this.pruneDebouncedFnAddIfNotKeeping({
-                                    key: entry.hash,
-                                    value: {
-                                        entry,
-                                        leaders: plan.leaders,
-                                    },
-                                }));
+                            finally {
+                                // Settle seam for the receive token. Every consumer that can
+                                // roll it back runs inline before control leaves this block: the
+                                // prepared-join callback resolves during the join await, and the
+                                // late finish/rollback arm runs above. This `finally` is what
+                                // closes the abandon arms (no prepared-join commit, a declined
+                                // native commit, a downgrade to the plain join) without having
+                                // to enumerate them.
+                                this._coordinates.settleResidentCoordinateSnapshot(nativeReceiveCoordinateBatch?.rollbackCoordinateEntries);
                             }
-                            this.rebalanceParticipationDebounced?.call();
                         }
                         for (const plan of joinPlans) {
                             if (!plan.maybeDelete) {