@peerbit/shared-log 16.0.2 → 16.0.4

package/dist/src/index.js

@@ -652,7 +652,58 @@ let SharedLog = (() => {
         uniqueReplicators;
         _replicatorJoinEmitted;
         /* private _totalParticipation!: number; */
-        // gid -> coordinate -> publicKeyHash list (of owners)
+        // gid -> set of publicKeyHashes known to hold that gid's entries.
+        //
+        // This is a suppression memo, not a source of truth. A present row lets the
+        // rebalance and repair paths skip re-sending an entry to a peer that already
+        // has it. Every read is `?.has(peer)` guarded, and a MISSING row always
+        // means "assume nothing is known", which produces strictly MORE work --
+        // redundant unchecked delivery in the rebalance loop, redundant queueing in
+        // the repair planner -- and never a wrong prune, a wrong quorum, or data
+        // loss. Losing a row costs bandwidth; keeping a stale row costs a little
+        // memory. That asymmetry is what the rest of this note turns on.
+        //
+        // GROWTH SHAPE. Rows are released by `deleteGidPeerHistory` on the two prune
+        // paths, by `removePeerFromGidPeerHistory` once a gid's last peer drops (the
+        // routine disconnect outcome), by `rebalanceAll({ clearCache: true })`, and
+        // wholesale on close/reset. Nothing on the TRIM path releases a row, so a
+        // node that bounds its log with trim rather than prune accumulates one row
+        // per distinct gid it has ever held. A gid names a graph, not an entry: an
+        // entry with `meta.next` inherits `min(next.meta.gid)` (see
+        // packages/log/src/entry-v0.ts), so document updates fold into the gid of
+        // the first put and the row count tracks distinct chain roots -- distinct
+        // document ids -- rather than entry count. Insert-only workloads mint a
+        // fresh gid per append and so do grow one row per entry. Merges are a
+        // smaller second source: when a join links two graphs the losing entries
+        // keep their own `meta.gid` on disk, and shared-log does not subscribe to
+        // the log's `onGidRemoved`, so the shadowed gid's row lingers too.
+        //
+        // WHY TRIM DOES NOT SIMPLY CALL `deleteGidPeerHistory` AS WELL. Both prune
+        // callers delete a whole row from a single entry's gid, and under the
+        // default hash domain that is correct by construction: the coordinate is a
+        // pure function of the gid (replication-domain-hash.ts sha256s
+        // `entry.meta.gid`), so identical gid => identical coordinates => identical
+        // leader set => every local sibling of that gid is prune-eligible in the
+        // same batch. The gid really is finished locally. Trim offers no such
+        // guarantee. It walks oldest-first against a length/bytelength/age bound and
+        // stops the instant the bound is met (packages/log/src/trim.ts); its only
+        // use of gid is memoizing the caller's `canTrim` verdict, never grouping
+        // deletes. So trim routinely removes the OLDEST entry of a gid while newer
+        // siblings -- same gid, same coordinates, still local, still replicated --
+        // remain. Copying the prune call onto trim would therefore delete a LIVE row
+        // on the common path, paying for the freed memory in repeated re-delivery of
+        // entries that are still here. That trade is not worth it.
+        //
+        // Bounding this correctly requires a per-gid count of locally held entries,
+        // dropping the row only when it reaches zero -- a real reverse index, not a
+        // one-line delete. Deliberately not built: the growth is bounded by distinct
+        // gids, and the cheap version is a bandwidth regression.
+        //
+        // Existing, deliberate imprecision: under the time domain the coordinate is
+        // `meta.clock.timestamp.wallTime` (replication-domain-time.ts) and is
+        // gid-independent, so siblings of one gid can carry different leader sets
+        // and prune's whole-row delete is already over-eager there. The cost is the
+        // same bounded extra traffic, never a wrong prune.
         _gidPeersHistory;
         _onSubscriptionFn;
         _onUnsubscriptionFn;
@@ -1518,8 +1569,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"
@@ -1537,6 +1603,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({
@@ -7081,10 +7150,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;
                 }
@@ -7105,6 +7179,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);
                         }
@@ -7164,6 +7241,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);
@@ -7466,6 +7549,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;
                     }
@@ -7533,6 +7620,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);
@@ -7594,6 +7683,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,
@@ -8148,6 +8241,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;
@@ -8170,6 +8265,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);
@@ -8260,6 +8357,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++) {
@@ -12925,221 +13025,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) {