@optimystic/db-p2p 0.14.0 → 0.16.2

package/src/repo/coordinator-repo.ts

@@ -1,5 +1,5 @@
 import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig, BlockId, ActionRev, ActionContext, ClusterRecord } from "@optimystic/db-core";
-import { LruMap, blockIdsForTransforms } from "@optimystic/db-core";
+import { LruMap, blockIdsForTransforms, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
 import { ClusterCoordinator } from "./cluster-coordinator.js";
 import type { ClusterClient } from "../cluster/client.js";
 import type { PeerId } from "@libp2p/interface";
@@ -7,7 +7,9 @@ import { peerIdFromString } from "@libp2p/peer-id";
 import type { FretService } from "p2p-fret";
 import { createLogger } from '../logger.js';
 import type { IPeerReputation } from "../reputation/types.js";
+import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "../cluster/i-transaction-state-store.js";
+import { selectQuorumRev, type RevClaim, type QuorumRev } from "../cluster/quorum-restore.js";
 
 const log = createLogger('coordinator-repo');
 
@@ -69,6 +71,11 @@ export class CoordinatorRepo implements IRepo {
 	private readonly readRepairMode: 'off' | 'lazy' | 'paranoid';
 	private readonly readRepairWindowMs: number;
 	private readonly readRepairSampleRate: number;
+	/** Simple-majority threshold from the consensus policy; drives the read-repair corroboration quorum. */
+	private readonly simpleMajorityThreshold: number;
+	/** Resolved super-majority threshold the coordinator commits on (mirrors the value handed to ClusterCoordinator). */
+	private readonly superMajorityThreshold: number;
+	private readonly reputation?: IPeerReputation;
 	/** Test seam: overridable clock for window-based read-repair gating. */
 	now: () => number = () => Date.now();
 	/** Test seam: overridable RNG (0..1) for sample-rate gating. */
@@ -89,7 +96,7 @@ export class CoordinatorRepo implements IRepo {
 		this.localPeerId = localPeerId;
 		const policy: ClusterConsensusConfig & { clusterSize: number } = {
 			clusterSize: cfg?.clusterSize ?? 10,
-			superMajorityThreshold: cfg?.superMajorityThreshold ?? 0.75,
+			superMajorityThreshold: cfg?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
 			simpleMajorityThreshold: cfg?.simpleMajorityThreshold ?? 0.51,
 			minAbsoluteClusterSize: cfg?.minAbsoluteClusterSize ?? 3,
 			allowClusterDownsize: cfg?.allowClusterDownsize ?? true,
@@ -100,13 +107,20 @@ export class CoordinatorRepo implements IRepo {
 			commitBroadcastRetryMaxIntervalMs: cfg?.commitBroadcastRetryMaxIntervalMs ?? 8000,
 			commitBroadcastRetryMaxAttempts: cfg?.commitBroadcastRetryMaxAttempts ?? 5,
 			commitBroadcastImmediateRetries: cfg?.commitBroadcastImmediateRetries ?? 1,
+			promiseImmediateRetries: cfg?.promiseImmediateRetries ?? 1,
 			readRepairMode: cfg?.readRepairMode ?? 'lazy',
 			readRepairWindowMs: cfg?.readRepairWindowMs ?? 10000,
-			readRepairSampleRate: cfg?.readRepairSampleRate ?? 0
+			readRepairSampleRate: cfg?.readRepairSampleRate ?? 0,
+			// Default false: an undersized cluster with no confident network-size estimate
+			// is REJECTED (fail closed). Callers only opt in for single-node/local/test meshes.
+			allowUnvalidatedSmallCluster: cfg?.allowUnvalidatedSmallCluster ?? false
 		};
 		this.readRepairMode = policy.readRepairMode!;
 		this.readRepairWindowMs = policy.readRepairWindowMs!;
 		this.readRepairSampleRate = policy.readRepairSampleRate!;
+		this.simpleMajorityThreshold = policy.simpleMajorityThreshold;
+		this.superMajorityThreshold = policy.superMajorityThreshold;
+		this.reputation = reputation;
 		const localClusterRef = localCluster && localPeerId ? {
 			update: localCluster.update.bind(localCluster),
 			peerId: localPeerId,
@@ -115,6 +129,15 @@ export class CoordinatorRepo implements IRepo {
 		this.coordinator = new ClusterCoordinator(keyNetwork, createClusterClient, policy, localClusterRef, fretService, reputation, stateStore);
 	}
 
+	/**
+	 * The resolved super-majority threshold this coordinator commits on. Exposed so the composition root
+	 * can fail-fast if the coordinator and the cluster member would run different thresholds (see the
+	 * coupling assertion in `libp2p-node-base.ts`).
+	 */
+	get effectiveSuperMajorityThreshold(): number {
+		return this.superMajorityThreshold;
+	}
+
 	/** Recover coordinator transactions from persistent store after a restart. */
 	async recoverTransactions(): Promise<void> {
 		await this.coordinator.recoverTransactions();
@@ -183,6 +206,13 @@ export class CoordinatorRepo implements IRepo {
 		//   (b) Stale-by-policy — block is present but read-repair policy says verify.
 		// Skip cluster fetch if this is already a sync request (to prevent recursive queries).
 		const skipClusterFetch = (options as any)?.skipClusterFetch;
+		// NOTE: NetworkTransactor.get treats an authoritative "absent" ({ state: {} })
+		// as final and no longer retries it (ticket txn-perf-authoritative-notfound),
+		// relying on this cluster reconciliation to have already run. If a coordinator
+		// is ever configured WITHOUT clusterLatestCallback, a missing block is answered
+		// from local state alone with no transactor-level retry to compensate. That is
+		// fine today (such a coordinator has no cluster to reconcile against), but keep
+		// this coupling in mind if a partial-cluster read path is added.
 		if (this.clusterLatestCallback && !skipClusterFetch) {
 			for (const blockId of blockGets.blockIds) {
 				const localEntry = localResult[blockId];
@@ -292,11 +322,23 @@ export class CoordinatorRepo implements IRepo {
 	}
 
 	/**
-	 * Query cluster peers to find the maximum latest revision for a block.
+	 * Query cluster peers for their latest revision and return the highest
+	 * revision corroborated by a quorum of distinct peers.
+	 *
+	 * Replaces the old "max rev any single peer reports" — which let one lying
+	 * peer over-reporting its revision steer restoration — with quorum
+	 * corroboration on the exact `(rev, actionId)` pair (see
+	 * {@link selectQuorumRev}). The local node's own latest is included as a
+	 * corroborating vote because `clusterLatestCallback` self-short-circuits to
+	 * local storage. Returns `undefined` (keep local, do not restore) when no
+	 * revision is corroborated.
+	 *
+	 * NOTE: the quorum is corroboration-of-a-claim, NOT Sybil-resistant cohort
+	 * membership — a peer minting fresh keypairs still casts a vote. Commit-cert
+	 * + membership anchoring is deferred to backlog
+	 * `debt-read-repair-commit-cert-verification`.
 	 */
 	private async queryClusterForLatest(peerIds: string[], blockId: BlockId, context?: ActionContext): Promise<ActionRev | undefined> {
-		let maxLatest: ActionRev | undefined;
-
 		// Add timeout wrapper to prevent hanging on unresponsive peers
 		const withTimeout = <T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> =>
 			Promise.race([
@@ -304,30 +346,68 @@ export class CoordinatorRepo implements IRepo {
 				new Promise<undefined>(resolve => setTimeout(() => resolve(undefined), timeoutMs))
 			]);
 
-		// Query peers in parallel for their latest revision (with 1s timeout per peer)
+		// Query peers in parallel for their latest revision (with 1s timeout per peer),
+		// tagging each response with the peer that made it so votes stay distinct.
 		const latestResults = await Promise.allSettled(
-			peerIds.map(peerIdStr => {
+			peerIds.map(async peerIdStr => {
 				const peerId = peerIdFromString(peerIdStr);
-				return withTimeout(this.clusterLatestCallback!(peerId, blockId, context), 1000);
+				const value = await withTimeout(this.clusterLatestCallback!(peerId, blockId, context), 1000);
+				return { peerIdStr, value };
 			})
 		);
 
+		const claims: RevClaim[] = [];
 		for (const result of latestResults) {
-			if (result.status === 'fulfilled' && result.value) {
-				const peerLatest = result.value;
-				if (!maxLatest || peerLatest.rev > maxLatest.rev) {
-					maxLatest = peerLatest;
-				}
+			if (result.status === 'fulfilled' && result.value.value) {
+				const { peerIdStr, value } = result.value;
+				claims.push({ peerId: peerIdStr, rev: value.rev, actionId: value.actionId });
 			}
 		}
 
-		return maxLatest;
+		const selected = selectQuorumRev(claims, this.simpleMajorityThreshold);
+		if (!selected) {
+			log('cluster-fetch:no-quorum', { blockId, responders: claims.length });
+			return undefined;
+		}
+
+		// Best-effort: penalize peers whose claim contradicts the corroborated pair
+		// (an inflated rev the quorum outvoted, or conflicting content at the agreed
+		// rev). A lower rev is just lag, never penalized. Never let this throw.
+		this.penalizeContradictingRevClaims(claims, selected, blockId);
+
+		return { actionId: selected.actionId, rev: selected.rev };
+	}
+
+	/**
+	 * Report peers whose reported latest contradicts the quorum-corroborated pair. Best-effort.
+	 *
+	 * NOTE: the `rev > selected.rev` branch is NOT provable misbehavior — an honest
+	 * peer legitimately ahead of the sampled quorum (an in-flight commit it durably
+	 * stored, or other honest holders dropped from the sample by the 1s per-peer
+	 * timeout) reports a higher rev and gets penalized (weight 30 → immediate
+	 * deprioritize at threshold 20). Distinguishing a liar from an honest leader
+	 * needs the commit-cert verification tracked in backlog
+	 * `debt-read-repair-penalty-provable-only` / `debt-read-repair-commit-cert-verification`.
+	 */
+	private penalizeContradictingRevClaims(claims: RevClaim[], selected: QuorumRev, blockId: BlockId): void {
+		if (!this.reputation) return;
+		try {
+			for (const c of claims) {
+				const contradicts = c.rev > selected.rev
+					|| (c.rev === selected.rev && c.actionId !== selected.actionId);
+				if (contradicts) {
+					this.reputation.reportPeer(c.peerId, PenaltyReason.InvalidRestoration, `read-repair:${blockId}`);
+				}
+			}
+		} catch (err) {
+			log('cluster-fetch:penalize-error', { blockId, error: (err as Error).message });
+		}
 	}
 
 	async pend(request: PendRequest, options?: MessageOptions): Promise<PendResult> {
 		const allBlockIds = blockIdsForTransforms(request.transforms);
 		await this.verifyResponsibility(allBlockIds);
-		const coordinatingBlockIds = (options as any)?.coordinatingBlockIds ?? allBlockIds;
+		const coordinatingBlockIds = options?.coordinatingBlockIds ?? allBlockIds;
 
 		const peerCount = await this.coordinator.getClusterSize(coordinatingBlockIds[0]!);
 		if (peerCount <= 1) {

package/src/repo/service.ts

@@ -5,6 +5,7 @@ import type { IRepo, RepoMessage } from '@optimystic/db-core'
 import { blockIdsForTransforms } from '@optimystic/db-core'
 import { peersEqual } from '../peer-utils.js'
 import { encodePeers, type RedirectPayload } from './redirect.js'
+import { MAX_BLOCK_MESSAGE_BYTES } from '../protocol-limits.js'
 import type { Uint8ArrayList } from 'uint8arraylist'
 import { createLogger } from '../logger.js'
 
@@ -267,6 +268,11 @@ export class RepoService implements Startable {
 
 				// Encode and yield the response
 				yield new TextEncoder().encode(JSON.stringify(response))
+				// One request per stream: every real RepoClient sends exactly one request
+				// per dial (see ProtocolClient.processMessage), so complete the generator
+				// after the first response. A second frame a peer queued is then never read
+				// or parsed. Mirrors sync/block-transfer.
+				return
 			}
 		}
 
@@ -274,7 +280,7 @@ export class RepoService implements Startable {
 			try {
 				const responses = pipe(
 					stream,
-					(source) => lpDecode(source),
+					(source) => lpDecode(source, { maxDataLength: MAX_BLOCK_MESSAGE_BYTES }),
 					processStream.bind(this),
 					(source) => lpEncode(source)
 				)

package/src/reputation/types.ts

@@ -20,6 +20,8 @@ export enum PenaltyReason {
 	FalseApproval = 'false-approval',
 	/** Challenger lost a dispute (their rejection was wrong) */
 	DisputeLost = 'dispute-lost',
+	/** Peer reported a block latest (rev/actionId) or served content contradicted by a cluster quorum during restoration */
+	InvalidRestoration = 'invalid-restoration',
 }
 
 /** Default penalty weights by reason */
@@ -34,6 +36,7 @@ export const DEFAULT_PENALTY_WEIGHTS: Record<PenaltyReason, number> = {
 	[PenaltyReason.ConnectionFailure]: 2,
 	[PenaltyReason.FalseApproval]: 40,
 	[PenaltyReason.DisputeLost]: 30,
+	[PenaltyReason.InvalidRestoration]: 30,
 };
 
 /** Thresholds controlling graduated reputation responses */

package/src/rn.ts

@@ -7,12 +7,15 @@ export * from './repo/cluster-coordinator.js';
 export * from './repo/coordinator-repo.js';
 export * from './repo/service.js';
 export * from './storage/block-storage.js';
+export * from './storage/raw-store-driver.js';
+export * from './storage/kv-raw-storage.js';
+export * from './storage/memory-store-driver.js';
 export * from './storage/memory-storage.js';
 export * from './storage/i-block-storage.js';
 export * from './storage/i-raw-storage.js';
 export * from './storage/struct.js';
 export * from './storage/storage-repo.js';
-export * from './storage/restoration-coordinator-v2.js';
+export * from './storage/restoration-coordinator.js';
 export * from './storage/ring-selector.js';
 export * from './storage/storage-monitor.js';
 export * from './storage/arachnode-fret-adapter.js';
@@ -26,3 +29,6 @@ export * from './routing/responsibility.js';
 export * from './routing/libp2p-known-peers.js';
 export * from './network/network-manager-service.js';
 export * from './network/get-network-manager.js';
+// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
+// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
+export * from './cohort-topic/peer-sig.js';

package/src/storage/arachnode-fret-adapter.ts

@@ -23,6 +23,24 @@ export interface ArachnodeInfo {
 
 	/** Ring membership status */
 	status: 'joining' | 'active' | 'moving' | 'leaving';
+
+	/**
+	 * The ring/partition this node is moving *from*, present only while `status === 'moving'`.
+	 *
+	 * During a ring shift the node advertises its **target** `ringDepth`/`partition` (Phase A) but
+	 * keeps serving its old range until it has confirmed the shed range is replicated elsewhere
+	 * (Phase B) and releases it (Phase C). `moveFrom` records that old range so peers can treat a
+	 * `moving` node as *still responsible for its old range* (fail-toward-old-holder), and so a
+	 * crash between advertise and release is recoverable. Cleared on release/rollback (→ `active`).
+	 * See `docs/arachnode-ring-handoff.md` § Part 2 & Part 3.
+	 */
+	moveFrom?: {
+		ringDepth: number;
+		partition?: {
+			prefixBits: number;
+			prefixValue: number;
+		};
+	};
 }
 
 /**
@@ -33,7 +51,15 @@ export interface ArachnodeInfo {
 export class ArachnodeFretAdapter {
 	private static readonly ARACHNODE_KEY = 'arachnode';
 
-	constructor(private readonly fret: FretService) {}
+	constructor(
+		private readonly fret: FretService,
+		/**
+		 * This node's own peer id string. When provided, {@link getMyArachnodeInfo} uses it
+		 * directly instead of reaching into the concrete FretService impl's private `.node` —
+		 * {@link FretService} (the public interface) exposes no self-peer accessor.
+		 */
+		private readonly selfPeerId?: string
+	) {}
 
 	/**
 	 * Set this node's Arachnode ring membership.
@@ -56,7 +82,12 @@ export class ArachnodeFretAdapter {
 	 * Get my own Arachnode info.
 	 */
 	getMyArachnodeInfo(): ArachnodeInfo | undefined {
-		const myPeerId = (this.fret as any).node?.peerId?.toString();
+		// Prefer the injected self peer id. Fall back to the concrete Libp2pFretService's private
+		// `.node.peerId` only when no id was injected — this cast is load-bearing (it depends on the
+		// concrete impl's shape, not the public FretService interface) and silently yields undefined
+		// for any impl lacking `.node`, so injection is the intended path.
+		const myPeerId = this.selfPeerId
+			?? (this.fret as unknown as { node?: { peerId?: { toString(): string } } }).node?.peerId?.toString();
 		if (!myPeerId) return undefined;
 		return this.getArachnodeInfo(myPeerId);
 	}

package/src/storage/arachnode-partition.ts

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