@optimystic/db-p2p 0.14.1 → 0.16.3

package/src/sync/client.ts

@@ -3,6 +3,7 @@ import type { IPeerNetwork } from '@optimystic/db-core';
 import { ProtocolClient } from '../protocol-client.js';
 import { buildSyncProtocol, type SyncRequest, type SyncResponse } from './protocol.js';
 import { withRpcDeadlineDefaults, type RpcDeadlineOptions } from '../rpc-deadline.js';
+import { MAX_BLOCK_MESSAGE_BYTES } from '../protocol-limits.js';
 
 /**
  * Client for sending sync requests to remote peers.
@@ -32,7 +33,10 @@ export class SyncClient extends ProtocolClient {
 	 * @throws Error if request fails or times out
 	 */
 	async requestBlock(request: SyncRequest, options?: RpcDeadlineOptions): Promise<SyncResponse> {
-		return await this.processMessage<SyncResponse>(request, this.protocol, withRpcDeadlineDefaults(options));
+		// Asymmetry: the *request* the server reads is a tiny SyncRequest (control cap
+		// on the server side), but the *response* read here is a BlockArchive carrying
+		// block data → block cap.
+		return await this.processMessage<SyncResponse>(request, this.protocol, { ...withRpcDeadlineDefaults(options), maxDataLength: MAX_BLOCK_MESSAGE_BYTES });
 	}
 
 	/**

package/src/sync/service.ts

@@ -4,6 +4,7 @@ import { buildSyncProtocol, type SyncRequest, type SyncResponse } from './protoc
 import { pipe } from 'it-pipe';
 import { toString as u8ToString } from 'uint8arrays/to-string';
 import * as lp from 'it-length-prefixed';
+import { MAX_CONTROL_MESSAGE_BYTES } from '../protocol-limits.js';
 import type { Uint8ArrayList } from 'uint8arraylist';
 
 export interface SyncServiceInit {
@@ -114,7 +115,7 @@ export class SyncService implements Startable {
 				const actualStream = stream.stream ?? stream;
 				const responses = pipe(
 					actualStream,
-					(source: any) => lp.decode(source),
+					(source: any) => lp.decode(source, { maxDataLength: MAX_CONTROL_MESSAGE_BYTES }),
 					processStream,
 					(source: any) => lp.encode(source)
 				);

package/src/testing/cohort-topic-mesh-harness.ts

@@ -56,18 +56,18 @@ import { DEFAULT_COHORT_TOPIC_PROTOCOLS as PROTOCOLS } from '../cohort-topic/pro
 
 export { PROTOCOLS };
 
-export const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+export { delay } from '@optimystic/db-core/test';
+import { delay } from '@optimystic/db-core/test';
 
-/** Poll `predicate` until true or `timeoutMs` elapses (deterministic-but-not-flaky async settle). */
-export async function waitFor(predicate: () => boolean, timeoutMs = 2_000, intervalMs = 5): Promise<boolean> {
+// NOTE: backward-compat wrapper returning boolean; downstream tickets (3-8) replace each
+// call site with the throw-on-timeout canonical waitFor from @optimystic/db-core/test.
+export async function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs = 2_000, intervalMs = 5): Promise<boolean> {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
-		if (predicate()) {
-			return true;
-		}
+		if (await predicate()) return true;
 		await delay(intervalMs);
 	}
-	return predicate();
+	return !!(await predicate());
 }
 
 // --- members (real Ed25519 keys) ---
@@ -268,6 +268,13 @@ export interface MeshOptions {
 export interface RouteTraceEntry {
 	readonly key: string;
 	readonly result: RegisterResult;
+	/**
+	 * Whether the routed frame carried a participant signature. A participant's own walk probes are always
+	 * signed; the cold-start forwarder→parent link frame is unsigned (`signature: ""`, the interim gap the
+	 * `cohort-topic-parent-child-link` follow-on closes). {@link walkTraceFrom} keeps only signed entries so
+	 * a follow-on instantiation's background parent-link RPC does not pollute a walk's reconstructed trace.
+	 */
+	readonly signed: boolean;
 }
 
 export class CohortMesh {
@@ -337,17 +344,18 @@ export class CohortMesh {
 	private async routeAct(msg: RouteAndMaybeActV1): Promise<NearAnchorV1 | { commitCertificate: string }> {
 		const key = b64urlToBytes(msg.key);
 		this.routeKeys.push(msg.key);
+		const signed = routedFrameIsSigned(msg.activity);
 		const target = this.nearest(key);
 		const handler = this.activity.get(target.idStr);
 		if (handler === undefined || this.down.has(target.idStr)) {
 			// No in-cluster activity to run (cold / unreachable target) → a bare anchor hint; the walk
 			// treats it as `no_state`.
-			this.routeTrace.push({ key: msg.key, result: 'no_state' });
+			this.routeTrace.push({ key: msg.key, result: 'no_state', signed });
 			return { v: 1, anchors: [], cohort_hint: [], estimated_cluster_size: this.members.length, confidence: 1 };
 		}
 		const cohort = this.assembleCohort(key, msg.want_k);
 		const reply = await handler(msg.activity ?? '', cohort, msg.min_sigs, msg.correlation_id);
-		this.routeTrace.push({ key: msg.key, result: replyResult(reply) });
+		this.routeTrace.push({ key: msg.key, result: replyResult(reply), signed });
 		return reply;
 	}
 
@@ -379,6 +387,24 @@ export class CohortMesh {
 	}
 }
 
+/**
+ * Whether the routed `RegisterV1` frame carries a participant signature. Decodes the activity best-effort
+ * (an undecodable / absent frame is treated as signed, so only a genuinely unsigned frame — the cold-start
+ * forwarder→parent link — is flagged). Lets {@link walkTraceFrom} drop the background parent-link RPC a
+ * `followOn` instantiation fires, which would otherwise alias a walk's own probe coord.
+ */
+function routedFrameIsSigned(activity: string | undefined): boolean {
+	if (activity === undefined || activity === '') {
+		return true;
+	}
+	try {
+		const frame = decodeCohortMessage(b64urlToBytes(activity)) as { signature?: unknown };
+		return typeof frame.signature !== 'string' || frame.signature.length > 0;
+	} catch {
+		return true;
+	}
+}
+
 /** The reply classification a `routeAct` resolved with: decode the commit certificate's `RegisterReplyV1`. */
 function replyResult(reply: NearAnchorV1 | { commitCertificate: string }): RegisterResult {
 	if ('commitCertificate' in reply) {
@@ -443,6 +469,7 @@ export async function signedWillingness(from: Member, coord: Uint8Array, epoch:
 		fromMember: bytesToB64url(from.bytes),
 		coord: bytesToB64url(coord),
 		cohortEpoch: bytesToB64url(epoch),
+		treeTier: 0,
 		willingnessBits, // default 'f' → willing at every tier
 		loadBuckets: [0, 0, 0, 0],
 		windowSeconds: 60,
@@ -458,6 +485,8 @@ export interface SignedRegisterOptions {
 	readonly tier?: number;
 	readonly treeTier?: number;
 	readonly bootstrap?: boolean;
+	/** Follow-on cold-start re-issue (treeTier >= 1); mutually exclusive with bootstrap, so pass `bootstrap: false`. */
+	readonly followOn?: boolean;
 	readonly ttl?: number;
 }
 
@@ -470,6 +499,7 @@ export async function signedRegister(participant: Member, topic: Uint8Array, now
 		participantCoord: bytesToB64url(participant.bytes),
 		ttl: opts.ttl ?? 90_000,
 		bootstrap: opts.bootstrap ?? true,
+		...(opts.followOn ? { followOn: true } : {}),
 		timestamp: now,
 		correlationId: bytesToB64url(new TextEncoder().encode(correlationId)),
 	};
@@ -522,10 +552,16 @@ export function coordTierMap(participant: Member, topic: Uint8Array, dMax: numbe
 	return map;
 }
 
-/** Reconstruct a {@link WalkTrace} from the mesh's recorded `routeTrace`, keeping only this walk's coords. */
+/**
+ * Reconstruct a {@link WalkTrace} from the mesh's recorded `routeTrace`, keeping only this walk's coords.
+ * Unsigned frames are excluded: a `followOn` cold-start instantiates a child whose background
+ * forwarder→parent link RPC routes to the (participant-independent) `coord_0` this walk also probes, so
+ * without the filter that link's `no_state` would alias the walk's own root probe and fabricate a spurious
+ * inward/outward move. Only the participant's own signed probes belong to the walk trace.
+ */
 export function walkTraceFrom(routeTrace: readonly RouteTraceEntry[], tierMap: Map<string, number>, dMax: number): WalkTrace {
 	const probes = routeTrace
-		.filter((e) => tierMap.has(e.key))
+		.filter((e) => tierMap.has(e.key) && e.signed)
 		.map((e) => ({ treeTier: tierMap.get(e.key)!, result: e.result }));
 	return { dMax, probes };
 }
@@ -585,6 +621,20 @@ export interface TopicSetup {
  * registration needs a seed. Operating on the cohort (not all `N` nodes) keeps setup `O(wantK²)` at
  * scale; for a whole-network cohort (`wantK = N`) it covers every node, matching the live-tier milestone.
  */
+/**
+ * Pump one gossip round on **every live coord engine across every node**, then let the async inbound
+ * `/cohort-gossip` handlers settle. This is the cold-bootstrap counterpart to {@link setupTopic}'s manual
+ * willingness pre-seed: with no seed, the idle-but-willing willingness heartbeat (change A) plus cold-sibling
+ * engine instantiation (change B) must carry a fresh cohort from cold to a willingness quorum on their own,
+ * and this drives the rounds that make that happen. Call it repeatedly — each call is one "wave": engines a
+ * previous wave's heartbeats just instantiated on siblings only get pumped (and so reciprocate their own
+ * willingness) on the next wave.
+ */
+export async function pumpMeshGossip(mesh: CohortMesh, now: number, settleMs = 30): Promise<void> {
+	await Promise.all(mesh.nodes.flatMap((n) => n.host.registry.all().map((e) => e.gossipRound(now))));
+	await delay(settleMs);
+}
+
 export async function setupTopic(mesh: CohortMesh, topic: Uint8Array, tierAddr = addressing): Promise<TopicSetup> {
 	const coord0 = tierAddr.coord0(topic);
 	const seedParticipant = mesh.nodes[0]!.member.bytes; // dummy participantCoord (unused at tier 0)

package/src/testing/index.ts

@@ -1 +1,2 @@
 export * from './mesh-harness.js';
+export * from './raw-storage-conformance.js';

package/src/testing/mesh-harness.ts

@@ -2,7 +2,7 @@ import type { PeerId, PrivateKey } from '@libp2p/interface';
 import type { IKeyNetwork, ClusterPeers, ICluster, ClusterRecord, IRepo, BlockId, ActionRev, ClusterConsensusConfig, ITransactor, PeerId as DbPeerId } from '@optimystic/db-core';
 import type { FindCoordinatorOptions } from '@optimystic/db-core';
 import type { IPeerNetwork } from '@optimystic/db-core';
-import { NetworkTransactor } from '@optimystic/db-core';
+import { NetworkTransactor, DEFAULT_SUPER_MAJORITY_THRESHOLD } from '@optimystic/db-core';
 import { peerIdFromPrivateKey } from '@libp2p/peer-id';
 import { generateKeyPair } from '@libp2p/crypto/keys';
 import { ClusterMember, clusterMember, type ReconcileBlockCallback } from '../cluster/cluster-repo.js';
@@ -141,12 +141,15 @@ export async function createMesh(nodeCount: number, options: MeshOptions): Promi
 		);
 
 		const consensusConfig: ClusterConsensusConfig = {
-			superMajorityThreshold: options.superMajorityThreshold ?? 0.75,
+			superMajorityThreshold: options.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
 			simpleMajorityThreshold: 0.51,
 			minAbsoluteClusterSize: 2,
 			allowClusterDownsize: options.allowClusterDownsize ?? true,
 			clusterSizeTolerance: 0.5,
-			partitionDetectionWindow: 60000
+			partitionDetectionWindow: 60000,
+			// Harness spins up small/single-node meshes on purpose; opt into running
+			// below the safe floor without a confident network-size estimate.
+			allowUnvalidatedSmallCluster: true
 		};
 
 		// Active reconciliation simulation: when a member commits a block it never
@@ -227,7 +230,9 @@ export async function createMesh(nodeCount: number, options: MeshOptions): Promi
 					// Ensure metadata exists
 					const meta = await localRawStorage.getMetadata(blockId as BlockId);
 					if (!meta) {
-						await localRawStorage.saveMetadata(blockId as BlockId, { latest: undefined, ranges: [[0]] });
+						// Seed empty ranges (honest: nothing reconstructible yet); the setLatest
+						// below merges [latest.rev, latest.rev+1] once the revision is persisted.
+						await localRawStorage.saveMetadata(blockId as BlockId, { latest: undefined, ranges: [] });
 					}
 					await localBlockStorage.saveMaterializedBlock(latest.actionId, entry.block);
 					await localBlockStorage.saveRevision(latest.rev, latest.actionId);
@@ -257,8 +262,11 @@ export async function createMesh(nodeCount: number, options: MeshOptions): Promi
 			(peerId: PeerId) => createClusterClient(peerId) as any,
 			{
 				clusterSize: options.clusterSize ?? nodeCount,
-				superMajorityThreshold: options.superMajorityThreshold ?? 0.75,
-				allowClusterDownsize: options.allowClusterDownsize ?? true
+				superMajorityThreshold: options.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
+				allowClusterDownsize: options.allowClusterDownsize ?? true,
+				// Harness meshes run below the safe floor on purpose; opt the coordinator
+				// side into that so validateSmallCluster admits them (fails closed by default).
+				allowUnvalidatedSmallCluster: true
 			}
 		);
 		node.coordinatorRepo = factory({

package/src/testing/raw-storage-conformance.ts

@@ -0,0 +1,397 @@
+import { expect } from 'chai';
+import type { BlockId, ActionId, IBlock, BlockHeader, Transform, Transforms } from '@optimystic/db-core';
+import type { IRawStorage } from '../storage/i-raw-storage.js';
+import type { BlockMetadata } from '../storage/struct.js';
+import { StorageRepo } from '../storage/storage-repo.js';
+import { BlockStorage } from '../storage/block-storage.js';
+
+/**
+ * What `makeStorage` hands each conformance case: a fresh `IRawStorage` and a
+ * `cleanup` that releases it (close a handle, delete a temp dir, etc.). The
+ * memory driver's cleanup is a no-op; disk/db backends do real teardown.
+ */
+export interface ConformanceHarness {
+	storage: IRawStorage;
+	cleanup: () => Promise<void>;
+}
+
+const makeHeader = (id: string): BlockHeader => ({
+	id: id as BlockId,
+	type: 'test',
+	collectionId: 'collection-1' as BlockId
+});
+
+const makeBlock = (id: string, data?: Record<string, unknown>): IBlock => ({
+	header: makeHeader(id),
+	...data
+});
+
+const makeInsertTransforms = (blockId: BlockId, block: IBlock): Transforms => ({
+	inserts: { [blockId]: block },
+	updates: {},
+	deletes: []
+});
+
+async function collect<T>(iter: AsyncIterable<T>): Promise<T[]> {
+	const out: T[] = [];
+	for await (const item of iter) out.push(item);
+	return out;
+}
+
+/**
+ * Registers a `describe(name, ...)` block asserting that a raw-storage backend
+ * behaves identically to every other backend. This is the ONE maintained parity
+ * target that replaces the four copied `test/*-storage.spec.ts` specs — each
+ * driver package calls it from its own `test/` with a factory for its backend.
+ *
+ * It covers the union of what the existing per-backend specs assert PLUS the
+ * behaviors the shared kernel makes parity-critical: clone-on-store/read (now
+ * structural via the byte boundary), promote atomicity + the exact missing-pend
+ * error, drain-before-yield iteration, and a `BlockStorage`-level slice that
+ * guards the `meta.ranges` open-ended seeding invariant and tombstone read-back.
+ */
+export function runRawStorageConformance(
+	name: string,
+	makeStorage: () => Promise<ConformanceHarness>
+): void {
+	describe(name, () => {
+		let harness: ConformanceHarness;
+		let storage: IRawStorage;
+
+		beforeEach(async () => {
+			harness = await makeStorage();
+			storage = harness.storage;
+		});
+
+		afterEach(async () => {
+			await harness.cleanup();
+		});
+
+		// --- Metadata ---
+
+		it('getMetadata returns undefined on a miss', async () => {
+			expect(await storage.getMetadata('absent' as BlockId)).to.equal(undefined);
+		});
+
+		it('metadata round-trips, including a one-element open-ended range', async () => {
+			const blockId = 'meta-block' as BlockId;
+			// [1, 3] is a bounded range; [5] is OPEN-ENDED (undefined upper bound). The byte
+			// codec must preserve the open-ended encoding exactly — no range normalization.
+			const meta: BlockMetadata = { ranges: [[1, 3], [5]], latest: { rev: 5, actionId: 'tx:a5' as ActionId } };
+
+			await storage.saveMetadata(blockId, meta);
+			const got = await storage.getMetadata(blockId);
+
+			expect(got).to.deep.equal({ ranges: [[1, 3], [5]], latest: { rev: 5, actionId: 'tx:a5' } });
+		});
+
+		// --- Revisions ---
+
+		it('getRevision returns undefined on a miss', async () => {
+			expect(await storage.getRevision('block' as BlockId, 1)).to.equal(undefined);
+		});
+
+		it('revision round-trips', async () => {
+			const blockId = 'rev-block' as BlockId;
+			await storage.saveRevision(blockId, 7, 'tx:a7' as ActionId);
+			expect(await storage.getRevision(blockId, 7)).to.equal('tx:a7');
+		});
+
+		it('listRevisions is ascending, inclusive on both bounds, and skips sparse gaps', async () => {
+			const blockId = 'list-asc' as BlockId;
+			await storage.saveRevision(blockId, 1, 'a1' as ActionId);
+			await storage.saveRevision(blockId, 2, 'a2' as ActionId);
+			await storage.saveRevision(blockId, 4, 'a4' as ActionId); // rev 3 absent
+
+			const revs = await collect(storage.listRevisions(blockId, 1, 4));
+			expect(revs).to.deep.equal([
+				{ rev: 1, actionId: 'a1' },
+				{ rev: 2, actionId: 'a2' },
+				{ rev: 4, actionId: 'a4' }
+			]);
+		});
+
+		it('listRevisions descends when startRev > endRev (bounds still inclusive)', async () => {
+			const blockId = 'list-desc' as BlockId;
+			await storage.saveRevision(blockId, 1, 'a1' as ActionId);
+			await storage.saveRevision(blockId, 2, 'a2' as ActionId);
+			await storage.saveRevision(blockId, 4, 'a4' as ActionId);
+
+			const revs = await collect(storage.listRevisions(blockId, 4, 1));
+			expect(revs).to.deep.equal([
+				{ rev: 4, actionId: 'a4' },
+				{ rev: 2, actionId: 'a2' },
+				{ rev: 1, actionId: 'a1' }
+			]);
+		});
+
+		it('listRevisions with a single inclusive bound yields that one rev', async () => {
+			const blockId = 'list-single' as BlockId;
+			await storage.saveRevision(blockId, 3, 'a3' as ActionId);
+			expect(await collect(storage.listRevisions(blockId, 3, 3))).to.deep.equal([{ rev: 3, actionId: 'a3' }]);
+		});
+
+		it('listRevisions is scoped to one blockId (a second block does not leak in)', async () => {
+			const a = 'scope-a' as BlockId;
+			const b = 'scope-b' as BlockId;
+			await storage.saveRevision(a, 1, 'a1' as ActionId);
+			await storage.saveRevision(b, 1, 'b1' as ActionId);
+			await storage.saveRevision(b, 2, 'b2' as ActionId);
+
+			expect(await collect(storage.listRevisions(a, 1, 5))).to.deep.equal([{ rev: 1, actionId: 'a1' }]);
+		});
+
+		it('listRevisions over an empty range yields nothing', async () => {
+			expect(await collect(storage.listRevisions('empty' as BlockId, 1, 10))).to.deep.equal([]);
+		});
+
+		it('listRevisions tolerates awaits interleaved between yields (drain-before-yield)', async () => {
+			const blockId = 'drain-revs' as BlockId;
+			await storage.saveRevision(blockId, 1, 'a1' as ActionId);
+			await storage.saveRevision(blockId, 2, 'a2' as ActionId);
+			await storage.saveRevision(blockId, 3, 'a3' as ActionId);
+
+			const seen: Array<[number, ActionId]> = [];
+			for await (const { rev, actionId } of storage.listRevisions(blockId, 1, 3)) {
+				// An unrelated storage read between yields would auto-commit / invalidate a
+				// native cursor that straddled the await, if the driver failed to drain first.
+				await storage.getMetadata('other' as BlockId);
+				seen.push([rev, actionId]);
+			}
+			expect(seen).to.deep.equal([[1, 'a1'], [2, 'a2'], [3, 'a3']]);
+		});
+
+		// --- Pending transactions ---
+
+		it('getPendingTransaction returns undefined on a miss', async () => {
+			expect(await storage.getPendingTransaction('block' as BlockId, 'a' as ActionId)).to.equal(undefined);
+		});
+
+		it('pending transaction round-trips', async () => {
+			const blockId = 'pend-block' as BlockId;
+			const transform: Transform = { insert: makeBlock('pend-block', { items: ['x'] }) };
+			await storage.savePendingTransaction(blockId, 'a1' as ActionId, transform);
+			expect(await storage.getPendingTransaction(blockId, 'a1' as ActionId)).to.deep.equal(transform);
+		});
+
+		it('listPendingTransactions is scoped to one block', async () => {
+			const a = 'pend-a' as BlockId;
+			const b = 'pend-b' as BlockId;
+			await storage.savePendingTransaction(a, 'a1' as ActionId, { delete: true });
+			await storage.savePendingTransaction(a, 'a2' as ActionId, { delete: true });
+			await storage.savePendingTransaction(b, 'b1' as ActionId, { delete: true });
+
+			const ids = new Set(await collect(storage.listPendingTransactions(a)));
+			expect(ids).to.deep.equal(new Set(['a1', 'a2']));
+		});
+
+		it('deletePendingTransaction removes the pending entry', async () => {
+			const blockId = 'pend-del' as BlockId;
+			await storage.savePendingTransaction(blockId, 'a1' as ActionId, { delete: true });
+			await storage.deletePendingTransaction(blockId, 'a1' as ActionId);
+
+			expect(await storage.getPendingTransaction(blockId, 'a1' as ActionId)).to.equal(undefined);
+			expect(await collect(storage.listPendingTransactions(blockId))).to.deep.equal([]);
+		});
+
+		it('listPendingTransactions tolerates awaits interleaved between yields (drain-before-yield)', async () => {
+			const blockId = 'drain-pend' as BlockId;
+			await storage.savePendingTransaction(blockId, 'a1' as ActionId, { delete: true });
+			await storage.savePendingTransaction(blockId, 'a2' as ActionId, { delete: true });
+
+			const seen: ActionId[] = [];
+			for await (const id of storage.listPendingTransactions(blockId)) {
+				await storage.getMetadata('other' as BlockId);
+				seen.push(id);
+			}
+			expect(new Set(seen)).to.deep.equal(new Set(['a1', 'a2']));
+		});
+
+		// --- Committed transactions ---
+
+		it('getTransaction returns undefined on a miss', async () => {
+			expect(await storage.getTransaction('block' as BlockId, 'a' as ActionId)).to.equal(undefined);
+		});
+
+		it('committed transaction round-trips', async () => {
+			const blockId = 'tx-block' as BlockId;
+			const transform: Transform = { updates: [['items', 0, 0, ['y']]] };
+			await storage.saveTransaction(blockId, 'a1' as ActionId, transform);
+			expect(await storage.getTransaction(blockId, 'a1' as ActionId)).to.deep.equal(transform);
+		});
+
+		// --- Materialized blocks ---
+
+		it('getMaterializedBlock returns undefined on a miss', async () => {
+			expect(await storage.getMaterializedBlock('block' as BlockId, 'a' as ActionId)).to.equal(undefined);
+		});
+
+		it('materialized block round-trips', async () => {
+			const blockId = 'mat-block' as BlockId;
+			const block = makeBlock('mat-block', { items: ['z'] });
+			await storage.saveMaterializedBlock(blockId, 'a1' as ActionId, block);
+			expect(await storage.getMaterializedBlock(blockId, 'a1' as ActionId)).to.deep.equal(block);
+		});
+
+		it('saveMaterializedBlock(undefined) deletes; a subsequent get returns undefined', async () => {
+			const blockId = 'mat-del' as BlockId;
+			await storage.saveMaterializedBlock(blockId, 'a1' as ActionId, makeBlock('mat-del'));
+			await storage.saveMaterializedBlock(blockId, 'a1' as ActionId, undefined);
+			expect(await storage.getMaterializedBlock(blockId, 'a1' as ActionId)).to.equal(undefined);
+		});
+
+		// --- Promote (the only cross-key atomic op) ---
+
+		it('promotePendingTransaction moves pending → committed atomically', async () => {
+			const blockId = 'promote-block' as BlockId;
+			const transform: Transform = { insert: makeBlock('promote-block') };
+			await storage.savePendingTransaction(blockId, 'a1' as ActionId, transform);
+
+			await storage.promotePendingTransaction(blockId, 'a1' as ActionId);
+
+			expect(await storage.getTransaction(blockId, 'a1' as ActionId), 'committed after promote').to.deep.equal(transform);
+			expect(await storage.getPendingTransaction(blockId, 'a1' as ActionId), 'pending removed after promote').to.equal(undefined);
+		});
+
+		it('promotePendingTransaction throws the exact message when no pending entry exists', async () => {
+			const blockId = 'promote-missing' as BlockId;
+			let error: Error | undefined;
+			try {
+				await storage.promotePendingTransaction(blockId, 'nope' as ActionId);
+			} catch (err) {
+				error = err as Error;
+			}
+			expect(error, 'promote of a missing pending throws').to.not.equal(undefined);
+			expect(error!.message).to.equal(`Pending action nope not found for block ${blockId}`);
+		});
+
+		// --- Clone-on-store / clone-on-read (now structural via the byte boundary) ---
+
+		it('saveMetadata snapshots — a later caller mutation does not corrupt stored state', async () => {
+			const blockId = 'clone-meta' as BlockId;
+			const meta: BlockMetadata = { ranges: [[1, 2]], latest: { rev: 1, actionId: 'a1' as ActionId } };
+			await storage.saveMetadata(blockId, meta);
+
+			// Mutate the caller's object AFTER saving — must not reach stored state.
+			meta.ranges.push([9, 10]);
+			meta.latest!.rev = 99;
+
+			const stored = await storage.getMetadata(blockId);
+			expect(stored).to.deep.equal({ ranges: [[1, 2]], latest: { rev: 1, actionId: 'a1' } });
+		});
+
+		it('savePendingTransaction / saveTransaction snapshot — a later caller mutation does not corrupt stored state', async () => {
+			const blockId = 'clone-tx' as BlockId;
+			const pend: Transform = { insert: makeBlock('clone-tx', { items: ['p-original'] }) };
+			const committed: Transform = { insert: makeBlock('clone-tx', { items: ['c-original'] }) };
+			await storage.savePendingTransaction(blockId, 'p1' as ActionId, pend);
+			await storage.saveTransaction(blockId, 'c1' as ActionId, committed);
+
+			// Mutate both caller references AFTER saving — neither must reach stored state.
+			(pend.insert as IBlock & { items: string[] }).items.push('mutated');
+			pend.delete = true;
+			(committed.insert as IBlock & { items: string[] }).items.push('mutated');
+
+			const storedPend = await storage.getPendingTransaction(blockId, 'p1' as ActionId);
+			expect((storedPend!.insert as IBlock & { items: string[] }).items).to.deep.equal(['p-original']);
+			expect(storedPend!.delete).to.equal(undefined);
+			const storedCommitted = await storage.getTransaction(blockId, 'c1' as ActionId);
+			expect((storedCommitted!.insert as IBlock & { items: string[] }).items).to.deep.equal(['c-original']);
+		});
+
+		it('getMetadata returns an independent copy each read (mutating one does not affect another)', async () => {
+			const blockId = 'clone-meta-read' as BlockId;
+			await storage.saveMetadata(blockId, { ranges: [[1, 2]], latest: { rev: 1, actionId: 'a1' as ActionId } });
+
+			const first = await storage.getMetadata(blockId);
+			first!.ranges.push([9, 10]);
+
+			const second = await storage.getMetadata(blockId);
+			expect(second!.ranges).to.deep.equal([[1, 2]]);
+		});
+
+		it('saveMaterializedBlock snapshots and getMaterializedBlock returns a fresh object', async () => {
+			const blockId = 'clone-mat' as BlockId;
+			const block = makeBlock('clone-mat', { items: ['original'] });
+			await storage.saveMaterializedBlock(blockId, 'a1' as ActionId, block);
+
+			// Mutate the caller's block after saving.
+			(block as IBlock & { items: string[] }).items.push('mutated');
+
+			const stored = await storage.getMaterializedBlock(blockId, 'a1' as ActionId) as IBlock & { items: string[] };
+			expect(stored.items, 'stored copy unaffected by post-save mutation').to.deep.equal(['original']);
+
+			// Mutate a returned copy; a fresh get is unaffected.
+			stored.items.push('mutated-again');
+			const reread = await storage.getMaterializedBlock(blockId, 'a1' as ActionId) as IBlock & { items: string[] };
+			expect(reread.items, 'fresh read unaffected by mutation of a prior read').to.deep.equal(['original']);
+		});
+
+		// --- listBlockIds (optional; only when the driver implements it) ---
+
+		it('listBlockIds yields exactly the blocks with metadata', async function () {
+			const listBlockIds = storage.listBlockIds;
+			if (typeof listBlockIds !== 'function') {
+				this.skip();
+			} else {
+				await storage.saveMetadata('b1' as BlockId, { ranges: [], latest: undefined });
+				await storage.saveMetadata('b2' as BlockId, { ranges: [], latest: undefined });
+				// Pended but never committed → no metadata → must not be enumerated.
+				await storage.savePendingTransaction('pending-only' as BlockId, 'x' as ActionId, { delete: true });
+
+				const ids = new Set(await collect(listBlockIds.call(storage)));
+				expect(ids).to.deep.equal(new Set(['b1', 'b2']));
+			}
+		});
+
+		it('listBlockIds yields nothing for an empty store', async function () {
+			const listBlockIds = storage.listBlockIds;
+			if (typeof listBlockIds !== 'function') {
+				this.skip();
+			} else {
+				expect(await collect(listBlockIds.call(storage))).to.deep.equal([]);
+			}
+		});
+
+		// --- BlockStorage-level parity slice (over the same driver) ---
+
+		it('BlockStorage pend → commit seeds open-ended ranges [[E]] (never [[0]]) and getBlock serves it', async () => {
+			const blockId = 'parity-commit' as BlockId;
+			const repo = new StorageRepo((id) => new BlockStorage(id, storage));
+
+			await repo.pend({
+				actionId: 'a1' as ActionId,
+				transforms: makeInsertTransforms(blockId, makeBlock('parity-commit', { items: [] })),
+				policy: 'c'
+			});
+			const commit = await repo.commit({ actionId: 'a1' as ActionId, blockIds: [blockId], tailId: blockId, rev: 1 });
+			expect(commit.success, 'commit succeeded').to.equal(true);
+
+			const meta = await storage.getMetadata(blockId);
+			expect(meta!.latest?.rev).to.equal(1);
+			// Open-ended from the earliest committed rev E=1 — NOT the over-claim [[0]].
+			expect(meta!.ranges, 'coverage open-ended from E=1').to.deep.equal([[1]]);
+
+			const got = await new BlockStorage(blockId, storage).getBlock();
+			expect(got?.block.header.id, 'committed block served').to.equal('parity-commit');
+		});
+
+		it('BlockStorage saveReplica → saveDeletion reads the tombstoned rev back as undefined', async () => {
+			const blockId = 'parity-tombstone' as BlockId;
+			const bs = new BlockStorage(blockId, storage);
+
+			await bs.saveReplica(makeBlock('parity-tombstone', { items: ['live'] }), { rev: 1, actionId: 'r1' as ActionId });
+			const meta = await storage.getMetadata(blockId);
+			// saveReplica seeds open-ended coverage anchored at the replica rev, never [[0]].
+			expect(meta!.ranges, 'replica seeds open-ended [[1]]').to.deep.equal([[1]]);
+
+			const latest = await bs.saveDeletion({ rev: 2, actionId: 'd2' as ActionId });
+			expect(latest.rev).to.equal(2);
+
+			// getBlock at the tombstone rev reverse-applies { delete: true } → absent block.
+			expect(await bs.getBlock(), 'tombstoned rev reads back undefined').to.equal(undefined);
+			// The prior revision still materializes.
+			expect((await bs.getBlock(1))?.block.header.id, 'rev 1 still serves the live block').to.equal('parity-tombstone');
+		});
+	});
+}