@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/reactivity/topic-bytes.ts

@@ -1,37 +1,37 @@
-/**
- * Reactivity — the one pinned `BlockId` → raw tail-bytes encoding, shared by origination and subscription.
- *
- * `reactivityTopicId` (db-core) hashes `H(tailBytes ‖ "reactivity")` to derive the topic's `coord_0`
- * cohort. Origination (the cohort-change membership gate, {@link
- * import("../cohort-topic/reactivity-membership-gate.js").createReactivitySelfMembershipGate}) and the
- * subscriber side (the production subscribe factory that converts a `BlockId` `tailIdAtAttach` to the bytes
- * {@link import("./subscription-manager.js").ReactivitySubscriptionManager} feeds `reactivityTopicId`) MUST
- * feed it the **same** bytes for a given tail, or they resolve different coords and origination silently
- * never reaches subscribers (green tests, dead feature).
- *
- * This module is that single source of truth: `reactivityTailBytes(tailId) = TextEncoder().encode(tailId)`,
- * the synchronous block-id→bytes convention the rest of db-p2p already uses for ring hashing of tail ids
- * (`cluster/client.ts`, `repo/client.ts`). db-core's async `blockIdToBytes` (which `sha256`s the utf8 bytes
- * first) is deliberately NOT used: it would (a) double-hash relative to the spec's `H(tailId ‖ "reactivity")`
- * and (b) force the synchronous origination gate to become async.
- *
- * It lives in the reactivity surface (not buried in the gate) so the subscribe path and the gate import the
- * exact same function rather than re-deriving the encoding independently. The
- * `cohort-topic/reactivity-membership-gate.ts` module re-exports it for its existing callers.
- */
-
-import type { BlockId } from "@optimystic/db-core";
-
-const utf8 = new TextEncoder();
-
-/**
- * The pinned `BlockId` → raw tail bytes encoding fed into `reactivityTopicId`: the **raw** utf8 bytes of the
- * tail block-id string (NOT a pre-hashed routing key, NOT db-core's double-hashing `blockIdToBytes`).
- *
- * Load-bearing: origination and the subscriber side must call this **same** function for a given tail (see
- * the module doc) — a mismatch resolves different `coord_0`s and origination silently never reaches
- * subscribers. The `topic-bytes-encoding` spec pins the coord-equality both ways.
- */
-export function reactivityTailBytes(tailId: BlockId): Uint8Array {
-	return utf8.encode(tailId);
-}
+/**
+ * Reactivity — the one pinned `BlockId` → raw tail-bytes encoding, shared by origination and subscription.
+ *
+ * `reactivityTopicId` (db-core) hashes `H(tailBytes ‖ "reactivity")` to derive the topic's `coord_0`
+ * cohort. Origination (the cohort-change membership gate, {@link
+ * import("../cohort-topic/reactivity-membership-gate.js").createReactivitySelfMembershipGate}) and the
+ * subscriber side (the production subscribe factory that converts a `BlockId` `tailIdAtAttach` to the bytes
+ * {@link import("./subscription-manager.js").ReactivitySubscriptionManager} feeds `reactivityTopicId`) MUST
+ * feed it the **same** bytes for a given tail, or they resolve different coords and origination silently
+ * never reaches subscribers (green tests, dead feature).
+ *
+ * This module is that single source of truth: `reactivityTailBytes(tailId) = TextEncoder().encode(tailId)`,
+ * the synchronous block-id→bytes convention the rest of db-p2p already uses for ring hashing of tail ids
+ * (`cluster/client.ts`, `repo/client.ts`). db-core's async `blockIdToBytes` (which `sha256`s the utf8 bytes
+ * first) is deliberately NOT used: it would (a) double-hash relative to the spec's `H(tailId ‖ "reactivity")`
+ * and (b) force the synchronous origination gate to become async.
+ *
+ * It lives in the reactivity surface (not buried in the gate) so the subscribe path and the gate import the
+ * exact same function rather than re-deriving the encoding independently. The
+ * `cohort-topic/reactivity-membership-gate.ts` module re-exports it for its existing callers.
+ */
+
+import type { BlockId } from "@optimystic/db-core";
+
+const utf8 = new TextEncoder();
+
+/**
+ * The pinned `BlockId` → raw tail bytes encoding fed into `reactivityTopicId`: the **raw** utf8 bytes of the
+ * tail block-id string (NOT a pre-hashed routing key, NOT db-core's double-hashing `blockIdToBytes`).
+ *
+ * Load-bearing: origination and the subscriber side must call this **same** function for a given tail (see
+ * the module doc) — a mismatch resolves different `coord_0`s and origination silently never reaches
+ * subscribers. The `topic-bytes-encoding` spec pins the coord-equality both ways.
+ */
+export function reactivityTailBytes(tailId: BlockId): Uint8Array {
+	return utf8.encode(tailId);
+}

package/src/repo/client.ts

@@ -5,6 +5,7 @@ import type {
 import type { RepoMessage } from "@optimystic/db-core";
 import { blockIdsForTransforms, blockIdToBytes } from "@optimystic/db-core";
 import { ProtocolClient } from "../protocol-client.js";
+import type { RedirectPayload } from "./redirect.js";
 import { MAX_BLOCK_MESSAGE_BYTES } from "../protocol-limits.js";
 import { peerIdFromString } from "@libp2p/peer-id";
 
@@ -102,16 +103,25 @@ export class RepoClient extends ProtocolClient implements IRepo {
 			clearTimeout(timer)
 		}
 
-		if (response?.redirect?.peers?.length) {
+		// Type the redirect branch against the payload the service actually produces
+		// (`RedirectPayload`) rather than reading it off the `any` response — the untyped read
+		// is what let the `addrs` the sender embedded fall on the floor.
+		const redirectResponse = response as Partial<RedirectPayload>
+		if (redirectResponse?.redirect?.peers?.length) {
 			if (hop >= 2) {
 				throw new Error('Redirect loop detected in RepoClient (max hops reached)')
 			}
 			const currentIdStr = this.peerId.toString()
-			const next = response.redirect.peers.find((p: any) => p.id !== currentIdStr) ?? response.redirect.peers[0]
+			const peers = redirectResponse.redirect.peers
+			const next = peers.find((p) => p.id !== currentIdStr) ?? peers[0]!
 			const nextId = peerIdFromString(next.id)
 			if (next.id === currentIdStr) {
 				throw new Error('Redirect loop detected in RepoClient (same peer)')
 			}
+			// Learn the redirect target's addresses BEFORE dialing it: the redirect is the only
+			// notice we get that this peer matters, and if it is relay-only we have no address
+			// for it at all. Merging after the dial would help only some later hop.
+			this.peerNetwork.recordPeerAddresses?.(nextId, next.addrs ?? [])
 			// cache hint — await so the recorded key bytes match what findCoordinator
 			// later looks up (blockIdToBytes is async); deterministic ordering also
 			// keeps the hint testable. The redirect retry below is async anyway.

package/src/repo/cluster-coordinator.ts

@@ -32,6 +32,27 @@ export class ValidatorRejectionError extends Error {
 	}
 }
 
+/**
+ * The transaction lost a conflict race: one or more members answered with a signed `conflict`
+ * vote (they hold a rival transaction that won the deterministic race on the same blocks) and
+ * approvals fell short of super-majority. Distinct from {@link ValidatorRejectionError} — nobody
+ * judged this write invalid; it lost an optimistic-concurrency race and a fresh retry can win.
+ * `CoordinatorRepo.pend` converts this into a `StaleFailure` with `conflict: true` so the normal
+ * retry machinery (`isConflictFailure`) absorbs it; it should escape as a thrown error only from
+ * paths other than pend. The conflicting peers and the winning hashes ride as structured data
+ * (from the signed `conflictWith` fields), never parsed out of prose.
+ */
+export class ConflictRaceLostError extends Error {
+	constructor(
+		message: string,
+		/** peerId → messageHash of the rival transaction that member holds as the race winner. */
+		readonly conflicts: Record<string, string>
+	) {
+		super(message);
+		this.name = 'ConflictRaceLostError';
+	}
+}
+
 /** Cancel handle for an injected timer; cancels a not-yet-fired timer (safe no-op after fire/cancel). */
 export type TimerCancel = () => void;
 
@@ -333,18 +354,21 @@ export class ClusterCoordinator {
 		const promised = await this.collectPromises(peers, record);
 		const superMajority = Math.ceil(peerCount * this.cfg.superMajorityThreshold);
 
-		// Count approvals and rejections separately
+		// Count approvals, rejections and conflict votes separately. A `conflict` vote is a member
+		// saying "not now — I hold the race winner": it must count toward NEITHER approvals NOR
+		// rejections, or a lost race would masquerade as a validator rejection (permanent) or as
+		// silence (indistinguishable from an unreachable cohort) — both wrong.
 		const promises = promised.record.promises;
 		const approvalCount = Object.values(promises).filter(sig => sig.type === 'approve').length;
 		const rejectionCount = Object.values(promises).filter(sig => sig.type === 'reject').length;
+		const conflictCount = Object.values(promises).filter(sig => sig.type === 'conflict').length;
 
 		// Check if rejections make super-majority impossible
 		// If more than (peerCount - superMajority) nodes reject, we can never reach super-majority
 		const maxAllowedRejections = peerCount - superMajority;
 		if (rejectionCount > maxAllowedRejections) {
 			const rejectReasonsByPeer = Object.fromEntries(Object.entries(promises)
-				.filter(([_, sig]) => sig.type === 'reject')
-				.map(([peerId, sig]) => [peerId, sig.rejectReason ?? 'unknown']));
+				.flatMap(([peerId, sig]) => sig.type === 'reject' ? [[peerId, sig.rejectReason ?? 'unknown'] as const] : []));
 			const rejectReasons = Object.entries(rejectReasonsByPeer)
 				.map(([peerId, reason]) => `${peerId}: ${reason}`)
 				.join('; ');
@@ -356,11 +380,46 @@ export class ClusterCoordinator {
 				reasons: rejectReasons
 			});
 			this.updateTransactionRecord(promised.record, 'rejected-by-validators');
+			// Abandoning here without telling anyone leaves every member that voted holding this
+			// transaction in its own reservation table, blocking its blocks until that member's
+			// staleness sweep fires — and each retry we throw back to the caller plants a fresh
+			// reservation, so the block never frees. The merged record carries enough signed
+			// rejections to *prove* the transaction is dead, so replaying it to the cohort makes
+			// every member recompute `Rejected` and clear immediately. Proof-carrying, so a member
+			// need not trust us: it verifies the signatures it is shown.
+			this.broadcastAbandonment(promised.record, 'rejected-by-validators');
 			throw new ValidatorRejectionError(
 				`Transaction rejected by validators (${rejectionCount}/${peerCount} rejected): ${rejectReasons}`,
 				rejectReasonsByPeer);
 		}
 
+		// A conflict-answered shortfall is a LOST RACE, not a validator verdict and not silence.
+		// Checked after the rejection threshold (a genuine validator rejection still wins) and
+		// before the generic shortfall (which must stay reserved for the genuinely-silent cohort).
+		if (conflictCount > 0 && approvalCount < superMajority) {
+			const conflicts = Object.fromEntries(Object.entries(promises)
+				.flatMap(([peerId, sig]) => sig.type === 'conflict' ? [[peerId, sig.conflictWith] as const] : []));
+			log('cluster-tx:conflict-race-lost', {
+				messageHash: record.messageHash,
+				peerCount,
+				approvals: approvalCount,
+				rejections: rejectionCount,
+				conflicts,
+				superMajority
+			});
+			this.updateTransactionRecord(promised.record, 'conflict-race-lost');
+			// Broadcast only when the merged record itself PROVES the transaction can no longer reach
+			// super-majority (members re-derive ConflictSuperseded/Rejected from the signed votes and
+			// clear their reservations immediately). Below that bar the record proves nothing and a
+			// broadcast would be the unauthenticated "forget this" the shortfall NOTE below refuses.
+			if (rejectionCount + conflictCount > maxAllowedRejections) {
+				this.broadcastAbandonment(promised.record, 'conflict-race-lost');
+			}
+			throw new ConflictRaceLostError(
+				`Conflict race lost: ${conflictCount}/${peerCount} member(s) hold a conflicting winner (${approvalCount}/${superMajority} approvals)`,
+				conflicts);
+		}
+
 		if (peerCount > 1 && approvalCount < superMajority) {
 			log('cluster-tx:supermajority-failed', {
 				messageHash: record.messageHash,
@@ -371,6 +430,15 @@ export class ClusterCoordinator {
 				threshold: this.cfg.superMajorityThreshold
 			});
 			this.updateTransactionRecord(promised.record, 'supermajority-failed');
+			// NOTE: deliberately NOT broadcast, unlike the rejected-by-validators branch above. With
+			// conflict-answered shortfalls peeled off above, we get here only because peers did not
+			// answer at all, so the record carries no signed evidence that the transaction is dead — a
+			// broadcast would be an unauthenticated "forget this" that any caller could use to clear a
+			// live transaction out of a member's reservation table. Members that DID vote are freed by
+			// their own staleness sweep instead.
+			// NOTE: the message below is load-bearing wire text — the consuming repo
+			// (sereus cadre-core control-write-retry) matches it verbatim to retry a genuinely-silent
+			// cohort. Keep it byte-identical, and never fold conflict votes into its rejection count.
 			throw new Error(`Failed to get super-majority: ${approvalCount}/${peerCount} approvals (needed ${superMajority}, ${rejectionCount} rejections)`);
 		}
 
@@ -696,6 +764,34 @@ export class ClusterCoordinator {
 		return { failures };
 	}
 
+	/**
+	 * Fire-and-forget replay of an abandoned transaction's record to every peer in its cohort.
+	 *
+	 * Called only where the record itself proves the transaction is dead (enough signed rejections that
+	 * super-majority is unreachable). Each member re-derives `TransactionPhase.Rejected` from the votes
+	 * it verifies and drops the entry from its own reservation table, freeing the blocks immediately
+	 * instead of after its 2 s staleness window. No new message type and no wire-format change — this is
+	 * the same `update()` every other phase uses.
+	 *
+	 * Never awaited into the caller's throw and never rethrows: an abandonment must not turn into a
+	 * *different* failure, and the staleness sweep remains the backstop if delivery fails.
+	 */
+	private broadcastAbandonment(record: ClusterRecord, reason: string): void {
+		const peerIds = Object.keys(record.peers);
+		log('cluster-tx:abandon-broadcast', { messageHash: record.messageHash, reason, peerIds });
+		void Promise.all(peerIds.map(async peerIdStr => {
+			try {
+				await this.updateMember(peerIdStr, record, 0, 'abandon-broadcast');
+			} catch (err) {
+				log('cluster-tx:abandon-broadcast-error', {
+					messageHash: record.messageHash,
+					peerId: peerIdStr,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		}));
+	}
+
 	private updateTransactionRecord(record: ClusterRecord, stage: string): void {
 		const state = this.transactions.get(record.messageHash);
 		if (!state) {