@optimystic/db-p2p 0.9.3 → 0.10.0

package/src/cluster/cluster-repo.ts

@@ -14,6 +14,7 @@ import type { PartitionDetector } from "./partition-detector.js";
 import type { FretService } from "p2p-fret";
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
+import type { ITransactionStateStore } from "./i-transaction-state-store.js";
 
 const log = createLogger('cluster-member')
 
@@ -45,6 +46,7 @@ interface ClusterMemberComponents {
 	validator?: ITransactionValidator;
 	reputation?: IPeerReputation;
 	consensusConfig?: ClusterConsensusConfig;
+	stateStore?: ITransactionStateStore;
 }
 
 export function clusterMember(components: ClusterMemberComponents): ClusterMember {
@@ -58,7 +60,8 @@ export function clusterMember(components: ClusterMemberComponents): ClusterMembe
 		components.fretService,
 		components.validator,
 		components.reputation,
-		components.consensusConfig
+		components.consensusConfig,
+		components.stateStore
 	);
 }
 
@@ -80,6 +83,9 @@ export class ClusterMember implements ICluster {
 	private pendingUpdates: Map<string, Promise<ClusterRecord>> = new Map();
 	// Temporarily set during validateSignatures so verifySignature can access the record
 	private currentValidationRecord?: ClusterRecord;
+	// Interval handles for periodic cleanup (stored so dispose() can clear them)
+	private readonly expirationInterval: NodeJS.Timeout;
+	private readonly cleanupInterval: NodeJS.Timeout;
 
 	/** Effective super-majority threshold. Defaults to 1.0 (unanimity) for backward compatibility. */
 	private readonly superMajorityThreshold: number;
@@ -94,13 +100,31 @@ export class ClusterMember implements ICluster {
 		private readonly fretService?: FretService,
 		private readonly validator?: ITransactionValidator,
 		private readonly reputation?: IPeerReputation,
-		consensusConfig?: ClusterConsensusConfig
+		consensusConfig?: ClusterConsensusConfig,
+		private readonly stateStore?: ITransactionStateStore
 	) {
 		this.superMajorityThreshold = consensusConfig?.superMajorityThreshold ?? 1.0;
 		// Periodically clean up expired transactions (.unref() so tests/short-lived processes can exit)
-		setInterval(() => this.queueExpiredTransactions(), 60000).unref();
+		this.expirationInterval = setInterval(() => this.queueExpiredTransactions(), 60000);
+		this.expirationInterval.unref();
 		// Process cleanup queue
-		setInterval(() => this.processCleanupQueue(), 1000).unref();
+		this.cleanupInterval = setInterval(() => this.processCleanupQueue(), 1000);
+		this.cleanupInterval.unref();
+	}
+
+	/**
+	 * Clears all interval and timeout handles and empties active state.
+	 * Called during node shutdown to prevent leaked timers.
+	 */
+	dispose(): void {
+		clearInterval(this.expirationInterval);
+		clearInterval(this.cleanupInterval);
+		for (const [, state] of this.activeTransactions) {
+			if (state.promiseTimeout) clearTimeout(state.promiseTimeout);
+			if (state.resolutionTimeout) clearTimeout(state.resolutionTimeout);
+		}
+		this.activeTransactions.clear();
+		this.cleanupQueue.length = 0;
 	}
 
 	/**
@@ -228,7 +252,10 @@ export class ClusterMember implements ICluster {
 						log('cluster-member:action-consensus-after-commit', {
 							messageHash: record.messageHash
 						});
-						await this.handleConsensus(currentRecord);
+						// Check persistent store for post-recovery dedup before synchronous guard
+						if (!await this.wasTransactionExecutedAsync(currentRecord.messageHash)) {
+							await this.handleConsensus(currentRecord);
+						}
 					}
 				}
 				shouldPersist = false;
@@ -237,8 +264,12 @@ export class ClusterMember implements ICluster {
 				log('cluster-member:action-consensus', {
 					messageHash: record.messageHash
 				});
-				// handleConsensus has its own idempotency guard via executedTransactions
-				await this.handleConsensus(currentRecord);
+				// Check persistent store for post-recovery dedup before synchronous guard
+				if (await this.wasTransactionExecutedAsync(currentRecord.messageHash)) {
+					log('cluster-member:consensus-already-executed', { messageHash: record.messageHash });
+				} else {
+					await this.handleConsensus(currentRecord);
+				}
 				// Don't call clearTransaction here - it happens in handleConsensus
 				shouldPersist = false;
 				break;
@@ -275,6 +306,7 @@ export class ClusterMember implements ICluster {
 				promiseTimeout: timeouts.promiseTimeout,
 				resolutionTimeout: timeouts.resolutionTimeout
 			});
+			this.persistParticipantState(record.messageHash, currentRecord);
 			log('cluster-member:state-persist', {
 				messageHash: record.messageHash,
 				storedPromises: Object.keys(currentRecord.promises ?? {}),
@@ -637,7 +669,10 @@ export class ClusterMember implements ICluster {
 			return;
 		}
 		// Mark as executing IMMEDIATELY before any async operations
-		this.executedTransactions.set(record.messageHash, Date.now());
+		const executedAt = Date.now();
+		this.executedTransactions.set(record.messageHash, executedAt);
+		this.stateStore?.markExecuted(record.messageHash, executedAt)
+			.catch(err => log('cluster-member:persist-executed-error', { messageHash: record.messageHash, error: (err as Error).message }));
 
 		try {
 			// Execute the operations - check return values for failures
@@ -902,6 +937,8 @@ export class ClusterMember implements ICluster {
 				this.executedTransactions.delete(messageHash);
 			}
 		}
+		this.stateStore?.pruneExecuted(expirationThreshold)
+			.catch(err => log('cluster-member:prune-executed-error', { error: (err as Error).message }));
 	}
 
 	private async processCleanupQueue(): Promise<void> {
@@ -937,10 +974,77 @@ export class ClusterMember implements ICluster {
 			clearTimeout(state.resolutionTimeout);
 		}
 		this.activeTransactions.delete(messageHash);
+		this.stateStore?.deleteParticipantState(messageHash)
+			.catch(err => log('cluster-member:persist-delete-error', { messageHash, error: (err as Error).message }));
 		log('cluster-member:clear-done', {
 			messageHash,
 			remaining: Array.from(this.activeTransactions.keys())
 		});
 	}
+
+	/** Fire-and-forget persist — errors are logged, never thrown. */
+	private persistParticipantState(messageHash: string, record: ClusterRecord): void {
+		if (!this.stateStore) return;
+		this.stateStore.saveParticipantState(messageHash, {
+			messageHash,
+			record,
+			lastUpdate: Date.now()
+		}).catch(err => log('cluster-member:persist-error', { messageHash, error: (err as Error).message }));
+	}
+
+	/**
+	 * Recover member transactions from persistent store after a restart.
+	 * Called during node startup, before accepting new requests.
+	 */
+	async recoverTransactions(): Promise<void> {
+		if (!this.stateStore) return;
+		const now = Date.now();
+
+		// 1. Prune expired executed entries from persistent store
+		await this.stateStore.pruneExecuted(now - ExecutedTransactionTtlMs);
+		// Note: executed transactions are checked via wasTransactionExecutedAsync() at runtime,
+		// which falls back to the persistent store when the in-memory map misses.
+
+		// 2. Restore active participant states
+		const participantStates = await this.stateStore.getAllParticipantStates();
+		for (const state of participantStates) {
+			const { messageHash } = state;
+			// Expired — clean up
+			if (state.record.message.expiration && state.record.message.expiration < now) {
+				log('cluster-member:recovery-expired', { messageHash });
+				await this.stateStore.deleteParticipantState(messageHash);
+				continue;
+			}
+			// Restore into activeTransactions with fresh timeouts
+			log('cluster-member:recovery-restore', { messageHash });
+			const timeouts = this.setupTimeouts(state.record);
+			this.activeTransactions.set(messageHash, {
+				record: state.record,
+				lastUpdate: state.lastUpdate,
+				promiseTimeout: timeouts.promiseTimeout,
+				resolutionTimeout: timeouts.resolutionTimeout
+			});
+		}
+
+		log('cluster-member:recovery-complete', {
+			restoredActive: this.activeTransactions.size,
+			restoredExecuted: this.executedTransactions.size
+		});
+	}
+
+	/**
+	 * Checks if a transaction's operations were already executed during consensus.
+	 * Falls back to the persistent store when the in-memory map misses.
+	 */
+	async wasTransactionExecutedAsync(messageHash: string): Promise<boolean> {
+		if (this.executedTransactions.has(messageHash)) return true;
+		if (!this.stateStore) return false;
+		const persisted = await this.stateStore.wasExecuted(messageHash);
+		if (persisted) {
+			// Re-populate in-memory map for future synchronous checks
+			this.executedTransactions.set(messageHash, Date.now());
+		}
+		return persisted;
+	}
 }
 

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

@@ -0,0 +1,43 @@
+import type { ClusterRecord } from "@optimystic/db-core";
+
+/** Serializable coordinator transaction state (excludes timers, Pending wrapper) */
+export interface PersistedCoordinatorState {
+	messageHash: string;
+	record: ClusterRecord;
+	lastUpdate: number;
+	/** Which phase was reached when last persisted */
+	phase: 'promising' | 'committing' | 'broadcasting';
+	/** Retry state for commit broadcast failures (excludes timer) */
+	retryState?: {
+		pendingPeers: string[];
+		attempt: number;
+		intervalMs: number;
+	};
+}
+
+/** Serializable participant transaction state (excludes timers) */
+export interface PersistedParticipantState {
+	messageHash: string;
+	record: ClusterRecord;
+	lastUpdate: number;
+}
+
+/** Platform-agnostic store for persisting 2PC transaction state. */
+export interface ITransactionStateStore {
+	// --- Coordinator state (keyed by messageHash) ---
+	saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void>;
+	getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined>;
+	deleteCoordinatorState(messageHash: string): Promise<void>;
+	getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]>;
+
+	// --- Participant state (keyed by messageHash) ---
+	saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void>;
+	getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined>;
+	deleteParticipantState(messageHash: string): Promise<void>;
+	getAllParticipantStates(): Promise<PersistedParticipantState[]>;
+
+	// --- Executed transaction dedup guard ---
+	markExecuted(messageHash: string, timestamp: number): Promise<void>;
+	wasExecuted(messageHash: string): Promise<boolean>;
+	pruneExecuted(olderThan: number): Promise<void>;
+}

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

@@ -0,0 +1,56 @@
+import type { ITransactionStateStore, PersistedCoordinatorState, PersistedParticipantState } from "./i-transaction-state-store.js";
+
+/** In-memory ITransactionStateStore. Default when no persistent store is injected. */
+export class MemoryTransactionStateStore implements ITransactionStateStore {
+	private readonly coordinatorStates = new Map<string, PersistedCoordinatorState>();
+	private readonly participantStates = new Map<string, PersistedParticipantState>();
+	private readonly executedMap = new Map<string, number>();
+
+	async saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void> {
+		this.coordinatorStates.set(messageHash, state);
+	}
+
+	async getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined> {
+		return this.coordinatorStates.get(messageHash);
+	}
+
+	async deleteCoordinatorState(messageHash: string): Promise<void> {
+		this.coordinatorStates.delete(messageHash);
+	}
+
+	async getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]> {
+		return Array.from(this.coordinatorStates.values());
+	}
+
+	async saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void> {
+		this.participantStates.set(messageHash, state);
+	}
+
+	async getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined> {
+		return this.participantStates.get(messageHash);
+	}
+
+	async deleteParticipantState(messageHash: string): Promise<void> {
+		this.participantStates.delete(messageHash);
+	}
+
+	async getAllParticipantStates(): Promise<PersistedParticipantState[]> {
+		return Array.from(this.participantStates.values());
+	}
+
+	async markExecuted(messageHash: string, timestamp: number): Promise<void> {
+		this.executedMap.set(messageHash, timestamp);
+	}
+
+	async wasExecuted(messageHash: string): Promise<boolean> {
+		return this.executedMap.has(messageHash);
+	}
+
+	async pruneExecuted(olderThan: number): Promise<void> {
+		for (const [hash, ts] of this.executedMap) {
+			if (ts < olderThan) {
+				this.executedMap.delete(hash);
+			}
+		}
+	}
+}

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

@@ -0,0 +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);
+				}
+			}
+		}
+	}
+}

package/src/cluster/spread-on-churn.ts

@@ -0,0 +1,285 @@
+import type { Startable, Libp2p } from '@libp2p/interface'
+import type { IRepo, IPeerNetwork } from '@optimystic/db-core'
+import { hashKey } from 'p2p-fret'
+import type { FretService } from 'p2p-fret'
+import { peerIdFromString } from '@libp2p/peer-id'
+import type { PartitionDetector } from './partition-detector.js'
+import { BlockTransferClient } from './block-transfer-service.js'
+import { createLogger } from '../logger.js'
+
+const log = createLogger('spread-on-churn')
+const textEncoder = new TextEncoder()
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface SpreadOnChurnConfig {
+	/** Enable the churn-resilient spread protocol. Default: true */
+	enabled: boolean
+	/** Number of middle-closest peers eligible to spread (d). Default: 3 */
+	spreadDistance: number
+	/** Enable dynamic d scaling based on cluster health. Default: true */
+	dynamicSpreadDistance: boolean
+	/** Cluster size ratio below which spread becomes more aggressive. Default: 0.6 */
+	healthThreshold: number
+	/** Debounce window for departure detection (ms). Default: 5000 */
+	departureDebounceMs: number
+	/** Number of peers beyond cluster boundary to target. Default: 4 */
+	expansionStep: number
+}
+
+export interface SpreadOnChurnDeps {
+	libp2p: Libp2p
+	fret: FretService
+	partitionDetector: PartitionDetector
+	repo: IRepo
+	peerNetwork: IPeerNetwork
+	clusterSize: number
+	protocolPrefix?: string
+}
+
+export interface SpreadEvent {
+	/** Blocks that were spread */
+	spread: Array<{
+		blockId: string
+		targets: string[]
+		succeeded: string[]
+		failed: string[]
+	}>
+	/** Current effective d */
+	effectiveD: number
+	/** Timestamp of the departure that triggered this */
+	triggeredAt: number
+}
+
+type SpreadHandler = (event: SpreadEvent) => void
+
+// ── Defaults ─────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: SpreadOnChurnConfig = {
+	enabled: true,
+	spreadDistance: 3,
+	dynamicSpreadDistance: true,
+	healthThreshold: 0.6,
+	departureDebounceMs: 5000,
+	expansionStep: 4,
+}
+
+// ── Monitor ──────────────────────────────────────────────────────────
+
+export class SpreadOnChurnMonitor implements Startable {
+	private running = false
+	private readonly trackedBlocks = new Set<string>()
+	private readonly handlers: SpreadHandler[] = []
+	private debounceTimer: ReturnType<typeof setTimeout> | null = null
+	private departureTimestamps: number[] = []
+	private departureTimestamp = 0
+
+	private readonly config: SpreadOnChurnConfig
+	private readonly onConnectionClose: () => void
+
+	constructor(
+		private readonly deps: SpreadOnChurnDeps,
+		config: Partial<SpreadOnChurnConfig> = {}
+	) {
+		this.config = { ...DEFAULT_CONFIG, ...config }
+		this.onConnectionClose = () => this.handleDeparture()
+	}
+
+	// ── Startable ────────────────────────────────────────────────────
+
+	async start(): Promise<void> {
+		if (this.running) return
+		this.running = true
+
+		this.deps.libp2p.addEventListener('connection:close', this.onConnectionClose)
+
+		log('started, tracking %d blocks', this.trackedBlocks.size)
+	}
+
+	async stop(): Promise<void> {
+		if (!this.running) return
+		this.running = false
+
+		this.deps.libp2p.removeEventListener('connection:close', this.onConnectionClose)
+
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer)
+			this.debounceTimer = null
+		}
+
+		log('stopped')
+	}
+
+	// ── Public API ───────────────────────────────────────────────────
+
+	onSpread(handler: SpreadHandler): void {
+		this.handlers.push(handler)
+	}
+
+	trackBlock(blockId: string): void {
+		this.trackedBlocks.add(blockId)
+	}
+
+	untrackBlock(blockId: string): void {
+		this.trackedBlocks.delete(blockId)
+	}
+
+	getTrackedBlockCount(): number {
+		return this.trackedBlocks.size
+	}
+
+	/** Force an immediate spread check (useful for testing). */
+	async checkNow(): Promise<SpreadEvent | null> {
+		return this.performSpread(Date.now())
+	}
+
+	// ── Internal ─────────────────────────────────────────────────────
+
+	private handleDeparture(): void {
+		if (!this.running) return
+		if (!this.config.enabled) return
+
+		if (!this.departureTimestamp) {
+			this.departureTimestamp = Date.now()
+		}
+
+		// Record for dynamic-d sliding window
+		this.departureTimestamps.push(Date.now())
+
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer)
+		}
+
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = null
+			const ts = this.departureTimestamp
+			this.departureTimestamp = 0
+			if (this.running) {
+				this.performSpread(ts).catch(err => {
+					log('spread error: %O', err)
+				})
+			}
+		}, this.config.departureDebounceMs)
+	}
+
+	private async performSpread(triggeredAt: number): Promise<SpreadEvent | null> {
+		if (!this.config.enabled) return null
+
+		if (this.deps.partitionDetector.detectPartition()) {
+			log('partition detected, suppressing spread')
+			return null
+		}
+
+		if (this.trackedBlocks.size === 0) return null
+
+		const selfId = this.deps.libp2p.peerId.toString()
+		const effectiveD = this.computeEffectiveD()
+		const spreadResults: SpreadEvent['spread'] = []
+
+		for (const blockId of this.trackedBlocks) {
+			const key = textEncoder.encode(blockId)
+			const coord = await hashKey(key)
+
+			// Check eligibility: only middle peers spread
+			const rank = this.deps.fret.neighborDistance(selfId, coord, this.deps.clusterSize)
+			if (rank >= effectiveD) continue
+
+			// Get current cohort and expansion targets
+			const cohort = this.deps.fret.assembleCohort(coord, this.deps.clusterSize)
+			const cohortSet = new Set(cohort)
+			const expanded = this.deps.fret.expandCohort(
+				cohort, coord, this.config.expansionStep
+			)
+			const targets = expanded.filter(id => !cohortSet.has(id) && id !== selfId)
+			if (targets.length === 0) continue
+
+			// Read block data from local storage
+			const result = await this.deps.repo.get({ blockIds: [blockId] })
+			const blockResult = result[blockId]
+			if (!blockResult?.block) {
+				log('no-local-data block=%s', blockId)
+				continue
+			}
+
+			const blockData = textEncoder.encode(JSON.stringify(blockResult.block))
+
+			// Push to each target
+			const succeeded: string[] = []
+			const failed: string[] = []
+
+			for (const targetId of targets) {
+				try {
+					const peerId = peerIdFromString(targetId)
+					const client = new BlockTransferClient(
+						peerId,
+						this.deps.peerNetwork,
+						this.deps.protocolPrefix
+					)
+					await client.pushBlocks([blockId], [blockData], 'replication')
+					succeeded.push(targetId)
+					log('push:ok block=%s target=%s', blockId, targetId)
+				} catch (err) {
+					failed.push(targetId)
+					log('push:fail block=%s target=%s err=%s',
+						blockId, targetId, (err as Error).message)
+				}
+			}
+
+			spreadResults.push({ blockId, targets, succeeded, failed })
+		}
+
+		if (spreadResults.length === 0) return null
+
+		const event: SpreadEvent = {
+			spread: spreadResults,
+			effectiveD,
+			triggeredAt,
+		}
+
+		this.emitEvent(event)
+		return event
+	}
+
+	private computeEffectiveD(): number {
+		const d = this.config.spreadDistance
+		if (!this.config.dynamicSpreadDistance) return d
+
+		const maxD = Math.max(d, Math.floor(this.deps.clusterSize / 2))
+		const windowMs = this.config.departureDebounceMs * 4
+		const now = Date.now()
+
+		// Prune old departure timestamps
+		this.departureTimestamps = this.departureTimestamps.filter(
+			ts => now - ts < windowMs
+		)
+
+		// Rapid churn: 3+ departures in window → increase d by 1
+		if (this.departureTimestamps.length >= 3) {
+			return Math.min(d + 1, maxD)
+		}
+
+		// Low cluster health: observed cohort shrunk relative to expected
+		// We approximate observed cohort size from FRET diagnostics
+		const diag: any = (this.deps.fret as any).getDiagnostics?.()
+		const estimate = diag?.estimate ?? diag?.n
+		if (typeof estimate === 'number' && Number.isFinite(estimate) && estimate > 0) {
+			const ratio = estimate / this.deps.clusterSize
+			if (ratio < this.config.healthThreshold) {
+				const scaled = Math.ceil(d * (this.deps.clusterSize / estimate))
+				return Math.min(scaled, maxD)
+			}
+		}
+
+		return d
+	}
+
+	private emitEvent(event: SpreadEvent): void {
+		for (const handler of this.handlers) {
+			try {
+				handler(event)
+			} catch (err) {
+				log('handler error: %O', err)
+			}
+		}
+	}
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./cluster/client.js";
 export * from "./cluster/cluster-repo.js";
 export * from "./cluster/service.js";
 export * from "./cluster/rebalance-monitor.js";
+export * from "./cluster/spread-on-churn.js";
 export * from "./cluster/block-transfer.js";
 export * from "./cluster/block-transfer-service.js";
 export * from "./protocol-client.js";
@@ -31,3 +32,8 @@ export * from "./network/network-manager-service.js";
 export * from "./network/get-network-manager.js";
 export * from "./reputation/index.js";
 export * from "./dispute/index.js";
+export * from "./cluster/i-transaction-state-store.js";
+export * from "./cluster/memory-transaction-state-store.js";
+export * from "./cluster/persistent-transaction-state-store.js";
+export * from "./storage/i-kv-store.js";
+export * from "./storage/memory-kv-store.js";