@optimystic/db-core 1.0.0-beta.1 → 1.0.0-beta.3

package/src/cluster/structs.ts

@@ -1,247 +1,277 @@
-import type { RepoMessage } from "../network/repo-protocol.js";
-import type { PendResult } from "../network/struct.js";
-
-/**
- * One member's vote on a cluster transaction, in either the promise or the commit map.
- *
- * A discriminated union rather than one shape with optional fields, so each vote kind carries
- * exactly its own payload: a `conflict` without its `conflictWith` (or a stray `rejectReason` on an
- * `approve`) does not typecheck. Every variant's extra field is folded into the signed payload
- * ({@link clusterVoteSigningPayload}), so none of them can be altered in transit.
- */
-export type Signature =
-	| { type: 'approve'; signature: string }
-	| { type: 'reject'; signature: string; rejectReason?: string }
-	/**
-	 * This member refuses the transaction *for now*: it holds a conflicting transaction that won
-	 * the deterministic race (`resolveRace`). Retryable — NOT a validity judgement, and never
-	 * counted toward the permanent-rejection threshold. `conflictWith` is the winning
-	 * transaction's messageHash: structured, signed, and readable without parsing prose.
-	 */
-	| { type: 'conflict'; signature: string; conflictWith: string };
-
-/**
- * The exact bytes a vote signature covers: `<hash>:<type>[:<extra>]`, where `extra` is the variant's
- * own payload — a reject's `rejectReason`, a conflict's `conflictWith`, nothing for an approve.
- * Folding the extra in is what makes it integrity-protected in transit rather than free-floating
- * prose.
- *
- * Producers and verifiers must both build the preimage here. It lives beside {@link Signature}
- * rather than in either consumer because a second copy that forgets a variant does not fail loudly:
- * it reports an honest vote as an invalid signature. (The dispute path once carried such a copy.)
- *
- * "Cluster" in the name distinguishes these consensus votes from the dispute subsystem's
- * arbitration votes, which have their own unrelated preimage (`dispute/invalidation.ts`).
- */
-export function clusterVoteSigningPayload(hash: string, type: Signature['type'], extra?: string): Uint8Array {
-	return new TextEncoder().encode(hash + ':' + type + (extra ? ':' + extra : ''));
-}
-
-/** Verifier-side {@link clusterVoteSigningPayload}: reads each variant's signed extra off the vote itself. */
-export function clusterVoteVerificationPayload(hash: string, signature: Signature): Uint8Array {
-	switch (signature.type) {
-		case 'reject': return clusterVoteSigningPayload(hash, 'reject', signature.rejectReason);
-		case 'conflict': return clusterVoteSigningPayload(hash, 'conflict', signature.conflictWith);
-		default: return clusterVoteSigningPayload(hash, signature.type);
-	}
-}
-
-export type ClusterPeers = {
-	[id: string]: {
-		multiaddrs: string[];
-		/** Base64url-encoded public key (serialization-safe) */
-		publicKey: string;
-	};
-};
-
-/**
- * One member's own report of what its storage did with this transaction at consensus-apply time; see
- * {@link ClusterRecord.applyOutcomes} for the trust rules. Only the pend arm exists today — a commit
- * refusal is not reported this way, because a commit that reached commit-consensus is authoritative
- * (the coordinator's own retained verdict plus the commit-promise guard cover that tier instead).
- */
-export type MemberApplyOutcome = {
-	/** This member's storage refused the record's pend with a conflict-shaped result. */
-	pend?: PendResult;
-};
-
-export type ClusterRecord = {
-	messageHash: string;	// Serves as a unique identifier for the clustered transaction record
-	peers: ClusterPeers;
-	/**
-	 * Membership-binding version. Absent or `1` = legacy *unbound* record: the peer set is NOT covered by
-	 * any hash (pre-binding history and its stored commit certs verify byte-identically to before). `2` =
-	 * the sorted peer-id set (as {@link ClusterRecord.membershipDigest}) is folded into `messageHash`,
-	 * `promiseHash`, and `commitHash`, so two different peer sets yield two different `messageHash`es.
-	 * New coordinators always emit `2`. See `packages/db-core/src/cluster/membership.ts`.
-	 */
-	membershipVersion?: 1 | 2;
-	/** Membership digest of {@link ClusterRecord.peers}; present iff `membershipVersion === 2`. base64url. */
-	membershipDigest?: string;
-	/**
-	 * The transaction's operations and the block the coordinator selected the cohort by
-	 * ({@link RepoMessage.coordinatingBlockIds}). There is deliberately NO top-level copy of the
-	 * coordinating block ids on the record: `messageHash` covers `message` only, so a duplicate at
-	 * this level would be outside every hash and any relaying peer could rewrite it — and the
-	 * membership admission gate derives its own cohort view from exactly that id
-	 * (`ClusterMember.deriveExpectedClusterView`). One source of truth, inside the hash.
-	 */
-	message: RepoMessage;
-	promises: { [peerId: string]: Signature };
-	commits: { [peerId: string]: Signature };
-	/** Sender's recommended cluster size: min(estimated network size, configured cluster size) */
-	suggestedClusterSize?: number;
-	minRequiredSize?: number;
-	/** Sender's current network size estimate */
-	networkSizeHint?: number;
-	/** Confidence in the network size estimate (0-1) */
-	networkSizeConfidence?: number;
-	/**
-	 * What each member's OWN storage answered when it applied this record's operations at consensus,
-	 * keyed by peer id. Advisory and **unsigned** — no hash covers it — and deliberately so: it is
-	 * written by a member *after* the votes are cast, on the response it hands back, so no signed
-	 * payload could carry it without a further round trip.
-	 *
-	 * Members set only their own entry, and only for a *conflict-shaped* pend refusal (one carrying
-	 * `pending` or `missing`, per `isConflictFailure`) — the optimistic-concurrency verdict that a
-	 * rival holds the blocks or already took the revision. Successes and bare-reason faults are
-	 * omitted: a bare fault stays tolerated local divergence, mirroring the coordinator's own
-	 * local-verdict arm.
-	 *
-	 * Why unsigned is acceptable: a hostile entry can only *downgrade* a reported pend success into a
-	 * retryable conflict, which the writer answers by rebasing and trying again. The same member
-	 * could already force strictly worse outcomes with a signed reject or conflict vote, so this adds
-	 * no attack surface beyond retry pressure — and failing toward retry is the correct direction for
-	 * optimistic concurrency. Never treat an entry here as evidence of anything but "retry".
-	 *
-	 * Old peers never set it and old coordinators ignore it, so it is wire-compatible in both
-	 * directions.
-	 */
-	applyOutcomes?: { [peerId: string]: MemberApplyOutcome };
-	/** Transaction proceeded despite minority rejections */
-	disputed?: boolean;
-	/** Evidence of the dispute: which peers rejected and why */
-	disputeEvidence?: {
-		rejectingPeers: string[];
-		rejectReasons: { [peerId: string]: string };
-	};
-}
-
-/**
- * Single source of truth for the default super-majority threshold — the fraction of a cluster's peers
- * that must promise before a transaction may proceed. Every component that falls back to a default when
- * config is absent (cluster member, coordinator policy, node composition root) references THIS constant,
- * so a member cannot silently default to a different threshold than the coordinator that commits. Explicit
- * caller-supplied thresholds are unaffected; this only unifies the *absent-config* default.
- * 0.75 = 3/4: chosen because the coordinator (which actually commits) already used it and the type documents it.
- */
-export const DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75;
-
-export interface ClusterConsensusConfig {
-	/** Super-majority threshold for promises (default {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} = 0.75 = 3/4) */
-	superMajorityThreshold: number;
-	/** Simple majority threshold for commits (default 0.51 = >50%) */
-	simpleMajorityThreshold: number;
-	/** Minimum absolute cluster size (default 3) */
-	minAbsoluteClusterSize: number;
-	/** Allow cluster to operate below configured size (default false) */
-	allowClusterDownsize: boolean;
-	/** Tolerance for cluster size variance as fraction (default 0.5 = 50%) */
-	clusterSizeTolerance: number;
-	/**
-	 * Configured full cluster size — the replication factor / target cohort breadth. This is what the
-	 * coordinator aims for when selecting a cohort. It is NOT a statement about how many peers exist,
-	 * and nothing may use it as a security yardstick; see {@link ClusterConsensusConfig.assumedClusterSize}.
-	 * The coordinator supplies this as a required `clusterSize` via `ClusterConsensusConfig & { clusterSize: number }`.
-	 */
-	clusterSize?: number;
-	/**
-	 * The smallest cohort the operator asserts this deployment can genuinely field — typically
-	 * `min(clusterSize, number of nodes actually run)`. Read ONLY when a node cannot independently
-	 * measure a cohort (no derivation capability wired, or no confident network-size estimate), where
-	 * it stands in for the measured estimate in the membership admission floor.
-	 *
-	 * Undefined means "unknown": the admission gate then cannot tell a downsize from a legitimately
-	 * small cluster and preserves legacy approve behavior. Composition roots should supply a concrete
-	 * value; `libp2p-node-base` defaults it to `minAbsoluteClusterSize`.
-	 */
-	assumedClusterSize?: number;
-	/**
-	 * Fraction of the member's OWN confident cluster-size estimate a declared peer set must meet to be
-	 * admitted for voting (default 0.75). Below `⌈membershipAdmissionFraction · K_est⌉` a declared set is
-	 * treated as an unjustified self-shrink and the member declines to approve. Distinct from
-	 * {@link superMajorityThreshold} (the vote-counting threshold) — this gates *which set* may be voted on.
-	 */
-	membershipAdmissionFraction?: number;
-	/** Window for detecting partition in milliseconds (default 60000 = 1 min) */
-	partitionDetectionWindow: number;
-	/** Enable dispute escalation protocol (default false) */
-	disputeEnabled?: boolean;
-	/** Timeout for dispute arbitration in milliseconds (default 60000) */
-	disputeArbitrationTimeoutMs?: number;
-	/**
-	 * Hard horizon on an invalidation cascade: maximum number of recursive re-evaluation rounds
-	 * (dependency-graph depth) before the cascade stops and escalates the affected collection(s)
-	 * for operator full re-sync (default 32). Bounds unbounded automatic reversal.
-	 */
-	maxCascadeDepth?: number;
-	/**
-	 * Hard horizon on an invalidation cascade: maximum number of transactions (including the root)
-	 * the cascade may invalidate before it stops and escalates for operator full re-sync
-	 * (default 1000). On overflow the already-applied invalidations stand; the remainder is flagged,
-	 * never silently dropped.
-	 */
-	maxCascadeTransactions?: number;
-	/** Initial scheduled-retry interval for failed commit broadcasts, ms (default 250) */
-	commitBroadcastRetryInitialMs?: number;
-	/** Backoff factor for commit-broadcast scheduled retries (default 2) */
-	commitBroadcastRetryBackoffFactor?: number;
-	/** Max scheduled-retry interval, ms (default 8000) */
-	commitBroadcastRetryMaxIntervalMs?: number;
-	/** Max scheduled retry attempts before giving up (default 5) */
-	commitBroadcastRetryMaxAttempts?: number;
-	/** Immediate in-line retries per failed peer inside the broadcast (default 1) */
-	commitBroadcastImmediateRetries?: number;
-	/**
-	 * Immediate in-line retries per peer while collecting promises (default 1).
-	 * The promise phase rides the same libp2p stream the commit broadcast does;
-	 * a circuit-relay ("limited") connection can reset that stream once a
-	 * per-circuit cap is hit, surfacing to the coordinator as a StreamResetError.
-	 * Unlike the commit broadcast there is no follow-up scheduled retry, so a
-	 * single reset here would otherwise drop the peer and sink super-majority.
-	 */
-	promiseImmediateRetries?: number;
-	/** Read-repair behavior: 'off' (only fetch on missing — legacy), 'lazy' (fetch when local age > window), 'paranoid' (always verify against cluster on read). Default 'lazy'. */
-	readRepairMode?: 'off' | 'lazy' | 'paranoid';
-	/** For 'lazy' mode: read-repair triggers when (now - localEntry.lastSeenCommitMs) > this. Default 10000. */
-	readRepairWindowMs?: number;
-	/** Per-read probability of triggering read-repair in 'lazy' mode even within the window (0..1). Default 0 (no random check). */
-	readRepairSampleRate?: number;
-	/**
-	 * When FRET has no confident network-size estimate, allow an undersized cluster
-	 * (peerCount < minAbsoluteClusterSize) to proceed anyway. Default false: with no
-	 * confident estimate an undersized cluster is REJECTED. Turn on only for
-	 * single-node / local dev where you knowingly run below the safe floor.
-	 */
-	allowUnvalidatedSmallCluster?: boolean;
-	/**
-	 * What a member WITH a transaction validator does with a pend that carries no `validation`
-	 * payload. See {@link UnvalidatablePendPolicy}; default 'accept'.
-	 */
-	unvalidatablePendPolicy?: UnvalidatablePendPolicy;
-}
-
-/**
- * What a receiver WITH a transaction checker does with a pend that carries no
- * {@link PendRequest.validation} payload — the single-collection (`Collection.sync`) shape, which
- * has no transaction to re-execute.
- *
- * - `'accept'` (default) preserves the historical behaviour: the pend is approved unchecked.
- * - `'reject'` is the fail-closed posture for a deployment that has decided every write must be
- *   re-checkable; it REFUSES `Collection.sync` writes, which is the point, not a bug.
- *
- * Irrelevant on a receiver with no checker, which never re-checks anything. Named once here and
- * referenced by every tier that carries the knob (`ClusterConsensusConfig`, db-p2p's
- * `ClusterPolicyOptions` and `StorageRepoOptions`) so the three cannot drift apart.
- */
-export type UnvalidatablePendPolicy = 'accept' | 'reject';
+import type { RepoMessage } from "../network/repo-protocol.js";
+import type { CommitResult, PendResult } from "../network/struct.js";
+
+/**
+ * One member's vote on a cluster transaction, in either the promise or the commit map.
+ *
+ * A discriminated union rather than one shape with optional fields, so each vote kind carries
+ * exactly its own payload: a `conflict` without its `conflictWith` (or a stray `rejectReason` on an
+ * `approve`) does not typecheck. Every variant's extra field is folded into the signed payload
+ * ({@link clusterVoteSigningPayload}), so none of them can be altered in transit.
+ */
+export type Signature =
+	| { type: 'approve'; signature: string }
+	| { type: 'reject'; signature: string; rejectReason?: string }
+	/**
+	 * This member refuses the transaction *for now*: it holds a conflicting transaction that won
+	 * the deterministic race (`resolveRace`). Retryable — NOT a validity judgement, and never
+	 * counted toward the permanent-rejection threshold. `conflictWith` is the winning
+	 * transaction's messageHash: structured, signed, and readable without parsing prose.
+	 */
+	| { type: 'conflict'; signature: string; conflictWith: string };
+
+/**
+ * The exact bytes a vote signature covers: `<hash>:<type>[:<extra>]`, where `extra` is the variant's
+ * own payload — a reject's `rejectReason`, a conflict's `conflictWith`, nothing for an approve.
+ * Folding the extra in is what makes it integrity-protected in transit rather than free-floating
+ * prose.
+ *
+ * Producers and verifiers must both build the preimage here. It lives beside {@link Signature}
+ * rather than in either consumer because a second copy that forgets a variant does not fail loudly:
+ * it reports an honest vote as an invalid signature. (The dispute path once carried such a copy.)
+ *
+ * "Cluster" in the name distinguishes these consensus votes from the dispute subsystem's
+ * arbitration votes, which have their own unrelated preimage (`dispute/invalidation.ts`).
+ */
+export function clusterVoteSigningPayload(hash: string, type: Signature['type'], extra?: string): Uint8Array {
+	return new TextEncoder().encode(hash + ':' + type + (extra ? ':' + extra : ''));
+}
+
+/** Verifier-side {@link clusterVoteSigningPayload}: reads each variant's signed extra off the vote itself. */
+export function clusterVoteVerificationPayload(hash: string, signature: Signature): Uint8Array {
+	switch (signature.type) {
+		case 'reject': return clusterVoteSigningPayload(hash, 'reject', signature.rejectReason);
+		case 'conflict': return clusterVoteSigningPayload(hash, 'conflict', signature.conflictWith);
+		default: return clusterVoteSigningPayload(hash, signature.type);
+	}
+}
+
+export type ClusterPeers = {
+	[id: string]: {
+		multiaddrs: string[];
+		/** Base64url-encoded public key (serialization-safe) */
+		publicKey: string;
+	};
+};
+
+/**
+ * One member's own report of what its storage did with this transaction at consensus-apply time; see
+ * {@link ClusterRecord.applyOutcomes} for the trust rules. The two arms report differently, and
+ * deliberately so:
+ *
+ *  - `pend` is set ONLY for a conflict-shaped refusal. The coordinator's rule for it is "an entry
+ *    means retry", so a success must not exist there.
+ *  - `commit` is ALWAYS set once a commit applied — successes included — because the coordinator
+ *    counts durable holders (`CoordinatorRepo.commit`'s durability gate), and a count needs the
+ *    positives. Consensus votes say the cohort agreed to apply the commit; this arm says whether
+ *    this member's storage actually holds the committed revision under the record's action
+ *    afterwards, measured AFTER the member's own reconcile (a member that pulled the revision from a
+ *    cohort peer reports success). A commit that reached consensus is authoritative for ordering,
+ *    but it was never evidence of storage — which is what this arm supplies.
+ */
+export type MemberApplyOutcome = {
+	/** This member's storage refused the record's pend with a conflict-shaped result. */
+	pend?: PendResult;
+	/**
+	 * Whether this member's storage durably holds the record's committed revision, for every block
+	 * the commit named, after applying and (if needed) reconciling. `success: true` is a durable
+	 * holder; a failure carries storage's refusal (or a refusal built from the missing-pend throw)
+	 * for the operator's benefit — the coordinator reads only `success`.
+	 */
+	commit?: CommitResult;
+};
+
+export type ClusterRecord = {
+	messageHash: string;	// Serves as a unique identifier for the clustered transaction record
+	peers: ClusterPeers;
+	/**
+	 * Membership-binding version. Absent or `1` = legacy *unbound* record: the peer set is NOT covered by
+	 * any hash (pre-binding history and its stored commit certs verify byte-identically to before). `2` =
+	 * the sorted peer-id set (as {@link ClusterRecord.membershipDigest}) is folded into `messageHash`,
+	 * `promiseHash`, and `commitHash`, so two different peer sets yield two different `messageHash`es.
+	 * New coordinators always emit `2`. See `packages/db-core/src/cluster/membership.ts`.
+	 */
+	membershipVersion?: 1 | 2;
+	/** Membership digest of {@link ClusterRecord.peers}; present iff `membershipVersion === 2`. base64url. */
+	membershipDigest?: string;
+	/**
+	 * The transaction's operations and the block the coordinator selected the cohort by
+	 * ({@link RepoMessage.coordinatingBlockIds}). There is deliberately NO top-level copy of the
+	 * coordinating block ids on the record: `messageHash` covers `message` only, so a duplicate at
+	 * this level would be outside every hash and any relaying peer could rewrite it — and the
+	 * membership admission gate derives its own cohort view from exactly that id
+	 * (`ClusterMember.deriveExpectedClusterView`). One source of truth, inside the hash.
+	 */
+	message: RepoMessage;
+	promises: { [peerId: string]: Signature };
+	commits: { [peerId: string]: Signature };
+	/** Sender's recommended cluster size: min(estimated network size, configured cluster size) */
+	suggestedClusterSize?: number;
+	minRequiredSize?: number;
+	/** Sender's current network size estimate */
+	networkSizeHint?: number;
+	/** Confidence in the network size estimate (0-1) */
+	networkSizeConfidence?: number;
+	/**
+	 * What each member's OWN storage answered when it applied this record's operations at consensus,
+	 * keyed by peer id. Advisory and **unsigned** — no hash covers it — and deliberately so: it is
+	 * written by a member *after* the votes are cast, on the response it hands back, so no signed
+	 * payload could carry it without a further round trip.
+	 *
+	 * Members set only their own entry. The pend arm is set only for a *conflict-shaped* pend
+	 * refusal (one carrying `pending` or `missing`, per `isConflictFailure`) — the
+	 * optimistic-concurrency verdict that a rival holds the blocks or already took the revision.
+	 * Pend successes and bare-reason faults are omitted: a bare fault stays tolerated local
+	 * divergence, mirroring the coordinator's own local-verdict arm. The commit arm is set for every
+	 * applied commit, success or not, because the coordinator counts the successes
+	 * ({@link MemberApplyOutcome}).
+	 *
+	 * Why unsigned is acceptable: a hostile pend entry can only *downgrade* a reported pend success
+	 * into a retryable conflict, which the writer answers by rebasing and trying again. A hostile
+	 * commit entry is no worse: a false *success* counts one durable holder the member already
+	 * counted for with its signed approve vote (the vote is what admits it to the majority the count
+	 * is measured against), and a false *refusal* is again only retry pressure. The same member
+	 * could already force strictly worse outcomes with a signed reject or conflict vote, so this adds
+	 * no attack surface beyond retry pressure — and failing toward retry is the correct direction for
+	 * optimistic concurrency. Never treat an entry here as evidence of anything but "retry" (pend) or
+	 * "one more holder in a count that a signed vote already bounded" (commit).
+	 *
+	 * Old peers never set it and old coordinators ignore it, so it is wire-compatible in both
+	 * directions.
+	 *
+	 * NOTE: unlike a signed reject/conflict vote, an entry here is unattributable — nothing verifies
+	 * it came from the peer it is keyed under beyond the coordinator taking each peer's entry from
+	 * that peer's own response, and no reputation penalty can be pinned on a false one. Fine while the
+	 * worst it buys is retry pressure a signed vote could already produce. If a member is ever
+	 * observed reporting refusals it did not make — writes on a block failing their retry budget with
+	 * `coordinator-repo:pend-remote-refusal` naming one peer over and over — the fix is to make the
+	 * entry attributable (sign it on a follow-up round) rather than to start trusting it less.
+	 */
+	applyOutcomes?: { [peerId: string]: MemberApplyOutcome };
+	/** Transaction proceeded despite minority rejections */
+	disputed?: boolean;
+	/** Evidence of the dispute: which peers rejected and why */
+	disputeEvidence?: {
+		rejectingPeers: string[];
+		rejectReasons: { [peerId: string]: string };
+	};
+}
+
+/**
+ * Single source of truth for the default super-majority threshold — the fraction of a cluster's peers
+ * that must promise before a transaction may proceed. Every component that falls back to a default when
+ * config is absent (cluster member, coordinator policy, node composition root) references THIS constant,
+ * so a member cannot silently default to a different threshold than the coordinator that commits. Explicit
+ * caller-supplied thresholds are unaffected; this only unifies the *absent-config* default.
+ * 0.75 = 3/4: chosen because the coordinator (which actually commits) already used it and the type documents it.
+ */
+export const DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75;
+
+export interface ClusterConsensusConfig {
+	/** Super-majority threshold for promises (default {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} = 0.75 = 3/4) */
+	superMajorityThreshold: number;
+	/** Simple majority threshold for commits (default 0.51 = >50%) */
+	simpleMajorityThreshold: number;
+	/** Minimum absolute cluster size (default 3) */
+	minAbsoluteClusterSize: number;
+	/** Allow cluster to operate below configured size (default false) */
+	allowClusterDownsize: boolean;
+	/** Tolerance for cluster size variance as fraction (default 0.5 = 50%) */
+	clusterSizeTolerance: number;
+	/**
+	 * Configured full cluster size — the replication factor / target cohort breadth. This is what the
+	 * coordinator aims for when selecting a cohort. It is NOT a statement about how many peers exist,
+	 * and nothing may use it as a security yardstick; see {@link ClusterConsensusConfig.assumedClusterSize}.
+	 * The coordinator supplies this as a required `clusterSize` via `ClusterConsensusConfig & { clusterSize: number }`.
+	 */
+	clusterSize?: number;
+	/**
+	 * The smallest cohort the operator asserts this deployment can genuinely field — typically
+	 * `min(clusterSize, number of nodes actually run)`. Read ONLY when a node cannot independently
+	 * measure a cohort (no derivation capability wired, or no confident network-size estimate), where
+	 * it stands in for the measured estimate in the membership admission floor.
+	 *
+	 * Undefined means "unknown": the admission gate then cannot tell a downsize from a legitimately
+	 * small cluster and preserves legacy approve behavior. Composition roots should supply a concrete
+	 * value; `libp2p-node-base` defaults it to `minAbsoluteClusterSize`.
+	 */
+	assumedClusterSize?: number;
+	/**
+	 * Fraction of the member's OWN confident cluster-size estimate a declared peer set must meet to be
+	 * admitted for voting (default 0.75). Below `⌈membershipAdmissionFraction · K_est⌉` a declared set is
+	 * treated as an unjustified self-shrink and the member declines to approve. Distinct from
+	 * {@link superMajorityThreshold} (the vote-counting threshold) — this gates *which set* may be voted on.
+	 */
+	membershipAdmissionFraction?: number;
+	/** Window for detecting partition in milliseconds (default 60000 = 1 min) */
+	partitionDetectionWindow: number;
+	/** Enable dispute escalation protocol (default false) */
+	disputeEnabled?: boolean;
+	/** Timeout for dispute arbitration in milliseconds (default 60000) */
+	disputeArbitrationTimeoutMs?: number;
+	/**
+	 * Hard horizon on an invalidation cascade: maximum number of recursive re-evaluation rounds
+	 * (dependency-graph depth) before the cascade stops and escalates the affected collection(s)
+	 * for operator full re-sync (default 32). Bounds unbounded automatic reversal.
+	 */
+	maxCascadeDepth?: number;
+	/**
+	 * Hard horizon on an invalidation cascade: maximum number of transactions (including the root)
+	 * the cascade may invalidate before it stops and escalates for operator full re-sync
+	 * (default 1000). On overflow the already-applied invalidations stand; the remainder is flagged,
+	 * never silently dropped.
+	 */
+	maxCascadeTransactions?: number;
+	/** Initial scheduled-retry interval for failed commit broadcasts, ms (default 250) */
+	commitBroadcastRetryInitialMs?: number;
+	/** Backoff factor for commit-broadcast scheduled retries (default 2) */
+	commitBroadcastRetryBackoffFactor?: number;
+	/** Max scheduled-retry interval, ms (default 8000) */
+	commitBroadcastRetryMaxIntervalMs?: number;
+	/** Max scheduled retry attempts before giving up (default 5) */
+	commitBroadcastRetryMaxAttempts?: number;
+	/** Immediate in-line retries per failed peer inside the broadcast (default 1) */
+	commitBroadcastImmediateRetries?: number;
+	/**
+	 * Immediate in-line retries per peer while collecting promises (default 1).
+	 * The promise phase rides the same libp2p stream the commit broadcast does;
+	 * a circuit-relay ("limited") connection can reset that stream once a
+	 * per-circuit cap is hit, surfacing to the coordinator as a StreamResetError.
+	 * Unlike the commit broadcast there is no follow-up scheduled retry, so a
+	 * single reset here would otherwise drop the peer and sink super-majority.
+	 */
+	promiseImmediateRetries?: number;
+	/** Read-repair behavior: 'off' (only fetch on missing — legacy), 'lazy' (fetch when local age > window), 'paranoid' (always verify against cluster on read, missing blocks included). Default 'lazy'. In 'off' and 'lazy', a missing block whose cohort is this node alone is re-consulted at most once per `readRepairWindowMs`. */
+	readRepairMode?: 'off' | 'lazy' | 'paranoid';
+	/** For 'lazy' mode: read-repair triggers when (now - localEntry.lastSeenCommitMs) > this. In 'lazy' and 'off' it is also how long a settled absence is remembered. Default 10000. */
+	readRepairWindowMs?: number;
+	/** Per-read probability of a cohort check in 'lazy' mode even within the window — of a held block or a settled absence (0..1). Default 0 (no random check). */
+	readRepairSampleRate?: number;
+	/**
+	 * When FRET has no confident network-size estimate, allow an undersized cluster
+	 * (peerCount < minAbsoluteClusterSize) to proceed anyway. Default false: with no
+	 * confident estimate an undersized cluster is REJECTED. Turn on only for
+	 * single-node / local dev where you knowingly run below the safe floor.
+	 */
+	allowUnvalidatedSmallCluster?: boolean;
+	/**
+	 * What a member WITH a transaction validator does with a pend that carries no `validation`
+	 * payload. See {@link UnvalidatablePendPolicy}; default 'accept'.
+	 */
+	unvalidatablePendPolicy?: UnvalidatablePendPolicy;
+}
+
+/**
+ * What a receiver WITH a transaction checker does with a pend that carries no
+ * {@link PendRequest.validation} payload — the single-collection (`Collection.sync`) shape, which
+ * has no transaction to re-execute.
+ *
+ * - `'accept'` (default) preserves the historical behaviour: the pend is approved unchecked.
+ * - `'reject'` is the fail-closed posture for a deployment that has decided every write must be
+ *   re-checkable; it REFUSES `Collection.sync` writes, which is the point, not a bug.
+ *
+ * Irrelevant on a receiver with no checker, which never re-checks anything. Named once here and
+ * referenced by every tier that carries the knob (`ClusterConsensusConfig`, db-p2p's
+ * `ClusterPolicyOptions` and `StorageRepoOptions`) so the three cannot drift apart.
+ */
+export type UnvalidatablePendPolicy = 'accept' | 'reject';

package/src/collection/collection.ts

@@ -646,8 +646,36 @@ export class Collection<TAction> implements ICollection<TAction> {
 
 	/** Restore the staged state captured by {@link snapshotPending}, discarding any
 	 * mutations staged since. Reads through the collection then observe exactly the
-	 * snapshot state again; storage is untouched because nothing was ever synced. */
+	 * snapshot state again; storage is untouched because nothing was ever synced.
+	 *
+	 * A snapshot is only restorable VERBATIM onto the committed boundary it was captured
+	 * on. If this collection has since ADOPTED a newer committed revision — a rival's
+	 * commit folded in by a refresh while the snapshot's transaction was in flight, e.g.
+	 * the conflict replay that refused a guarded insert (TreeKeyTakenError) — the
+	 * snapshot's transforms describe block state at the OLD boundary, and reinstalling
+	 * them would shadow committed blocks with stale structure. The observed case: an
+	 * INVENTED collection's pre-commit header/root transforms restored over the rival's
+	 * now-committed collection make every later read descend an empty tree, silently
+	 * hiding the committed rows. When the snapshot's pending queue is empty (the
+	 * transaction-rollback shape: the capture predates the transaction's first stage),
+	 * the correct restore target IS the committed state — reset the tracker empty and
+	 * let reads flow through to the adopted revision.
+	 *
+	 * NOTE: a snapshot that carries PENDING actions across a moved boundary (a
+	 * mid-transaction savepoint captured before a mid-transaction refresh adopted a
+	 * rival's commit) still restores verbatim below — rebasing it would require an async
+	 * replay this synchronous method cannot run. That shape predates this guard and
+	 * keeps its old behaviour; if it is ever observed producing stale reads, the rebase
+	 * belongs in an async caller that can replay the pending queue (see replayActions). */
 	restorePending(snapshot: CollectionSnapshot<TAction>): void {
+		const capturedRev = snapshot.context?.rev;
+		const currentRev = this.source.actionContext?.rev;
+		const boundaryMoved = currentRev !== undefined && (capturedRev === undefined || currentRev > capturedRev);
+		if (boundaryMoved && snapshot.pending.length === 0) {
+			this.tracker.reset();
+			this.pending = [];
+			return;
+		}
 		this.tracker.reset(copyTransforms(snapshot.transforms));
 		this.pending = [...snapshot.pending];
 	}
@@ -763,7 +791,14 @@ export class Collection<TAction> implements ICollection<TAction> {
 	 * process can be at different revisions at the same instant. That gap is invisible
 	 * from outside the class without this accessor, which is the whole reason it
 	 * exists: `docs/debugging.md` (§ "Which revision did a read descend?") explains
-	 * how an operator reads the difference. */
+	 * how an operator reads the difference.
+	 *
+	 * The one exception is `undefined` itself, which is a STATE rather than a revision:
+	 * "this instance invented the collection and has never adopted a committed revision".
+	 * For the same reason (only this instance moves it), it stays true until this instance
+	 * updates, syncs or records a commit, so a caller holding a freshly opened instance may
+	 * branch on it — the Quereus adapter does, to leave an invented, never-written index tree
+	 * unflushed exactly as an unwritten table tree is left. Never branch on the NUMBER. */
 	committedRevision(): number | undefined {
 		return this.source.actionContext?.rev;
 	}