@optimystic/db-p2p 0.22.0 → 0.24.0

package/src/storage/memory-store-driver.ts

@@ -1,157 +1,157 @@
-import type { BlockId, ActionId } from "@optimystic/db-core";
-import type { RawStoreDriver } from "./raw-store-driver.js";
-
-/**
- * In-memory {@link RawStoreDriver}: the five logical block-storage stores as
- * `Map`s of `Uint8Array` values. `KvRawStorage` hands this driver bytes produced
- * by `JSON`-encode and reads them back via `JSON`-decode, so every get yields a
- * fresh object and every save stored an independent byte snapshot BY
- * CONSTRUCTION — the old `structuredClone`-on-every-get/put discipline is now
- * structural, not a rule a maintainer has to remember. The driver therefore
- * stores the byte reference directly: those bytes are never mutated by the
- * kernel or exposed to callers as a mutable handle.
- */
-export class MemoryStoreDriver implements RawStoreDriver {
-	private readonly metadata = new Map<BlockId, Uint8Array>();
-	private readonly revisions = new Map<string, Uint8Array>(); // `${blockId}:${rev}` -> actionId bytes
-	private readonly pending = new Map<string, Uint8Array>();    // `${blockId}:${actionId}` -> transform bytes
-	private readonly transactions = new Map<string, Uint8Array>();
-	private readonly materialized = new Map<string, Uint8Array>();
-
-	private revisionKey(blockId: BlockId, rev: number): string {
-		return `${blockId}:${rev}`;
-	}
-
-	private actionKey(blockId: BlockId, actionId: ActionId): string {
-		return `${blockId}:${actionId}`;
-	}
-
-	// --- metadata ---
-
-	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
-		return this.metadata.get(blockId);
-	}
-
-	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
-		this.metadata.set(blockId, value);
-	}
-
-	// --- revisions ---
-
-	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.revisions.get(this.revisionKey(blockId, rev));
-	}
-
-	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		this.revisions.set(this.revisionKey(blockId, rev), value);
-	}
-
-	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
-		// Drain into an array before yielding (drain-before-yield contract): the
-		// consumer awaits between yields, and a Map has no live cursor to pin, but
-		// this keeps the memory driver's semantics identical to the native backends.
-		const results: [number, Uint8Array][] = [];
-		for (let rev = lo; rev <= hi; rev++) {
-			const value = this.revisions.get(this.revisionKey(blockId, rev));
-			if (value !== undefined) {
-				results.push([rev, value]);
-			}
-		}
-		if (reverse) {
-			results.reverse();
-		}
-		for (const result of results) {
-			yield result;
-		}
-	}
-
-	// --- pending ---
-
-	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.pending.get(this.actionKey(blockId, actionId));
-	}
-
-	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		this.pending.set(this.actionKey(blockId, actionId), value);
-	}
-
-	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
-		this.pending.delete(this.actionKey(blockId, actionId));
-	}
-
-	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
-		const prefix = `${blockId}:`;
-		// Snapshot before yielding (drain-before-yield): a concurrent putPending during
-		// the scan must not invalidate a live map iterator.
-		const ids: ActionId[] = [];
-		for (const key of Array.from(this.pending.keys())) {
-			if (key.startsWith(prefix)) {
-				ids.push(key.substring(prefix.length) as ActionId);
-			}
-		}
-		for (const id of ids) {
-			yield id;
-		}
-	}
-
-	// --- transactions ---
-
-	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.transactions.get(this.actionKey(blockId, actionId));
-	}
-
-	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		this.transactions.set(this.actionKey(blockId, actionId), value);
-	}
-
-	// --- materialized ---
-
-	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.materialized.get(this.actionKey(blockId, actionId));
-	}
-
-	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		this.materialized.set(this.actionKey(blockId, actionId), value);
-	}
-
-	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
-		this.materialized.delete(this.actionKey(blockId, actionId));
-	}
-
-	// --- promote (atomic move; synchronous Map ops make it indivisible here) ---
-
-	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
-		const key = this.actionKey(blockId, actionId);
-		const value = this.pending.get(key);
-		if (value === undefined) {
-			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
-		}
-		this.transactions.set(key, value);
-		this.pending.delete(key);
-	}
-
-	// --- optional passthroughs ---
-
-	async *listBlockIds(): AsyncIterable<BlockId> {
-		// Snapshot the keys before yielding so a concurrent putMetadata during the scan
-		// doesn't invalidate a live map iterator. Fresh in-memory storage is empty, so at
-		// real process startup this yields nothing — it exists so the seed path can be
-		// unit-tested against a pre-populated store.
-		for (const blockId of Array.from(this.metadata.keys())) {
-			yield blockId;
-		}
-	}
-
-	async approximateBytesUsed(): Promise<number> {
-		let total = 0;
-		for (const [blockId, value] of this.metadata) {
-			total += blockId.length + value.byteLength;
-		}
-		for (const store of [this.revisions, this.pending, this.transactions, this.materialized]) {
-			for (const [key, value] of store) {
-				total += key.length + value.byteLength;
-			}
-		}
-		return total;
-	}
-}
+import type { BlockId, ActionId } from "@optimystic/db-core";
+import type { RawStoreDriver } from "./raw-store-driver.js";
+
+/**
+ * In-memory {@link RawStoreDriver}: the five logical block-storage stores as
+ * `Map`s of `Uint8Array` values. `KvRawStorage` hands this driver bytes produced
+ * by `JSON`-encode and reads them back via `JSON`-decode, so every get yields a
+ * fresh object and every save stored an independent byte snapshot BY
+ * CONSTRUCTION — the old `structuredClone`-on-every-get/put discipline is now
+ * structural, not a rule a maintainer has to remember. The driver therefore
+ * stores the byte reference directly: those bytes are never mutated by the
+ * kernel or exposed to callers as a mutable handle.
+ */
+export class MemoryStoreDriver implements RawStoreDriver {
+	private readonly metadata = new Map<BlockId, Uint8Array>();
+	private readonly revisions = new Map<string, Uint8Array>(); // `${blockId}:${rev}` -> actionId bytes
+	private readonly pending = new Map<string, Uint8Array>();    // `${blockId}:${actionId}` -> transform bytes
+	private readonly transactions = new Map<string, Uint8Array>();
+	private readonly materialized = new Map<string, Uint8Array>();
+
+	private revisionKey(blockId: BlockId, rev: number): string {
+		return `${blockId}:${rev}`;
+	}
+
+	private actionKey(blockId: BlockId, actionId: ActionId): string {
+		return `${blockId}:${actionId}`;
+	}
+
+	// --- metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
+		return this.metadata.get(blockId);
+	}
+
+	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
+		this.metadata.set(blockId, value);
+	}
+
+	// --- revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		return this.revisions.get(this.revisionKey(blockId, rev));
+	}
+
+	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		this.revisions.set(this.revisionKey(blockId, rev), value);
+	}
+
+	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+		// Drain into an array before yielding (drain-before-yield contract): the
+		// consumer awaits between yields, and a Map has no live cursor to pin, but
+		// this keeps the memory driver's semantics identical to the native backends.
+		const results: [number, Uint8Array][] = [];
+		for (let rev = lo; rev <= hi; rev++) {
+			const value = this.revisions.get(this.revisionKey(blockId, rev));
+			if (value !== undefined) {
+				results.push([rev, value]);
+			}
+		}
+		if (reverse) {
+			results.reverse();
+		}
+		for (const result of results) {
+			yield result;
+		}
+	}
+
+	// --- pending ---
+
+	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.pending.get(this.actionKey(blockId, actionId));
+	}
+
+	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		this.pending.set(this.actionKey(blockId, actionId), value);
+	}
+
+	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
+		this.pending.delete(this.actionKey(blockId, actionId));
+	}
+
+	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
+		const prefix = `${blockId}:`;
+		// Snapshot before yielding (drain-before-yield): a concurrent putPending during
+		// the scan must not invalidate a live map iterator.
+		const ids: ActionId[] = [];
+		for (const key of Array.from(this.pending.keys())) {
+			if (key.startsWith(prefix)) {
+				ids.push(key.substring(prefix.length) as ActionId);
+			}
+		}
+		for (const id of ids) {
+			yield id;
+		}
+	}
+
+	// --- transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.transactions.get(this.actionKey(blockId, actionId));
+	}
+
+	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		this.transactions.set(this.actionKey(blockId, actionId), value);
+	}
+
+	// --- materialized ---
+
+	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.materialized.get(this.actionKey(blockId, actionId));
+	}
+
+	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		this.materialized.set(this.actionKey(blockId, actionId), value);
+	}
+
+	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
+		this.materialized.delete(this.actionKey(blockId, actionId));
+	}
+
+	// --- promote (atomic move; synchronous Map ops make it indivisible here) ---
+
+	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
+		const key = this.actionKey(blockId, actionId);
+		const value = this.pending.get(key);
+		if (value === undefined) {
+			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+		}
+		this.transactions.set(key, value);
+		this.pending.delete(key);
+	}
+
+	// --- optional passthroughs ---
+
+	async *listBlockIds(): AsyncIterable<BlockId> {
+		// Snapshot the keys before yielding so a concurrent putMetadata during the scan
+		// doesn't invalidate a live map iterator. Fresh in-memory storage is empty, so at
+		// real process startup this yields nothing — it exists so the seed path can be
+		// unit-tested against a pre-populated store.
+		for (const blockId of Array.from(this.metadata.keys())) {
+			yield blockId;
+		}
+	}
+
+	async approximateBytesUsed(): Promise<number> {
+		let total = 0;
+		for (const [blockId, value] of this.metadata) {
+			total += blockId.length + value.byteLength;
+		}
+		for (const store of [this.revisions, this.pending, this.transactions, this.materialized]) {
+			for (const [key, value] of store) {
+				total += key.length + value.byteLength;
+			}
+		}
+		return total;
+	}
+}

package/src/storage/raw-store-codec.ts

@@ -1,42 +1,42 @@
-import type { ActionId } from "@optimystic/db-core";
-
-/**
- * Value codec shared by every `KvRawStorage`-backed store. Values cross the
- * `RawStoreDriver` boundary as `Uint8Array`, so this module is the single place
- * that turns `BlockMetadata`/`Transform`/`IBlock` (via JSON) and the `ActionId`
- * string (via UTF-8) into bytes and back.
- *
- * Because a get always decodes fresh bytes into a NEW object and a save always
- * encodes an independent byte copy, the clone-on-store / clone-on-read invariant
- * that in-memory storage used to enforce by hand (`structuredClone`) is now
- * structural for kernel-backed stores — see docs/internals.md "Storage Returns
- * References".
- *
- * Round-trip fidelity matters for `BlockMetadata`: an open-ended `RevisionRange`
- * is encoded `[E]` (one element, upper bound `undefined`). `JSON.stringify([5])`
- * → `"[5]"` → `JSON.parse` → `[5]`, so the open-ended encoding survives byte-exact.
- * Do NOT normalize ranges here.
- */
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-
-/** JSON-encode a value (`BlockMetadata` / `Transform` / `IBlock`) to UTF-8 bytes. */
-export function encodeJson<T>(value: T): Uint8Array {
-	return encoder.encode(JSON.stringify(value));
-}
-
-/** Decode UTF-8 JSON bytes back into a value. Callers guard the miss (`undefined`) first. */
-export function decodeJson<T>(bytes: Uint8Array): T {
-	return JSON.parse(decoder.decode(bytes)) as T;
-}
-
-/** Encode an `ActionId` string to UTF-8 bytes (stored as the revisions-store value). */
-export function encodeActionId(actionId: ActionId): Uint8Array {
-	return encoder.encode(actionId);
-}
-
-/** Decode UTF-8 bytes back into an `ActionId` string. */
-export function decodeActionId(bytes: Uint8Array): ActionId {
-	return decoder.decode(bytes) as ActionId;
-}
+import type { ActionId } from "@optimystic/db-core";
+
+/**
+ * Value codec shared by every `KvRawStorage`-backed store. Values cross the
+ * `RawStoreDriver` boundary as `Uint8Array`, so this module is the single place
+ * that turns `BlockMetadata`/`Transform`/`IBlock` (via JSON) and the `ActionId`
+ * string (via UTF-8) into bytes and back.
+ *
+ * Because a get always decodes fresh bytes into a NEW object and a save always
+ * encodes an independent byte copy, the clone-on-store / clone-on-read invariant
+ * that in-memory storage used to enforce by hand (`structuredClone`) is now
+ * structural for kernel-backed stores — see docs/internals.md "Storage Returns
+ * References".
+ *
+ * Round-trip fidelity matters for `BlockMetadata`: an open-ended `RevisionRange`
+ * is encoded `[E]` (one element, upper bound `undefined`). `JSON.stringify([5])`
+ * → `"[5]"` → `JSON.parse` → `[5]`, so the open-ended encoding survives byte-exact.
+ * Do NOT normalize ranges here.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** JSON-encode a value (`BlockMetadata` / `Transform` / `IBlock`) to UTF-8 bytes. */
+export function encodeJson<T>(value: T): Uint8Array {
+	return encoder.encode(JSON.stringify(value));
+}
+
+/** Decode UTF-8 JSON bytes back into a value. Callers guard the miss (`undefined`) first. */
+export function decodeJson<T>(bytes: Uint8Array): T {
+	return JSON.parse(decoder.decode(bytes)) as T;
+}
+
+/** Encode an `ActionId` string to UTF-8 bytes (stored as the revisions-store value). */
+export function encodeActionId(actionId: ActionId): Uint8Array {
+	return encoder.encode(actionId);
+}
+
+/** Decode UTF-8 bytes back into an `ActionId` string. */
+export function decodeActionId(bytes: Uint8Array): ActionId {
+	return decoder.decode(bytes) as ActionId;
+}

package/src/storage/raw-store-driver.ts

@@ -1,80 +1,80 @@
-import type { BlockId, ActionId } from "@optimystic/db-core";
-
-/**
- * Bytes-valued, per-logical-store driver surface. Each backend implements the
- * five block-storage stores (metadata, revisions, pending, transactions,
- * materialized) over its native mechanism (LevelDB tag-ranges, five SQLite
- * tables, five IndexedDB object stores, five filesystem subdirectories, five
- * in-memory maps). `KvRawStorage` layers all JSON serialization and call
- * orchestration on top — drivers never (de)serialize values and never see the
- * `BlockMetadata`/`Transform`/`IBlock` types. Drivers speak only
- * `Uint8Array`/`BlockId`/`ActionId`/`number`.
- *
- * ### Iteration semantics (drain-before-yield)
- *
- * `rangeRevisions` and `listPendingActionIds` return an `AsyncIterable`, but a
- * driver MUST drain its native cursor/iterator into memory BEFORE yielding to
- * the consumer. A live LevelDB iterator, IndexedDB transaction, or SQLite
- * cursor must not straddle the consumer's `await`s: IndexedDB auto-commits an
- * idle transaction, SQLite would hold its mutex slot, and LevelDB pins native
- * resources. The kernel encodes this as a contract (not a shared implementation)
- * because the drain is backend-specific. The conformance suite exercises it by
- * interleaving other awaits between yielded items.
- *
- * ### Promote atomicity
- *
- * `promote` is the ONLY cross-key atomic operation the kernel requires. Every
- * other write is a single put/delete. Each backend satisfies `promote` with its
- * native atomic mechanism (LevelDB batch, SQLite transaction, IndexedDB
- * readwrite transaction, filesystem rename); the kernel never assumes an
- * atomicity a backend cannot deliver.
- */
-export interface RawStoreDriver {
-	// metadata store — keyed by blockId
-	getMetadata(blockId: BlockId): Promise<Uint8Array | undefined>;
-	putMetadata(blockId: BlockId, value: Uint8Array): Promise<void>;
-
-	// revisions store — keyed by (blockId, rev), ORDERED BY rev
-	getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined>;
-	putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void>;
-	/**
-	 * Yield `[rev, value]` for every present rev in `[lo, hi]` (both inclusive),
-	 * ascending when `reverse` is false, descending when `reverse` is true. The
-	 * driver MUST drain any native cursor into memory before yielding — see the
-	 * "drain-before-yield" contract above.
-	 */
-	rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]>;
-
-	// pending store — keyed by (blockId, actionId)
-	getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
-	putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
-	deletePending(blockId: BlockId, actionId: ActionId): Promise<void>;
-	/** Yield each present pending actionId for the block. MUST drain before yielding (see above). */
-	listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId>;
-
-	// transactions store — keyed by (blockId, actionId)
-	getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
-	putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
-
-	// materialized store — keyed by (blockId, actionId)
-	getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
-	putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
-	deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void>;
-
-	/**
-	 * Atomically move `pending(blockId, actionId)` → `transactions(blockId, actionId)`:
-	 * write the transactions entry and remove the pending entry as one indivisible
-	 * step (batch / DB transaction / rename). A crash must leave exactly one of the
-	 * two states, never both/neither. Throw
-	 * `Pending action <actionId> not found for block <blockId>` when no pending
-	 * entry exists. This is the ONLY cross-key atomic operation the kernel requires.
-	 */
-	promote(blockId: BlockId, actionId: ActionId): Promise<void>;
-
-	/** Optional — enumerate block ids with durable metadata (startup seed). Passed through by the kernel. */
-	listBlockIds?(): AsyncIterable<BlockId>;
-	/** Optional — best cheap byte estimate. Passed through by the kernel. */
-	approximateBytesUsed?(): Promise<number>;
-	/** Optional — release the underlying handle. */
-	close?(): Promise<void>;
-}
+import type { BlockId, ActionId } from "@optimystic/db-core";
+
+/**
+ * Bytes-valued, per-logical-store driver surface. Each backend implements the
+ * five block-storage stores (metadata, revisions, pending, transactions,
+ * materialized) over its native mechanism (LevelDB tag-ranges, five SQLite
+ * tables, five IndexedDB object stores, five filesystem subdirectories, five
+ * in-memory maps). `KvRawStorage` layers all JSON serialization and call
+ * orchestration on top — drivers never (de)serialize values and never see the
+ * `BlockMetadata`/`Transform`/`IBlock` types. Drivers speak only
+ * `Uint8Array`/`BlockId`/`ActionId`/`number`.
+ *
+ * ### Iteration semantics (drain-before-yield)
+ *
+ * `rangeRevisions` and `listPendingActionIds` return an `AsyncIterable`, but a
+ * driver MUST drain its native cursor/iterator into memory BEFORE yielding to
+ * the consumer. A live LevelDB iterator, IndexedDB transaction, or SQLite
+ * cursor must not straddle the consumer's `await`s: IndexedDB auto-commits an
+ * idle transaction, SQLite would hold its mutex slot, and LevelDB pins native
+ * resources. The kernel encodes this as a contract (not a shared implementation)
+ * because the drain is backend-specific. The conformance suite exercises it by
+ * interleaving other awaits between yielded items.
+ *
+ * ### Promote atomicity
+ *
+ * `promote` is the ONLY cross-key atomic operation the kernel requires. Every
+ * other write is a single put/delete. Each backend satisfies `promote` with its
+ * native atomic mechanism (LevelDB batch, SQLite transaction, IndexedDB
+ * readwrite transaction, filesystem rename); the kernel never assumes an
+ * atomicity a backend cannot deliver.
+ */
+export interface RawStoreDriver {
+	// metadata store — keyed by blockId
+	getMetadata(blockId: BlockId): Promise<Uint8Array | undefined>;
+	putMetadata(blockId: BlockId, value: Uint8Array): Promise<void>;
+
+	// revisions store — keyed by (blockId, rev), ORDERED BY rev
+	getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined>;
+	putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void>;
+	/**
+	 * Yield `[rev, value]` for every present rev in `[lo, hi]` (both inclusive),
+	 * ascending when `reverse` is false, descending when `reverse` is true. The
+	 * driver MUST drain any native cursor into memory before yielding — see the
+	 * "drain-before-yield" contract above.
+	 */
+	rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]>;
+
+	// pending store — keyed by (blockId, actionId)
+	getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+	putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+	deletePending(blockId: BlockId, actionId: ActionId): Promise<void>;
+	/** Yield each present pending actionId for the block. MUST drain before yielding (see above). */
+	listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId>;
+
+	// transactions store — keyed by (blockId, actionId)
+	getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+	putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+
+	// materialized store — keyed by (blockId, actionId)
+	getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+	putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+	deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void>;
+
+	/**
+	 * Atomically move `pending(blockId, actionId)` → `transactions(blockId, actionId)`:
+	 * write the transactions entry and remove the pending entry as one indivisible
+	 * step (batch / DB transaction / rename). A crash must leave exactly one of the
+	 * two states, never both/neither. Throw
+	 * `Pending action <actionId> not found for block <blockId>` when no pending
+	 * entry exists. This is the ONLY cross-key atomic operation the kernel requires.
+	 */
+	promote(blockId: BlockId, actionId: ActionId): Promise<void>;
+
+	/** Optional — enumerate block ids with durable metadata (startup seed). Passed through by the kernel. */
+	listBlockIds?(): AsyncIterable<BlockId>;
+	/** Optional — best cheap byte estimate. Passed through by the kernel. */
+	approximateBytesUsed?(): Promise<number>;
+	/** Optional — release the underlying handle. */
+	close?(): Promise<void>;
+}