@optimystic/db-p2p 0.25.1 → 0.27.0

package/src/cluster/cluster-repo.ts

@@ -2,7 +2,7 @@ import type { IRepo, ClusterRecord, ClusterPeers, Signature, RepoMessage, ITrans
 import type { ICluster } from "@optimystic/db-core";
 import type { IPeerNetwork } from "@optimystic/db-core";
 import { blockIdsForTransforms, isOwnRevision, DEFAULT_SUPER_MAJORITY_THRESHOLD } from "@optimystic/db-core";
-import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clampPriority, clusterVoteSigningPayload, clusterVoteVerificationPayload } from "@optimystic/db-core";
+import { computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash, membershipDigest, recordMembershipDigest, clusterVoteSigningPayload, clusterVoteVerificationPayload } from "@optimystic/db-core";
 import { verifyInvalidationCertificate, type ArbitratorSetRecompute } from "../dispute/invalidation.js";
 import { buildCommitCert, invalidationActionId } from "./commit-cert.js";
 import { ClusterClient } from "./client.js";
@@ -19,7 +19,9 @@ import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "./i-transaction-state-store.js";
 import { isMissingBaseRevisionFailure, type CommitDigestPreview, type ICommitDigestPreviewer, type ICommitProofPersister, type IRevisionActionReader } from "../storage/storage-repo.js";
 import { checkPendValidation } from "../pend-validation.js";
-import { buildBlockCommitProof } from "./commit-proof.js";
+import { getAffectedBlockIds } from "./record-operations.js";
+import { operationsConflict, resolveRace } from "./race-resolution.js";
+import { buildBlockCommitProof, mintSoloCommitProof, type BlockCommitProof } from "./commit-proof.js";
 import { RECONCILE_TIMEOUT_MS } from "./reconcile-block.js";
 
 const log = createLogger('cluster-member')
@@ -132,13 +134,40 @@ 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 asserted
+ * that cannot derive a view (no FRET, unit tests): with no capability 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.
+ * asserted size still lets the gate fail closed on an unjustified downsize.
+ *
+ * Wiring this capability also arms the record-shape refusals: a member that CAN derive refuses outright
+ * (rather than falling back) when the record names no coordinating block, or names one the record's own
+ * operations never touch — those are the sender's free choice, not this member's inability. See
+ * {@link ClusterViewDerivation} and {@link ClusterMember} admission gate.
  */
 export type DeriveExpectedClusterCallback = (blockId: BlockId) => Promise<ExpectedClusterView>;
 
+/**
+ * Why a member does or does not have its own view of a record's cohort. The whole point of the union is
+ * that the caller MUST distinguish a fault of the RECEIVER (nothing to check against — stay lenient)
+ * from a fault of the SENDER (a record no current coordinator would build — refuse), a distinction a
+ * bare `undefined` erased and let a coordinator exploit: by choosing how it filled `coordinatingBlockIds`
+ * the coordinator chose which check every member ran.
+ *
+ * Module-internal on purpose — nothing outside this file consumes it.
+ */
+type ClusterViewDerivation =
+	/** The member resolved a view. Confidence / emptiness is judged by the caller, not here. */
+	| { kind: 'view'; view: ExpectedClusterView }
+	/** No {@link DeriveExpectedClusterCallback} wired (no FRET, unit tests): nothing to check against. */
+	| { kind: 'no-capability' }
+	/**
+	 * A usable block was named but the lookup itself failed. Receiver fault. Carries no payload: the
+	 * error is logged where it is caught, and the gate's response does not depend on which error it was.
+	 */
+	| { kind: 'underivable' }
+	/** The record names no block this member can legitimately derive from. Sender fault. */
+	| { kind: 'unusable-record'; variant: 'no-coordinating-block' }
+	| { kind: 'unusable-record'; variant: 'unbound-coordinating-block'; blockId: string; affected: number };
+
 /** Stable reject reason a member emits when a declared peer set fails the membership admission gate. */
 export const MEMBERSHIP_NOT_ADMITTED = 'membership-not-admitted';
 
@@ -182,6 +211,19 @@ interface ClusterMemberComponents {
 	recomputeArbitratorSet?: RecomputeArbitratorSetCapability;
 	/** Member-side cluster derivation for the membership admission gate; see {@link DeriveExpectedClusterCallback}. */
 	deriveExpectedCluster?: DeriveExpectedClusterCallback;
+	/**
+	 * Wall clock in unix milliseconds; defaults to `Date.now`. Injectable so a test can age a held
+	 * reservation past {@link CONFLICT_STALE_THRESHOLD_MS} without sleeping. It governs BOTH sides of
+	 * the reservation's `lastUpdate` — the stamp and the comparison — so the two can never end up on
+	 * different time bases.
+	 *
+	 * NOTE: partial injection, by design. This clock reaches ONLY `lastUpdate`; `message.expiration`,
+	 * the promise/resolution timeouts, the periodic expiry sweep and the executed-transaction TTL all
+	 * still read the real `Date.now`. So an injected clock must share an epoch with real time (seed it
+	 * from `Date.now()`, then advance) — one starting near zero makes every record look long expired
+	 * via the un-injected expiration check. Widen the injection if a test needs to drive expiry too.
+	 */
+	now?: () => number;
 }
 
 export function clusterMember(components: ClusterMemberComponents): ClusterMember {
@@ -201,13 +243,22 @@ export function clusterMember(components: ClusterMemberComponents): ClusterMembe
 		components.onCommitCertificate,
 		components.onInvalidate,
 		components.recomputeArbitratorSet,
-		components.deriveExpectedCluster
+		components.deriveExpectedCluster,
+		components.now
 	);
 }
 
 // How long to keep executed transaction records (10 minutes)
 const ExecutedTransactionTtlMs = 10 * 60 * 1000;
 
+/**
+ * How long a held reservation may go untouched before the conflict scan ({@link ClusterMember.findConflict})
+ * sweeps it. Generous relative to a round-trip: the scan frees an ABANDONED coordinator's blocks, so
+ * sweeping too eagerly would drop a live transaction whose next delivery is merely in flight.
+ * Exported so a test can advance an injected clock past it without restating the number.
+ */
+export const CONFLICT_STALE_THRESHOLD_MS = 2000;
+
 // Upper bound on an awaited active reconciliation of a divergent commit. Bounds the
 // consensus path so a slow/unreachable cohort peer can't stall the cluster stream;
 // a timeout is logged and tolerated (never thrown — that would reset the stream).
@@ -284,6 +335,8 @@ export class ClusterMember implements ICluster {
 	/** What a validator-configured member does with a pend carrying no `validation` payload — see
 	 * {@link ClusterConsensusConfig.unvalidatablePendPolicy}. Read once, like the gate parameters. */
 	private readonly unvalidatablePendPolicy: UnvalidatablePendPolicy;
+	/** Clock behind the reservation table's `lastUpdate` — see {@link ClusterMemberComponents.now}. */
+	private readonly now: () => number;
 
 	constructor(
 		private readonly storageRepo: IRepo,
@@ -302,8 +355,10 @@ export class ClusterMember implements ICluster {
 		private readonly onCommitCertificate?: CommitCertificateSink,
 		private readonly onInvalidate?: InvalidationApplySink,
 		private readonly recomputeArbitratorSet?: RecomputeArbitratorSetCapability,
-		private readonly deriveExpectedCluster?: DeriveExpectedClusterCallback
+		private readonly deriveExpectedCluster?: DeriveExpectedClusterCallback,
+		now?: () => number
 	) {
+		this.now = now ?? ((): number => Date.now());
 		this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? DEFAULT_SUPER_MAJORITY_THRESHOLD;
 		this.minAbsoluteClusterSize = consensusConfig?.minAbsoluteClusterSize ?? 3;
 		this.clusterSizeTolerance = consensusConfig?.clusterSizeTolerance ?? 0.5;
@@ -390,6 +445,17 @@ export class ClusterMember implements ICluster {
 		return this.executedCommitResults.get(messageHash);
 	}
 
+	/**
+	 * Self-sign a one-peer {@link BlockCommitProof} over `message` — a thin delegate to
+	 * {@link mintSoloCommitProof} with this member's own id and key. Lives here because this class is
+	 * the key holder: `CoordinatorRepo` (the caller, on its solo-cohort commit short-circuit) knows
+	 * the local peer id but never sees the private key. Nothing else moves — no record, no consensus
+	 * state; the mint is a pure signing operation over the message the caller built.
+	 */
+	async mintSoloCommitProof(message: RepoMessage): Promise<BlockCommitProof> {
+		return mintSoloCommitProof(this.peerId.toString(), this.privateKey, message);
+	}
+
 	/**
 	 * Handles an incoming cluster update, managing the two-phase commit process
 	 * and coordinating with the local storage repo
@@ -574,7 +640,7 @@ export class ClusterMember implements ICluster {
 			const timeouts = this.setupTimeouts(currentRecord);
 			this.activeTransactions.set(record.messageHash, {
 				record: currentRecord,
-				lastUpdate: Date.now(),
+				lastUpdate: this.now(),
 				promiseTimeout: timeouts.promiseTimeout,
 				resolutionTimeout: timeouts.resolutionTimeout
 			});
@@ -1047,8 +1113,16 @@ export class ClusterMember implements ICluster {
 	 *  3. **Consistency with the derived view** — `|D △ E|` within `clusterSizeTolerance·|E|`; honest churn
 	 *     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 — but it
+	 * **Inadmissible records come first.** Before any of that, a member that CAN derive refuses outright a
+	 * record whose coordinating block is the sender's free choice rather than a fact about the record: one
+	 * that names no coordinating block at all, or names a block the record's own operations never touch.
+	 * Those are defects of the SENDER, and no current coordinator produces them; treating them as "cannot
+	 * derive" would hand a dishonest coordinator the choice of which check every member ran. A member with
+	 * no derivation capability never reaches this refusal — it has nothing to check against.
+	 *
+	 * **Fail-closed posture.** When the member cannot confidently derive `E` — no capability, a bound
+	 * block whose lookup failed or returned an empty/low-confidence view (low FRET confidence is 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
@@ -1073,12 +1147,59 @@ export class ClusterMember implements ICluster {
 		}
 
 		// Explicit opt-in: knowingly transact below the safe floor (single-node / local dev). Skips the
-		// size/consistency gates but not self-membership above.
+		// size/consistency gates AND the record-shape refusals below, but not self-membership above: it
+		// already bypasses the far stronger confident predicates, so making a weaker check the one thing it
+		// cannot bypass would be incoherent.
 		if (this.allowUnvalidatedSmallCluster) {
 			return { admit: true };
 		}
 
-		const derived = await this.deriveExpectedClusterView(record);
+		const derivation = await this.deriveExpectedClusterView(record);
+
+		// Split the sender's faults from this member's own. A record that names no coordinating block, or
+		// names one its own operations never touch, is one no current coordinator builds (every production
+		// sender goes through `ClusterCoordinator.executeClusterTransaction`, which stamps a bound id) — so
+		// it is inadmissible, not merely underived. Collapsing these into the lenient fallback let a
+		// dishonest coordinator choose which check every member ran, just by how it filled one field.
+		// Exhaustive switch on purpose: a future `kind` must not silently join the lenient bucket.
+		switch (derivation.kind) {
+			case 'unusable-record': {
+				log('cluster-member:admission-reject', {
+					messageHash: record.messageHash,
+					reason: derivation.variant,
+					declaredSize: declared.length
+				});
+				// The count of affected block ids, not the list: this string is signed into the vote and lands
+				// in dispute records, so a wide multi-block pend must not produce an unbounded reason.
+				// NOTE: `blockId` itself is copied verbatim from the (untrusted) record and nothing upstream
+				// bounds its length — fine while block ids are short content hashes; if a record ever carries
+				// a pathological id, truncate it here rather than signing an arbitrarily large reason string.
+				// A fresh record carries no signatures, so `validateRecord` does not authenticate the sender
+				// before this point; what keeps it harmless is that the reason is bounded by the record the
+				// sender already transmitted (no amplification), not that the path is authenticated.
+				return {
+					admit: false,
+					reason: derivation.variant === 'no-coordinating-block'
+						? `${MEMBERSHIP_NOT_ADMITTED}:no-coordinating-block`
+						: `${MEMBERSHIP_NOT_ADMITTED}:unbound-coordinating-block (blockId=${derivation.blockId}, affected=${derivation.affected})`
+				};
+			}
+			// Receiver-side outcomes: a resolved view, no capability at all, or a bound block whose lookup
+			// failed. All three keep today's behaviour, judged below.
+			case 'view':
+			case 'no-capability':
+			case 'underivable':
+				break;
+			default: {
+				// `never` is the compile-time half of the guard: adding a `kind` without deciding its side
+				// of the sender/receiver split fails the build here. The runtime half returns a real
+				// verdict — fail closed — rather than the derivation object, which is not one.
+				const exhaustive: never = derivation;
+				return { admit: false, reason: `${MEMBERSHIP_NOT_ADMITTED}:${(exhaustive as { kind: string }).kind}` };
+			}
+		}
+
+		const derived = derivation.kind === 'view' ? derivation.view : undefined;
 		// An empty derived view (kEst === 0) carries no usable reference set: measured against it every
 		// non-empty declared set is wholly "inconsistent" (maxDiff = ceil(tol·0) = 0), which would spuriously
 		// reject a legitimate full cluster — a stricter, worse outcome than an absent view. Treat empty as
@@ -1180,23 +1301,43 @@ export class ClusterMember implements ICluster {
 	}
 
 	/**
-	 * 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, a coordinating block not bound
-	 * to the record's own operations, or a derivation error — all of which the gate treats as "not
-	 * confident"). Derived from the record's coordinating block, the same key the coordinator used to
-	 * select the cluster.
+	 * Derive this member's own view of the record's block cluster via the injected capability, reporting
+	 * *why* when it cannot — see {@link ClusterViewDerivation}. Four outcomes, deliberately not collapsed
+	 * into one `undefined`: the member has no capability; the lookup failed; the record named no
+	 * coordinating block; the record named a block its own operations never touch. The last two are the
+	 * sender's choices and {@link admitMembership} refuses them; the first two are this member's own
+	 * limitation and stay lenient. Derived from the record's coordinating block, the same key the
+	 * coordinator used to select the cluster.
 	 *
 	 * Read off `record.message`, NOT a top-level record field: `messageHash` covers the message only, so
 	 * only the in-message copy is tamper-evident to a relaying peer. (There is no top-level copy any more —
 	 * see {@link ClusterRecord.message}.)
 	 */
-	private async deriveExpectedClusterView(record: ClusterRecord): Promise<ExpectedClusterView | undefined> {
+	private async deriveExpectedClusterView(record: ClusterRecord): Promise<ClusterViewDerivation> {
+		// Capability check FIRST, before the record's field is even read: a member with nothing to derive
+		// against must never report a sender fault — it has no standing to judge the record's shape.
 		if (!this.deriveExpectedCluster) {
-			return undefined;
+			return { kind: 'no-capability' };
 		}
+		// NOTE: only `coordinatingBlockIds[0]` is read. A pend may declare the whole consolidated batch
+		// here; the gate needs one block to derive a cohort from, and the coordinator's choke point puts
+		// the cohort key it actually selected against at index 0.
 		const blockId = record.message.coordinatingBlockIds?.[0];
 		if (blockId === undefined) {
-			return undefined;
+			// Covers both an absent field and a present-but-empty array — distinct wire shapes, same
+			// defect: the record names nothing to derive from. Every production sender routes through
+			// `ClusterCoordinator.executeClusterTransaction`, which stamps a bound id when the message has
+			// none, so no honest record reaches here.
+			//
+			// No rolling-upgrade gate guards this refusal, and `membershipVersion` is NOT that gate:
+			// `validateRecord` accepts v1 and unversioned records, and the choke point that stamps the
+			// field onto commit/cancel records (`commit-and-cancel-records-omit-the-coordinating-block`)
+			// landed without bumping the version — so a peer on a build older than that one sends
+			// commit/cancel records this refuses. The decision is that cluster consensus deploys as one
+			// unit and this project makes no cross-build compatibility promise; if that ever changes,
+			// the gate belongs here (admit an unversioned record on the lenient path), not in the caller.
+			log('cluster-member:coordinating-block-absent', { messageHash: record.messageHash });
+			return { kind: 'unusable-record', variant: 'no-coordinating-block' };
 		}
 		// Hashing the field makes it tamper-evident to RELAYS, but the coordinator is the party this gate
 		// exists to check and it picks the field before it computes the hash. Unbound, a Byzantine
@@ -1206,14 +1347,21 @@ export class ClusterMember implements ICluster {
 		// record's OWN operations touch removes that free choice. `getAffectedBlockIds` is the same block
 		// extraction conflict detection already runs on this message — one definition, so the set a
 		// coordinating id must come from cannot drift from the set the record is judged to touch.
-		if (!this.getAffectedBlockIds(record.message.operations).includes(blockId)) {
+		const affected = getAffectedBlockIds(record.message.operations);
+		if (!affected.includes(blockId)) {
 			log('cluster-member:coordinating-block-unbound', {
 				messageHash: record.messageHash,
 				coordinatingBlockId: blockId
 			});
-			// Fail closed into the branch that already exists rather than throwing: a hard reject would
-			// change `validateRecord`'s failure surface, and "not confident" already refuses any downsize.
-			return undefined;
+			// Refuse, do not fall back: the fallback floor is the posture for a fault of THIS member, and
+			// letting a sender-chosen defect land there let the coordinator pick which check ran. Reported
+			// as a reject vote rather than a throw so the member emits a signed `reject` and dispute
+			// accounting keeps working — this stays out of `validateRecord`'s failure surface.
+			//
+			// `affected` is empty for a record with no operations, so any named block is unbound and the
+			// record is refused — correct (a record with no operations is malformed), and why `affected=0`
+			// can legitimately appear in the reason string.
+			return { kind: 'unusable-record', variant: 'unbound-coordinating-block', blockId, affected: affected.length };
 		}
 		// Which block a member derived its cohort view from is the single most useful fact when an
 		// admission decision has to be explained after the fact — and the only externally visible sign
@@ -1223,10 +1371,13 @@ export class ClusterMember implements ICluster {
 			// NOTE: derives (findCluster) once per inbound record on the promise path — one routing lookup
 			// per vote. If this shows up as hot, cache the derived view per (blockId, short TTL): it is a
 			// pure read of current topology, so a few-seconds-stale view is safe for admission.
-			return await this.deriveExpectedCluster(blockId as BlockId);
+			return { kind: 'view', view: await this.deriveExpectedCluster(blockId as BlockId) };
 		} catch (err) {
 			log('cluster-member:derive-expected-cluster-error', { messageHash: record.messageHash, error: (err as Error).message });
-			return undefined;
+			// Receiver fault: a bound block whose lookup threw. Stays lenient (the `assumedClusterSize`
+			// fallback) — that is the partition posture, and refusing here would make a transient routing
+			// hiccup refuse every write.
+			return { kind: 'underivable' };
 		}
 	}
 
@@ -2074,10 +2225,11 @@ export class ClusterMember implements ICluster {
 	 * entries are swept, and a held transaction that LOSES the race to `record` is cleared.
 	 */
 	private findConflict(record: ClusterRecord): { blockedBy: string } | undefined {
-		const now = Date.now();
-		const staleThresholdMs = 2000; // 2 seconds - allow more time for distributed consensus
+		// Same clock as the `lastUpdate` stamp (the `shouldPersist` set and `persistParticipantState`),
+		// so an injected test clock ages entries instead of putting stamp and comparison on different bases.
+		const now = this.now();
 
-		const incomingBlockIds = this.getAffectedBlockIds(record.message.operations);
+		const incomingBlockIds = getAffectedBlockIds(record.message.operations);
 		log('cluster-member:findConflict-check', {
 			messageHash: record.messageHash,
 			activeCount: this.activeTransactions.size,
@@ -2085,11 +2237,18 @@ export class ClusterMember implements ICluster {
 		});
 
 		for (const [existingHash, state] of Array.from(this.activeTransactions.entries())) {
+			// Defensive only — no caller can reach it today. `getTransactionPhase` calls this scan solely
+			// when `!record.promises[ourId]`, and every write into `activeTransactions` already carries our
+			// vote (the `shouldPersist` set happens after the phase loop recorded it; `recoverTransactions`
+			// restores what that same branch persisted; `handleExpiration` re-sets with our reject added).
+			// A redelivery at a known hash is merged with the held record first (`mergeRecords`, first-seen
+			// wins), so our vote is present by the time the phase is computed. Kept because the scan is on
+			// the vote path, where self-blocking would be silent and permanent.
 			if (existingHash === record.messageHash) {
 				continue;
 			}
 
-			const existingBlockIds = this.getAffectedBlockIds(state.record.message.operations);
+			const existingBlockIds = getAffectedBlockIds(state.record.message.operations);
 			log('cluster-member:findConflict-compare', {
 				existing: existingHash,
 				incoming: record.messageHash,
@@ -2097,8 +2256,9 @@ export class ClusterMember implements ICluster {
 				incomingBlockIds
 			});
 
-			// Clean up stale transactions that have been around too long
-			if (now - state.lastUpdate > staleThresholdMs) {
+			// Sweep abandoned reservations BEFORE the race is decided: an entry nobody is driving any
+			// more must not win a contest it should not be in and block a live rival for its whole life.
+			if (now - state.lastUpdate > CONFLICT_STALE_THRESHOLD_MS) {
 				log('cluster-member:stale-cleanup', {
 					messageHash: existingHash,
 					age: now - state.lastUpdate
@@ -2107,9 +2267,9 @@ export class ClusterMember implements ICluster {
 				continue;
 			}
 
-			if (this.operationsConflict(state.record.message.operations, record.message.operations)) {
+			if (operationsConflict(state.record.message.operations, record.message.operations)) {
 				// Use race resolution to determine winner
-				const resolution = this.resolveRace(state.record, record);
+				const resolution = resolveRace(state.record, record);
 
 				if (resolution === 'keep-existing') {
 					log('cluster-member:race-keep-existing', {
@@ -2124,7 +2284,10 @@ export class ClusterMember implements ICluster {
 						incoming: record.messageHash
 					});
 					this.clearTransaction(existingHash);
-					continue; // Check other conflicts
+					// `continue`, not `break`: the incoming transaction may overlap several held
+					// reservations, and beating one says nothing about the rest. Stopping here would let it
+					// walk past a second, still-live rival it actually loses to.
+					continue;
 				}
 			}
 		}
@@ -2132,182 +2295,6 @@ export class ClusterMember implements ICluster {
 		return undefined; // No blocking conflicts
 	}
 
-	/** Number of *approve* promise votes on a record — the count the commit rule uses. */
-	private static 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 {@link findConflict}) 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).
-	 */
-	private 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 = ClusterMember.approvalCount(existing);
-		const incomingCount = ClusterMember.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 = this.recordPriority(existing);
-		const incomingPriority = this.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), i.e. between two still-open conflicting
-	 * transactions, which is exactly the concurrent-contention case priority is meant to order.
-	 */
-	private 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;
-	}
-
-	private 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 = this.getActionId(ops1);
-		const actionId2 = this.getActionId(ops2);
-		if (actionId1 && actionId2 && actionId1 === actionId2) {
-			// Same action - commit is resolving the pend, not conflicting
-			return false;
-		}
-
-		const blocks1 = new Set(this.getAffectedBlockIds(ops1));
-		const blocks2 = new Set(this.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;
-	}
-
-	private getActionId(operations: RepoMessage['operations']): string | undefined {
-		for (const operation of operations) {
-			if ('pend' in operation) {
-				return operation.pend.actionId;
-			} else if ('commit' in operation) {
-				return operation.commit.actionId;
-			} else if ('cancel' in operation) {
-				return operation.cancel.actionRef.actionId;
-			}
-		}
-		return undefined;
-	}
-
-	/**
-	 * Every block id the message's own operations name. Two consumers, deliberately sharing one
-	 * definition: conflict detection (which writes must serialize against each other) and the membership
-	 * admission gate's binding check (the set a legitimate `coordinatingBlockIds[0]` must come from —
-	 * {@link ClusterMember.deriveExpectedClusterView}). If the two ever disagreed, a coordinator could
-	 * name a block the record is not judged to touch.
-	 */
-	private getAffectedBlockIds(operations: RepoMessage['operations']): string[] {
-		const blockIds = new Set<string>();
-
-		for (const operation of operations) {
-			if ('get' in operation) {
-				operation.get.blockIds.forEach(id => blockIds.add(id));
-			} else if ('pend' in operation) {
-				// Use blockIdsForTransforms to correctly extract block IDs from Transforms structure
-				blockIdsForTransforms(operation.pend.transforms).forEach(id => blockIds.add(id));
-			} else if ('commit' in operation) {
-				operation.commit.blockIds.forEach(id => blockIds.add(id));
-			} else if ('cancel' in operation) {
-				operation.cancel.actionRef.blockIds.forEach(id => blockIds.add(id));
-			} else if ('invalidate' in operation) {
-				// The invalidation writes compensating revisions to these blocks; surfacing them lets
-				// conflict detection serialize a concurrent commit racing the invalidation on a block.
-				operation.invalidate.blockIds.forEach(id => blockIds.add(id));
-			}
-		}
-
-		return Array.from(blockIds);
-	}
-
 	private async propagateIfNeeded(record: ClusterRecord): Promise<void> {
 		const promises = [];
 		for (const peerId of Object.keys(record.peers)) {
@@ -2439,7 +2426,7 @@ export class ClusterMember implements ICluster {
 		this.stateStore.saveParticipantState(messageHash, {
 			messageHash,
 			record,
-			lastUpdate: Date.now()
+			lastUpdate: this.now()
 		}).catch(err => log('cluster-member:persist-error', { messageHash, error: (err as Error).message }));
 	}
 

package/src/cluster/commit-proof.ts

@@ -1,11 +1,14 @@
 import type { ActionId, BlockId, ClusterRecord, IBlock, RepoMessage, Signature, CommitRequest } from "@optimystic/db-core";
 import {
-	canonicalBlockHash, clusterVoteVerificationPayload, computeClusterCommitHash,
-	computeClusterMessageHash, computeClusterPromiseHash, membershipDigestFromIds
+	canonicalBlockHash, clusterVoteSigningPayload, clusterVoteVerificationPayload,
+	computeClusterCommitHash, computeClusterMessageHash, computeClusterPromiseHash,
+	membershipDigestFromIds
 } from "@optimystic/db-core";
+import type { PrivateKey } from "@libp2p/interface";
 import { peerIdFromString } from "@libp2p/peer-id";
 import { publicKeyFromRaw } from "@libp2p/crypto/keys";
 import { fromString as uint8ArrayFromString } from "uint8arrays/from-string";
+import { toString as uint8ArrayToString } from "uint8arrays/to-string";
 
 /**
  * A durable, self-contained proof that a cluster cohort agreed on a commit — everything an offline
@@ -91,6 +94,39 @@ export function buildBlockCommitProof(record: ClusterRecord): BlockCommitProof |
 	};
 }
 
+/**
+ * Mint a fully-signed one-peer {@link BlockCommitProof} — the producing sibling of
+ * {@link verifyBlockCommitProofClaim}, kept in this file so the hash recipe the two must agree on
+ * lives in one place. Used by the solo-cohort commit path (`CoordinatorRepo.commit`'s
+ * `peerCount <= 1` short-circuit), where consensus never runs and there is no {@link ClusterRecord}
+ * to project: the lone member IS the whole cohort, so it signs both rounds itself over a one-peer
+ * membership. The artifact stays honest — "one peer, which was the whole cohort at the time,
+ * committed these bytes at this revision" — and verifies offline from the peer id alone, exactly
+ * like a consensus-produced proof: `ceil(0.75 × 1) = 1` approve satisfies the promise round and
+ * `1 > 1 × 0.5` the commit round under the production thresholds.
+ *
+ * The promise round is signed FIRST: the commit hash's preimage includes the promises map
+ * (`computeClusterCommitHash`), so the order is load-bearing, not stylistic.
+ */
+export async function mintSoloCommitProof(
+	peerId: string, privateKey: PrivateKey, message: RepoMessage
+): Promise<BlockCommitProof> {
+	const membershipDigest = await membershipDigestFromIds([peerId]);
+	const messageHash = await computeClusterMessageHash(message, membershipDigest);
+	const signApprove = async (hash: string): Promise<Signature> => ({
+		type: 'approve',
+		signature: uint8ArrayToString(await privateKey.sign(clusterVoteSigningPayload(hash, 'approve')), 'base64url')
+	});
+	const promiseHash = await computeClusterPromiseHash(messageHash, message, membershipDigest);
+	const promises: Record<string, Signature> = { [peerId]: await signApprove(promiseHash) };
+	const commitHash = await computeClusterCommitHash(messageHash, message, promises, membershipDigest);
+	const commits: Record<string, Signature> = { [peerId]: await signApprove(commitHash) };
+	return {
+		v: 1, messageHash, message, promises, commits,
+		membershipVersion: 2, membershipDigest, peerIds: [peerId]
+	};
+}
+
 /**
  * Verify that `proof` certifies the CLAIM — `claim.blockId` at `claim.rev` under `claim.actionId` —
  * without needing the block bytes. Pure and total on hostile input: never throws; every failure is a