@optimystic/db-p2p 1.0.0-beta.2 → 1.0.0-beta.3

package/src/storage/storage-repo.ts

@@ -60,6 +60,25 @@ export function isMissingBaseRevisionFailure(result: CommitResult): boolean {
 	return !result.success && (result.reason?.startsWith(MISSING_BASE_REVISION_REASON) ?? false);
 }
 
+/**
+ * Stable, greppable prefix on the failure reason `CoordinatorRepo.commit` answers with when a commit
+ * assembled consensus but FEWER than a majority of the cohort reported durably holding the committed
+ * revision afterwards. Same convention as {@link MISSING_BASE_REVISION_REASON}: a string marker,
+ * because the reason crosses the wire as `StaleFailure.reason` prose. The refusal is retryable
+ * (`conflict: true`) and means "not confirmed durable at a quorum" — never "guaranteed absent"; see
+ * the durability gate in `CoordinatorRepo.commit` for the two-phase ambiguity that wording covers.
+ */
+export const COMMIT_NOT_DURABLE_REASON = 'commit-not-durable';
+
+/**
+ * True when a {@link CommitResult} was refused by the coordinator's durability gate — consensus was
+ * reached but no durable majority reported holding the revision. Sibling of
+ * {@link isMissingBaseRevisionFailure}, for callers that need to tell this refusal from a stale loss.
+ */
+export function isCommitNotDurableFailure(result: CommitResult): boolean {
+	return !result.success && (result.reason?.startsWith(COMMIT_NOT_DURABLE_REASON) ?? false);
+}
+
 export type StorageRepoOptions = {
 	/** Optional hook to validate transactions in PendRequests */
 	validatePend?: PendValidationHook;
@@ -630,6 +649,17 @@ export class StorageRepo implements IRepo, IBlockChangeNotifier, IBlockReplicaSt
 						}
 					}
 				}
+				// NOTE: a pend of an update-only transform for a block this node holds NO revision of
+				// falls through here and is recorded (`latest` is undefined, so there is nothing to be
+				// stale against). It can never be promoted on this node without a reconcile —
+				// `internalCommit`'s fork guard refuses it (`missing-base-revision`) and drops the
+				// record — so the pend round it wins is one this member could not honour on its own.
+				// Harmless today: the commit-tier durability gate (`CoordinatorRepo.commit`) refuses
+				// the acknowledgement unless a majority of the cohort holds the revision after
+				// reconcile, and the coordinating member's proof-carrying copy is what a behind member
+				// reconciles from. If pend-time refusals ever become worth their cost (one wasted
+				// consensus round per such write), refuse at `ClusterMember.validatePendOperations`
+				// instead of here.
 
 				// Then handle any pending actions
 				const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());

package/src/testing/mesh-harness.ts

@@ -4,7 +4,7 @@ import type { FindCoordinatorOptions } from '@optimystic/db-core';
 import type { IPeerNetwork } from '@optimystic/db-core';
 import { NetworkTransactor } from '@optimystic/db-core';
 import { peerIdFromPrivateKey } from '@libp2p/peer-id';
-import { generateKeyPair } from '@libp2p/crypto/keys';
+import { generateKeyPair, generateKeyPairFromSeed } from '@libp2p/crypto/keys';
 import { ClusterMember, clusterMember, type ReconcileBlockCallback, type DeriveExpectedClusterCallback, type ExpectedClusterView } from '../cluster/cluster-repo.js';
 import { createReconcileBlock } from '../cluster/reconcile-block.js';
 import { resolveClusterPolicy, type ClusterPolicyOptions, type ResolvedClusterPolicy } from '../cluster/cluster-policy.js';
@@ -89,6 +89,21 @@ export interface MeshOptions {
 	 * than its threshold (0.5), so returning the threshold itself lands on the fail-closed side.
 	 */
 	meshConfidence?: (node: MeshNode) => number;
+	/**
+	 * Wraps the mesh's shared key network before any node, member derivation or transactor captures it —
+	 * so a wrapper here observes EVERY cohort lookup in the mesh (each node's coordinator, cluster
+	 * coordinator and admission derivation, plus `mesh.keyNetwork`), not only the transactor's.
+	 * Reassigning `mesh.keyNetwork` after `createMesh` reaches the transactor alone.
+	 * Omitted → identity.
+	 */
+	wrapKeyNetwork?: (shared: IKeyNetwork) => IKeyNetwork;
+	/**
+	 * Derive every node's Ed25519 key from a fixed seed `(keySeed, index)` instead of fresh
+	 * randomness, so the mesh's ring geometry is identical on every run. For specs that assert on
+	 * statistics of cohort placement: with random keys such a bound is a sample whose tail
+	 * eventually crosses it. Omitted → random keys.
+	 */
+	keySeed?: number;
 }
 
 export interface MeshFailureConfig {
@@ -238,6 +253,15 @@ export function resolveMeshPolicy(options: MeshOptions): ResolvedClusterPolicy {
 	});
 }
 
+/** The 32-byte Ed25519 seed for node `index` of a `keySeed` mesh. */
+function meshKeySeed(keySeed: number, index: number): Uint8Array {
+	const seed = new Uint8Array(32);
+	const view = new DataView(seed.buffer);
+	view.setUint32(0, keySeed);
+	view.setUint32(4, index);
+	return seed;
+}
+
 /**
  * Creates N interconnected mesh nodes with real components and mock transport.
  * ClusterClient calls route directly to target ClusterMember instances.
@@ -263,8 +287,10 @@ export async function createMesh(nodeCount: number, options: MeshOptions): Promi
 
 	// Generate key pairs for all nodes
 	const keyPairs = await Promise.all(
-		Array.from({ length: nodeCount }, async () => {
-			const privateKey = await generateKeyPair('Ed25519');
+		Array.from({ length: nodeCount }, async (_, i) => {
+			const privateKey = options.keySeed === undefined
+				? await generateKeyPair('Ed25519')
+				: await generateKeyPairFromSeed('Ed25519', meshKeySeed(options.keySeed, i));
 			return { peerId: peerIdFromPrivateKey(privateKey), privateKey };
 		})
 	);
@@ -283,7 +309,14 @@ export async function createMesh(nodeCount: number, options: MeshOptions): Promi
 	// admission gate's view) needs a per-node key network in phase 1, and constructing it here beats
 	// a late-bound slot a closure could fire on before it is filled. Safe because `nodes` is captured
 	// by reference and only consulted at call time, after the array is fully populated.
-	const keyNetwork = new MockMeshKeyNetwork(nodes, options.responsibilityK, failures);
+	//
+	// `wrapKeyNetwork` is applied HERE, before `makeNodeKeyNetwork` closes over `keyNetwork` below and
+	// before phase 1 builds any `deriveExpectedCluster` closure — every one of them reads the `keyNetwork`
+	// binding, so a wrapper assigned to it here is what every node's coordinator, cluster member and the
+	// returned `Mesh.keyNetwork` all observe. Reassigning `mesh.keyNetwork` after this function returns
+	// only reaches whoever reads that property later (the transactor); it is too late for the rest.
+	const sharedKeyNetwork = new MockMeshKeyNetwork(nodes, options.responsibilityK, failures);
+	const keyNetwork = options.wrapKeyNetwork ? options.wrapKeyNetwork(sharedKeyNetwork) : sharedKeyNetwork;
 
 	/**
 	 * One node's own view of the key network — what `Libp2pKeyPeerNetwork` gives a real node: