@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/cluster/persistent-transaction-state-store.ts

@@ -1,92 +1,92 @@
-import type { IKVStore } from "../storage/i-kv-store.js";
-import type { ITransactionStateStore, PersistedCoordinatorState, PersistedParticipantState } from "./i-transaction-state-store.js";
-
-/**
- * ITransactionStateStore backed by an IKVStore for cross-platform persistence.
- *
- * Key namespace:
- *   coordinator/{messageHash}  → JSON(PersistedCoordinatorState)
- *   participant/{messageHash}  → JSON(PersistedParticipantState)
- *   executed/{messageHash}     → JSON({ timestamp: number })
- */
-export class PersistentTransactionStateStore implements ITransactionStateStore {
-	constructor(private readonly kv: IKVStore) {}
-
-	// --- Coordinator ---
-
-	async saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void> {
-		await this.kv.set(`coordinator/${messageHash}`, JSON.stringify(state));
-	}
-
-	async getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined> {
-		const raw = await this.kv.get(`coordinator/${messageHash}`);
-		return raw ? JSON.parse(raw) as PersistedCoordinatorState : undefined;
-	}
-
-	async deleteCoordinatorState(messageHash: string): Promise<void> {
-		await this.kv.delete(`coordinator/${messageHash}`);
-	}
-
-	async getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]> {
-		const keys = await this.kv.list('coordinator/');
-		const results: PersistedCoordinatorState[] = [];
-		for (const key of keys) {
-			const raw = await this.kv.get(key);
-			if (raw) {
-				results.push(JSON.parse(raw) as PersistedCoordinatorState);
-			}
-		}
-		return results;
-	}
-
-	// --- Participant ---
-
-	async saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void> {
-		await this.kv.set(`participant/${messageHash}`, JSON.stringify(state));
-	}
-
-	async getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined> {
-		const raw = await this.kv.get(`participant/${messageHash}`);
-		return raw ? JSON.parse(raw) as PersistedParticipantState : undefined;
-	}
-
-	async deleteParticipantState(messageHash: string): Promise<void> {
-		await this.kv.delete(`participant/${messageHash}`);
-	}
-
-	async getAllParticipantStates(): Promise<PersistedParticipantState[]> {
-		const keys = await this.kv.list('participant/');
-		const results: PersistedParticipantState[] = [];
-		for (const key of keys) {
-			const raw = await this.kv.get(key);
-			if (raw) {
-				results.push(JSON.parse(raw) as PersistedParticipantState);
-			}
-		}
-		return results;
-	}
-
-	// --- Executed ---
-
-	async markExecuted(messageHash: string, timestamp: number): Promise<void> {
-		await this.kv.set(`executed/${messageHash}`, JSON.stringify({ timestamp }));
-	}
-
-	async wasExecuted(messageHash: string): Promise<boolean> {
-		const raw = await this.kv.get(`executed/${messageHash}`);
-		return raw !== undefined;
-	}
-
-	async pruneExecuted(olderThan: number): Promise<void> {
-		const keys = await this.kv.list('executed/');
-		for (const key of keys) {
-			const raw = await this.kv.get(key);
-			if (raw) {
-				const { timestamp } = JSON.parse(raw) as { timestamp: number };
-				if (timestamp < olderThan) {
-					await this.kv.delete(key);
-				}
-			}
-		}
-	}
-}
+import type { IKVStore } from "../storage/i-kv-store.js";
+import type { ITransactionStateStore, PersistedCoordinatorState, PersistedParticipantState } from "./i-transaction-state-store.js";
+
+/**
+ * ITransactionStateStore backed by an IKVStore for cross-platform persistence.
+ *
+ * Key namespace:
+ *   coordinator/{messageHash}  → JSON(PersistedCoordinatorState)
+ *   participant/{messageHash}  → JSON(PersistedParticipantState)
+ *   executed/{messageHash}     → JSON({ timestamp: number })
+ */
+export class PersistentTransactionStateStore implements ITransactionStateStore {
+	constructor(private readonly kv: IKVStore) {}
+
+	// --- Coordinator ---
+
+	async saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void> {
+		await this.kv.set(`coordinator/${messageHash}`, JSON.stringify(state));
+	}
+
+	async getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined> {
+		const raw = await this.kv.get(`coordinator/${messageHash}`);
+		return raw ? JSON.parse(raw) as PersistedCoordinatorState : undefined;
+	}
+
+	async deleteCoordinatorState(messageHash: string): Promise<void> {
+		await this.kv.delete(`coordinator/${messageHash}`);
+	}
+
+	async getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]> {
+		const keys = await this.kv.list('coordinator/');
+		const results: PersistedCoordinatorState[] = [];
+		for (const key of keys) {
+			const raw = await this.kv.get(key);
+			if (raw) {
+				results.push(JSON.parse(raw) as PersistedCoordinatorState);
+			}
+		}
+		return results;
+	}
+
+	// --- Participant ---
+
+	async saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void> {
+		await this.kv.set(`participant/${messageHash}`, JSON.stringify(state));
+	}
+
+	async getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined> {
+		const raw = await this.kv.get(`participant/${messageHash}`);
+		return raw ? JSON.parse(raw) as PersistedParticipantState : undefined;
+	}
+
+	async deleteParticipantState(messageHash: string): Promise<void> {
+		await this.kv.delete(`participant/${messageHash}`);
+	}
+
+	async getAllParticipantStates(): Promise<PersistedParticipantState[]> {
+		const keys = await this.kv.list('participant/');
+		const results: PersistedParticipantState[] = [];
+		for (const key of keys) {
+			const raw = await this.kv.get(key);
+			if (raw) {
+				results.push(JSON.parse(raw) as PersistedParticipantState);
+			}
+		}
+		return results;
+	}
+
+	// --- Executed ---
+
+	async markExecuted(messageHash: string, timestamp: number): Promise<void> {
+		await this.kv.set(`executed/${messageHash}`, JSON.stringify({ timestamp }));
+	}
+
+	async wasExecuted(messageHash: string): Promise<boolean> {
+		const raw = await this.kv.get(`executed/${messageHash}`);
+		return raw !== undefined;
+	}
+
+	async pruneExecuted(olderThan: number): Promise<void> {
+		const keys = await this.kv.list('executed/');
+		for (const key of keys) {
+			const raw = await this.kv.get(key);
+			if (raw) {
+				const { timestamp } = JSON.parse(raw) as { timestamp: number };
+				if (timestamp < olderThan) {
+					await this.kv.delete(key);
+				}
+			}
+		}
+	}
+}

package/src/cluster/quorum-restore.ts

@@ -1,223 +1,223 @@
-import type { IBlock } from "@optimystic/db-core";
-import { sha256 } from "multiformats/hashes/sha2";
-import { toString as uint8ArrayToString } from 'uint8arrays';
-
-/**
- * Quorum-corroboration helpers shared by the two block-restoration paths:
- *   - read-repair   (`CoordinatorRepo.queryClusterForLatest`)
- *   - reconcile     (`libp2p-node-base.reconcileBlock`)
- *
- * Both paths previously trusted a single peer's self-reported "latest" (max rev
- * wins), so one lying peer could steer restoration. These helpers replace
- * "max wins" with "highest value corroborated by a quorum of distinct peers".
- *
- * NOTE: the quorum here is corroboration-of-a-claim, NOT Sybil-resistant cohort
- * membership. A peer minting fresh keypairs can still cast a vote — proving a
- * voter is a legitimate cohort member requires commit-cert + membership
- * anchoring, deferred to backlog `debt-read-repair-commit-cert-verification`.
- */
-
-/** A single peer's self-reported (rev, actionId) for a block. */
-export interface RevClaim {
-	/** Distinct voter identity (peer-id string). One vote per distinct peerId per group. */
-	peerId: string;
-	rev: number;
-	actionId: string;
-}
-
-/** The (rev, actionId) pair a quorum agreed on, plus the peers that corroborated it. */
-export interface QuorumRev {
-	rev: number;
-	actionId: string;
-	/** Distinct peer-ids that voted for this exact (rev, actionId). */
-	supporters: string[];
-}
-
-/**
- * Votes a claim needs when the cohort is big enough to supply them: a claim must be
- * seconded by a second, independent peer. See {@link quorumSize} for the cap that
- * applies when the cohort is smaller than this.
- */
-const CORROBORATION_FLOOR = 2;
-
-/**
- * Number of distinct corroborating votes required to accept a claim:
- * `floor(simpleMajorityThreshold × responderCount)`, never below
- * {@link CORROBORATION_FLOOR} — except that demanding more corroborators than the cohort
- * can possibly supply is a deadlock, not a safety property, so the floor is additionally
- * capped at `corroboratorCapacity`.
- *
- * `corroboratorCapacity` is how many peers OTHER than the asking node could answer at
- * all. Omit it when the caller cannot state one; the absolute floor of two then applies,
- * which is the conservative direction (a claim no one seconded is never accepted).
- *
- * Note the capacity caps the FLOOR only, never the proportional term: with many
- * responders the majority requirement still grows past two.
- */
-export function quorumSize(
-	responderCount: number,
-	simpleMajorityThreshold: number,
-	corroboratorCapacity: number = Number.POSITIVE_INFINITY
-): number {
-	const floor = Math.max(1, Math.min(CORROBORATION_FLOOR, corroboratorCapacity));
-	return Math.max(floor, Math.floor(simpleMajorityThreshold * responderCount));
-}
-
-/**
- * The `corroboratorCapacity` to hand {@link quorumSize}: how many peers other than the asking node
- * could answer for a block at all, given `cohortPeerCount` peers currently visible (self already
- * excluded) and `repairCorroborationClusterSize` — the cohort size this deployment is measured
- * against, resolved by `resolveClusterPolicy` in `cluster/cluster-policy.ts`.
- *
- * Deliberately the MAX of the two: the corroboration floor may be relaxed only for a cohort that is
- * *genuinely* small, never for one that merely looks small. Cohort views are unauthenticated — the
- * read path takes them from `IKeyNetwork.findCluster`, the commit path from a coordinator-declared
- * peer set — so a partition, a self-shrunk record, or an attacker with routing influence could
- * otherwise talk the requirement down to a single voter. Measuring against the resolved size keeps a
- * shrunken view out of the relaxed branch.
- *
- * An unconfigured node resolves this to its `clusterSize` (default 10), so the floor of two binds and
- * a shrunken view gains nothing. The escape hatch for a real two-node deployment is one explicit
- * operator declaration — `clusterPolicy.assumedClusterSize: 2`, which does NOT also drop the
- * replication factor, or an honest `clusterSize: 2`.
- *
- * Shared by both restoration paths so the two can never drift apart on the rule that decides how
- * much trust a lone peer gets.
- */
-export function corroboratorCapacity(cohortPeerCount: number, repairCorroborationClusterSize: number): number {
-	return Math.max(cohortPeerCount, repairCorroborationClusterSize - 1);
-}
-
-/**
- * Select the highest revision corroborated by a quorum of distinct peers.
- *
- * Claims are grouped by the exact `(rev, actionId)` pair; a liar's fabricated
- * pair lands in its own singleton group and is outvoted. The highest rev whose
- * group has `>= quorum` distinct voters wins.
- *
- * **Claims must not include the asking node's own revision.** A node confirming its own
- * answer is not evidence; its revision is the baseline being repaired, and counting it
- * both inflates the responder count and lets a lone reader "corroborate" itself. Callers
- * filter self out before calling (see `CoordinatorRepo.queryClusterForLatest`,
- * `reconcileBlock`).
- *
- * `corroboratorCapacity` — how many peers other than the asking node could corroborate at
- * all — lets a genuinely tiny cohort still converge: a cohort with exactly one other peer
- * cannot produce two corroborators, so requiring two makes divergence permanent rather
- * than making it safe. Pass a capacity that a shrunken view of the network cannot talk
- * down (see {@link corroboratorCapacity}), or omit it to keep the floor at two.
- *
- * Returns `undefined` when nothing is corroborated — an uncorroborated claim
- * must never drive restoration.
- */
-export function selectQuorumRev(
-	claims: RevClaim[],
-	simpleMajorityThreshold: number,
-	corroboratorCapacity?: number
-): QuorumRev | undefined {
-	if (claims.length === 0) return undefined;
-
-	const groups = new Map<string, { rev: number; actionId: string; supporters: Set<string> }>();
-	const responders = new Set<string>();
-	for (const c of claims) {
-		responders.add(c.peerId);
-		const key = `${c.rev}\0${c.actionId}`;
-		let g = groups.get(key);
-		if (!g) {
-			g = { rev: c.rev, actionId: c.actionId, supporters: new Set() };
-			groups.set(key, g);
-		}
-		g.supporters.add(c.peerId);
-	}
-
-	const quorum = quorumSize(responders.size, simpleMajorityThreshold, corroboratorCapacity);
-
-	// Highest rev whose (rev, actionId) group meets quorum. There is deliberately no
-	// "too few responders, but they all agree" fallback: that rule fired at ANY cohort
-	// size, so a lone responder in a large cohort — where a second corroborator does
-	// exist and simply did not answer within the per-peer timeout — was accepted on its
-	// own word. `corroboratorCapacity` expresses the same permissiveness where it is
-	// actually justified (a cohort that cannot supply a second corroborator) and nowhere
-	// else.
-	let best: { rev: number; actionId: string; supporters: Set<string> } | undefined;
-	for (const g of groups.values()) {
-		if (g.supporters.size >= quorum && (!best || g.rev > best.rev)) {
-			best = g;
-		}
-	}
-	return best
-		? { rev: best.rev, actionId: best.actionId, supporters: [...best.supporters] }
-		: undefined;
-}
-
-/** Deterministic JSON: sorts object keys so the hash is order-independent. Mirrors `ClusterMember.canonicalJson`. */
-function canonicalJson(value: unknown): string {
-	return JSON.stringify(value, (_, v) =>
-		v && typeof v === 'object' && !Array.isArray(v)
-			? Object.keys(v).sort().reduce((o: Record<string, unknown>, k) => { o[k] = v[k]; return o; }, {})
-			: v
-	);
-}
-
-/** Canonical sha256 of a block's content, base64url. Same pattern as `ClusterMember.computeCommitHash`. */
-export async function canonicalBlockHash(block: IBlock): Promise<string> {
-	const bytes = new TextEncoder().encode(canonicalJson(block));
-	const digest = await sha256.digest(bytes);
-	return uint8ArrayToString(digest.digest, 'base64url');
-}
-
-/** One block candidate paired with its serving peer and canonical hash. */
-export interface BlockHashCandidate {
-	peerId: string;
-	hash: string;
-	block: IBlock;
-}
-
-/**
- * Among candidates already known to corroborate the target `(rev, actionId)`,
- * pick the block content agreed by a quorum. Requires a UNIQUE hash group meeting
- * `quorum` — a cohort split on content declines rather than picking a side.
- * Returns the agreed block, or `undefined`.
- *
- * `corroboratorCapacity` caps the floor exactly as it does in {@link selectQuorumRev}, and for
- * the same reason: a cohort holding one other peer cannot produce two block-carriers, so
- * demanding two makes the block permanently unrestorable on this node rather than making it safe.
- * Omit it to keep the floor at two.
- *
- * **What relaxing this does and does not cost.** Block ids are random 256-bit strings, not
- * content-addressed, so {@link canonicalBlockHash} is a cross-peer *agreement* hash and never a
- * check against the requested id — nothing here re-derives an id from received bytes. At capacity
- * one the sole peer's content is therefore taken on its word. That extends no trust the cohort had
- * not already extended: the same peer's `(rev, actionId)` claim is equally uncorroborable at that
- * size, and a two-member cohort has no honest majority to appeal to. Pass a capacity a shrunken
- * view of the network cannot talk down (see {@link corroboratorCapacity}), so only a cohort that is
- * *genuinely* that small reaches this branch.
- */
-export function selectQuorumBlock(
-	candidates: BlockHashCandidate[],
-	simpleMajorityThreshold: number,
-	corroboratorCapacity?: number
-): { block: IBlock; hash: string } | undefined {
-	if (candidates.length === 0) return undefined;
-
-	// 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.
-	const groups = new Map<string, { block: IBlock; supporters: Set<string> }>();
-	const voters = new Set<string>();
-	for (const c of candidates) {
-		voters.add(c.peerId);
-		let g = groups.get(c.hash);
-		if (!g) {
-			g = { block: c.block, supporters: new Set() };
-			groups.set(c.hash, g);
-		}
-		g.supporters.add(c.peerId);
-	}
-
-	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 };
-}
+import type { IBlock } from "@optimystic/db-core";
+import { sha256 } from "multiformats/hashes/sha2";
+import { toString as uint8ArrayToString } from 'uint8arrays';
+
+/**
+ * Quorum-corroboration helpers shared by the two block-restoration paths:
+ *   - read-repair   (`CoordinatorRepo.queryClusterForLatest`)
+ *   - reconcile     (`libp2p-node-base.reconcileBlock`)
+ *
+ * Both paths previously trusted a single peer's self-reported "latest" (max rev
+ * wins), so one lying peer could steer restoration. These helpers replace
+ * "max wins" with "highest value corroborated by a quorum of distinct peers".
+ *
+ * NOTE: the quorum here is corroboration-of-a-claim, NOT Sybil-resistant cohort
+ * membership. A peer minting fresh keypairs can still cast a vote — proving a
+ * voter is a legitimate cohort member requires commit-cert + membership
+ * anchoring, deferred to backlog `debt-read-repair-commit-cert-verification`.
+ */
+
+/** A single peer's self-reported (rev, actionId) for a block. */
+export interface RevClaim {
+	/** Distinct voter identity (peer-id string). One vote per distinct peerId per group. */
+	peerId: string;
+	rev: number;
+	actionId: string;
+}
+
+/** The (rev, actionId) pair a quorum agreed on, plus the peers that corroborated it. */
+export interface QuorumRev {
+	rev: number;
+	actionId: string;
+	/** Distinct peer-ids that voted for this exact (rev, actionId). */
+	supporters: string[];
+}
+
+/**
+ * Votes a claim needs when the cohort is big enough to supply them: a claim must be
+ * seconded by a second, independent peer. See {@link quorumSize} for the cap that
+ * applies when the cohort is smaller than this.
+ */
+export const CORROBORATION_FLOOR = 2;
+
+/**
+ * Number of distinct corroborating votes required to accept a claim:
+ * `floor(simpleMajorityThreshold × responderCount)`, never below
+ * {@link CORROBORATION_FLOOR} — except that demanding more corroborators than the cohort
+ * can possibly supply is a deadlock, not a safety property, so the floor is additionally
+ * capped at `corroboratorCapacity`.
+ *
+ * `corroboratorCapacity` is how many peers OTHER than the asking node could answer at
+ * all. Omit it when the caller cannot state one; the absolute floor of two then applies,
+ * which is the conservative direction (a claim no one seconded is never accepted).
+ *
+ * Note the capacity caps the FLOOR only, never the proportional term: with many
+ * responders the majority requirement still grows past two.
+ */
+export function quorumSize(
+	responderCount: number,
+	simpleMajorityThreshold: number,
+	corroboratorCapacity: number = Number.POSITIVE_INFINITY
+): number {
+	const floor = Math.max(1, Math.min(CORROBORATION_FLOOR, corroboratorCapacity));
+	return Math.max(floor, Math.floor(simpleMajorityThreshold * responderCount));
+}
+
+/**
+ * The `corroboratorCapacity` to hand {@link quorumSize}: how many peers other than the asking node
+ * could answer for a block at all, given `cohortPeerCount` peers currently visible (self already
+ * excluded) and `repairCorroborationClusterSize` — the cohort size this deployment is measured
+ * against, resolved by `resolveClusterPolicy` in `cluster/cluster-policy.ts`.
+ *
+ * Deliberately the MAX of the two: the corroboration floor may be relaxed only for a cohort that is
+ * *genuinely* small, never for one that merely looks small. Cohort views are unauthenticated — the
+ * read path takes them from `IKeyNetwork.findCluster`, the commit path from a coordinator-declared
+ * peer set — so a partition, a self-shrunk record, or an attacker with routing influence could
+ * otherwise talk the requirement down to a single voter. Measuring against the resolved size keeps a
+ * shrunken view out of the relaxed branch.
+ *
+ * An unconfigured node resolves this to its `clusterSize` (default 10), so the floor of two binds and
+ * a shrunken view gains nothing. The escape hatch for a real two-node deployment is one explicit
+ * operator declaration — `clusterPolicy.assumedClusterSize: 2`, which does NOT also drop the
+ * replication factor, or an honest `clusterSize: 2`.
+ *
+ * Shared by both restoration paths so the two can never drift apart on the rule that decides how
+ * much trust a lone peer gets.
+ */
+export function corroboratorCapacity(cohortPeerCount: number, repairCorroborationClusterSize: number): number {
+	return Math.max(cohortPeerCount, repairCorroborationClusterSize - 1);
+}
+
+/**
+ * Select the highest revision corroborated by a quorum of distinct peers.
+ *
+ * Claims are grouped by the exact `(rev, actionId)` pair; a liar's fabricated
+ * pair lands in its own singleton group and is outvoted. The highest rev whose
+ * group has `>= quorum` distinct voters wins.
+ *
+ * **Claims must not include the asking node's own revision.** A node confirming its own
+ * answer is not evidence; its revision is the baseline being repaired, and counting it
+ * both inflates the responder count and lets a lone reader "corroborate" itself. Callers
+ * filter self out before calling (see `CoordinatorRepo.queryClusterForLatest`,
+ * `reconcileBlock`).
+ *
+ * `corroboratorCapacity` — how many peers other than the asking node could corroborate at
+ * all — lets a genuinely tiny cohort still converge: a cohort with exactly one other peer
+ * cannot produce two corroborators, so requiring two makes divergence permanent rather
+ * than making it safe. Pass a capacity that a shrunken view of the network cannot talk
+ * down (see {@link corroboratorCapacity}), or omit it to keep the floor at two.
+ *
+ * Returns `undefined` when nothing is corroborated — an uncorroborated claim
+ * must never drive restoration.
+ */
+export function selectQuorumRev(
+	claims: RevClaim[],
+	simpleMajorityThreshold: number,
+	corroboratorCapacity?: number
+): QuorumRev | undefined {
+	if (claims.length === 0) return undefined;
+
+	const groups = new Map<string, { rev: number; actionId: string; supporters: Set<string> }>();
+	const responders = new Set<string>();
+	for (const c of claims) {
+		responders.add(c.peerId);
+		const key = `${c.rev}\0${c.actionId}`;
+		let g = groups.get(key);
+		if (!g) {
+			g = { rev: c.rev, actionId: c.actionId, supporters: new Set() };
+			groups.set(key, g);
+		}
+		g.supporters.add(c.peerId);
+	}
+
+	const quorum = quorumSize(responders.size, simpleMajorityThreshold, corroboratorCapacity);
+
+	// Highest rev whose (rev, actionId) group meets quorum. There is deliberately no
+	// "too few responders, but they all agree" fallback: that rule fired at ANY cohort
+	// size, so a lone responder in a large cohort — where a second corroborator does
+	// exist and simply did not answer within the per-peer timeout — was accepted on its
+	// own word. `corroboratorCapacity` expresses the same permissiveness where it is
+	// actually justified (a cohort that cannot supply a second corroborator) and nowhere
+	// else.
+	let best: { rev: number; actionId: string; supporters: Set<string> } | undefined;
+	for (const g of groups.values()) {
+		if (g.supporters.size >= quorum && (!best || g.rev > best.rev)) {
+			best = g;
+		}
+	}
+	return best
+		? { rev: best.rev, actionId: best.actionId, supporters: [...best.supporters] }
+		: undefined;
+}
+
+/** Deterministic JSON: sorts object keys so the hash is order-independent. Mirrors `ClusterMember.canonicalJson`. */
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_, v) =>
+		v && typeof v === 'object' && !Array.isArray(v)
+			? Object.keys(v).sort().reduce((o: Record<string, unknown>, k) => { o[k] = v[k]; return o; }, {})
+			: v
+	);
+}
+
+/** Canonical sha256 of a block's content, base64url. Same pattern as `ClusterMember.computeCommitHash`. */
+export async function canonicalBlockHash(block: IBlock): Promise<string> {
+	const bytes = new TextEncoder().encode(canonicalJson(block));
+	const digest = await sha256.digest(bytes);
+	return uint8ArrayToString(digest.digest, 'base64url');
+}
+
+/** One block candidate paired with its serving peer and canonical hash. */
+export interface BlockHashCandidate {
+	peerId: string;
+	hash: string;
+	block: IBlock;
+}
+
+/**
+ * Among candidates already known to corroborate the target `(rev, actionId)`,
+ * pick the block content agreed by a quorum. Requires a UNIQUE hash group meeting
+ * `quorum` — a cohort split on content declines rather than picking a side.
+ * Returns the agreed block, or `undefined`.
+ *
+ * `corroboratorCapacity` caps the floor exactly as it does in {@link selectQuorumRev}, and for
+ * the same reason: a cohort holding one other peer cannot produce two block-carriers, so
+ * demanding two makes the block permanently unrestorable on this node rather than making it safe.
+ * Omit it to keep the floor at two.
+ *
+ * **What relaxing this does and does not cost.** Block ids are random 256-bit strings, not
+ * content-addressed, so {@link canonicalBlockHash} is a cross-peer *agreement* hash and never a
+ * check against the requested id — nothing here re-derives an id from received bytes. At capacity
+ * one the sole peer's content is therefore taken on its word. That extends no trust the cohort had
+ * not already extended: the same peer's `(rev, actionId)` claim is equally uncorroborable at that
+ * size, and a two-member cohort has no honest majority to appeal to. Pass a capacity a shrunken
+ * view of the network cannot talk down (see {@link corroboratorCapacity}), so only a cohort that is
+ * *genuinely* that small reaches this branch.
+ */
+export function selectQuorumBlock(
+	candidates: BlockHashCandidate[],
+	simpleMajorityThreshold: number,
+	corroboratorCapacity?: number
+): { block: IBlock; hash: string } | undefined {
+	if (candidates.length === 0) return undefined;
+
+	// 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.
+	const groups = new Map<string, { block: IBlock; supporters: Set<string> }>();
+	const voters = new Set<string>();
+	for (const c of candidates) {
+		voters.add(c.peerId);
+		let g = groups.get(c.hash);
+		if (!g) {
+			g = { block: c.block, supporters: new Set() };
+			groups.set(c.hash, g);
+		}
+		g.supporters.add(c.peerId);
+	}
+
+	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 };
+}