@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/libp2p-node-base.ts

@@ -3,6 +3,8 @@ import { noise } from '@chainsafe/libp2p-noise';
 import { yamux } from '@chainsafe/libp2p-yamux';
 import { identify } from '@libp2p/identify';
 import { ping } from '@libp2p/ping';
+import { dcutr } from '@libp2p/dcutr';
+import { autoNAT } from '@libp2p/autonat';
 import { gossipsub } from '@chainsafe/libp2p-gossipsub';
 import { bootstrap } from '@libp2p/bootstrap';
 import { circuitRelayServer, type CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
@@ -10,30 +12,70 @@ import { peerIdFromString } from '@libp2p/peer-id';
 import { generateKeyPair } from '@libp2p/crypto/keys';
 import type { ConnectionGater, PrivateKey } from '@libp2p/interface';
 import { clusterService } from './cluster/service.js';
+import { blockTransferService } from './cluster/block-transfer-service.js';
 import { repoService } from './repo/service.js';
 import { StorageRepo } from './storage/storage-repo.js';
 import { BlockStorage } from './storage/block-storage.js';
 import { MemoryRawStorage } from './storage/memory-storage.js';
 import type { IRawStorage } from './storage/i-raw-storage.js';
-import { clusterMember } from './cluster/cluster-repo.js';
+import { clusterMember, type ReconcileBlockCallback, type CommitCertificateSink } from './cluster/cluster-repo.js';
+import { createCommitCertStore, makeClusterCommitCertExtractor, type CommitCertStore } from './cluster/commit-cert.js';
 import { coordinatorRepo } from './repo/coordinator-repo.js';
 import { Libp2pKeyPeerNetwork, type NetworkMode, type NetworkStatePersistence } from './libp2p-key-network.js';
 import { ClusterClient } from './cluster/client.js';
-import type { IRepo, ICluster, ITransactionValidator } from '@optimystic/db-core';
+import type { IRepo, ICluster, ITransactionValidator, BlockId, ActionRev, IBlock, IBlockChangeNotifier } from '@optimystic/db-core';
 import type { ITransactionStateStore } from './cluster/i-transaction-state-store.js';
-import { networkManagerService } from './network/network-manager-service.js';
+import { networkManagerService, type NetworkManagerService } from './network/network-manager-service.js';
+import type { SpreadOnChurnConfig, SpreadOnChurnMonitor } from './cluster/spread-on-churn.js';
 import { fretService, Libp2pFretService } from 'p2p-fret';
 import { syncService } from './sync/service.js';
 import { SyncClient } from './sync/client.js';
+import type { SyncResponse } from './sync/protocol.js';
 import type { ClusterLatestCallback } from './repo/coordinator-repo.js';
 import { RestorationCoordinator } from './storage/restoration-coordinator-v2.js';
 import { RingSelector } from './storage/ring-selector.js';
 import { StorageMonitor } from './storage/storage-monitor.js';
 import type { StorageMonitorConfig } from './storage/storage-monitor.js';
 import { ArachnodeFretAdapter } from './storage/arachnode-fret-adapter.js';
-import type { RestoreCallback } from './storage/struct.js';
+import type { RestoreCallback, BlockArchive } from './storage/struct.js';
 import type { FretService } from 'p2p-fret';
+import { createCohortTopicHost, type CohortTopicHostOptions } from './cohort-topic/host.js';
+import { attachCohortChangeBridge } from './cohort-topic/change-bridge.js';
+import { createReactivitySelfMembershipGate, reactivityTailBytes } from './cohort-topic/reactivity-membership-gate.js';
+import { Libp2pReactivityNotifyTransport, registerNotifyHandler } from './reactivity/notify-transport.js';
+import {
+	Libp2pReactivityRecoverTransport,
+	createLibp2pRecoverDialer,
+	registerRecoverHandler,
+	createRecoverRequestSigners,
+} from './reactivity/recover-transport.js';
+import { ReactivityForwarderHost, reactivityDirectSubscribers, reactivityNotificationTopicId } from './reactivity/forwarder-host.js';
+import { ReactivityOriginationManager } from './reactivity/origination-manager.js';
+import { ReactivityPushStateGossipDriver, registerPushStateGossipHandler, type ReactivityGossipCollection } from './reactivity/push-state-gossip.js';
+import { RotationReRegistrationScheduler } from './reactivity/rotation-rereg-scheduler.js';
+import { ReactivitySubscriberRegistry } from './reactivity/subscriber-registry.js';
+import { DEFAULT_REACTIVITY_PROTOCOLS, reactivityProtocolList } from './reactivity/protocols.js';
+import { registerMatchmakingQueryHandler } from './matchmaking/query-transport.js';
+import { DEFAULT_MATCHMAKING_PROTOCOLS, matchmakingProtocolList } from './matchmaking/protocols.js';
+import { signPeer } from './cohort-topic/peer-sig.js';
+import {
+	createNotificationVerifier,
+	createCorrelationReplayGuard,
+	createStickyCohortHintCache,
+	reactivityNodePolicy,
+	createTierAddressing,
+	createRingHash,
+	Tier,
+	b64urlToBytes,
+	bytesToB64url,
+	type NotificationV1,
+	type CohortRef,
+	type PushStateGossipV1,
+	type PushStateInit,
+	type NotificationVerifier,
+} from '@optimystic/db-core';
 import { PartitionDetector } from './cluster/partition-detector.js';
+import { createLogger } from './logger.js';
 import { PeerReputationService } from './reputation/peer-reputation.js';
 import { DisputeService } from './dispute/dispute-service.js';
 import { DisputeClient } from './dispute/client.js';
@@ -42,6 +84,9 @@ import type { DisputeConfig } from './dispute/types.js';
 type Libp2pInit = NonNullable<Parameters<typeof createLibp2p>[0]>;
 export type Libp2pTransports = NonNullable<Libp2pInit['transports']>;
 
+/** Logger for the reactivity node-wiring (origination/forwarder/recover/rotation composition). */
+const reactivityWiringLog = createLogger('reactivity-node-wiring');
+
 /** Factory function or instance for creating raw storage */
 export type RawStorageProvider = IRawStorage | (() => IRawStorage);
 
@@ -99,9 +144,12 @@ export type NodeOptions = {
 	/**
 	 * Responsibility K - the replica set size for determining cluster membership.
 	 * This is distinct from kBucketSize (DHT routing) and clusterSize (consensus quorum).
-	 * When a node receives a request, it checks if it's in the top responsibilityK
-	 * peers (by XOR distance) for the key. If not, it redirects to closer peers.
-	 * Default: 1 (only the closest peer is responsible)
+	 * On the repo path, a node checks whether it is in the top responsibilityK peers
+	 * (by XOR distance) for the key and redirects to closer peers if not. On the cluster
+	 * update path it is a small-mesh bypass threshold: when the record's peer set is
+	 * smaller than this, the update is processed locally regardless of membership;
+	 * otherwise a non-member redirects to the responsible peers.
+	 * Default: 1 (only the closest/member peer is responsible)
 	 */
 	responsibilityK?: number;
 
@@ -111,6 +159,12 @@ export type NodeOptions = {
 		storage?: StorageMonitorConfig;
 	};
 
+	/**
+	 * Churn-resilient spread protocol tuning. Absent -> enabled with defaults
+	 * (see SpreadOnChurnConfig). Set { enabled: false } to disable spread on this node.
+	 */
+	spreadOnChurn?: Partial<SpreadOnChurnConfig>;
+
 	/** Transaction validator for cluster consensus */
 	validator?: ITransactionValidator;
 
@@ -123,6 +177,39 @@ export type NodeOptions = {
 	/** Optional persistent store for 2PC transaction state (enables crash recovery) */
 	transactionStateStore?: ITransactionStateStore;
 
+	/**
+	 * Optional sink for the consensus commit certificate, fired per committed action just before the
+	 * commit is applied to local storage (see {@link CommitCertificateSink}). This is the cluster-side
+	 * half of the reactivity origination path: a caller wiring reactivity supplies a
+	 * {@link CommitCertStore}'s `put` here, then resolves it via {@link makeClusterCommitCertExtractor}
+	 * when it installs the change-notifier bridge ({@link attachCohortChangeBridge}) on the running
+	 * node. Absent → zero cost (no cert is assembled).
+	 */
+	onCommitCertificate?: CommitCertificateSink;
+
+	/**
+	 * Opt-in cohort-topic substrate activation (reactivity / matchmaking origination). Default OFF →
+	 * the node keeps today's bare `blockChangeNotifier = storageRepo` behavior at zero cohort cost (no
+	 * host, no cert store; a caller-supplied {@link onCommitCertificate} is the only sink). When
+	 * `enabled`, the node-base constructs the cohort-topic host post-assembly, builds a real FRET-backed
+	 * `selfIsCohortMember` gate over `coord_0(H(tailId ‖ "reactivity"))`, and installs the change-notifier
+	 * origination bridge — making reactivity origination live for ALL collections created on the node.
+	 *
+	 * A failure to construct the host (or a missing FRET service) **hard-fails** node startup: the
+	 * operator opted in, so silently degrading to the bare notifier would hide misconfiguration.
+	 */
+	cohortTopic?: {
+		/** Master switch. Absent/`false` → dormant, zero cost. */
+		enabled: boolean;
+		/**
+		 * Requested cohort size; MUST match the host's `wantK` so the membership gate checks the same
+		 * cohort the host serves. Default 16 (the host's default).
+		 */
+		wantK?: number;
+		/** Optional pass-through host tuning (profile / minSigs / fanout / gossipIntervalMs / antiDos / promotion). */
+		host?: Omit<CohortTopicHostOptions, 'privateKey' | 'wantK'>;
+	};
+
 	/**
 	 * Optional Ed25519 private key for this node. When provided, the libp2p
 	 * node uses this identity instead of generating a fresh keypair. Use this
@@ -149,6 +236,39 @@ function resolveStorage(provider: RawStorageProvider | undefined): IRawStorage {
 	return typeof provider === 'function' ? provider() : provider;
 }
 
+/**
+ * Resolve the full FRET engine the cohort-topic host needs.
+ *
+ * `createCohortTopicHost` consumes the complete {@link FretService} engine surface — notably
+ * `setActivityHandler` (and `routeAct`, size estimation, …). The value at `node.services.fret` is the
+ * libp2p `Libp2pFretService` *wrapper*, which re-exports only a subset (`assembleCohort`, `routeAct`, …)
+ * and keeps the real engine private behind its lazy `ensure()` accessor. By the time activation runs the
+ * engine is already initialized — the wrapper's `Startable.start()` ran during `node.start()` — and the
+ * engine and wrapper share one underlying routing store, so the host and the membership gate observe the
+ * same cohort state. Returns the engine when reachable; otherwise the value as-is (a test may inject a
+ * raw engine that needs no unwrapping).
+ */
+function resolveFretEngine(fret: FretService | undefined): FretService | undefined {
+	if (!fret) {
+		return undefined;
+	}
+	const candidate = fret as unknown as { ensure?: () => FretService };
+	return typeof candidate.ensure === 'function' ? candidate.ensure() : fret;
+}
+
+/**
+ * The raw topic id bytes of a collection's current served reactivity {@link PushState}, or `undefined` if the
+ * node serves none. The forwarder host keys its served map by topicId, but a **backfill** recover request
+ * carries only a collectionId — so the drain-redirect binding resolves the collection's current tail topic
+ * here (the highest-`lastRevision` served PushState) before consulting `rotationRedirectFor`. While the old
+ * tail is the only served state this resolves it (and its drain gate redirects); once the new tail is served
+ * this resolves the new tail (no gate → no redirect), exactly as the recover serve's backfill path intends.
+ */
+function resolveCurrentServedTopic(forwarderHost: ReactivityForwarderHost, collectionId: string): Uint8Array | undefined {
+	const ps = forwarderHost.pushStateForCollection(collectionId);
+	return ps === undefined ? undefined : b64urlToBytes(ps.topicId);
+}
+
 export async function createLibp2pNodeBase(
 	options: NodeOptions,
 	defaults: {
@@ -204,6 +324,23 @@ export async function createLibp2pNodeBase(
 	const listenAddrs = options.listenAddrs ?? defaults.listenAddrs;
 	const transports = options.transports ?? defaults.transports;
 
+	// --- cohort-topic substrate activation (opt-in; default off → today's bare behavior, zero cost) ---
+	const cohortEnabled = options.cohortTopic?.enabled === true;
+	// Resolve wantK ONCE so the post-assembly host serves and the membership gate checks the SAME cohort.
+	const cohortWantK = options.cohortTopic?.wantK ?? 16;
+	// When enabled, the cluster member records the consensus commit cert into this store synchronously,
+	// BEFORE `storageRepo.commit` emits the change event the bridge's extractor resolves it from (see
+	// cluster-repo.ts §applyConsensusOperation). Created early because the sink must be passed into
+	// `clusterMember(...)` below. Composed with any caller-supplied `onCommitCertificate` so both fire.
+	const certStore: CommitCertStore | undefined = cohortEnabled ? createCommitCertStore() : undefined;
+	const onCommitCertificate: CommitCertificateSink | undefined = certStore
+		// `certStore.put` runs FIRST so origination's cert capture cannot be defeated by a throwing caller
+		// sink: the whole composed call is isolated in `ClusterMember.captureCommitCert`, so a caller sink
+		// that threw before the store was written would make that commit silently never originate. Ordering
+		// the store first keeps origination correct regardless of the caller sink (`put` never throws).
+		? (actionId, cert): void => { certStore.put(actionId, cert); options.onCommitCertificate?.(actionId, cert); }
+		: options.onCommitCertificate;
+
 	const libp2pOptions: unknown = {
 		start: false,
 		privateKey: nodePrivateKey,
@@ -226,6 +363,13 @@ export async function createLibp2pNodeBase(
 				protocolPrefix: `/optimystic/${options.networkName}`
 			}),
 			ping: ping(),
+			// DCUtR (hole-punch) upgrades relayed node↔node connections to direct
+			// ones; AutoNAT learns this node's public reachability via peer dial-back.
+			// Both are always-on and depend on `identify` above. They are inert where
+			// the transport can't hole-punch or dial back (e.g. browser/WS-only), which
+			// is acceptable — they neither throw nor break the build in that case.
+			dcutr: dcutr(),
+			autoNAT: autoNAT(),
 			pubsub: gossipsub({
 				allowPublishToZeroTopicPeers: true,
 				heartbeatInterval: 7000
@@ -237,15 +381,26 @@ export async function createLibp2pNodeBase(
 			cluster: (components: any) => {
 				const serviceFactory = clusterService({
 					protocolPrefix: `/optimystic/${options.networkName}`,
-					configuredClusterSize: options.clusterSize ?? 10,
-					allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
-					clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5,
 					responsibilityK: options.responsibilityK ?? 1
 				});
 				return serviceFactory({
 					logger: components.logger,
 					registrar: components.registrar,
-					cluster: clusterProxy
+					cluster: clusterProxy,
+					// Identity for membership scoping on the update path. peerId is a core
+					// libp2p component, available at service-construction time.
+					peerId: components.peerId,
+					// Fallback addr resolver for redirect targets whose multiaddrs are not
+					// already embedded in record.peers.
+					getConnectionAddrs: (peerId: any) => {
+						const conns = components.libp2p?.getConnections?.(peerId) ?? [];
+						const addrs: string[] = [];
+						for (const c of conns) {
+							const addr = c.remoteAddr?.toString?.();
+							if (addr) addrs.push(addr);
+						}
+						return addrs;
+					}
 				});
 			},
 
@@ -254,6 +409,15 @@ export async function createLibp2pNodeBase(
 					protocolPrefix: `/optimystic/${options.networkName}`,
 					responsibilityK: options.responsibilityK ?? 1
 				});
+				// RepoService.checkRedirect needs the running node (network manager for the
+				// responsible-set computation, self id for the membership check, connection
+				// addrs for redirect targets). The libp2p components.libp2p proxy does NOT
+				// reliably resolve from inside a service at request time, so the node is
+				// injected explicitly post-construction via setLibp2p(node) below — the same
+				// mechanism networkManager/fret use — rather than forwarded here. checkRedirect
+				// keys the responsible set on the RAW encoded block id
+				// (getCluster(encode(blockKey)) → hashKey(encode(...))), matching the
+				// coordinator's findCluster(encode(blockId)) — same cohort, no spurious redirect.
 				return serviceFactory({
 					logger: components.logger,
 					registrar: components.registrar,
@@ -272,6 +436,19 @@ export async function createLibp2pNodeBase(
 				});
 			},
 
+			// Block-transfer protocol handler for churn re-replication. Wired to the
+			// *local* storageRepo (not repoProxy): a pushed replica must land in this
+			// node's own storage, not be re-routed through the cluster-coordinated repo.
+			blockTransfer: (components: any) => {
+				const serviceFactory = blockTransferService({
+					protocolPrefix: `/optimystic/${options.networkName}`
+				});
+				return serviceFactory({
+					registrar: components.registrar,
+					repo: storageRepo
+				});
+			},
+
 			networkManager: (components: any) => {
 				const svcFactory = networkManagerService({
 					clusterSize: options.clusterSize ?? 10,
@@ -308,6 +485,11 @@ export async function createLibp2pNodeBase(
 	// Inject libp2p reference into services that need it before start
 	try { ((node as any).services?.fret as any)?.setLibp2p?.(node); } catch { }
 	try { ((node as any).services?.networkManager as any)?.setLibp2p?.(node); } catch { }
+	// RepoService.checkRedirect resolves the network manager / self id / connection
+	// addrs through this injected node (the components.libp2p proxy is unreliable
+	// from inside a service at request time). Done before start() so the protocol
+	// handler is live with a resolvable node from its first request.
+	try { ((node as any).services?.repo as any)?.setLibp2p?.(node); } catch { }
 
 	await node.start();
 
@@ -337,6 +519,60 @@ export async function createLibp2pNodeBase(
 		partitionDetectionWindow: 60000
 	};
 
+	// Fetch a block archive from one cohort peer over the sync protocol, bounded by a
+	// per-peer timeout so an unreachable peer can't stall reconciliation. Mirrors the
+	// SyncClient query in `clusterLatestCallback`, but returns the full archive (which
+	// carries the materialized block) rather than only the latest ActionRev.
+	const fetchArchiveFromPeer = async (peerIdStr: string, blockId: BlockId): Promise<BlockArchive | undefined> => {
+		let peerId: ReturnType<typeof peerIdFromString>;
+		try {
+			peerId = peerIdFromString(peerIdStr);
+		} catch {
+			return undefined;
+		}
+		if (peerId.equals(node.peerId)) return undefined;
+		const syncClient = new SyncClient(peerId, keyNetwork, protocolPrefix);
+		try {
+			const response = await Promise.race<SyncResponse>([
+				syncClient.requestBlock({ blockId, rev: undefined }),
+				new Promise<SyncResponse>(resolve => { setTimeout(() => resolve({ success: false }), 1000).unref(); })
+			]);
+			return response.success ? response.archive : undefined;
+		} catch {
+			// Peer unreachable / no data — caller falls back to the next cohort peer.
+			return undefined;
+		}
+	};
+
+	// Active reconciliation for a block this member committed without the matching pend
+	// (cohort drift). Queries the commit cohort (self already excluded) for the block,
+	// picks the highest revision that is at least the committed rev, and persists it via
+	// the churn-replication funnel so the block is no longer under-replicated.
+	const reconcileBlock: ReconcileBlockCallback = async (blockId, committed, cohortPeerIds) => {
+		const targets = cohortPeerIds.filter(id => id !== node.peerId.toString());
+		if (targets.length === 0) return;
+
+		const archives = await Promise.all(targets.map(peerIdStr => fetchArchiveFromPeer(peerIdStr, blockId)));
+
+		let best: { block: IBlock; source: ActionRev } | undefined;
+		for (const archive of archives) {
+			if (!archive) continue;
+			const revs = Object.keys(archive.revisions).map(Number);
+			if (revs.length === 0) continue;
+			const maxRev = Math.max(...revs);
+			if (maxRev < committed.rev) continue;
+			const data = archive.revisions[maxRev];
+			if (!data?.block) continue;
+			if (!best || maxRev > best.source.rev) {
+				best = { block: data.block, source: { actionId: data.action.actionId, rev: maxRev } };
+			}
+		}
+
+		if (best) {
+			await storageRepo.saveReplicatedBlock(blockId, best.block, best.source);
+		}
+	};
+
 	clusterImpl = clusterMember({
 		storageRepo,
 		peerNetwork: keyNetwork,
@@ -348,7 +584,15 @@ export async function createLibp2pNodeBase(
 		validator: options.validator,
 		reputation,
 		consensusConfig,
-		stateStore: options.transactionStateStore
+		stateStore: options.transactionStateStore,
+		reconcileBlock,
+		onCommitCertificate
+		// `recomputeArbitratorSet` (invalidation layer-2) is intentionally NOT wired here yet: a live FRET
+		// recompute needs a churn-tolerance window so it does not false-reject legitimate certificates from
+		// late-joiners (a liveness regression). Until that is tuned against live topology — and the
+		// cohort-topic membership-cert trust anchor (layer 3) lands — invalidation verification runs on the
+		// challenger-bound set + membership + dedup (layer 1) and LOGS the residual anchoring gap. See
+		// `verifyInvalidationCertificate` and `tickets/plan/cohort-topic-membership-cert-trust-anchoring.md`.
 	});
 
 	const coordinatorRepoFactory = coordinatorRepo(
@@ -409,6 +653,65 @@ export async function createLibp2pNodeBase(
 		await (coordinatedRepo as import('./repo/coordinator-repo.js').CoordinatorRepo).recoverTransactions();
 	}
 
+	// --- Churn-resilient spread: drive SpreadOnChurnMonitor on a live node ---
+	// Nothing previously activated the SENDING side of the churn-resilient spread protocol on a
+	// real node. Here we init + start the monitor and feed it the blocks this node physically
+	// holds, so a debounced connection:close re-pushes them to expansion-cohort peers (the
+	// receiver durably persists each push via saveReplicatedBlock).
+	const networkManager = (node as any).services?.networkManager as NetworkManagerService | undefined;
+	let spreadMonitor: SpreadOnChurnMonitor | undefined;
+	let offOwnedBlockFeed: (() => void) | undefined;
+	if (networkManager && (options.spreadOnChurn?.enabled ?? true) !== false) {
+		try {
+			spreadMonitor = networkManager.initSpreadOnChurnMonitor(
+				partitionDetector,
+				storageRepo,
+				keyNetwork,
+				options.clusterSize ?? 10,
+				protocolPrefix,
+				options.spreadOnChurn,
+			);
+			await spreadMonitor.start();
+			// Feed owned blocks: every block this node commits OR receives as a replica fires
+			// storageRepo.onAnyCollectionChange. Subscribe to storageRepo DIRECTLY (not
+			// node.blockChangeNotifier): the cohort-topic activation block below may replace
+			// blockChangeNotifier with a decorating bridge, but storageRepo keeps emitting on its
+			// own surface regardless of that opt-in. NOTE: blocks already durable from a previous
+			// run are NOT re-emitted on startup, so they are not tracked until next touched -
+			// acceptable here (churn re-replication re-derives over time); an initial-scan is a
+			// follow-on enhancement.
+			const monitor = spreadMonitor;
+			offOwnedBlockFeed = storageRepo.onAnyCollectionChange((e) => {
+				for (const blockId of e.blockIds) monitor.trackBlock(blockId);
+			});
+		} catch (err) {
+			// Spread is a resilience optimization, not a correctness requirement - a wiring
+			// failure (e.g. FRET briefly unavailable) must NOT hard-fail node startup, unlike the
+			// operator-opted-in cohortTopic block. Log and continue with spread inert.
+			((node as any).logger?.forComponent?.('db-p2p:spread-on-churn'))?.('init failed: %o', err);
+		}
+	}
+
+	// Expose for tests/diagnostics (mirrors node.keyNetwork / node.reputation).
+	(node as any).spreadOnChurnMonitor = spreadMonitor;
+
+	// Disposal: release the owned-block subscription + stop the monitor deterministically
+	// before the transports close. Composes with the arachnode / clusterMember / cohort-topic
+	// stop wrappers (each calls its captured previousStop last). Both steps are idempotent (the
+	// unsubscribe is flag-guarded; SpreadOnChurnMonitor.stop early-returns when not running), so
+	// a double node.stop() does not throw.
+	{
+		const previousStop = node.stop.bind(node);
+		node.stop = async () => {
+			try {
+				offOwnedBlockFeed?.();
+				if (spreadMonitor) await spreadMonitor.stop();
+			} finally {
+				await previousStop();
+			}
+		};
+	}
+
 	// Initialize Arachnode ring membership and restoration
 	const enableArachnode = options.arachnode?.enableRingZulu ?? true;
 	if (enableArachnode) {
@@ -519,9 +822,314 @@ export async function createLibp2pNodeBase(
 	// Expose coordinated repo and storage for external use
 	(node as any).coordinatedRepo = coordinatedRepo;
 	(node as any).storageRepo = storageRepo;
+	// The StorageRepo is the single commit funnel for both the coordinated and
+	// direct paths, so it is the node's per-collection change-notifier origin. This is the
+	// default; the cohort-topic activation block below REPLACES it with the origination-decorating
+	// bridge notifier when the substrate is enabled.
+	(node as any).blockChangeNotifier = storageRepo;
 	(node as any).keyNetwork = keyNetwork;
 	(node as any).reputation = reputation;
 	(node as any).disputeService = disputeServiceInstance;
 
+	// --- Cohort-topic origination activation (post-node: consumes the fully-assembled node + FRET) ---
+	// This is the only place that is after the node + FRET are assembled (node.start() done, fretSvc
+	// available) yet before any caller can capture `blockChangeNotifier` — the Quereus collection-factory
+	// captures it once, immediately after createLibp2pNode returns, and reuses that reference as
+	// `localChangeNotifier` for every NetworkTransactor it builds. Installing the bridge here makes the
+	// origination path live for ALL collections created on the node.
+	if (cohortEnabled) {
+		// The host needs the full FRET engine surface; node.services.fret is the wrapper (see resolveFretEngine).
+		const fret = resolveFretEngine(fretSvc);
+		if (!fret) {
+			// Operator opted in; degrading silently to the bare notifier would hide misconfiguration.
+			// The node has already started (transports open, FRET running), so tear it down before the
+			// hard-fail rather than leaking a started node + open transports on the rejection.
+			await node.stop();
+			throw new Error('cohortTopic enabled but the FRET service is unavailable on the node');
+		}
+
+		// A host-construction failure also hard-fails (operator opted in); stop the started node first so
+		// the rejection does not leak open transports / a running FRET service. node.stop() runs the
+		// already-installed arachnode + clusterMember teardown wrappers and closes the node's connections.
+		let host: Awaited<ReturnType<typeof createCohortTopicHost>>;
+		try {
+			host = await createCohortTopicHost(node, fret, {
+				...(options.cohortTopic!.host ?? {}),
+				// Wire the node's reputation service in as the production backing for the bootstrap-evidence
+				// referee verifier (the `{ isBanned, getScore }` view `PeerReputationService` satisfies), so a
+				// configured cohort genuinely gates cold-root `bootstrap: true` (PoW always; reputation when a
+				// referee endorsement is offered; a signed reference to an existing parent topic on any tier).
+				// The node service is the *default* backing — a caller that supplies its own `antiDos.reputation`
+				// (or any other `antiDos` override) still wins, since the caller spread comes last.
+				antiDos: { reputation, ...(options.cohortTopic!.host?.antiDos) },
+				// committedParentTopicReader (the T0/T1 committed-tier parent-reference existence backing) is
+				// intentionally left unwired: no coord-keyed committed-membership index exists yet (the
+				// transaction-log commit certificate is keyed by action, not by coord_0). So the host default
+				// fails T0/T1 parent-ref existence closed — a FRET-cached cert must not vouch for committed-tier
+				// existence (committed-tier integrity) — while T2/T3 parent-ref consults the FRET membership cache
+				// for real. The dedicated committed backing is the follow-on `cohort-topic-parent-ref-tx-log-content`;
+				// an operator may still pass one via cohortTopic.host.committedParentTopicReader.
+				privateKey: nodePrivateKey, // real k − x threshold signing
+				wantK: cohortWantK,
+			});
+		} catch (err) {
+			await node.stop();
+			throw err;
+		}
+
+		// selfIsCohortMember: this node owns the collection's reactivity-topic fan-out iff it is in the
+		// FRET cohort around coord_0(H(currentTailId ‖ "reactivity")). Uses db-core's default hashes
+		// (createReactivityTopicAnchor / createTierAddressing / createRingHash), byte-identical to the
+		// host's internal `new RingHash()` and the subscriber-side anchor, and the SAME cohortWantK as
+		// the host — so the coord + cohort line up across origination and subscription.
+		const selfIsCohortMember = createReactivitySelfMembershipGate({
+			fret,
+			selfPeerId: node.peerId.toString(),
+			wantK: cohortWantK,
+		});
+
+		const { unsubscribe } = attachCohortChangeBridge(
+			node as unknown as { blockChangeNotifier?: IBlockChangeNotifier },
+			{
+				source: storageRepo,
+				service: host.service,
+				selfIsCohortMember,
+				extractCommitCert: makeClusterCommitCertExtractor(certStore!),
+			},
+		);
+
+		// Expose the host so the reactivity origination wiring (and the activation test) can install
+		// `CohortTopicService.onLocalCommit`.
+		(node as any).cohortTopicHost = host;
+
+		// --- Reactivity notification transport (origination → fan-out → inbound delivery → push-state gossip) ---
+		// Compose notify + forwarder-host + push-state-gossip onto the cohort-topic host so a committed change
+		// on a tail-cohort member actually reaches subscribers on OTHER nodes over real sockets. The change
+		// bridge above fires `onLocalCommit`; this is what the emitted notifications travel over.
+		// (docs/reactivity.md §Notification origination / §Propagation.) Reactivity reuses the canonical,
+		// network-agnostic protocol IDs, matching the cohort-topic family's production default.
+		const selfPeerId = node.peerId.toString();
+		const reactivityProtocols = DEFAULT_REACTIVITY_PROTOCOLS;
+		const reactivityProfile = host.profile; // Edge ⇒ subscriber-only via the policy gate; Core forwards.
+		const reactivityPolicy = reactivityNodePolicy(reactivityProfile);
+		// db-core default anchor + tier addressing, byte-identical to the host's `new RingHash()`, the
+		// origination gate, and the subscriber-side anchor — so coord_0 derivation lines up everywhere.
+		const reactivityAddressing = createTierAddressing(createRingHash());
+		// Reactivity's forwarder cohort sits at coord_0 — TREE tier 0 (peer-independent), distinct from the
+		// CAPACITY tier T3 the verifier/willingness use. `registry.findServing` keys on the engine's tree
+		// depth, so the served reactivity engine is found at tree tier 0, never at 3.
+		const REACTIVITY_FORWARDER_TREE_TIER = 0;
+
+		// Node-level subscriber registry: a constructed ReactivitySubscriptionManager registers here so a
+		// socket-delivered NotificationV1 reaches it. (The Quereus Database.watch → manager bridge that
+		// CONSTRUCTS managers stays the backlog item optimystic-network-reactive-watch-integration-test.)
+		const reactivitySubscribers = new ReactivitySubscriberRegistry();
+		(node as any).reactivitySubscribers = reactivitySubscribers;
+
+		// 1. Notify transport — unicast NotificationV1 send + inbound subscribe. selfPeerId guards self-dials.
+		const notify = new Libp2pReactivityNotifyTransport(node, { selfPeerId });
+
+		// 2. Forwarder host — turns the forward decision into live fan-out over the notify transport.
+		const forwarderHost = new ReactivityForwarderHost({
+			transport: notify,
+			selfPeerId,
+			profile: reactivityProfile,
+			pushStateInit: (topicId: Uint8Array, n: NotificationV1): PushStateInit => ({
+				collectionId: n.collectionId,
+				topicId: bytesToB64url(topicId),
+				tailIdAtJoin: n.tailId,
+				deltaMaxBytes: reactivityPolicy.deltaMaxBytes,
+			}),
+			verifierFor: (): NotificationVerifier => createNotificationVerifier({ verifier: host.service.verifier(), tier: Tier.T3 }),
+			directSubscribers: (topicId: Uint8Array): string[] => {
+				// Find the served reactivity engine at TREE tier 0 (see REACTIVITY_FORWARDER_TREE_TIER) and read
+				// its direct-subscriber records. The adapter filters to reactivity appState and maps participantId
+				// bytes → dialable peer-id strings (the transport's `peerIdFromString` space) — NOT base64url,
+				// which would silently fail to dial. `undefined` (no subscriber has registered here yet) ⇒ [].
+				const engine = host.registry.findServing(topicId, REACTIVITY_FORWARDER_TREE_TIER);
+				return engine === undefined ? [] : reactivityDirectSubscribers(engine, topicId);
+			},
+			// No childCohorts until cohort-topic-parent-child-link populates PushState.childCohorts (single
+			// tier-0 reach today); wire the resolver anyway. A child cohort's primary is the FRET-nearest member
+			// of its coord, returned as a peer-id string (the dial space).
+			resolveChildPrimary: (ref: CohortRef): string | undefined => {
+				const peers = fret.assembleCohort(b64urlToBytes(ref.coord), cohortWantK);
+				return peers.length > 0 ? peers[0] : undefined;
+			},
+			deliverLocal: (topicId: Uint8Array, n: NotificationV1): void => reactivitySubscribers.deliver(topicId, n),
+		});
+
+		// Inbound notify frames → forwarder host (subscriber role delivers in-process; forwarder role fans out).
+		registerNotifyHandler(node, reactivityProtocols.notify, notify);
+		const offInboundNotify = notify.onNotification((from, n): void => { void forwarderHost.onInbound(from, n); });
+
+		// 3. Origination emit — install onLocalCommit: a member commit builds a NotificationV1 and ingests it.
+		const origination = new ReactivityOriginationManager({
+			service: host.service,
+			resolveContext: (event) => {
+				if (event.tailId === undefined) {
+					return undefined; // tail-less (read-driven promotion) never originates (the gate also returns first)
+				}
+				return {
+					// MUST reuse the gate's `reactivityTailBytes` (utf8), NOT db-core's double-hashing
+					// blockIdToBytes — else origination derives a different coord than subscribers resolve.
+					tailId: reactivityTailBytes(event.tailId),
+					deltaMaxBytes: reactivityPolicy.deltaMaxBytes,
+					// rotationHint stays undefined on a live node: the successor tail id is not knowable at the
+					// filling commit (random block ids; gated on 6.5-block-id-derivation). The authoritative,
+					// observable rotation signal is `event.tailId` CHANGING, which the manager observes via the
+					// `markRotated` binding below. (The pre-announce remains exercised in the mock-tier harness +
+					// the design simulator, both of which can synthesize the successor id.)
+				};
+			},
+			// reactivityNotificationTopicId(n) = reactivityTopicId(b64urlToBytes(n.tailId)); since
+			// n.tailId = b64url(reactivityTailBytes(tail)), this is the SAME topicId the gate assembled coord_0
+			// around and the subscriber/forwarder verifier derives — closing the encoding loop.
+			emit: (n): void => { void forwarderHost.ingest(reactivityNotificationTopicId(n), n); },
+			// Observe-rotation: when a collection's tail id changes between commits the OLD tail's reactivity
+			// topic has rotated. Start its drain so the recover serve begins redirecting to the new tree (the
+			// `reactivity-rotation-recover-redirect-drain` markRotated seam). `oldTopicId` is byte-identical to
+			// the topic a subscriber subscribed under (both `reactivityTopicId(reactivityTailBytes(tail))`).
+			markRotated: (oldTopicId, redirect, now): void => forwarderHost.markRotated(oldTopicId, redirect, now),
+		});
+		origination.install();
+
+		// 4. PushState gossip — periodic intra-cohort convergence so any member (not just the primary) can
+		// serve a replay/backfill. Rides the host's cohort gossip transport (no second transport).
+		const pushStateGossip = new ReactivityPushStateGossipDriver({
+			gossipTransport: host.gossipTransport,
+			liveCollections: (): ReactivityGossipCollection[] => forwarderHost.livePushStates().map((pushState) => ({
+				pushState,
+				cohortCoord: reactivityAddressing.coord0(b64urlToBytes(pushState.topicId)),
+			})),
+			pushStateForGossip: (g: PushStateGossipV1) => forwarderHost.pushStateFor(b64urlToBytes(g.topicId)),
+			// Authenticity gate: accept gossip only from a member of the cohort around the frame's reactivity
+			// coord (per-frame peer-sig envelope signing is deferred — reactivity-pushstate-gossip's hardening backlog).
+			isCohortMember: (fromPeerId: string, g: PushStateGossipV1): boolean =>
+				fret.assembleCohort(reactivityAddressing.coord0(b64urlToBytes(g.topicId)), cohortWantK).includes(fromPeerId),
+		});
+		registerPushStateGossipHandler(node, reactivityProtocols.pushStateGossip, pushStateGossip);
+		pushStateGossip.start();
+
+		// 5. Recover RPC — the pull companion to notify (docs/reactivity.md §Backfill RPC / §Resume). A
+		// subscriber that detected a gap, or woke from sleep past the live tail, asks a serving cohort member
+		// "what did I miss?" and is brought current over a real request-reply socket. The SERVE side is live
+		// here: this node answers RecoverRequestV1 frames against its live forwarder PushStates. The OUTBOUND
+		// transport + signers are constructed and exposed for the subscribe factory that CONSTRUCTS managers
+		// (the Quereus Database.watch app-bridge — backlog optimystic-network-reactive-watch-integration-test);
+		// no node-internal manager calls them yet, exactly as the notify subscriber side is constructed against
+		// `reactivitySubscribers` rather than from a watch.
+		//
+		// Node-level sticky cohort-hint cache (keyed by collectionId), shared between the outbound transport's
+		// sticky-primary lookup and a future manager's rotation-invalidation so both see ONE cache. It starts
+		// empty ⇒ the transport falls through to the cohort-walk (any member holding the gossiped PushState
+		// answers); populating the sticky primary is a one-RT optimization, not a correctness need.
+		const reactivityCohortHintCache = createStickyCohortHintCache();
+		// topicId → dialable cohort member peer-id strings: the SAME FRET coord_0 assembly the push-state-gossip
+		// authenticity gate uses (`reactivityAddressing.coord0` → `fret.assembleCohort`), so a recover walk
+		// reaches exactly the cohort that holds the topic's gossiped PushState. `assembleCohort` returns peer-id
+		// strings (the recover dialer's `peerIdFromString` space), matching the notify dial-target space.
+		const resolveReactivityCohort = (topicId: Uint8Array): string[] =>
+			fret.assembleCohort(reactivityAddressing.coord0(topicId), cohortWantK);
+
+		// Outbound transport: exposes the db-core BackfillTransport / ResumeTransport seams against this node.
+		// maxBytes is omitted so the dialer + handler default to DEFAULT_STREAM_MAX_BYTES, matching the notify
+		// transport's default (constructed above without an override) — one frame ceiling across the family.
+		const recover = new Libp2pReactivityRecoverTransport({
+			dialer: createLibp2pRecoverDialer(node, reactivityProtocols.recover),
+			selfPeerId,
+			cohortHintCache: reactivityCohortHintCache,
+			resolveCohort: resolveReactivityCohort,
+		});
+
+		// Inbound serve handler: decode (bounded) → verify the dialing peer's signature → freshness/replay gate →
+		// resolve the live PushState off the forwarder host → serveBackfill/serveResume → reply (no reply on any
+		// failure; the stream aborts and the subscriber walks/chain-reads). One node-level replay guard is shared
+		// across all recover requests — a plain pruned-on-access map, so no new timer to tear down.
+		registerRecoverHandler(node, reactivityProtocols.recover, {
+			pushStateFor: forwarderHost.pushStateFor.bind(forwarderHost),
+			pushStateForCollection: forwarderHost.pushStateForCollection.bind(forwarderHost),
+			replayGuard: createCorrelationReplayGuard(),
+			rotationFor: (req, now) => {
+				// Drain-window redirect: a recover reaching an OLD (rotated, still-draining) tail is bounced to
+				// the new tree (reactivity-rotation-recover-redirect-drain). A resume carries the stale topic
+				// (topicId = reactivityTopicId(latestKnownTailId)); a backfill carries no topic, so resolve the
+				// collection's current served topic. rotationRedirectFor returns the gate's redirect while
+				// draining and undefined once drained (then evicting the gate + the old tail's served PushState).
+				const oldTopicId = req.topicId ?? resolveCurrentServedTopic(forwarderHost, req.collectionId);
+				return oldTopicId === undefined ? undefined : forwarderHost.rotationRedirectFor(oldTopicId, now);
+			},
+		});
+
+		// The subscriber's synchronous request signers over the node's Ed25519 key (resolves the recover wiring's
+		// lone design point — see recover-transport.ts §createRecoverRequestSigners). Fed to a manager by the
+		// subscribe factory alongside recover.backfillTransport(topicId, collectionId) /
+		// recover.resumeTransport(topicId, collectionId).
+		const recoverSigners = createRecoverRequestSigners(nodePrivateKey);
+
+		// Expose the recover seams so the subscribe factory wires backfill/resume RPC + signers + the shared
+		// sticky cache (mirrors `reactivitySubscribers` above).
+		(node as any).reactivityRecover = recover;
+		(node as any).reactivityRecoverSigners = recoverSigners;
+		(node as any).reactivityCohortHintCache = reactivityCohortHintCache;
+
+		// 6. Rotation re-registration scheduler — the host timer that moves a subscriber to the rotated tree
+		// when its manager surfaces a `RotationNotice` (`reactivity-rotation-rereg-scheduler`). Constructed with
+		// the default unref'd `setTimeout` timer so an idle re-registration never pins the process. The
+		// `reRegister(plan)` MOVE belongs to the subscribe factory that CONSTRUCTS managers (the deferred Quereus
+		// `Database.watch` bridge — backlog optimystic-network-reactive-watch-integration-test): on fire it builds
+		// a fresh `ReactivitySubscriptionManager` under `plan.newTopicId` carrying `plan.lastRevision`, registers
+		// it, and swaps the `ReactivitySubscriberRegistry` entry — registering the NEW-topic handler BEFORE
+		// unregistering the old, so a notification mid-swap is never dropped. Until that factory lands no
+		// node-internal manager drives `schedule()`, so this seam is a logged no-op — exactly as 12.33 exposed
+		// `reactivitySubscribers` / `reactivityRecover` without a live manager constructor.
+		const reactivityRotation = new RotationReRegistrationScheduler({
+			reRegister: (plan): Promise<void> => {
+				reactivityWiringLog("reactivity rotation re-registration fired for successor topic=%s (lastRevision=%d) but no subscribe factory is wired yet — deferred to optimystic-network-reactive-watch-integration-test", bytesToB64url(plan.newTopicId), plan.lastRevision);
+				return Promise.resolve();
+			},
+		});
+		(node as any).reactivityRotation = reactivityRotation;
+
+		// --- Matchmaking QueryV1 RPC — cohort serve side (docs/matchmaking.md §Seeker query) ---
+		// The server half of the seeker query transport: a remote seeker dials `/optimystic/matchmaking/1.0.0/query`
+		// and this node answers with its cohort's locally-held provider/seeker registrations, signed by the node
+		// peer key. Matchmaking is layered ABOVE the cohort-topic substrate, so it owns its own protocol family
+		// and is wired here (the composition root) over the host's PUBLIC surface only — mirroring the reactivity
+		// registration above; nothing reaches into host.ts internals. The OUTBOUND seeker walk client is the
+		// prereq follow-on `matchmaking-query-rpc-seeker-walk`; only the serve side is live here.
+		const matchmakingProtocols = DEFAULT_MATCHMAKING_PROTOCOLS;
+		registerMatchmakingQueryHandler(node, matchmakingProtocols.query, {
+			registry: host.registry,
+			// Reuse the reactivity addressing: createTierAddressing(createRingHash()) is byte-identical to the
+			// host's internal addressing for the tier-0 coord (peer- and fanout-independent), and the handler
+			// only ever derives coord_0(topicId).
+			addressing: reactivityAddressing,
+			// Single-member reply signature over the node peer key (same pattern reactivity uses for its signers).
+			sign: async (payload: Uint8Array): Promise<string> => bytesToB64url(await signPeer(nodePrivateKey, payload)),
+			// Anti-DoS rate-limit seam (backlog matchmaking-query-rate-limit) intentionally left unwired here:
+			// default-allow. When that ticket lands it passes a `gate: (from, topicId) => boolean` that limits on
+			// the connection's verified `from` peer (NOT the self-asserted query.requesterId).
+		});
+
+		// Teardown: release reactivity timers + protocol handlers BEFORE host.stop() (which clears the cohort
+		// gossip timer + unhandles the cohort-topic protocols) BEFORE the node's transports close (previousStop).
+		// Composes with the existing arachnode + clusterMember stop wrappers (each calls its captured previousStop last).
+		const previousStop = node.stop.bind(node);
+		node.stop = async (): Promise<void> => {
+			try {
+				reactivityRotation.stop();
+				pushStateGossip.stop();
+				offInboundNotify();
+				await node.unhandle(reactivityProtocolList(reactivityProtocols));
+				await node.unhandle(matchmakingProtocolList(matchmakingProtocols));
+				unsubscribe();
+				await host.stop();
+			} finally {
+				await previousStop();
+			}
+		};
+	}
+
 	return node;
 }