@optimystic/db-p2p 0.24.2 → 0.25.0

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

@@ -1,116 +1,172 @@
-import type { IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
-
-/** Interface for block-level storage operations */
-export interface IBlockStorage {
-    /** Gets the latest revision information for this block */
-    getLatest(): Promise<ActionRev | undefined>;
-
-    /**
-     * Gets a materialized block at the given revision.
-     * Returns undefined when the block has no materialized content yet — either
-     * no metadata exists, or metadata exists (seeded by a pending transaction)
-     * but no revision has been committed. Throws only when a specific `rev` was
-     * requested but cannot be located.
-     */
-    getBlock(rev?: number): Promise<{ block: IBlock, actionRev: ActionRev } | undefined>;
-
-    /** Gets an action by ID */
-    getTransaction(actionId: ActionId): Promise<Transform | undefined>;
-
-    /** Gets a pending action by ID */
-    getPendingTransaction(actionId: ActionId): Promise<Transform | undefined>;
-
-    /** Lists all pending action IDs */
-    listPendingTransactions(): AsyncIterable<ActionId>;
-
-    /** Saves a pending action */
-    savePendingTransaction(actionId: ActionId, transform: Transform): Promise<void>;
-
-    /** Deletes a pending action */
-    deletePendingTransaction(actionId: ActionId): Promise<void>;
-
-    /** Lists revisions in ascending or descending order between startRev and endRev (inclusive) */
-    listRevisions(startRev: number, endRev: number): AsyncIterable<ActionRev>;
-
-    /** 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>;
-
-    /**
-     * Promotes a pending action to committed, MOVING the record from the pending namespace to the
-     * committed one in a single atomic step.
-     *
-     * **Invariant P** — a block never holds a pending record and a committed record for the same
-     * action id at the same time. This method maintains it on the commit path; every OTHER writer of
-     * a committed transform for a block ({@link saveReplica}, {@link saveDeletion}, and any forward
-     * path added later) must maintain it too, by deleting that action's pending record when it
-     * writes the committed one. A pending record left beside a committed one can never be promoted,
-     * and is reported as a phantom conflicting action by `StorageRepo.pend` on every later write to
-     * the block.
-     */
-    promotePendingTransaction(actionId: ActionId): Promise<void>;
-
-    /** Sets the latest revision information */
-    setLatest(latest: ActionRev): Promise<void>;
-
-    /**
-     * Persist a replica of a block received out-of-band (churn re-replication).
-     *
-     * Seeds metadata if absent, writes `rev → actionId`, the action transform, and the
-     * materialized block, merges `[rev, rev+1]` into `ranges`, and advances `latest`
-     * monotonically. When `source` is provided its `rev`/`actionId` are used; otherwise
-     * it falls back to `rev = 1` and a deterministic `actionId` derived from the block
-     * (so retries stay idempotent — never random).
-     *
-     * Maintains **Invariant P** (see {@link promotePendingTransaction}): writing the committed
-     * transform for `actionId` also deletes that action's pending record on this block, so a node
-     * that pended the action but diverged before committing it does not keep an unpromotable record.
-     * Only on the write path — the monotonic no-op below deletes nothing.
-     *
-     * No-op (still durable) when an equal-or-newer revision is already present: `latest`
-     * is never downgraded. Idempotent for a fixed `(rev, actionId)`. Returns the
-     * effective latest `ActionRev`.
-     */
-    saveReplica(block: IBlock, source?: ActionRev): Promise<ActionRev>;
-
-    /**
-     * Writes a forward TOMBSTONE revision that reverses a block creation: persists `rev → actionId`,
-     * a `{ delete: true }` transform, and NO materialized block, then merges `[rev, rev+1]` into
-     * `ranges` and advances `latest` monotonically. The reverse-apply path treats the absent
-     * materialization as a deletion, so a `getBlock()` after a tombstone reads back as *absent*
-     * (`undefined`) while a historical `getBlock(creationRev)` still materializes the created content.
-     *
-     * Maintains **Invariant P** (see {@link promotePendingTransaction}) on the write path, exactly as
-     * {@link saveReplica} does: the tombstone's `actionId` loses its pending record on this block.
-     *
-     * Idempotent for a fixed `(rev, actionId)`; never downgrades `latest` (a no-op — still durable —
-     * when an equal-or-newer revision is already present). Returns the effective latest `ActionRev`.
-     */
-    saveDeletion(source: ActionRev): Promise<ActionRev>;
-
-    /**
-     * Reconciles `metadata.latest` with the highest contiguous fully-promoted revision in
-     * the revisions table. Intended for post-crash recovery of the Crash-D3 gap, where
-     * `promotePendingTransaction` succeeded but `setLatest` did not: the revision and
-     * committed-log entry are durable, but `meta.latest` still points at the prior rev
-     * (or is undefined), and retry-commit is rejected because the pending record is gone.
-     *
-     * Stops at the first rev whose action is not yet in the committed log, preserving the
-     * Crash-D2 invariant that retry-commit — not recovery — owns advancement past a half-
-     * promoted state.
-     *
-     * Idempotent and monotonic (latest only advances forward).
-     */
-    recover(): Promise<{ reconciled: boolean; latest?: ActionRev }>;
-}
+import type { BlockId, IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
+import type { BlockCommitProof } from "../cluster/commit-proof.js";
+import type { BlockWriteLatch } from "./block-latch.js";
+
+/**
+ * Thrown by {@link IBlockStorage.getBlock} when the block has metadata here but the target revision
+ * lies outside the locally held revision ranges — this node holds no local records that can serve
+ * it. Not a fault: it is the signal a caller that is allowed to heal (only `StorageRepo.get`, under
+ * the block's write latch) turns into a {@link IBlockStorage.restoreRevision}; every other caller
+ * treats it like any other unreadable-base condition.
+ *
+ * It lives beside the interface rather than beside `BlockStorage` because it is part of the
+ * `getBlock` contract: an alternate `IBlockStorage` implementation must be able to throw it, and
+ * `StorageRepo` must be able to catch it, without either depending on the concrete implementation.
+ */
+export class RevisionNotCoveredError extends Error {
+	constructor(readonly blockId: BlockId, readonly rev: number) {
+		super(`Block ${blockId} revision ${rev} is not covered by local records`);
+		this.name = 'RevisionNotCoveredError';
+	}
+}
+
+/**
+ * Interface for block-level storage operations.
+ *
+ * **One block, one write lock.** Every method that writes — metadata, revision records, action
+ * transforms, pending records, materializations, proofs — takes a {@link BlockWriteLatch} token as
+ * its LAST parameter. The token is proof the caller holds this block's write latch
+ * (`blockWriteLatchKey(blockId)`, see `block-latch.ts`), which is the only thing that keeps two
+ * writers' read-modify-writes of the metadata blob from silently undoing each other. Only
+ * `acquireBlockWriteLatch` / `withBlockWriteLatch` can mint a token, and an implementation must
+ * reject a token minted for a different block.
+ */
+export interface IBlockStorage {
+    /** Gets the latest revision information for this block */
+    getLatest(): Promise<ActionRev | undefined>;
+
+    /**
+     * Gets a materialized block at the given revision, from LOCAL records only — this never fetches
+     * from a peer. Returns `undefined` when this node has never seen the block (no metadata) or when
+     * it is pending-only (metadata seeded by a pending transaction, nothing committed) and no `rev`
+     * was named. Throws {@link RevisionNotCoveredError} when the target revision (`rev`, or `latest.rev`)
+     * lies outside `meta.ranges` — the caller decides whether to heal that gap with
+     * {@link restoreRevision} under the block's write latch (`StorageRepo.get` does; the commit path
+     * deliberately does not). Throws a plain `Error` when the revision is covered but cannot be
+     * materialized from the records held (truncated history — genuine corruption).
+     */
+    getBlock(rev?: number): Promise<{ block: IBlock, actionRev: ActionRev } | undefined>;
+
+    /**
+     * Fill a gap in local revision history by fetching `rev` from a peer (the restore wire) and
+     * recording the vetted coverage. No-op when `rev` is already covered. Throws when the block has
+     * no metadata here (a never-seen block is not restored at this layer — see the note in
+     * `BlockStorage.getBlock`) or when no peer could supply an acceptable archive.
+     */
+    restoreRevision(rev: number, latch: BlockWriteLatch): Promise<void>;
+
+    /** Gets an action by ID */
+    getTransaction(actionId: ActionId): Promise<Transform | undefined>;
+
+    /** The commit proof stored for a revision, if one was retained (see IRawStorage.getBlockProof). */
+    getBlockProof(rev: number): Promise<BlockCommitProof | undefined>;
+
+    /** Persists the commit proof for a revision (see IRawStorage.saveBlockProof). */
+    saveBlockProof(rev: number, proof: BlockCommitProof, latch: BlockWriteLatch): Promise<void>;
+
+    /** Gets a pending action by ID */
+    getPendingTransaction(actionId: ActionId): Promise<Transform | undefined>;
+
+    /** Lists all pending action IDs */
+    listPendingTransactions(): AsyncIterable<ActionId>;
+
+    /** Saves a pending action (seeding this block's metadata when it has none). */
+    savePendingTransaction(actionId: ActionId, transform: Transform, latch: BlockWriteLatch): Promise<void>;
+
+    /** Deletes a pending action */
+    deletePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
+
+    /** Lists revisions in ascending or descending order between startRev and endRev (inclusive) */
+    listRevisions(startRev: number, endRev: number): AsyncIterable<ActionRev>;
+
+    /** Saves a materialized block */
+    saveMaterializedBlock(actionId: ActionId, block: IBlock | undefined, latch: BlockWriteLatch): 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).
+     */
+    pruneSupersededMaterialization(prior: ActionRev, latch: BlockWriteLatch): Promise<void>;
+
+    /** Saves a revision */
+    saveRevision(rev: number, actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
+
+    /**
+     * Promotes a pending action to committed, MOVING the record from the pending namespace to the
+     * committed one in a single atomic step.
+     *
+     * **Invariant P** — a block never holds a pending record and a committed record for the same
+     * action id at the same time. This method maintains it on the commit path; every OTHER writer of
+     * a committed transform for a block ({@link saveReplica}, {@link saveDeletion}, and any forward
+     * path added later) must maintain it too, by deleting that action's pending record when it
+     * writes the committed one. A pending record left beside a committed one can never be promoted,
+     * and is reported as a phantom conflicting action by `StorageRepo.pend` on every later write to
+     * the block.
+     */
+    promotePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
+
+    /** Sets the latest revision information */
+    setLatest(latest: ActionRev, latch: BlockWriteLatch): Promise<void>;
+
+    /**
+     * Persist a replica of a block received out-of-band (churn re-replication).
+     *
+     * Seeds metadata if absent, writes `rev → actionId`, the action transform, and the
+     * materialized block, merges `[rev, rev+1]` into `ranges`, and advances `latest`
+     * monotonically. When `source` is provided its `rev`/`actionId` are used; otherwise
+     * it falls back to `rev = 1` and a deterministic `actionId` derived from the block
+     * (so retries stay idempotent — never random).
+     *
+     * Maintains **Invariant P** (see {@link promotePendingTransaction}): writing the committed
+     * transform for `actionId` also deletes that action's pending record on this block, so a node
+     * that pended the action but diverged before committing it does not keep an unpromotable record.
+     * Only on the write path — the monotonic no-op below deletes nothing.
+     *
+     * No-op (still durable) when an equal-or-newer revision is already present: `latest`
+     * is never downgraded. Idempotent for a fixed `(rev, actionId)`. Returns the
+     * effective latest `ActionRev`.
+     *
+     * `proof` is persisted for `source.rev` and MUST already be verified by the caller against
+     * these exact bytes (`verifyBlockCommitProofContent` — the digest check is what binds a proof
+     * to the block content). An unverified proof passed here would be re-served onward as evidence
+     * this node never checked. The monotonic no-op persists nothing, proof included — a proof for an
+     * already-held revision is back-filled one layer up, by `StorageRepo.saveReplicatedBlock`, which
+     * first checks the declared digest against LOCAL content (these bytes may not be the held bytes).
+     *
+     * `source` and `proof` are positional-but-optional (pass `undefined` when absent) so the latch
+     * token can stay in the last position like every other writer.
+     */
+    saveReplica(block: IBlock, source: ActionRev | undefined, proof: BlockCommitProof | undefined, latch: BlockWriteLatch): Promise<ActionRev>;
+
+    /**
+     * Writes a forward TOMBSTONE revision that reverses a block creation: persists `rev → actionId`,
+     * a `{ delete: true }` transform, and NO materialized block, then merges `[rev, rev+1]` into
+     * `ranges` and advances `latest` monotonically. The reverse-apply path treats the absent
+     * materialization as a deletion, so a `getBlock()` after a tombstone reads back as *absent*
+     * (`undefined`) while a historical `getBlock(creationRev)` still materializes the created content.
+     *
+     * Maintains **Invariant P** (see {@link promotePendingTransaction}) on the write path, exactly as
+     * {@link saveReplica} does: the tombstone's `actionId` loses its pending record on this block.
+     *
+     * Idempotent for a fixed `(rev, actionId)`; never downgrades `latest` (a no-op — still durable —
+     * when an equal-or-newer revision is already present). Returns the effective latest `ActionRev`.
+     */
+    saveDeletion(source: ActionRev, latch: BlockWriteLatch): Promise<ActionRev>;
+
+    /**
+     * Reconciles `metadata.latest` with the highest contiguous fully-promoted revision in
+     * the revisions table. Intended for post-crash recovery of the Crash-D3 gap, where
+     * `promotePendingTransaction` succeeded but `setLatest` did not: the revision and
+     * committed-log entry are durable, but `meta.latest` still points at the prior rev
+     * (or is undefined), and retry-commit is rejected because the pending record is gone.
+     *
+     * Stops at the first rev whose action is not yet in the committed log, preserving the
+     * Crash-D2 invariant that retry-commit — not recovery — owns advancement past a half-
+     * promoted state.
+     *
+     * Idempotent and monotonic (latest only advances forward).
+     */
+    recover(latch: BlockWriteLatch): Promise<{ reconciled: boolean; latest?: ActionRev }>;
+}

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

@@ -1,5 +1,7 @@
 import type { BlockId, ActionId, ActionRev, Transform, IBlock } from "@optimystic/db-core";
+import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockMetadata } from "./struct.js";
+import type { StoreIdentity } from "./store-identity.js";
 
 export interface IRawStorage {
 	// Metadata operations
@@ -21,6 +23,17 @@ export interface IRawStorage {
 	getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined>;
 	saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void>;
 
+	/**
+	 * The commit proof stored for a revision, if one was retained. Keyed by revision: the proof lives
+	 * and dies with the REVISION record, not the materialization, so the checkpoint sweep
+	 * (`pruneSupersededMaterialization`) never touches it — that is what lets it outlive the
+	 * 60-second in-memory commit-cert TTL. Whatever deletes a revision record must delete its proof;
+	 * no such site exists today (`RawStoreDriver` has no revision delete at all — invalidations write
+	 * compensating FORWARD revisions), so this is a contract note, not a wired path.
+	 */
+	getBlockProof(blockId: BlockId, rev: number): Promise<BlockCommitProof | undefined>;
+	saveBlockProof(blockId: BlockId, rev: number, proof: BlockCommitProof): Promise<void>;
+
 	// Block materialization operations
 	getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined>;
 	saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void>;
@@ -28,6 +41,33 @@ export interface IRawStorage {
 	// Promote a pending action to a committed action
 	promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void>;
 
+	/**
+	 * A stable, process-scoped string naming what this storage is ultimately backed by (a
+	 * resolved directory, an open database handle). Wrappers pass it through from whatever they
+	 * wrap, so a cache and the storage it fronts name the same store — e.g.
+	 * `new CachedRawStorage(new FileRawStorage(dir)).getStoreIdentity()` is `'file:<resolved dir>'`.
+	 *
+	 * Contract — note it is ONE-DIRECTIONAL; read both halves before consuming it:
+	 * - Two storages over DIFFERENT locations MUST NOT return equal strings. So **equality
+	 *   proves sameness**, and a consumer may merge on it. (The fs backend documents one exotic
+	 *   Windows exception at its own site.)
+	 * - Two storages over the SAME location SHOULD return equal strings, but this is
+	 *   best-effort and several backends knowingly under-approximate: two handles opened over
+	 *   one database, or two spellings of one directory that cannot be collapsed synchronously,
+	 *   read as two identities. So **inequality proves nothing** — never treat it as evidence
+	 *   that two storages are distinct stores. Each backend's `NOTE:` states its own gaps.
+	 * - Every string is scheme-prefixed so backends cannot collide: `file:`, `sqlite-handle:`,
+	 *   `idb-handle:`, `leveldb-handle:`. Compared for equality only — never parsed.
+	 * - Stable for the storage object's whole life; fixed at construction.
+	 * - OPTIONAL BY DESIGN. A backend that cannot honour the contract omits the method entirely
+	 *   and callers fall back to per-object behavior. Never install a stub that returns
+	 *   `undefined` — feature-detection (`typeof storage.getStoreIdentity === 'function'`) must
+	 *   see the backend's true capability, the same trap `KvRawStorage`'s class doc calls out
+	 *   for `listBlockIds`.
+	 * - It identifies the STORE, not its contents.
+	 */
+	getStoreIdentity?(): StoreIdentity;
+
 	/**
 	 * Approximate bytes currently stored by this backend.
 	 *

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

@@ -1,34 +1,41 @@
 import type { BlockId, ActionId, ActionRev, Transform, IBlock } from "@optimystic/db-core";
+import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockMetadata } from "./struct.js";
 import type { IRawStorage } from "./i-raw-storage.js";
 import type { RawStoreDriver } from "./raw-store-driver.js";
+import type { StoreIdentity } from "./store-identity.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
+ * call orchestration so each backend only has to expose its six 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.
+ * codec for the 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 six relational
+ * tables, IndexedDB six 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.
+	 * capability instead of a stub that silently reports 0 / no seed. The same rule
+	 * governs `getStoreIdentity`: a stub returning `undefined` would make every store
+	 * look identity-less to consumers that dedupe on it.
 	 */
 	listBlockIds?: () => AsyncIterable<BlockId>;
 	getApproximateBytesUsed?: () => Promise<number>;
+	getStoreIdentity?: () => StoreIdentity;
 
 	constructor(private readonly driver: RawStoreDriver) {
+		if (driver.storeIdentity) {
+			this.getStoreIdentity = () => driver.storeIdentity!();
+		}
 		if (driver.listBlockIds) {
 			this.listBlockIds = () => driver.listBlockIds!();
 		}
@@ -46,7 +53,7 @@ export class KvRawStorage implements IRawStorage {
 
 	// 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
+	// saveBlockProof / 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
@@ -111,6 +118,24 @@ export class KvRawStorage implements IRawStorage {
 		await this.driver.putTransaction(blockId, actionId, encodeJson(transform));
 	}
 
+	// --- Commit proofs (their OWN (blockId, rev)-keyed store — see RawStoreDriver.getProof) ---
+	//
+	// Proofs deliberately do NOT share the transactions keyspace. Action ids are
+	// chosen by whoever originates a write and are never re-derived or format-checked
+	// by the storing node, so no reserved action-id prefix can be relied on: a client
+	// pending an action literally named `~proof:5`, or a peer's restore archive naming
+	// one, used to land on the same key as revision 5's proof and silently overwrite it
+	// (or be overwritten by it). Separate stores make that collision unrepresentable.
+
+	async getBlockProof(blockId: BlockId, rev: number): Promise<BlockCommitProof | undefined> {
+		const bytes = await this.driver.getProof(blockId, rev);
+		return bytes === undefined ? undefined : decodeJson<BlockCommitProof>(bytes);
+	}
+
+	async saveBlockProof(blockId: BlockId, rev: number, proof: BlockCommitProof): Promise<void> {
+		await this.driver.putProof(blockId, rev, encodeJson(proof));
+	}
+
 	// --- Materialized blocks ---
 
 	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {

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

@@ -2,7 +2,7 @@ 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
+ * In-memory {@link RawStoreDriver}: the six 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
@@ -16,6 +16,7 @@ export class MemoryStoreDriver implements RawStoreDriver {
 	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 proofs = new Map<string, Uint8Array>();       // `${blockId}:${rev}` -> proof bytes
 	private readonly materialized = new Map<string, Uint8Array>();
 
 	private revisionKey(blockId: BlockId, rev: number): string {
@@ -104,6 +105,16 @@ export class MemoryStoreDriver implements RawStoreDriver {
 		this.transactions.set(this.actionKey(blockId, actionId), value);
 	}
 
+	// --- proofs (keyed like revisions, NOT like actions — see RawStoreDriver.getProof) ---
+
+	async getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		return this.proofs.get(this.revisionKey(blockId, rev));
+	}
+
+	async putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		this.proofs.set(this.revisionKey(blockId, rev), value);
+	}
+
 	// --- materialized ---
 
 	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
@@ -132,6 +143,19 @@ export class MemoryStoreDriver implements RawStoreDriver {
 
 	// --- optional passthroughs ---
 
+	// Deliberately NO storeIdentity(): two MemoryStoreDrivers hold two independent Maps and are
+	// genuinely two different stores, so there is no shared "location" for them to name.
+	//
+	// NOTE: one driver object shared by two `KvRawStorage` wrappers is NOT covered. `withReadCache`
+	// falls back to keying on the STORAGE object, not the driver, so those two wrappers are two
+	// keys and get two read caches over one Map — the divergence dedupe exists to remove. Harmless
+	// today: this driver is a test fixture and every shipping backend's driver reports an identity,
+	// so the identity-less path only ever sees genuinely distinct stores. If a host ever wires
+	// `rawStorageFactory: () => new KvRawStorage(oneSharedDriver)` for two consumers, give this
+	// driver `identityForHandle('memory', this)` (store-identity.ts) — that makes the two wrappers
+	// name one store — and re-premise `local-transactor-read-cache.spec.ts`, which currently
+	// asserts the non-dedupe.
+
 	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
@@ -147,7 +171,7 @@ export class MemoryStoreDriver implements RawStoreDriver {
 		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 store of [this.revisions, this.pending, this.transactions, this.proofs, this.materialized]) {
 			for (const [key, value] of store) {
 				total += key.length + value.byteLength;
 			}

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`/`BlockCommitProof` (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;
+}