@optimystic/db-p2p 0.14.1 → 0.16.3

package/src/storage/memory-storage.ts

@@ -1,173 +1,25 @@
-import type { BlockId, IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
-import type { BlockMetadata } from "./struct.js";
-import type { IRawStorage } from "./i-raw-storage.js";
-
-export class MemoryRawStorage implements IRawStorage {
-	private metadata = new Map<BlockId, BlockMetadata>();
-	private revisions = new Map<string, ActionId>(); // blockId:rev -> actionId
-	private pendingActions = new Map<string, Transform>(); // blockId:actionId -> transform
-	private actions = new Map<string, Transform>(); // blockId:actionId -> transform
-	private materializedBlocks = new Map<string, IBlock>(); // blockId:actionId -> block
-
-	private getRevisionKey(blockId: BlockId, rev: number): string {
-		return `${blockId}:${rev}`;
-	}
-
-	private getActionKey(blockId: BlockId, actionId: ActionId): string {
-		return `${blockId}:${actionId}`;
-	}
-
-	/**
-	 * Retrieves metadata for a block.
-	 *
-	 * @pitfall **MUST return a clone** - `BlockStorage.setLatest` mutates the returned
-	 * metadata in place (`meta.latest = latest`) before calling `saveMetadata`. Returning
-	 * the stored reference leaks that mutation into RAM even when a subsequent
-	 * `saveMetadata` call fails, masking mid-commit crashes that a persistent store
-	 * (file/sqlite/leveldb) would surface correctly.
-	 * @see docs/internals.md "Storage Returns References" pitfall
-	 */
-	async getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined> {
-		const meta = this.metadata.get(blockId);
-		return meta ? structuredClone(meta) : undefined;
-	}
-
-	/**
-	 * Stores metadata for a block.
-	 *
-	 * @pitfall **MUST store a clone** - callers may continue mutating the metadata object
-	 * after saving; storing the reference lets those mutations corrupt persisted state.
-	 * @see docs/internals.md "Storage Returns References" pitfall
-	 */
-	async saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void> {
-		this.metadata.set(blockId, structuredClone(metadata));
-	}
-
-	async getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined> {
-		return this.revisions.get(this.getRevisionKey(blockId, rev));
-	}
-
-	async saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void> {
-		this.revisions.set(this.getRevisionKey(blockId, rev), actionId);
-	}
-
-	async *listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev> {
-		const ascending = startRev <= endRev;
-		const actualStart = ascending ? startRev : endRev;
-		const actualEnd = ascending ? endRev : startRev;
-
-		const results: ActionRev[] = [];
-		for (let rev = actualStart; rev <= actualEnd; rev++) {
-			const actionId = this.revisions.get(this.getRevisionKey(blockId, rev));
-			if (actionId) {
-				results.push({ rev, actionId });
-			}
-		}
-
-		if (!ascending) {
-			results.reverse();
-		}
-
-		for (const result of results) {
-			yield result;
-		}
-	}
-
-	async getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
-		return this.pendingActions.get(this.getActionKey(blockId, actionId));
-	}
-
-	async savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
-		// Clone transform to prevent external modifications from affecting stored data
-		this.pendingActions.set(this.getActionKey(blockId, actionId), structuredClone(transform));
-	}
-
-	async deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
-		this.pendingActions.delete(this.getActionKey(blockId, actionId));
-	}
-
-	async *listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId> {
-		const prefix = `${blockId}:`;
-		for (const [key] of Array.from(this.pendingActions.entries())) {
-			if (key.startsWith(prefix)) {
-				yield key.substring(prefix.length);
-			}
-		}
-	}
-
-	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
-		return this.actions.get(this.getActionKey(blockId, actionId));
-	}
-
-	async saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
-		this.actions.set(this.getActionKey(blockId, actionId), transform);
-	}
-
-	/**
-	 * Retrieves a materialized block at a specific revision.
-	 *
-	 * @pitfall **MUST return a clone** - `applyTransform()` mutates blocks in place.
-	 * If we return the stored reference, mutations corrupt ALL revisions that share
-	 * the same underlying object.
-	 * @see docs/internals.md "Storage Returns References" pitfall
-	 */
-	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {
-		const block = this.materializedBlocks.get(this.getActionKey(blockId, actionId));
-		// Clone to prevent external mutations from affecting stored data
-		return block ? structuredClone(block) : undefined;
-	}
-
-	/**
-	 * Stores a materialized block at a specific revision.
-	 *
-	 * @pitfall **MUST store a clone** - callers may continue mutating the block after saving.
-	 * If we store the reference, those mutations corrupt the stored data.
-	 * @see docs/internals.md "Storage Returns References" pitfall
-	 */
-	async saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void> {
-		const key = this.getActionKey(blockId, actionId);
-		if (block) {
-			// Clone to prevent external mutations from affecting stored data
-			this.materializedBlocks.set(key, structuredClone(block));
-		} else {
-			this.materializedBlocks.delete(key);
-		}
-	}
-
-	async promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
-		const key = this.getActionKey(blockId, actionId);
-		const transform = this.pendingActions.get(key);
-		if (transform) {
-			this.actions.set(key, transform);
-			this.pendingActions.delete(key);
-		}
-	}
-
-	async getApproximateBytesUsed(): Promise<number> {
-		let total = 0;
-		for (const [blockId, meta] of this.metadata) {
-			total += blockId.length + jsonByteSize(meta);
-		}
-		for (const [key, actionId] of this.revisions) {
-			total += key.length + actionId.length;
-		}
-		for (const [key, transform] of this.pendingActions) {
-			total += key.length + jsonByteSize(transform);
-		}
-		for (const [key, transform] of this.actions) {
-			total += key.length + jsonByteSize(transform);
-		}
-		for (const [key, block] of this.materializedBlocks) {
-			total += key.length + jsonByteSize(block);
-		}
-		return total;
-	}
-}
-
-function jsonByteSize(value: unknown): number {
-	try {
-		return JSON.stringify(value)?.length ?? 0;
-	} catch {
-		return 0;
-	}
-}
+import { KvRawStorage } from "./kv-raw-storage.js";
+import { MemoryStoreDriver } from "./memory-store-driver.js";
+
+/**
+ * In-memory {@link IRawStorage}, now a thin shell over the shared
+ * {@link KvRawStorage} kernel backed by a {@link MemoryStoreDriver}.
+ *
+ * @pitfall The old hand-rolled version had to `structuredClone` on every get and
+ * put — otherwise callers mutating a returned/stored object corrupted the store
+ * (see docs/internals.md "Storage Returns References"). That discipline is GONE
+ * and must not be reintroduced: values cross the driver boundary as
+ * `Uint8Array` produced by `JSON`-encode and consumed by `JSON`-decode, so every
+ * read decodes a fresh object and every write stored an independent byte
+ * snapshot BY CONSTRUCTION. The clone-on-store / clone-on-read invariant is now
+ * structural, not a rule. The conformance suite asserts it so a future driver
+ * that shortcuts the byte boundary is caught.
+ *
+ * The name is kept stable so existing imports (`from '@optimystic/db-p2p'`)
+ * continue to resolve.
+ */
+export class MemoryRawStorage extends KvRawStorage {
+	constructor() {
+		super(new MemoryStoreDriver());
+	}
+}

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

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

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

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

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

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

package/src/storage/{restoration-coordinator-v2.ts → restoration-coordinator.ts}

@@ -1,10 +1,11 @@
 import type { BlockId } from '@optimystic/db-core';
-import { hashKey } from 'p2p-fret';
+import { hashKey, type RingCoord } from 'p2p-fret';
 import { peerIdFromString } from '@libp2p/peer-id';
 import type { BlockArchive, RestoreCallback } from './struct.js';
 import { SyncClient } from '../sync/client.js';
 import type { IPeerNetwork } from '@optimystic/db-core';
 import type { ArachnodeFretAdapter } from './arachnode-fret-adapter.js';
+import { partitionCovers } from './arachnode-partition.js';
 import { createLogger } from '../logger.js';
 
 /**
@@ -41,8 +42,14 @@ export class RestorationCoordinator {
 		const startTime = Date.now();
 		this.metrics.totalRequests++;
 
+		// Hash the block id once into the shared coordinate space. Peer responsibility
+		// (RingSelector.calculatePartition) and cohort assembly both operate on hashed
+		// coords, so restoration must filter in the same space — see getMyRingPeers and
+		// filterByPartition below, which reuse this value.
+		const blockCoord = await hashKey(new TextEncoder().encode(blockId));
+
 		// 1. Try my transaction ring peers first
-		const myPeers = await this.getMyRingPeers(blockId);
+		const myPeers = this.getMyRingPeers(blockCoord);
 		const myRingDepth = this.getMyRingDepth();
 
 		// Avoid dialing self: on a solo/bootstrap node with no listenAddrs, dialing self
@@ -63,13 +70,15 @@ export class RestorationCoordinator {
 				return archive;
 			}
 		}
+		// My transaction ring was queried and yielded nothing — count it as one ring failure.
+		this.recordFailure(myRingDepth);
 
 		// 2. Try inner storage rings (broader coverage)
 		for (let ringDepth = myRingDepth - 1; ringDepth >= 0; ringDepth--) {
 			const storagePeers = this.fretAdapter.findPeersAtRing(ringDepth);
 
 			// Filter to peers responsible for this block's partition (skip self — cannot dial self).
-			const responsiblePeers = this.filterByPartition(storagePeers, blockId, ringDepth)
+			const responsiblePeers = this.filterByPartition(storagePeers, blockCoord, ringDepth)
 				.filter(p => !this.selfPeerId || p !== this.selfPeerId);
 
 			for (const peerIdStr of responsiblePeers) {
@@ -79,6 +88,8 @@ export class RestorationCoordinator {
 					return archive;
 				}
 			}
+			// This inner ring was queried and yielded nothing — count it as one ring failure.
+			this.recordFailure(ringDepth);
 		}
 
 		// No ring had the data
@@ -98,11 +109,10 @@ export class RestorationCoordinator {
 
 	/**
 	 * Get peers in my transaction ring for a given block.
+	 * @param blockCoord the block id already hashed into the shared coordinate space.
 	 */
-	private async getMyRingPeers(blockId: BlockId): Promise<string[]> {
-		const blockIdBytes = new TextEncoder().encode(blockId);
-		const coord = await hashKey(blockIdBytes);
-		return this.fretAdapter.getFret().assembleCohort(coord, 10);
+	private getMyRingPeers(blockCoord: RingCoord): string[] {
+		return this.fretAdapter.getFret().assembleCohort(blockCoord, 10);
 	}
 
 	/**
@@ -115,43 +125,22 @@ export class RestorationCoordinator {
 
 	/**
 	 * Filter peers by partition responsibility.
+	 * @param blockCoord the block id hashed into the shared coordinate space (same space
+	 *   RingSelector.calculatePartition uses for peer partitions).
 	 */
-	private filterByPartition(peers: string[], blockId: BlockId, ringDepth: number): string[] {
+	private filterByPartition(peers: string[], blockCoord: RingCoord, ringDepth: number): string[] {
 		if (ringDepth === 0) {
 			return peers; // Ring 0 covers all blocks
 		}
 
-		const blockPrefix = this.extractBlockPrefix(blockId, ringDepth);
-
 		return peers.filter(peerId => {
 			const info = this.fretAdapter.getArachnodeInfo(peerId);
 			if (!info || !info.partition) return false;
-			return info.partition.prefixValue === blockPrefix;
+			// Compare block prefix vs peer partition via the shared responsibility derivation.
+			return partitionCovers(info.partition, blockCoord);
 		});
 	}
 
-	/**
-	 * Extract prefix bits from block ID for partition matching.
-	 */
-	private extractBlockPrefix(blockId: BlockId, bits: number): number {
-		const bytes = new TextEncoder().encode(blockId);
-		// Hash the block ID to get uniform distribution
-		const hash = new Uint8Array(32);
-		for (let i = 0; i < Math.min(bytes.length, hash.length); i++) {
-			hash[i] = bytes[i]!;
-		}
-
-		// Extract first N bits
-		let value = 0;
-		for (let i = 0; i < bits; i++) {
-			const byteIndex = Math.floor(i / 8);
-			const bitIndex = 7 - (i % 8);
-			const bit = (hash[byteIndex]! >> bitIndex) & 1;
-			value = (value << 1) | bit;
-		}
-		return value;
-	}
-
 	/**
 	 * Query a specific peer for a block.
 	 */
@@ -185,9 +174,18 @@ export class RestorationCoordinator {
 		const prevTotal = this.metrics.averageDurationMs * (totalSuccesses - 1);
 		this.metrics.averageDurationMs = (prevTotal + durationMs) / totalSuccesses;
 
-		console.log(
-			`[Ring ${ringDepth}] Successfully restored block ${blockId} in ${durationMs}ms`
-		);
+		this.log('[Ring %d] Successfully restored block %s in %dms', ringDepth, blockId, durationMs);
+	}
+
+	/**
+	 * Record that a ring was queried during a restore but did not yield the block.
+	 * Counterpart to {@link recordSuccess}: the ring — not the individual peer query — is the
+	 * failure unit, so this increments once per exhausted ring at the points where the peer
+	 * loops in {@link restore} complete without returning an archive.
+	 */
+	private recordFailure(ringDepth: number): void {
+		const count = this.metrics.failureByRing.get(ringDepth) ?? 0;
+		this.metrics.failureByRing.set(ringDepth, count + 1);
 	}
 
 	/**
@@ -199,7 +197,15 @@ export class RestorationCoordinator {
 		failureByRing: Map<number, number>;
 		averageDurationMs: number;
 	} {
-		return { ...this.metrics };
+		// Copy the Maps: a bare `{ ...this.metrics }` spreads only the top level, handing the
+		// caller the SAME Map instances this coordinator keeps mutating — the snapshot would
+		// then change under the caller's feet, and a caller mutation would corrupt internal state.
+		return {
+			totalRequests: this.metrics.totalRequests,
+			successByRing: new Map(this.metrics.successByRing),
+			failureByRing: new Map(this.metrics.failureByRing),
+			averageDurationMs: this.metrics.averageDurationMs
+		};
 	}
 }