@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/repo/client.ts

@@ -3,6 +3,7 @@ import type {
 	PendRequest, CommitRequest, BlockGets, IPeerNetwork, PeerId
 } from "@optimystic/db-core";
 import type { RepoMessage } from "@optimystic/db-core";
+import { blockIdsForTransforms, blockIdToBytes } from "@optimystic/db-core";
 import { ProtocolClient } from "../protocol-client.js";
 import { peerIdFromString } from "@libp2p/peer-id";
 
@@ -64,20 +65,39 @@ export class RepoClient extends ProtocolClient implements IRepo {
 		};
 		const correlationId = this.extractCorrelationId(operations);
 		const deadline = options.expiration ?? (Date.now() + 30_000)
-		const msLeft = Math.max(1, deadline - Date.now())
-		const withTimeout = async <U>(fn: () => Promise<U>): Promise<U> => {
-			return await Promise.race<U>([
-				fn(),
-				new Promise<never>((_, reject) => setTimeout(() => reject(new Error('RepoClient timeout')), msLeft))
-			])
-		}
-		let response: any
+		const deadlineMs = Math.max(1, deadline - Date.now())
 		const preferred = (this.protocolPrefix ?? '/db-p2p') + '/repo/1.0.0'
-		response = await withTimeout(() => super.processMessage<any>(message, preferred, {
-			signal: options?.signal,
-			correlationId,
-			dialTimeoutMs: options?.dialTimeoutMs,
-		}))
+
+		// Drive the remaining `expiration` budget through an AbortController whose
+		// abort *reason* is the caller-facing `'RepoClient timeout'` Error, combined
+		// with any caller signal. processMessage forwards `signal` to both the dial
+		// and the response-read and calls `stream.abort(signal.reason)` on abort, so —
+		// unlike the old `Promise.race`, whose losing branch left the inner read
+		// running and leaked a pending read + stream on every timed-out RPC to a silent
+		// peer — the deadline now genuinely cancels the inner read while the caller
+		// still observes an error whose `.message === 'RepoClient timeout'`.
+		//
+		// Intentionally no `responseTimeoutMs`: the combined signal already bounds the
+		// read at `deadlineMs`. A second, shorter cap would surface as
+		// ResponseTimeoutError and mask the caller-facing 'RepoClient timeout' message.
+		const deadlineController = new AbortController()
+		const timer = setTimeout(
+			() => deadlineController.abort(new Error('RepoClient timeout')),
+			deadlineMs
+		)
+		const combinedSignal = options?.signal
+			? AbortSignal.any([options.signal, deadlineController.signal])
+			: deadlineController.signal
+		let response: any
+		try {
+			response = await super.processMessage<any>(message, preferred, {
+				signal: combinedSignal,
+				correlationId,
+				dialTimeoutMs: options?.dialTimeoutMs,
+			})
+		} finally {
+			clearTimeout(timer)
+		}
 
 		if (response?.redirect?.peers?.length) {
 			if (hop >= 2) {
@@ -89,8 +109,10 @@ export class RepoClient extends ProtocolClient implements IRepo {
 			if (next.id === currentIdStr) {
 				throw new Error('Redirect loop detected in RepoClient (same peer)')
 			}
-			// cache hint
-			this.recordCoordinatorForOpsIfSupported(operations, nextId)
+			// cache hint — await so the recorded key bytes match what findCoordinator
+			// later looks up (blockIdToBytes is async); deterministic ordering also
+			// keeps the hint testable. The redirect retry below is async anyway.
+			await this.recordCoordinatorForOpsIfSupported(operations, nextId)
 			// single-hop retry against target peer using repo protocol
 			const nextClient = RepoClient.create(nextId, this.peerNetwork, this.protocolPrefix)
 			return await nextClient.processRepoMessage<T>(operations, options, hop + 1)
@@ -98,28 +120,37 @@ export class RepoClient extends ProtocolClient implements IRepo {
 		return response as T;
 	}
 
-	private extractKeyFromOperations(ops: RepoMessage['operations']): Uint8Array | undefined {
+	private async extractKeyFromOperations(ops: RepoMessage['operations']): Promise<Uint8Array | undefined> {
 		const op = ops[0];
+		// The recorded key MUST be the sha256 digest produced by blockIdToBytes — the
+		// exact bytes findCoordinator/recordCoordinator key the coordinator cache on
+		// (NetworkTransactor passes blockIdToBytes(blockId)). Raw utf8 of the id would
+		// never match, so the hint would silently never be retrieved.
 		if ('get' in op) {
 			const id = op.get.blockIds[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('pend' in op) {
-			const id = Object.keys(op.pend.transforms)[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			// Key on a real block id the pend touches, NOT a structural transforms field
+			// name ('inserts'/'updates'/'deletes'); see RepoService.deriveBlockKey.
+			const id = blockIdsForTransforms(op.pend.transforms)[0];
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('commit' in op) {
-			return new TextEncoder().encode(op.commit.tailId);
+			// Anchor on blockIds[0] (where CoordinatorRepo.commit runs consensus +
+			// verifyResponsibility), NOT tailId — they differ for a non-tail batch.
+			const id = op.commit.blockIds[0];
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		if ('cancel' in op) {
 			const id = op.cancel.actionRef.blockIds[0];
-			return id ? new TextEncoder().encode(id) : undefined;
+			return id ? await blockIdToBytes(id) : undefined;
 		}
 		return undefined;
 	}
 
-	private recordCoordinatorForOpsIfSupported(ops: RepoMessage['operations'], peerId: PeerId): void {
-		const keyBytes = this.extractKeyFromOperations(ops)
+	private async recordCoordinatorForOpsIfSupported(ops: RepoMessage['operations'], peerId: PeerId): Promise<void> {
+		const keyBytes = await this.extractKeyFromOperations(ops)
 		const pn: any = this.peerNetwork as any
 		if (keyBytes != null && typeof pn?.recordCoordinator === 'function') {
 			pn.recordCoordinator(keyBytes, peerId)

package/src/repo/service.ts

@@ -1,9 +1,9 @@
 import { pipe } from 'it-pipe'
 import { decode as lpDecode, encode as lpEncode } from 'it-length-prefixed'
-import type { Startable, Logger, Stream, Connection, StreamHandler, PeerId } from '@libp2p/interface'
+import type { Startable, Logger, Stream, Connection, StreamHandler, PeerId, Libp2p } from '@libp2p/interface'
 import type { IRepo, RepoMessage } from '@optimystic/db-core'
+import { blockIdsForTransforms } from '@optimystic/db-core'
 import { peersEqual } from '../peer-utils.js'
-import { sha256 } from 'multiformats/hashes/sha2'
 import { encodePeers, type RedirectPayload } from './redirect.js'
 import type { Uint8ArrayList } from 'uint8arraylist'
 import { createLogger } from '../logger.js'
@@ -28,6 +28,13 @@ export type RepoServiceComponents = BaseComponents & {
 	networkManager?: NetworkManagerLike
 	peerId?: PeerId
 	getConnectionAddrs?: (peerId: PeerId) => string[]
+	/**
+	 * Optional libp2p node. The production wiring injects the node post-construction
+	 * via {@link RepoService.setLibp2p} (the `components.libp2p` proxy does not
+	 * reliably resolve from inside a service at request time); this field is a
+	 * best-effort fallback resolver used only when no node has been injected.
+	 */
+	libp2p?: Libp2p
 }
 
 export type RepoServiceInit = {
@@ -65,6 +72,14 @@ export class RepoService implements Startable {
 	private running: boolean
 	/** Responsibility K - how many peers are responsible for a key (for redirect decisions) */
 	private readonly responsibilityK: number
+	/**
+	 * The libp2p node, injected post-construction by the node wiring (see
+	 * libp2p-node-base.ts, mirroring how `networkManager`/`fret` receive theirs).
+	 * The libp2p `components.libp2p` proxy does NOT reliably resolve from inside a
+	 * service at request time, so the redirect path resolves the network manager,
+	 * self identity, and connection addrs through this explicitly-set reference.
+	 */
+	private libp2pRef: Libp2p | undefined
 
 	constructor(components: RepoServiceComponents, init: RepoServiceInit = {}) {
 		this.components = components
@@ -80,6 +95,19 @@ export class RepoService implements Startable {
 
 	readonly [Symbol.toStringTag] = '@libp2p/repo-service'
 
+	/**
+	 * Inject the running libp2p node. Called once post-construction by the node
+	 * wiring so the redirect path can resolve the network manager / self id / addrs.
+	 */
+	setLibp2p(libp2p: Libp2p): void {
+		this.libp2pRef = libp2p
+	}
+
+	/** Resolve the libp2p node: the injected ref first, then the (best-effort) components proxy. */
+	private getLibp2p(): Libp2p | undefined {
+		return this.libp2pRef ?? (this.components as any).libp2p
+	}
+
 	/**
 	 * Start the service
 	 */
@@ -110,17 +138,17 @@ export class RepoService implements Startable {
 
 	private getNetworkManager(): NetworkManagerLike | undefined {
 		if (this.components.networkManager) return this.components.networkManager
-		return (this.components as any).libp2p?.services?.networkManager as NetworkManagerLike | undefined
+		return (this.getLibp2p() as any)?.services?.networkManager as NetworkManagerLike | undefined
 	}
 
 	private getSelfId(): PeerId | undefined {
 		if (this.components.peerId) return this.components.peerId
-		return (this.components as any).libp2p?.peerId as PeerId | undefined
+		return this.getLibp2p()?.peerId as PeerId | undefined
 	}
 
 	private getPeerAddrs(peerId: PeerId): string[] {
 		if (this.components.getConnectionAddrs) return this.components.getConnectionAddrs(peerId)
-		const libp2p = (this.components as any).libp2p
+		const libp2p = this.getLibp2p() as any
 		if (!libp2p?.getConnections) return []
 		const conns: any[] = libp2p.getConnections(peerId) ?? []
 		const addrs: string[] = []
@@ -131,6 +159,41 @@ export class RepoService implements Startable {
 		return addrs
 	}
 
+	/**
+	 * Derive the redirect routing key and op name for a single operation.
+	 *
+	 * The key MUST be the block the corresponding handler actually coordinates and
+	 * verifies responsibility on, so redirect routing stays consistent with where the
+	 * op is executed:
+	 *   - get    → blockIds[0]
+	 *   - pend   → blockIdsForTransforms(transforms)[0]
+	 *   - cancel → actionRef.blockIds[0]
+	 *   - commit → blockIds[0]  (CoordinatorRepo.commit anchors consensus on
+	 *     getClusterSize(blockIds[0]) / executeClusterTransaction(blockIds[0]) and guards
+	 *     with verifyResponsibility(blockIds) — NOT tailId; for a per-block commit batch
+	 *     whose blockIds[0] !== tailId, keying on tailId redirected the commit to the
+	 *     collection tail's cluster, which then fails verifyResponsibility for the non-tail block.)
+	 *
+	 * Returns blockKey === undefined when the op carries no routable key (e.g. a cancel
+	 * with an empty blockIds list), in which case the caller handles it locally without a
+	 * redirect check.
+	 */
+	deriveBlockKey(operation: RepoMessage['operations'][number]): { blockKey: string | undefined, opName: string } {
+		if ('get' in operation) {
+			return { blockKey: operation.get.blockIds[0], opName: 'get' }
+		}
+		if ('pend' in operation) {
+			return { blockKey: blockIdsForTransforms(operation.pend.transforms)[0], opName: 'pend' }
+		}
+		if ('cancel' in operation) {
+			return { blockKey: operation.cancel.actionRef.blockIds[0], opName: 'cancel' }
+		}
+		if ('commit' in operation) {
+			return { blockKey: operation.commit.blockIds[0], opName: 'commit' }
+		}
+		return { blockKey: undefined, opName: 'unknown' }
+	}
+
 	/**
 	 * Check if this node should redirect the request for a given key.
 	 * Returns a RedirectPayload if not responsible, null if should handle locally.
@@ -140,8 +203,14 @@ export class RepoService implements Startable {
 		const nm = this.getNetworkManager()
 		if (!nm) return null
 
-		const mh = await sha256.digest(new TextEncoder().encode(blockKey))
-		const key = mh.digest
+		// Pass the RAW encoded block-key bytes to getCluster. getCluster hashes
+		// internally (hashKey == sha256), so the responsible-set coordinate becomes
+		// hashKey(encode(blockKey)) — identical to how the cluster coordinator
+		// derives it (ClusterCoordinator.getClusterForBlock → findCluster(encode(blockId))).
+		// Pre-hashing here would double-hash (hashKey(sha256(encode(blockKey)))), placing
+		// the cohort at an unrelated ring coordinate and redirecting requests the
+		// coordinator legitimately routed to this peer.
+		const key = new TextEncoder().encode(blockKey)
 		const cluster = await nm.getCluster(key)
 		;(message as any).cluster = cluster.map((p: PeerId) => p.toString?.() ?? String(p))
 
@@ -175,46 +244,25 @@ export class RepoService implements Startable {
 				const decoded = new TextDecoder().decode(msg.subarray())
 				const message = JSON.parse(decoded) as RepoMessage
 
-				// Process each operation
+				// Process each operation. Derive the redirect routing key once (keyed on the
+				// block the handler actually coordinates), redirect-check it, then dispatch.
 				const operation = message.operations[0]
-				let response: any
+				const { blockKey, opName } = this.deriveBlockKey(operation)
+				const redirect = blockKey !== undefined
+					? await this.checkRedirect(blockKey, opName, message)
+					: null
 
-				if ('get' in operation) {
-					const blockKey = operation.get.blockIds[0]!
-					const redirect = await this.checkRedirect(blockKey, 'get', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
-					}
+				let response: any
+				if (redirect) {
+					response = redirect
+				} else if ('get' in operation) {
+					response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
 				} else if ('pend' in operation) {
-					const blockKey = Object.keys(operation.pend.transforms)[0]!
-					const redirect = await this.checkRedirect(blockKey, 'pend', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.pend(operation.pend, { expiration: message.expiration })
-					}
+					response = await this.repo.pend(operation.pend, { expiration: message.expiration })
 				} else if ('cancel' in operation) {
-					const blockKey = operation.cancel.actionRef.blockIds[0]
-					if (blockKey) {
-						const redirect = await this.checkRedirect(blockKey, 'cancel', message)
-						if (redirect) {
-							response = redirect
-						} else {
-							response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
-						}
-					} else {
-						response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
-					}
+					response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
 				} else if ('commit' in operation) {
-					const blockKey = operation.commit.tailId
-					const redirect = await this.checkRedirect(blockKey, 'commit', message)
-					if (redirect) {
-						response = redirect
-					} else {
-						response = await this.repo.commit(operation.commit, { expiration: message.expiration })
-					}
+					response = await this.repo.commit(operation.commit, { expiration: message.expiration })
 				}
 
 				// Encode and yield the response

package/src/rpc-deadline.ts

@@ -0,0 +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,
+	};
+}

package/src/storage/block-storage.ts

@@ -1,5 +1,5 @@
 import type { BlockId, IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
-import { Latches, applyTransform } from "@optimystic/db-core";
+import { Latches, applyTransform, hashString } from "@optimystic/db-core";
 import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from "./struct.js";
 import type { IRawStorage } from "./i-raw-storage.js";
 import { mergeRanges } from "./helpers.js";
@@ -123,6 +123,105 @@ export class BlockStorage implements IBlockStorage {
 		return { reconciled: false, latest: meta.latest };
 	}
 
+	async saveReplica(block: IBlock, source?: ActionRev): Promise<ActionRev> {
+		const rev = source?.rev ?? 1;
+		// Deterministic fallback id when the sender carried no revision metadata, so a
+		// re-push of the same block resolves to the same (rev, actionId) and stays
+		// idempotent. Never random/time-based — that would mint a new revision per retry.
+		const actionId = source?.actionId ?? await hashString(`${this.blockId}:${JSON.stringify(block)}`);
+
+		// Serialize the read-modify-write on this block's metadata (mirrors ensureRevision).
+		const lockId = `BlockStorage.saveReplica:${this.blockId}`;
+		const release = await Latches.acquire(lockId);
+		try {
+			let meta = await this.storage.getMetadata(this.blockId);
+
+			// Monotonic guard: an equal-or-newer revision is already held. The block is
+			// durably present; do not downgrade `latest` or rewrite the metadata.
+			if (meta?.latest && meta.latest.rev >= rev) {
+				log('replica:skip blockId=%s rev=%d held=%d', this.blockId, rev, meta.latest.rev);
+				return meta.latest;
+			}
+
+			// Write rev → actionId, the action transform, and the materialized block.
+			// `{ insert: block }` satisfies saveRestored's write invariants; on the serving
+			// path materializeBlock returns the materialized block directly (single rev), so
+			// this transform is never applied — see ticket notes.
+			const archive: BlockArchive = {
+				blockId: this.blockId,
+				revisions: {
+					[rev]: {
+						action: { actionId, rev, transform: { insert: block } },
+						block
+					}
+				},
+				range: [rev, rev + 1]
+			};
+			await this.saveRestored(archive);
+
+			// Seed metadata when absent, advance latest, and merge the covered range.
+			if (!meta) {
+				meta = { latest: undefined, ranges: [] };
+			}
+			meta.latest = { rev, actionId };
+			meta.ranges.unshift([rev, rev + 1]);
+			meta.ranges = mergeRanges(meta.ranges);
+			await this.storage.saveMetadata(this.blockId, meta);
+
+			log('replica:save blockId=%s rev=%d actionId=%s', this.blockId, rev, actionId);
+			return meta.latest;
+		} finally {
+			release();
+		}
+	}
+
+	async saveDeletion(source: ActionRev): Promise<ActionRev> {
+		const { rev, actionId } = source;
+
+		// Share the saveReplica latch: both do a read-modify-write of `meta.latest`, so they must be
+		// mutually exclusive on this block to keep the monotonic guard sound.
+		const lockId = `BlockStorage.saveReplica:${this.blockId}`;
+		const release = await Latches.acquire(lockId);
+		try {
+			let meta = await this.storage.getMetadata(this.blockId);
+
+			// Monotonic guard: an equal-or-newer revision is already held. Do not downgrade `latest`
+			// or rewrite metadata — the tombstone (or a later revision) is already durable.
+			if (meta?.latest && meta.latest.rev >= rev) {
+				log('deletion:skip blockId=%s rev=%d held=%d', this.blockId, rev, meta.latest.rev);
+				return meta.latest;
+			}
+
+			// Forward tombstone: a `{ delete: true }` transform and NO materialized block. saveRestored
+			// skips materialization when `block` is absent, so the reverse-apply in materializeBlock
+			// resolves this revision to an absent block (read-back as undefined).
+			const archive: BlockArchive = {
+				blockId: this.blockId,
+				revisions: {
+					[rev]: {
+						action: { actionId, rev, transform: { delete: true } }
+					}
+				},
+				range: [rev, rev + 1]
+			};
+			await this.saveRestored(archive);
+
+			// Seed metadata when absent, advance latest, and merge the covered range.
+			if (!meta) {
+				meta = { latest: undefined, ranges: [] };
+			}
+			meta.latest = { rev, actionId };
+			meta.ranges.unshift([rev, rev + 1]);
+			meta.ranges = mergeRanges(meta.ranges);
+			await this.storage.saveMetadata(this.blockId, meta);
+
+			log('deletion:save blockId=%s rev=%d actionId=%s', this.blockId, rev, actionId);
+			return meta.latest;
+		} finally {
+			release();
+		}
+	}
+
 	private async ensureRevision(meta: BlockMetadata, rev: number): Promise<void> {
 		if (this.inRanges(rev, meta.ranges)) {
 			return;
@@ -154,7 +253,7 @@ export class BlockStorage implements IBlockStorage {
 		}
 	}
 
-	private async materializeBlock(_meta: BlockMetadata, targetRev: number): Promise<{ block: IBlock, actionRev: ActionRev }> {
+	private async materializeBlock(_meta: BlockMetadata, targetRev: number): Promise<{ block: IBlock, actionRev: ActionRev } | undefined> {
 		let block: IBlock | undefined;
 		let materializedActionRev: ActionRev | undefined;
 		const actions: ActionRev[] = [];
@@ -187,7 +286,11 @@ export class BlockStorage implements IBlockStorage {
 		}
 
 		if (!block) {
-			throw new Error(`Block ${this.blockId} has been deleted`);
+			// The reverse-apply collapsed to a tombstone (a `{ delete: true }` revision) — the block
+			// is absent at this revision, not corrupt. Read it back as undefined (matching getBlock's
+			// "no materialized content" contract) rather than throwing. The genuine-truncation throw
+			// ("Failed to find materialized block") above still fires when no materialization exists.
+			return undefined;
 		}
 		if (actions.length) {
 			await this.storage.saveMaterializedBlock(this.blockId, actions[0]!.actionId, block);

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

@@ -44,6 +44,33 @@ export interface IBlockStorage {
     /** 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).
+     *
+     * 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.
+     *
+     * 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