@optimystic/db-p2p 0.14.1 → 0.16.3

package/src/storage/block-storage.ts

@@ -1,4 +1,4 @@
-import type { BlockId, IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
+import type { BlockId, IBlock, Transform, ActionId, ActionRev, ActionTransform } from "@optimystic/db-core";
 import { Latches, applyTransform, hashString } from "@optimystic/db-core";
 import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from "./struct.js";
 import type { IRawStorage } from "./i-raw-storage.js";
@@ -8,11 +8,24 @@ import { createLogger } from "../logger.js";
 
 const log = createLogger('block-storage');
 
+/**
+ * Default checkpoint cadence: a full materialization is retained at every `CHECKPOINT_INTERVAL`th
+ * revision (plus the tip and each range floor). This bounds the maximum replay depth for any read
+ * to at most `CHECKPOINT_INTERVAL` forward transforms. See {@link BlockStorage.pruneSupersededMaterialization}.
+ */
+const CHECKPOINT_INTERVAL = 32;
+
 export class BlockStorage implements IBlockStorage {
 	constructor(
 		private readonly blockId: BlockId,
 		private readonly storage: IRawStorage,
-		private readonly restoreCallback?: RestoreCallback
+		private readonly restoreCallback?: RestoreCallback,
+		/**
+		 * Revisions where `rev % checkpointInterval === 0` retain a full materialization even after they
+		 * stop being the tip. Optional (default {@link CHECKPOINT_INTERVAL}); tests inject a small value
+		 * to exercise sweeping without committing 32+ revisions.
+		 */
+		private readonly checkpointInterval: number = CHECKPOINT_INTERVAL
 	) { }
 
 	async getLatest(): Promise<ActionRev | undefined> {
@@ -54,7 +67,12 @@ export class BlockStorage implements IBlockStorage {
 		log('pend blockId=%s actionId=%s', this.blockId, actionId);
 		let meta = await this.storage.getMetadata(this.blockId);
 		if (!meta) {
-			meta = { latest: undefined, ranges: [[0]] };
+			// A freshly-pended block holds NO committed revision, so it can reconstruct
+			// nothing yet: seed empty ranges. The first commit anchors an OPEN-ENDED span at
+			// the earliest held rev E ([E, +inf)); later commits/recover merge into it via
+			// setLatest/recover. Seeding open-ended `[[0]]` would falsely claim coverage of the
+			// un-held revs below E and disable ensureRevision's restore path.
+			meta = { latest: undefined, ranges: [] };
 			await this.storage.saveMetadata(this.blockId, meta);
 		}
 		await this.storage.savePendingTransaction(this.blockId, actionId, transform);
@@ -73,6 +91,25 @@ export class BlockStorage implements IBlockStorage {
 		await this.storage.saveMaterializedBlock(this.blockId, actionId, block);
 	}
 
+	async pruneSupersededMaterialization(prior: ActionRev): Promise<void> {
+		const meta = await this.storage.getMetadata(this.blockId);
+		// No metadata / no committed tip yet ⇒ nothing has superseded `prior`; leave it.
+		if (!meta || meta.latest === undefined) {
+			return;
+		}
+		// `prior` is the PRIOR latest, so it shares the (latest) range containing meta.latest.rev — its
+		// floor is that span's start. Retain if it is the tip, that floor, or a checkpoint rev.
+		const rangeFloor = this.rangeFloorOf(meta.latest.rev, meta.ranges);
+		if (this.isRetainedRev(prior.rev, meta.latest.rev, rangeFloor)) {
+			return;
+		}
+		// Redundant: `prior`'s forward transform is retained, so it stays reconstructible by replay from
+		// the nearest retained materialization below it. Delete routes to the driver's deleteMaterialized;
+		// a no-op at the driver when `prior.rev` carried no materialization (e.g. a tombstone rev).
+		await this.storage.saveMaterializedBlock(this.blockId, prior.actionId, undefined);
+		log('prune blockId=%s rev=%d actionId=%s', this.blockId, prior.rev, prior.actionId);
+	}
+
 	async saveRevision(rev: number, actionId: ActionId): Promise<void> {
 		await this.storage.saveRevision(this.blockId, rev, actionId);
 	}
@@ -87,7 +124,24 @@ export class BlockStorage implements IBlockStorage {
 		if (!meta) {
 			throw new Error(`Block ${this.blockId} not found`);
 		}
+		// Capture the prior latest rev BEFORE overwriting: coverage anchors to the earliest held rev.
+		const prevRev = meta.latest?.rev;
 		meta.latest = latest;
+		// NOTE: re-sorts (mergeRanges) the whole ranges array on every commit; if a block ever
+		// accumulates many disjoint ranges and commits show as slow, keep a running merged structure.
+		// `getBlock(r)` is served by materializeBlock's DESCENDING walk (highest committed rev <= r).
+		// Once this node holds the chain from the block's earliest committed rev E, EVERY rev >= E is
+		// serveable locally: a read at any r >= E resolves to the highest committed rev <= r (at worst
+		// the latest, which is materialized), so coverage is the OPEN-ENDED span [E, +inf) — not the
+		// single point [L, L+1) (which wrongly missed reads above L, e.g. a block read at the collection
+		// tip after a later commit touched only its siblings) and not [0, +inf) (which wrongly claimed
+		// the un-held revs below E). Claim open-ended from the prior latest (>= E via merge); the first
+		// commit (prevRev undefined) anchors the span at E = L. mergeRanges folds it into the existing
+		// [E, +inf). Only revs BELOW E miss inRanges, which is exactly the genuine-gap/restore case.
+		// Range + latest advance in one saveMetadata write (atomic under the commit latch), so a crash
+		// before this call advances neither.
+		meta.ranges.unshift([prevRev ?? latest.rev]);
+		meta.ranges = mergeRanges(meta.ranges);
 		await this.storage.saveMetadata(this.blockId, meta);
 	}
 
@@ -115,6 +169,13 @@ export class BlockStorage implements IBlockStorage {
 		if (maxRev > currentRev && maxActionId !== undefined) {
 			const advanced: ActionRev = { rev: maxRev, actionId: maxActionId };
 			meta.latest = advanced;
+			// The lost setLatest would have merged each recovered revision's range; redo that
+			// here. Open-ended from currentRev+1 (see setLatest): every rev in (currentRev, maxRev]
+			// was verified present in the committed log above, and any rev > maxRev resolves via the
+			// descending walk to maxRev's materialization — so [currentRev+1, +inf) is honest. It joins
+			// the prior [E, currentRev+1) (from the earlier setLatest) into one open-ended [E, +inf).
+			meta.ranges.unshift([currentRev + 1]);
+			meta.ranges = mergeRanges(meta.ranges);
 			await this.storage.saveMetadata(this.blockId, meta);
 			log('recover blockId=%s advanced latest from rev=%d to rev=%d', this.blockId, currentRev, maxRev);
 			return { reconciled: true, latest: advanced };
@@ -130,92 +191,91 @@ export class BlockStorage implements IBlockStorage {
 		// idempotent. Never random/time-based — that would mint a new revision per retry.
 		const actionId = source?.actionId ?? await hashString(`${this.blockId}:${JSON.stringify(block)}`);
 
-		// Serialize the read-modify-write on this block's metadata (mirrors ensureRevision).
-		const lockId = `BlockStorage.saveReplica:${this.blockId}`;
-		const release = await Latches.acquire(lockId);
-		try {
-			let meta = await this.storage.getMetadata(this.blockId);
-
-			// Monotonic guard: an equal-or-newer revision is already held. The block is
-			// durably present; do not downgrade `latest` or rewrite the metadata.
-			if (meta?.latest && meta.latest.rev >= rev) {
-				log('replica:skip blockId=%s rev=%d held=%d', this.blockId, rev, meta.latest.rev);
-				return meta.latest;
-			}
-
-			// Write rev → actionId, the action transform, and the materialized block.
-			// `{ insert: block }` satisfies saveRestored's write invariants; on the serving
-			// path materializeBlock returns the materialized block directly (single rev), so
-			// this transform is never applied — see ticket notes.
-			const archive: BlockArchive = {
-				blockId: this.blockId,
-				revisions: {
-					[rev]: {
-						action: { actionId, rev, transform: { insert: block } },
-						block
-					}
-				},
-				range: [rev, rev + 1]
-			};
-			await this.saveRestored(archive);
-
-			// Seed metadata when absent, advance latest, and merge the covered range.
-			if (!meta) {
-				meta = { latest: undefined, ranges: [] };
-			}
-			meta.latest = { rev, actionId };
-			meta.ranges.unshift([rev, rev + 1]);
-			meta.ranges = mergeRanges(meta.ranges);
-			await this.storage.saveMetadata(this.blockId, meta);
-
-			log('replica:save blockId=%s rev=%d actionId=%s', this.blockId, rev, actionId);
-			return meta.latest;
-		} finally {
-			release();
-		}
+		// Replica revision carries the materialized block. `{ insert: block }` satisfies saveRestored's
+		// write invariants; on the serving path materializeBlock returns the materialized block directly
+		// (single rev), so this transform is never applied — see ticket notes.
+		return await this.saveForwardRevision(
+			rev,
+			actionId,
+			{ action: { actionId, rev, transform: { insert: block } }, block },
+			'replica'
+		);
 	}
 
 	async saveDeletion(source: ActionRev): Promise<ActionRev> {
 		const { rev, actionId } = source;
 
-		// Share the saveReplica latch: both do a read-modify-write of `meta.latest`, so they must be
-		// mutually exclusive on this block to keep the monotonic guard sound.
+		// Forward tombstone: a `{ delete: true }` transform and NO materialized block. saveRestored
+		// skips materialization when `block` is absent, so the reverse-apply in materializeBlock
+		// resolves this revision to an absent block (read-back as undefined).
+		return await this.saveForwardRevision(
+			rev,
+			actionId,
+			{ action: { actionId, rev, transform: { delete: true } } },
+			'deletion'
+		);
+	}
+
+	/**
+	 * Shared forward-write path for saveReplica and saveDeletion. Both append a single new revision
+	 * that ADVANCES `latest` (never rewrites history): acquire the block's metadata latch, apply the
+	 * monotonic guard, saveRestored a one-revision archive, then seed/advance/merge metadata.
+	 *
+	 * The only per-caller difference is the revision `body`: a replica carries `{ insert: block }`
+	 * plus the materialized `block`; a deletion carries `{ delete: true }` and no block. `rev` and
+	 * `actionId` are passed alongside `body` because the guard and the `latest` advance need them
+	 * independently of the archive body.
+	 */
+	private async saveForwardRevision(
+		rev: number,
+		actionId: ActionId,
+		body: { action: ActionTransform; block?: IBlock },
+		logLabel: 'replica' | 'deletion'
+	): Promise<ActionRev> {
+		// Serialize the read-modify-write on this block's metadata (mirrors ensureRevision). saveReplica
+		// and saveDeletion deliberately SHARE this one lock id (keyed `saveReplica`, NOT per-method):
+		// both do a read-modify-write of `meta.latest`, so they must be mutually exclusive on this block
+		// to keep the monotonic guard sound against a concurrent replica+deletion.
 		const lockId = `BlockStorage.saveReplica:${this.blockId}`;
 		const release = await Latches.acquire(lockId);
 		try {
 			let meta = await this.storage.getMetadata(this.blockId);
 
-			// Monotonic guard: an equal-or-newer revision is already held. Do not downgrade `latest`
-			// or rewrite metadata — the tombstone (or a later revision) is already durable.
+			// Monotonic guard: an equal-or-newer revision is already held. The block (or tombstone) is
+			// durably present; do not downgrade `latest` or rewrite the metadata.
 			if (meta?.latest && meta.latest.rev >= rev) {
-				log('deletion:skip blockId=%s rev=%d held=%d', this.blockId, rev, meta.latest.rev);
+				log('%s:skip blockId=%s rev=%d held=%d', logLabel, this.blockId, rev, meta.latest.rev);
 				return meta.latest;
 			}
 
-			// Forward tombstone: a `{ delete: true }` transform and NO materialized block. saveRestored
-			// skips materialization when `block` is absent, so the reverse-apply in materializeBlock
-			// resolves this revision to an absent block (read-back as undefined).
+			// One-revision archive. A replica's body carries the materialized block; a deletion's body
+			// omits it (forward tombstone). saveRestored skips materialization when `block` is absent,
+			// so a tombstone reverse-applies to an absent block (read back as undefined).
 			const archive: BlockArchive = {
 				blockId: this.blockId,
 				revisions: {
-					[rev]: {
-						action: { actionId, rev, transform: { delete: true } }
-					}
+					[rev]: body
 				},
 				range: [rev, rev + 1]
 			};
 			await this.saveRestored(archive);
 
 			// Seed metadata when absent, advance latest, and merge the covered range.
+			const prevRev = meta?.latest?.rev;
 			if (!meta) {
 				meta = { latest: undefined, ranges: [] };
 			}
 			meta.latest = { rev, actionId };
-			meta.ranges.unshift([rev, rev + 1]);
+			// Open-ended coverage from the earliest held rev (see setLatest): the descending walk serves
+			// any rev >= the anchor. A prior latest at prevRev (< rev per the monotonic guard) is a
+			// materialized point, so anchor at prevRev; the first write (prevRev undefined) anchors at
+			// rev. Freshness of a stale replica is a separate (replication-lag) concern from what this
+			// node can locally reconstruct, which is exactly what ranges records.
+			meta.ranges.unshift([prevRev ?? rev]);
 			meta.ranges = mergeRanges(meta.ranges);
 			await this.storage.saveMetadata(this.blockId, meta);
 
-			log('deletion:save blockId=%s rev=%d actionId=%s', this.blockId, rev, actionId);
+			log('%s:save blockId=%s rev=%d actionId=%s', logLabel, this.blockId, rev, actionId);
 			return meta.latest;
 		} finally {
 			release();
@@ -253,7 +313,7 @@ export class BlockStorage implements IBlockStorage {
 		}
 	}
 
-	private async materializeBlock(_meta: BlockMetadata, targetRev: number): Promise<{ block: IBlock, actionRev: ActionRev } | undefined> {
+	private async materializeBlock(meta: BlockMetadata, targetRev: number): Promise<{ block: IBlock, actionRev: ActionRev } | undefined> {
 		let block: IBlock | undefined;
 		let materializedActionRev: ActionRev | undefined;
 		const actions: ActionRev[] = [];
@@ -293,7 +353,26 @@ export class BlockStorage implements IBlockStorage {
 			return undefined;
 		}
 		if (actions.length) {
-			await this.storage.saveMaterializedBlock(this.blockId, actions[0]!.actionId, block);
+			// Re-cache the recomputed materialization ONLY at a retained rev (checkpoint / range floor /
+			// tip). Caching unconditionally would let a cold read at a non-checkpoint historical rev
+			// re-add a materialization the checkpoint sweep is designed to remove — storage would regrow
+			// via reads. Skipping it means a repeated cold read re-replays each time, bounded by
+			// `checkpointInterval` transforms.
+			// NOTE: cold non-checkpoint historical reads re-replay every time (up to `checkpointInterval`
+			// forward transforms). Acceptable — historical reads are rare and replay is depth-bounded. If
+			// they ever show as hot, cache at the nearest checkpoint below the target instead of skipping.
+			// Read metadata FRESH for the retention decision: the `meta` passed in was captured by getBlock
+			// BEFORE ensureRevision, which may have restored the containing range during this same read
+			// (ensureRevision mutates its own re-read, not this snapshot). A stale `meta.ranges` would send
+			// rangeFloorOf into its fallback (treats the target as its own floor ⇒ wrongly "retained"),
+			// re-caching a rev the sweep means to prune — regrowing storage via reads of restored ranges.
+			const retentionMeta = (await this.storage.getMetadata(this.blockId)) ?? meta;
+			const cacheRev = actions[0]!.rev;
+			const latestRev = retentionMeta.latest?.rev ?? cacheRev;
+			const rangeFloor = this.rangeFloorOf(cacheRev, retentionMeta.ranges);
+			if (this.isRetainedRev(cacheRev, latestRev, rangeFloor)) {
+				await this.storage.saveMaterializedBlock(this.blockId, actions[0]!.actionId, block);
+			}
 			return { block, actionRev: actions[0]! };
 		}
 		return { block, actionRev: materializedActionRev };
@@ -323,4 +402,33 @@ export class BlockStorage implements IBlockStorage {
 			rev >= range[0] && (range[1] === undefined || rev < range[1])
 		);
 	}
+
+	/**
+	 * Checkpoint retention predicate. A materialization at `rev` must be kept iff it is the tip
+	 * (`latestRev` — the common read target and the replay base for the next commit), the floor of its
+	 * contiguous range (`rangeFloor` — the descending walk in {@link materializeBlock} has nothing below
+	 * the floor to fall back to), or a periodic checkpoint (`rev % checkpointInterval === 0`, which bounds
+	 * replay depth). Otherwise the materialization is prunable — its forward transform is retained, so the
+	 * rev stays reconstructible by replay from the nearest retained materialization below it. The floor
+	 * clause is SEPARATE and mandatory: absolute `rev % K` checkpoints do not automatically land on the
+	 * floor (e.g. floor `E = 1`, `K = 32`).
+	 */
+	private isRetainedRev(rev: number, latestRev: number, rangeFloor: number): boolean {
+		return rev === latestRev
+			|| rev === rangeFloor
+			|| rev % this.checkpointInterval === 0;
+	}
+
+	/** Start of the contiguous `ranges` span containing `rev`. Falls back to `rev` itself when no span
+	 * contains it — unreachable for a committed rev (setLatest always merges the containing span before a
+	 * prune/read runs), and the conservative direction (treats `rev` as its own floor ⇒ retained). */
+	private rangeFloorOf(rev: number, ranges: RevisionRange[]): number {
+		for (const range of ranges) {
+			const [start, end] = range;
+			if (rev >= start && (end === undefined || rev < end)) {
+				return start;
+			}
+		}
+		return rev;
+	}
 }

package/src/storage/i-block-storage.ts

@@ -35,6 +35,15 @@ export interface IBlockStorage {
     /** Saves a materialized block */
     saveMaterializedBlock(actionId: ActionId, block: IBlock | undefined): Promise<void>;
 
+    /**
+     * Delete the materialized copy at `prior` if it is now redundant under the checkpoint
+     * retention policy (not the tip, not its range floor, not a checkpoint rev). The forward
+     * transform for `prior.rev` is retained, so the rev stays reconstructible by replay.
+     * No-op if `prior.rev` must be retained or has no materialization (e.g. a tombstone rev).
+     * Must be called under the per-block commit latch (serialized against concurrent commit).
+     */
+    pruneSupersededMaterialization(prior: ActionRev): Promise<void>;
+
     /** Saves a revision */
     saveRevision(rev: number, actionId: ActionId): Promise<void>;
 

package/src/storage/i-raw-storage.ts

@@ -37,4 +37,18 @@ export interface IRawStorage {
 	 * advisory — `StorageMonitor` treats a missing implementation as 0.
 	 */
 	getApproximateBytesUsed?(): Promise<number>;
+
+	/**
+	 * Enumerate the block ids that currently have durable state in this backend
+	 * (one id per block that has committed/replicated metadata). Used at node
+	 * startup to seed the resilience monitors' owned-block tracked set from blocks
+	 * already on disk from a previous run, so churn-spread / rebalance protection
+	 * covers them without waiting for each to be touched again.
+	 *
+	 * Streamed (AsyncIterable) so a large store does not force the whole id list
+	 * into memory at once. Order is unspecified. Optional: a backend that omits it
+	 * (or an in-memory backend with nothing durable across a restart) simply yields
+	 * no seed — the monitors still populate over time via the live change feed.
+	 */
+	listBlockIds?(): AsyncIterable<BlockId>;
 }

package/src/storage/kv-raw-storage.ts

@@ -0,0 +1,135 @@
+import type { BlockId, ActionId, ActionRev, Transform, IBlock } from "@optimystic/db-core";
+import type { BlockMetadata } from "./struct.js";
+import type { IRawStorage } from "./i-raw-storage.js";
+import type { RawStoreDriver } from "./raw-store-driver.js";
+import { encodeJson, decodeJson, encodeActionId, decodeActionId } from "./raw-store-codec.js";
+
+/**
+ * Shared ordered-KV storage kernel. Implements the full {@link IRawStorage}
+ * surface over a {@link RawStoreDriver}, owning all value (de)serialization and
+ * call orchestration so each backend only has to expose its five logical stores
+ * as bytes-valued maps over its native mechanism.
+ *
+ * The genuinely-shared logic lives ABOVE the storage primitive: the JSON/string
+ * codec for the four value types, `listRevisions`' lo/hi/reverse bound
+ * computation, `saveMaterializedBlock`'s put-or-delete branch, and the
+ * passthroughs. Key layout / storage topology stays in the driver, because the
+ * backends do NOT share one — LevelDB is a single ordered byte keyspace, SQLite
+ * five relational tables, IndexedDB five object stores, the filesystem a
+ * directory tree.
+ */
+export class KvRawStorage implements IRawStorage {
+	/**
+	 * Optional passthroughs are wired in the constructor ONLY when the driver
+	 * provides them, so a `StorageMonitor` / owned-block seed that feature-detects
+	 * (`typeof storage.listBlockIds === 'function'`) sees the driver's true
+	 * capability instead of a stub that silently reports 0 / no seed.
+	 */
+	listBlockIds?: () => AsyncIterable<BlockId>;
+	getApproximateBytesUsed?: () => Promise<number>;
+
+	constructor(private readonly driver: RawStoreDriver) {
+		if (driver.listBlockIds) {
+			this.listBlockIds = () => driver.listBlockIds!();
+		}
+		if (driver.approximateBytesUsed) {
+			this.getApproximateBytesUsed = () => driver.approximateBytesUsed!();
+		}
+	}
+
+	// --- Metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined> {
+		const bytes = await this.driver.getMetadata(blockId);
+		return bytes === undefined ? undefined : decodeJson<BlockMetadata>(bytes);
+	}
+
+	// NOTE: every value write funnels through the driver put/delete calls in the
+	// methods below (saveMetadata / saveRevision / save*Transaction /
+	// saveMaterializedBlock). This is the single choke point where an incremental
+	// byte counter would hook in, replacing the per-driver full-scan
+	// getApproximateBytesUsed. The chosen capacity-estimate mechanism is instead a
+	// short-TTL cache over the full scan in StorageMonitor (see storage-monitor.ts
+	// `usedBytesCacheTtlMs`) — backend-agnostic, no write-path changes, and ring
+	// selection tolerates the bounded staleness by design. The counter remains a
+	// future option only if TTL staleness ever proves insufficient; do NOT
+	// implement it here — leave the write path a single seam.
+	async saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void> {
+		await this.driver.putMetadata(blockId, encodeJson(metadata));
+	}
+
+	// --- Revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined> {
+		const bytes = await this.driver.getRevision(blockId, rev);
+		return bytes === undefined ? undefined : decodeActionId(bytes);
+	}
+
+	async saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void> {
+		await this.driver.putRevision(blockId, rev, encodeActionId(actionId));
+	}
+
+	async *listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev> {
+		// Both bounds inclusive; ordering follows startRev→endRev direction. Empty
+		// revs are skipped by the driver's range. Preserves the exact semantics of
+		// every existing backend.
+		const ascending = startRev <= endRev;
+		const lo = ascending ? startRev : endRev;
+		const hi = ascending ? endRev : startRev;
+		for await (const [rev, bytes] of this.driver.rangeRevisions(blockId, lo, hi, !ascending)) {
+			yield { rev, actionId: decodeActionId(bytes) };
+		}
+	}
+
+	// --- Pending transactions ---
+
+	async getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		const bytes = await this.driver.getPending(blockId, actionId);
+		return bytes === undefined ? undefined : decodeJson<Transform>(bytes);
+	}
+
+	async savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.driver.putPending(blockId, actionId, encodeJson(transform));
+	}
+
+	async deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.driver.deletePending(blockId, actionId);
+	}
+
+	async *listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId> {
+		yield* this.driver.listPendingActionIds(blockId);
+	}
+
+	// --- Committed transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		const bytes = await this.driver.getTransaction(blockId, actionId);
+		return bytes === undefined ? undefined : decodeJson<Transform>(bytes);
+	}
+
+	async saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.driver.putTransaction(blockId, actionId, encodeJson(transform));
+	}
+
+	// --- Materialized blocks ---
+
+	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {
+		const bytes = await this.driver.getMaterialized(blockId, actionId);
+		return bytes === undefined ? undefined : decodeJson<IBlock>(bytes);
+	}
+
+	async saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void> {
+		// Present ⇒ put the materialized block; absent ⇒ delete (tombstone / truncation).
+		if (block) {
+			await this.driver.putMaterialized(blockId, actionId, encodeJson(block));
+		} else {
+			await this.driver.deleteMaterialized(blockId, actionId);
+		}
+	}
+
+	// --- Promote (the only cross-key atomic op; driver owns atomicity) ---
+
+	async promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.driver.promote(blockId, actionId);
+	}
+}