@optimystic/db-p2p 0.25.1 → 0.27.0

package/src/cluster/quorum-restore.ts

@@ -16,8 +16,13 @@ import type { BlockCommitProof } from "./commit-proof.js";
  * caller has already verified (`cluster/certified-claims.ts`) and marked via the
  * injected `certified` flag — so a lone honest holder with a valid proof is
  * sufficient where uncertified claims still need distinct-peer corroboration.
- * Verification itself never happens here: both selectors stay pure and
- * synchronous; verdicts arrive as booleans.
+ * Certified claims are additionally weighed by the proof's SIGNER COUNT
+ * (`certifiedSignerCount`, injected alongside the flag): a single-signer proof —
+ * routine since solo cohorts mint their own commit receipts — is one machine's
+ * honest word about its own commit, so it wins only where nothing multi-peer
+ * contests it, and never outranks several distinct peers agreeing at the same
+ * revision. Verification itself never happens here: both selectors stay pure and
+ * synchronous; verdicts arrive as booleans and counts.
  */
 
 /** A single peer's self-reported (rev, actionId) for a block. */
@@ -41,6 +46,16 @@ export interface RevClaim {
 	 * Never set this from the mere presence of {@link proof}.
 	 */
 	certified?: boolean;
+	/**
+	 * Distinct signers in the verified proof, injected by the caller from the certification verdict
+	 * (`ClaimCertification.signerCount`, `cluster/certified-claims.ts`) — never read off
+	 * {@link proof} here. Meaningful only when {@link certified} is set. Selection weighs a certified
+	 * claim as SINGLE-SIGNER when this is absent or below two: the conservative direction, since a
+	 * single-signer proof (a solo cohort's self-signed commit receipt) must never outrank multi-peer
+	 * agreement, and a caller that forgot to plumb the count should degrade toward corroboration,
+	 * not toward trusting one signature.
+	 */
+	certifiedSignerCount?: number;
 }
 
 /** The (rev, actionId) pair a quorum agreed on, plus the peers that corroborated it. */
@@ -136,18 +151,26 @@ export function corroboratorCapacity(cohortPeerCount: number, repairCorroboratio
  *
  * **Certified claims** (`certified === true`, injected by a caller that verified the claim's
  * cohort commit proof — see `cluster/certified-claims.ts`) short-circuit the distinct-peer rule,
- * because the proof's signature set IS the corroboration:
+ * because the proof's signature set IS the corroboration — weighed by how many signers that set
+ * actually holds ({@link RevClaim.certifiedSignerCount}):
  *
  *  - No certified claims → today's corroboration result, unchanged.
  *  - A corroborated pair at a HIGHER rev than every certified claim wins — corroboration stays a
  *    legitimate weaker path, so a legacy uncertified tail written after the last proven rev
  *    remains readable.
- *  - Otherwise the highest certified rev wins: this covers a certified rev beaten in raw rev only
- *    by an *uncorroborated* claim (which failed quorum and is no evidence), and the equal-rev
- *    tie, where the proof outweighs votes.
- *  - Except: two distinct `actionId`s certified at that top rev is equivocation — the cohort
- *    provably signed two different actions into one revision — and the whole selection declines
- *    (`undefined`). Callers distinguish this decline from a plain no-quorum via
+ *  - A MULTI-SIGNER certified claim (two-plus signers) at the top certified rev wins over an
+ *    equal-rev corroborated pair and over any uncorroborated claim: the proof outweighs votes.
+ *    Single-signer certified claims at that rev neither outrank it nor equivocate against it — a
+ *    solo cohort's self-signed receipt is one machine's word, not the cohort's second signature.
+ *  - A SINGLE-SIGNER-only certified rev still wins where nothing multi-peer contests it (a lone
+ *    holder with a solo proof stays repairable), but it never beats corroboration by
+ *    {@link CORROBORATION_FLOOR}-plus distinct peers at the SAME revision — one machine that was
+ *    briefly alone must not outrank the cohort that stayed together. A corroborated pair that
+ *    AGREES with the sole certified action is convergence, not a contest; the certified verdict
+ *    is kept.
+ *  - Two distinct `actionId`s still CONTENDING at the top certified rev is equivocation — the
+ *    same keys provably signed two different actions into one revision — and the whole selection
+ *    declines (`undefined`). Callers distinguish this decline from a plain no-quorum via
  *    {@link certifiedEquivocation}.
  */
 export function selectQuorumRev(
@@ -195,43 +218,87 @@ export function selectQuorumRev(
 	// must stay readable. A merely UNcorroborated higher rev never reaches here (it is not in
 	// `corroborated`), so it cannot outrank a proof.
 	if (corroborated && corroborated.rev > certified.rev) return corroborated;
-	// Two actions provably signed into the same top revision: decline the whole selection rather
-	// than pick a side. Callers log via certifiedEquivocation.
-	if (certified.byAction.size !== 1) return undefined;
-	const [entry] = certified.byAction;
-	const [actionId, supporters] = entry!; // size === 1 checked above
-	return { rev: certified.rev, actionId, supporters: [...supporters], certified: true };
+	const contenders = certifiedContenders(certified.byAction);
+	// A single-signer-only certified rev loses the equal-rev tie to genuinely multi-peer
+	// corroboration — unless the corroborated pair AGREES with the sole certified action, which is
+	// convergence rather than a contest and keeps the certified verdict (and its logging/penalty
+	// exemptions) intact.
+	// NOTE: the weighing reaches EQUAL revisions only. A solo fork that committed twice while its
+	// cohort committed once claims the higher rev and still wins above. That is not an oversight of
+	// this rule: a claim carries no lineage, so "one peer ahead of two" is identical whether it
+	// forked or the two are lagging, and refusing it would break ordinary lagging-cohort repair.
+	// Pinned by 'does NOT reach a solo fork one revision AHEAD' in quorum-restore-certified.spec.ts;
+	// closing it needs new evidence — debt-repair-cannot-tell-a-fork-from-a-lagging-cohort.
+	if (!contenders.multiSigner && corroborated && corroborated.rev === certified.rev
+		&& corroborated.supporters.length >= CORROBORATION_FLOOR
+		&& !(certified.byAction.size === 1 && certified.byAction.has(corroborated.actionId))) {
+		return corroborated;
+	}
+	// Two actions provably signed into the same top revision by contending proofs: decline the
+	// whole selection rather than pick a side. Callers log via certifiedEquivocation.
+	if (contenders.entries.length !== 1) return undefined;
+	const [actionId, group] = contenders.entries[0]!;
+	return { rev: certified.rev, actionId, supporters: [...group.supporters], certified: true };
 }
 
-/** Certified claims at the top certified rev, keyed by actionId → distinct certified claimants. */
-function certifiedGroups(claims: RevClaim[]): { rev: number; byAction: Map<string, Set<string>> } | undefined {
+/** Distinct certified claimants of one action at the top certified rev, and whether any of their
+ * proofs carried two-plus signers. */
+interface CertifiedActionGroup {
+	supporters: Set<string>;
+	/** True when at least one certified claim for this action had `certifiedSignerCount >= 2`. */
+	multiSigner: boolean;
+}
+
+/** Certified claims at the top certified rev, keyed by actionId → the claimants behind each. */
+function certifiedGroups(claims: RevClaim[]): { rev: number; byAction: Map<string, CertifiedActionGroup> } | undefined {
 	let top: number | undefined;
 	for (const c of claims) {
 		if (c.certified === true && (top === undefined || c.rev > top)) top = c.rev;
 	}
 	if (top === undefined) return undefined;
-	const byAction = new Map<string, Set<string>>();
+	const byAction = new Map<string, CertifiedActionGroup>();
 	for (const c of claims) {
 		if (c.certified !== true || c.rev !== top) continue;
-		let s = byAction.get(c.actionId);
-		if (!s) {
-			s = new Set();
-			byAction.set(c.actionId, s);
+		let g = byAction.get(c.actionId);
+		if (!g) {
+			g = { supporters: new Set(), multiSigner: false };
+			byAction.set(c.actionId, g);
 		}
-		s.add(c.peerId);
+		g.supporters.add(c.peerId);
+		// Absent or sub-two count weighs as single-signer — see RevClaim.certifiedSignerCount.
+		if ((c.certifiedSignerCount ?? 1) >= 2) g.multiSigner = true;
 	}
 	return { rev: top, byAction };
 }
 
+/**
+ * Which certified actions at the top rev actually CONTEND for selection. A multi-signer proof is
+ * the cohort's own signature set; a single-signer proof is one machine's word about its own solo
+ * commit — so when any action is multi-signer-backed, only the multi-signer-backed ones contend
+ * (a solo receipt can neither outrank nor equivocate against a cohort proof), and only with no
+ * multi-signer action anywhere do the single-signer ones contend among themselves. One helper so
+ * {@link selectQuorumRev} and {@link certifiedEquivocation} cannot drift on the rule.
+ */
+function certifiedContenders(
+	byAction: Map<string, CertifiedActionGroup>
+): { entries: [string, CertifiedActionGroup][]; multiSigner: boolean } {
+	const multi = [...byAction].filter(([, g]) => g.multiSigner);
+	return multi.length > 0
+		? { entries: multi, multiSigner: true }
+		: { entries: [...byAction], multiSigner: false };
+}
+
 /**
  * The conflicting certified set at the top certified rev, when there is one: two-plus distinct
- * `actionId`s each carrying a verified cohort commit proof for the SAME revision. It deserves a
- * distinct log line from a plain no-quorum — the cohort (or whoever holds its keys) provably
- * signed both sides. Selection stays pure, so callers do the logging with what this reports.
+ * `actionId`s that CONTEND there ({@link certifiedContenders}) — each carrying a verified cohort
+ * commit proof for the SAME revision, at comparable weight. It deserves a distinct log line from a
+ * plain no-quorum — whoever holds the signing keys provably signed both sides. Selection stays
+ * pure, so callers do the logging with what this reports.
  *
- * `undefined` when no certified claim exists or the top certified rev names a single action —
- * conflicts at LOWER certified revs are history already superseded, not equivocation worth
- * declining over.
+ * `undefined` when no certified claim exists or a single action contends at the top certified rev —
+ * conflicts at LOWER certified revs are history already superseded, and a single-signer proof
+ * disagreeing with a multi-signer one at the same rev is a solo machine's fork losing to the
+ * cohort, not equivocation worth declining over.
  *
  * **Ask this only on a decline.** A non-`undefined` result does NOT imply {@link selectQuorumRev}
  * returned `undefined`: a corroborated pair STRICTLY above the top certified rev still wins, and
@@ -240,8 +307,10 @@ function certifiedGroups(claims: RevClaim[]): { rev: number; byAction: Map<strin
  */
 export function certifiedEquivocation(claims: RevClaim[]): { rev: number; actionIds: string[] } | undefined {
 	const groups = certifiedGroups(claims);
-	if (!groups || groups.byAction.size < 2) return undefined;
-	return { rev: groups.rev, actionIds: [...groups.byAction.keys()] };
+	if (!groups) return undefined;
+	const contenders = certifiedContenders(groups.byAction);
+	if (contenders.entries.length < 2) return undefined;
+	return { rev: groups.rev, actionIds: contenders.entries.map(([actionId]) => actionId) };
 }
 
 /** One block candidate paired with its serving peer and canonical hash
@@ -256,6 +325,13 @@ export interface BlockHashCandidate {
 	 * bytes), so the cohort's signatures stand in for other peers serving the same hash.
 	 */
 	certified?: boolean;
+	/**
+	 * Distinct signers in the verified proof, from the certification verdict
+	 * (`ContentCertification.signerCount`) — the content-side sibling of
+	 * {@link RevClaim.certifiedSignerCount}, with the same weighing: meaningful only when
+	 * {@link certified} is set, and absent or sub-two counts as single-signer.
+	 */
+	certifiedSignerCount?: number;
 }
 
 /**
@@ -279,11 +355,23 @@ export interface BlockHashCandidate {
  * *genuinely* that small reaches this branch.
  *
  * **Certified candidates** (`certified === true` — a caller verified a cohort commit proof whose
- * declared digest matches these exact bytes) short-circuit the hash quorum: exactly one distinct
- * certified hash → that block wins outright, however many peers served it. Two-plus distinct
- * certified hashes is certified content equivocation → decline (`undefined`), mirroring the
- * existing unique-hash-tie decline; callers name that decline via
- * {@link certifiedContentEquivocation}. No certified candidate → the hash quorum below, unchanged.
+ * declared digest matches these exact bytes) are weighed by the proof's signer count, mirroring
+ * {@link selectQuorumRev}:
+ *
+ *  - Exactly one distinct MULTI-SIGNER certified hash → that block wins outright, however many
+ *    peers served anything else: the cohort's own signatures over the digest outweigh other
+ *    carriers' bytes. Two-plus distinct multi-signer certified hashes is certified content
+ *    equivocation → decline (`undefined`); a single-signer certified hash alongside a
+ *    multi-signer one neither wins nor forces that decline (a solo receipt cannot equivocate
+ *    against the cohort's proof).
+ *  - SINGLE-SIGNER-only certified hashes no longer short-circuit: a hash group carried by
+ *    {@link CORROBORATION_FLOOR}-plus distinct peers that meets the ordinary quorum displaces
+ *    them (two-plus such groups is a genuine content disagreement → decline, as ever). With no
+ *    multi-peer group to defer to, a sole single-signer certified hash still wins on its proof —
+ *    a lone certified holder stays repairable — and two-plus distinct ones decline.
+ *  - No certified candidate → the hash quorum below, unchanged.
+ *
+ * Callers name the certified declines via {@link certifiedContentEquivocation}.
  */
 export function selectQuorumBlock(
 	candidates: BlockHashCandidate[],
@@ -293,12 +381,12 @@ export function selectQuorumBlock(
 	if (candidates.length === 0) return undefined;
 
 	const certifiedByHash = certifiedHashes(candidates);
-	if (certifiedByHash.size === 1) {
-		const [entry] = certifiedByHash;
-		const [hash, block] = entry!;
+	const multiSignerHashes = [...certifiedByHash].filter(([, v]) => v.multiSigner);
+	if (multiSignerHashes.length === 1) {
+		const [hash, { block }] = multiSignerHashes[0]!;
 		return { block, hash };
 	}
-	if (certifiedByHash.size > 1) return undefined; // certified content equivocation — decline
+	if (multiSignerHashes.length > 1) return undefined; // certified content equivocation — decline
 
 	// One vote per distinct peer per hash group, matching selectQuorumRev — a peer appearing twice
 	// must not be able to second itself into a content quorum.
@@ -316,33 +404,72 @@ export function selectQuorumBlock(
 
 	const quorum = quorumSize(voters.size, simpleMajorityThreshold, corroboratorCapacity);
 	const meeting = [...groups.entries()].filter(([, g]) => g.supporters.size >= quorum);
-	// Exactly one hash may meet quorum; a tie is a genuine content disagreement → decline.
-	if (meeting.length !== 1) return undefined;
-	const [hash, group] = meeting[0]!;
-	return { block: group.block, hash };
+
+	if (certifiedByHash.size === 0) {
+		// Exactly one hash may meet quorum; a tie is a genuine content disagreement → decline.
+		if (meeting.length !== 1) return undefined;
+		const [hash, group] = meeting[0]!;
+		return { block: group.block, hash };
+	}
+
+	// Only single-signer certified hashes remain. Genuinely multi-peer agreement — a quorum-meeting
+	// group of CORROBORATION_FLOOR-plus distinct carriers — outranks a solo proof, with the usual
+	// uniqueness rule among such groups. (A quorum-meeting group of ONE carrier, possible only on a
+	// capacity-one cohort, is a bare assertion and does not displace a verified proof.)
+	const multiPeer = meeting.filter(([, g]) => g.supporters.size >= CORROBORATION_FLOOR);
+	if (multiPeer.length > 1) return undefined;
+	if (multiPeer.length === 1) {
+		const [hash, group] = multiPeer[0]!;
+		return { block: group.block, hash };
+	}
+	// No multi-peer agreement to defer to: a sole single-signer certified hash wins on its proof;
+	// two-plus distinct ones are solo-vs-solo equivocation → decline.
+	if (certifiedByHash.size > 1) return undefined;
+	const [entry] = certifiedByHash;
+	const [hash, { block }] = entry!;
+	return { block, hash };
 }
 
-/** Distinct hashes carried by certified candidates → the first block instance serving each. */
-function certifiedHashes(candidates: BlockHashCandidate[]): Map<string, IBlock> {
-	const byHash = new Map<string, IBlock>();
+/** Distinct hashes carried by certified candidates → the first block instance serving each, and
+ * whether any certified candidate at that hash carried a two-plus-signer proof. */
+function certifiedHashes(candidates: BlockHashCandidate[]): Map<string, { block: IBlock; multiSigner: boolean }> {
+	const byHash = new Map<string, { block: IBlock; multiSigner: boolean }>();
 	for (const c of candidates) {
-		if (c.certified === true && !byHash.has(c.hash)) byHash.set(c.hash, c.block);
+		if (c.certified !== true) continue;
+		let entry = byHash.get(c.hash);
+		if (!entry) {
+			entry = { block: c.block, multiSigner: false };
+			byHash.set(c.hash, entry);
+		}
+		// Absent or sub-two count weighs as single-signer — see BlockHashCandidate.certifiedSignerCount.
+		if ((c.certifiedSignerCount ?? 1) >= 2) entry.multiSigner = true;
 	}
 	return byHash;
 }
 
 /**
- * The conflicting certified hashes when there are two or more — the content-side sibling of
- * {@link certifiedEquivocation}, and the reason {@link selectQuorumBlock} declines outright.
- * Candidates reaching that selector all carry the SAME `(rev, actionId)`, so two certified hashes
- * mean the cohort's keys signed two different digests into one revision: a provable compromise an
- * operator must be able to tell apart from the routine "not enough carriers agreed" decline. Both
- * declines return `undefined`, so without this they log identically.
+ * The conflicting certified hashes when there are two or more CONTENDING — the content-side
+ * sibling of {@link certifiedEquivocation}, and the reason {@link selectQuorumBlock} declines
+ * outright. Candidates reaching that selector all carry the SAME `(rev, actionId)`, so two
+ * contending certified hashes mean the same keys signed two different digests into one revision: a
+ * provable compromise an operator must be able to tell apart from the routine "not enough carriers
+ * agreed" decline. Both declines return `undefined`, so without this they log identically.
+ * Contention mirrors the selector: multi-signer certified hashes when any exist, else the
+ * single-signer ones among themselves — a solo receipt disagreeing with a cohort proof is a fork
+ * losing, not equivocation.
  *
- * `undefined` when fewer than two distinct certified hashes exist — including the ordinary
+ * `undefined` when fewer than two certified hashes contend — including the ordinary
  * no-certified-candidate case, where a decline really is a plain content-quorum shortfall.
+ *
+ * **Ask this only on a decline**, exactly as with {@link certifiedEquivocation}: a non-`undefined`
+ * result does NOT imply {@link selectQuorumBlock} returned `undefined`. Two contending
+ * single-signer certified hashes yield to a {@link CORROBORATION_FLOOR}-plus-carrier quorum group,
+ * so selection can succeed while the solo-versus-solo conflict is still reported here. Call it when
+ * selection declined, to say WHY.
  */
 export function certifiedContentEquivocation(candidates: BlockHashCandidate[]): { hashes: string[] } | undefined {
 	const byHash = certifiedHashes(candidates);
-	return byHash.size < 2 ? undefined : { hashes: [...byHash.keys()] };
+	const multi = [...byHash].filter(([, v]) => v.multiSigner);
+	const contenders = multi.length > 0 ? multi : [...byHash];
+	return contenders.length < 2 ? undefined : { hashes: contenders.map(([hash]) => hash) };
 }

package/src/cluster/race-resolution.ts

@@ -0,0 +1,158 @@
+/**
+ * The deterministic arbiter between two conflicting cluster transactions: which of two writes to a
+ * shared block wins. Every function here is a total function of its arguments, with no member state
+ * and no effect beyond a debug log — `resolveRace` runs on the vote path, where a throw would cost
+ * the member its vote entirely — so the ordering rule can be read and tested on its own (see
+ * `test/race-resolution.spec.ts`). The stateful scan that consults them (`findConflict`, which sweeps stale
+ * reservations and clears a losing transaction) stays on `ClusterMember` in `cluster-repo.ts`.
+ */
+import type { ClusterRecord, RepoMessage } from "@optimystic/db-core";
+import { clampPriority } from "@optimystic/db-core";
+import { getActionId, getAffectedBlockIds } from "./record-operations.js";
+import { createLogger } from "../logger.js";
+
+// Same sub-namespace `cluster-repo.ts` logs under: these functions moved out of `ClusterMember`, and
+// their emitted tags (and the `debug` namespace they land in) must stay byte-identical, because
+// several specs capture by namespace and tag substring.
+const log = createLogger('cluster-member')
+
+/** Number of *approve* promise votes on a record — the count the commit rule uses. */
+export function approvalCount(record: ClusterRecord): number {
+	return Object.values(record.promises).filter(s => s.type === 'approve').length;
+}
+
+/**
+ * Resolve a race between two conflicting transactions. Total and deterministic, so every honest
+ * member computes the identical winner (the Theorem 1 Case-2 premise). Order:
+ *   1. more *approve* promise signatures wins  (progress monotonicity — see safety note below);
+ *   2. equal approval counts → higher aged priority wins  (fairness — see {@link recordPriority});
+ *   3. still tied → higher message hash wins.
+ *
+ * The count is APPROVALS, not `promises` keys. `promises` is the vote map — a reject occupies a key
+ * there exactly as an approve does — so counting keys would treat a rejection as progress, letting a
+ * record that can never commit outrank (and therefore block, via the reservation scan `findConflict`
+ * in `cluster-repo.ts`) a fresh rival for the whole staleness window. Approvals is also the count
+ * the invariant below actually needs: the commit rule is `approvedPromises >= superMajority`,
+ * which never looks at rejections.
+ *
+ * Approval count is FIRST so this comparison never displaces a transaction that is further along.
+ * That restores the pre-priority safety invariant: a member commits purely on promise supermajority
+ * (`handleCommitNeeded` signs whenever `approvedPromises >= superMajority`; the commit path has NO
+ * conflict re-check), so `resolveRace` is the ONLY arbiter among concurrently-pending conflicts.
+ * With approvals-first, once transaction X holds a promise supermajority every conflicting rival Y has
+ * strictly fewer approvals — Y can only match X's count by getting the intersecting quorum member to
+ * approve it, but that member already holds X at supermajority and `resolveRace(X, Y)` returns
+ * `keep-existing` on X's higher count, so it never does. By quorum intersection any Y-supermajority
+ * overlaps X's in ≥1 honest member, and that member rejects Y. One winner (docs/correctness.md
+ * Theorem 9). Priority-first would break this: it could displace an already-quorum-reached X for a
+ * higher-priority Y with fewer approvals, letting BOTH commit (split brain) — the regression fixed by
+ * ticket occ-priority-first-breaks-promise-monotonicity.
+ *
+ * Priority is now a tie-break that runs only at EQUAL approval counts, which is exactly the
+ * concurrent-starvation case aging targets (two fresh rivals, 0 promises each, otherwise coin-flipping
+ * on the hash). Priority still breaks those ties deterministically, so aging still solves the stated
+ * fairness problem in its common case. It only orders two *concurrently-pending* conflicts; it does NOT
+ * defer a fresh pend for an absent aged transaction (that residual — sequential sub-window starvation —
+ * is the deferred feat-occ-priority-reservation).
+ *
+ * NOTE: residual-fairness tripwire. Under approvals-first an aged transaction can still lose to a fresh
+ * rival that has *legitimately* gathered even one more approval — that is not the pure-coin-flip
+ * starvation aging targets (equal counts, priority wins), it is the monotonicity behaviour we WANT (a
+ * more-progressed rival is never displaced). If deeper fairness against a genuinely-more-progressed
+ * rival is ever needed, it belongs to feat-occ-priority-reservation (reserve/defer at pend time), NOT
+ * to this race tie-break.
+ *
+ * NOTE: Byzantine self-assert is a fairness DoS, not a safety hole. A coordinator can stamp
+ * priority == MaxPriority on every transaction; recordPriority clamps to the cap so it cannot
+ * exceed it, and priority never influences validity/operationsHash/stale-read checks — and now sits
+ * below the approval count, so it can only break equal-count ties it might have ~50% won anyway,
+ * degrading to at-worst-status-quo fairness (the same graceful-degradation class as spam under
+ * honest-majority). Binding priority to provable age is out of scope (feat-occ-priority-reservation).
+ *
+ * NOTE: keep priority a self-contained additive message field + this one comparison key so it
+ * composes with — does not block — a future HLC/crdt-sync redesign of this same path
+ * (design-hot-log-tail-sharding-guidance).
+ */
+export function resolveRace(existing: ClusterRecord, incoming: ClusterRecord): 'keep-existing' | 'accept-incoming' {
+	// 1. Transaction with more APPROVALS wins — never displace a more-progressed rival (safety, see
+	// above). Counting `promises` keys instead would count reject votes as progress: a record holding
+	// one rejection would outrank an untouched rival and reserve its blocks for the whole staleness
+	// window, and the commit rule this ordering protects (`approvedPromises >= superMajority`) never
+	// looks at rejections anyway.
+	const existingCount = approvalCount(existing);
+	const incomingCount = approvalCount(incoming);
+	if (existingCount !== incomingCount) {
+		return existingCount > incomingCount ? 'keep-existing' : 'accept-incoming';
+	}
+
+	// 2. Equal approval counts → higher aged priority wins (fairness tie-break).
+	const existingPriority = recordPriority(existing);
+	const incomingPriority = recordPriority(incoming);
+	if (existingPriority !== incomingPriority) {
+		return existingPriority > incomingPriority ? 'keep-existing' : 'accept-incoming';
+	}
+
+	// 3. Tie-breaker: higher message hash wins (deterministic).
+	return existing.messageHash > incoming.messageHash ? 'keep-existing' : 'accept-incoming';
+}
+
+/**
+ * Aged advisory priority carried by a record's pend operation, clamped to [0, MaxPriority].
+ * The multi-collection path carries it on `pend.validation.transaction.priority`; the single-collection
+ * (`Collection.sync`) path carries it as top-level `pend.priority`; a record with neither — a
+ * legacy/unversioned coordinator's transaction, or a non-pend operation — is priority 0
+ * (backward compatible: such transactions simply never age). Both carriers live inside the signed
+ * `message`, so priority is integrity-protected in transit; clamping here bounds a self-asserted
+ * out-of-range value to the cap.
+ *
+ * NOTE: `message` is fixed for a transaction's whole lifecycle (promises/commits accrue in the
+ * separate `promises`/`commits` maps, never in `message`), so a transaction keeps its rank through
+ * the commit phase — there is no "priority drops to 0 at commit" asymmetry. resolveRace is only
+ * consulted at the promise decision (`findConflict` in `cluster-repo.ts`), i.e. between two
+ * still-open conflicting transactions, which is exactly the concurrent-contention case priority
+ * is meant to order.
+ */
+export function recordPriority(record: ClusterRecord): number {
+	for (const op of record.message.operations) {
+		if ('pend' in op) {
+			// Every hop optional: `validation` arrives off the wire inside a signed message whose
+			// hash binds its bytes, not its shape, so a malformed pair must yield priority 0 (what
+			// clampPriority already does for a missing or Byzantine number) rather than throw out
+			// of the vote path — the lost vote this fail-closed pass exists to prevent.
+			return clampPriority(op.pend.validation?.transaction?.priority ?? op.pend.priority);
+		}
+	}
+	return 0;
+}
+
+/**
+ * Whether two messages must serialize against each other: true when they touch a common block AND
+ * are not the same action. The same-action escape is what lets a commit follow its own pend — both
+ * name every block the action writes, so a bare overlap test would have each transaction blocking
+ * its own next phase. Gates whether {@link resolveRace} runs at all.
+ */
+export function operationsConflict(ops1: RepoMessage['operations'], ops2: RepoMessage['operations']): boolean {
+	// Check if one is a commit for the same action as a pend - these don't conflict
+	const actionId1 = getActionId(ops1);
+	const actionId2 = getActionId(ops2);
+	if (actionId1 && actionId2 && actionId1 === actionId2) {
+		// Same action - commit is resolving the pend, not conflicting
+		return false;
+	}
+
+	const blocks1 = new Set(getAffectedBlockIds(ops1));
+	const blocks2 = new Set(getAffectedBlockIds(ops2));
+
+	for (const block of Array.from(blocks1)) {
+		if (blocks2.has(block)) {
+			log('cluster-member:conflict-detected', {
+				blocks1: Array.from(blocks1),
+				blocks2: Array.from(blocks2),
+				conflictingBlock: block
+			});
+			return true;
+		}
+	}
+
+	return false;
+}

package/src/cluster/reconcile-block.ts

@@ -45,6 +45,12 @@ interface ReconcileCandidate {
 	revCertified?: boolean;
 	/** Injected by the certification pass: the proof's declared digest matches these exact bytes. */
 	contentCertified?: boolean;
+	/**
+	 * Injected by the certification pass alongside {@link revCertified}: the verified proof's
+	 * distinct signer count, from the certification verdict. The selectors weigh a single-signer
+	 * certification below multi-peer agreement (`quorum-restore.ts`).
+	 */
+	certifiedSignerCount?: number;
 	/**
 	 * Set on `digest-mismatch` only: the served bytes provably contradict the proof's declared
 	 * digest, so this candidate is dropped from the content quorum (its rev claim still counts —
@@ -177,6 +183,7 @@ async function certifyCandidates(deps: ReconcileBlockDeps, blockId: BlockId, can
 			const verdict = await certifyContent(c.proof, claim, c.block, thresholds, deps.anchoring);
 			if (verdict.revCertified) {
 				c.revCertified = true;
+				c.certifiedSignerCount = verdict.signerCount;
 				if (verdict.contentCertified) {
 					c.contentCertified = true;
 				} else if (verdict.failure === 'digest-mismatch') {
@@ -198,6 +205,7 @@ async function certifyCandidates(deps: ReconcileBlockDeps, blockId: BlockId, can
 		const verdict = await certifyClaim(c.proof, claim, thresholds, deps.anchoring);
 		if (verdict.certified) {
 			c.revCertified = true;
+			c.certifiedSignerCount = verdict.signerCount;
 			return;
 		}
 		logUncertified(blockId, c, verdict.failure);
@@ -247,12 +255,19 @@ async function hashCarriers(
 		carriers.map(async c => ({
 			peerId: c.peerId, hash: await canonicalBlockHash(c.block!), block: c.block!,
 			...(c.contentCertified ? { certified: true } : {}),
+			...(c.contentCertified && c.certifiedSignerCount !== undefined
+				? { certifiedSignerCount: c.certifiedSignerCount } : {}),
 			...(c.contentCertified && c.proof ? { proof: c.proof } : {})
 		}))
 	);
 }
 
-/** Report cohort members that served content contradicting the agreed hash. Best-effort; never throws. */
+/**
+ * Report cohort members that served content contradicting the agreed hash. Best-effort; never
+ * throws. A CERTIFIED disagreeing carrier is exempt: its bytes match a verified proof's declared
+ * digest, so it honestly served a commit that really happened — when the hash quorum outweighs its
+ * single-signer proof (`selectQuorumBlock`), it is the losing side of a fork, not a fabricator.
+ */
 function penalizeContradictingContent(
 	reputation: Pick<IPeerReputation, 'reportPeer'> | undefined,
 	candidates: BlockHashCandidate[],
@@ -262,7 +277,7 @@ function penalizeContradictingContent(
 	if (!reputation) return;
 	try {
 		for (const c of candidates) {
-			if (c.hash !== agreedHash) {
+			if (c.hash !== agreedHash && c.certified !== true) {
 				reputation.reportPeer(c.peerId, PenaltyReason.InvalidRestoration, `reconcile:${blockId}`);
 			}
 		}
@@ -281,8 +296,11 @@ function penalizeContradictingContent(
  *
  * Peer-attached cohort commit proofs are verified first ({@link certifyCandidates}) and both gates
  * weigh the verdicts: a claim — and, separately, the bytes — that a verified proof certifies is
- * accepted with no second peer at any cohort size, and the proof that certified the bytes is
- * persisted alongside them so the repaired replica serves it onward.
+ * accepted with no second peer where nothing multi-peer contests it. The proof's signer count is
+ * weighed too: a SINGLE-SIGNER proof (a solo cohort's self-signed receipt) never outranks several
+ * distinct peers agreeing at the same revision or on the same bytes — see `quorum-restore.ts`. The
+ * proof that certified the agreed bytes is persisted alongside them so the repaired replica serves
+ * it onward.
  *
  * Both quorums are capped by {@link corroboratorCapacity} for the claims that still need
  * corroboration: demanding two corroborators from a cohort that contains exactly one other peer is
@@ -298,8 +316,10 @@ function penalizeContradictingContent(
  * no honest majority to appeal to in the first place. It is closed for a candidate that carries a
  * verified cohort commit proof — {@link certifyCandidates} binds the proof's declared digest to the
  * served bytes, which is a check against the *cohort's own signatures* rather than against other
- * peers, so a certified carrier wins the content gate outright and this exposure never applies to
- * it. It remains open for a proof-less candidate, and for the residual that layer 1 proves only
+ * peers, so a certified carrier wins the content gate with no second carrier and this exposure
+ * never applies to it. (Weighing still applies at larger widths: a SINGLE-SIGNER certified carrier
+ * does not displace a multi-peer hash quorum — see `selectQuorumBlock` — but at the capacity-one
+ * width this paragraph describes there is no multi-peer group to lose to.) It remains open for a proof-less candidate, and for the residual that layer 1 proves only
  * that the listed signers signed (`feat-cluster-membership-threshold-cert-anchoring`).
  *
  * Declines are cheap and retryable: nothing is persisted, nothing is marked, and the next commit
@@ -319,8 +339,10 @@ export function createReconcileBlock(deps: ReconcileBlockDeps): ReconcileBlockCa
 
 		await certifyCandidates(deps, blockId, candidates);
 
-		const revClaims: RevClaim[] = candidates.map(({ peerId, rev, actionId, revCertified }) => ({
-			peerId, rev, actionId, ...(revCertified ? { certified: true } : {})
+		const revClaims: RevClaim[] = candidates.map(({ peerId, rev, actionId, revCertified, certifiedSignerCount }) => ({
+			peerId, rev, actionId,
+			...(revCertified ? { certified: true } : {}),
+			...(revCertified && certifiedSignerCount !== undefined ? { certifiedSignerCount } : {})
 		}));
 		const selected = selectQuorumRev(revClaims, deps.simpleMajorityThreshold, capacity);
 		if (!selected) {
@@ -381,9 +403,10 @@ export function createReconcileBlock(deps: ReconcileBlockDeps): ReconcileBlockCa
 			return;
 		}
 
-		// Detection is sound: selectQuorumBlock's certified branch fires iff exactly one distinct
-		// certified hash exists, so a defined `agreed` with a certified carrier at `agreed.hash` ⇔
-		// the certified rule won.
+		// A certified carrier at the agreed hash means a proof was verified against exactly these
+		// bytes — safe to persist whichever rule won the selection. (Since single-signer certified
+		// hashes stopped short-circuiting the quorum, the hash-quorum rule CAN win at a hash that
+		// also has a certified carrier; the proof still certifies those bytes.)
 		const certifiedCarrier = hashCandidates.find(c => c.certified === true && c.hash === agreed.hash);
 
 		// Contradicting-content penalties run ONLY on a corroborated win, mirroring the read path's