@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/{strand-backfill.js → peer-join-backfill.js}

@@ -1,36 +1,59 @@
 import debug from 'debug';
 import { BlockTransferClient } from '@optimystic/db-p2p';
-// NOTE: this copies the WHOLE local store to every newly connected strand peer, which is
-// right while a strand mesh is one party's handful of machines (see docs/architecture.md →
-// Replication cluster size, "On a strand, the machine count is not a party count"). If
-// strand meshes ever get large, filter the pushed set by FRET cohort responsibility for
-// each block id instead of pushing everything.
+// Peer-join whole-store block catch-up, shared by the STRAND networks and the CONTROL
+// network. On `connection:open` (debounced) it pushes every committed, materialized block
+// in the local raw store to the new peer, so a machine that joined after blocks were
+// committed still ends up physically holding them. Optimystic has no cohort-join catch-up
+// of its own; a block committed while its writer was alone has exactly one holder forever
+// without this (named collection-header blocks are written once, at collection creation,
+// and their revision never moves again — so no later commit ever carries them anywhere).
+//
+// NOTE: this copies the WHOLE local store to every newly connected peer, which is right
+// while a network is one party's handful of machines (see docs/architecture.md →
+// Replication cluster size — the control network replicates to the whole party by intent,
+// and "On a strand, the machine count is not a party count"). If these meshes ever get
+// large, filter the pushed set by FRET cohort responsibility for each block id instead of
+// pushing everything.
 //
 // NOTE: this lives in cadre-core only because `../optimystic` is read-only from this repo.
 // If Optimystic ever grows a cohort-join catch-up of its own, delete this module rather
 // than running two.
 //
-// Membership: anything connected on the strand's own libp2p network already receives
-// cohort replicas of new commits, so pushing older blocks to it exposes nothing new. No
-// membership gate here — adding one would diverge from what ordinary replication already
-// does on this network. A peer that does NOT speak this strand's block-transfer protocol
-// (a bare circuit relay or bootstrap node the strand node also connects to) cannot receive
-// anything: the protocol id is namespaced per strand, so the dial fails and the push is
-// dropped.
+// Membership — the one place the two networks differ, expressed as the optional
+// `authorizePeer` dep:
+//
+// - STRAND networks pass none. Anything connected on a strand's own libp2p network already
+//   receives cohort replicas of new commits, so pushing older blocks to it exposes nothing
+//   new; adding a gate would diverge from what ordinary replication already does there. A
+//   peer that does NOT speak the strand's block-transfer protocol (a bare circuit relay or
+//   bootstrap node the strand node also connects to) cannot receive anything: the protocol
+//   id is namespaced per strand, so the dial fails and the push is dropped.
+// - The CONTROL network MUST pass one, because that argument does not carry over: its
+//   inbound connection gate deliberately admits non-members in several states (an
+//   un-enrolled node taking its seed, an open enrollment window, an outstanding
+//   invitation, configured bootstrap/relay peers — see docs/architecture.md, the
+//   control-network inbound connection gate). Pushing the whole control store to such a
+//   peer would hand a stranger the party's entire membership, addresses and strand list.
+//   `CadreNode` passes `isAuthorizedMember`; the gate is consulted at PUSH time, not at
+//   schedule time, and fails closed on a thrown check. A denied run is not memoized, so
+//   the peer is retried on its next `connection:open` — or sooner, via
+//   `scheduleConnectedPeers()` on a membership change (the production join order is
+//   connect-then-authorize, so the denial at dial time is the expected first pass).
 //
-// NOTE: that failing case costs one dial timeout per connection:open from such a peer, and
-// is never memoized (only clean runs are). Bounded today by the debounce plus the
-// unreachable-peer bail in `runCatchUp` — one dial per event, not one per chunk. If a strand
-// node ever holds many non-strand connections, or the enumeration ahead of the first chunk
-// gets expensive, pre-check `libp2p.peerStore` for this strand's block-transfer protocol
-// before enumerating.
+// NOTE: a failing dial to a non-speaking peer costs one dial timeout per connection:open
+// from such a peer, and is never memoized (only clean runs are). Bounded today by the
+// debounce plus the unreachable-peer bail in `runCatchUp` — one dial per event, not one
+// per chunk. If a node ever holds many such connections, or the enumeration ahead of the
+// first chunk gets expensive, pre-check `libp2p.peerStore` for this network's
+// block-transfer protocol before enumerating.
 //
-// NOTE: a run that fails is retried only when that peer next opens a connection. Over a
-// stable connection a transient push failure therefore leaves the peer partially copied
-// until the next reconnect (read repair still covers reads meanwhile). If strand meshes
-// ever hold long-lived connections where that matters, re-arm the debounce timer with a
-// backoff on a non-clean run instead of waiting for connection:open.
-const log = debug('sereus:cadre:strand-backfill');
+// NOTE: a run that fails is retried only when that peer next opens a connection (or, with
+// an `authorizePeer` gate wired, when `scheduleConnectedPeers()` is driven). Over a stable
+// connection a transient push failure therefore leaves the peer partially copied until the
+// next reconnect (read repair still covers reads meanwhile). If these meshes ever hold
+// long-lived connections where that matters, re-arm the debounce timer with a backoff on a
+// non-clean run instead of waiting for connection:open.
+const log = debug('sereus:cadre:peer-join-backfill');
 /**
  * The block-transfer protocol's hard cap on one length-prefixed message. Mirrors
  * `MAX_BLOCK_MESSAGE_BYTES` in `@optimystic/db-p2p`'s `protocol-limits.ts` (8 MiB), which
@@ -38,8 +61,8 @@ const log = debug('sereus:cadre:strand-backfill');
  * changes it or starts exporting it.
  */
 export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
-/** The resolved defaults every {@link StrandBackfill} starts from. */
-export const DEFAULT_STRAND_BACKFILL = {
+/** The resolved defaults every {@link PeerJoinBackfill} starts from. */
+export const DEFAULT_PEER_JOIN_BACKFILL = {
     enabled: true,
     debounceMs: 1000,
     maxBlocks: 10000,
@@ -49,7 +72,7 @@ export const DEFAULT_STRAND_BACKFILL = {
     responseTimeoutMs: 10000
 };
 function emptyResult() {
-    return { offered: 0, accepted: 0, rejected: [], uncommitted: 0, unmaterialized: 0, capped: 0, oversized: [] };
+    return { offered: 0, accepted: 0, rejected: [], uncommitted: 0, unmaterialized: 0, capped: 0, oversized: [], denied: false };
 }
 /**
  * Base64 wire size of a raw buffer — `pushBlocks` base64-encodes each block into the JSON
@@ -59,17 +82,17 @@ function base64WireBytes(rawBytes) {
     return Math.ceil(rawBytes / 3) * 4;
 }
 /**
- * Copies every block in one strand's own raw store to each peer its libp2p node connects
- * to, so a peer that joined the strand after blocks were committed still ends up holding
+ * Copies every block in one network's own raw store to each peer its libp2p node connects
+ * to, so a peer that joined the network after blocks were committed still ends up holding
  * them physically (the receiver persists each push via `saveReplicatedBlock`, which is
  * monotonic and idempotent — crossing pushes from both ends cannot regress a revision).
  *
- * Best-effort throughout: nothing here throws into a libp2p event handler or into
- * `buildStrandRuntime`; a failed chunk is logged and the run continues. A peer is marked
+ * Best-effort throughout: nothing here throws into a libp2p event handler or into a
+ * runtime bring-up; a failed chunk is logged and the run continues. A peer is marked
  * fully caught up ONLY after a run with no thrown chunk and an empty `missing` list, so
  * the next `connection:open` from a peer whose catch-up failed retries it.
  */
-export class StrandBackfill {
+export class PeerJoinBackfill {
     constructor(deps, config) {
         this.deps = deps;
         this.started = false;
@@ -78,10 +101,19 @@ export class StrandBackfill {
         this.done = new Set();
         /** Peers with a catch-up currently running (suppresses concurrent duplicates). */
         this.inFlight = new Set();
+        /**
+         * Peers whose (re-)schedule arrived while their OWN run was in flight, replayed once
+         * that run finishes. Load-bearing for the gated path: the gate's authorization check is
+         * a control-database read, so the window between it and the run's end is wide enough for
+         * the very membership commit that would have authorized the peer to land inside it —
+         * dropping that schedule (rather than deferring it) leaves the denied peer waiting for a
+         * reconnect, which is exactly what the re-arm exists to avoid.
+         */
+        this.rearmAfterFlight = new Set();
         /** Pending per-peer debounce timers, cleared on stop. */
         this.timers = new Map();
         this.loggedNoListBlockIds = false;
-        this.config = { ...DEFAULT_STRAND_BACKFILL, ...config };
+        this.config = { ...DEFAULT_PEER_JOIN_BACKFILL, ...config };
         this.createPushClient = deps.createPushClient
             ?? ((peerId) => new BlockTransferClient(peerId, deps.peerNetwork, deps.protocolPrefix));
         this.onConnectionOpen = (evt) => this.schedulePeer(evt.detail.remotePeer);
@@ -94,11 +126,8 @@ export class StrandBackfill {
         this.deps.libp2p.addEventListener('connection:open', this.onConnectionOpen);
         // A runtime rebuilt over live connections (resumeStrand) never sees their
         // connection:open, so walk what is already connected once.
-        const existing = this.deps.libp2p.getConnections();
-        for (const connection of existing) {
-            this.schedulePeer(connection.remotePeer);
-        }
-        log('[%s] started (%d peer(s) already connected)', this.deps.strandId, existing.length);
+        const scheduled = this.scheduleConnectedPeers();
+        log('[%s] started (%d peer(s) already connected)', this.deps.label, scheduled);
     }
     /** Unsubscribe, clear timers; in-flight runs observe the stopped flag and bail. */
     stop() {
@@ -112,13 +141,43 @@ export class StrandBackfill {
             clearTimeout(timer);
         }
         this.timers.clear();
-        log('[%s] stopped', this.deps.strandId);
+        this.rearmAfterFlight.clear();
+        log('[%s] stopped', this.deps.label);
+    }
+    /**
+     * (Re-)schedule a debounced catch-up for every currently-connected peer not yet caught
+     * up. Idempotent and cheap (caught-up peers are skipped before any timer is set, and a
+     * peer whose run is in flight is deferred to the end of that run rather than dropped).
+     * Driven by {@link start}, and — on a gated network — by the embedder whenever
+     * membership changes, so a peer whose first pass was denied (connected before it was
+     * authorized: the production join order) is retried without waiting for a reconnect.
+     * Returns how many distinct peers were considered (for the start() log) — a peer holding
+     * several connections is one peer, and is scheduled once.
+     */
+    scheduleConnectedPeers() {
+        if (this.stopped)
+            return 0;
+        const peers = new Set();
+        for (const connection of this.deps.libp2p.getConnections()) {
+            const key = connection.remotePeer.toString();
+            if (peers.has(key))
+                continue;
+            peers.add(key);
+            this.schedulePeer(connection.remotePeer);
+        }
+        return peers.size;
     }
     /** Debounced entry point for connection churn: one run per peer per settle window. */
     schedulePeer(peerId) {
         const key = peerId.toString();
-        if (this.stopped || this.done.has(key) || this.inFlight.has(key))
+        if (this.stopped || this.done.has(key))
+            return;
+        if (this.inFlight.has(key)) {
+            // Defer rather than drop: the running pass may already be past its gate check (or
+            // past the block this schedule was meant to carry), so replay it when that pass ends.
+            this.rearmAfterFlight.add(key);
             return;
+        }
         const existing = this.timers.get(key);
         if (existing)
             clearTimeout(existing);
@@ -143,32 +202,54 @@ export class StrandBackfill {
             // NOTE: a run that hit `maxBlocks` is still "clean" and still memoizes the peer, so
             // the tail past the ceiling never reaches it. Deliberate: enumeration is not
             // resumable, so not memoizing would re-push the same prefix on every reconnect
-            // without ever advancing. Loud in the log below (capped > 0). If a strand's store can
+            // without ever advancing. Loud in the log below (capped > 0). If a store can
             // realistically exceed maxBlocks, the fix is a resumable cursor, not either policy.
             if (clean && !this.stopped) {
                 this.done.add(key);
             }
-            log('[%s] catch-up peer=%s offered=%d accepted=%d rejected=%d uncommitted=%d unmaterialized=%d capped=%d oversized=%d done=%s', this.deps.strandId, key, result.offered, result.accepted, result.rejected.length, result.uncommitted, result.unmaterialized, result.capped, result.oversized.length, clean);
+            log('[%s] catch-up peer=%s offered=%d accepted=%d rejected=%d uncommitted=%d unmaterialized=%d capped=%d oversized=%d denied=%s done=%s', this.deps.label, key, result.offered, result.accepted, result.rejected.length, result.uncommitted, result.unmaterialized, result.capped, result.oversized.length, result.denied, clean);
             return result;
         }
         catch (error) {
             // runCatchUp already contains a per-chunk catch; this guards the enumeration and
             // metadata reads too — a backfill fault must never surface through a libp2p event.
-            log('[%s] catch-up peer=%s failed: %o', this.deps.strandId, key, error);
+            log('[%s] catch-up peer=%s failed: %o', this.deps.label, key, error);
             return emptyResult();
         }
         finally {
             this.inFlight.delete(key);
+            // Replay a schedule that arrived mid-run. `schedulePeer` re-checks `done`, so a run
+            // that finished clean re-arms nothing; a denied or failed one gets its retry.
+            if (this.rearmAfterFlight.delete(key)) {
+                this.schedulePeer(peerId);
+            }
         }
     }
     /** The actual copy. `clean` = every chunk pushed and the remote persisted every block. */
     async runCatchUp(peerId) {
         const result = emptyResult();
         const { storage } = this.deps;
+        // The membership gate, judged at push time (never at schedule time — authorization can
+        // change during the debounce window in either direction). Fails CLOSED on a throw: a
+        // gate that cannot answer must not leak the store. A denied run is not clean, so the
+        // peer is retried later rather than memoized as caught up.
+        if (this.deps.authorizePeer) {
+            let authorized = false;
+            try {
+                authorized = await this.deps.authorizePeer(peerId.toString());
+            }
+            catch (error) {
+                log('[%s] authorizePeer(%s) threw — treating as denied: %o', this.deps.label, peerId.toString(), error);
+            }
+            if (!authorized) {
+                result.denied = true;
+                return { result, clean: false };
+            }
+        }
         if (!storage.listBlockIds) {
             if (!this.loggedNoListBlockIds) {
                 this.loggedNoListBlockIds = true;
-                log('[%s] raw storage does not implement listBlockIds(); backfill is inert', this.deps.strandId);
+                log('[%s] raw storage does not implement listBlockIds(); backfill is inert', this.deps.label);
             }
             return { result, clean: false };
         }
@@ -207,12 +288,12 @@ export class StrandBackfill {
                     }
                 }
                 if (response.missing.length > 0) {
-                    log('[%s] peer=%s rejected %d block(s): %o', this.deps.strandId, peerId.toString(), response.missing.length, response.missing);
+                    log('[%s] peer=%s rejected %d block(s): %o', this.deps.label, peerId.toString(), response.missing.length, response.missing);
                 }
             }
             catch (error) {
                 chunkFailed = true;
-                log('[%s] push to peer=%s failed for %d block(s): %s', this.deps.strandId, peerId.toString(), ids.length, error.message);
+                log('[%s] push to peer=%s failed for %d block(s): %s', this.deps.label, peerId.toString(), ids.length, error.message);
             }
         };
         for await (const blockId of storage.listBlockIds()) {
@@ -239,7 +320,7 @@ export class StrandBackfill {
             const block = await storage.getMaterializedBlock(blockId, latest.actionId);
             if (!block) {
                 result.unmaterialized += 1;
-                log('[%s] block=%s has latest rev %d but no materialized content; skipped', this.deps.strandId, blockId, latest.rev);
+                log('[%s] block=%s has latest rev %d but no materialized content; skipped', this.deps.label, blockId, latest.rev);
                 continue;
             }
             const buffer = encoder.encode(JSON.stringify(block));
@@ -247,11 +328,11 @@ export class StrandBackfill {
             // this test ignores the request envelope (ids array, blockMeta, JSON punctuation).
             // A lone block within a few KiB of the cap therefore still ships and is rejected by
             // the receiver's length-prefix decoder — a permanent chunk failure for that peer. No
-            // block in a strand comes close today; if one ever can, subtract a measured envelope
-            // allowance here rather than raising the cap.
+            // block comes close today; if one ever can, subtract a measured envelope allowance
+            // here rather than raising the cap.
             if (base64WireBytes(buffer.length) >= MAX_BLOCK_MESSAGE_BYTES) {
                 result.oversized.push(blockId);
-                log('[%s] block=%s is %d bytes (%d on the wire) — exceeds the %d-byte protocol cap alone; skipped', this.deps.strandId, blockId, buffer.length, base64WireBytes(buffer.length), MAX_BLOCK_MESSAGE_BYTES);
+                log('[%s] block=%s is %d bytes (%d on the wire) — exceeds the %d-byte protocol cap alone; skipped', this.deps.label, blockId, buffer.length, base64WireBytes(buffer.length), MAX_BLOCK_MESSAGE_BYTES);
                 continue;
             }
             // Flush before adding when this block would overflow either budget. A single block
@@ -279,10 +360,10 @@ export class StrandBackfill {
             await flush();
         }
         if (result.capped > 0) {
-            log('[%s] peer=%s catch-up CAPPED at %d blocks; %d block id(s) not attempted', this.deps.strandId, peerId.toString(), this.config.maxBlocks, result.capped);
+            log('[%s] peer=%s catch-up CAPPED at %d blocks; %d block id(s) not attempted', this.deps.label, peerId.toString(), this.config.maxBlocks, result.capped);
         }
         const clean = !chunkFailed && result.rejected.length === 0;
         return { result, clean };
     }
 }
-//# sourceMappingURL=strand-backfill.js.map
+//# sourceMappingURL=peer-join-backfill.js.map

package/dist/peer-join-backfill.js.map

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

package/dist/relay-addrs.d.ts

@@ -3,34 +3,47 @@
  * setting — into the listen entry a node needs before it can hold a circuit-relay
  * slot, and validate the operator's entries while doing it.
  *
- * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr,
- * and the same `relayAddrs` list resolves to either shape depending on WHO is
- * listening ({@link RelayListenRoute}):
- *
- * | route          | listen entry                                | libp2p behaviour                                          |
- * | -------------- | ------------------------------------------- | --------------------------------------------------------- |
- * | `'configured'` | `<relayAddr>/p2p-circuit`, one per relay      | dial that relay from inside `listen()` and reserve, or throw |
- * | `'search'`     | a single bare `/p2p-circuit`                  | register a pending reservation; open no connection          |
- *
- * The CONTROL node takes the `'search'` route, and `CadreNode.start()` drives the
- * reservation explicitly (`relay-reservation.ts`) once the control database is up.
- * That ordering is the point: a configured circuit listener dials the relay from
- * inside `libp2p.start()`, so the control database was being built while a sibling
- * relay was already in this node's cohort — and a sibling that has not yet
- * replicated this node's `CadrePeer` row correctly refuses its control-DB streams,
- * which killed `start()` outright. See `cadre-node.ts` → `start()`.
- *
- * STRAND nodes keep the `'configured'` route (`strand-instance-manager.ts`): they
- * inherit the control node's `NetworkConfig`, nothing drives an explicit
- * reservation for them, and their relay connection cannot disturb a control-DB
- * bring-up (a strand node's protocol ids are namespaced `/optimystic/strand-<id>/…`,
- * so the relay is never in its cohort).
- *
- * `network.relayAddrs` is FAIL-FAST for the operator on both routes, just from
- * different places: a malformed entry throws here at config resolution, and on the
- * control node a first reservation attempt that does not land throws out of
- * `start()` (`RelayReservationFailedError`). Naming a relay that is down still
- * means the node does not come up.
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr:
+ *
+ * | listen entry                        | libp2p behaviour                                                |
+ * | ----------------------------------- | --------------------------------------------------------------- |
+ * | `<relayAddr>/p2p-circuit`           | CONFIGURED: dial that relay from inside `listen()` and reserve, or throw |
+ * | bare `/p2p-circuit`                 | SEARCH: register a pending reservation; open no connection      |
+ *
+ * Every cadre-built node takes the SEARCH shape, and something explicit drives the
+ * reservation afterwards (`relay-reservation.ts`):
+ *
+ * - The CONTROL node resolves `relayAddrs` here to ONE bare entry (whichever relay
+ *   answers first fills it) and `CadreNode.start()` drives the reservation once the
+ *   control database is up. That ordering is the point: a configured circuit
+ *   listener dials the relay from inside `libp2p.start()`, so the control database
+ *   was being built while a sibling relay was already in this node's cohort — and a
+ *   sibling that has not yet replicated this node's `CadrePeer` row correctly refuses
+ *   its control-DB streams, which killed `start()` outright. See `cadre-node.ts` →
+ *   `start()`.
+ * - Each STRAND node resolves the same `relayAddrs` to one bare entry PER relay and
+ *   runs one reservation supervisor per relay (`strand-network-config.ts`,
+ *   `strand-instance-manager.ts`).
+ *
+ * The CONFIGURED shape is deliberately not producible from a `NetworkConfig` any
+ * more: it loses its address and never recovers when the relay restarts, when either
+ * side hangs up, and — with no network event at all — on libp2p's own reservation
+ * refresh, which removes the reservation before re-creating it while a configured
+ * listener republishes only from inside its own `listen()`. A hand-written
+ * `<relay>/p2p-circuit` entry in `network.listenAddrs` is rejected on the control
+ * node ({@link resolveListenAddrs}) and folded into the supervised relay set on a
+ * strand node.
+ *
+ * `network.relayAddrs` is FAIL-FAST for the operator by default: a malformed entry
+ * throws here at config resolution regardless of posture, and on the control node a
+ * first reservation attempt that does not land throws out of `start()`
+ * (`RelayReservationFailedError`). Naming a relay that is down still means the control
+ * node does not come up. `network.requireRelay: false` softens the second half only —
+ * for a node that must still boot with no network (a phone, a browser tab) — logging
+ * the failed attempt instead of throwing and leaving the retry supervisor running in
+ * the background; the malformed-entry check is unaffected. A strand node is
+ * fail-SOFT regardless of `requireRelay` (its supervisor keeps trying while the
+ * strand serves).
  *
  * The bare `/p2p-circuit` search listener cannot open a connection on its own:
  * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
@@ -42,18 +55,25 @@
 import type { NetworkConfig } from './types.js';
 import type { RelayReservationState } from './relay-reservation.js';
 /**
- * libp2p's relay SEARCH listener: registers one pending reservation and dials
- * nothing. One entry covers every configured relay — the pending reservation is
- * per-listener, not per-relay, and `relay-reservation.ts` fills it with whichever
- * relay answers first.
+ * The direct listener a node keeps when it configures `relayAddrs` but no
+ * `listenAddrs`. Without this, naming a relay would silently REPLACE the node's
+ * direct TCP listener with a circuit-only one. Shared with the strand-node
+ * derivation (`strand-network-config.ts`), which applies the same rule.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s own default listen addr in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (`/ip4/0.0.0.0/tcp/<port>`,
+ * and `CadreNode` passes `port: 0`) — that file is the source of truth. If it
+ * ever changes its default, this constant has to follow.
  */
-export declare const RELAY_SEARCH_LISTEN_ADDR = "/p2p-circuit";
+export declare const DEFAULT_DIRECT_LISTEN_ADDR = "/ip4/0.0.0.0/tcp/0";
 /**
- * Which listener shape `network.relayAddrs` resolves to for this caller — see the
- * table in the module doc. Defaults to `'configured'` everywhere except the
- * control node's own libp2p options.
+ * libp2p's relay SEARCH listener: registers one pending reservation and dials
+ * nothing. The pending reservation is per-LISTENER, not per-relay: the control
+ * node binds one entry for its whole relay list (`relay-reservation.ts` fills it
+ * with whichever relay answers first), a strand node binds one entry per relay so
+ * each relay's supervisor has a slot of its own to fill.
  */
-export type RelayListenRoute = 'configured' | 'search';
+export declare const RELAY_SEARCH_LISTEN_ADDR = "/p2p-circuit";
 /**
  * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
  * An entry that already carries `/p2p-circuit` is passed through unchanged.
@@ -61,28 +81,113 @@ export type RelayListenRoute = 'configured' | 'search';
  * operator configuration, so a typo must fail loudly at start rather than
  * silently costing the node its reachability.
  *
+ * No node LISTENS on these any more (see the module doc); they are the validated
+ * form of `relayAddrs`, read by `CadreNode.circuitRelayTargets` for the delegate
+ * announce and by `strand-network-config.ts` for the per-relay supervisor list.
+ *
  * Deliberately unlike `extractCircuitRelayTargets` (`delegate-admission.ts`), which
  * SKIPS a bad entry: that one reads addresses discovered at runtime from peers, where
  * one bad entry must not be fatal.
  */
 export declare function relayCircuitAddrs(relayAddrs: readonly string[]): string[];
 /**
- * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * relay listen entry `route` calls for, deduplicated, order-stable (configured
- * entries first). Returns `undefined` when neither field is set, so callers keep
- * omitting `listenAddrs` and inherit db-p2p's default.
- *
- * Every `relayAddrs` entry is validated on BOTH routes — the `'search'` route
- * discards the resolved circuit addrs, but an operator typo must fail at config
- * resolution either way.
+ * The listen multiaddrs the CONTROL node binds: configured `listenAddrs` plus ONE
+ * bare `/p2p-circuit` search entry when `relayAddrs` names any relay, deduplicated,
+ * order-stable (configured entries first). Returns `undefined` when neither field
+ * is set, so callers keep omitting `listenAddrs` and inherit db-p2p's default.
+ *
+ * Every `relayAddrs` entry is validated even though the search entry discards the
+ * resolved circuit addrs — an operator typo must fail at config resolution. A
+ * hand-written `<relay>/p2p-circuit` entry in `listenAddrs` is rejected outright
+ * (see {@link rejectConfiguredCircuitListenAddrs}).
+ *
+ * Strand nodes derive their own listen set from the same config in
+ * `strand-network-config.ts` (`strandNodeAddrs`) — one search entry per relay,
+ * fixed direct ports made ephemeral.
  */
-export declare function resolveListenAddrs(network: NetworkConfig | undefined, route?: RelayListenRoute): string[] | undefined;
+export declare function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined;
+/**
+ * The transport-derived `createLibp2pNode` options a resolved listen set implies —
+ * see {@link resolveTransportOptions}.
+ */
+export interface ListenTransportOptions {
+    /**
+     * Present when some listen entry names WebSocket. Its VALUE is never bound; it is
+     * the switch that makes `@optimystic/db-p2p` add `webSockets()` — see
+     * {@link WS_TRANSPORT_SWITCH_PORT}.
+     */
+    wsPort?: number;
+}
+/**
+ * The transport-derived libp2p options `listenAddrs` implies, and the gate that stops a
+ * listen address the node has no transport for from being SILENTLY dropped.
+ *
+ * libp2p's transport manager sorts configured listen addresses by which transport claims
+ * them, discards the unclaimed ones, and raises `UnsupportedListenAddressesError` only
+ * when EVERY address was discarded. Pair a TCP address with a WebSocket one — which is
+ * exactly what the shipped configs do — and the TCP address carries the start while the
+ * missing WebSocket listener is never reported. Two halves of `NetworkConfig` that have
+ * to agree (`listenAddrs`, and the transports the node will actually have) were never
+ * checked against each other; this is that check, and it covers both node kinds because
+ * both derive their listen set from the same config here ({@link resolveListenAddrs}) or
+ * in `strand-network-config.ts`, and both call this on the result.
+ *
+ * The two transport classes are handled differently, on purpose:
+ *
+ * - **WebSocket is DERIVED.** It is the one non-TCP transport the shipped configs need
+ *   (the React Native reference app's companion drone; `cadre start --ws-port`), and
+ *   `@optimystic/db-p2p` already knows how to add it. `cadre-core` grows no dependency
+ *   and decides no transport policy — it flips db-p2p's own switch
+ *   ({@link WS_TRANSPORT_SWITCH_PORT}).
+ * - **Everything else is REFUSED.** Deriving `/quic-v1`, `/webrtc` or `/webtransport`
+ *   would mean importing transport packages into every `cadre-core` consumer including
+ *   the React Native and browser bundles (against the cross-platform rule in
+ *   `AGENTS.md`) and duplicating policy `libp2p-node.ts` owns. So name the address, name
+ *   the transport it needs, and refuse to start — matching how `network.relayAddrs` and
+ *   `network.announceAddrs` already treat an operator typo.
+ *
+ * Returns `{}` unconditionally when `network.transports` is set: a programmatic embedder
+ * supplying transport factories owns the policy, and the factories are opaque — nothing
+ * can be inferred from them. That is what keeps the RN phone, the web app, and the
+ * integration-test harness unaffected.
+ *
+ * NOTE: pairing this with {@link resolveListenAddrs} is a CONVENTION, not a structure —
+ * a third libp2p-node build site could resolve listen addrs and forget to call this,
+ * putting the original bug back on that path. Both existing sites are covered
+ * (`cadre-node.ts` → `buildControlNodeOptions`, `strand-network-config.ts` →
+ * `strandNodeAddrs`), and they are the only two `createLibp2pNode` callers in this repo
+ * that derive their listen set from a `NetworkConfig` — the other callers
+ * (`integration-tests/src/harness/test-party.ts`, `quereus-plugin-sereus`'s `connect.ts`
+ * and `connect-browser.ts`) pass no `listenAddrs` at all, or pass their own transports
+ * with it. If a third CONFIG-derived site appears, fold the two functions into one that
+ * returns listen addrs and transport options together, so forgetting becomes impossible
+ * rather than merely unlikely.
+ *
+ * @param listenAddrs the ALREADY-resolved listen set — the output of
+ *   {@link resolveListenAddrs}, or the strand derivation, after any per-node rewriting —
+ *   so the check reads what this node will actually bind.
+ * @throws {UnbindableListenAddressError} when a listen entry names a transport outside
+ *   {tcp, ws/wss, p2p-circuit}.
+ */
+export declare function resolveTransportOptions(network: NetworkConfig | undefined, listenAddrs: readonly string[] | undefined): ListenTransportOptions;
+/**
+ * Thrown at config resolution when `network.listenAddrs` names an address none of the
+ * default transports can bind. Names each offending address alongside the libp2p
+ * transport package it would need — what the operator has without this is a node that
+ * starts and silently never listens there.
+ */
+export declare class UnbindableListenAddressError extends Error {
+    readonly listenAddrs: readonly string[];
+    constructor(listenAddrs: readonly string[]);
+}
 /**
  * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
- * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt,
+ * UNLESS `network.requireRelay` is explicitly `false` (see `driveControlRelayReservation`,
+ * which logs and returns instead on that posture).
  *
- * This is what keeps `network.relayAddrs` fail-fast now that the control node
- * takes the `'search'` route: libp2p's own `UnsupportedListenAddressesError` used
+ * This is what keeps `network.relayAddrs` fail-fast by default now that the control node
+ * listens on the bare search entry: libp2p's own `UnsupportedListenAddressesError` used
  * to abort start from inside `listen()`, and an operator who names a relay is
  * telling the node it has no other reachability — coming up undialable is worse
  * than not coming up. Names the relays and the reservation's own reason, both of
@@ -93,3 +198,9 @@ export declare class RelayReservationFailedError extends Error {
     readonly state: RelayReservationState;
     constructor(relayAddrs: readonly string[], state: RelayReservationState);
 }
+/**
+ * `<something>/p2p-circuit` — the configured shape, as opposed to the bare search
+ * addr. An unparsable entry is `false`: libp2p reports a bad listen addr itself,
+ * and this helper only ever ADDS a denial (or, on the strand path, a supervisor).
+ */
+export declare function isConfiguredCircuitListenAddr(listenAddr: string): boolean;