@optimystic/db-p2p 0.21.0 → 0.22.0

package/src/cluster/cluster-policy.ts

@@ -1,4 +1,8 @@
 import { DEFAULT_SUPER_MAJORITY_THRESHOLD, type ClusterConsensusConfig } from "@optimystic/db-core";
+import { createLogger } from "../logger.js";
+import { CORROBORATION_FLOOR } from "./quorum-restore.js";
+
+const log = createLogger('cluster-policy');
 
 /**
  * Resolves the operator-facing cluster knobs (`clusterSize`, `clusterPolicy.*`) into the concrete
@@ -48,6 +52,16 @@ import { DEFAULT_SUPER_MAJORITY_THRESHOLD, type ClusterConsensusConfig } from "@
  */
 export const minAbsoluteClusterSize = 2;
 
+/**
+ * Default replication factor / target cohort breadth when the operator declares no `clusterSize`.
+ *
+ * Exported (and re-exported from the package root) rather than left inline because a caller that
+ * must construct a `Libp2pKeyPeerNetwork` for a node it did not build has to state a cluster size —
+ * the constructor no longer supplies one — and the only defensible answer is "whatever a node built
+ * here would have resolved to". Repeating the literal is how the two drifted last time.
+ */
+export const DEFAULT_CLUSTER_SIZE = 10;
+
 /**
  * The operator-facing cluster knobs. `NodeOptions` (`libp2p-node-base.ts`) intersects this rather
  * than restating it, so a knob added here is one `resolveClusterPolicy` is guaranteed to see — a
@@ -110,8 +124,10 @@ export type ResolvedClusterPolicy = ClusterConsensusConfig & {
 };
 
 /**
- * Apply every cluster-policy default a node needs. Pure — same options in, same numbers out — so the
- * composition root's behavior is unit-testable (`test/cluster-policy.spec.ts`).
+ * Apply every cluster-policy default a node needs. Same options in, same numbers out, so the
+ * composition root's behavior is unit-testable (`test/cluster-policy.spec.ts`). Its one side effect
+ * is the `assumed-cluster-size-unset` advisory below, which lives here because this is the only place
+ * that knows the resolution produced a self-defeating combination.
  */
 export function resolveClusterPolicy(options: ClusterPolicyOptions): ResolvedClusterPolicy {
 	// undefined here means "the operator said nothing", which is the only case where the two
@@ -124,7 +140,42 @@ export function resolveClusterPolicy(options: ClusterPolicyOptions): ResolvedClu
 	// rejects non-positive integers). If another composition root starts accepting unvalidated config,
 	// clamp here rather than in each consumer.
 	const declaredCohortSize = options.clusterPolicy?.assumedClusterSize;
-	const clusterSize = options.clusterSize ?? 10;
+	const clusterSize = options.clusterSize ?? DEFAULT_CLUSTER_SIZE;
+	const repairCorroborationClusterSize = declaredCohortSize ?? clusterSize;
+
+	// Called once per node (resolveClusterPolicy runs once at construction), so this fires once per
+	// node startup, not per repair — a per-attempt warn on a busy node would be noise that gets
+	// filtered, defeating the point. Fires purely off configuration (not an observed cohort), so a
+	// deployment that genuinely runs `clusterSize` machines sees it too; worded as a conditional
+	// ("if you run fewer than N machines") rather than a fault for exactly that reason.
+	//
+	// The machine count in the message is CORROBORATION_FLOOR + 1, NOT repairCorroborationClusterSize:
+	// `corroboratorCapacity` caps only the FLOOR of two (`quorum-restore.ts`), so a cohort with two
+	// peers besides the reader meets it whatever the declared size. What an undeclared size costs is
+	// the relaxation below two, which is only reachable when repairCorroborationClusterSize <= 2.
+	// NOTE: only the UNDECLARED case warns. An operator who declares an assumedClusterSize larger than
+	// the cohort they actually run is equally unable to repair and gets no warning — deliberate, since
+	// a declaration is an explicit assertion and this function has no observed cohort to contradict it
+	// with. If `feat-admission-floor-from-observed-cohort-high-water-mark` ever lands (deriving the
+	// yardstick from observation), that warning becomes cheap and worth adding here.
+	if (declaredCohortSize === undefined && clusterSize > minAbsoluteClusterSize) {
+		const minimumSelfHealingDeployment = CORROBORATION_FLOOR + 1;
+		log('assumed-cluster-size-unset', {
+			clusterSize,
+			repairCorroborationClusterSize,
+			corroborationFloor: CORROBORATION_FLOOR,
+			minimumSelfHealingDeployment,
+			message:
+				`No clusterPolicy.assumedClusterSize declared: block repair (read-repair and reconcile) requires ` +
+				`${CORROBORATION_FLOOR} distinct corroborating peers other than the reader, and that floor is ` +
+				`relaxed only for a cohort that DECLARES it is smaller — with ` +
+				`repairCorroborationClusterSize=${repairCorroborationClusterSize} it never relaxes. So a deployment ` +
+				`that actually runs fewer than ${minimumSelfHealingDeployment} machines can never supply the floor ` +
+				`and every repair declines, permanently. If you run fewer than ${minimumSelfHealingDeployment} ` +
+				`machines, set clusterPolicy.assumedClusterSize to your real cohort size; it does not lower ` +
+				`clusterSize=${clusterSize} (the replication factor). Larger deployments can ignore this.`
+		});
+	}
 
 	return {
 		superMajorityThreshold: options.clusterPolicy?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
@@ -147,6 +198,6 @@ export function resolveClusterPolicy(options: ClusterPolicyOptions): ResolvedClu
 		// Repair corroboration floor, every repair. Defaults strict — to the replication factor — so an
 		// unconfigured node cannot have its floor talked down to a single voter by a shrunken cohort
 		// view. A genuinely small mesh declares its size (either field) to regain self-repair.
-		repairCorroborationClusterSize: declaredCohortSize ?? clusterSize
+		repairCorroborationClusterSize
 	};
 }

package/src/cluster/cluster-repo.ts

@@ -990,9 +990,9 @@ export class ClusterMember implements ICluster {
 	 *
 	 * NOTE: partition safety needs `2 · membershipAdmissionFraction · superMajorityThreshold > 1` — each
 	 * side of a split must recruit `fraction · threshold · K` distinct honest members, and two sides cannot
-	 * both find them in one K-peer cluster. At the shipped defaults (0.75 · 0.67) that product is 1.005 —
-	 * true, but with almost no margin. If either default is ever lowered, re-check Theorem 2 in
-	 * `docs/correctness.md` before shipping it.
+	 * both find them in one K-peer cluster. At the shipped defaults (0.75 · 0.75 — both default to
+	 * `DEFAULT_SUPER_MAJORITY_THRESHOLD` / `membershipAdmissionFraction`'s own default) that product is
+	 * 1.125. If either default is ever lowered, re-check Theorem 2 in `docs/correctness.md` before shipping it.
 	 */
 	private admissionFloor(k: number): number {
 		const scaled = Math.ceil(this.membershipAdmissionFraction * k);

package/src/cluster/cluster-size-coupling.ts

@@ -0,0 +1,45 @@
+/** A component that exposes the cluster size it actually resolved to. */
+export interface HasEffectiveClusterSize {
+	readonly effectiveClusterSize: number;
+}
+
+/**
+ * Fail-fast coupling check for a live node's cluster-size wiring, mirroring
+ * `assertSuperMajorityCoupling`.
+ *
+ * `resolveClusterPolicy` (`cluster/cluster-policy.ts`) is the single place that settles the
+ * replication factor / target cohort breadth (`clusterSize`). Every consumer that resolves its
+ * own cluster size — `Libp2pKeyPeerNetwork` (peer selection) and `NetworkManagerService` (ring
+ * sizing) — must be constructed from that SAME resolved value, or the membership admission
+ * gate's "is this declared peer set suspiciously small?" yardstick silently diverges from the
+ * cohort width peer selection actually assembles (ticket
+ * `bug-cluster-size-resolution-single-source`: an unconfigured node ran peer selection at 16
+ * while consensus believed full size was 10, so a cohort that had quietly lost six members still
+ * measured as full).
+ *
+ * On a live node both are constructed from `resolveClusterPolicy(options).clusterSize`, so this
+ * check normally passes. It exists to catch *future* drift — a call site reverting to its own
+ * default, a new consumer added without threading the resolved value — by throwing at
+ * construction with every resolved value and its source, rather than letting the node come up
+ * mismatched.
+ *
+ * @throws Error naming the resolved size and every consumer that disagrees with it.
+ */
+export function assertClusterSizeCoupling(
+	resolvedClusterSize: number,
+	consumers: Record<string, HasEffectiveClusterSize | undefined>
+): void {
+	const mismatches = Object.entries(consumers)
+		.filter((entry): entry is [string, HasEffectiveClusterSize] => entry[1] !== undefined)
+		.filter(([, consumer]) => consumer.effectiveClusterSize !== resolvedClusterSize)
+		.map(([name, consumer]) => `${name} resolved ${consumer.effectiveClusterSize}`);
+
+	if (mismatches.length > 0) {
+		throw new Error(
+			`Cluster size mismatch at node startup: resolveClusterPolicy() produced clusterSize=${resolvedClusterSize}, ` +
+			`but ${mismatches.join(', ')}. Every cluster-size consumer must be constructed from the SAME resolved ` +
+			`value (see cluster/cluster-policy.ts), or the membership admission gate's yardstick can diverge from ` +
+			`the cohort width peer selection actually assembles.`
+		);
+	}
+}

package/src/cluster/quorum-restore.ts

@@ -38,7 +38,7 @@ export interface QuorumRev {
  * seconded by a second, independent peer. See {@link quorumSize} for the cap that
  * applies when the cohort is smaller than this.
  */
-const CORROBORATION_FLOOR = 2;
+export const CORROBORATION_FLOOR = 2;
 
 /**
  * Number of distinct corroborating votes required to accept a claim:

package/src/cluster/reconcile-block.ts

@@ -4,7 +4,7 @@ import type { ReconcileBlockCallback } from "./cluster-repo.js";
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import {
-	selectQuorumRev, selectQuorumBlock, canonicalBlockHash, corroboratorCapacity,
+	selectQuorumRev, selectQuorumBlock, canonicalBlockHash, corroboratorCapacity, quorumSize,
 	type RevClaim, type BlockHashCandidate, type QuorumRev
 } from "./quorum-restore.js";
 import { createLogger } from '../logger.js';
@@ -172,14 +172,26 @@ export function createReconcileBlock(deps: ReconcileBlockDeps): ReconcileBlockCa
 		const selected = selectQuorumRev(revClaims, deps.simpleMajorityThreshold, capacity);
 		if (!selected) {
 			// Leave the block behind; churn/rebalance and the next commit retry.
-			log('reconcile:no-rev-quorum', { blockId, rev: committed.rev, responders: revClaims.length, capacity });
+			log('reconcile:no-rev-quorum', {
+				blockId,
+				rev: committed.rev,
+				responders: revClaims.length,
+				required: quorumSize(revClaims.length, deps.simpleMajorityThreshold, capacity),
+				repairCorroborationClusterSize: deps.repairCorroborationClusterSize
+			});
 			return;
 		}
 
 		const hashCandidates = await hashCarriers(candidates, selected);
 		const agreed = selectQuorumBlock(hashCandidates, deps.simpleMajorityThreshold, capacity);
 		if (!agreed) {
-			log('reconcile:no-content-quorum', { blockId, rev: selected.rev, carriers: hashCandidates.length, capacity });
+			log('reconcile:no-content-quorum', {
+				blockId,
+				rev: selected.rev,
+				carriers: hashCandidates.length,
+				required: quorumSize(hashCandidates.length, deps.simpleMajorityThreshold, capacity),
+				repairCorroborationClusterSize: deps.repairCorroborationClusterSize
+			});
 			return;
 		}
 

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./cluster/client.js";
 export * from "./cluster/cluster-repo.js";
+export * from "./cluster/cluster-policy.js";
 export * from "./cluster/commit-cert.js";
 export * from "./cluster/service.js";
 export * from "./cluster/rebalance-monitor.js";
@@ -31,6 +32,7 @@ export * from "./sync/service.js";
 export * from "./it-utility.js";
 export * from "./libp2p-key-network.js";
 export * from "./libp2p-node.js";
+export * from "./optimystic-node.js";
 export * from "./routing/responsibility.js";
 export * from "./routing/libp2p-known-peers.js";
 export * from "./network/network-manager-service.js";

package/src/libp2p-key-network.ts

@@ -149,9 +149,19 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 	private readonly networkMode: NetworkMode;
 	private readonly persistence?: NetworkStatePersistence;
 
+	// NOTE: seven positional parameters, and the list stays that way for now — converting to an
+	// options bag would touch ~50 construction sites in `test/libp2p-key-network.spec.ts` alone.
+	// Revisit if an eighth parameter is ever needed, or if that spec is being rewritten anyway.
 	constructor(
 		private readonly libp2p: Libp2p,
-		private readonly clusterSize: number = 16,
+		/**
+		 * Replication factor / target cohort breadth for peer selection. REQUIRED, deliberately:
+		 * a silent default here meant a caller that did not know the node's cluster size quietly
+		 * selected a different-width cohort than the node's own consensus path used for the same
+		 * key. Reuse the node's own instance (`node.keyNetwork`) where one exists; a caller that
+		 * genuinely must construct standalone passes `DEFAULT_CLUSTER_SIZE` (`cluster/cluster-policy.ts`).
+		 */
+		private readonly clusterSize: number,
 		selfCoordinationConfig?: SelfCoordinationConfig,
 		networkMode?: NetworkMode,
 		persistence?: NetworkStatePersistence,
@@ -161,17 +171,25 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 		 * provided, coordinator/cohort selection is scoped to peers that serve THIS
 		 * network's `cluster`/`repo` protocol, so a peer that only belongs to another
 		 * network sharing the same physical nodes/bootstraps is never chosen. When
-		 * ABSENT, the membership filter is disabled (today's exact behavior) — required
-		 * for backward compatibility because most call sites don't know the network name.
+		 * ABSENT, the membership filter is disabled.
+		 *
+		 * NOTE: optional for the same reason `clusterSize` used to be — "most call sites don't
+		 * know the network name" — and that reason no longer holds: both production sites now
+		 * pass it (`libp2p-node-base.ts`, and the foreign-node fallback in the Quereus
+		 * collection-factory), and only the mock-based cases in `test/libp2p-key-network.spec.ts`
+		 * omit it. So a caller omitting it today gets the filter silently off, exactly the shape
+		 * that let a second key network be built with a wrong cohort width. Left optional because
+		 * making it required would touch ~50 construction sites in that one spec and no reachable
+		 * caller is affected. Make it required (or take the whole list as an options bag) the
+		 * moment a THIRD production construction site appears, or when that spec is rewritten.
 		 */
 		private readonly protocolPrefix?: string
 	) {
-		// NOTE: no construction site in this repo passes a SelfCoordinationConfig — every one
-		// leaves it `undefined` (libp2p-node-base.ts, quereus-plugin-optimystic's
-		// collection-factory.ts and key-network.ts, reference-peer's cli.ts), so these
-		// defaults are always what is in force and no operator can tune them. If tuning
-		// `gracePeriodMs` is ever needed, those four sites have to thread the config through
-		// first. Low urgency: a grace-period denial no longer fails the caller, it only costs
+		// NOTE: no production construction site in this repo passes a SelfCoordinationConfig —
+		// both leave it `undefined` (libp2p-node-base.ts, and the foreign-node fallback in
+		// quereus-plugin-optimystic's collection-factory.ts), so these defaults are always what
+		// is in force and no operator can tune them. If tuning `gracePeriodMs` is ever needed,
+		// those two sites have to thread the config through first. Low urgency: a grace-period denial no longer fails the caller, it only costs
 		// a write the ~1s findCoordinator retry window before self-coordinating.
 		this.selfCoordinationConfig = {
 			gracePeriodMs: selfCoordinationConfig?.gracePeriodMs ?? 30_000,
@@ -183,6 +201,20 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 		this.setupConnectionTracking();
 	}
 
+	/** The cluster size this instance actually resolved to, for `assertClusterSizeCoupling`. */
+	get effectiveClusterSize(): number {
+		return this.clusterSize;
+	}
+
+	/**
+	 * The network-namespaced protocol prefix (`/optimystic/<networkName>`) selection is scoped to,
+	 * or `undefined` when the network-membership filter is off. Readable so a spec can assert the
+	 * node's attached instance really is network-scoped without reaching into a private field.
+	 */
+	get effectiveProtocolPrefix(): string | undefined {
+		return this.protocolPrefix;
+	}
+
 	// coordinator cache: key (base64url) -> peerId until expiry (bounded LRU-ish via Map insertion order)
 	private readonly coordinatorCache = new Map<string, { id: PeerId, expires: number }>()
 	private static readonly MAX_CACHE_ENTRIES = 1000