@optimystic/db-p2p 0.13.5 → 0.14.0

package/dist/src/reactivity/forwarder-host.js

@@ -0,0 +1,355 @@
+/**
+ * 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, } from "@optimystic/db-core";
+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) {
+    return reactivityTopicId(b64urlToBytes(n.tailId));
+}
+/**
+ * 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, topicId) {
+    const out = [];
+    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;
+}
+/**
+ * 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 {
+    transport;
+    selfPeerId;
+    profile;
+    pushStateInit;
+    verifierFor;
+    directSubscribers;
+    resolveChildPrimary;
+    deliverLocal;
+    clock;
+    /** Per-topic served state. `ServedTopic` ⇒ forwards; `null` ⇒ resolved subscriber-only (Edge); absent ⇒ unresolved. */
+    served = new Map();
+    /** Per-topic serialization tail: an ingest chains onto its topic's prior ingest so the ring/dedupe never interleave. */
+    ingestTails = new Map();
+    /**
+     * 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`.
+     */
+    rotationGates = new Map();
+    constructor(deps) {
+        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 ?? (() => 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, n) {
+        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. */
+    async ingestSerialized(topicId, n, key) {
+        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, n) {
+        let topicId;
+        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) {
+        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() {
+        const out = [];
+        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) {
+        let best;
+        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, redirect, now) {
+        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, now) {
+        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.
+     */
+    fanOut(topicId, pushState, n) {
+        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). */
+    reconcileQueues(pushState, subscriberIds) {
+        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. */
+    deliverTo(topicId, subId, n) {
+        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. */
+    deliverInProcess(topicId, n) {
+        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. */
+    dispatch(target, n) {
+        let pending;
+        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) => {
+            log("notify send to %s rejected (isolated): %o", target, err);
+        });
+    }
+    /** Resolve (instantiating once, behind the Edge gate) the served state for a topic. */
+    resolveServed(topicId, n, key) {
+        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 = {
+            pushState,
+            forwarder: createReactivityForwarder({ state: pushState, verifier: this.verifierFor(topicId) }),
+        };
+        this.served.set(key, served);
+        return served;
+    }
+    topicKey(topicId) {
+        return bytesToB64url(topicId);
+    }
+}
+//# sourceMappingURL=forwarder-host.js.map

package/dist/src/reactivity/forwarder-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder-host.js","sourceRoot":"","sources":["../../../src/reactivity/forwarder-host.ts"],"names":[],"mappings":"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"}

package/dist/src/reactivity/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/reactivity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/reactivity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

package/dist/src/reactivity/index.js

@@ -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";
+//# sourceMappingURL=index.js.map

package/dist/src/reactivity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/reactivity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

package/dist/src/reactivity/notify-transport.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 type { Libp2p } from "libp2p";
+/** 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 declare class Libp2pReactivityNotifyTransport implements ReactivityNotifyTransport {
+    private readonly node;
+    private readonly handlers;
+    private readonly notifyProtocol;
+    private readonly maxBytes;
+    private readonly selfPeerId?;
+    constructor(node: Libp2p, options?: ReactivityNotifyTransportOptions);
+    send(target: string, n: NotificationV1): Promise<void>;
+    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;
+}
+/**
+ * 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 declare function registerNotifyHandler(node: Libp2p, protocol: string, transport: ReactivityNotifyTransport, maxBytes?: number): void;
+//# sourceMappingURL=notify-transport.d.ts.map

package/dist/src/reactivity/notify-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-transport.d.ts","sourceRoot":"","sources":["../../../src/reactivity/notify-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAWrC,wGAAwG;AACxG,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,wFAAwF;IACxF,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChF,mFAAmF;IACnF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACrD;AAED,wEAAwE;AACxE,MAAM,WAAW,gCAAgC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2GAA2G;IAC3G,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,YAAW,yBAAyB;IAMpE,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyD;IAClF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;gBAER,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gCAAqC;IAMzF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBtD,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAK/E,mFAAmF;IACnF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,yBAAyB,EACpC,QAAQ,SAA2B,GACjC,IAAI,CAgBN"}

package/dist/src/reactivity/notify-transport.js

@@ -0,0 +1,111 @@
+/**
+ * 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 { encodeNotificationV1, decodeNotificationV1 } from "@optimystic/db-core";
+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");
+/**
+ * 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 {
+    node;
+    handlers = new Set();
+    notifyProtocol;
+    maxBytes;
+    selfPeerId;
+    constructor(node, options = {}) {
+        this.node = node;
+        this.notifyProtocol = options.notifyProtocol ?? PROTOCOL_REACTIVITY_NOTIFY;
+        this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+        this.selfPeerId = options.selfPeerId;
+    }
+    send(target, n) {
+        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) => {
+                // 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) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    /** Feed an inbound notify frame (called by the host's notify protocol handler). */
+    deliver(fromPeerId, frame) {
+        let n;
+        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 = { 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, protocol, transport, maxBytes = DEFAULT_STREAM_MAX_BYTES) {
+    void node.handle(protocol, (stream, connection) => {
+        void (async () => {
+            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 */
+                }
+            }
+        })();
+    });
+}
+//# sourceMappingURL=notify-transport.js.map

package/dist/src/reactivity/notify-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-transport.js","sourceRoot":"","sources":["../../../src/reactivity/notify-transport.ts"],"names":[],"mappings":"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"}