@optimystic/db-p2p 0.17.0 → 0.18.0

package/src/cluster/cluster-repo.ts

@@ -117,9 +117,10 @@ export type ExpectedClusterView = {
  * Independently derive this member's own view of a block's responsible cluster. Injected so
  * {@link ClusterMember} stays transport-agnostic — the composition root supplies it from
  * `IKeyNetwork.findCluster` + FRET (mirroring how the coordinator derives the cluster). Absent on nodes
- * that cannot derive a view (no FRET, unit tests): with no derived view AND no configured full-size
- * reference the gate preserves legacy approve behavior, but a configured `clusterSize` still lets the gate
- * fail closed on an unjustified downsize. See {@link ClusterMember} admission gate.
+ * that cannot derive a view (no FRET, unit tests): with no derived view AND no asserted
+ * {@link ClusterConsensusConfig.assumedClusterSize} the gate preserves legacy approve behavior, but an
+ * asserted size still lets the gate fail closed on an unjustified downsize. See {@link ClusterMember}
+ * admission gate.
  */
 export type DeriveExpectedClusterCallback = (blockId: BlockId) => Promise<ExpectedClusterView>;
 
@@ -232,8 +233,8 @@ export class ClusterMember implements ICluster {
 	private readonly minAbsoluteClusterSize: number;
 	private readonly clusterSizeTolerance: number;
 	private readonly membershipAdmissionFraction: number;
-	/** Configured full cluster size, or undefined when unknown (then the gate cannot judge a downsize). */
-	private readonly configuredClusterSize: number | undefined;
+	/** Operator-asserted smallest genuine cohort size, or undefined when unknown. */
+	private readonly assumedClusterSize: number | undefined;
 	private readonly allowUnvalidatedSmallCluster: boolean;
 
 	constructor(
@@ -259,8 +260,17 @@ export class ClusterMember implements ICluster {
 		this.minAbsoluteClusterSize = consensusConfig?.minAbsoluteClusterSize ?? 3;
 		this.clusterSizeTolerance = consensusConfig?.clusterSizeTolerance ?? 0.5;
 		this.membershipAdmissionFraction = consensusConfig?.membershipAdmissionFraction ?? 0.75;
-		this.configuredClusterSize = consensusConfig?.clusterSize;
+		this.assumedClusterSize = consensusConfig?.assumedClusterSize;
 		this.allowUnvalidatedSmallCluster = consensusConfig?.allowUnvalidatedSmallCluster ?? false;
+		// State the resolved gate parameters once, so an operator diagnosing a membership rejection can see
+		// what this node actually resolved. A fact, not a warning: `assumedClusterSize < clusterSize` is the
+		// normal default state, so warning on it would fire for every node and be ignored.
+		log('cluster-member:admission-config', {
+			assumedClusterSize: this.assumedClusterSize,
+			minAbsoluteClusterSize: this.minAbsoluteClusterSize,
+			membershipAdmissionFraction: this.membershipAdmissionFraction,
+			allowUnvalidatedSmallCluster: this.allowUnvalidatedSmallCluster
+		});
 		// Periodically clean up expired transactions (.unref() so tests/short-lived processes can exit)
 		this.expirationInterval = setInterval(() => this.queueExpiredTransactions(), 60000);
 		this.expirationInterval.unref();
@@ -858,12 +868,18 @@ export class ClusterMember implements ICluster {
 	 *     of a peer or two is absorbed, a wholesale-disjoint or half-size set is not.
 	 *
 	 * **Fail-closed posture.** When the member cannot confidently derive `E` (no capability, low FRET
-	 * confidence — exactly what a partition induces), it must refuse any *downsizing* decision: a
-	 * below-full-size `D` is rejected against the configured full `clusterSize`. With NEITHER a confident
-	 * view NOR a configured full size the gate cannot judge a downsize at all, so it preserves the legacy
-	 * approve behavior (backward-compatible for nodes/tests with no derivation wired). `allowUnvalidatedSmallCluster`
-	 * is the explicit opt-in (single-node / local dev knowingly below the safe floor), matching the
-	 * coordinator's `validateSmallCluster` semantics.
+	 * confidence — exactly what a partition induces), it must refuse any *downsizing* decision — but it
+	 * needs a size reference to judge "downsize" against, and it may NOT borrow `clusterSize` for that:
+	 * `clusterSize` is the replication factor (what a cohort should aim for), not a claim about how many
+	 * peers exist, so a small deployment configured with the default 10 would refuse every write. The
+	 * fallback yardstick is instead {@link ClusterConsensusConfig.assumedClusterSize} — the operator's own
+	 * assertion of the smallest cohort this deployment can genuinely field — run through the SAME
+	 * {@link admissionFloor} as the confident path, so the fallback can never be stricter than the measured
+	 * path (it was: it demanded the full configured size, with no fraction and no slack for churn or a peer
+	 * not yet discovered). With NEITHER a confident view NOR an asserted size the gate cannot judge a
+	 * downsize at all, so it preserves the legacy approve behavior (backward-compatible for nodes/tests with
+	 * no derivation wired). `allowUnvalidatedSmallCluster` is the explicit opt-in (single-node / local dev
+	 * knowingly below the safe floor), matching the coordinator's `validateSmallCluster` semantics.
 	 */
 	private async admitMembership(record: ClusterRecord): Promise<{ admit: boolean; reason?: string }> {
 		const ourId = this.peerId.toString();
@@ -894,30 +910,42 @@ export class ClusterMember implements ICluster {
 			&& derivedSize > 0;
 
 		if (!confident) {
-			// Fail closed for downsizing under low/absent confidence. A full-size (or larger) declared set is
-			// still admitted — there is nothing to shrink. Without a configured full-size reference we cannot
-			// tell a downsize from a legitimate small cluster, so we preserve legacy approve behavior.
-			if (this.configuredClusterSize === undefined) {
+			// Fail closed for downsizing under low/absent confidence, measured against the operator's asserted
+			// cohort size rather than the replication factor. With no asserted size the gate cannot tell a
+			// downsize from a legitimately small cluster at all, so it preserves legacy approve behavior.
+			if (this.assumedClusterSize === undefined) {
 				return { admit: true };
 			}
-			if (declared.length >= this.configuredClusterSize) {
+			const floor = this.admissionFloor(this.assumedClusterSize);
+			if (declared.length >= floor) {
 				return { admit: true };
 			}
 			log('cluster-member:admission-reject', {
 				messageHash: record.messageHash,
 				reason: 'low-confidence-downsize',
 				declaredSize: declared.length,
-				configuredClusterSize: this.configuredClusterSize,
+				floor,
+				assumedClusterSize: this.assumedClusterSize,
 				confidence: derived?.confidence
 			});
-			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:low-confidence-downsize` };
+			// The numbers ride along in the reason: this rejection is caused by *local* configuration, and
+			// without them a coordinator (or an operator reading a dispute record) has no hint which knob did it.
+			// NOTE: two honest members with different local config now emit *different* reason strings for the
+			// same record. Nothing compares reasons across peers today (`disputeEvidence.rejectReasons` is a
+			// per-peer map, and the signed payload hashes the string each vote carries); if anything ever groups
+			// or dedupes dispute reasons by string equality, group on the `membership-not-admitted:<variant>`
+			// prefix, not the whole string.
+			return {
+				admit: false,
+				reason: `${MEMBERSHIP_NOT_ADMITTED}:low-confidence-downsize (declared=${declared.length}, floor=${floor}, assumedClusterSize=${this.assumedClusterSize})`
+			};
 		}
 
 		const expected = Object.keys(derived!.peers ?? {});
 		const kEst = expected.length;
 
 		// Predicate 2: floor derived from the member's OWN confident estimate.
-		const floor = Math.max(this.minAbsoluteClusterSize, Math.ceil(this.membershipAdmissionFraction * kEst));
+		const floor = this.admissionFloor(kEst);
 		if (declared.length < floor) {
 			log('cluster-member:admission-reject', {
 				messageHash: record.messageHash,
@@ -926,7 +954,10 @@ export class ClusterMember implements ICluster {
 				floor,
 				kEst
 			});
-			return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:below-floor` };
+			return {
+				admit: false,
+				reason: `${MEMBERSHIP_NOT_ADMITTED}:below-floor (declared=${declared.length}, floor=${floor}, kEst=${kEst})`
+			};
 		}
 
 		// Predicate 3: consistency with the derived view within tolerance.
@@ -947,6 +978,27 @@ export class ClusterMember implements ICluster {
 		return { admit: true };
 	}
 
+	/**
+	 * The smallest declared peer set admissible against a cohort-size reference `k`, whether `k` is
+	 * measured (the confident path's `kEst`) or asserted (`assumedClusterSize`). One function so the
+	 * fallback can never be stricter than the measured path — which it was, demanding the full configured
+	 * size with no fraction and no slack. Clamped at `minAbsoluteClusterSize`, so a degenerate `k` of 0, 1
+	 * or negative yields the absolute floor rather than a floor that admits everything. A non-finite scaled
+	 * size (a `NaN` or `Infinity` config value) is likewise treated as no usable reference rather than
+	 * propagating: an unguarded `NaN` floor fails EVERY comparison, which would silently make the node
+	 * reject every unconfident write.
+	 *
+	 * 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.
+	 */
+	private admissionFloor(k: number): number {
+		const scaled = Math.ceil(this.membershipAdmissionFraction * k);
+		return Math.max(this.minAbsoluteClusterSize, Number.isFinite(scaled) ? scaled : 0);
+	}
+
 	/**
 	 * Derive this member's own view of the record's block cluster via the injected capability, or
 	 * `undefined` when it cannot (no capability, no coordinating block id, or a derivation error — all of
@@ -1000,6 +1052,20 @@ export class ClusterMember implements ICluster {
 					const blockResults = await this.storageRepo.get({ blockIds });
 					for (const blockId of blockIds) {
 						const blockResult = blockResults[blockId];
+						if (blockResult?.unavailable !== undefined) {
+							// This member cannot establish the block's revision, so it cannot judge
+							// staleness. Vote reject rather than approve on an answer it knows is a
+							// guess — approving would let a stale pend reach consensus on the strength
+							// of a member that could not check it. (Before StorageRepo caught
+							// materialization faults per block, this read threw out of the promise
+							// handler; rejecting keeps the fail-closed posture with a signed reason.)
+							log('cluster-member:validation-block-unavailable', {
+								messageHash: record.messageHash,
+								blockId,
+								reason: blockResult.unavailable
+							});
+							return { valid: false, reason: `block ${blockId} unavailable (${blockResult.unavailable}): cannot verify revision` };
+						}
 						const latestRev = blockResult?.state?.latest?.rev;
 						if (latestRev !== undefined && latestRev >= pendRequest.rev) {
 							log('cluster-member:validation-stale-revision', {
@@ -1395,7 +1461,12 @@ export class ClusterMember implements ICluster {
 	private async reconcileOneBlock(messageHash: string, blockId: BlockId, committed: ActionRev, cohortPeerIds: string[]): Promise<void> {
 		try {
 			await this.withReconcileTimeout(this.reconcileBlock!(blockId, committed, cohortPeerIds), blockId);
-			log('cluster-member:consensus-commit-reconciled', { messageHash, blockId, rev: committed.rev });
+			// "attempted", not "reconciled": the callback returns void, and a quorum decline is a
+			// normal, non-throwing outcome — so reaching here means the pass ran to completion, NOT
+			// that anything was restored. `reconcile:restored` (reconcile-block.ts) is the line that
+			// says the bytes actually landed; `reconcile:no-rev-quorum` / `reconcile:no-content-quorum`
+			// say they did not.
+			log('cluster-member:consensus-commit-reconcile-attempted', { messageHash, blockId, rev: committed.rev });
 		} catch (err) {
 			log('cluster-member:consensus-commit-reconcile-failed', {
 				messageHash,

package/src/cluster/quorum-restore.ts

@@ -63,6 +63,31 @@ export function quorumSize(
 	return Math.max(floor, Math.floor(simpleMajorityThreshold * responderCount));
 }
 
+/**
+ * The `corroboratorCapacity` to hand {@link quorumSize}: how many peers other than the asking node
+ * could answer for a block at all, given `cohortPeerCount` peers currently visible (self already
+ * excluded) and `repairCorroborationClusterSize` — the cohort size this deployment is measured
+ * against, resolved by `resolveClusterPolicy` in `cluster/cluster-policy.ts`.
+ *
+ * Deliberately the MAX of the two: the corroboration floor may be relaxed only for a cohort that is
+ * *genuinely* small, never for one that merely looks small. Cohort views are unauthenticated — the
+ * read path takes them from `IKeyNetwork.findCluster`, the commit path from a coordinator-declared
+ * peer set — so a partition, a self-shrunk record, or an attacker with routing influence could
+ * otherwise talk the requirement down to a single voter. Measuring against the resolved size keeps a
+ * shrunken view out of the relaxed branch.
+ *
+ * An unconfigured node resolves this to its `clusterSize` (default 10), so the floor of two binds and
+ * a shrunken view gains nothing. The escape hatch for a real two-node deployment is one explicit
+ * operator declaration — `clusterPolicy.assumedClusterSize: 2`, which does NOT also drop the
+ * replication factor, or an honest `clusterSize: 2`.
+ *
+ * Shared by both restoration paths so the two can never drift apart on the rule that decides how
+ * much trust a lone peer gets.
+ */
+export function corroboratorCapacity(cohortPeerCount: number, repairCorroborationClusterSize: number): number {
+	return Math.max(cohortPeerCount, repairCorroborationClusterSize - 1);
+}
+
 /**
  * Select the highest revision corroborated by a quorum of distinct peers.
  *
@@ -80,7 +105,7 @@ export function quorumSize(
  * all — lets a genuinely tiny cohort still converge: a cohort with exactly one other peer
  * cannot produce two corroborators, so requiring two makes divergence permanent rather
  * than making it safe. Pass a capacity that a shrunken view of the network cannot talk
- * down (see `CoordinatorRepo.corroboratorCapacity`), or omit it to keep the floor at two.
+ * down (see {@link corroboratorCapacity}), or omit it to keep the floor at two.
  *
  * Returns `undefined` when nothing is corroborated — an uncorroborated claim
  * must never drive restoration.
@@ -165,8 +190,8 @@ export interface BlockHashCandidate {
  * one the sole peer's content is therefore taken on its word. That extends no trust the cohort had
  * not already extended: the same peer's `(rev, actionId)` claim is equally uncorroborable at that
  * size, and a two-member cohort has no honest majority to appeal to. Pass a capacity a shrunken
- * view of the network cannot talk down (see `CoordinatorRepo.corroboratorCapacity` and
- * `reconcile-block.ts`), so only a cohort that is *genuinely* that small reaches this branch.
+ * view of the network cannot talk down (see {@link corroboratorCapacity}), so only a cohort that is
+ * *genuinely* that small reaches this branch.
  */
 export function selectQuorumBlock(
 	candidates: BlockHashCandidate[],

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,
+	selectQuorumRev, selectQuorumBlock, canonicalBlockHash, corroboratorCapacity,
 	type RevClaim, type BlockHashCandidate, type QuorumRev
 } from "./quorum-restore.js";
 import { createLogger } from '../logger.js';
@@ -38,23 +38,32 @@ export interface ReconcileBlockDeps {
 	saveReplicatedBlock: (blockId: BlockId, block: IBlock, source: ActionRev) => Promise<void>;
 	/** Proportional corroboration threshold; the cohort's `simpleMajorityThreshold`. */
 	simpleMajorityThreshold: number;
-	/** Configured full cluster size — the floor for {@link corroboratorCapacity}. */
-	clusterSize: number;
+	/**
+	 * Yardstick the corroboration floor is measured against — the floor for
+	 * {@link corroboratorCapacity}. Required, not optional: unlike the membership admission gate there
+	 * is no "unknown" handling here, so a caller that cannot state an asserted cohort size should pass
+	 * its configured `clusterSize` (the strict direction) rather than a small placeholder. The failure
+	 * mode of overstating it is a block that stays unrepaired — degraded, not dead; of understating it,
+	 * a shrunken cohort view that can relax the floor to a single voter. `resolveClusterPolicy`
+	 * (`cluster/cluster-policy.ts`) resolves it for a real node and defaults it to `clusterSize`.
+	 */
+	repairCorroborationClusterSize: number;
 	/** Best-effort misbehavior reporting; a throwing implementation is swallowed. */
 	reputation?: Pick<IPeerReputation, 'reportPeer'>;
 }
 
 /**
- * How many peers other than this node could answer for the block at all. Mirrors
- * `CoordinatorRepo.corroboratorCapacity` exactly, and for the same reason: the corroboration
- * floor may be relaxed only for a cohort that is *genuinely* small, never for one that merely
- * looks small. `cohortPeerIds` come from the (untrusted) coordinator-declared peer set, so a
- * self-shrunk record could otherwise talk the requirement down to a single voter; taking the MAX
- * against the configured `clusterSize` keeps that shrunken view out of the relaxed branch. The
- * escape hatch for a real two-node deployment is to configure `clusterSize: 2`.
+ * Highest revision an archive covers. Keys arrive as strings off the wire from an untrusted peer,
+ * so a non-numeric one is skipped rather than poisoning the maximum with `NaN`; folding instead of
+ * `Math.max(...keys)` also keeps a wide archive off the argument-count limit.
  */
-function corroboratorCapacity(targets: string[], clusterSize: number): number {
-	return Math.max(targets.length, clusterSize - 1);
+function maxRevision(revisions: BlockArchive['revisions']): number | undefined {
+	let max: number | undefined;
+	for (const key of Object.keys(revisions)) {
+		const rev = Number(key);
+		if (Number.isFinite(rev) && (max === undefined || rev > max)) max = rev;
+	}
+	return max;
 }
 
 /**
@@ -64,16 +73,40 @@ function corroboratorCapacity(targets: string[], clusterSize: number): number {
  */
 function toCandidate(peerId: string, archive: BlockArchive | undefined, committedRev: number): ReconcileCandidate | undefined {
 	if (!archive) return undefined;
-	const revs = Object.keys(archive.revisions).map(Number);
-	if (revs.length === 0) return undefined;
-	const maxRev = Math.max(...revs);
-	if (maxRev < committedRev) return undefined;
+	const maxRev = maxRevision(archive.revisions);
+	if (maxRev === undefined || maxRev < committedRev) return undefined;
 	const data = archive.revisions[maxRev];
 	if (!data?.action) return undefined;
 	return { peerId, rev: maxRev, actionId: data.action.actionId, block: data.block };
 }
 
-/** Hash the block bytes of every candidate that both corroborates `selected` and actually carried content. */
+/**
+ * One peer's answer, isolated. `fetchArchive` is contracted to answer `undefined` for an
+ * unreachable peer, but a raw `Promise.all` over the cohort would let a single rejecting fetch
+ * discard the answers every other peer already gave — turning a heal the cohort could complete
+ * into a decline. One peer's failure costs only that peer's vote.
+ */
+async function fetchCandidate(
+	deps: ReconcileBlockDeps,
+	peerId: string,
+	blockId: BlockId,
+	committedRev: number
+): Promise<ReconcileCandidate | undefined> {
+	try {
+		return toCandidate(peerId, await deps.fetchArchive(peerId, blockId), committedRev);
+	} catch (err) {
+		log('reconcile:fetch-error', { blockId, peerId, error: (err as Error).message });
+		return undefined;
+	}
+}
+
+/**
+ * Hash the block bytes of every candidate that both corroborates `selected` and actually carried content.
+ *
+ * NOTE: this canonical-JSON-serializes and sha256s every carrier's whole block on every reconcile.
+ * Negligible at today's cohort widths and block sizes; if blocks grow large or cohorts wide enough
+ * for this to show up on a commit-path profile, hash incrementally at receive time instead.
+ */
 async function hashCarriers(candidates: ReconcileCandidate[], selected: QuorumRev): Promise<BlockHashCandidate[]> {
 	const carriers = candidates.filter(c => c.rev === selected.rev && c.actionId === selected.actionId && c.block);
 	return await Promise.all(
@@ -130,10 +163,10 @@ export function createReconcileBlock(deps: ReconcileBlockDeps): ReconcileBlockCa
 		if (targets.length === 0) return;
 
 		const fetched = await Promise.all(
-			targets.map(async peerId => toCandidate(peerId, await deps.fetchArchive(peerId, blockId), committed.rev))
+			targets.map(peerId => fetchCandidate(deps, peerId, blockId, committed.rev))
 		);
 		const candidates = fetched.filter((c): c is ReconcileCandidate => c !== undefined);
-		const capacity = corroboratorCapacity(targets, deps.clusterSize);
+		const capacity = corroboratorCapacity(targets.length, deps.repairCorroborationClusterSize);
 
 		const revClaims: RevClaim[] = candidates.map(({ peerId, rev, actionId }) => ({ peerId, rev, actionId }));
 		const selected = selectQuorumRev(revClaims, deps.simpleMajorityThreshold, capacity);

package/src/cluster/spread-on-churn.ts

@@ -221,6 +221,14 @@ export class SpreadOnChurnMonitor implements Startable {
 			// Read block data from local storage
 			const result = await this.deps.repo.get({ blockIds: [blockId] })
 			const blockResult = result[blockId]
+			if (blockResult?.unavailable !== undefined) {
+				// The repo could not work out whether it still holds this block (unmaterializable
+				// history / failed restore). Untracking on that answer would silently drop the block
+				// from the spread set on a guess, and only a later re-commit would put it back — so
+				// keep it tracked and let the next sweep (or a heal) settle it.
+				log('unavailable block=%s reason=%s (keeping tracked)', blockId, blockResult.unavailable)
+				continue
+			}
 			if (!blockResult?.block) {
 				// The block has left local storage. No deletion event exists today to evict it
 				// from the tracked set, so prune here. Deleting the current element of a Set mid

package/src/inbound-authorization.ts

@@ -32,6 +32,12 @@
  * - **Cost**: the predicate sits in the hot path of every inbound stream, ahead of the work
  *   that stream would do. Embedders are expected to make it cheap — an in-memory set lookup —
  *   and to memoize anything that would otherwise hit storage or the network per stream.
+ *
+ * NOTE: denial is stateless and unthrottled — a denied peer may reopen streams as fast as
+ * libp2p's per-connection `maxInboundStreams` allows, and nothing here records the denial. That
+ * is fine while the predicate is an in-memory lookup. If a denied peer ever shows up as load, the
+ * fix is upstream of this module, not inside it: feed denials into `PeerReputationService`, or
+ * refuse the peer at the connection level with `NodeOptions.connectionGater`.
  */
 
 /**

package/src/libp2p-key-network.ts

@@ -299,7 +299,25 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 		return { allow: true, reason: 'extended-isolation', warn: true };
 	}
 
+	/**
+	 * Memoize the coordinator for a key. A pick of SELF is deliberately ignored — the
+	 * cache is consulted ahead of every selection tier, so a self entry would keep the
+	 * key routed at our own (possibly stale) replica for the full TTL long after a
+	 * better-placed peer became reachable, and would return self without re-consulting
+	 * {@link shouldAllowSelfCoordination}, letting a partitioned node silently serve its
+	 * own data. Self needs no memoizing anyway: every tier that can select it re-derives
+	 * it from a local lookup with no dial and no retry sleep.
+	 *
+	 * The gate lives here rather than at each call site because most writers are OUTSIDE
+	 * this class — `recordCoordinator` is public and is fed self-valued picks by
+	 * `NetworkTransactor` (it writes back whatever `findCoordinator` returned, including
+	 * self) and by `RepoClient`/`ClusterClient` on redirect responses.
+	 */
 	public recordCoordinator(key: Uint8Array, peerId: PeerId, ttlMs = 30 * 60 * 1000): void {
+		if (peerId.toString() === this.libp2p.peerId.toString()) {
+			this.log('coordinator-cache:self-write-ignored key=%s', this.toCacheKey(key).substring(0, 12))
+			return
+		}
 		const k = this.toCacheKey(key)
 		const now = Date.now()
 		for (const [ck, entry] of this.coordinatorCache) {
@@ -417,11 +435,39 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 				this.log('findCoordinator:fret-neighbors key=%s candidates=%d', keyStr, ids.length)
 				if (verbose) this.log('findCoordinator:fret-candidates key=%s ids=%o connected=%o', keyStr, ids, Array.from(connectedSet))
 
-				// Filter to only connected FRET neighbors, excluding banned peers
+				// Filter to only connected FRET neighbors, excluding banned peers. Self is
+				// never "connected" to itself, so it is admitted by the explicit self clause
+				// below — but ONLY when the self-coordination guard allows it, otherwise a
+				// node whose FRET neighborhood contains self (essentially always on a small or
+				// forming network) would bypass the guard and the last-resort tier's
+				// SELF_COORDINATION_BLOCKED would never fire. On refusal self is merely DROPPED
+				// from the candidate list, so the connected-peer fallback below still gets its
+				// chance at a good remote peer; only if that also comes up empty does the
+				// last-resort tier raise the accurate error.
+				const selfStr = this.libp2p.peerId.toString()
+				let selfAllowedThisAttempt: boolean | undefined
+				// Memoized per ATTEMPT, and evaluated lazily so an all-remote neighborhood never
+				// pays detectPartition() / getNetworkSizeEstimate(). Re-evaluated on each attempt
+				// because a connection can land during the 500ms inter-attempt sleep and
+				// legitimately flip the answer — as filterByMembership re-reads the peerStore.
+				// NOTE: on a small network self is a neighbor of nearly every key, so this runs
+				// per findCoordinator call and self-coordinated keys are never cached to absorb
+				// it. Fine while detectPartition()/getNetworkSizeEstimate() stay local FRET
+				// table reads; if either ever grows a probe or other network round-trip, cache
+				// the decision with a short TTL on the instance instead of per attempt.
+				const isSelfAdmissible = (): boolean => {
+					if (selfAllowedThisAttempt === undefined) {
+						const decision = this.shouldAllowSelfCoordination()
+						selfAllowedThisAttempt = decision.allow
+						if (!decision.allow) {
+							this.log('findCoordinator:fret-self-dropped key=%s reason=%s attempt=%d', keyStr, decision.reason, attempt)
+						}
+					}
+					return selfAllowedThisAttempt
+				}
 				const connectedFretIds = ids
-					.filter(id => (connectedSet.has(id) || id === this.libp2p.peerId.toString())
-						&& !excludedSet.has(id)
-						&& !(this.reputation?.isBanned(id)))
+					.filter(id => !excludedSet.has(id) && !(this.reputation?.isBanned(id)))
+					.filter(id => connectedSet.has(id) || (id === selfStr && isSelfAdmissible()))
 					.sort((a, b) => (this.reputation?.getScore(a) ?? 0) - (this.reputation?.getScore(b) ?? 0))
 				this.log('findCoordinator:fret-connected key=%s count=%d peers=%o', keyStr, connectedFretIds.length, connectedFretIds.map(s => s.substring(0, 12)))
 
@@ -438,6 +484,8 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 				const pick = ranked[0]
 				if (pick) {
 					const pid = peerIdFromString(pick)
+					// A self pick is a no-op here — recordCoordinator ignores self-valued
+					// writes (see its doc comment), matching the last-resort self tier below.
 					this.recordCoordinator(key, pid)
 					this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'fret')
 					return pid
@@ -451,6 +499,8 @@ export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
 			// `unknown` peer is never picked). Note this candidate set is built from
 			// connected REMOTE peers and never includes self, so when no serving peer is
 			// present selection falls through to the last-resort self-coordination block.
+			// Being remote-only, this tier needs no self-coordination guard check, unlike the
+			// FRET tier above.
 			const connectedCandidates = connected
 				.filter(p => !excludedSet.has(p.toString()) && !(this.reputation?.isBanned(p.toString())))
 				.sort((a, b) => (this.reputation?.getScore(a.toString()) ?? 0) - (this.reputation?.getScore(b.toString()) ?? 0))

package/src/libp2p-node-base.ts

@@ -21,6 +21,7 @@ import type { IRawStorage } from './storage/i-raw-storage.js';
 import { seedOwnedBlocksFromStorage } from './owned-block-seed.js';
 import { clusterMember, type ReconcileBlockCallback, type CommitCertificateSink, type DeriveExpectedClusterCallback } from './cluster/cluster-repo.js';
 import { createReconcileBlock } from './cluster/reconcile-block.js';
+import { resolveClusterPolicy, type ClusterPolicyOptions } from './cluster/cluster-policy.js';
 import { createCommitCertStore, makeClusterCommitCertExtractor, type CommitCertStore } from './cluster/commit-cert.js';
 import { coordinatorRepo } from './repo/coordinator-repo.js';
 import { Libp2pKeyPeerNetwork, type NetworkMode, type NetworkStatePersistence } from './libp2p-key-network.js';
@@ -70,7 +71,6 @@ import {
 	reactivityNodePolicy,
 	createTierAddressing,
 	createRingHash,
-	DEFAULT_SUPER_MAJORITY_THRESHOLD,
 	Tier,
 	b64urlToBytes,
 	bytesToB64url,
@@ -135,7 +135,12 @@ const wiringLog = createLogger('node-wiring');
 /** Factory function or instance for creating raw storage */
 export type RawStorageProvider = IRawStorage | (() => IRawStorage);
 
-export type NodeOptions = {
+/**
+ * `ClusterPolicyOptions` is intersected in, not restated: `resolveClusterPolicy` consumes those
+ * fields structurally, so a second copy of the shape here would let a newly added knob compile and
+ * be silently ignored. See `cluster/cluster-policy.ts` for what each one resolves to.
+ */
+export type NodeOptions = ClusterPolicyOptions & {
 	/**
 	 * Network port. Only used by the default `listenAddrs` fallback.
 	 * For non-TCP transports (e.g. WebSockets), set `listenAddrs` explicitly.
@@ -174,29 +179,20 @@ export type NodeOptions = {
 	relayServerInit?: CircuitRelayServerInit;
 	/** Storage provider - either an IRawStorage instance or a factory function. Defaults to MemoryRawStorage if not provided. */
 	storage?: RawStorageProvider;
-	/**
-	 * Desired cluster size per key (default 10). Beyond sizing the cohort, this is the
-	 * node's declaration of how many peers *should* exist to corroborate a claim: the
-	 * read-repair corroboration floor is measured against it, so a genuine two-node
-	 * deployment must set `clusterSize: 2` for its members to be able to repair each
-	 * other (see `CoordinatorRepo.corroboratorCapacity`).
-	 */
-	clusterSize?: number;
-	clusterPolicy?: {
-		allowDownsize?: boolean;
-		sizeTolerance?: number; // acceptable relative difference (e.g. 0.5 = +/-50%)
-		superMajorityThreshold?: number; // fraction of peers needed for super-majority (default: DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75)
-		/**
-		 * Opt in to transacting below the safe cluster-size floor when FRET has no confident
-		 * network-size estimate — the membership-admission and coordinator small-cluster gates
-		 * both fail closed without it. Default false. Turn on only for single-node / local dev
-		 * meshes that knowingly run undersized.
-		 */
-		allowUnvalidatedSmallCluster?: boolean;
-	};
-
 	/** Override libp2p listen multiaddrs. */
 	listenAddrs?: string[];
+	/**
+	 * Multiaddrs to advertise INSTEAD OF the listen addrs. For a node behind a NAT / reverse proxy /
+	 * DNS front that binds one address but is reachable at another. When non-empty these REPLACE the
+	 * advertised set entirely — observed/relayed addresses and {@link NodeOptions.appendAnnounceAddrs}
+	 * are all dropped from it. An empty array means "unset" (libp2p's own semantics).
+	 */
+	announceAddrs?: string[];
+	/**
+	 * Multiaddrs to advertise IN ADDITION TO the listen addrs. Ignored while
+	 * {@link NodeOptions.announceAddrs} is non-empty.
+	 */
+	appendAnnounceAddrs?: string[];
 	/** Override libp2p transports. */
 	transports?: Libp2pTransports;
 
@@ -305,9 +301,10 @@ export type NodeOptions = {
 	 * dialing peer's `PeerId.toString()`. See {@link AuthorizeInboundStream} and
 	 * `docs/internals.md` § Inbound Stream Authorization.
 	 *
-	 * NOTE: this covers the four database protocols only. The reactivity, matchmaking,
+	 * NOTE: this covers the four database protocols only. The dispute, reactivity, matchmaking,
 	 * cohort-topic and libp2p built-in (identify/ping/…) protocols this node also registers are
-	 * NOT gated by it.
+	 * NOT gated by it. To refuse a peer at the connection level instead — every protocol at once,
+	 * including identify — use {@link NodeOptions.connectionGater}.
 	 */
 	authorizeInboundStream?: AuthorizeInboundStream;
 
@@ -464,8 +461,13 @@ export async function createLibp2pNodeBase(
 	const libp2pOptions: Libp2pInit = {
 		start: false,
 		privateKey: nodePrivateKey,
+		// NOTE: libp2p's `AddressManagerInit` also carries `noAnnounce` and `announceFilter`; neither is
+		// exposed on `NodeOptions`. Add them here the same way if a deployment ever needs to suppress a
+		// specific advertised address rather than replace the whole set.
 		addresses: {
-			listen: listenAddrs
+			listen: listenAddrs,
+			...(options.announceAddrs ? { announce: options.announceAddrs } : {}),
+			...(options.appendAnnounceAddrs ? { appendAnnounce: options.appendAnnounceAddrs } : {})
 		},
 		connectionManager: {
 			// `autoDial`, `minConnections`, and `dialQueue` were stale libp2p option keys silently
@@ -603,7 +605,9 @@ export async function createLibp2pNodeBase(
 				});
 				return serviceFactory({
 					registrar: components.registrar,
-					repo: storageRepo
+					repo: storageRepo,
+					// So this service's authorization denials reach the same error sink as the other three.
+					logger: components.logger
 				});
 			},
 
@@ -696,21 +700,11 @@ export async function createLibp2pNodeBase(
 	const partitionDetector = new PartitionDetector();
 	const fretSvc = (node as any).services?.fret as FretService | undefined;
 
-	const consensusConfig = {
-		superMajorityThreshold: options.clusterPolicy?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD,
-		simpleMajorityThreshold: 0.51,
-		minAbsoluteClusterSize: 2,
-		allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
-		clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5,
-		// Fail closed by default (an undersized cluster with no confident network-size estimate is
-		// rejected); embedders running knowingly-small meshes opt in through clusterPolicy.
-		allowUnvalidatedSmallCluster: options.clusterPolicy?.allowUnvalidatedSmallCluster ?? false,
-		partitionDetectionWindow: 60000,
-		// Configured full cluster size — the member's own reference for "full size" in the membership
-		// admission gate (a below-full-size declared set under low FRET confidence is refused as a possible
-		// self-shrink). Matches the size threaded into the coordinator below.
-		clusterSize: options.clusterSize ?? 10
-	};
+	// Every cluster-policy default lives in `cluster/cluster-policy.ts` — including WHY the admission
+	// gate and the repair corroboration floor resolve the one operator field
+	// (`clusterPolicy.assumedClusterSize`) to different values when it is absent. Extracted so those
+	// defaults can be asserted without booting a node.
+	const consensusConfig = resolveClusterPolicy(options);
 
 	// Fetch a block archive from one cohort peer over the sync protocol, bounded by a
 	// per-peer timeout so an unreachable peer can't stall reconciliation. Mirrors the
@@ -741,12 +735,17 @@ export async function createLibp2pNodeBase(
 	// (cohort drift, or a refused `missing-base-revision` commit). See `reconcile-block.ts` for
 	// the corroboration rules — in particular why both quorums are capped by how many peers
 	// could answer at all, which is what lets a genuinely two-node cohort heal.
+	// NOTE: this and the CoordinatorRepo below must cap against the SAME
+	// repairCorroborationClusterSize, or the two restoration paths disagree about how much trust a
+	// lone peer gets. Safe today because both read the one `resolveClusterPolicy` result above; if
+	// either ever resolves its own value, add a fail-fast coupling check like
+	// `assertSuperMajorityCoupling` rather than relying on proximity.
 	const reconcileBlock: ReconcileBlockCallback = createReconcileBlock({
 		selfPeerId: node.peerId.toString(),
 		fetchArchive: fetchArchiveFromPeer,
 		saveReplicatedBlock: (blockId, block, source) => storageRepo.saveReplicatedBlock(blockId, block, source),
 		simpleMajorityThreshold: consensusConfig.simpleMajorityThreshold,
-		clusterSize: consensusConfig.clusterSize,
+		repairCorroborationClusterSize: consensusConfig.repairCorroborationClusterSize,
 		reputation
 	});