@optimystic/db-p2p 1.0.0-beta.2 → 1.0.0

package/dist/src/network/relay-reservation.js

@@ -0,0 +1,527 @@
+/**
+ * Keeps a relay-only node's circuit reservation alive.
+ *
+ * A phone or browser reaches its group only through a relay server: it listens on
+ * `<relay address>/p2p/<relay id>/p2p-circuit`, holds a slot ("reservation") on that relay, and
+ * advertises the circuit address other peers dial. libp2p asks the relay for that slot once, from
+ * inside `start()`, and never again. The slot is lost, and the node stays unreachable until the
+ * app restarts, whenever the relay restarts, the connection to it drops, or libp2p's own routine
+ * renewal of the slot runs — all three verified against the installed `@libp2p/circuit-relay-v2`
+ * 4.1.3 (see the `NOTE:` at {@link findCircuitRelayTransport} for the exact mechanics).
+ *
+ * This module gives the node its own supervisor for every such relay, in two parts:
+ *
+ * 1. {@link planRelayListenAddrs} rewrites each relay-naming circuit listen address into a bare
+ *    `/p2p-circuit` entry and records the relay it named. libp2p treats the bare shape as a
+ *    "search" listener: it registers a pending slot and publishes any `discovered` reservation
+ *    that fills it, including the re-created one after a renewal. A listener on the relay-naming
+ *    ("configured") shape publishes only from inside its own `listen()`, so nothing done after
+ *    start can ever bring its address back — which is why the rewrite is not optional.
+ * 2. {@link superviseRelayReservation} runs one supervisor per recorded relay. It dials the relay,
+ *    asks the circuit-relay transport's reservation store for a `discovered` slot on it, waits
+ *    until the node advertises a circuit address through it, and repeats that whenever the address
+ *    goes away. "Held" is judged per relay ({@link routesThroughRelay}), so one relay's slot never
+ *    satisfies another relay's supervisor.
+ *
+ * `createLibp2pNodeBase` applies the plan before building libp2p's options, starts the supervisors
+ * first thing after `node.start()`, and awaits their first drives so a relay that cannot be
+ * reserved still rejects node creation, as it did when libp2p reserved from `listen()`.
+ *
+ * A host that passes a bare `/p2p-circuit` itself is left alone and not supervised: it owns that
+ * reservation (Sereus runs its own supervisor over exactly that shape).
+ *
+ * Everything here is fail-soft: a drive never throws, a stopped supervisor never schedules
+ * anything, and every timer is `unref`'d so a pending retry cannot keep a Node process alive.
+ * Adapted from `sereus/packages/cadre-core/src/relay-reservation.ts`, reduced to what this node
+ * needs: one relay per supervisor, event-driven re-checks, and no status surface.
+ */
+import { multiaddr } from '@multiformats/multiaddr';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { routesThroughRelay } from '../peer-address-book.js';
+import { createLogger } from '../logger.js';
+const log = createLogger('relay-reservation');
+/** The bare "search" circuit listen address: one pending slot, filled by whoever asks for it. */
+export const CIRCUIT_SEARCH_LISTEN_ADDR = '/p2p-circuit';
+/**
+ * Split a node's listen addresses into what libp2p should listen on and which relays this node
+ * must supervise.
+ *
+ * A relay-naming circuit listen address — exactly one `p2p-circuit` component, last, with a `p2p`
+ * component (the relay's peer id) immediately before it — becomes one bare
+ * {@link CIRCUIT_SEARCH_LISTEN_ADDR} entry plus one supervised relay. libp2p keeps listen addresses
+ * as a plain array with no de-duplication, so N such entries give N bare listeners and N pending
+ * slots. Two entries naming one relay (by peer id, whatever the spelling) give one of each; the
+ * first entry's dial address wins. Everything else passes through untouched: a host's own bare
+ * `/p2p-circuit` (the host owns that reservation), TCP and WebSocket entries, and anything
+ * malformed or multi-hop, which libp2p rejects itself.
+ */
+export function planRelayListenAddrs(listenAddrs) {
+    const listen = [];
+    const supervised = [];
+    const seen = new Set();
+    for (const addr of listenAddrs) {
+        const relay = relayNamedByListenAddr(addr);
+        if (relay === undefined) {
+            listen.push(addr);
+            continue;
+        }
+        if (seen.has(relay.peerId))
+            continue;
+        seen.add(relay.peerId);
+        supervised.push(relay);
+        listen.push(CIRCUIT_SEARCH_LISTEN_ADDR);
+    }
+    return { listenAddrs: listen, supervisedRelays: supervised };
+}
+/** The relay a listen address names, or `undefined` when it is not a relay-naming circuit listen address. */
+function relayNamedByListenAddr(addr) {
+    let components;
+    try {
+        components = multiaddr(addr).getComponents();
+    }
+    catch {
+        return undefined;
+    }
+    const circuitHops = components.filter(c => c.name === 'p2p-circuit').length;
+    const last = components[components.length - 1];
+    const relayHop = components[components.length - 2];
+    if (circuitHops !== 1 || last?.name !== 'p2p-circuit' || relayHop?.name !== 'p2p' || relayHop.value === undefined) {
+        return undefined;
+    }
+    let peerId;
+    try {
+        peerId = peerIdFromString(relayHop.value).toString();
+    }
+    catch {
+        return undefined;
+    }
+    return { dialAddr: multiaddr(components.slice(0, -1)).toString(), peerId };
+}
+/**
+ * The running node's circuit-relay transport, or `null` when it has none.
+ *
+ * NOTE: the ONE place this package reaches libp2p internals for relay reservations, pinned against
+ * `libp2p` 3.1.3 and `@libp2p/circuit-relay-v2` 4.1.3 by `test/relay-reservation-seam.spec.ts`,
+ * which must fail loudly if an upgrade moves any of it. There is no public route: the `Libp2p`
+ * interface has no `listen`, and nothing public exposes the reservation store. `node.components`
+ * is a real public field on libp2p's node class, just not on the interface; `transportManager`
+ * is a component; the circuit-relay transport is the one whose `reservationStore` has `addRelay`
+ * and `hasReservation`. What the store does on 4.1.3, read from
+ * `node_modules/@libp2p/circuit-relay-v2/src/transport/`: `listener.ts` publishes a `configured`
+ * reservation only from inside `listen()` and ignores it on `relay:created-reservation`, while a
+ * bare listener publishes any `discovered` reservation carrying its pending id; and
+ * `reservation-store.ts` drops a reservation on `connection:close`, re-queues the pending id only
+ * for `discovered` ones, removes-then-recreates on refresh, and adds a relay whose request failed
+ * with `DialError` or `UnsupportedProtocolError` to the private `relayFilter`, refusing it
+ * afterwards with "The relay was previously invalid" until the filter is reset.
+ */
+export function findCircuitRelayTransport(node) {
+    for (const transport of nodeTransports(node)) {
+        const store = transport.reservationStore;
+        if (isReservationStore(store)) {
+            return { reservationStore: store };
+        }
+    }
+    return null;
+}
+function nodeTransports(node) {
+    const manager = node.components?.transportManager;
+    if (typeof manager?.getTransports !== 'function') {
+        log.error('no transportManager.getTransports() on this node — libp2p internals moved?');
+        return [];
+    }
+    try {
+        return manager.getTransports();
+    }
+    catch (err) {
+        log.error('transportManager.getTransports() threw: %o', err);
+        return [];
+    }
+}
+function isReservationStore(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const store = value;
+    return typeof store.addRelay === 'function' && typeof store.hasReservation === 'function';
+}
+/**
+ * Fail node creation, before anything starts, when a listen address names a relay but no transport
+ * could ever reserve on it. libp2p would reject the bare `/p2p-circuit` entry itself during
+ * `start()`, with a generic unsupported-listen-address error; this names the actual omission.
+ */
+export function assertCircuitRelayTransport(node, relays) {
+    if (relays.length === 0)
+        return;
+    if (findCircuitRelayTransport(node) !== null)
+        return;
+    throw new Error(`listen address names a relay (${relays[0].dialAddr}) but the node has no circuit-relay transport — add circuitRelayTransport() to transports`);
+}
+/**
+ * Fail node creation, before anything is built, when a listen address names a relay but
+ * `announceAddrs` is set. libp2p advertises ONLY the announce set then (the readme's "replaces the
+ * advertised set entirely"), so the circuit address through the relay could never appear in
+ * `node.getMultiaddrs()`, nobody could learn it, and every supervisor drive would time out waiting
+ * for it: node creation would reject after a full drive deadline with a message about publishing
+ * rather than about the configuration. `appendAnnounceAddrs` keeps the listener addresses and is fine.
+ */
+export function assertRelayAddrsAdvertisable(relays, announceAddrs) {
+    if (relays.length === 0 || announceAddrs === undefined || announceAddrs.length === 0)
+        return;
+    throw new Error(`listen address names a relay (${relays[0].dialAddr}) but announceAddrs replaces the advertised address set, so the circuit address through it could never be advertised — drop announceAddrs or use appendAnnounceAddrs`);
+}
+/**
+ * Forget that a relay ever failed a reservation request, so the next request is actually made
+ * rather than refused with "The relay was previously invalid".
+ *
+ * The store resets its filter when a reservation is removed while a pending slot exists, which a
+ * bare listener always has, so this is a belt-and-braces step: the poisoning path this guards is a
+ * failed request from libp2p's own relay discovery while the relay was down. Fails soft in every
+ * direction; returns whether an entry was actually removed (for specs).
+ */
+export function clearRelayFilterEntry(store, relayPeerId) {
+    const filter = store.relayFilter;
+    if (typeof filter?.remove !== 'function')
+        return false;
+    try {
+        return filter.remove(relayPeerId.toMultihash().bytes);
+    }
+    catch (err) {
+        log('could not clear the relayFilter entry for %s: %o', relayPeerId.toString(), err);
+        return false;
+    }
+}
+/** Deadline for one drive: dial, reservation request and the wait for the address share it. */
+export const DEFAULT_RELAY_DRIVE_TIMEOUT_MS = 10_000;
+/** Gap between liveness checks while the reservation is held; a fallback in case an event is missed. */
+export const DEFAULT_RELAY_CHECK_MS = 5_000;
+/** Backoff before the first retry after a failed drive. */
+export const DEFAULT_RELAY_MIN_BACKOFF_MS = 1_000;
+/**
+ * Backoff ceiling. It bounds recovery time after a long relay outage, because nothing else
+ * reconnects a lone phone to its relay; a WebSocket dial every 30 s during an outage is cheap.
+ */
+export const DEFAULT_RELAY_MAX_BACKOFF_MS = 30_000;
+/** How often a drive re-reads the address list while waiting for the address to be published. */
+export const DEFAULT_RELAY_POLL_MS = 100;
+/**
+ * Keep asking `relay` for a reservation until one is held, then keep watching that it still is.
+ *
+ * Drives run on: the first tick, right away; libp2p's `self:peer:update` (the listener withdrew or
+ * added addresses); `peer:connect` for this relay (a dial by anything on this node reconnected it,
+ * which turns a partner's dial through the relay into an immediate re-reserve, and resets the
+ * backoff); a liveness poll every `checkMs` while held; and a doubling backoff from `minBackoffMs`
+ * to `maxBackoffMs` after a failed drive. Drives are serialized per relay: a trigger that arrives
+ * mid-drive does nothing by itself, because every drive ends with the same re-check and reschedule.
+ *
+ * `HadEnoughRelaysError` from the reservation store means this node's pending slot was already
+ * filled with a reservation on a different relay (libp2p's relay discovery, see the accepted
+ * tradeoff in `libp2p-node-base.ts`); it is logged once per episode and retried at the backoff cap, since it
+ * recovers on its own only if that other reservation drops.
+ */
+export function superviseRelayReservation(node, relay, opts = {}) {
+    return new RelayReservationLoop(node, relay, opts);
+}
+/** One {@link superviseRelayReservation} per relay, started immediately. */
+export function superviseRelayReservations(node, relays, opts = {}) {
+    const supervisors = relays.map(relay => superviseRelayReservation(node, relay, opts));
+    return {
+        supervisors,
+        async awaitFirstDrives() {
+            const outcomes = await Promise.all(supervisors.map(async (s) => ({ relay: s.relay, reason: await s.firstDrive })));
+            const failed = outcomes.filter(o => o.reason !== null);
+            if (failed.length === 0)
+                return;
+            throw new Error(failed.map(f => `could not reserve a circuit on relay ${f.relay.dialAddr}: ${f.reason}`).join('; '));
+        },
+        stop() {
+            for (const s of supervisors)
+                s.stop();
+        }
+    };
+}
+/** Sentinel resolved by the deadline race around `addRelay`, which takes no signal. */
+const DEADLINE_PASSED = Symbol('relay-reservation-deadline-passed');
+/** Milliseconds left until `deadline`, never negative. */
+const remaining = (deadline) => Math.max(0, deadline - Date.now());
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+/** A pending timer must not keep a stopped Node process alive; browsers and React Native have no `unref`. */
+function unref(timer) {
+    timer.unref?.();
+}
+/** Resolve after `ms`, on an unref'd timer. */
+function delay(ms) {
+    return new Promise(resolve => {
+        unref(setTimeout(resolve, ms));
+    });
+}
+/** The self-rescheduling loop behind {@link superviseRelayReservation}. */
+class RelayReservationLoop {
+    node;
+    relay;
+    firstDrive;
+    relayPeerId;
+    driveTimeoutMs;
+    checkMs;
+    minBackoffMs;
+    maxBackoffMs;
+    pollMs;
+    backoffMs;
+    timer = null;
+    stopped = false;
+    inFlight = false;
+    nextTickAtMs = null;
+    failure = null;
+    dialAbort = null;
+    slotTakenLogged = false;
+    settleFirstDrive = () => { };
+    firstDriveSettled = false;
+    constructor(node, relay, opts) {
+        this.node = node;
+        this.relay = relay;
+        this.relayPeerId = peerIdFromString(relay.peerId);
+        // Clamped away from 0: a caller-supplied 0 would spin the loop hot.
+        this.driveTimeoutMs = Math.max(1, opts.driveTimeoutMs ?? DEFAULT_RELAY_DRIVE_TIMEOUT_MS);
+        this.checkMs = Math.max(1, opts.checkMs ?? DEFAULT_RELAY_CHECK_MS);
+        this.minBackoffMs = Math.max(1, opts.minBackoffMs ?? DEFAULT_RELAY_MIN_BACKOFF_MS);
+        this.maxBackoffMs = Math.max(this.minBackoffMs, opts.maxBackoffMs ?? DEFAULT_RELAY_MAX_BACKOFF_MS);
+        this.pollMs = Math.max(1, opts.pollMs ?? DEFAULT_RELAY_POLL_MS);
+        this.backoffMs = this.minBackoffMs;
+        this.firstDrive = new Promise(resolve => {
+            this.settleFirstDrive = resolve;
+        });
+        node.addEventListener('self:peer:update', this.onSelfPeerUpdate);
+        node.addEventListener('peer:connect', this.onPeerConnect);
+        void this.tick('start');
+    }
+    get held() {
+        return this.node.getMultiaddrs().some(addr => routesThroughRelay(addr.toString(), this.relay.peerId, log));
+    }
+    get driving() {
+        return this.inFlight;
+    }
+    get retryAtMs() {
+        return this.nextTickAtMs;
+    }
+    get lastError() {
+        return this.failure;
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.clearTimer();
+        this.nextTickAtMs = null;
+        this.node.removeEventListener('self:peer:update', this.onSelfPeerUpdate);
+        this.node.removeEventListener('peer:connect', this.onPeerConnect);
+        this.dialAbort?.abort();
+        this.settleFirst('the relay reservation supervisor was stopped before its first drive settled');
+    }
+    onSelfPeerUpdate = () => {
+        this.wake('self:peer:update', false);
+    };
+    onPeerConnect = (evt) => {
+        if (!evt.detail.equals(this.relayPeerId))
+            return;
+        this.wake('peer:connect', true);
+    };
+    /**
+     * Something may have changed the reservation: re-check now. Mid-drive, only the backoff reset
+     * takes effect — the drive's own tail re-checks and reschedules, so nothing is lost.
+     */
+    wake(trigger, resetBackoff) {
+        if (this.stopped)
+            return;
+        if (resetBackoff)
+            this.backoffMs = this.minBackoffMs;
+        if (this.inFlight)
+            return;
+        this.clearTimer();
+        void this.tick(trigger);
+    }
+    async tick(trigger) {
+        if (this.stopped || this.inFlight)
+            return;
+        this.nextTickAtMs = null;
+        if (this.held) {
+            this.onHeld();
+            return;
+        }
+        await this.driveOnce(trigger);
+        if (this.stopped)
+            return;
+        // A drive that landed the reservation resumes the healthy cadence at once; backing off here
+        // would leave the first liveness check after a long outage a fully grown backoff away.
+        if (this.held) {
+            this.onHeld();
+            return;
+        }
+        this.scheduleBackoff();
+    }
+    /** Healthy tick: nothing to request, so only reset and re-check later. */
+    onHeld() {
+        this.backoffMs = this.minBackoffMs;
+        this.failure = null;
+        // Once held, a later slot-taken episode is a new event and deserves its own log line.
+        this.slotTakenLogged = false;
+        this.settleFirst(null);
+        this.schedule(this.checkMs);
+    }
+    async driveOnce(trigger) {
+        this.inFlight = true;
+        log('relay-reservation:drive relay=%s trigger=%s', this.relay.dialAddr, trigger);
+        try {
+            const reason = await this.drive();
+            if (this.stopped)
+                return;
+            this.failure = reason;
+            if (reason === null) {
+                log('relay-reservation:held relay=%s', this.relay.dialAddr);
+            }
+            else {
+                log.error('relay-reservation:failed relay=%s reason=%s', this.relay.dialAddr, reason);
+            }
+        }
+        catch (err) {
+            // `drive` is fail-soft by contract, so reaching here means that contract broke. The loop
+            // must survive it anyway: an escaping rejection would leave `firstDrive` pending forever
+            // and schedule no further attempt, which is the failure this supervisor exists to prevent.
+            const message = errorMessage(err);
+            log.error('relay-reservation:drive-threw relay=%s err=%s', this.relay.dialAddr, message);
+            if (!this.stopped)
+                this.failure = message;
+        }
+        finally {
+            this.inFlight = false;
+            if (!this.stopped)
+                this.settleFirst(this.failure);
+        }
+    }
+    /** One attempt under one deadline. Never throws; returns `null` when the address is held afterwards. */
+    async drive() {
+        const transport = findCircuitRelayTransport(this.node);
+        if (transport === null) {
+            return 'the node has no circuit-relay transport — add circuitRelayTransport() to transports';
+        }
+        const deadline = Date.now() + this.driveTimeoutMs;
+        clearRelayFilterEntry(transport.reservationStore, this.relayPeerId);
+        const dialFailure = await this.dialRelay(deadline);
+        if (dialFailure !== null)
+            return dialFailure;
+        if (this.stopped)
+            return 'stopped';
+        const requestFailure = await this.requestReservation(transport.reservationStore, deadline);
+        if (requestFailure !== null)
+            return requestFailure;
+        if (await this.waitUntilHeld(deadline))
+            return null;
+        return `relay ${this.relay.dialAddr} granted a reservation but no circuit address through it was published within ${this.driveTimeoutMs}ms`;
+    }
+    /**
+     * Dial the relay, or return why that failed. An explicit controller rather than
+     * `AbortSignal.timeout`, which is unreliable on Hermes; {@link stop} aborts it too.
+     */
+    async dialRelay(deadline) {
+        const controller = new AbortController();
+        this.dialAbort = controller;
+        const timer = setTimeout(() => controller.abort(), remaining(deadline));
+        unref(timer);
+        try {
+            await this.node.dial(multiaddr(this.relay.dialAddr), { signal: controller.signal });
+            return null;
+        }
+        catch (err) {
+            return `dial to relay ${this.relay.dialAddr} failed: ${errorMessage(err)}`;
+        }
+        finally {
+            clearTimeout(timer);
+            this.dialAbort = null;
+        }
+    }
+    /**
+     * Ask the store for a `discovered` reservation on the relay, raced against the deadline because
+     * `addRelay` takes no signal. `'discovered'`, never `'configured'`: only a `discovered`
+     * reservation is published by the bare listener the plan gave libp2p. A concurrent `addRelay`
+     * for the same relay from libp2p's own discovery joins the same queue job, so there is no
+     * double reservation. The abandoned promise stays handled — `Promise.race` attaches handlers.
+     */
+    async requestReservation(store, deadline) {
+        let timer;
+        const expired = new Promise(resolve => {
+            timer = setTimeout(() => resolve(DEADLINE_PASSED), remaining(deadline));
+            unref(timer);
+        });
+        try {
+            const outcome = await Promise.race([store.addRelay(this.relayPeerId, 'discovered'), expired]);
+            if (outcome === DEADLINE_PASSED) {
+                return `reservation request to relay ${this.relay.dialAddr} did not complete within ${this.driveTimeoutMs}ms`;
+            }
+            return null;
+        }
+        catch (err) {
+            return this.describeReservationFailure(err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Turn the store's rejection into a reason that names the cause, and apply its consequence. */
+    describeReservationFailure(err) {
+        const name = err instanceof Error ? err.name : '';
+        switch (name) {
+            case 'HadEnoughRelaysError': {
+                // The pending slot the bare listener registered is already filled, by a reservation on
+                // some other relay. Nothing this supervisor does frees it, so retry only at the cap.
+                this.backoffMs = this.maxBackoffMs;
+                const reason = `this node's pending circuit slot is already filled by a reservation on another relay, so relay ${this.relay.dialAddr} was not asked; retrying every ${this.maxBackoffMs}ms until that reservation drops`;
+                if (!this.slotTakenLogged) {
+                    this.slotTakenLogged = true;
+                    log.error('relay-reservation:slot-taken relay=%s', this.relay.dialAddr);
+                }
+                return reason;
+            }
+            case 'UnsupportedProtocolError':
+                return `the peer at ${this.relay.dialAddr} does not serve the circuit-relay hop protocol, so it is not a relay`;
+            default:
+                return `reservation request to relay ${this.relay.dialAddr} failed: ${errorMessage(err)}`;
+        }
+    }
+    /** `addRelay` resolving means the relay accepted; the listener publishes the address a tick later. */
+    async waitUntilHeld(deadline) {
+        for (;;) {
+            if (this.held)
+                return true;
+            if (this.stopped || Date.now() >= deadline)
+                return false;
+            await delay(Math.min(this.pollMs, remaining(deadline)));
+        }
+    }
+    scheduleBackoff() {
+        const wait = this.backoffMs;
+        this.backoffMs = Math.min(this.backoffMs * 2, this.maxBackoffMs);
+        this.schedule(wait);
+    }
+    schedule(ms) {
+        if (this.stopped)
+            return;
+        this.clearTimer();
+        this.nextTickAtMs = Date.now() + ms;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick('timer');
+        }, ms);
+        unref(this.timer);
+    }
+    clearTimer() {
+        if (this.timer === null)
+            return;
+        clearTimeout(this.timer);
+        this.timer = null;
+    }
+    settleFirst(reason) {
+        if (this.firstDriveSettled)
+            return;
+        this.firstDriveSettled = true;
+        this.settleFirstDrive(reason);
+    }
+}
+//# sourceMappingURL=relay-reservation.js.map

package/dist/src/network/relay-reservation.js.map

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

package/dist/src/pend-validation.d.ts

@@ -37,8 +37,9 @@ export type PendValidationEvent = {
  *
  * Two decisions live here:
  *
- * - **No `validation` pair** (the single-collection `Collection.sync` shape — bare transforms, so
- *   there is nothing to re-execute): an explicit, LOGGED policy branch on both arms, never a silent
+ * - **No `validation` pair** (bare transforms, so there is nothing to re-execute: the
+ *   single-collection `Collection.sync` shape, and the Quereus adapter's legacy multi-tree commit,
+ *   whose coordinator is built with `pendValidation: 'none'`): an explicit, LOGGED policy branch on both arms, never a silent
  *   fall-through. `'accept'` admits it unchecked, preserving the historical behaviour; `'reject'`
  *   refuses with {@link PEND_NOT_VALIDATABLE}. The presence test is on the whole pair, so a sender
  *   cannot talk a receiver out of validating by omitting half of it.

package/dist/src/pend-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pend-validation.d.ts","sourceRoot":"","sources":["../../src/pend-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEhH,+FAA+F;AAC/F,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAmB/B"}
+{"version":3,"file":"pend-validation.d.ts","sourceRoot":"","sources":["../../src/pend-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEhH,+FAA+F;AAC/F,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAmB/B"}

package/dist/src/pend-validation.js

@@ -21,8 +21,9 @@ export const VALIDATOR_FAULT = 'validator-fault';
  *
  * Two decisions live here:
  *
- * - **No `validation` pair** (the single-collection `Collection.sync` shape — bare transforms, so
- *   there is nothing to re-execute): an explicit, LOGGED policy branch on both arms, never a silent
+ * - **No `validation` pair** (bare transforms, so there is nothing to re-execute: the
+ *   single-collection `Collection.sync` shape, and the Quereus adapter's legacy multi-tree commit,
+ *   whose coordinator is built with `pendValidation: 'none'`): an explicit, LOGGED policy branch on both arms, never a silent
  *   fall-through. `'accept'` admits it unchecked, preserving the historical behaviour; `'reject'`
  *   refuses with {@link PEND_NOT_VALIDATABLE}. The presence test is on the whole pair, so a sender
  *   cannot talk a receiver out of validating by omitting half of it.

package/dist/src/pend-validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"pend-validation.js","sourceRoot":"","sources":["../../src/pend-validation.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAoB,EACpB,KAA8B,EAC9B,MAA+B,EAC/B,OAA6C;IAE7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACzB,OAAO,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3C,OAAO,MAAM,KAAK,QAAQ;YACzB,iFAAiF;YACjF,yFAAyF;YACzF,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,oBAAoB,6CAA6C,EAAE;YAChG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpB,CAAC;IACD,IAAI,CAAC;QACJ,OAAO,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,KAAK,GAAI,GAAa,CAAC,OAAO,CAAC;QACrC,OAAO,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,KAAK,KAAK,EAAE,EAAE,CAAC;IACjE,CAAC;AACF,CAAC"}
+{"version":3,"file":"pend-validation.js","sourceRoot":"","sources":["../../src/pend-validation.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAoB,EACpB,KAA8B,EAC9B,MAA+B,EAC/B,OAA6C;IAE7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACzB,OAAO,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3C,OAAO,MAAM,KAAK,QAAQ;YACzB,iFAAiF;YACjF,yFAAyF;YACzF,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,oBAAoB,6CAA6C,EAAE;YAChG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpB,CAAC;IACD,IAAI,CAAC;QACJ,OAAO,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,KAAK,GAAI,GAAa,CAAC,OAAO,CAAC;QACrC,OAAO,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,KAAK,KAAK,EAAE,EAAE,CAAC;IACjE,CAAC;AACF,CAAC"}

package/dist/src/protocol-client.d.ts

@@ -1,4 +1,4 @@
-import type { PeerId, IPeerNetwork } from '@optimystic/db-core';
+import type { PeerId, IPeerNetwork, BlockId } from '@optimystic/db-core';
 /**
  * Thrown when the per-peer dial deadline expires before a stream is established.
  * Distinct from a libp2p dial failure (no route, refused, etc.) so the
@@ -27,6 +27,13 @@ export declare class ProtocolClient {
     protected readonly peerId: PeerId;
     protected readonly peerNetwork: IPeerNetwork;
     constructor(peerId: PeerId, peerNetwork: IPeerNetwork);
+    /**
+     * Remember that `coordinator` coordinates `blockId`, so a follow-up op on that block dials it directly
+     * instead of being redirected again. Only a key network keeps coordinator hints — a plain
+     * {@link IPeerNetwork} omits `recordCoordinator`, and this is then a no-op. The hint is keyed on the
+     * block's routing key, the key a later `findCoordinator` looks it up by.
+     */
+    protected recordCoordinatorHint(blockId: BlockId, coordinator: PeerId): void;
     protected processMessage<T>(message: unknown, protocol: string, options?: {
         signal?: AbortSignal;
         correlationId?: string;

package/dist/src/protocol-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-client.d.ts","sourceRoot":"","sources":["../../src/protocol-client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAOhE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,kBAA2B;gBAC5B,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAItD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAE9D,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,sBAA+B;gBAChC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAItD;AAED,oEAAoE;AACpE,qBAAa,cAAc;IAEzB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,YAAY;gBADzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,YAAY;cAG7B,cAAc,CAAC,CAAC,EAC/B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACpI,OAAO,CAAC,CAAC,CAAC;CA6Ib"}
+{"version":3,"file":"protocol-client.d.ts","sourceRoot":"","sources":["../../src/protocol-client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAe,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAQtF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,kBAA2B;gBAC5B,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAItD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAE9D,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,sBAA+B;gBAChC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAItD;AAED,oEAAoE;AACpE,qBAAa,cAAc;IAEzB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,YAAY;gBADzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,YAAY;IAG7C;;;;;OAKG;IACH,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;cAK5D,cAAc,CAAC,CAAC,EAC/B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACpI,OAAO,CAAC,CAAC,CAAC;CA6Ib"}

package/dist/src/protocol-client.js

@@ -1,5 +1,6 @@
 import { pipe } from 'it-pipe';
 import { encode as lpEncode, decode as lpDecode } from 'it-length-prefixed';
+import { routingKeyForBlock } from '@optimystic/db-core';
 import { first } from './it-utility.js';
 import { createLogger } from './logger.js';
 import { MAX_BLOCK_MESSAGE_BYTES } from './protocol-limits.js';
@@ -41,6 +42,16 @@ export class ProtocolClient {
         this.peerId = peerId;
         this.peerNetwork = peerNetwork;
     }
+    /**
+     * Remember that `coordinator` coordinates `blockId`, so a follow-up op on that block dials it directly
+     * instead of being redirected again. Only a key network keeps coordinator hints — a plain
+     * {@link IPeerNetwork} omits `recordCoordinator`, and this is then a no-op. The hint is keyed on the
+     * block's routing key, the key a later `findCoordinator` looks it up by.
+     */
+    recordCoordinatorHint(blockId, coordinator) {
+        const hints = this.peerNetwork;
+        hints.recordCoordinator?.(routingKeyForBlock(blockId), coordinator);
+    }
     async processMessage(message, protocol, options) {
         const peer = this.peerId.toString();
         const cid = options?.correlationId;