@optimystic/db-p2p-storage-rn 1.15.0 → 1.16.0

package/src/identity.ts

@@ -7,7 +7,9 @@ export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
 
 /**
  * Loads the persisted React Native peer's libp2p private key, or generates a
- * fresh Ed25519 key on first call and persists it.
+ * fresh Ed25519 key on first call and persists it in one batch, synced where
+ * the handle can sync, so a power cut right after first start cannot give the
+ * node a different peer id next time. An existing key is read as it is.
  *
  * The key is stored as raw protobuf bytes under a dedicated identity tag —
  * LevelDB stores arbitrary byte sequences natively, so there is no base64
@@ -28,6 +30,6 @@ export async function loadOrCreateRNPeerKey(
 	}
 	const key = await generateKeyPair('Ed25519');
 	const bytes = privateKeyToProtobuf(key);
-	await db.put(identityKey(keyName), bytes);
+	await db.batch().put(identityKey(keyName), bytes).write({ sync: db.canSync });
 	return key;
 }

package/src/index.ts

@@ -1,5 +1,5 @@
-export { LevelDBRawStorage, LevelDBStoreDriver } from './leveldb-storage.js';
-export { LevelDBKVStore } from './leveldb-kv-store.js';
+export { LevelDBRawStorage, LevelDBJournalStore, type LevelDBRawStorageOptions } from './leveldb-storage.js';
+export { LevelDBKVStore, type LevelDBKVStoreOptions } from './leveldb-kv-store.js';
 export { loadOrCreateRNPeerKey, DEFAULT_PEER_KEY_NAME } from './identity.js';
 export {
 	openOptimysticRNDb,

package/src/keys.ts

@@ -16,6 +16,10 @@
  *   - proofs:       rev (8-byte big-endian unsigned, same as revisions)
  *   - materialized: actionId UTF-8 (terminal)
  *
+ * The journal (`TAG_JOURNAL`) has no `blockId` envelope: a record key is the
+ * tag then its `seq` as 8 bytes big-endian, and the applied-through mark is the
+ * bare tag, which sorts before every numbered key.
+ *
  * `kv` and `identity` keys are flat — no `blockId` envelope — under their
  * own tag bytes (`TAG_KV`, `TAG_IDENTITY`) and use UTF-8 of the full key.
  *
@@ -30,6 +34,7 @@ export const TAG_PENDING = 0x03;
 export const TAG_TRANSACTIONS = 0x04;
 export const TAG_MATERIALIZED = 0x05;
 export const TAG_PROOFS = 0x06;
+export const TAG_JOURNAL = 0x07;
 export const TAG_KV = 0x10;
 export const TAG_IDENTITY = 0x20;
 
@@ -150,6 +155,58 @@ export function actionIdFromKey(key: Uint8Array, blockId: string): string {
 	return textDecoder().decode(key.subarray(suffixOffset));
 }
 
+// --- the journal ---
+
+const SEQ_BYTES = 8;
+
+/** `seq` as 8 bytes big-endian, the suffix of a record key and the value of the mark. */
+function encodeSeq(seq: number): Uint8Array {
+	const out = new Uint8Array(SEQ_BYTES);
+	new DataView(out.buffer).setBigUint64(0, BigInt(seq), false);
+	return out;
+}
+
+/** The number 8 bytes big-endian hold, or `undefined` for any other length. */
+function decodeSeq(bytes: Uint8Array): number | undefined {
+	if (bytes.byteLength !== SEQ_BYTES) return undefined;
+	return Number(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(0, false));
+}
+
+/** `TAG_JOURNAL || seq (8 BE)`: the key of the journal record numbered `seq`. */
+export function journalRecordKey(seq: number): Uint8Array {
+	return concat(Uint8Array.of(TAG_JOURNAL), encodeSeq(seq));
+}
+
+/** The bare tag: the key of the applied-through mark, which sorts before every record key. */
+export function journalMarkKey(): Uint8Array {
+	return Uint8Array.of(TAG_JOURNAL);
+}
+
+/** The mark's value: the number of the last record applied, as 8 bytes big-endian. */
+export function encodeJournalMark(appliedThrough: number): Uint8Array {
+	return encodeSeq(appliedThrough);
+}
+
+/** The number a mark value holds, or `undefined` when it is not 8 bytes. */
+export function decodeJournalMark(value: Uint8Array): number | undefined {
+	return decodeSeq(value);
+}
+
+/** Returns the inclusive lower / exclusive upper range covering the mark and every record key. */
+export function journalRange(): { gte: Uint8Array; lt: Uint8Array } {
+	return { gte: Uint8Array.of(TAG_JOURNAL), lt: Uint8Array.of(TAG_JOURNAL + 1) };
+}
+
+/** Whether a key inside `journalRange` is the mark's (the bare tag) rather than a record's. */
+export function isJournalMarkKey(key: Uint8Array): boolean {
+	return key.byteLength === 1;
+}
+
+/** The `seq` a record key names, or `undefined` for a key of another shape. */
+export function seqFromJournalKey(key: Uint8Array): number | undefined {
+	return decodeSeq(key.subarray(1));
+}
+
 export function kvKey(key: string): Uint8Array {
 	return concat(Uint8Array.of(TAG_KV), textEncoder.encode(key));
 }

package/src/leveldb-kv-store.ts

@@ -1,7 +1,10 @@
-import type { IKVStore } from '@optimystic/db-p2p';
+import { WriteGroup, type CommittedBatch, type FlushOptions, type IKVStore, type WriteGroupEntry, type WriteGroupOptions } from '@optimystic/db-p2p';
 import { drain, type LevelDBLike } from './leveldb-like.js';
 import { kvKey, kvKeyToString, kvPrefixRange } from './keys.js';
 
+/** The write group's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer`). */
+export type LevelDBKVStoreOptions = WriteGroupOptions;
+
 const textEncoder = new TextEncoder();
 // Built on first use, not at module load: Hermes (React Native) has no native `TextDecoder`, so a
 // module-scope construction fails the import itself whenever it runs ahead of the host's polyfill.
@@ -16,29 +19,87 @@ const textDecoder = (): TextDecoder => textDecoderInstance ??= new TextDecoder()
  * so the three subsystems can't collide regardless of the user-chosen
  * `prefix`. `list(prefix)` is a range-bounded scan — never a full-database
  * iteration plus JS-side filter — so listing latency stays bounded.
+ *
+ * Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
+ * `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
+ * everything written since the last flush as ONE LevelDB batch, synced wherever the handle can
+ * sync (`canSync`), so the writes are on the disk before the flush resolves. Every flush the node
+ * makes of this store is strict, and so is the group's own idle flush, so there is no relaxed path
+ * to journal: a flush given a window is treated as strict, as a store that cannot defer a sync
+ * treats every window, and each batch carries its own data. A failed batch latches the store, after
+ * which every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
+ * `RawStoreDriver.flush`); reads keep serving the overlay.
  */
 export class LevelDBKVStore implements IKVStore {
-	private readonly prefix: string;
+	private readonly group: WriteGroup<string>;
 
-	constructor(private readonly db: LevelDBLike, prefix: string = 'optimystic:txn:') {
-		this.prefix = prefix;
+	constructor(
+		private readonly db: LevelDBLike,
+		private readonly prefix: string = 'optimystic:txn:',
+		options: LevelDBKVStoreOptions = {},
+	) {
+		this.group = new WriteGroup<string>(key => key, {
+			commit: entries => this.commit(entries),
+			// Every commit is as durable as this store can make it when it resolves, so nothing is ever owed a sync.
+			sync: () => Promise.resolve(),
+		}, options);
 	}
 
 	async get(key: string): Promise<string | undefined> {
+		const held = this.group.lookup(key);
+		if (held !== undefined) return held === null ? undefined : textDecoder().decode(held);
 		const bytes = await this.db.get(kvKey(this.prefix + key));
 		if (!bytes) return undefined;
 		return textDecoder().decode(bytes);
 	}
 
 	async set(key: string, value: string): Promise<void> {
-		await this.db.put(kvKey(this.prefix + key), textEncoder.encode(value));
+		this.group.put(key, textEncoder.encode(value));
 	}
 
 	async delete(key: string): Promise<void> {
-		await this.db.delete(kvKey(this.prefix + key));
+		this.group.delete(key);
 	}
 
+	/** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
 	async list(prefix: string): Promise<string[]> {
+		// Taken before awaiting the store: a commit resolving meanwhile drops entries from the overlay
+		// that the listing below may have been taken without.
+		const held = [...this.group.entries()].filter(([key]) => key.startsWith(prefix));
+		const keys = new Set(await this.listStored(prefix));
+		for (const [key, value] of held) {
+			if (value === null) keys.delete(key);
+			else keys.add(key);
+		}
+		return [...keys];
+	}
+
+	/** Make every write resolved before this call durable: one batch, synced where the handle can, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
+	flush(options?: FlushOptions): Promise<void> {
+		return this.group.flush(options);
+	}
+
+	/** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
+	whenDurable(): Promise<void> {
+		return this.group.whenDurable();
+	}
+
+	/** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
+	close(): Promise<void> {
+		return this.group.close();
+	}
+
+	private async commit(entries: readonly WriteGroupEntry<string>[]): Promise<CommittedBatch> {
+		const batch = this.db.batch();
+		for (const { key, value } of entries) {
+			const encoded = kvKey(this.prefix + key);
+			if (value === undefined) batch.delete(encoded); else batch.put(encoded, value);
+		}
+		await batch.write({ sync: this.db.canSync });
+		return { durable: Promise.resolve() };
+	}
+
+	private async listStored(prefix: string): Promise<string[]> {
 		const range = kvPrefixRange(this.prefix + prefix);
 		const entries = await drain(this.db.iterator({ gte: range.gte, lt: range.lt, keys: true }));
 		return entries.map(([rawKey]) => kvKeyToString(rawKey).slice(this.prefix.length));

package/src/leveldb-like.ts

@@ -10,6 +10,12 @@
  * Only `openOptimysticRNDb`, the user-facing constructors, and the identity
  * helper are exported from `index.ts`; the interfaces in this file are
  * internal — consumers never see them.
+ *
+ * Every write this package makes is a `batch().write(...)`: the surface has no
+ * single `put` or `delete`, on purpose. A direct write lands unsynced in
+ * LevelDB's current log file, which LevelDB closes unsynced when it switches to
+ * a new one, so a later synced write does not cover it — exactly the write the
+ * journal under `LevelDBRawStorage` exists to keep out of the store.
  */
 
 /** Range options for a `LevelDBLike.iterator` scan. */
@@ -38,12 +44,22 @@ export interface LevelDBIteratorLike {
 	close(): Promise<void>;
 }
 
+/** How a batch is written. */
+export interface LevelDBWriteOptions {
+	/**
+	 * Write with LevelDB's `WriteOptions.sync`: the batch is on the disk before the write resolves.
+	 * Only valid on a handle whose `canSync` is true; asking a handle that cannot is a caller bug,
+	 * and the adapter throws rather than write unsynced and report otherwise.
+	 */
+	readonly sync?: boolean;
+}
+
 /** Atomic batch of `put` / `delete` operations against a single database. */
 export interface LevelDBWriteBatchLike {
 	put(key: Uint8Array, value: Uint8Array): this;
 	delete(key: Uint8Array): this;
-	/** Commit the batch atomically. */
-	write(): Promise<void>;
+	/** Commit the batch atomically; unsynced unless `options.sync`. The batch is consumed either way. */
+	write(options?: LevelDBWriteOptions): Promise<void>;
 }
 
 /**
@@ -55,9 +71,13 @@ export interface LevelDBWriteBatchLike {
  * uniform with `classic-level`'s native async API.
  */
 export interface LevelDBLike {
+	/**
+	 * Whether `batch().write({ sync: true })` is honoured. Fixed for the life of the handle; it is
+	 * what `LevelDBRawStorage` reports its `durability` from. `rn-leveldb` cannot sync today
+	 * (`react-native-storage-syncs-once-rn-leveldb-can`); `classic-level` can.
+	 */
+	readonly canSync: boolean;
 	get(key: Uint8Array): Promise<Uint8Array | undefined>;
-	put(key: Uint8Array, value: Uint8Array): Promise<void>;
-	delete(key: Uint8Array): Promise<void>;
 	batch(): LevelDBWriteBatchLike;
 	iterator(options?: LevelDBIteratorOptions): LevelDBIteratorLike;
 	/** Release the underlying database handle. */

package/src/leveldb-storage.ts

@@ -1,11 +1,33 @@
 import type { ActionId, BlockId } from '@optimystic/db-core';
-import { KvRawStorage, identityForHandle, type RawStoreDriver, type StoreIdentity } from '@optimystic/db-p2p';
-import { drain, type LevelDBLike } from './leveldb-like.js';
+import {
+	JournalBatchBackend,
+	JournalRecordDecodeError,
+	KvRawStorage,
+	WriteGroupDriver,
+	decodeJournalRecord,
+	encodeJournalRecord,
+	identityForHandle,
+	type JournalBatchBackendOptions,
+	type JournalContents,
+	type JournalRecord,
+	type JournalStore,
+	type StoreDurability,
+	type StoreIdentity,
+	type StoreKey,
+	type WriteGroupOptions,
+} from '@optimystic/db-p2p';
+import { drain, type LevelDBLike, type LevelDBWriteBatchLike } from './leveldb-like.js';
 import {
 	TAG_PENDING,
 	actionIdFromKey,
 	blockEnvelopeRange,
 	blockIdFromMetadataKey,
+	decodeJournalMark,
+	encodeJournalMark,
+	isJournalMarkKey,
+	journalMarkKey,
+	journalRange,
+	journalRecordKey,
 	materializedKey,
 	metadataKey,
 	metadataRange,
@@ -13,27 +35,71 @@ import {
 	proofKey,
 	revisionFromKey,
 	revisionKey,
+	seqFromJournalKey,
 	transactionKey,
 } from './keys.js';
 import { createLogger } from './logger.js';
 
 const log = createLogger('storage:leveldb');
 
+/** The LevelDB key a `StoreKey` addresses: the tag-prefixed byte scheme of `keys.ts`, unchanged from the per-write driver before it. */
+function keyBytes(key: StoreKey): Uint8Array {
+	switch (key.store) {
+		case 'metadata':
+			return metadataKey(key.blockId);
+		case 'revisions':
+			return revisionKey(key.blockId, key.rev);
+		case 'proofs':
+			return proofKey(key.blockId, key.rev);
+		case 'pending':
+			return pendingKey(key.blockId, key.actionId);
+		case 'transactions':
+			return transactionKey(key.blockId, key.actionId);
+		case 'materialized':
+			return materializedKey(key.blockId, key.actionId);
+	}
+}
+
 /**
- * LevelDB {@link RawStoreDriver}: the six logical block-storage stores mapped
- * into a single ordered byte keyspace, partitioned by a leading tag byte (see
- * `./keys.ts`). LevelDB is already one ordered byte-keyspace, so this driver is
- * mostly key encoding — the tag-prefixed byte scheme in `keys.ts` stays in this
- * package; the kernel deals in logical keys.
+ * LevelDB {@link JournalStore}: the six logical block-storage stores mapped into a single ordered
+ * byte keyspace, partitioned by a leading tag byte (see `./keys.ts`), read exactly as the per-write
+ * driver before it read them, so data an earlier build wrote reads unchanged; and the journal under
+ * its own tag byte, which `JournalBatchBackend` drives.
+ *
+ * `KvRawStorage` owns all JSON/UTF-8 serialization, so this store only ever reads/writes raw
+ * `Uint8Array` values; a journal record is bytes too, through `encodeJournalRecord`. Everything
+ * LevelDB-specific stays here: the tag-range scans (drained snapshot-first before yielding, so a
+ * native iterator never straddles a consumer's `await`), and the one `WriteBatch` each journal
+ * write is.
  *
- * `KvRawStorage` now owns all JSON/UTF-8 serialization, so this driver only ever
- * reads/writes raw `Uint8Array` values — no `TextEncoder`/`TextDecoder` for
- * values, and no `JSON.parse`/`stringify`. A value round-trips as the exact bytes
- * the kernel wrote. Everything LevelDB-specific stays here: the tag-range scans
- * (drained snapshot-first before yielding, so a native iterator never straddles a
- * consumer's `await`), and the single `WriteBatch` that makes `promote` atomic.
+ * ### Why a group survives, and in order
+ *
+ * A LevelDB batch is atomic, but LevelDB syncs only its current log file, closes an old one
+ * unsynced when it switches, and under default options skips a damaged log record and keeps the
+ * ones after it, so a later write can survive a power cut while an earlier one is lost — which is
+ * why the backend journals (see `JournalBatchBackend`). Here an append is one unsynced batch
+ * putting the record under its sequence, and an apply is one batch over the data tags and the
+ * journal — every record's entries in order, the applied-through mark, and the delete of each
+ * record applied or discarded — written synced wherever the handle can sync (`canSync`). The apply
+ * carries every byte it applies, so its durability depends on no earlier batch, and the backend
+ * syncs each apply before the next starts: what a power cut leaves is a prefix of the groups, and
+ * `durability` is `'power-loss'`. Nothing this package writes bypasses a batch, so no unsynced
+ * direct write can sit in an old log file outside the journal's reach.
+ *
+ * `rn-leveldb` cannot sync today, so on a phone the store reports `'process-crash'` and the backend
+ * applies each group at once as one unsynced batch, never journaling: a group lands whole or not
+ * at all, and the ordering half of the contract arrives with the binding change and nothing here.
+ *
+ * The handle is shared with `LevelDBKVStore` and `loadOrCreateRNPeerKey`, so there is no `close`
+ * here: the host closes the handle after `storage.close()` has resolved.
  */
-export class LevelDBStoreDriver implements RawStoreDriver {
+export class LevelDBJournalStore implements JournalStore {
+	// NOTE: `'process-crash'` holds only while the handle cannot sync (flush contract rule 3 is then
+	// not kept across a power cut: LevelDB's recovery skips a damaged log record and keeps the ones
+	// after it, and no apply is synced). The synced path is built and tested over `classic-level`;
+	// `react-native-storage-syncs-once-rn-leveldb-can` is the binding change that turns it on.
+	readonly durability: StoreDurability;
+
 	// NOTE: identity is the HANDLE object, so two handles opened over the same LevelDB PATH read
 	// as two identities. Resolving that would mean naming the underlying on-disk path, which
 	// `LevelDBLike` does not expose. The package opener (`rn-opener.ts`) hands out one handle per
@@ -41,6 +107,7 @@ export class LevelDBStoreDriver implements RawStoreDriver {
 	private readonly identity: StoreIdentity;
 
 	constructor(private readonly db: LevelDBLike) {
+		this.durability = db.canSync ? 'power-loss' : 'process-crash';
 		this.identity = identityForHandle('leveldb-handle', db);
 	}
 
@@ -48,119 +115,30 @@ export class LevelDBStoreDriver implements RawStoreDriver {
 		return this.identity;
 	}
 
-	// --- metadata ---
+	// --- reads: the applied stores ---
 
-	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
-		return this.db.get(metadataKey(blockId));
+	async get(key: StoreKey): Promise<Uint8Array | undefined> {
+		return this.db.get(keyBytes(key));
 	}
 
-	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
-		await this.db.put(metadataKey(blockId), value);
-	}
-
-	// --- revisions ---
-
-	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.db.get(revisionKey(blockId, rev));
-	}
-
-	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		await this.db.put(revisionKey(blockId, rev), value);
-	}
-
-	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+	async rangeRevisions(blockId: BlockId, lo: number, hi: number): Promise<[number, Uint8Array][]> {
 		// Revs are encoded 8-byte big-endian (`revisionKey`), so byte order == numeric
 		// order and `revisionKey(blockId, hi)` is exactly the inclusive upper bound;
 		// LevelDB's upper bound is exclusive (`lt`), so use `lt = revisionKey(hi + 1)`.
 		const gte = revisionKey(blockId, lo);
 		const lt = revisionKey(blockId, hi + 1);
-		// Drain before yielding — a native LevelDB iterator must not stay open across
-		// the consumer's awaits (the kernel's drain-before-yield contract).
-		const entries = await drain(this.db.iterator({ gte, lt, reverse }));
-		for (const [key, value] of entries) {
-			yield [revisionFromKey(key), value];
-		}
+		// Drained before returning: a native LevelDB iterator must not stay open across the
+		// consumer's awaits (the kernel's drain-before-yield contract).
+		const entries = await drain(this.db.iterator({ gte, lt }));
+		return entries.map(([key, value]) => [revisionFromKey(key), value]);
 	}
 
-	// --- pending ---
-
-	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get(pendingKey(blockId, actionId));
-	}
-
-	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put(pendingKey(blockId, actionId), value);
-	}
-
-	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete(pendingKey(blockId, actionId));
-	}
-
-	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
+	async listPendingActionIds(blockId: BlockId): Promise<ActionId[]> {
 		const range = blockEnvelopeRange(TAG_PENDING, blockId);
-		// Drain before yielding, same rationale as rangeRevisions.
 		const entries = await drain(this.db.iterator({ gte: range.gte, lt: range.lt, keys: true }));
-		for (const [key] of entries) {
-			yield actionIdFromKey(key, blockId) as ActionId;
-		}
-	}
-
-	// --- transactions ---
-
-	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get(transactionKey(blockId, actionId));
-	}
-
-	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put(transactionKey(blockId, actionId), value);
-	}
-
-	// --- proofs (own tag byte; no delete — see RawStoreDriver.getProof) ---
-
-	async getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.db.get(proofKey(blockId, rev));
-	}
-
-	async putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		await this.db.put(proofKey(blockId, rev), value);
+		return entries.map(([key]) => actionIdFromKey(key, blockId) as ActionId);
 	}
 
-	// --- materialized ---
-
-	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get(materializedKey(blockId, actionId));
-	}
-
-	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put(materializedKey(blockId, actionId), value);
-	}
-
-	// The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
-	// driver exposes delete as a separate op.
-	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete(materializedKey(blockId, actionId));
-	}
-
-	// --- promote (the only cross-key atomic op) ---
-
-	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
-		const pKey = pendingKey(blockId, actionId);
-		const value = await this.db.get(pKey);
-		if (!value) {
-			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
-		}
-		// The single `WriteBatch` IS the atomic move: a crash leaves either the
-		// pending or the committed entry, never both/neither.
-		const tKey = transactionKey(blockId, actionId);
-		await this.db
-			.batch()
-			.put(tKey, value)
-			.delete(pKey)
-			.write();
-	}
-
-	// --- optional passthroughs ---
-
 	async *listBlockIds(): AsyncIterable<BlockId> {
 		// Scan the whole TAG_METADATA keyspace; each metadata key is one distinct
 		// block id (empty suffix). keys:true skips values — we only need the ids.
@@ -197,31 +175,118 @@ export class LevelDBStoreDriver implements RawStoreDriver {
 		}
 	}
 
+	// --- the journal ---
+
+	/** One unsynced batch: the record's bytes under its `seq`. `JournalStore.appendJournal`'s contract. */
+	async appendJournal(record: JournalRecord): Promise<void> {
+		await this.db.batch().put(journalRecordKey(record.seq), encodeJournalRecord(record)).write();
+	}
+
+	/**
+	 * One batch over the data tags and the journal, synced wherever the handle can sync: each
+	 * record's entries in order, then the mark, then the delete of every numbered record. A number
+	 * with no record present (a strict group's, never appended) deletes nothing.
+	 * `JournalStore.applyJournal`'s contract.
+	 */
+	// NOTE: on a handle that cannot sync every group is applied this way, so each flush also puts the
+	// mark and deletes a record key that was never appended (a LevelDB tombstone): two small extra
+	// operations per flush, unmeasured. If flush cost on phones ever shows in profiles, have the
+	// backend hand the store only the numbers it appended, rather than every number applied.
+	async applyJournal(apply: readonly JournalRecord[], appliedThrough: number, discard: readonly number[]): Promise<void> {
+		const batch = this.db.batch();
+		for (const record of apply) {
+			putEntries(batch, record);
+		}
+		batch.put(journalMarkKey(), encodeJournalMark(appliedThrough));
+		for (const { seq } of apply) batch.delete(journalRecordKey(seq));
+		for (const seq of discard) batch.delete(journalRecordKey(seq));
+		await batch.write({ sync: this.db.canSync });
+	}
+
+	/**
+	 * One drained scan over the journal's tag: the mark and every numbered record, ascending (the
+	 * sequence is 8 bytes big-endian, so key order is sequence order). A record that does not
+	 * decode, or whose decoded number is not the one its key names, is left out, which recovery
+	 * treats as a gap; a mark that is not 8 bytes reads as 0. `JournalStore.readJournal`'s contract.
+	 */
+	async readJournal(): Promise<JournalContents> {
+		const range = journalRange();
+		const entries = await drain(this.db.iterator({ gte: range.gte, lt: range.lt }));
+		let appliedThrough = 0;
+		const records: JournalRecord[] = [];
+		for (const [key, value] of entries) {
+			if (isJournalMarkKey(key)) {
+				appliedThrough = this.readMark(value);
+			} else {
+				const record = this.readRecord(key, value);
+				if (record) records.push(record);
+			}
+		}
+		return { appliedThrough, records };
+	}
+
+	private readMark(value: Uint8Array): number {
+		const mark = decodeJournalMark(value);
+		if (mark === undefined || !Number.isSafeInteger(mark)) {
+			log('read-journal: the applied-through mark of %s is not a number this build can read (%d bytes) and reads as 0', this.identity, value.byteLength);
+			return 0;
+		}
+		return mark;
+	}
+
+	private readRecord(key: Uint8Array, value: Uint8Array): JournalRecord | undefined {
+		const seq = seqFromJournalKey(key);
+		try {
+			const record = decodeJournalRecord(value);
+			if (record.seq === seq) return record;
+			log('read-journal: a journal record of %s is numbered %d but filed under %s and is left out; recovery treats its number as missing', this.identity, record.seq, String(seq));
+			return undefined;
+		} catch (err) {
+			if (!(err instanceof JournalRecordDecodeError)) throw err;
+			log('read-journal: journal record %s of %s is not one this build can read and is left out (%s); recovery treats its number as missing', String(seq), this.identity, err.message);
+			return undefined;
+		}
+	}
+
 	// NOTE: intentionally NO close(). The `LevelDBLike` handle is shared with
 	// `LevelDBKVStore` and `loadOrCreateRNPeerKey` (one db per RN peer — see the
-	// README usage), so the driver must not own its lifecycle; closing it here
-	// would break the other two. Same rationale as the IndexedDB driver. The
-	// kernel never wires the optional close() regardless.
+	// README usage), so the store must not own its lifecycle; closing it here
+	// would break the other two. Same rationale as the IndexedDB store.
 }
 
+/** The record's entries onto the batch, in order: a put stores the value, a delete removes the key. */
+function putEntries(batch: LevelDBWriteBatchLike, record: JournalRecord): void {
+	for (const { key, value } of record.entries) {
+		const encoded = keyBytes(key);
+		if (value === undefined) batch.delete(encoded); else batch.put(encoded, value);
+	}
+}
+
+/** The write group's and the journal backend's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer` and `now`). */
+export type LevelDBRawStorageOptions = WriteGroupOptions & JournalBatchBackendOptions;
+
 /**
- * LevelDB-backed {@link IRawStorage} for React Native peers, now a thin shell
- * over the shared {@link KvRawStorage} kernel driven by a {@link LevelDBStoreDriver}.
- * The public name/constructor (`new LevelDBRawStorage(db)`) is unchanged so
- * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
- * and the driver supplies LevelDB behavior.
+ * LevelDB-backed {@link IRawStorage} for React Native peers: the shared {@link KvRawStorage}
+ * kernel over a {@link WriteGroupDriver} over a {@link JournalBatchBackend} over a
+ * {@link LevelDBJournalStore}. Every write resolves into the driver's in-memory overlay; `flush()`
+ * hands the group to the backend as one LevelDB batch — applied before the flush resolves, or,
+ * for a flush with a window on a handle that can sync, appended as one journal record and applied
+ * by the deadline. The public name/constructor (`new LevelDBRawStorage(db)`) is unchanged so
+ * existing imports keep resolving.
  *
- * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
- * (the LevelDB driver always implements them, so the kernel constructor always
- * wires them) — the base declares them optional, but every RN consumer relies on
- * them.
+ * `listBlockIds`/`getApproximateBytesUsed`/`getStoreIdentity`/`close` are re-declared here as
+ * always-present (the store always implements the first three, so the backend, driver and kernel
+ * always wire them, and the driver always has a `close`) — the base declares them optional, but
+ * every RN consumer relies on them. `close()` applies what is still held and disarms the timers;
+ * it does not close the shared handle, which the host closes afterwards.
  */
 export class LevelDBRawStorage extends KvRawStorage {
 	declare listBlockIds: () => AsyncIterable<BlockId>;
 	declare getApproximateBytesUsed: () => Promise<number>;
 	declare getStoreIdentity: () => StoreIdentity;
+	declare close: () => Promise<void>;
 
-	constructor(db: LevelDBLike) {
-		super(new LevelDBStoreDriver(db));
+	constructor(db: LevelDBLike, options: LevelDBRawStorageOptions = {}) {
+		super(new WriteGroupDriver(new JournalBatchBackend(new LevelDBJournalStore(db), options), options));
 	}
 }