@serfab/cadre-core 0.11.0 → 0.13.0

package/dist/relay-addrs.d.ts

@@ -1,29 +1,59 @@
 /**
  * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
- * setting — into the mechanism this repo already has for reserving a circuit-relay
- * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
+ * 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 transport is always present on the Node path
- * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
- * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
- * that relay and hold a reservation. Everything downstream of the listen list —
- * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
- * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
- * publishing in `registerSelf` — then works unchanged.
+ * `@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}):
  *
- * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
+ * | 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          |
  *
- *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
+ * 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()`.
  *
- * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
- * throws when a configured circuit listener cannot listen, so naming a relay that
- * is down means the node does not start. The fail-soft route is the bare
- * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
- * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
- * reserves via the search listener adds the fatal listener back and the node
- * stops booting when its relay is down.
+ * 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.
+ *
+ * The bare `/p2p-circuit` search listener cannot open a connection on its own:
+ * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
+ * only once the relay-hop protocol id is in that peer's peer-store protocol list,
+ * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
+ * namespaces per network, so a cadre node and a stock relay never identify each
+ * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 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.
+ */
+export declare const RELAY_SEARCH_LISTEN_ADDR = "/p2p-circuit";
+/**
+ * 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.
+ */
+export type RelayListenRoute = 'configured' | 'search';
 /**
  * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
  * An entry that already carries `/p2p-circuit` is passed through unchanged.
@@ -38,8 +68,101 @@ import type { NetworkConfig } from './types.js';
 export declare function relayCircuitAddrs(relayAddrs: readonly string[]): string[];
 /**
  * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * circuit-listen addr of every configured 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.
+ * 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.
+ */
+export declare function resolveListenAddrs(network: NetworkConfig | undefined, route?: RelayListenRoute): 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 resolve their listen set through {@link resolveListenAddrs}.
+ *
+ * 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} 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.
+ *
+ * This is what keeps `network.relayAddrs` fail-fast now that the control node
+ * takes the `'search'` route: 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
+ * which the libp2p error omitted.
  */
-export declare function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined;
+export declare class RelayReservationFailedError extends Error {
+    readonly relayAddrs: readonly string[];
+    readonly state: RelayReservationState;
+    constructor(relayAddrs: readonly string[], state: RelayReservationState);
+}

package/dist/relay-addrs.js

@@ -1,27 +1,43 @@
 /**
  * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
- * setting — into the mechanism this repo already has for reserving a circuit-relay
- * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
- *
- * `@libp2p/circuit-relay-v2`'s transport is always present on the Node path
- * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
- * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
- * that relay and hold a reservation. Everything downstream of the listen list —
- * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
- * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
- * publishing in `registerSelf` — then works unchanged.
- *
- * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
- *
- *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
- *
- * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
- * throws when a configured circuit listener cannot listen, so naming a relay that
- * is down means the node does not start. The fail-soft route is the bare
- * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
- * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
- * reserves via the search listener adds the fatal listener back and the node
- * stops booting when its relay is down.
+ * 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.
+ *
+ * The bare `/p2p-circuit` search listener cannot open a connection on its own:
+ * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
+ * only once the relay-hop protocol id is in that peer's peer-store protocol list,
+ * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
+ * namespaces per network, so a cadre node and a stock relay never identify each
+ * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 import { multiaddr } from '@multiformats/multiaddr';
 import { circuitRelayTargetOrThrow } from './delegate-admission.js';
@@ -36,6 +52,13 @@ import { circuitRelayTargetOrThrow } from './delegate-admission.js';
  * ever changes its default, this constant has to follow.
  */
 const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
+/**
+ * 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.
+ */
+export 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.
@@ -52,20 +75,280 @@ export function relayCircuitAddrs(relayAddrs) {
 }
 /**
  * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * circuit-listen addr of every configured 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.
+ * 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.
  */
-export function resolveListenAddrs(network) {
-    const circuits = relayCircuitAddrs(network?.relayAddrs ?? []);
+export function resolveListenAddrs(network, route = 'configured') {
+    const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
+    const relayEntries = route === 'search'
+        ? (configured.length > 0 ? [RELAY_SEARCH_LISTEN_ADDR] : [])
+        : configured;
     const listenAddrs = network?.listenAddrs;
-    if (!listenAddrs && circuits.length === 0) {
+    if (route === 'search') {
+        rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
+    }
+    if (!listenAddrs && relayEntries.length === 0) {
         return undefined;
     }
     // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
-    // empty — but a relay named alongside it still gets its circuit listener, since
-    // acquiring one is the whole point of configuring a relay.
-    return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...circuits]);
+    // empty — but a relay named alongside it still gets its listen entry, since
+    // acquiring a slot is the whole point of configuring a relay.
+    return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...relayEntries]);
+}
+/**
+ * The `wsPort` value passed purely to turn `@optimystic/db-p2p`'s WebSocket transport
+ * ON. It is never bound, so it is deliberately `0` rather than a port scraped from a
+ * listen entry.
+ *
+ * WHY it is a switch and not a port: `createLibp2pNode`
+ * (`../optimystic/packages/db-p2p/src/libp2p-node.ts`) feeds `wsPort` into BOTH its
+ * default transports and its default listen addrs, and `createLibp2pNodeBase`
+ * (`libp2p-node-base.ts:490-491`) falls back to those two defaults INDEPENDENTLY:
+ *
+ * ```ts
+ * const listenAddrs = options.listenAddrs ?? defaults.listenAddrs;
+ * const transports  = options.transports  ?? defaults.transports;
+ * ```
+ *
+ * `cadre-core` always supplies explicit `listenAddrs` alongside it, so the synthesized
+ * `/ip4/<wsHost>/tcp/<wsPort>/ws` default ADDRESS is discarded while the `webSockets()`
+ * transport it added survives. A scraped port would also be a lie whenever a config
+ * names several WebSocket addresses on different ports, and the strand path rewrites
+ * fixed ports to `0` regardless (`strand-network-config.ts`).
+ *
+ * NOTE: db-p2p's own doc comment on `wsPort` (`libp2p-node-base.ts:170-172`) says it is
+ * "Ignored when `transports`/`listenAddrs` are explicitly provided" — true of the
+ * address half, NOT of the transport half, which is the half this depends on. Re-verify
+ * empirically rather than trusting that comment: `test/listen-transport-options.spec.ts`
+ * boots a real node and asserts a `/ws` multiaddr appears. If db-p2p ever makes the
+ * comment true of both halves, it needs an explicit `enableWebSockets` switch and this
+ * constant becomes unusable.
+ */
+const WS_TRANSPORT_SWITCH_PORT = 0;
+/**
+ * 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 resolve their listen set through {@link resolveListenAddrs}.
+ *
+ * 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} 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 function resolveTransportOptions(network, listenAddrs) {
+    if (network?.transports) {
+        return {};
+    }
+    const kinds = (listenAddrs ?? []).map((addr) => [addr, listenTransportKind(addr)]);
+    const unsupported = kinds.filter(([, kind]) => kind === 'unsupported').map(([addr]) => addr);
+    if (unsupported.length > 0) {
+        throw new UnbindableListenAddressError(unsupported);
+    }
+    return kinds.some(([, kind]) => kind === 'websockets') ? { wsPort: WS_TRANSPORT_SWITCH_PORT } : {};
+}
+/**
+ * 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 class UnbindableListenAddressError extends Error {
+    constructor(listenAddrs) {
+        super('network.listenAddrs names an address this node has no transport for: ' +
+            `${listenAddrs.map((a) => `${a} — ${unbindableReason(a)}`).join('; ')}. ` +
+            'Default transports bind TCP (including /unix/<path>), WebSocket (/ws, /wss) and circuit-relay addresses only. ' +
+            'Either drop the address, or supply the transport programmatically via network.transports.');
+        this.listenAddrs = listenAddrs;
+        this.name = 'UnbindableListenAddressError';
+    }
+}
+/**
+ * Which default transport claims `listenAddr`, or `'unsupported'` when none does.
+ *
+ * Classification is a multiaddr COMPONENT question, not a string question, so this
+ * parses and reads the transport stack — the component names left once the addressing
+ * and security layers are dropped. That stack is outermost-LAST
+ * (`/ip4/…/tcp/443/tls/ws` → `['tcp', 'ws']`), which is why its terminal entry decides.
+ *
+ * An unparsable entry is `'ignored'` and passes through untouched, following
+ * `isConfiguredCircuitListenAddr` below and `ephemeralPortListenAddr`
+ * (`strand-network-config.ts`): libp2p reports a bad listen addr itself, and this check
+ * must only ever ADD a denial.
+ */
+function listenTransportKind(listenAddr) {
+    let stack;
+    try {
+        stack = transportStack(listenAddr);
+    }
+    catch {
+        return 'ignored';
+    }
+    const outermost = stack.at(-1);
+    if (outermost === undefined) {
+        // Nothing but addressing components — a bare `/ip4/1.2.3.4`. No transport claims
+        // it, so it is dropped by exactly the same silent path this check exists to close.
+        return 'unsupported';
+    }
+    if (outermost === 'p2p-circuit') {
+        return 'circuit';
+    }
+    if (outermost === 'ws' || outermost === 'wss') {
+        return 'websockets';
+    }
+    // Only a BARE tcp or unix stack is TCP. `@libp2p/tcp` binds both — its `listenFilter`
+    // accepts an exact TCP match OR a `/unix/<path>` address (a named pipe on Windows) —
+    // and nothing layered on top of either, which is why `/tcp/<port>/<anything else>` is
+    // NOT waved through merely because a `tcp` component happens to appear.
+    return stack.length === 1 && (outermost === 'tcp' || outermost === 'unix') ? 'tcp' : 'unsupported';
+}
+/**
+ * Component names of `listenAddr` with the addressing and security layers removed, so
+ * what remains names transports. Host components (`ip4`, `dns4`, …) and the layers that
+ * ride inside a transport without being one (`tls`, `sni`, `certhash`, `p2p`) say
+ * nothing about which transport has to be configured.
+ */
+function transportStack(listenAddr) {
+    return multiaddr(listenAddr).getComponents()
+        .map((component) => component.name)
+        .filter((name) => !NON_TRANSPORT_COMPONENTS.has(name));
+}
+/** Components that address or secure a connection rather than name its transport. */
+const NON_TRANSPORT_COMPONENTS = new Set([
+    'ip4', 'ip6', 'ip6zone', 'dns', 'dns4', 'dns6', 'dnsaddr',
+    'tls', 'sni', 'certhash', 'p2p', 'noise'
+]);
+/**
+ * Why `listenAddr` cannot be bound, phrased for the operator: the libp2p package that
+ * would make it bindable where one is known, and otherwise what is wrong with it.
+ *
+ * Read OUTERMOST-first (`/udp/…/quic-v1/webtransport` needs `@libp2p/webtransport`,
+ * not the `@libp2p/quic` it rides on), matching how `listenTransportKind` decides.
+ */
+function unbindableReason(listenAddr) {
+    let stack;
+    try {
+        stack = transportStack(listenAddr);
+    }
+    catch {
+        return 'not a parsable multiaddr';
+    }
+    if (stack.length === 0) {
+        return 'it names no transport component';
+    }
+    const pkg = [...stack].reverse().map((name) => TRANSPORT_PACKAGES[name]).find((p) => p !== undefined);
+    return pkg === undefined ? 'needs an unrecognized transport' : `needs ${pkg}`;
+}
+/**
+ * The libp2p package each unbindable transport component comes from. Naming the package
+ * is the actionable half of the refusal — the operator either drops the address or wires
+ * that package in through `network.transports`.
+ */
+const TRANSPORT_PACKAGES = {
+    'quic': '@libp2p/quic',
+    'quic-v1': '@libp2p/quic',
+    'webtransport': '@libp2p/webtransport',
+    'webrtc': '@libp2p/webrtc',
+    'webrtc-direct': '@libp2p/webrtc'
+};
+/**
+ * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ *
+ * This is what keeps `network.relayAddrs` fail-fast now that the control node
+ * takes the `'search'` route: 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
+ * which the libp2p error omitted.
+ */
+export class RelayReservationFailedError extends Error {
+    constructor(relayAddrs, state) {
+        super(`network.relayAddrs reservation failed (status: ${state.status}): ` +
+            `${state.error ?? 'no /p2p-circuit address appeared'} — relays: ${relayAddrs.join(', ')}`);
+        this.relayAddrs = relayAddrs;
+        this.state = state;
+        this.name = 'RelayReservationFailedError';
+    }
+}
+/**
+ * A hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs` is the
+ * CONFIGURED listener shape, and it is unusable on the `'search'` route: libp2p
+ * dials that relay from inside `listen()`, the bring-up quiet period
+ * (`membership-connection-gater.ts`) denies exactly that dial, `listen()` fails, and
+ * the transport manager's default `FATAL_ALL` aborts `libp2p.start()`. The operator
+ * would see `UnsupportedListenAddressesError` from deep inside bring-up with nothing
+ * naming the cause, so name it here instead.
+ *
+ * `network.relayAddrs` is the exact replacement — same relay, and the reservation is
+ * driven after bring-up, which is the whole point of the route.
+ */
+function rejectConfiguredCircuitListenAddrs(listenAddrs) {
+    const configured = listenAddrs.filter(isConfiguredCircuitListenAddr);
+    if (configured.length > 0) {
+        throw new Error('network.listenAddrs names a relay directly ' +
+            `(${configured.join(', ')}), which a control node cannot listen on: libp2p would ` +
+            'dial that relay during control-database bring-up, when the node accepts no ' +
+            'connections. Move the relay to network.relayAddrs, which reserves after bring-up.');
+    }
+}
+/** `<something>/p2p-circuit` — the configured shape, as opposed to the bare search addr. */
+function isConfiguredCircuitListenAddr(listenAddr) {
+    if (listenAddr === RELAY_SEARCH_LISTEN_ADDR) {
+        return false;
+    }
+    try {
+        return multiaddr(listenAddr).getComponents().some((c) => c.name === 'p2p-circuit');
+    }
+    catch {
+        // Not our error to raise: libp2p reports an unparsable listen addr itself, and
+        // this helper only ever ADDS a denial.
+        return false;
+    }
 }
 /**
  * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.

package/dist/relay-addrs.js.map

@@ -1 +1 @@
-{"version":3,"file":"relay-addrs.js","sourceRoot":"","sources":["../src/relay-addrs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAGpE;;;;;;;;;GASG;AACH,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA6B;IAC7D,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IACzC,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,kFAAkF;IAClF,gFAAgF;IAChF,2DAA2D;IAC3D,OAAO,MAAM,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,MAAM,cAAc,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC;IACxF,MAAM,UAAU,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,cAAc,CAAC;IAC3E,IAAI,CAAC;QACH,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC,6BAA6B;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,4FAA4F,SAAS,EAAE,EACvG,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,2FAA2F;AAC3F,SAAS,eAAe,CAAC,SAAiB;IACxC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,sDAAsD,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACrG,CAAC;AACH,CAAC;AAED,yFAAyF;AACzF,SAAS,MAAM,CAAC,KAAwB;IACtC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"relay-addrs.js","sourceRoot":"","sources":["../src/relay-addrs.ts"],"names":[],"mappings":"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"}

package/dist/relay-reservation.d.ts

@@ -4,28 +4,32 @@
  * (live) status derivation.
  *
  * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen
- * address, and the two shapes are alternatives, not layers:
+ * address:
  *
  * | listen addr                                       | libp2p behaviour                                                                     | unreachable relay          |
  * | ------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------- |
  * | `<dial addr>/p2p/<relayPeerId>/p2p-circuit`        | CONFIGURED reservation: dial that exact relay and reserve, or fail                     | `listen()` throws          |
  * | bare `/p2p-circuit`                                | SEARCH mode: register a pending reservation, to be filled by relay discovery           | nothing throws, no reserve |
  *
- * The configured shape is what `relay-addrs.ts` builds out of `network.relayAddrs`.
- * It is **fail-fast by construction**: libp2p's transport manager throws
- * `UnsupportedListenAddressesError` when any configured listen address fails to
- * listen under the default `FATAL_ALL` fault tolerance, so naming a relay that is
- * down means the node does not start. Good for a server; wrong for a browser tab,
- * which must still boot (solo, undialable) when its relay is down.
+ * A search listener needs someone to (a) dial the relay and (b) fill the pending
+ * reservation it created, then report whether one actually landed. That is this
+ * module. It is **fail-soft by construction**: nothing here throws.
  *
- * So a browser-shaped node listens on bare `/p2p-circuit` and needs someone to
- * (a) dial the relay and (b) fill the pending reservation that listener created,
- * then report whether one actually landed. That is this module. It is **fail-soft
- * by construction**: nothing here throws.
+ * EVERY cadre CONTROL node now takes that route — `network.relayAddrs` resolves
+ * to the bare search entry (`relay-addrs.ts` → `RelayListenRoute`) and
+ * `CadreNode.start()` drives this module once the control database is up. The
+ * configured shape would dial the relay from inside `libp2p.start()`, putting a
+ * sibling in this node's cohort before its own control database existed, and a
+ * sibling that has not yet replicated this node's `CadrePeer` row correctly
+ * refuses its control-DB streams — which killed `start()` outright.
  *
- * Do NOT "consolidate" the two by also setting `network.relayAddrs` on a node
- * that reserves this way — that re-introduces the fatal configured listener
- * alongside the search listener and the tab stops booting when the relay is down.
+ * So the two shapes are no longer alternative ROUTES, only alternative failure
+ * postures on top of the same drive: a node that names `network.relayAddrs` gets
+ * a `RelayReservationFailedError` out of `start()` when the first attempt lands
+ * nothing (fail-fast, the operator asked for this relay), while a node that calls
+ * `CadreNode.reserveRelays()` itself gets a non-`reserved` status and stays up
+ * (fail-soft, the browser-tab posture). Configuring both is now redundant, not
+ * fatal. STRAND nodes still take the configured shape — see `relay-addrs.ts`.
  *
  * ⚠️ WHY THE RESERVATION IS REQUESTED EXPLICITLY RATHER THAN LEFT TO DISCOVERY.
  * libp2p fills a search listener's pending reservation from `RelayDiscovery`,
@@ -60,7 +64,8 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 /**
  * Relay-reservation posture for a node that reserves through the SEARCH listen
- * addr (bare `/p2p-circuit`) rather than a configured `network.relayAddrs` entry.
+ * addr (bare `/p2p-circuit`) — every cadre control node, whether its relays came
+ * from `network.relayAddrs` or from an explicit `CadreNode.reserveRelays()` call.
  *  - `none`     — no relay addrs supplied; the node is undialable by design.
  *  - `dialing`  — a drive is in flight.
  *  - `reserved` — the node currently holds at least one `/p2p-circuit` addr.