@optimystic/db-p2p 0.13.5 → 0.14.1

package/src/reactivity/forwarder-host.ts

@@ -0,0 +1,438 @@
+/**
+ * Reactivity — forwarder **host** orchestrator (`docs/reactivity.md` §Propagation, §Slow-subscriber
+ * backpressure, §Per-cohort policy).
+ *
+ * This is the piece that turns the in-process forward *decision* (db-core's {@link ReactivityForwarder})
+ * into live fan-out over the {@link ReactivityNotifyTransport}. For one {@link NotificationV1} — whether
+ * locally originated (the change-bridge's `emit` seam binds to {@link ReactivityForwarderHost.ingest}) or
+ * inbound off a dial ({@link ReactivityForwarderHost.onInbound}) — it:
+ *
+ *  1. lazily instantiates the per-collection {@link PushState} + forwarder behind the Edge policy gate
+ *     ({@link instantiateForwarderPushState}: `undefined` on an Edge node ⇒ this node never forwards);
+ *  2. runs the db-core receive path (verify → dedupe → buffer) and stops on `"duplicate"` / `"untrusted"`;
+ *  3. on `"forward"`, fans the **unmodified** frame out to every direct subscriber (through the
+ *     per-subscriber bounded queue, so a slow/dead subscriber's drops never stall the rest) and every
+ *     child cohort.
+ *
+ * It owns the per-subscriber dequeue→dial delivery loop, the bounded-queue backpressure interaction,
+ * subscriber-queue eviction (the memory bound — a departed subscriber's queue is reclaimed lazily each
+ * fan-out round), and per-topic serialization so the replay ring + dedupe set never interleave across two
+ * concurrent notifications for the same collection.
+ *
+ * **Subscriber-id space.** `selfPeerId`, the {@link ReactivityForwarderHostDeps.directSubscribers} output,
+ * the {@link CohortRef.primary} child targets, and every {@link ReactivityNotifyTransport.send} target are
+ * the **same** string space (it is also the `perSubscriberQueue` key). This host is agnostic to the concrete
+ * encoding so long as it is consistent across all four seams; the **transport** pins which space —
+ * {@link import("./notify-transport.js").Libp2pReactivityNotifyTransport.send} calls `peerIdFromString`, so
+ * the space is the **canonical peer-id string** (NOT base64url-of-member-bytes — that would silently fail
+ * `peerIdFromString` and never dial). The {@link reactivityDirectSubscribers} adapter and the node-wiring
+ * layer ([reactivity-notification-transport]) therefore both emit peer-id strings.
+ *
+ * This module deliberately touches neither the libp2p node assembly ([reactivity-notification-transport])
+ * nor gossip ([reactivity-pushstate-gossip]); it depends only on the transport interface + db-core logic,
+ * so it is unit-testable with a fake transport.
+ */
+
+import {
+	reactivityTopicId,
+	b64urlToBytes,
+	bytesToB64url,
+	createReactivityForwarder,
+	instantiateForwarderPushState,
+	decodeSubscribeAppPayload,
+	TailDrainGate,
+	type NotificationV1,
+	type PeerRef,
+	type NodeProfile,
+	type PushState,
+	type PushStateInit,
+	type CohortRef,
+	type NotificationVerifier,
+	type ReactivityForwarder,
+	type RegistrationRecord,
+	type RotationRedirectV1,
+} from "@optimystic/db-core";
+import type { ReactivityNotifyTransport } from "./notify-transport.js";
+import { bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-forwarder-host");
+
+/**
+ * The reactivity topic id a notification belongs to: `H(tailId ‖ "reactivity")` over the notification's
+ * tail anchor. Kept in one place so it matches origination's `reactivityTailBytes` encoding and the
+ * subscriber/forwarder verifier's coord derivation byte-for-byte (both decode `tailId` as base64url first).
+ */
+export function reactivityNotificationTopicId(n: NotificationV1): Uint8Array {
+	return reactivityTopicId(b64urlToBytes(n.tailId));
+}
+
+/** The minimal cohort read the {@link reactivityDirectSubscribers} adapter needs (a {@link CoordEngine} satisfies it). */
+export interface ReactivityRecordSource {
+	/** This cohort's locally-known direct registration records for `topicId`. */
+	records(topicId: Uint8Array): readonly RegistrationRecord[];
+}
+
+/**
+ * The direct-subscriber **peer-id strings** for a reactivity topic, read from a cohort's
+ * {@link RegistrationRecord} set: a record carries a subscriber iff its opaque `appState` decodes to a
+ * reactivity {@link import("@optimystic/db-core").SubscribeAppPayloadV1}. `record.participantId` is the
+ * subscriber's dialable member id (db-core's `service` pins `participantId = self`), carried as
+ * `peerIdToBytes(peerId) = utf8(peerIdString)`; this decodes it back to the canonical peer-id string via
+ * {@link bytesToPeerIdString} so the value is both the `transport.send` dial target (which calls
+ * `peerIdFromString`) and the `perSubscriberQueue` key. **The whole host runs in this peer-id-string space**
+ * — `selfPeerId`, `resolveChildPrimary`, and every `send` target must agree, or a base64url-vs-peer-id
+ * mismatch is a silent no-dial. A record whose `appState` is absent or decodes to a non-reactivity payload
+ * (e.g. a matchmaking registration sharing the cohort store) is skipped.
+ */
+export function reactivityDirectSubscribers(source: ReactivityRecordSource, topicId: Uint8Array): string[] {
+	const out: string[] = [];
+	for (const record of source.records(topicId)) {
+		if (record.appState === undefined) {
+			continue;
+		}
+		try {
+			decodeSubscribeAppPayload(record.appState); // throws on a non-reactivity / malformed payload
+		} catch {
+			continue; // not a reactivity subscriber — leave the record to its own application
+		}
+		out.push(bytesToPeerIdString(record.participantId));
+	}
+	return out;
+}
+
+/** Construction inputs for a {@link ReactivityForwarderHost}. */
+export interface ReactivityForwarderHostDeps {
+	/** One-way notification transport (unicast send + inbound subscribe); fan-out dials each target through it. */
+	readonly transport: ReactivityNotifyTransport;
+	/** This node's member id, base64url — never dialed; a co-located subscriber is delivered in-process. */
+	readonly selfPeerId: string;
+	/** Node profile; gates {@link PushState} instantiation (Edge ⇒ subscriber-only, never forwards). */
+	readonly profile: NodeProfile;
+	/** Build the per-collection {@link PushStateInit} on first ingest for a topic this node serves. */
+	readonly pushStateInit: (topicId: Uint8Array, n: NotificationV1) => PushStateInit;
+	/** The notification verifier for a topic (a db-core `createNotificationVerifier` over the host's service verifier, T3). */
+	readonly verifierFor: (topicId: Uint8Array) => NotificationVerifier;
+	/** Direct-subscriber member ids (base64url) for a topic — e.g. {@link reactivityDirectSubscribers} over the cohort. */
+	readonly directSubscribers: (topicId: Uint8Array) => string[];
+	/** Resolve a child cohort's dialable primary when {@link CohortRef.primary} is absent (e.g. a FRET resolver). */
+	readonly resolveChildPrimary?: (ref: CohortRef) => string | undefined;
+	/**
+	 * Route an inbound notification to a co-located subscription manager, when this node also subscribes the
+	 * topic. **Must be idempotent on `(collectionId, revision)`**: on the {@link ReactivityForwarderHost.onInbound}
+	 * path a node that is both a cohort member *and* a subscriber invokes this **twice** for the same
+	 * notification — once in the subscriber role (directly) and once in the forwarder role (when `self` is in
+	 * {@link directSubscribers}, via `fanOut`'s self-delivery). The db-core subscriber's `(collectionId,
+	 * revision)` dedupe (`createReactivitySubscriber`) collapses the second call to a no-op, so a correctly
+	 * wired manager delivers exactly once; a sink without that dedupe would double-deliver.
+	 */
+	readonly deliverLocal?: (topicId: Uint8Array, n: NotificationV1) => void;
+	/** Wall clock (unix ms) stamped on `receive`. Default `Date.now`. */
+	readonly clock?: () => number;
+}
+
+/** A topic this node forwards: its live {@link PushState} and the forwarder driving the receive path over it. */
+interface ServedTopic {
+	readonly pushState: PushState;
+	readonly forwarder: ReactivityForwarder;
+}
+
+/**
+ * The reactivity fan-out orchestrator. Build one per node; it serves every reactivity topic the node is a
+ * cohort member for, lazily instantiating per-collection state on first ingest. Bind
+ * {@link ReactivityForwarderHost.ingest} to the origination `emit` seam and
+ * {@link ReactivityForwarderHost.onInbound} to the transport's inbound subscribe.
+ */
+export class ReactivityForwarderHost {
+	private readonly transport: ReactivityNotifyTransport;
+	private readonly selfPeerId: string;
+	private readonly profile: NodeProfile;
+	private readonly pushStateInit: (topicId: Uint8Array, n: NotificationV1) => PushStateInit;
+	private readonly verifierFor: (topicId: Uint8Array) => NotificationVerifier;
+	private readonly directSubscribers: (topicId: Uint8Array) => string[];
+	private readonly resolveChildPrimary?: (ref: CohortRef) => string | undefined;
+	private readonly deliverLocal?: (topicId: Uint8Array, n: NotificationV1) => void;
+	private readonly clock: () => number;
+
+	/** Per-topic served state. `ServedTopic` ⇒ forwards; `null` ⇒ resolved subscriber-only (Edge); absent ⇒ unresolved. */
+	private readonly served = new Map<string, ServedTopic | null>();
+	/** Per-topic serialization tail: an ingest chains onto its topic's prior ingest so the ring/dedupe never interleave. */
+	private readonly ingestTails = new Map<string, Promise<void>>();
+	/**
+	 * Per **old-topic** drain gate: set by {@link markRotated} when this node observes the collection's tail
+	 * rotate, keyed by the outgoing tail's topicId (base64url). For `T_drain` after the rotation
+	 * {@link rotationRedirectFor} answers a recover request reaching the outgoing tail with the gate's
+	 * {@link RotationRedirectV1} ("this moved — go to the new tree"); once the window closes the entry is
+	 * evicted along with the topic's served `PushState`.
+	 */
+	private readonly rotationGates = new Map<string, TailDrainGate>();
+
+	constructor(deps: ReactivityForwarderHostDeps) {
+		this.transport = deps.transport;
+		this.selfPeerId = deps.selfPeerId;
+		this.profile = deps.profile;
+		this.pushStateInit = deps.pushStateInit;
+		this.verifierFor = deps.verifierFor;
+		this.directSubscribers = deps.directSubscribers;
+		this.resolveChildPrimary = deps.resolveChildPrimary;
+		this.deliverLocal = deps.deliverLocal;
+		this.clock = deps.clock ?? ((): number => Date.now());
+	}
+
+	/**
+	 * Local origination emit **and** the inbound forwarder path: receive → forward → fan-out for one
+	 * notification on `topicId`. Ingests for one topic run strictly in sequence (verify is async and the
+	 * replay ring + dedupe set must not interleave); ingests for different topics proceed concurrently.
+	 * Never rejects — a fan-out fault can never surface as a commit failure on the origination seam.
+	 */
+	ingest(topicId: Uint8Array, n: NotificationV1): Promise<void> {
+		const key = this.topicKey(topicId);
+		const prev = this.ingestTails.get(key) ?? Promise.resolve();
+		// Run regardless of the prior ingest's outcome; `ingestSerialized` isolates its own throws, so the
+		// chain never accumulates a rejection that would leak out of a later `ingest`.
+		const next = prev.then(
+			() => this.ingestSerialized(topicId, n, key),
+			() => this.ingestSerialized(topicId, n, key),
+		);
+		this.ingestTails.set(key, next);
+		return next;
+	}
+
+	/** One serialized ingest: resolve served state, run receive, fan out on `"forward"`. Isolates all throws. */
+	private async ingestSerialized(topicId: Uint8Array, n: NotificationV1, key: string): Promise<void> {
+		try {
+			const served = this.resolveServed(topicId, n, key);
+			if (served === null) {
+				return; // Edge / subscriber-only: this node never forwards (delivery rides onInbound → deliverLocal).
+			}
+			const decision = await served.forwarder.receive(n, this.clock());
+			if (decision !== "forward") {
+				return; // "duplicate" (already buffered) or "untrusted" (dropped before any state mutation).
+			}
+			this.fanOut(topicId, served.pushState, n);
+		} catch (err) {
+			log("ingest failed for topic=%s rev=%d (isolated): %o", key, n.revision, err);
+		}
+	}
+
+	/**
+	 * Inbound notify dial: run the **subscriber** role (in-process delivery to a co-located manager) and the
+	 * **forwarder** role (receive + fan-out) as applicable. A node that is both a cohort member and a
+	 * subscriber does both — the forwarder dedupe + the subscriber's `(collectionId, revision)` dedupe keep
+	 * it idempotent. Never rejects.
+	 */
+	async onInbound(_from: PeerRef, n: NotificationV1): Promise<void> {
+		let topicId: Uint8Array;
+		try {
+			topicId = reactivityNotificationTopicId(n);
+		} catch (err) {
+			log("onInbound: undecodable tailId on rev=%d (dropped): %o", n.revision, err);
+			return;
+		}
+		// Subscriber role first: deliver in-process to a co-located subscription manager, if any.
+		this.deliverInProcess(topicId, n);
+		// Forwarder role: ingest self-gates (Edge ⇒ no PushState; a non-member ⇒ empty fan-out).
+		await this.ingest(topicId, n);
+	}
+
+	/** The live {@link PushState} for a served topic, or `undefined` (Edge, or not yet ingested). Test/diagnostic. */
+	pushStateFor(topicId: Uint8Array): PushState | undefined {
+		const served = this.served.get(this.topicKey(topicId));
+		return served === undefined || served === null ? undefined : served.pushState;
+	}
+
+	/**
+	 * Every live forwarder {@link PushState} this node currently serves: the topics it has ingested at least
+	 * one notification for and instantiated state behind the Edge gate (subscriber-only `null`s and
+	 * not-yet-ingested topics are skipped). The push-state-gossip driver iterates these each round to
+	 * broadcast convergence state to each collection's cohort, so a member that missed an origin dial still
+	 * ends up holding the replay entry.
+	 */
+	livePushStates(): PushState[] {
+		const out: PushState[] = [];
+		for (const served of this.served.values()) {
+			if (served !== null) {
+				out.push(served.pushState);
+			}
+		}
+		return out;
+	}
+
+	/**
+	 * The live {@link PushState} this node serves for `collectionId` (base64url), or `undefined` if none.
+	 * The served map is keyed by **topicId**, but a backfill request carries only a collectionId and a
+	 * resume that lost its tail must still resolve the collection's current tail — so this scans for the
+	 * served topic whose `PushState.collectionId` matches. Across a tail-rotation **drain window** a
+	 * collection can briefly have two served topics (the outgoing and incoming tail); the one with the
+	 * highest `lastRevision` is the current tail, so that is the one returned. (The precise drain-window
+	 * redirect choreography is `reactivity-tail-rotation-transport`'s; this picks the current tail.)
+	 */
+	pushStateForCollection(collectionId: string): PushState | undefined {
+		let best: PushState | undefined;
+		for (const served of this.served.values()) {
+			if (served === null || served.pushState.collectionId !== collectionId) {
+				continue;
+			}
+			if (best === undefined || served.pushState.lastRevision > best.lastRevision) {
+				best = served.pushState;
+			}
+		}
+		return best;
+	}
+
+	/**
+	 * Record that the topic anchored on `oldTopicId` has **rotated** to a successor tail, starting a
+	 * {@link TailDrainGate} so the outgoing tail bounces recover requests to the new tree for `T_drain`
+	 * (`docs/reactivity.md` §Tail rotation step 2). db-core derives the redirect's `newTopicId` internally via
+	 * `reactivityTopicId(newTailId)`. The trigger is origination observing the collection's `event.tailId`
+	 * change ({@link reactivity-rotation-host-wiring-e2e}); this seam is called directly in unit tests.
+	 *
+	 * **Idempotent / chained.** A second `markRotated` for the **same** successor is a no-op; a `markRotated`
+	 * to a **later** successor (higher `effectiveAtRevision`) replaces the gate — so a chained OLD→A→B rotation
+	 * advances the redirect to the most recent successor and restarts its drain window from `now`. An earlier
+	 * (or equal) successor leaves the existing gate untouched.
+	 */
+	markRotated(oldTopicId: Uint8Array, redirect: { newTailId: string; effectiveAtRevision: number }, now: number): void {
+		const key = this.topicKey(oldTopicId);
+		const existing = this.rotationGates.get(key);
+		if (existing !== undefined && redirect.effectiveAtRevision <= existing.rotationRedirect.effectiveAtRevision) {
+			return; // same or earlier successor — the gate already points at this-or-a-later tail.
+		}
+		this.rotationGates.set(key, new TailDrainGate({
+			rotatedAt: now,
+			newTailId: redirect.newTailId,
+			effectiveAtRevision: redirect.effectiveAtRevision,
+		}));
+	}
+
+	/**
+	 * The drain-window redirect for a recover request that reached the outgoing tail anchored on `oldTopicId`,
+	 * or `undefined` if this topic never rotated / its drain window has elapsed. While the gate is draining
+	 * (`isDraining(now)`) returns its {@link RotationRedirectV1}; once `T_drain` closes, evicts the gate **and**
+	 * the topic's served `PushState` (the old tail originates nothing further — this also reclaims the
+	 * `served` / `ingestTails` maps the 12.31 review flagged as un-evicted on rotation) and returns `undefined`,
+	 * so the next request gets no reply and the subscriber re-walks / chain-reads.
+	 */
+	rotationRedirectFor(oldTopicId: Uint8Array, now: number): RotationRedirectV1 | undefined {
+		const key = this.topicKey(oldTopicId);
+		const gate = this.rotationGates.get(key);
+		if (gate === undefined) {
+			return undefined;
+		}
+		if (gate.isDraining(now)) {
+			return gate.rotationRedirect;
+		}
+		// Drain window closed: the outgoing tail is done. Drop the gate and reclaim its served state so the
+		// per-topic maps don't leak across rotations.
+		this.rotationGates.delete(key);
+		this.served.delete(key);
+		this.ingestTails.delete(key);
+		return undefined;
+	}
+
+	/**
+	 * Fan the unmodified frame out: reconcile (GC) departed-subscriber queues, enqueue per-subscriber
+	 * (drop-oldest under pressure), drain each queue and deliver (self in-process, others dialed, per-target
+	 * isolated), then dial each resolved child cohort. One slow/dead target never blocks the loop for the rest.
+	 */
+	private fanOut(topicId: Uint8Array, pushState: PushState, n: NotificationV1): void {
+		const subscriberIds = this.directSubscribers(topicId);
+
+		// Memory bound: drop any per-subscriber queue whose id left the live set (departed / TTL-expired /
+		// withdrawn). The map can never grow past the live subscriber set + the current round (lazy GC, so it
+		// shrinks at most one fan-out round late) — this satisfies the `subscribers × queue_max × size` bound.
+		this.reconcileQueues(pushState, subscriberIds);
+
+		// Enqueue onto each subscriber's bounded queue (a slow subscriber's drop-oldest isolates to its queue).
+		pushState.enqueueForSubscribers(subscriberIds, n);
+
+		// Drain + deliver per subscriber, isolated: one dead subscriber's dial never stalls the others.
+		for (const subId of subscriberIds) {
+			const queue = pushState.perSubscriberQueue.peekQueue(subId);
+			if (queue === undefined) {
+				continue;
+			}
+			for (const m of queue.drain()) {
+				this.deliverTo(topicId, subId, m);
+			}
+		}
+
+		// Child cohorts get the unmodified frame (forwarders never re-sign). No-op until the parent/child link
+		// lands ([cohort-topic-parent-child-link]) populates `childCohorts`.
+		for (const ref of pushState.childCohorts) {
+			const target = ref.primary ?? this.resolveChildPrimary?.(ref);
+			if (target !== undefined && target !== this.selfPeerId) {
+				this.dispatch(target, n);
+			}
+		}
+	}
+
+	/** Reclaim the queues of subscribers no longer in the live set (lazy, one round late). */
+	private reconcileQueues(pushState: PushState, subscriberIds: readonly string[]): void {
+		const live = new Set(subscriberIds);
+		// Snapshot the keys: `remove` mutates the backing map, which would invalidate a live iterator.
+		for (const id of [...pushState.perSubscriberQueue.subscribers()]) {
+			if (!live.has(id)) {
+				pushState.perSubscriberQueue.remove(id);
+			}
+		}
+	}
+
+	/** Deliver one notification to one subscriber: self in-process, everyone else over the transport. */
+	private deliverTo(topicId: Uint8Array, subId: string, n: NotificationV1): void {
+		if (subId === this.selfPeerId) {
+			this.deliverInProcess(topicId, n);
+		} else {
+			this.dispatch(subId, n);
+		}
+	}
+
+	/** Route to a co-located subscription manager, isolating a throwing subscriber from the rest of the fan-out. */
+	private deliverInProcess(topicId: Uint8Array, n: NotificationV1): void {
+		if (this.deliverLocal === undefined) {
+			return;
+		}
+		try {
+			this.deliverLocal(topicId, n);
+		} catch (err) {
+			log("local delivery threw (isolated) for rev=%d: %o", n.revision, err);
+		}
+	}
+
+	/** Fire one unicast send, isolated: a synchronous throw or a rejection is swallowed, never the loop's concern. */
+	private dispatch(target: string, n: NotificationV1): void {
+		let pending: Promise<void>;
+		try {
+			pending = this.transport.send(target, n);
+		} catch (err) {
+			log("notify send to %s threw synchronously (isolated): %o", target, err);
+			return;
+		}
+		void pending.catch((err: unknown) => {
+			log("notify send to %s rejected (isolated): %o", target, err);
+		});
+	}
+
+	/** Resolve (instantiating once, behind the Edge gate) the served state for a topic. */
+	private resolveServed(topicId: Uint8Array, n: NotificationV1, key: string): ServedTopic | null {
+		const existing = this.served.get(key);
+		if (existing !== undefined) {
+			return existing; // a `ServedTopic` or a remembered `null` (Edge / subscriber-only)
+		}
+		const pushState = instantiateForwarderPushState(this.profile, this.pushStateInit(topicId, n));
+		if (pushState === undefined) {
+			this.served.set(key, null); // Edge node: remember it never forwards this topic.
+			return null;
+		}
+		const served: ServedTopic = {
+			pushState,
+			forwarder: createReactivityForwarder({ state: pushState, verifier: this.verifierFor(topicId) }),
+		};
+		this.served.set(key, served);
+		return served;
+	}
+
+	private topicKey(topicId: Uint8Array): string {
+		return bytesToB64url(topicId);
+	}
+}

package/src/reactivity/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Reactivity — db-p2p wiring to the cohort-topic substrate.
+ *
+ * The db-core `reactivity` module owns the wire codecs, topic anchor, config, origination assembler,
+ * forwarder/dedupe/replay logic, and subscriber-side verify/deliver; these managers bind that to the
+ * participant-facing `CohortTopicService` (subscribe/renew/withdraw at tier T3) and install the
+ * `onLocalCommit` origination hook. See `docs/reactivity.md` §Subscription / §Notification origination.
+ */
+
+export * from "./topic-bytes.js";
+export * from "./protocols.js";
+export * from "./notify-transport.js";
+export * from "./recover-transport.js";
+export * from "./subscription-manager.js";
+export * from "./rotation-rereg-scheduler.js";
+export * from "./origination-manager.js";
+export * from "./forwarder-host.js";
+export * from "./push-state-gossip.js";
+export * from "./subscriber-registry.js";

package/src/reactivity/notify-transport.ts

@@ -0,0 +1,144 @@
+/**
+ * Reactivity notify transport — the one-way `NotificationV1` delivery primitive (`docs/reactivity.md`
+ * §Propagation).
+ *
+ * Unlike the cohort-gossip transport (which *broadcasts* a frame to a FRET-assembled cohort), notify is
+ * **unicast**: the fan-out orchestration above this layer (the `reactivity-forwarder-host` ticket) decides
+ * who to dial and calls {@link ReactivityNotifyTransport.send} once per named target. This module owns only
+ * the framing + dial + inbound-decode plumbing — no fan-out, no role decision, no gossip.
+ *
+ * The db-core `NotificationV1` codec ({@link encodeNotificationV1} / {@link decodeNotificationV1}) does the
+ * length-prefixed JSON framing; this layer rides one self-delimiting frame each way over the notify
+ * protocol, reusing the cohort-topic {@link sendOneWay} / {@link readAllBounded} stream lifecycle so the
+ * two protocol families behave identically on the wire.
+ *
+ * Failure isolation is the load-bearing property: notify is fire-and-forget and hint-only, so a dead /
+ * unreachable target's rejection is swallowed (logged), never propagated to the caller's fan-out loop or a
+ * commit. There is no reply frame — a handler that tried to send one back would desync the dialer's
+ * {@link sendOneWay} (which closes after send).
+ */
+
+import type { NotificationV1, PeerRef } from "@optimystic/db-core";
+import { encodeNotificationV1, decodeNotificationV1 } from "@optimystic/db-core";
+import type { Libp2p } from "libp2p";
+import type { Connection, Stream } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { readAllBounded } from "p2p-fret";
+import { peerIdToBytes } from "../cohort-topic/peer-codec.js";
+import { sendOneWay, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { PROTOCOL_REACTIVITY_NOTIFY } from "./protocols.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-notify");
+
+/** One-way `NotificationV1` transport: unicast send, inbound subscribe, and the host's deliver seam. */
+export interface ReactivityNotifyTransport {
+	/**
+	 * Frame `n` ({@link encodeNotificationV1}) and dial `target` (peer-id string) over the notify protocol.
+	 * Fire-and-forget, failure-isolated: a dead/unreachable target's rejection is swallowed (logged), never
+	 * propagated to the caller's fan-out loop.
+	 */
+	send(target: string, n: NotificationV1): Promise<void>;
+	/** Subscribe to inbound notifications (after decode); returns an unsubscribe handle. */
+	onNotification(handler: (from: PeerRef, n: NotificationV1) => void): () => void;
+	/** Feed an inbound notify frame (called by the host's notify protocol handler). */
+	deliver(fromPeerId: string, frame: Uint8Array): void;
+}
+
+/** Construction options for {@link Libp2pReactivityNotifyTransport}. */
+export interface ReactivityNotifyTransportOptions {
+	/** Notify protocol ID; default {@link PROTOCOL_REACTIVITY_NOTIFY}. */
+	readonly notifyProtocol?: string;
+	/** Per-frame ceiling for the inbound decode bound. Default {@link DEFAULT_STREAM_MAX_BYTES}. */
+	readonly maxBytes?: number;
+	/** This node's peer-id string; when set, {@link Libp2pReactivityNotifyTransport.send} never dials self. */
+	readonly selfPeerId?: string;
+}
+
+/**
+ * libp2p-backed {@link ReactivityNotifyTransport}: {@link send} frames + dials a single target over
+ * `/optimystic/reactivity/1.0.0/notify` (fire-and-forget, failure-isolated); inbound frames arrive through
+ * the host's notify protocol handler ({@link registerNotifyHandler}), which calls {@link deliver}.
+ * Subscribers registered via {@link onNotification} see every decoded notification.
+ */
+export class Libp2pReactivityNotifyTransport implements ReactivityNotifyTransport {
+	private readonly handlers = new Set<(from: PeerRef, n: NotificationV1) => void>();
+	private readonly notifyProtocol: string;
+	private readonly maxBytes: number;
+	private readonly selfPeerId?: string;
+
+	constructor(private readonly node: Libp2p, options: ReactivityNotifyTransportOptions = {}) {
+		this.notifyProtocol = options.notifyProtocol ?? PROTOCOL_REACTIVITY_NOTIFY;
+		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+		this.selfPeerId = options.selfPeerId;
+	}
+
+	send(target: string, n: NotificationV1): Promise<void> {
+		if (this.selfPeerId !== undefined && target === this.selfPeerId) {
+			// Never dial self; a co-located subscriber is delivered in-process by the forwarder host.
+			return Promise.resolve();
+		}
+		try {
+			const frame = encodeNotificationV1(n);
+			return sendOneWay(this.node, peerIdFromString(target), this.notifyProtocol, frame).catch((err: unknown) => {
+				// Best-effort, failure-isolated: a dead/unreachable target must not break the fan-out or a commit.
+				log("send to %s failed (swallowed): %o", target, err);
+			});
+		} catch (err) {
+			// Malformed notification or peer-id string: log + drop, never reject (reactivity is hint-only).
+			log("dropped a send to %s: %o", target, err);
+			return Promise.resolve();
+		}
+	}
+
+	onNotification(handler: (from: PeerRef, n: NotificationV1) => void): () => void {
+		this.handlers.add(handler);
+		return () => this.handlers.delete(handler);
+	}
+
+	/** Feed an inbound notify frame (called by the host's notify protocol handler). */
+	deliver(fromPeerId: string, frame: Uint8Array): void {
+		let n: NotificationV1;
+		try {
+			n = decodeNotificationV1(frame, this.maxBytes);
+		} catch (err) {
+			// A malformed frame must never throw out of a stream handler: log + drop.
+			log("dropped an undecodable inbound frame from %s: %o", fromPeerId, err);
+			return;
+		}
+		const from: PeerRef = { id: peerIdToBytes(fromPeerId) };
+		for (const handler of this.handlers) {
+			handler(from, n);
+		}
+	}
+}
+
+/**
+ * Register the inbound notify protocol handler: read one bounded frame and hand it to
+ * {@link ReactivityNotifyTransport.deliver}, then close. One-way — no reply frame (notify is strictly
+ * fire-and-forget; a reply would desync the dialer's {@link sendOneWay}). Mirrors the cohort-topic
+ * one-way handlers: a read error aborts the stream, and {@link ReactivityNotifyTransport.deliver}
+ * swallows a decode failure, so the handler never throws on the stream.
+ */
+export function registerNotifyHandler(
+	node: Libp2p,
+	protocol: string,
+	transport: ReactivityNotifyTransport,
+	maxBytes = DEFAULT_STREAM_MAX_BYTES,
+): void {
+	void node.handle(protocol, (stream: Stream, connection: Connection) => {
+		void (async (): Promise<void> => {
+			try {
+				const frame = await readAllBounded(stream, maxBytes);
+				transport.deliver(connection.remotePeer.toString(), frame);
+				await stream.close();
+			} catch {
+				try {
+					stream.abort(new Error("reactivity notify stream handler error"));
+				} catch {
+					/* already aborted */
+				}
+			}
+		})();
+	});
+}