@peerbit/native-backbone 0.2.8 → 0.2.10

package/README.md

@@ -7,26 +7,60 @@ fused. It owns the native lower-log graph, native log block store, and shared-lo
 resident coordinate state in one Rust object so higher layers can move toward a
 single `JS -> native -> compact facts` transaction boundary.
 
-## Coordinate WAL persistence
+## Coordinate and document-fact WAL persistence
 
-Native shared-log coordinates can be persisted through a write-through WAL or a
-buffered WAL. Write-through flushes every append and is the strictest persistence
-mode. Buffered WAL batches coordinate bytes and flushes on threshold, explicit
-flush, compact, or close, which is the high-throughput mode for strict native
-document writes.
+Native shared-log coordinates, document values, and document signer facts can be
+persisted through write-through or buffered WALs. Write-through flushes every
+append and is the strictest persistence mode. Buffered WALs batch bytes and flush
+on their pending-byte threshold, explicit flush, checkpoint, or close, which is
+the high-throughput mode for strict native document writes.
 
 Use `createBufferedNativeBackboneCoordinatePersistence(store)` with OPFS, memory,
 or custom stores, and `createBufferedNativeBackboneNodeCoordinatePersistence(dir)`
-for the Node adapter. The lower-level
-`createNativeBackboneCoordinatePersistence({ store, buffered: true })` config
-uses the same bounded checkpoint default.
+for the Node adapter. Persistence flush and replay are enabled by default;
+checkpoint compaction is not.
 
-Buffered helpers also install a bounded checkpoint policy by default. When the
-coordinate journal reaches the checkpoint threshold, the adapter writes a compact
-snapshot and removes the replay WAL. This keeps high-throughput strict-native
-document writes from trading append speed for unbounded restart replay cost.
+The built-in Node adapter supports explicit crash-safe checkpointing when its
+filesystem implementation provides atomic replacement. Opt in by setting
+`compactMaxJournalBytes` or `compactMaxJournalRecords` on
+`NativeBackboneNodeCoordinatePersistence` or
+`createBufferedNativeBackboneNodeCoordinatePersistence`:
 
-The coordinate WAL supports clean stop/restart. It is not the recovery authority
+```ts
+const persistence = createBufferedNativeBackboneNodeCoordinatePersistence(
+	programDirectory,
+	{ compactMaxJournalBytes: 64 * 1024 * 1024 },
+);
+```
+
+Crossing either configured threshold durably publishes one versioned, checksummed
+checkpoint for all three fact sets, switches between fixed A/B WAL generations,
+and records an atomic replay high-water mark before covered WAL data is retired.
+Checkpointing is serialized with flushes, so recovery chooses a fully published
+generation instead of combining partially replaced snapshots.
+
+Memory and OPFS persistence, along with custom stores that do not implement the
+atomic replacement, removal, and durability capabilities, continue to reject
+these threshold options. They retain ordinary WAL flush and replay behavior.
+There is intentionally no automatic checkpoint threshold, including for the
+Node helpers.
+
+The checkpoint bounds only the coordinate, document-value, and document-signer
+WALs. The entry-block WAL has a separate owner and remains out of scope, so this
+feature does not by itself bound every file in a program directory.
+
+Existing directories using the legacy snapshots and WALs open without a manual
+migration. Their first checkpoint becomes forward-only once its staged generation
+and downgrade sentinel are durable. If publication is interrupted after that
+boundary, current recovery validates and promotes the staged generation; before
+the boundary, the complete legacy WAL remains authoritative. The sentinel makes a
+pre-checkpoint package fail closed rather than replay stale legacy files. Rolling
+back therefore requires restoring a pre-migration copy of the directory. This is
+an opt-in, forward-only internal persistence-format migration. It removes no
+public API and does not alter the peer-to-peer wire format; it does add observable
+Node checkpoint capabilities and downgrade behavior.
+
+These fact WALs support clean stop/restart. They are not the recovery authority
 for a crash-atomic append across blocks, graph state, heads, coordinates,
 documents, and signer facts.
 
@@ -50,9 +84,10 @@ directory sync. Its first open creates a synced genesis only in an otherwise
 empty program directory; a nonempty legacy directory fails with
 `NativeDurabilityMigrationRequiredError` and is never adopted implicitly.
 
-Phase one retains the full journal and pins genesis as its scan base while newer
-A/B checkpoints prove staging coverage. Journal compaction is deliberately
-deferred until a later phase can switch the journal generation and its scan base
-together. Memory storage is a non-crash-safe reference adapter, and OPFS remains
-unsupported until its lifetime lease and worker-termination barriers have a
-dedicated conformance gate.
+Phase one retains this separate durability-transaction journal and pins genesis
+as its scan base while newer A/B checkpoints prove staging coverage. Compaction
+of that journal is deliberately deferred until a later phase can switch its
+generation and scan base together; the coordinate/document-fact checkpointing
+described above does not alter it. Memory storage is a non-crash-safe reference
+adapter, and OPFS remains unsupported until its lifetime lease and
+worker-termination barriers have a dedicated conformance gate.

package/dist/src/index.d.ts

@@ -5,6 +5,11 @@ export * from "./durability/node-lease.js";
 export * from "./durability/node-storage.js";
 export * from "./durability/storage.js";
 export type RangeResolution = "u32" | "u64";
+type NativePrepareNoNextDocumentIndexCompactTrimFacts = (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentValuePrefixBytes: Uint8Array, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+type NativePrepareNoNextCachedDocumentIndexCompactTrimFacts = (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+type NativePrepareNoNextCachedPlainPutPayloadDocumentIndexCompactTrimFacts = (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+type NativePrepareLatestDocumentIndexTrimFacts = (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentValuePrefixBytes: Uint8Array, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+type NativePrepareLatestCachedDocumentIndexTrimFacts = (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
 type NativePeerbitBackboneHandle = {
     log_len: () => number;
     block_len: () => number;
@@ -244,18 +249,24 @@ type NativePeerbitBackboneHandle = {
     ]>;
     plan_receive_coordinates_for_gids_batch: (entryHashes: string[], gids: string[], hashNumbers: string[], nextHashBatches: string[][], replicaCounts: number[], roleAgeMs: number, now: string, peerFilter: string[] | undefined, expandPeerFilter: boolean, selfHash: string, includeSelf: boolean, fullReplicaFallback: boolean, includeStrictFullReplica: boolean) => Array<[unknown[], unknown[], boolean, boolean, unknown[]]>;
     prepare_plain_entry_commit_facts: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined) => unknown[];
+    prepare_plain_entry_commit_facts_trim_refs?: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number) => unknown[];
     prepare_plain_entry_commit_facts_document_index: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentValuePrefixBytes: Uint8Array, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
     prepare_plain_entry_commit_facts_document_index_cached_plan: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
     prepare_plain_entry_commit_no_next_facts_document_index_compact: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, documentKey: string, documentValuePrefixBytes: Uint8Array, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
     prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
     prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_plain_put_payload?: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionSigner: Uint8Array | undefined) => unknown[];
     prepare_plain_entry_commit_no_next_facts_document_index_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentValuePrefixBytes: Uint8Array, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
-    prepare_plain_entry_commit_no_next_facts_document_index_compact_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentValuePrefixBytes: Uint8Array, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+    prepare_plain_entry_commit_no_next_facts_document_index_compact_trim_hashes: NativePrepareNoNextDocumentIndexCompactTrimFacts;
+    prepare_plain_entry_commit_no_next_facts_document_index_compact_trim_refs?: NativePrepareNoNextDocumentIndexCompactTrimFacts;
     prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
-    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
-    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes_plain_put_payload?: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number, documentKey: string, documentExistingCreated: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionSigner: Uint8Array | undefined) => unknown[];
-    prepare_plain_entry_commit_latest_facts_document_index_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentValuePrefixBytes: Uint8Array, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlan: NativeBackboneSimpleDocumentProjectionPlan | undefined, documentProjectionEncodedDocument: Uint8Array | undefined, documentProjectionSigner: Uint8Array | undefined) => unknown[];
-    prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_hashes: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number | undefined, documentKey: string, documentByteElementIndexLimit: number, documentDeleteTrimmedHeads: boolean, documentProjectionPlanId: number, documentProjectionEncodedDocument: Uint8Array, documentProjectionSigner: Uint8Array | undefined) => unknown[];
+    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes: NativePrepareNoNextCachedDocumentIndexCompactTrimFacts;
+    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_refs?: NativePrepareNoNextCachedDocumentIndexCompactTrimFacts;
+    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_hashes_plain_put_payload?: NativePrepareNoNextCachedPlainPutPayloadDocumentIndexCompactTrimFacts;
+    prepare_plain_entry_commit_no_next_facts_document_index_cached_plan_compact_trim_refs_plain_put_payload?: NativePrepareNoNextCachedPlainPutPayloadDocumentIndexCompactTrimFacts;
+    prepare_plain_entry_commit_latest_facts_document_index_trim_hashes: NativePrepareLatestDocumentIndexTrimFacts;
+    prepare_plain_entry_commit_latest_facts_document_index_trim_refs?: NativePrepareLatestDocumentIndexTrimFacts;
+    prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_hashes: NativePrepareLatestCachedDocumentIndexTrimFacts;
+    prepare_plain_entry_commit_latest_facts_document_index_cached_plan_trim_refs?: NativePrepareLatestCachedDocumentIndexTrimFacts;
     prepare_plain_entry_storage_facts_and_put: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array) => unknown[];
     prepare_plain_entry_storage_facts_trim_and_put: (wallTime: bigint, logical: number, gid: string, next: string[], type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, trimLengthTo: number) => unknown[];
     prepare_plain_no_next_storage_append_transaction: (wallTime: bigint, logical: number, gid: string, type: number, metaData: Uint8Array | undefined, payloadData: Uint8Array, replicas: number, roleAgeMs: number, now: string, selfHash: string, selfReplicating: boolean, resolveTrimmedEntries: boolean) => unknown[];
@@ -763,6 +774,7 @@ export type NativeBackboneAppendResult = {
     assignedToRangeBoundary: boolean;
     trimmed: NativeBackboneTrimmedEntry[];
     trimmedHashes?: string[];
+    trimmedGids?: string[];
     documentTrimmedHeadsProcessed?: boolean;
     documentPreviousContext?: NativeBackboneDocumentContextFacts;
 };
@@ -774,6 +786,7 @@ type NativeBackboneStorageAppendResult = {
     assignedToRangeBoundary: boolean;
     trimmed: NativeBackboneTrimmedEntry[];
     trimmedHashes?: string[];
+    trimmedGids?: string[];
     documentTrimmedHeadsProcessed?: boolean;
     documentPreviousContext?: NativeBackboneDocumentContextFacts;
 };
@@ -924,7 +937,21 @@ export type NativeBackboneCoordinatePersistenceOptions = NativeBackboneCoordinat
 };
 export type NativeBackboneCoordinatePersistenceStore = {
     read(name: string): Promise<Uint8Array | undefined>;
+    /**
+     * Read a named file without materializing more than `maxBytes`.
+     *
+     * The optional method is an explicit capability: callers that require a
+     * pre-allocation bound must fail closed when it is absent and must not fall
+     * back to `read`.
+     */
+    readLimited?(name: string, maxBytes: number): Promise<Uint8Array | undefined>;
     write(name: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * Durably replace one named file without exposing a torn destination. The
+     * replacement is not visible until its bytes and containing directory have
+     * crossed their physical durability barriers.
+     */
+    atomicReplace?(name: string, bytes: Uint8Array): Promise<void>;
     /**
      * Appends `bytes` to the named file. Callers hand over ownership of
      * `bytes` and must not mutate it afterwards: buffering stores keep the
@@ -943,6 +970,13 @@ export type NativeBackboneCoordinatePersistenceStore = {
         flush?: boolean;
     }): Promise<void>;
 };
+export declare class NativeBackboneCoordinatePersistenceReadLimitError extends Error {
+    readonly file: string;
+    readonly maxBytes: number;
+    readonly observedBytes: bigint;
+    readonly code = "ERR_NATIVE_BACKBONE_COORDINATE_READ_LIMIT";
+    constructor(file: string, maxBytes: number, observedBytes: bigint);
+}
 export type NativeBackboneCoordinatePersistenceAdapter = {
     /**
      * Optional durable capability used by higher layers for atomic operation
@@ -1007,7 +1041,7 @@ export type NativeBackboneNodeCoordinatePersistenceOptions = NativeBackboneCoord
 };
 export declare const nativeBackboneCoordinateDropTombstoneFile = "native-backbone-drop.tombstone";
 export declare const defaultNativeBackboneCoordinateFlushMaxPendingBytes: number;
-/** @deprecated Built-in coordinate persistence compaction is currently disabled. */
+/** Recommended explicit byte threshold for crash-safe Node checkpointing. */
 export declare const defaultNativeBackboneCoordinateCompactMaxJournalBytes: number;
 type NativeBackboneNodeFs = {
     mkdir(path: string, options?: {
@@ -1016,6 +1050,9 @@ type NativeBackboneNodeFs = {
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array): Promise<unknown>;
     appendFile(path: string, data: Uint8Array): Promise<unknown>;
+    rename?(from: string, to: string): Promise<unknown>;
+    /** Explicit capability for pre-allocation-bounded positional reads. */
+    openBoundedRead?(path: string): Promise<NativeBackboneNodeBoundedReadFileHandle>;
     open?(path: string, flags: string): Promise<NativeBackboneNodeAppendFileHandle>;
     rm(path: string, options?: {
         force?: boolean;
@@ -1025,9 +1062,28 @@ type NativeBackboneNodeAppendFileHandle = {
     write(data: Uint8Array): Promise<{
         bytesWritten: number;
     }>;
+    read?(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    stat?(options: {
+        bigint: true;
+    }): Promise<{
+        size: bigint;
+    }>;
     sync?(): Promise<unknown>;
     close(): Promise<unknown>;
 };
+type NativeBackboneNodeBoundedReadFileHandle = {
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    stat(options: {
+        bigint: true;
+    }): Promise<{
+        size: bigint;
+    }>;
+    close(): Promise<unknown>;
+};
 type NativeBackboneOPFSFile = {
     arrayBuffer(): Promise<ArrayBuffer>;
     size: number;
@@ -1111,7 +1167,9 @@ declare class NativeBackboneLogGraph {
     }, _blockStore: unknown): (NativeBackboneCommittedEntry & {
         trimmedEntries?: NativeBackboneLogEntry[];
         trimmedEntryHashes?: string[];
+        trimmedEntryGids?: string[];
         documentTrimmedHeadsProcessed?: boolean;
+        documentPreviousContext?: NativeBackboneDocumentContextFacts;
     }) | undefined;
     prepareEntryV0PlainEntryAndPut(input: {
         clockId: Uint8Array;
@@ -1529,6 +1587,7 @@ export declare class NativePeerbitBackbone {
 export declare class NativeBackboneMemoryCoordinatePersistenceStore implements NativeBackboneCoordinatePersistenceStore {
     readonly files: Map<string, Uint8Array<ArrayBufferLike>>;
     read(name: string): Promise<Uint8Array | undefined>;
+    readLimited(name: string, maxBytes: number): Promise<Uint8Array | undefined>;
     write(name: string, bytes: Uint8Array): Promise<void>;
     append(name: string, bytes: Uint8Array): Promise<void>;
     remove(name: string): Promise<void>;
@@ -1541,7 +1600,9 @@ export declare class NativeBackboneNodeCoordinatePersistenceStore implements Nat
     private readonly filePaths;
     private directoryEnsured;
     private appendFailure;
+    readonly readLimited?: (name: string, maxBytes: number) => Promise<Uint8Array | undefined>;
     readonly durableBarrier?: (name?: string) => Promise<void>;
+    readonly atomicReplace?: (name: string, bytes: Uint8Array) => Promise<void>;
     constructor(directory: string, fs?: NativeBackboneNodeFs | undefined);
     private nodeFs;
     private filePath;
@@ -1549,7 +1610,9 @@ export declare class NativeBackboneNodeCoordinatePersistenceStore implements Nat
     private closeAppendHandle;
     private appendHandle;
     read(name: string): Promise<Uint8Array | undefined>;
+    private readWithinLimit;
     write(name: string, bytes: Uint8Array): Promise<void>;
+    private replaceAtomically;
     append(name: string, bytes: Uint8Array): Promise<void>;
     remove(name: string): Promise<void>;
     flush(name?: string): Promise<void>;
@@ -1567,6 +1630,7 @@ export declare class NativeBackboneOPFSCoordinatePersistenceStore implements Nat
     private static defaultRoot;
     private static directoryParts;
     read(name: string): Promise<Uint8Array | undefined>;
+    readLimited(name: string, maxBytes: number): Promise<Uint8Array | undefined>;
     write(name: string, bytes: Uint8Array): Promise<void>;
     append(name: string, bytes: Uint8Array): Promise<void>;
     remove(name: string): Promise<void>;
@@ -1578,13 +1642,16 @@ export declare class NativeBackboneBufferedCoordinatePersistenceStore implements
     private readonly options;
     private readonly buffers;
     private bufferedBytes;
+    readonly readLimited?: (name: string, maxBytes: number) => Promise<Uint8Array | undefined>;
     readonly supportsRemoval: boolean;
     readonly durableBarrier?: (name?: string) => Promise<void>;
+    readonly atomicReplace?: (name: string, bytes: Uint8Array) => Promise<void>;
     constructor(inner: NativeBackboneCoordinatePersistenceStore, options?: {
         maxBufferedBytes?: number;
     });
     private buffer;
     read(name: string): Promise<Uint8Array | undefined>;
+    private readWithinLimit;
     write(name: string, bytes: Uint8Array): Promise<void>;
     append(name: string, bytes: Uint8Array): Promise<void>;
     remove(name: string): Promise<void>;
@@ -1600,7 +1667,7 @@ export declare class NativeBackboneCoordinatePersistence {
     readonly flushIntervalMs?: number;
     readonly compactMaxJournalBytes?: number;
     readonly compactMaxJournalRecords?: number;
-    readonly crashSafeCompaction = false;
+    readonly crashSafeCompaction: boolean;
     readonly durableBarrier: boolean;
     readonly supportsDrop: boolean;
     readonly dropIsTerminal = true;
@@ -1610,9 +1677,22 @@ export declare class NativeBackboneCoordinatePersistence {
     private readonly documentJournalFile;
     private readonly documentSignerSnapshotFile;
     private readonly documentSignerJournalFile;
+    private readonly checkpointConfigurationChecksum;
+    private readonly checkpointStateFile;
+    private readonly checkpointFiles;
+    private readonly checkpointJournalFiles;
     private journalInitialized;
+    private journalByteLength;
+    private journalRecordCount;
     private documentJournalInitialized;
+    private documentJournalByteLength;
+    private documentJournalRecordCount;
     private documentSignerJournalInitialized;
+    private documentSignerJournalByteLength;
+    private documentSignerJournalRecordCount;
+    private checkpointHighwater;
+    private checkpointCompleted?;
+    private checkpointPending?;
     private lastFlushMs;
     private persistenceQueue;
     private persistenceLifecycle;
@@ -1625,13 +1705,22 @@ export declare class NativeBackboneCoordinatePersistence {
     constructor(store: NativeBackboneCoordinatePersistenceStore, options?: NativeBackboneCoordinatePersistenceOptions);
     /** Durable operation-intent capability for strict shared-log transactions. */
     get intentStore(): NativeBackboneCoordinatePersistenceStore;
+    private legacyConfiguredFiles;
     private configuredFiles;
+    private checkpointSlot;
+    private activeJournalFiles;
     private assertLifecycleActive;
     private assertActive;
+    private assertPersistenceHealthy;
     private resetJournalTracking;
+    private persistDropTombstone;
     private eraseDropFiles;
     drop(additionalFiles?: readonly string[]): Promise<void>;
     resumeDrop(): Promise<boolean>;
+    private barrierFile;
+    private hasDurableLegacyMigrationSentinel;
+    private installLegacyMigrationSentinel;
+    private requireLegacyMigrationSentinel;
     hydrate(backbone: NativePeerbitBackbone): Promise<number>;
     private assertHydrating;
     private resumeDropInternal;
@@ -1639,8 +1728,12 @@ export declare class NativeBackboneCoordinatePersistence {
     flushJournalOnAppend(backbone: NativePeerbitBackbone): number | Promise<number>;
     flushJournal(backbone: NativePeerbitBackbone): Promise<number>;
     private enqueuePersistence;
+    private shouldCompactJournal;
+    private nextCheckpointGeneration;
+    private publishCheckpoint;
+    private cleanupRetiredCheckpointFiles;
     private flushJournalInternal;
-    compact(_backbone: NativePeerbitBackbone): Promise<void>;
+    compact(backbone: NativePeerbitBackbone): Promise<void>;
     close(): Promise<void>;
 }
 export declare class NativeBackboneNodeCoordinatePersistence extends NativeBackboneCoordinatePersistence {