@optimystic/db-p2p 0.13.5 → 0.14.0

package/dist/src/libp2p-node-base.js

@@ -3,17 +3,21 @@ 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 } from '@libp2p/circuit-relay-v2';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { generateKeyPair } from '@libp2p/crypto/keys';
 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 { clusterMember } from './cluster/cluster-repo.js';
+import { createCommitCertStore, makeClusterCommitCertExtractor } from './cluster/commit-cert.js';
 import { coordinatorRepo } from './repo/coordinator-repo.js';
 import { Libp2pKeyPeerNetwork } from './libp2p-key-network.js';
 import { ClusterClient } from './cluster/client.js';
@@ -25,16 +29,65 @@ import { RestorationCoordinator } from './storage/restoration-coordinator-v2.js'
 import { RingSelector } from './storage/ring-selector.js';
 import { StorageMonitor } from './storage/storage-monitor.js';
 import { ArachnodeFretAdapter } from './storage/arachnode-fret-adapter.js';
+import { createCohortTopicHost } 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 } 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, } 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';
+/** Logger for the reactivity node-wiring (origination/forwarder/recover/rotation composition). */
+const reactivityWiringLog = createLogger('reactivity-node-wiring');
 function resolveStorage(provider) {
     if (!provider) {
         return new MemoryRawStorage();
     }
     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) {
+    if (!fret) {
+        return undefined;
+    }
+    const candidate = fret;
+    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, collectionId) {
+    const ps = forwarderHost.pushStateForCollection(collectionId);
+    return ps === undefined ? undefined : b64urlToBytes(ps.topicId);
+}
 export async function createLibp2pNodeBase(options, defaults) {
     const rawStorage = resolveStorage(options.storage);
     // Create placeholder restore callback (will be replaced after node starts)
@@ -74,6 +127,22 @@ export async function createLibp2pNodeBase(options, defaults) {
     const nodePrivateKey = options.privateKey ?? await generateKeyPair('Ed25519');
     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 = cohortEnabled ? createCommitCertStore() : undefined;
+    const onCommitCertificate = 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) => { certStore.put(actionId, cert); options.onCommitCertificate?.(actionId, cert); }
+        : options.onCommitCertificate;
     const libp2pOptions = {
         start: false,
         privateKey: nodePrivateKey,
@@ -96,6 +165,13 @@ export async function createLibp2pNodeBase(options, defaults) {
                 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
@@ -106,15 +182,27 @@ export async function createLibp2pNodeBase(options, defaults) {
             cluster: (components) => {
                 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) => {
+                        const conns = components.libp2p?.getConnections?.(peerId) ?? [];
+                        const addrs = [];
+                        for (const c of conns) {
+                            const addr = c.remoteAddr?.toString?.();
+                            if (addr)
+                                addrs.push(addr);
+                        }
+                        return addrs;
+                    }
                 });
             },
             repo: (components) => {
@@ -122,6 +210,15 @@ export async function createLibp2pNodeBase(options, defaults) {
                     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,
@@ -138,6 +235,18 @@ export async function createLibp2pNodeBase(options, defaults) {
                     repo: repoProxy
                 });
             },
+            // 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) => {
+                const serviceFactory = blockTransferService({
+                    protocolPrefix: `/optimystic/${options.networkName}`
+                });
+                return serviceFactory({
+                    registrar: components.registrar,
+                    repo: storageRepo
+                });
+            },
             networkManager: (components) => {
                 const svcFactory = networkManagerService({
                     clusterSize: options.clusterSize ?? 10,
@@ -184,6 +293,14 @@ export async function createLibp2pNodeBase(options, defaults) {
         node.services?.networkManager?.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.services?.repo?.setLibp2p?.(node);
+    }
+    catch { }
     await node.start();
     // Initialize peer reputation service
     const reputation = new PeerReputationService();
@@ -209,6 +326,63 @@ export async function createLibp2pNodeBase(options, defaults) {
         clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5,
         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, blockId) => {
+        let peerId;
+        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([
+                syncClient.requestBlock({ blockId, rev: undefined }),
+                new Promise(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 = 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;
+        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,
@@ -220,7 +394,15 @@ export async function createLibp2pNodeBase(options, defaults) {
         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(keyNetwork, createClusterClient, {
         clusterSize: options.clusterSize ?? 10,
@@ -271,6 +453,59 @@ export async function createLibp2pNodeBase(options, defaults) {
         await clusterImpl.recoverTransactions();
         await coordinatedRepo.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.services?.networkManager;
+    let spreadMonitor;
+    let offOwnedBlockFeed;
+    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.logger?.forComponent?.('db-p2p:spread-on-churn'))?.('init failed: %o', err);
+        }
+    }
+    // Expose for tests/diagnostics (mirrors node.keyNetwork / node.reputation).
+    node.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) {
@@ -364,9 +599,291 @@ export async function createLibp2pNodeBase(options, defaults) {
     // Expose coordinated repo and storage for external use
     node.coordinatedRepo = coordinatedRepo;
     node.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.blockChangeNotifier = storageRepo;
     node.keyNetwork = keyNetwork;
     node.reputation = reputation;
     node.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;
+        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, {
+            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.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.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, n) => ({
+                collectionId: n.collectionId,
+                topicId: bytesToB64url(topicId),
+                tailIdAtJoin: n.tailId,
+                deltaMaxBytes: reactivityPolicy.deltaMaxBytes,
+            }),
+            verifierFor: () => createNotificationVerifier({ verifier: host.service.verifier(), tier: Tier.T3 }),
+            directSubscribers: (topicId) => {
+                // 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) => {
+                const peers = fret.assembleCohort(b64urlToBytes(ref.coord), cohortWantK);
+                return peers.length > 0 ? peers[0] : undefined;
+            },
+            deliverLocal: (topicId, n) => 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 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 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) => 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: () => forwarderHost.livePushStates().map((pushState) => ({
+                pushState,
+                cohortCoord: reactivityAddressing.coord0(b64urlToBytes(pushState.topicId)),
+            })),
+            pushStateForGossip: (g) => 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, g) => 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) => 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.reactivityRecover = recover;
+        node.reactivityRecoverSigners = recoverSigners;
+        node.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) => {
+                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.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) => 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 () => {
+            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;
 }
 //# sourceMappingURL=libp2p-node-base.js.map