@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/repo/types.ts

@@ -1,7 +1,7 @@
-export interface ClusterLogPeerOutcome {
-	peerId: string;
-	success: boolean;
-	/** Optional error message that explains why the peer failed. */
-	error?: string;
-}
-
+export interface ClusterLogPeerOutcome {
+	peerId: string;
+	success: boolean;
+	/** Optional error message that explains why the peer failed. */
+	error?: string;
+}
+

package/src/rn.ts

@@ -1,34 +1,39 @@
-export * from './cluster/client.js';
-export * from './cluster/cluster-repo.js';
-export * from './cluster/service.js';
-export * from './protocol-client.js';
-export * from './repo/client.js';
-export * from './repo/cluster-coordinator.js';
-export * from './repo/coordinator-repo.js';
-export * from './repo/service.js';
-export * from './storage/block-storage.js';
-export * from './storage/raw-store-driver.js';
-export * from './storage/kv-raw-storage.js';
-export * from './storage/memory-store-driver.js';
-export * from './storage/memory-storage.js';
-export * from './storage/i-block-storage.js';
-export * from './storage/i-raw-storage.js';
-export * from './storage/struct.js';
-export * from './storage/storage-repo.js';
-export * from './storage/restoration-coordinator.js';
-export * from './storage/ring-selector.js';
-export * from './storage/storage-monitor.js';
-export * from './storage/arachnode-fret-adapter.js';
-export * from './sync/protocol.js';
-export * from './sync/client.js';
-export * from './sync/service.js';
-export * from './it-utility.js';
-export * from './libp2p-key-network.js';
-export * from './libp2p-node-rn.js';
-export * from './routing/responsibility.js';
-export * from './routing/libp2p-known-peers.js';
-export * from './network/network-manager-service.js';
-export * from './network/get-network-manager.js';
-// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
-// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
-export * from './cohort-topic/peer-sig.js';
+export * from './cluster/client.js';
+export * from './cluster/cluster-policy.js';
+export * from './cluster/cluster-repo.js';
+export * from './cluster/service.js';
+export * from './protocol-client.js';
+export * from './repo/client.js';
+export * from './repo/cluster-coordinator.js';
+export * from './repo/coordinator-repo.js';
+export * from './repo/service.js';
+export * from './storage/block-storage.js';
+export * from './storage/raw-store-driver.js';
+export * from './storage/kv-raw-storage.js';
+export * from './storage/shared-cache-pool.js';
+export * from './storage/cached-store-driver.js';
+export * from './storage/cached-raw-storage.js';
+export * from './storage/memory-store-driver.js';
+export * from './storage/memory-storage.js';
+export * from './storage/i-block-storage.js';
+export * from './storage/i-raw-storage.js';
+export * from './storage/struct.js';
+export * from './storage/storage-repo.js';
+export * from './storage/restoration-coordinator.js';
+export * from './storage/ring-selector.js';
+export * from './storage/storage-monitor.js';
+export * from './storage/arachnode-fret-adapter.js';
+export * from './sync/protocol.js';
+export * from './sync/client.js';
+export * from './sync/service.js';
+export * from './it-utility.js';
+export * from './libp2p-key-network.js';
+export * from './libp2p-node-rn.js';
+export * from './optimystic-node.js';
+export * from './routing/responsibility.js';
+export * from './routing/libp2p-known-peers.js';
+export * from './network/network-manager-service.js';
+export * from './network/get-network-manager.js';
+// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
+// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
+export * from './cohort-topic/peer-sig.js';

package/src/rpc-deadline.ts

@@ -1,45 +1,45 @@
-/**
- * Per-RPC deadline knobs shared by the simple {@link ProtocolClient} subclasses
- * (cluster / sync / dispute). `dialTimeoutMs` bounds connecting; `responseTimeoutMs`
- * bounds waiting for the reply once connected (so a peer that connects then goes
- * silent throws {@link ResponseTimeoutError} instead of hanging the caller forever);
- * `signal` cancels the whole request. All optional.
- */
-export type RpcDeadlineOptions = {
-	signal?: AbortSignal;
-	dialTimeoutMs?: number;
-	responseTimeoutMs?: number;
-};
-
-/**
- * Default per-peer dial deadline. Matches `spread-on-churn.ts` `pushDialTimeoutMs`
- * (3000ms) — an unreachable peer fails the dial fast so the caller can re-pick a
- * different coordinator rather than blocking on a dead route.
- */
-export const DEFAULT_DIAL_TIMEOUT_MS = 3000;
-
-/**
- * Default per-peer response deadline. Matches `spread-on-churn.ts`
- * `pushResponseTimeoutMs` (10000ms) — a peer that connects then never writes a
- * reply is abandoned instead of hanging the caller forever.
- */
-export const DEFAULT_RESPONSE_TIMEOUT_MS = 10000;
-
-/**
- * Merge caller-supplied deadline options with the client-level defaults. An
- * explicitly-supplied value wins (including a deliberate `0`, which
- * {@link ProtocolClient.processMessage} reads as "no cap"); an absent key falls
- * back to the default so a caller that passes nothing still gets a deadline.
- * `signal` has no default — cancellation is always caller-driven.
- *
- * Unlike `BlockTransferClient` (which leaves its defaults to the owning
- * `SpreadOnChurnMonitor` config), these clients have many callers and no single
- * owning monitor, so the deadline default belongs here on the client.
- */
-export function withRpcDeadlineDefaults(options?: RpcDeadlineOptions): RpcDeadlineOptions {
-	return {
-		dialTimeoutMs: options?.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS,
-		responseTimeoutMs: options?.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
-		signal: options?.signal,
-	};
-}
+/**
+ * Per-RPC deadline knobs shared by the simple {@link ProtocolClient} subclasses
+ * (cluster / sync / dispute). `dialTimeoutMs` bounds connecting; `responseTimeoutMs`
+ * bounds waiting for the reply once connected (so a peer that connects then goes
+ * silent throws {@link ResponseTimeoutError} instead of hanging the caller forever);
+ * `signal` cancels the whole request. All optional.
+ */
+export type RpcDeadlineOptions = {
+	signal?: AbortSignal;
+	dialTimeoutMs?: number;
+	responseTimeoutMs?: number;
+};
+
+/**
+ * Default per-peer dial deadline. Matches `spread-on-churn.ts` `pushDialTimeoutMs`
+ * (3000ms) — an unreachable peer fails the dial fast so the caller can re-pick a
+ * different coordinator rather than blocking on a dead route.
+ */
+export const DEFAULT_DIAL_TIMEOUT_MS = 3000;
+
+/**
+ * Default per-peer response deadline. Matches `spread-on-churn.ts`
+ * `pushResponseTimeoutMs` (10000ms) — a peer that connects then never writes a
+ * reply is abandoned instead of hanging the caller forever.
+ */
+export const DEFAULT_RESPONSE_TIMEOUT_MS = 10000;
+
+/**
+ * Merge caller-supplied deadline options with the client-level defaults. An
+ * explicitly-supplied value wins (including a deliberate `0`, which
+ * {@link ProtocolClient.processMessage} reads as "no cap"); an absent key falls
+ * back to the default so a caller that passes nothing still gets a deadline.
+ * `signal` has no default — cancellation is always caller-driven.
+ *
+ * Unlike `BlockTransferClient` (which leaves its defaults to the owning
+ * `SpreadOnChurnMonitor` config), these clients have many callers and no single
+ * owning monitor, so the deadline default belongs here on the client.
+ */
+export function withRpcDeadlineDefaults(options?: RpcDeadlineOptions): RpcDeadlineOptions {
+	return {
+		dialTimeoutMs: options?.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS,
+		responseTimeoutMs: options?.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
+		signal: options?.signal,
+	};
+}

package/src/storage/arachnode-partition.ts

@@ -1,74 +1,74 @@
-import type { ArachnodeInfo } from './arachnode-fret-adapter.js';
-
-/**
- * An Arachnode ring partition: the first `prefixBits` bits of a hashed coordinate must equal
- * `prefixValue` for a key to fall inside it. Structurally identical to `ArachnodeInfo.partition`.
- */
-export interface RingPartition {
-	prefixBits: number;
-	prefixValue: number;
-}
-
-/**
- * Extract the first `bits` bits of a hashed coordinate as an integer (MSB-first).
- *
- * The single source of truth for the block/peer prefix comparison Arachnode uses to decide
- * responsibility. `RingSelector.calculatePartition` (peer side) and `RestorationCoordinator`
- * (block side) both route through this, so a peer's advertised partition and a block's derived
- * prefix are computed the same way — otherwise "this peer owns this block's slice" would silently
- * stop meaning what it says.
- */
-export function extractPrefix(coord: Uint8Array, bits: number): number {
-	let value = 0;
-	for (let i = 0; i < bits; i++) {
-		const byteIndex = Math.floor(i / 8);
-		const bitIndex = 7 - (i % 8);
-		const bit = (coord[byteIndex]! >> bitIndex) & 1;
-		value = (value << 1) | bit;
-	}
-	return value;
-}
-
-/**
- * Does `partition` cover the key at `coord`? Ring 0 (an undefined partition) covers the whole
- * keyspace, so it always returns true.
- */
-export function partitionCovers(partition: RingPartition | undefined, coord: Uint8Array): boolean {
-	if (!partition) {
-		return true;
-	}
-	return extractPrefix(coord, partition.prefixBits) === partition.prefixValue;
-}
-
-/**
- * Is the node described by `info` a currently-serving responsible holder for the key at `coord`?
- *
- * **Fail-toward-old-holder.** A node mid-move (`status === 'moving'`) advertises its *target*
- * `partition`, but it keeps serving its *old* range (`moveFrom`) until it releases. So a moving
- * node covers the key if EITHER its old range or its target range covers it — it is still counted
- * as a serving holder for everything it served before the move until it transitions to `active` at
- * the new ring. This is what keeps a shed key covered through Phases A–B and across a mid-handoff
- * crash. See `docs/arachnode-ring-handoff.md` § Part 3.
- */
-export function isServingHolder(info: ArachnodeInfo, coord: Uint8Array): boolean {
-	if (info.status === 'moving' && info.moveFrom) {
-		return partitionCovers(info.moveFrom.partition, coord) || partitionCovers(info.partition, coord);
-	}
-	return partitionCovers(info.partition, coord);
-}
-
-/**
- * Does the node described by `info` qualify toward *another* mover's Phase-B replication floor for
- * the key at `coord`?
- *
- * A qualifying holder must still cover the key **after its own advertised move** — i.e. its
- * *target* `partition` (the one it currently advertises) must cover it. A concurrent mover that is
- * shedding the same sub-range advertises a target that does NOT cover the key, so it is excluded:
- * two adjacent movers can never both count the other, so at most one reaches "confirmed" on the
- * shared overlap and the other rolls back. For a non-moving (`active`) node, the advertised
- * partition IS its serving range, so this reduces to plain partition coverage. See
- * `docs/arachnode-ring-handoff.md` § Part 3 (concurrent moves).
- */
-export function qualifiesForFloor(info: ArachnodeInfo, coord: Uint8Array): boolean {
-	return partitionCovers(info.partition, coord);
-}
+import type { ArachnodeInfo } from './arachnode-fret-adapter.js';
+
+/**
+ * An Arachnode ring partition: the first `prefixBits` bits of a hashed coordinate must equal
+ * `prefixValue` for a key to fall inside it. Structurally identical to `ArachnodeInfo.partition`.
+ */
+export interface RingPartition {
+	prefixBits: number;
+	prefixValue: number;
+}
+
+/**
+ * Extract the first `bits` bits of a hashed coordinate as an integer (MSB-first).
+ *
+ * The single source of truth for the block/peer prefix comparison Arachnode uses to decide
+ * responsibility. `RingSelector.calculatePartition` (peer side) and `RestorationCoordinator`
+ * (block side) both route through this, so a peer's advertised partition and a block's derived
+ * prefix are computed the same way — otherwise "this peer owns this block's slice" would silently
+ * stop meaning what it says.
+ */
+export function extractPrefix(coord: Uint8Array, bits: number): number {
+	let value = 0;
+	for (let i = 0; i < bits; i++) {
+		const byteIndex = Math.floor(i / 8);
+		const bitIndex = 7 - (i % 8);
+		const bit = (coord[byteIndex]! >> bitIndex) & 1;
+		value = (value << 1) | bit;
+	}
+	return value;
+}
+
+/**
+ * Does `partition` cover the key at `coord`? Ring 0 (an undefined partition) covers the whole
+ * keyspace, so it always returns true.
+ */
+export function partitionCovers(partition: RingPartition | undefined, coord: Uint8Array): boolean {
+	if (!partition) {
+		return true;
+	}
+	return extractPrefix(coord, partition.prefixBits) === partition.prefixValue;
+}
+
+/**
+ * Is the node described by `info` a currently-serving responsible holder for the key at `coord`?
+ *
+ * **Fail-toward-old-holder.** A node mid-move (`status === 'moving'`) advertises its *target*
+ * `partition`, but it keeps serving its *old* range (`moveFrom`) until it releases. So a moving
+ * node covers the key if EITHER its old range or its target range covers it — it is still counted
+ * as a serving holder for everything it served before the move until it transitions to `active` at
+ * the new ring. This is what keeps a shed key covered through Phases A–B and across a mid-handoff
+ * crash. See `docs/arachnode-ring-handoff.md` § Part 3.
+ */
+export function isServingHolder(info: ArachnodeInfo, coord: Uint8Array): boolean {
+	if (info.status === 'moving' && info.moveFrom) {
+		return partitionCovers(info.moveFrom.partition, coord) || partitionCovers(info.partition, coord);
+	}
+	return partitionCovers(info.partition, coord);
+}
+
+/**
+ * Does the node described by `info` qualify toward *another* mover's Phase-B replication floor for
+ * the key at `coord`?
+ *
+ * A qualifying holder must still cover the key **after its own advertised move** — i.e. its
+ * *target* `partition` (the one it currently advertises) must cover it. A concurrent mover that is
+ * shedding the same sub-range advertises a target that does NOT cover the key, so it is excluded:
+ * two adjacent movers can never both count the other, so at most one reaches "confirmed" on the
+ * shared overlap and the other rolls back. For a non-moving (`active`) node, the advertised
+ * partition IS its serving range, so this reduces to plain partition coverage. See
+ * `docs/arachnode-ring-handoff.md` § Part 3 (concurrent moves).
+ */
+export function qualifiesForFloor(info: ArachnodeInfo, coord: Uint8Array): boolean {
+	return partitionCovers(info.partition, coord);
+}

package/src/storage/block-storage.ts

@@ -50,14 +50,44 @@ export class BlockStorage implements IBlockStorage {
 			return undefined;
 		}
 
-		// Pending-only state: metadata was seeded by savePendingTransaction but no
-		// revision has been committed yet. Treat as "doesn't exist" for the default
-		// request path — matches StorageRepo.get()'s contract that undefined => empty.
-		if (rev === undefined && meta.latest === undefined) {
-			return undefined;
+		// Pending-only state: metadata was seeded by savePendingTransaction but no revision has been
+		// committed yet. "No committed base here" is an ABSENCE, not a fault — nothing is being
+		// FAILED to reconstruct — so both arms below answer `undefined` rather than throwing, whether
+		// or not the caller named a revision. StorageRepo.get then applies any pending overlay over
+		// that absent base; a throw here would instead be caught into `unavailable: 'unmaterializable'`
+		// and a writer reading back its own not-yet-committed insert would be told it is unreadable.
+		// `unmaterializable` must keep its one meaning: records prove the block exists and this node
+		// cannot reconstruct it.
+		if (meta.latest === undefined) {
+			if (rev === undefined) {
+				return undefined;
+			}
+			// A named rev still ATTEMPTS the restore: `restoreCallback` may be able to supply that
+			// revision even though nothing is committed locally, and a successful restore serves real
+			// content with `latest` still undefined. That capability is pinned by the 'getBlock for an
+			// absent revision fires restoreCallback (restore not short-circuited)' test in
+			// test/block-storage.spec.ts — do not short-circuit it away.
+			//
+			// Only ensureRevision's FAILURE is swallowed (no callback wired, or restore could not
+			// supply the rev): that is precisely the "no committed base here" absence. materializeBlock
+			// below is deliberately OUTSIDE the try — a throw from there means revision records exist
+			// with no materialization anywhere under them, which is genuine corruption and must keep
+			// reading as `unmaterializable`.
+			//
+			// NOTE: a contextful read of a pending-only block still attempts a network restore before
+			// falling back to absent (same cost as the pre-fix throw path); if pending-only read-backs
+			// ever show as hot, short-circuit when ranges are empty.
+			try {
+				await this.ensureRevision(meta, rev);
+			} catch (err) {
+				log('getBlock:no-committed-base blockId=%s rev=%d error=%s', this.blockId, rev,
+					err instanceof Error ? err.message : String(err));
+				return undefined;
+			}
+			return await this.materializeBlock(meta, rev);
 		}
 
-		const targetRev = rev ?? meta.latest!.rev;
+		const targetRev = rev ?? meta.latest.rev;
 		await this.ensureRevision(meta, targetRev);
 		return await this.materializeBlock(meta, targetRev);
 	}
@@ -271,6 +301,29 @@ export class BlockStorage implements IBlockStorage {
 			};
 			await this.saveRestored(archive);
 
+			// INVARIANT P: a block never holds a pending record AND a committed record for the same
+			// action id. On the commit path `promotePendingTransaction` maintains it by MOVING the
+			// record atomically; this forward path writes the committed transform directly (via
+			// saveRestored above), so it owes the deletion itself. Without it, a node that pended the
+			// action but diverged before committing keeps a record nothing can ever promote — reported
+			// as a phantom conflicting action by every later `pend` on the block, which under
+			// `policy: 'f'` refuses that node's participation in the block's writes permanently.
+			//
+			// Deliberately on the WRITE path only: the monotonic guard above returns before here, and
+			// that early return must stay a true no-op (the earlier call that wrote the revision is the
+			// one that owed the deletion). Deliberately here rather than in `saveRestored`, which is
+			// also reached from ensureRevision's historical restore under a different latch, where a
+			// deletion could race a concurrent promotePendingTransaction; this path holds
+			// `BlockStorage.saveReplica:<id>` and (via StorageRepo.saveReplicatedBlock) the per-block
+			// commit latch, so it is already mutually exclusive with a live commit.
+			//
+			// NOTE: deletes only this revision's actionId, not every pending whose action is already
+			// committed. A broader sweep would repair records orphaned by routes that do not carry the
+			// committing actionId; if orphaned pendings ever show up in the field on blocks whose
+			// committing action id differs, widen to a sweep over listPendingTransactions filtered by
+			// getTransaction.
+			await this.storage.deletePendingTransaction(this.blockId, actionId);
+
 			// Seed metadata when absent, advance latest, and merge the covered range.
 			const prevRev = meta?.latest?.rev;
 			if (!meta) {

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

@@ -0,0 +1,180 @@
+import type { BlockId, ActionId } from "@optimystic/db-core";
+import type { IRawStorage } from "./i-raw-storage.js";
+import type { RawStoreDriver } from "./raw-store-driver.js";
+import { KvRawStorage } from "./kv-raw-storage.js";
+import { CachedStoreDriver } from "./cached-store-driver.js";
+import type { SharedCachePool } from "./shared-cache-pool.js";
+import { encodeJson, decodeJson, encodeActionId, decodeActionId } from "./raw-store-codec.js";
+
+/**
+ * Presents a plain {@link IRawStorage} as a {@link RawStoreDriver}, so the
+ * {@link CachedStoreDriver} (and the `KvRawStorage` kernel above it) can wrap a backend
+ * that does NOT expose its driver — the composition {@link CachedRawStorage} uses.
+ *
+ * Every value crossing this adapter is re-encoded to bytes on read and re-decoded on
+ * write, on top of whatever (de)serialization the inner storage does itself. For a
+ * kernel-backed inner storage that is a double codec pass per COLD miss — cache hits
+ * never reach this adapter. Wrapping the backend's `RawStoreDriver` directly with
+ * `CachedStoreDriver` avoids the double pass entirely; prefer that when the driver is
+ * reachable, and this adapter when only the `IRawStorage` surface is.
+ */
+export class RawStorageDriverAdapter implements RawStoreDriver {
+	/**
+	 * Optional passthroughs wired only when the inner storage provides them, mirroring
+	 * `KvRawStorage`'s constructor: feature-detection above must observe the inner
+	 * storage's true capability. `IRawStorage` has no `close`/`approximateBytesUsed`
+	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`.
+	 */
+	listBlockIds?: () => AsyncIterable<BlockId>;
+	approximateBytesUsed?: () => Promise<number>;
+
+	constructor(private readonly inner: IRawStorage) {
+		if (inner.listBlockIds) {
+			this.listBlockIds = () => inner.listBlockIds!();
+		}
+		if (inner.getApproximateBytesUsed) {
+			this.approximateBytesUsed = () => inner.getApproximateBytesUsed!();
+		}
+	}
+
+	// --- metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
+		const meta = await this.inner.getMetadata(blockId);
+		return meta === undefined ? undefined : encodeJson(meta);
+	}
+
+	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
+		await this.inner.saveMetadata(blockId, decodeJson(value));
+	}
+
+	// --- revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		const actionId = await this.inner.getRevision(blockId, rev);
+		return actionId === undefined ? undefined : encodeActionId(actionId);
+	}
+
+	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		await this.inner.saveRevision(blockId, rev, decodeActionId(value));
+	}
+
+	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+		// `listRevisions` derives direction from bound order (start > end ⇒ descending);
+		// map (lo, hi, reverse) back onto that. Drain before yielding — the inner
+		// iterable already drained per its own contract, but the consumer's awaits must
+		// not straddle OUR loop over it either.
+		const startRev = reverse ? hi : lo;
+		const endRev = reverse ? lo : hi;
+		const drained: [number, Uint8Array][] = [];
+		for await (const { rev, actionId } of this.inner.listRevisions(blockId, startRev, endRev)) {
+			drained.push([rev, encodeActionId(actionId)]);
+		}
+		yield* drained;
+	}
+
+	// --- pending ---
+
+	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const transform = await this.inner.getPendingTransaction(blockId, actionId);
+		return transform === undefined ? undefined : encodeJson(transform);
+	}
+
+	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.savePendingTransaction(blockId, actionId, decodeJson(value));
+	}
+
+	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.deletePendingTransaction(blockId, actionId);
+	}
+
+	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
+		const drained: ActionId[] = [];
+		for await (const id of this.inner.listPendingTransactions(blockId)) {
+			drained.push(id);
+		}
+		yield* drained;
+	}
+
+	// --- transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const transform = await this.inner.getTransaction(blockId, actionId);
+		return transform === undefined ? undefined : encodeJson(transform);
+	}
+
+	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.saveTransaction(blockId, actionId, decodeJson(value));
+	}
+
+	// --- materialized ---
+
+	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const block = await this.inner.getMaterializedBlock(blockId, actionId);
+		return block === undefined ? undefined : encodeJson(block);
+	}
+
+	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.saveMaterializedBlock(blockId, actionId, decodeJson(value));
+	}
+
+	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.saveMaterializedBlock(blockId, actionId, undefined);
+	}
+
+	// --- promote ---
+
+	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.promotePendingTransaction(blockId, actionId);
+	}
+}
+
+/**
+ * Write-through cached view over a plain {@link IRawStorage} — the wrapper form for a
+ * backend whose {@link RawStoreDriver} is not reachable. Composition:
+ *
+ * ```
+ * KvRawStorage kernel → CachedStoreDriver → RawStorageDriverAdapter → inner IRawStorage
+ * ```
+ *
+ * All caching semantics (write-through coherence, proven-absence negatives, list
+ * completeness, promote mirroring) live in {@link CachedStoreDriver}; see its class doc
+ * and docs/storage.md "Write-through raw-storage cache" for the invariants this relies
+ * on — including the single-process-owner precondition.
+ *
+ * Prefer wrapping the backend's driver directly — `new KvRawStorage(new
+ * CachedStoreDriver(driver))` — when the driver is available: it skips this adapter's
+ * extra codec pass on cold misses. Do not wrap `MemoryRawStorage` in production wiring
+ * (already in-memory; the cache adds bookkeeping with nothing to save) — tests do, to
+ * prove semantics are identical through the full composition.
+ *
+ * By default the cache joins the process-wide shared pool (`defaultCachePool()`), so
+ * every workspace's cache competes inside ONE memory budget; pass a specific
+ * {@link SharedCachePool} only for isolation (tests) or host-specific sizing, and a
+ * `label` to make this store recognizable in the pool's `stats()`.
+ */
+export class CachedRawStorage extends KvRawStorage {
+	private readonly cacheDriver: CachedStoreDriver;
+
+	constructor(inner: IRawStorage, pool?: SharedCachePool, label?: string) {
+		const cacheDriver = new CachedStoreDriver(new RawStorageDriverAdapter(inner), pool, label);
+		super(cacheDriver);
+		this.cacheDriver = cacheDriver;
+	}
+
+	/** Drop every cached entry. Always safe — the cache is clean (write-through, never write-behind). */
+	clearCache(): void {
+		this.cacheDriver.clear();
+	}
+
+	/**
+	 * Release this storage's cache registration with the shared pool (drops all entries,
+	 * retires the store id). Call when the workspace departs; a skipped dispose leaks only
+	 * cold entries the pool will evict under pressure, but the polite release keeps a
+	 * long-lived process's occupancy honest. `IRawStorage` itself has no close, so this is
+	 * the wrapper's own lifecycle method.
+	 */
+	async dispose(): Promise<void> {
+		await this.cacheDriver.close();
+	}
+}