@peerbit/native-backbone 0.2.9 → 0.2.11

package/dist/src/index.js

@@ -191,9 +191,9 @@ const nativeBackboneCoordinatePersistenceFiles = {
 };
 export const nativeBackboneCoordinateDropTombstoneFile = "native-backbone-drop.tombstone";
 export const defaultNativeBackboneCoordinateFlushMaxPendingBytes = 1024 * 1024;
-/** @deprecated Built-in coordinate persistence compaction is currently disabled. */
+/** Recommended explicit byte threshold for crash-safe Node checkpointing. */
 export const defaultNativeBackboneCoordinateCompactMaxJournalBytes = 64 * 1024 * 1024;
-const nativeBackboneCoordinateCompactionDisabledMessage = "Native backbone coordinate persistence compaction is disabled until snapshots use a crash-safe generation protocol";
+const nativeBackboneCoordinateCompactionDisabledMessage = "Native backbone coordinate persistence compaction is disabled for stores without crash-safe atomic replacement";
 const nativeBackboneCoordinateJournalMagic = Uint8Array.from([
     0x50, 0x42, 0x52, 0x49, 0x44, 0x58, 0x57, 0x31,
 ]);
@@ -209,6 +209,171 @@ const coordinateJournalChecksum = (bytes) => {
     }
     return checksum;
 };
+const nativeBackboneCoordinateCheckpointMagic = Uint8Array.from([
+    0x50, 0x42, 0x52, 0x49, 0x44, 0x58, 0x43, 0x31,
+]);
+const nativeBackboneCoordinateCheckpointStateMagic = Uint8Array.from([
+    0x50, 0x42, 0x52, 0x49, 0x44, 0x58, 0x53, 0x31,
+]);
+const nativeBackboneCoordinateLegacyMigrationSentinel = (() => {
+    const payload = Uint8Array.of(0xff);
+    const bytes = new Uint8Array(nativeBackboneCoordinateJournalMagic.byteLength + 8 + payload.byteLength);
+    bytes.set(nativeBackboneCoordinateJournalMagic, 0);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    view.setUint32(nativeBackboneCoordinateJournalMagic.byteLength, 1, true);
+    view.setUint32(nativeBackboneCoordinateJournalMagic.byteLength + 4, coordinateJournalChecksum(payload), true);
+    bytes.set(payload, nativeBackboneCoordinateJournalMagic.byteLength + 8);
+    return bytes;
+})();
+const nativeBackboneCoordinateCheckpointVersion = 1;
+const nativeBackboneCoordinateCheckpointHeaderBytes = 56;
+const nativeBackboneCoordinateCheckpointStateBytes = 60;
+const nativeBackboneCoordinateMaxU64 = (1n << 64n) - 1n;
+const hasBytesPrefix = (bytes, prefix) => bytes.byteLength >= prefix.byteLength &&
+    prefix.every((byte, index) => bytes[index] === byte);
+const writeCoordinateCheckpointU64 = (view, offset, value) => {
+    if (value < 0n || value > nativeBackboneCoordinateMaxU64) {
+        throw new RangeError("Native backbone checkpoint generation exceeds u64");
+    }
+    view.setUint32(offset, Number(value & 0xffffffffn), true);
+    view.setUint32(offset + 4, Number(value >> 32n), true);
+};
+const readCoordinateCheckpointU64 = (view, offset) => BigInt(view.getUint32(offset, true)) |
+    (BigInt(view.getUint32(offset + 4, true)) << 32n);
+const encodeNativeBackboneCoordinateCheckpoint = (checkpoint) => {
+    const coordinateLength = checkpoint.coordinateSnapshot.byteLength;
+    const documentLength = checkpoint.documentSnapshot.byteLength;
+    const signerLength = checkpoint.documentSignerSnapshot.byteLength;
+    const byteLength = nativeBackboneCoordinateCheckpointHeaderBytes +
+        coordinateLength +
+        documentLength +
+        signerLength;
+    if (!Number.isSafeInteger(byteLength) || byteLength > 0xffff_ffff) {
+        throw new RangeError("Native backbone coordinate checkpoint is too large");
+    }
+    const bytes = new Uint8Array(byteLength);
+    bytes.set(nativeBackboneCoordinateCheckpointMagic, 0);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    view.setUint32(8, nativeBackboneCoordinateCheckpointVersion, true);
+    view.setUint32(12, nativeBackboneCoordinateCheckpointHeaderBytes, true);
+    writeCoordinateCheckpointU64(view, 16, checkpoint.generation);
+    view.setUint32(24, coordinateLength, true);
+    view.setUint32(28, documentLength, true);
+    view.setUint32(32, signerLength, true);
+    view.setUint32(36, coordinateJournalChecksum(checkpoint.coordinateSnapshot), true);
+    view.setUint32(40, coordinateJournalChecksum(checkpoint.documentSnapshot), true);
+    view.setUint32(44, coordinateJournalChecksum(checkpoint.documentSignerSnapshot), true);
+    view.setUint32(48, checkpoint.configurationChecksum, true);
+    view.setUint32(52, coordinateJournalChecksum(bytes.subarray(8, 52)), true);
+    let offset = nativeBackboneCoordinateCheckpointHeaderBytes;
+    bytes.set(checkpoint.coordinateSnapshot, offset);
+    offset += coordinateLength;
+    bytes.set(checkpoint.documentSnapshot, offset);
+    offset += documentLength;
+    bytes.set(checkpoint.documentSignerSnapshot, offset);
+    return bytes;
+};
+const parseNativeBackboneCoordinateCheckpoint = (bytes, name) => {
+    if (bytes.byteLength < nativeBackboneCoordinateCheckpointHeaderBytes ||
+        !hasBytesPrefix(bytes, nativeBackboneCoordinateCheckpointMagic)) {
+        throw new Error(`Native backbone ${name} has an invalid checkpoint header`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8, true) !== nativeBackboneCoordinateCheckpointVersion ||
+        view.getUint32(12, true) !==
+            nativeBackboneCoordinateCheckpointHeaderBytes ||
+        view.getUint32(52, true) !==
+            coordinateJournalChecksum(bytes.subarray(8, 52))) {
+        throw new Error(`Native backbone ${name} has invalid checkpoint metadata`);
+    }
+    const coordinateLength = view.getUint32(24, true);
+    const documentLength = view.getUint32(28, true);
+    const signerLength = view.getUint32(32, true);
+    const expectedLength = nativeBackboneCoordinateCheckpointHeaderBytes +
+        coordinateLength +
+        documentLength +
+        signerLength;
+    if (!Number.isSafeInteger(expectedLength) ||
+        expectedLength !== bytes.byteLength) {
+        throw new Error(`Native backbone ${name} has an invalid checkpoint length`);
+    }
+    let offset = nativeBackboneCoordinateCheckpointHeaderBytes;
+    const coordinateSnapshot = bytes.subarray(offset, offset + coordinateLength);
+    offset += coordinateLength;
+    const documentSnapshot = bytes.subarray(offset, offset + documentLength);
+    offset += documentLength;
+    const documentSignerSnapshot = bytes.subarray(offset, offset + signerLength);
+    if (coordinateJournalChecksum(coordinateSnapshot) !==
+        view.getUint32(36, true) ||
+        coordinateJournalChecksum(documentSnapshot) !== view.getUint32(40, true) ||
+        coordinateJournalChecksum(documentSignerSnapshot) !==
+            view.getUint32(44, true)) {
+        throw new Error(`Native backbone ${name} has a checkpoint checksum mismatch`);
+    }
+    return {
+        configurationChecksum: view.getUint32(48, true),
+        generation: readCoordinateCheckpointU64(view, 16),
+        coordinateSnapshot,
+        documentSnapshot,
+        documentSignerSnapshot,
+    };
+};
+const encodeNativeBackboneCoordinateCheckpointState = (state) => {
+    const bytes = new Uint8Array(nativeBackboneCoordinateCheckpointStateBytes);
+    bytes.set(nativeBackboneCoordinateCheckpointStateMagic, 0);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    view.setUint32(8, nativeBackboneCoordinateCheckpointVersion, true);
+    view.setUint32(12, state.configurationChecksum, true);
+    writeCoordinateCheckpointU64(view, 16, state.highwater);
+    writeCoordinateCheckpointU64(view, 24, state.pending?.generation ?? 0n);
+    view.setUint32(32, state.pending?.byteLength ?? 0, true);
+    view.setUint32(36, state.pending?.checksum ?? 0, true);
+    writeCoordinateCheckpointU64(view, 40, state.completed?.generation ?? 0n);
+    view.setUint32(48, state.completed?.byteLength ?? 0, true);
+    view.setUint32(52, state.completed?.checksum ?? 0, true);
+    view.setUint32(56, coordinateJournalChecksum(bytes.subarray(8, 56)), true);
+    return bytes;
+};
+const parseNativeBackboneCoordinateCheckpointState = (bytes, name) => {
+    if (bytes.byteLength !== nativeBackboneCoordinateCheckpointStateBytes ||
+        !hasBytesPrefix(bytes, nativeBackboneCoordinateCheckpointStateMagic)) {
+        throw new Error(`Native backbone ${name} has an invalid checkpoint authority`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8, true) !== nativeBackboneCoordinateCheckpointVersion ||
+        view.getUint32(56, true) !==
+            coordinateJournalChecksum(bytes.subarray(8, 56))) {
+        throw new Error(`Native backbone ${name} has corrupt checkpoint authority`);
+    }
+    const configurationChecksum = view.getUint32(12, true);
+    const highwater = readCoordinateCheckpointU64(view, 16);
+    const pendingGeneration = readCoordinateCheckpointU64(view, 24);
+    const completedGeneration = readCoordinateCheckpointU64(view, 40);
+    const authority = (generation, lengthOffset, checksumOffset) => {
+        const byteLength = view.getUint32(lengthOffset, true);
+        const checksum = view.getUint32(checksumOffset, true);
+        if (generation === 0n) {
+            if (byteLength !== 0 || checksum !== 0) {
+                throw new Error(`Native backbone ${name} has empty authority metadata`);
+            }
+            return undefined;
+        }
+        if (byteLength < nativeBackboneCoordinateCheckpointHeaderBytes) {
+            throw new Error(`Native backbone ${name} has invalid authority length`);
+        }
+        return { generation, byteLength, checksum };
+    };
+    const pending = authority(pendingGeneration, 32, 36);
+    const completed = authority(completedGeneration, 48, 52);
+    if ((completed && completed.generation > highwater) ||
+        (pending && pending.generation !== highwater) ||
+        (pending && completed && pending.generation <= completed.generation) ||
+        (!pending && completed && completed.generation !== highwater) ||
+        (!pending && !completed && highwater !== 0n)) {
+        throw new Error(`Native backbone ${name} has invalid generation authority`);
+    }
+    return { configurationChecksum, highwater, pending, completed };
+};
 const hasCoordinateJournalMagic = (bytes) => bytes.byteLength >= nativeBackboneCoordinateJournalMagic.byteLength &&
     nativeBackboneCoordinateJournalMagic.every((byte, index) => bytes[index] === byte);
 /**
@@ -246,6 +411,12 @@ const resolveCoordinateFlushMaxPendingBytes = (options) => options.flushMaxPendi
     : options.flushOnAppend === false
         ? defaultNativeBackboneCoordinateFlushMaxPendingBytes
         : undefined;
+const validateCoordinateCompactionThreshold = (value, name) => {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`Native backbone ${name} must be a positive safe integer`);
+    }
+    return value;
+};
 const isNotFoundError = (error) => {
     const maybeError = error;
     return maybeError?.code === "ENOENT" || maybeError?.name === "NotFoundError";
@@ -656,7 +827,7 @@ const requestPruneEntryFromRow = (row) => {
     return entry;
 };
 const storageAppendResultFromRow = (resolution, row) => {
-    const [entryRow, leaderRows, isLeader, assignedToRangeBoundary, coordinateRow, trimRows, trimHashRows, documentTrimmedHeadsProcessed, documentPreviousContextRow,] = row;
+    const [entryRow, leaderRows, isLeader, assignedToRangeBoundary, coordinateRow, trimRows, trimHashRows, documentTrimmedHeadsProcessed, documentPreviousContextRow, _trimGidExtension, trimGidRows,] = row;
     return {
         entry: storageFactsEntryFromRow(entryRow),
         leaders: rowsToSamples(leaderRows),
@@ -664,12 +835,13 @@ const storageAppendResultFromRow = (resolution, row) => {
         assignedToRangeBoundary,
         coordinate: appendCoordinatePlanFromRow(resolution, coordinateRow),
         ...trimmedRowsAndHashesResult(trimRows, trimHashRows),
+        trimmedGids: trimGidRows ?? trimRows.map((trim) => trim[1]),
         documentTrimmedHeadsProcessed,
         documentPreviousContext: documentContextFactsFromRow(documentPreviousContextRow),
     };
 };
 const committedStorageAppendResultFromRow = (resolution, row) => {
-    const [entryRow, leaderRows, isLeader, assignedToRangeBoundary, coordinateRow, trimRows, trimHashRows, documentTrimmedHeadsProcessed, documentPreviousContextRow,] = row;
+    const [entryRow, leaderRows, isLeader, assignedToRangeBoundary, coordinateRow, trimRows, trimHashRows, documentTrimmedHeadsProcessed, documentPreviousContextRow, _trimGidExtension, trimGidRows,] = row;
     return {
         entry: committedStorageFactsEntryFromRow(entryRow),
         leaders: rowsToSamples(leaderRows),
@@ -677,15 +849,22 @@ const committedStorageAppendResultFromRow = (resolution, row) => {
         assignedToRangeBoundary,
         coordinate: appendCoordinatePlanFromRow(resolution, coordinateRow),
         ...trimmedRowsAndHashesResult(trimRows, trimHashRows),
+        trimmedGids: trimGidRows ?? trimRows.map((trim) => trim[1]),
         documentTrimmedHeadsProcessed,
         documentPreviousContext: documentContextFactsFromRow(documentPreviousContextRow),
     };
 };
 const compactCommittedNoNextStorageAppendResultFromRow = (resolution, row) => {
-    const [hash, byteLength, metaBytes, fourth] = row;
+    const appendedTrimGids = row.length >= 12 &&
+        row[row.length - 2] === undefined &&
+        Array.isArray(row[row.length - 1])
+        ? row[row.length - 1]
+        : undefined;
+    const baseRow = appendedTrimGids ? row.slice(0, -2) : row;
+    const [hash, byteLength, metaBytes, fourth] = baseRow;
     const hasDigestRow = fourth instanceof Uint8Array;
     const hashDigestBytes = hasDigestRow ? fourth : undefined;
-    const rest = row.slice(hasDigestRow ? 4 : 3);
+    const rest = baseRow.slice(hasDigestRow ? 4 : 3);
     const usesNestedCoordinateRow = Array.isArray(rest[0]);
     let coordinate;
     let leaderRows;
@@ -733,11 +912,18 @@ const compactCommittedNoNextStorageAppendResultFromRow = (resolution, row) => {
         coordinate,
         trimmed: [],
         trimmedHashes: trimHashRows ?? [],
+        trimmedGids: appendedTrimGids,
         documentTrimmedHeadsProcessed,
     };
 };
 const compactCommittedLatestStorageAppendResultFromRow = (resolution, row) => {
-    const [hash, byteLength, metaBytes, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth,] = row;
+    const appendedTrimGids = row.length >= 13 &&
+        row[row.length - 2] === undefined &&
+        Array.isArray(row[row.length - 1])
+        ? row[row.length - 1]
+        : undefined;
+    const baseRow = appendedTrimGids ? row.slice(0, -2) : row;
+    const [hash, byteLength, metaBytes, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth,] = baseRow;
     const hasDigestRow = fourth instanceof Uint8Array;
     const hashDigestBytes = hasDigestRow ? fourth : undefined;
     const next = (hasDigestRow ? fifth : fourth);
@@ -765,6 +951,7 @@ const compactCommittedLatestStorageAppendResultFromRow = (resolution, row) => {
         coordinate,
         trimmed: [],
         trimmedHashes: trimHashRows ?? [],
+        trimmedGids: appendedTrimGids,
         documentTrimmedHeadsProcessed,
         documentPreviousContext: documentContextFactsFromRow(documentPreviousContextRow),
     };
@@ -784,6 +971,14 @@ const preparedCommitFactsFromRow = (row) => {
     }
     return prepared;
 };
+const preparedCommitFactsWithTrimRefsFromRow = (row) => {
+    const prepared = committedStorageFactsEntryFromRow(row[0]);
+    return {
+        ...prepared,
+        trimmedEntryHashes: row[1],
+        trimmedEntryGids: row[2],
+    };
+};
 const preparedCommitFactsWithLatestDocumentContextFromRow = (row) => {
     const [entryRow, trimHashRows, documentTrimmedHeadsProcessed, contextRow] = row;
     return {
@@ -793,24 +988,53 @@ const preparedCommitFactsWithLatestDocumentContextFromRow = (row) => {
         documentPreviousContext: documentContextFactsFromRow(contextRow),
     };
 };
-const compactPreparedCommitFactsWithTrimHashesFromRow = (row) => {
+const preparedCommitFactsWithLatestDocumentContextAndTrimRefsFromRow = (row) => {
+    const [entryRow, trimHashRows, trimGidRows, documentTrimmedHeadsProcessed, contextRow,] = row;
+    return {
+        ...committedStorageFactsEntryFromRow(entryRow),
+        trimmedEntryHashes: trimHashRows,
+        trimmedEntryGids: trimGidRows,
+        documentTrimmedHeadsProcessed,
+        documentPreviousContext: documentContextFactsFromRow(contextRow),
+    };
+};
+const compactPreparedCommitFactsBaseFromRow = (row) => {
     const [hash, byteLength, metaBytes, fourth] = row;
     const hasDigestRow = fourth instanceof Uint8Array;
-    const hashDigestBytes = hasDigestRow ? fourth : undefined;
-    const trimHashOffset = hasDigestRow ? 4 : 3;
-    const trimHashRows = row[trimHashOffset];
-    const documentTrimmedHeadsProcessed = row[trimHashOffset + 1];
     return {
-        cid: hash,
-        hash,
-        next: [],
-        metaBytes,
-        byteLength,
-        hashDigestBytes,
+        entry: {
+            cid: hash,
+            hash,
+            next: [],
+            metaBytes,
+            byteLength,
+            hashDigestBytes: hasDigestRow ? fourth : undefined,
+        },
+        trimRowOffset: hasDigestRow ? 4 : 3,
+    };
+};
+const compactPreparedCommitFactsWithTrimHashesFromRow = (row) => {
+    const { entry, trimRowOffset } = compactPreparedCommitFactsBaseFromRow(row);
+    const trimHashRows = row[trimRowOffset];
+    const documentTrimmedHeadsProcessed = row[trimRowOffset + 1];
+    return {
+        ...entry,
         trimmedEntryHashes: trimHashRows ?? [],
         documentTrimmedHeadsProcessed,
     };
 };
+const compactPreparedCommitFactsWithTrimRefsFromRow = (row) => {
+    const { entry, trimRowOffset } = compactPreparedCommitFactsBaseFromRow(row);
+    const trimHashRows = row[trimRowOffset];
+    const trimGidRows = row[trimRowOffset + 1];
+    const documentTrimmedHeadsProcessed = row[trimRowOffset + 2];
+    return {
+        ...entry,
+        trimmedEntryHashes: trimHashRows,
+        trimmedEntryGids: trimGidRows,
+        documentTrimmedHeadsProcessed,
+    };
+};
 const nativeLogCommitEntryColumns = (entries) => {
     const hashes = new Array(entries.length);
     const blockBytes = new Array(entries.length);
@@ -1266,13 +1490,60 @@ class NativeBackboneLogGraph {
         const documentIndex = input.documentIndex;
         const documentIndexArgs = nativeDocumentIndexArgs(documentIndex);
         const projection = documentIndex?.projection;
+        if (!documentIndexArgs &&
+            input.resolveTrimmedEntries === false &&
+            input.trimLengthTo != null &&
+            this.native.prepare_plain_entry_commit_facts_trim_refs) {
+            return preparedCommitFactsWithTrimRefsFromRow(this.native.prepare_plain_entry_commit_facts_trim_refs(wallTime, logical, input.gid, input.next ?? [], entryType, input.metaData, input.payloadData, input.trimLengthTo));
+        }
         if (documentIndex?.useLatestContext &&
             documentIndexArgs &&
             input.resolveTrimmedEntries === false) {
             if (projection && this.options?.documentProjectionPlanId) {
-                return preparedCommitFactsWithLatestDocumentContextFromRow(this.native.prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_hashes(wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, documentIndex.key, documentIndex.byteElementIndexLimit ?? 0, documentIndex.deleteTrimmedHeads === true, this.options.documentProjectionPlanId(projection.plan), projection.encodedDocument, projection.signer));
+                const args = [
+                    wallTime,
+                    logical,
+                    input.gid,
+                    entryType,
+                    input.metaData,
+                    input.payloadData,
+                    input.trimLengthTo,
+                    documentIndex.key,
+                    documentIndex.byteElementIndexLimit ?? 0,
+                    documentIndex.deleteTrimmedHeads === true,
+                    this.options.documentProjectionPlanId(projection.plan),
+                    projection.encodedDocument,
+                    projection.signer,
+                ];
+                const prepareTrimRefs = this.native
+                    .prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_refs;
+                if (prepareTrimRefs) {
+                    return preparedCommitFactsWithLatestDocumentContextAndTrimRefsFromRow(prepareTrimRefs.call(this.native, ...args));
+                }
+                return preparedCommitFactsWithLatestDocumentContextFromRow(this.native.prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_hashes(...args));
+            }
+            const args = [
+                wallTime,
+                logical,
+                input.gid,
+                entryType,
+                input.metaData,
+                input.payloadData,
+                input.trimLengthTo,
+                documentIndex.key,
+                documentIndex.valuePrefixBytes ?? EMPTY_UINT8_ARRAY,
+                documentIndex.byteElementIndexLimit ?? 0,
+                documentIndex.deleteTrimmedHeads === true,
+                projection?.plan,
+                projection?.encodedDocument,
+                projection?.signer,
+            ];
+            const prepareTrimRefs = this.native
+                .prepare_plain_entry_commit_latest_facts_document_index_trim_refs;
+            if (prepareTrimRefs) {
+                return preparedCommitFactsWithLatestDocumentContextAndTrimRefsFromRow(prepareTrimRefs.call(this.native, ...args));
             }
-            return preparedCommitFactsWithLatestDocumentContextFromRow(this.native.prepare_plain_entry_commit_latest_facts_document_index_trim_hashes(wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, documentIndex.key, documentIndex.valuePrefixBytes ?? EMPTY_UINT8_ARRAY, documentIndex.byteElementIndexLimit ?? 0, documentIndex.deleteTrimmedHeads === true, projection?.plan, projection?.encodedDocument, projection?.signer));
+            return preparedCommitFactsWithLatestDocumentContextFromRow(this.native.prepare_plain_entry_commit_latest_facts_document_index_trim_hashes(...args));
         }
         if (documentIndexArgs &&
             projection &&
@@ -1281,16 +1552,57 @@ class NativeBackboneLogGraph {
             input.trimLengthTo != null &&
             hasNoNext) {
             const projectionPlanId = this.options.documentProjectionPlanId(projection.plan);
+            const plainPutPayloadArgs = [
+                wallTime,
+                logical,
+                input.gid,
+                entryType,
+                input.metaData,
+                input.payloadData,
+                input.trimLengthTo,
+                documentIndex.key,
+                documentIndex.existingCreated == null
+                    ? ""
+                    : integerString(documentIndex.existingCreated),
+                documentIndex.byteElementIndexLimit ?? 0,
+                documentIndex.deleteTrimmedHeads === true,
+                projectionPlanId,
+                projection.signer,
+            ];
+            const plainPutPayloadCommitWithTrimRefs = this.native
+                .prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_refs_plain_put_payload;
+            if (plainPutPayloadCommitWithTrimRefs) {
+                return compactPreparedCommitFactsWithTrimRefsFromRow(plainPutPayloadCommitWithTrimRefs.call(this.native, ...plainPutPayloadArgs));
+            }
             const plainPutPayloadCommit = this.native
                 .prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes_plain_put_payload;
             if (plainPutPayloadCommit) {
-                return compactPreparedCommitFactsWithTrimHashesFromRow(plainPutPayloadCommit.call(this.native, wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, documentIndex.key, documentIndex.existingCreated == null
+                return compactPreparedCommitFactsWithTrimHashesFromRow(plainPutPayloadCommit.call(this.native, ...plainPutPayloadArgs));
+            }
+            const args = [
+                wallTime,
+                logical,
+                input.gid,
+                entryType,
+                input.metaData,
+                input.payloadData,
+                input.trimLengthTo,
+                documentIndex.key,
+                documentIndex.existingCreated == null
                     ? ""
-                    : integerString(documentIndex.existingCreated), documentIndex.byteElementIndexLimit ?? 0, documentIndex.deleteTrimmedHeads === true, projectionPlanId, projection.signer));
+                    : integerString(documentIndex.existingCreated),
+                documentIndex.byteElementIndexLimit ?? 0,
+                documentIndex.deleteTrimmedHeads === true,
+                projectionPlanId,
+                projection.encodedDocument,
+                projection.signer,
+            ];
+            const prepareTrimRefs = this.native
+                .prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_refs;
+            if (prepareTrimRefs) {
+                return compactPreparedCommitFactsWithTrimRefsFromRow(prepareTrimRefs.call(this.native, ...args));
             }
-            return compactPreparedCommitFactsWithTrimHashesFromRow(this.native.prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes(wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, documentIndex.key, documentIndex.existingCreated == null
-                ? ""
-                : integerString(documentIndex.existingCreated), documentIndex.byteElementIndexLimit ?? 0, documentIndex.deleteTrimmedHeads === true, projectionPlanId, projection.encodedDocument, projection.signer));
+            return compactPreparedCommitFactsWithTrimHashesFromRow(this.native.prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes(...args));
         }
         if (documentIndexArgs &&
             projection &&
@@ -1333,6 +1645,11 @@ class NativeBackboneLogGraph {
             input.resolveTrimmedEntries === false &&
             input.trimLengthTo != null &&
             hasNoNext) {
+            const prepareTrimRefs = this.native
+                .prepare_plain_entry_commit_no_next_facts_document_index_compact_trim_refs;
+            if (prepareTrimRefs) {
+                return compactPreparedCommitFactsWithTrimRefsFromRow(prepareTrimRefs.call(this.native, wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, ...documentIndexArgs));
+            }
             return compactPreparedCommitFactsWithTrimHashesFromRow(this.native.prepare_plain_entry_commit_no_next_facts_document_index_compact_trim_hashes(wallTime, logical, input.gid, entryType, input.metaData, input.payloadData, input.trimLengthTo, ...documentIndexArgs));
         }
         const baseArgs = [
@@ -2263,6 +2580,12 @@ export class NativePeerbitBackbone {
     fullReplicaCandidatesFor(minReplicas, selfHash) {
         return this.native.full_replica_candidates_for(minReplicas, selfHash);
     }
+    getRoutingFullReplicaLeaders(replicas, options) {
+        if (!this.native.get_routing_full_replica_leaders) {
+            return undefined;
+        }
+        return rowsToSamples(this.native.get_routing_full_replica_leaders(replicas, ...findLeaderArguments(options)));
+    }
     clearEntryCoordinates() {
         this.native.clear_entry_coordinates();
     }
@@ -3016,6 +3339,7 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
     appendFailure;
     readLimited;
     durableBarrier;
+    atomicReplace;
     constructor(directory, fs) {
         this.directory = directory;
         this.fs = fs;
@@ -3028,6 +3352,10 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
         if (!fs || typeof fs.openBoundedRead === "function") {
             this.readLimited = (name, maxBytes) => this.readWithinLimit(name, maxBytes);
         }
+        if (!fs ||
+            (typeof fs.open === "function" && typeof fs.rename === "function")) {
+            this.atomicReplace = (name, bytes) => this.replaceAtomically(name, bytes);
+        }
     }
     async nodeFs() {
         return this.fs ?? (await importNodeFs());
@@ -3159,6 +3487,43 @@ export class NativeBackboneNodeCoordinatePersistenceStore {
         await this.closeAppendHandle(path);
         await fs.writeFile(path, bytes);
     }
+    async replaceAtomically(name, bytes) {
+        const fs = await this.ensureDirectory();
+        if (!fs.open || !fs.rename) {
+            throw new Error("Node coordinate persistence does not expose atomic file replacement");
+        }
+        const validName = validateCoordinatePersistenceName(name);
+        const temporaryName = validateCoordinatePersistenceName(`${validName}.tmp`);
+        const path = await this.filePath(validName);
+        const temporaryPath = await this.filePath(temporaryName);
+        await this.closeAppendHandle(path);
+        await this.closeAppendHandle(temporaryPath);
+        await fs.rm(temporaryPath, { force: true });
+        await fs.writeFile(temporaryPath, bytes);
+        let temporaryHandle;
+        try {
+            temporaryHandle = await fs.open(temporaryPath, "r");
+            if (typeof temporaryHandle.sync !== "function") {
+                throw new Error("Node coordinate persistence atomic replacement does not expose FileHandle.sync");
+            }
+            await temporaryHandle.sync();
+        }
+        finally {
+            await temporaryHandle?.close();
+        }
+        await fs.rename(temporaryPath, path);
+        let directoryHandle;
+        try {
+            directoryHandle = await fs.open(this.directory, "r");
+            if (typeof directoryHandle.sync !== "function") {
+                throw new Error("Node coordinate persistence atomic replacement does not expose directory sync");
+            }
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle?.close();
+        }
+    }
     async append(name, bytes) {
         if (this.appendFailure !== undefined) {
             throw this.appendFailure;
@@ -3458,6 +3823,7 @@ export class NativeBackboneBufferedCoordinatePersistenceStore {
     readLimited;
     supportsRemoval;
     durableBarrier;
+    atomicReplace;
     constructor(inner, options = {}) {
         this.inner = inner;
         this.options = options;
@@ -3473,6 +3839,12 @@ export class NativeBackboneBufferedCoordinatePersistenceStore {
                 await inner.durableBarrier(name);
             };
         }
+        if (typeof inner.atomicReplace === "function") {
+            this.atomicReplace = async (name, bytes) => {
+                await this.flush(name);
+                await inner.atomicReplace(name, bytes);
+            };
+        }
     }
     buffer(name) {
         const validName = validateCoordinatePersistenceName(name);
@@ -3589,7 +3961,7 @@ export class NativeBackboneCoordinatePersistence {
     flushIntervalMs;
     compactMaxJournalBytes;
     compactMaxJournalRecords;
-    crashSafeCompaction = false;
+    crashSafeCompaction;
     durableBarrier;
     supportsDrop;
     dropIsTerminal = true;
@@ -3599,9 +3971,22 @@ export class NativeBackboneCoordinatePersistence {
     documentJournalFile;
     documentSignerSnapshotFile;
     documentSignerJournalFile;
+    checkpointConfigurationChecksum;
+    checkpointStateFile;
+    checkpointFiles;
+    checkpointJournalFiles;
     journalInitialized;
+    journalByteLength = 0;
+    journalRecordCount = 0;
     documentJournalInitialized;
+    documentJournalByteLength = 0;
+    documentJournalRecordCount = 0;
     documentSignerJournalInitialized;
+    documentSignerJournalByteLength = 0;
+    documentSignerJournalRecordCount = 0;
+    checkpointHighwater = 0n;
+    checkpointCompleted;
+    checkpointPending;
     lastFlushMs = Date.now();
     persistenceQueue;
     persistenceLifecycle = "active";
@@ -3627,24 +4012,61 @@ export class NativeBackboneCoordinatePersistence {
             nativeBackboneCoordinatePersistenceFiles.documentSignerSnapshot);
         this.documentSignerJournalFile = validateCoordinatePersistenceName(options.documentSignerJournal ??
             nativeBackboneCoordinatePersistenceFiles.documentSignerJournal);
-        if (this.configuredFiles().includes(nativeBackboneCoordinateDropTombstoneFile)) {
-            throw new Error("Native backbone coordinate persistence file conflicts with its drop tombstone");
-        }
+        this.checkpointConfigurationChecksum = coordinateJournalChecksum(new TextEncoder().encode(JSON.stringify([
+            this.snapshotFile,
+            this.journalFile,
+            this.documentSnapshotFile,
+            this.documentJournalFile,
+            this.documentSignerSnapshotFile,
+            this.documentSignerJournalFile,
+        ])));
+        this.checkpointStateFile = validateCoordinatePersistenceName(`${this.snapshotFile}.checkpoint-state`);
+        this.checkpointFiles = {
+            a: validateCoordinatePersistenceName(`${this.snapshotFile}.checkpoint-a`),
+            b: validateCoordinatePersistenceName(`${this.snapshotFile}.checkpoint-b`),
+        };
+        this.checkpointJournalFiles = {
+            a: {
+                coordinate: validateCoordinatePersistenceName(`${this.journalFile}.checkpoint-a`),
+                document: validateCoordinatePersistenceName(`${this.documentJournalFile}.checkpoint-a`),
+                signer: validateCoordinatePersistenceName(`${this.documentSignerJournalFile}.checkpoint-a`),
+            },
+            b: {
+                coordinate: validateCoordinatePersistenceName(`${this.journalFile}.checkpoint-b`),
+                document: validateCoordinatePersistenceName(`${this.documentJournalFile}.checkpoint-b`),
+                signer: validateCoordinatePersistenceName(`${this.documentSignerJournalFile}.checkpoint-b`),
+            },
+        };
+        if (this.configuredFiles().includes(nativeBackboneCoordinateDropTombstoneFile) ||
+            new Set(this.configuredFiles()).size !== this.configuredFiles().length) {
+            throw new Error("Native backbone coordinate persistence files conflict with one another or with its drop tombstone");
+        }
+        this.crashSafeCompaction =
+            typeof store.atomicReplace === "function" &&
+                this.supportsDrop &&
+                this.durableBarrier;
         this.flushOnAppend = options.flushOnAppend ?? true;
         this.flushMaxPendingBytes = resolveCoordinateFlushMaxPendingBytes(options);
         if (options.flushIntervalMs != null) {
             this.flushIntervalMs = Math.max(0, options.flushIntervalMs);
         }
-        if (options.compactMaxJournalBytes != null ||
-            options.compactMaxJournalRecords != null) {
+        if ((options.compactMaxJournalBytes != null ||
+            options.compactMaxJournalRecords != null) &&
+            !this.crashSafeCompaction) {
             throw new Error(nativeBackboneCoordinateCompactionDisabledMessage);
         }
+        if (options.compactMaxJournalBytes != null) {
+            this.compactMaxJournalBytes = validateCoordinateCompactionThreshold(options.compactMaxJournalBytes, "compactMaxJournalBytes");
+        }
+        if (options.compactMaxJournalRecords != null) {
+            this.compactMaxJournalRecords = validateCoordinateCompactionThreshold(options.compactMaxJournalRecords, "compactMaxJournalRecords");
+        }
     }
     /** Durable operation-intent capability for strict shared-log transactions. */
     get intentStore() {
         return this.store;
     }
-    configuredFiles() {
+    legacyConfiguredFiles() {
         return [
             this.snapshotFile,
             this.journalFile,
@@ -3654,26 +4076,79 @@ export class NativeBackboneCoordinatePersistence {
             this.documentSignerJournalFile,
         ];
     }
+    configuredFiles() {
+        return [
+            ...this.legacyConfiguredFiles(),
+            this.checkpointStateFile,
+            this.checkpointFiles.a,
+            this.checkpointFiles.b,
+            this.checkpointJournalFiles.a.coordinate,
+            this.checkpointJournalFiles.a.document,
+            this.checkpointJournalFiles.a.signer,
+            this.checkpointJournalFiles.b.coordinate,
+            this.checkpointJournalFiles.b.document,
+            this.checkpointJournalFiles.b.signer,
+            `${this.checkpointStateFile}.tmp`,
+            `${this.checkpointFiles.a}.tmp`,
+            `${this.checkpointFiles.b}.tmp`,
+            `${this.journalFile}.tmp`,
+            `${nativeBackboneCoordinateDropTombstoneFile}.tmp`,
+        ];
+    }
+    checkpointSlot(generation) {
+        return generation % 2n === 1n ? "a" : "b";
+    }
+    activeJournalFiles() {
+        const completed = this.checkpointCompleted;
+        return completed
+            ? this.checkpointJournalFiles[this.checkpointSlot(completed.generation)]
+            : {
+                coordinate: this.journalFile,
+                document: this.documentJournalFile,
+                signer: this.documentSignerJournalFile,
+            };
+    }
     assertLifecycleActive(operation) {
         if (this.persistenceLifecycle !== "active") {
             throw new Error(`Native backbone coordinate persistence can not ${operation} while ${this.persistenceLifecycle}`);
         }
     }
     assertActive(operation) {
-        if (this.persistenceFailure !== undefined) {
-            throw this.persistenceFailure;
-        }
+        this.assertPersistenceHealthy();
         this.assertLifecycleActive(operation);
         if (this.dropInitiatedOnGeneration) {
             throw new Error(`Native backbone coordinate persistence can not ${operation} after drop was initiated; retry drop or resume drop first`);
         }
     }
+    assertPersistenceHealthy() {
+        if (this.persistenceFailure !== undefined) {
+            throw this.persistenceFailure;
+        }
+    }
     resetJournalTracking() {
         this.journalInitialized = undefined;
+        this.journalByteLength = 0;
+        this.journalRecordCount = 0;
         this.documentJournalInitialized = undefined;
+        this.documentJournalByteLength = 0;
+        this.documentJournalRecordCount = 0;
         this.documentSignerJournalInitialized = undefined;
+        this.documentSignerJournalByteLength = 0;
+        this.documentSignerJournalRecordCount = 0;
+        this.checkpointHighwater = 0n;
+        this.checkpointCompleted = undefined;
+        this.checkpointPending = undefined;
         this.lastFlushMs = Date.now();
     }
+    async persistDropTombstone(files, preferAtomicReplace = false) {
+        const bytes = nativeBackboneCoordinateDropTombstoneBytes(files);
+        if (preferAtomicReplace && this.store.atomicReplace) {
+            await this.store.atomicReplace(nativeBackboneCoordinateDropTombstoneFile, bytes);
+            return;
+        }
+        await this.store.write(nativeBackboneCoordinateDropTombstoneFile, bytes);
+        await this.barrierFile(nativeBackboneCoordinateDropTombstoneFile);
+    }
     async eraseDropFiles(files) {
         if (!this.supportsDrop || !this.store.remove) {
             throw new Error("Native backbone coordinate persistence store does not support removal");
@@ -3709,13 +4184,7 @@ export class NativeBackboneCoordinatePersistence {
         this.dropInitiatedOnGeneration = true;
         this.persistenceLifecycle = "dropping";
         await this.enqueuePersistence(async () => {
-            await this.store.write(nativeBackboneCoordinateDropTombstoneFile, nativeBackboneCoordinateDropTombstoneBytes(files));
-            if (this.store.durableBarrier) {
-                await this.store.durableBarrier(nativeBackboneCoordinateDropTombstoneFile);
-            }
-            else {
-                await this.store.flush?.(nativeBackboneCoordinateDropTombstoneFile);
-            }
+            await this.persistDropTombstone(files);
             await this.eraseDropFiles(files);
             this.resetJournalTracking();
             this.persistenceLifecycle = "dropped";
@@ -3748,6 +4217,43 @@ export class NativeBackboneCoordinatePersistence {
             return this.resumeDropInternal(completesInitiatedDrop ? "dropped" : "active");
         });
     }
+    async barrierFile(name) {
+        if (this.store.durableBarrier) {
+            await this.store.durableBarrier(name);
+        }
+        else {
+            await this.store.flush?.(name);
+        }
+    }
+    async hasDurableLegacyMigrationSentinel() {
+        const existing = await this.store.read(this.journalFile);
+        if (existing &&
+            existing.byteLength ===
+                nativeBackboneCoordinateLegacyMigrationSentinel.byteLength &&
+            nativeBackboneCoordinateLegacyMigrationSentinel.every((byte, index) => existing[index] === byte)) {
+            // A previous process may have observed the bytes from page cache before
+            // its durability barrier rejected. Cross a fresh barrier on every reopen
+            // before any post-checkpoint WAL append can be admitted.
+            await this.barrierFile(this.journalFile);
+            return true;
+        }
+        return false;
+    }
+    async installLegacyMigrationSentinel() {
+        if (await this.hasDurableLegacyMigrationSentinel()) {
+            return;
+        }
+        if (!this.store.atomicReplace) {
+            throw new Error("Native backbone completed checkpoint can not install its downgrade sentinel atomically");
+        }
+        await this.store.atomicReplace(this.journalFile, nativeBackboneCoordinateLegacyMigrationSentinel);
+    }
+    async requireLegacyMigrationSentinel() {
+        if (await this.hasDurableLegacyMigrationSentinel()) {
+            return;
+        }
+        throw new Error("Native backbone completed checkpoint downgrade sentinel is missing or has been replaced; refusing to overwrite possible legacy writes");
+    }
     async hydrate(backbone) {
         this.assertActive("hydrate");
         // Claim the lifecycle synchronously. close() queues after this complete
@@ -3758,24 +4264,147 @@ export class NativeBackboneCoordinatePersistence {
                 this.assertHydrating();
                 await this.resumeDropInternal("hydrating");
                 this.assertHydrating();
-                const [snapshot, journal, documentSnapshot, documentJournal, documentSignerSnapshot, documentSignerJournal,] = await Promise.all([
-                    this.store.read(this.snapshotFile),
-                    this.store.read(this.journalFile),
-                    this.store.read(this.documentSnapshotFile),
-                    this.store.read(this.documentJournalFile),
-                    this.store.read(this.documentSignerSnapshotFile),
-                    this.store.read(this.documentSignerJournalFile),
-                ]);
+                const checkpointStateBytes = await this.store.read(this.checkpointStateFile);
                 this.assertHydrating();
+                let checkpointState;
+                if (checkpointStateBytes) {
+                    try {
+                        checkpointState = parseNativeBackboneCoordinateCheckpointState(checkpointStateBytes, this.checkpointStateFile);
+                        if (checkpointState.configurationChecksum !==
+                            this.checkpointConfigurationChecksum) {
+                            throw new Error("Native backbone checkpoint authority does not match the configured persistence files");
+                        }
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
+                this.checkpointHighwater = checkpointState?.highwater ?? 0n;
+                this.checkpointPending = checkpointState?.pending;
+                this.checkpointCompleted = checkpointState?.completed;
+                let checkpointAuthority = this.checkpointCompleted;
+                let promotePendingCheckpoint = false;
+                if (!checkpointAuthority && this.checkpointPending) {
+                    try {
+                        // On the first generation only, the sentinel is the durable stage
+                        // boundary: publication writes it after the pending checkpoint and its
+                        // WAL headers, but before completed authority. A pre-checkpoint reader
+                        // can no longer consume legacy state, so recovery may validate and
+                        // promote the staged generation. Once a completed generation exists the
+                        // sentinel predates later pending work and is not a promotion signal.
+                        if (await this.hasDurableLegacyMigrationSentinel()) {
+                            checkpointAuthority = this.checkpointPending;
+                            promotePendingCheckpoint = true;
+                        }
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
+                let snapshot;
+                let journal;
+                let documentSnapshot;
+                let documentJournal;
+                let documentSignerSnapshot;
+                let documentSignerJournal;
+                let journalNames = {
+                    coordinate: this.journalFile,
+                    document: this.documentJournalFile,
+                    signer: this.documentSignerJournalFile,
+                };
+                if (checkpointAuthority) {
+                    const authority = checkpointAuthority;
+                    const authorityKind = promotePendingCheckpoint
+                        ? "promotable pending"
+                        : "completed";
+                    const slot = this.checkpointSlot(authority.generation);
+                    const checkpointFile = this.checkpointFiles[slot];
+                    journalNames = this.checkpointJournalFiles[slot];
+                    const [checkpointBytes, coordinateJournal, valueJournal, signerJournal,] = await Promise.all([
+                        this.store.read(checkpointFile),
+                        this.store.read(journalNames.coordinate),
+                        this.store.read(journalNames.document),
+                        this.store.read(journalNames.signer),
+                    ]);
+                    this.assertHydrating();
+                    try {
+                        if (!checkpointBytes ||
+                            checkpointBytes.byteLength !== authority.byteLength ||
+                            coordinateJournalChecksum(checkpointBytes) !== authority.checksum) {
+                            throw new Error(`Native backbone ${authorityKind} checkpoint authority is missing or corrupt`);
+                        }
+                        if (!coordinateJournal || !valueJournal || !signerJournal) {
+                            throw new Error(`Native backbone ${authorityKind} checkpoint WAL generation is incomplete`);
+                        }
+                        const checkpoint = parseNativeBackboneCoordinateCheckpoint(checkpointBytes, checkpointFile);
+                        if (checkpoint.generation !== authority.generation ||
+                            checkpoint.configurationChecksum !==
+                                this.checkpointConfigurationChecksum) {
+                            throw new Error(`Native backbone checkpoint generation or configuration does not match its ${authorityKind} authority`);
+                        }
+                        snapshot = checkpoint.coordinateSnapshot;
+                        documentSnapshot = checkpoint.documentSnapshot;
+                        documentSignerSnapshot = checkpoint.documentSignerSnapshot;
+                        journal = coordinateJournal;
+                        documentJournal = valueJournal;
+                        documentSignerJournal = signerJournal;
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
+                else {
+                    [
+                        snapshot,
+                        journal,
+                        documentSnapshot,
+                        documentJournal,
+                        documentSignerSnapshot,
+                        documentSignerJournal,
+                    ] = await Promise.all([
+                        this.store.read(this.snapshotFile),
+                        this.store.read(this.journalFile),
+                        this.store.read(this.documentSnapshotFile),
+                        this.store.read(this.documentJournalFile),
+                        this.store.read(this.documentSignerSnapshotFile),
+                        this.store.read(this.documentSignerJournalFile),
+                    ]);
+                    this.assertHydrating();
+                }
                 try {
-                    validateCoordinateJournal(journal, this.journalFile);
-                    validateCoordinateJournal(documentJournal, this.documentJournalFile);
-                    validateCoordinateJournal(documentSignerJournal, this.documentSignerJournalFile);
+                    if (checkpointAuthority &&
+                        (!journal ||
+                            !hasCoordinateJournalMagic(journal) ||
+                            !documentJournal ||
+                            !hasCoordinateJournalMagic(documentJournal) ||
+                            !documentSignerJournal ||
+                            !hasCoordinateJournalMagic(documentSignerJournal))) {
+                        throw new Error(`Native backbone ${promotePendingCheckpoint ? "promotable pending" : "completed"} checkpoint WAL generation has a missing or invalid header`);
+                    }
+                    validateCoordinateJournal(journal, journalNames.coordinate);
+                    validateCoordinateJournal(documentJournal, journalNames.document);
+                    validateCoordinateJournal(documentSignerJournal, journalNames.signer);
                 }
                 catch (error) {
                     this.persistenceFailure ??= error;
                     throw this.persistenceFailure;
                 }
+                if (checkpointAuthority && !promotePendingCheckpoint) {
+                    try {
+                        // Completed authority is never permission to overwrite an ordinary
+                        // legacy WAL: it may contain writes made by a downgraded process in the
+                        // publication cut. Require the exact durable sentinel before loading.
+                        await this.requireLegacyMigrationSentinel();
+                        this.assertHydrating();
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
                 let operations;
                 let documentOperations;
                 let documentSignerOperations;
@@ -3797,12 +4426,49 @@ export class NativeBackboneCoordinatePersistence {
                     }
                     throw error;
                 }
+                if (promotePendingCheckpoint) {
+                    try {
+                        const authority = checkpointAuthority;
+                        if (!this.store.atomicReplace) {
+                            throw new Error("Native backbone pending checkpoint can not publish completed authority atomically");
+                        }
+                        await this.store.atomicReplace(this.checkpointStateFile, encodeNativeBackboneCoordinateCheckpointState({
+                            configurationChecksum: this.checkpointConfigurationChecksum,
+                            highwater: authority.generation,
+                            completed: authority,
+                        }));
+                        this.checkpointCompleted = authority;
+                        this.checkpointPending = undefined;
+                        this.assertHydrating();
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
+                if (this.checkpointCompleted || this.checkpointPending) {
+                    try {
+                        await this.cleanupRetiredCheckpointFiles();
+                        this.assertHydrating();
+                    }
+                    catch (error) {
+                        this.persistenceFailure ??= error;
+                        throw this.persistenceFailure;
+                    }
+                }
                 this.assertHydrating();
                 this.journalInitialized = !!journal && journal.byteLength > 0;
+                this.journalByteLength = journal?.byteLength ?? 0;
+                this.journalRecordCount = operations;
                 this.documentJournalInitialized =
                     !!documentJournal && documentJournal.byteLength > 0;
+                this.documentJournalByteLength = documentJournal?.byteLength ?? 0;
+                this.documentJournalRecordCount = documentOperations;
                 this.documentSignerJournalInitialized =
                     !!documentSignerJournal && documentSignerJournal.byteLength > 0;
+                this.documentSignerJournalByteLength =
+                    documentSignerJournal?.byteLength ?? 0;
+                this.documentSignerJournalRecordCount = documentSignerOperations;
                 backbone.setCoordinateJournalEnabled(true);
                 backbone.setDocumentJournalEnabled(true);
                 backbone.setDocumentSignerJournalEnabled(true);
@@ -3838,13 +4504,17 @@ export class NativeBackboneCoordinatePersistence {
             return false;
         }
         let tombstone;
+        let expandedFiles;
         try {
             tombstone = parseNativeBackboneCoordinateDropTombstone(bytes);
-            for (const file of this.configuredFiles()) {
+            for (const file of this.legacyConfiguredFiles()) {
                 if (!tombstone.files.includes(file)) {
                     throw new Error("Native backbone drop tombstone does not cover the configured namespace");
                 }
             }
+            expandedFiles = [
+                ...new Set([...tombstone.files, ...this.configuredFiles()]),
+            ];
         }
         catch (error) {
             // Corruption must never hydrate stale files, but an explicit drop must
@@ -3853,6 +4523,17 @@ export class NativeBackboneCoordinatePersistence {
             this.persistenceLifecycle = this.closePromise ? "closing" : "active";
             throw this.persistenceFailure;
         }
+        if (expandedFiles.length !== tombstone.files.length) {
+            // Older valid markers only knew the six snapshot/WAL files. Widen the
+            // destructive intent durably before erasing any checkpoint generation,
+            // while preserving additional namespace files recorded by that version.
+            await this.persistDropTombstone(expandedFiles, true);
+            tombstone = { ...tombstone, files: expandedFiles };
+        }
+        // A prior replacement attempt may have made the expanded bytes visible before
+        // its durability barrier rejected. Cross a fresh barrier on every recovery
+        // before allowing any target removal.
+        await this.barrierFile(nativeBackboneCoordinateDropTombstoneFile);
         await this.eraseDropFiles(tombstone.files);
         this.resetJournalTracking();
         this.persistenceLifecycle =
@@ -3896,7 +4577,13 @@ export class NativeBackboneCoordinatePersistence {
         this.assertActive("flush");
         // Serialized with compact() so a flush never clears records appended to
         // the wasm journal while a previous flush was awaiting its disk write.
-        return this.enqueuePersistence(() => this.flushJournalInternal(backbone));
+        return this.enqueuePersistence(() => {
+            // A call can be admitted while an earlier queued write is still in flight.
+            // Re-check the sticky failure at execution time so no suffix can ACK after
+            // that earlier write or authority switch failed.
+            this.assertPersistenceHealthy();
+            return this.flushJournalInternal(backbone);
+        });
     }
     enqueuePersistence(fn) {
         // Runs `fn` immediately when no other persistence operation is in
@@ -3912,7 +4599,151 @@ export class NativeBackboneCoordinatePersistence {
         });
         return next;
     }
-    async flushJournalInternal(backbone) {
+    shouldCompactJournal(additionalBytes, additionalRecords) {
+        return ((this.compactMaxJournalBytes != null &&
+            this.journalByteLength +
+                this.documentJournalByteLength +
+                this.documentSignerJournalByteLength +
+                additionalBytes >=
+                this.compactMaxJournalBytes) ||
+            (this.compactMaxJournalRecords != null &&
+                this.journalRecordCount +
+                    this.documentJournalRecordCount +
+                    this.documentSignerJournalRecordCount +
+                    additionalRecords >=
+                    this.compactMaxJournalRecords));
+    }
+    nextCheckpointGeneration() {
+        let generation = this.checkpointHighwater + 1n;
+        const active = this.checkpointCompleted;
+        if (active &&
+            this.checkpointSlot(generation) === this.checkpointSlot(active.generation)) {
+            generation += 1n;
+        }
+        if (generation > nativeBackboneCoordinateMaxU64) {
+            throw new RangeError("Native backbone checkpoint generation highwater is exhausted");
+        }
+        return generation;
+    }
+    async publishCheckpoint(checkpoint) {
+        if (!this.crashSafeCompaction ||
+            !this.store.atomicReplace ||
+            !this.store.remove) {
+            throw new Error(nativeBackboneCoordinateCompactionDisabledMessage);
+        }
+        const generation = this.nextCheckpointGeneration();
+        const slot = this.checkpointSlot(generation);
+        const checkpointBytes = encodeNativeBackboneCoordinateCheckpoint({
+            configurationChecksum: this.checkpointConfigurationChecksum,
+            generation,
+            ...checkpoint,
+        });
+        const authority = {
+            generation,
+            byteLength: checkpointBytes.byteLength,
+            checksum: coordinateJournalChecksum(checkpointBytes),
+        };
+        const pendingState = {
+            configurationChecksum: this.checkpointConfigurationChecksum,
+            highwater: generation,
+            pending: authority,
+            completed: this.checkpointCompleted,
+        };
+        await this.store.atomicReplace(this.checkpointStateFile, encodeNativeBackboneCoordinateCheckpointState(pendingState));
+        this.checkpointHighwater = generation;
+        this.checkpointPending = authority;
+        const targetJournals = this.checkpointJournalFiles[slot];
+        for (const file of [
+            targetJournals.coordinate,
+            targetJournals.document,
+            targetJournals.signer,
+        ]) {
+            await this.store.remove(file);
+        }
+        const journalHeaders = [
+            [targetJournals.coordinate, nativeBackboneCoordinateJournalMagic],
+            [targetJournals.document, nativeBackboneCoordinateJournalMagic],
+            [targetJournals.signer, nativeBackboneCoordinateJournalMagic],
+        ];
+        for (const [file, header] of journalHeaders) {
+            await this.store.write(file, header);
+            await this.barrierFile(file);
+        }
+        await this.store.atomicReplace(this.checkpointFiles[slot], checkpointBytes);
+        // A prior release does not understand checkpoint authority. The sentinel is
+        // the first-generation publication boundary: install and durably revalidate
+        // it before completed authority becomes visible. On later generations it
+        // must already be exact; never overwrite possible writes from a downgrade.
+        if (this.checkpointCompleted) {
+            await this.requireLegacyMigrationSentinel();
+        }
+        else {
+            await this.installLegacyMigrationSentinel();
+        }
+        const completedState = {
+            configurationChecksum: this.checkpointConfigurationChecksum,
+            highwater: generation,
+            completed: authority,
+        };
+        await this.store.atomicReplace(this.checkpointStateFile, encodeNativeBackboneCoordinateCheckpointState(completedState));
+        // The completed authority is now the only writable generation. Update all
+        // in-memory routing synchronously before another queued flush can start.
+        this.checkpointCompleted = authority;
+        this.checkpointPending = undefined;
+        this.journalInitialized = true;
+        this.documentJournalInitialized = true;
+        this.documentSignerJournalInitialized = true;
+        this.journalByteLength = nativeBackboneCoordinateJournalMagic.byteLength;
+        this.documentJournalByteLength =
+            nativeBackboneCoordinateJournalMagic.byteLength;
+        this.documentSignerJournalByteLength =
+            nativeBackboneCoordinateJournalMagic.byteLength;
+        this.journalRecordCount = 0;
+        this.documentJournalRecordCount = 0;
+        this.documentSignerJournalRecordCount = 0;
+    }
+    async cleanupRetiredCheckpointFiles() {
+        if (!this.store.remove ||
+            (!this.checkpointCompleted && !this.checkpointPending)) {
+            return;
+        }
+        const retiredSlot = this
+            .checkpointCompleted
+            ? this.checkpointSlot(this.checkpointCompleted.generation) === "a"
+                ? "b"
+                : "a"
+            : this.checkpointSlot(this.checkpointPending.generation);
+        const retiredJournals = this.checkpointJournalFiles[retiredSlot];
+        const files = [
+            ...(this.checkpointCompleted
+                ? [
+                    this.snapshotFile,
+                    this.documentSnapshotFile,
+                    this.documentJournalFile,
+                    this.documentSignerSnapshotFile,
+                    this.documentSignerJournalFile,
+                ]
+                : []),
+            this.checkpointFiles[retiredSlot],
+            `${this.checkpointFiles[retiredSlot]}.tmp`,
+            retiredJournals.coordinate,
+            retiredJournals.document,
+            retiredJournals.signer,
+        ];
+        const removals = await Promise.allSettled(files.map((file) => this.store.remove(file)));
+        if (removals.every((result) => result.status === "fulfilled")) {
+            try {
+                await this.store.durableBarrier?.();
+            }
+            catch {
+                // Cleanup is retryable debt. Publication and the caller's ACK already
+                // belong to the new generation, so never turn this into an ambiguous
+                // append failure after the authority switch.
+            }
+        }
+    }
+    async flushJournalInternal(backbone, forceCheckpoint = false) {
+        this.assertPersistenceHealthy();
         let written = 0;
         let persistenceMutationStarted = false;
         let coordinateBytes;
@@ -3924,10 +4755,39 @@ export class NativeBackboneCoordinatePersistence {
         const documentRecordCount = backbone.documentPendingJournalLength;
         const signerRecords = backbone.documentSignerJournal();
         const signerRecordCount = backbone.documentSignerPendingJournalLength;
+        const additionalBytes = coordinateRecords.byteLength +
+            documentRecords.byteLength +
+            signerRecords.byteLength +
+            (coordinateRecords.byteLength > 0 && this.journalInitialized !== true
+                ? backbone.coordinateJournalHeader().byteLength
+                : 0) +
+            (documentRecords.byteLength > 0 &&
+                this.documentJournalInitialized !== true
+                ? backbone.documentJournalHeader().byteLength
+                : 0) +
+            (signerRecords.byteLength > 0 &&
+                this.documentSignerJournalInitialized !== true
+                ? backbone.documentSignerJournalHeader().byteLength
+                : 0);
+        const additionalRecords = coordinateRecordCount + documentRecordCount + signerRecordCount;
+        const checkpointRequested = forceCheckpoint ||
+            (this.crashSafeCompaction &&
+                this.shouldCompactJournal(additionalBytes, additionalRecords));
+        // These three synchronous copies and the journal prefixes above are one
+        // logical cut. No mutation can slip into the checkpoint without also being
+        // represented by one of the captured prefixes.
+        const checkpoint = checkpointRequested
+            ? {
+                coordinateSnapshot: backbone.coordinateSnapshot(),
+                documentSnapshot: backbone.documentSnapshot(),
+                documentSignerSnapshot: backbone.documentSignerSnapshot(),
+            }
+            : undefined;
         try {
+            const activeJournals = this.activeJournalFiles();
             if (coordinateRecords.byteLength > 0) {
                 if (this.journalInitialized === undefined) {
-                    const existing = await this.store.read(this.journalFile);
+                    const existing = await this.store.read(activeJournals.coordinate);
                     this.journalInitialized = !!existing && existing.byteLength > 0;
                 }
                 coordinateBytes = this.journalInitialized
@@ -3936,26 +4796,26 @@ export class NativeBackboneCoordinatePersistence {
                         backbone.coordinateJournalHeader(),
                         coordinateRecords,
                     ]);
-                await this.store.append(this.journalFile, coordinateBytes);
+                await this.store.append(activeJournals.coordinate, coordinateBytes);
                 persistenceMutationStarted = true;
                 written += coordinateRecords.byteLength;
             }
             if (documentRecords.byteLength > 0) {
                 if (this.documentJournalInitialized === undefined) {
-                    const existing = await this.store.read(this.documentJournalFile);
+                    const existing = await this.store.read(activeJournals.document);
                     this.documentJournalInitialized =
                         !!existing && existing.byteLength > 0;
                 }
                 documentBytes = this.documentJournalInitialized
                     ? documentRecords
                     : concatBytes([backbone.documentJournalHeader(), documentRecords]);
-                await this.store.append(this.documentJournalFile, documentBytes);
+                await this.store.append(activeJournals.document, documentBytes);
                 persistenceMutationStarted = true;
                 written += documentRecords.byteLength;
             }
             if (signerRecords.byteLength > 0) {
                 if (this.documentSignerJournalInitialized === undefined) {
-                    const existing = await this.store.read(this.documentSignerJournalFile);
+                    const existing = await this.store.read(activeJournals.signer);
                     this.documentSignerJournalInitialized =
                         !!existing && existing.byteLength > 0;
                 }
@@ -3965,42 +4825,50 @@ export class NativeBackboneCoordinatePersistence {
                         backbone.documentSignerJournalHeader(),
                         signerRecords,
                     ]);
-                await this.store.append(this.documentSignerJournalFile, signerBytes);
+                await this.store.append(activeJournals.signer, signerBytes);
                 persistenceMutationStarted = true;
                 written += signerRecords.byteLength;
             }
-            if (written === 0) {
+            if (written === 0 && !checkpoint) {
                 this.lastFlushMs = Date.now();
                 return 0;
             }
             // `append` may only enqueue bytes in a buffered store. Drain and fsync
             // every affected WAL before clearing its wasm prefix or returning an ACK.
             for (const file of [
-                coordinateBytes ? this.journalFile : undefined,
-                documentBytes ? this.documentJournalFile : undefined,
-                signerBytes ? this.documentSignerJournalFile : undefined,
+                coordinateBytes ? activeJournals.coordinate : undefined,
+                documentBytes ? activeJournals.document : undefined,
+                signerBytes ? activeJournals.signer : undefined,
             ]) {
                 if (file) {
-                    if (this.store.durableBarrier) {
-                        await this.store.durableBarrier(file);
-                    }
-                    else {
-                        await this.store.flush?.(file);
-                    }
+                    await this.barrierFile(file);
                 }
             }
             if (coordinateBytes) {
                 this.journalInitialized = true;
+                this.journalByteLength += coordinateBytes.byteLength;
+                this.journalRecordCount += coordinateRecordCount;
             }
             if (documentBytes) {
                 this.documentJournalInitialized = true;
+                this.documentJournalByteLength += documentBytes.byteLength;
+                this.documentJournalRecordCount += documentRecordCount;
             }
             if (signerBytes) {
                 this.documentSignerJournalInitialized = true;
+                this.documentSignerJournalByteLength += signerBytes.byteLength;
+                this.documentSignerJournalRecordCount += signerRecordCount;
+            }
+            if (checkpoint) {
+                persistenceMutationStarted = true;
+                await this.publishCheckpoint(checkpoint);
             }
             backbone.clearCoordinateJournalPrefix(coordinateRecords.byteLength, coordinateRecordCount);
             backbone.clearDocumentJournalPrefix(documentRecords.byteLength, documentRecordCount);
             backbone.clearDocumentSignerJournalPrefix(signerRecords.byteLength, signerRecordCount);
+            if (checkpoint) {
+                await this.cleanupRetiredCheckpointFiles();
+            }
             this.lastFlushMs = Date.now();
             return written;
         }
@@ -4012,9 +4880,15 @@ export class NativeBackboneCoordinatePersistence {
             throw error;
         }
     }
-    async compact(_backbone) {
+    async compact(backbone) {
         this.assertActive("compact");
-        throw new Error(nativeBackboneCoordinateCompactionDisabledMessage);
+        if (!this.crashSafeCompaction) {
+            throw new Error(nativeBackboneCoordinateCompactionDisabledMessage);
+        }
+        await this.enqueuePersistence(async () => {
+            this.assertPersistenceHealthy();
+            await this.flushJournalInternal(backbone, true);
+        });
     }
     close() {
         if (this.closePromise) {