@serfab/cadre-core 0.13.0 → 1.1.0

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,22 +81,31 @@ 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}.
@@ -100,7 +129,8 @@ export interface ListenTransportOptions {
  * 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}.
+ * 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:
  *
@@ -134,8 +164,8 @@ export interface ListenTransportOptions {
  * 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.
+ *   {@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}.
  */
@@ -152,10 +182,12 @@ export declare class UnbindableListenAddressError extends Error {
 }
 /**
  * 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
@@ -166,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;

package/dist/relay-addrs.js

@@ -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}):
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr:
  *
- * | 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          |
+ * | 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      |
  *
- * 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()`.
+ * Every cadre-built node takes the SEARCH shape, and something explicit drives the
+ * reservation afterwards (`relay-reservation.ts`):
  *
- * 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).
+ * - 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`).
  *
- * `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 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
@@ -44,19 +57,21 @@ import { circuitRelayTargetOrThrow } from './delegate-admission.js';
 /**
  * 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.
+ * 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.
  */
-const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
+export 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.
+ * 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 const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
 /**
@@ -66,6 +81,10 @@ export const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
  * 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.
@@ -74,24 +93,26 @@ export function relayCircuitAddrs(relayAddrs) {
     return dedupe(relayAddrs.map(circuitListenAddr));
 }
 /**
- * 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.
+ * 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}).
  *
- * 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.
+ * 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 function resolveListenAddrs(network, route = 'configured') {
-    const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
-    const relayEntries = route === 'search'
-        ? (configured.length > 0 ? [RELAY_SEARCH_LISTEN_ADDR] : [])
-        : configured;
+export function resolveListenAddrs(network) {
+    const relayEntries = relayCircuitAddrs(network?.relayAddrs ?? []).length > 0
+        ? [RELAY_SEARCH_LISTEN_ADDR]
+        : [];
     const listenAddrs = network?.listenAddrs;
-    if (route === 'search') {
-        rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
-    }
+    rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
     if (!listenAddrs && relayEntries.length === 0) {
         return undefined;
     }
@@ -141,7 +162,8 @@ const WS_TRANSPORT_SWITCH_PORT = 0;
  * 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}.
+ * 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:
  *
@@ -175,8 +197,8 @@ const WS_TRANSPORT_SWITCH_PORT = 0;
  * 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.
+ *   {@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}.
  */
@@ -297,10 +319,12 @@ const TRANSPORT_PACKAGES = {
 };
 /**
  * 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
@@ -317,7 +341,7 @@ export class RelayReservationFailedError extends Error {
 }
 /**
  * A hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs` is the
- * CONFIGURED listener shape, and it is unusable on the `'search'` route: libp2p
+ * CONFIGURED listener shape, and it is unusable on the control node: 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
@@ -325,7 +349,10 @@ export class RelayReservationFailedError extends Error {
  * 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.
+ * driven after bring-up, which is the whole point of the search shape. (A strand node
+ * built directly from such a config folds the entry into its supervised relay set
+ * instead — `strand-network-config.ts` — but the control node's resolution runs first
+ * on every machine, so in production the entry never reaches a strand node.)
  */
 function rejectConfiguredCircuitListenAddrs(listenAddrs) {
     const configured = listenAddrs.filter(isConfiguredCircuitListenAddr);
@@ -336,8 +363,12 @@ function rejectConfiguredCircuitListenAddrs(listenAddrs) {
             '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) {
+/**
+ * `<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 function isConfiguredCircuitListenAddr(listenAddr) {
     if (listenAddr === RELAY_SEARCH_LISTEN_ADDR) {
         return false;
     }
@@ -351,13 +382,14 @@ function isConfiguredCircuitListenAddr(listenAddr) {
     }
 }
 /**
- * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.
+ * One entry of {@link relayCircuitAddrs}: this relay's addr in the configured shape.
  *
  * NOTE: an entry carrying components AFTER `/p2p-circuit` — a full relayed DIAL addr,
- * `…/p2p/<relay>/p2p-circuit/p2p/<someone else>` — is passed through as written and
- * would be listened on verbatim. It validates (the relay it names is real), so only an
- * operator who pastes a peer's relayed address into `relayAddrs` hits it; if that turns
- * out to be a common paste, truncate at the `/p2p-circuit` component here.
+ * `…/p2p/<relay>/p2p-circuit/p2p/<someone else>` — is passed through as written. It
+ * validates (the relay it names is real), and every consumer reads only the relay
+ * peer id and the dial prefix before `/p2p-circuit`, so the tail is ignored rather
+ * than harmful; if that paste turns out to be common, truncate at the `/p2p-circuit`
+ * component here so the resolved list is canonical.
  */
 function circuitListenAddr(relayAddr) {
     const alreadyCircuit = parseComponents(relayAddr).some((c) => c.name === 'p2p-circuit');

package/dist/relay-addrs.js.map

@@ -1 +1 @@
-{"version":3,"file":"relay-addrs.js","sourceRoot":"","sources":["../src/relay-addrs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relay-addrs.js","sourceRoot":"","sources":["../src/relay-addrs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAIpE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA6B;IAC7D,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;QAC1E,CAAC,CAAC,CAAC,wBAAwB,CAAC;QAC5B,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IACzC,kCAAkC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC,WAAW,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,kFAAkF;IAClF,4EAA4E;IAC5E,8DAA8D;IAC9D,OAAO,MAAM,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC;AACrF,CAAC;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAkC,EAClC,WAA0C;IAE1C,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAU,CAAC,CAAC;IAC5F,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7F,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,4BAA4B,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrG,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD,YAAqB,WAA8B;QACjD,KAAK,CACH,uEAAuE;YACvE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACzE,gHAAgH;YAChH,2FAA2F,CAC5F,CAAC;QANiB,gBAAW,GAAX,WAAW,CAAmB;QAOjD,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,IAAI,KAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,iFAAiF;QACjF,mFAAmF;QACnF,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QAC9C,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,sFAAsF;IACtF,qFAAqF;IACrF,sFAAsF;IACtF,wEAAwE;IACxE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,KAAK,IAAI,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;AACrG,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,UAAkB;IACxC,OAAO,SAAS,CAAC,UAAU,CAAC,CAAC,aAAa,EAAE;SACzC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;SAClC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,qFAAqF;AACrF,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC;IACvC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS;IACzD,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO;CACzC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,IAAI,KAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,0BAA0B,CAAC;IACpC,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,iCAAiC,CAAC;IAC3C,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACtG,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAA2B;IACjD,MAAM,EAAE,cAAc;IACtB,SAAS,EAAE,cAAc;IACzB,cAAc,EAAE,sBAAsB;IACtC,QAAQ,EAAE,gBAAgB;IAC1B,eAAe,EAAE,gBAAgB;CAClC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YACW,UAA6B,EAC7B,KAA4B;QAErC,KAAK,CACH,kDAAkD,KAAK,CAAC,MAAM,KAAK;YACnE,GAAG,KAAK,CAAC,KAAK,IAAI,kCAAkC,cAAc,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC1F,CAAC;QANO,eAAU,GAAV,UAAU,CAAmB;QAC7B,UAAK,GAAL,KAAK,CAAuB;QAMrC,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,kCAAkC,CAAC,WAA8B;IACxE,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,6BAA6B,CAAC,CAAC;IACrE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,6CAA6C;YAC7C,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,yDAAyD;YAClF,6EAA6E;YAC7E,mFAAmF,CACpF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,UAAkB;IAC9D,IAAI,UAAU,KAAK,wBAAwB,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,UAAU,CAAC,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,+EAA+E;QAC/E,uCAAuC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;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"}

package/dist/relay-reservation.d.ts

@@ -16,7 +16,7 @@
  * 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
+ * to the bare search entry (`relay-addrs.ts` → `resolveListenAddrs`) 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
@@ -28,8 +28,30 @@
  * 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`.
+ * (fail-soft, the browser-tab posture). `network.requireRelay: false` gives a
+ * CONFIGURED relay the fail-soft posture too, for a node that must boot with no
+ * network at all — same drive, same supervisor, only the throw is dropped.
+ * Configuring both is now redundant, not fatal.
+ *
+ * STRAND nodes take the same route, ONE supervisor PER RELAY
+ * (`strand-instance-manager.ts` → `buildStrandRuntime`): each configured relay
+ * gets its own bare `/p2p-circuit` listener (`strand-network-config.ts`) and its
+ * own {@link superviseRelayReservation} over just that relay's addr, fail-soft
+ * like the browser tab. The configured shape they used to take
+ * (`<relay>/p2p-circuit`, reserved from inside `libp2p.start()`) is gone from
+ * cadre-built nodes entirely, because it loses its address and never recovers in
+ * three situations — the relay restarts, either side hangs up the relay
+ * connection, and libp2p's OWN reservation refresh (which removes the reservation
+ * before re-creating it, and a configured listener republishes only from inside
+ * its own `listen()`). The last one needs no network event at all: at the relay
+ * default TTL of two hours every configured-shape node went undialable ~1 h 55 min
+ * after reserving. A search listener republishes on `relay:created-reservation`
+ * for its own pending id, which the refresh re-queues, and the supervisor covers
+ * the other two.
+ *
+ * Because a strand node runs one supervisor per relay, "is the reservation held"
+ * is asked PER RELAY ({@link circuitMultiaddrsVia}): relay X's supervisor must not
+ * be satisfied by relay Y's circuit addr, or it would never re-drive X.
  *
  * ⚠️ WHY THE RESERVATION IS REQUESTED EXPLICITLY RATHER THAN LEFT TO DISCOVERY.
  * libp2p fills a search listener's pending reservation from `RelayDiscovery`,
@@ -60,6 +82,19 @@
  * so {@link driveRelayReservation} stays a single-shot primitive and
  * {@link superviseRelayReservation} owns the retry cadence on top of it. That
  * loop is what makes a lost reservation recover without a page reload.
+ *
+ * One measured refinement to "out of reach": libp2p 3.1.3's `connection.newStream`
+ * records every protocol OUR OWN outbound stream negotiated into the peer store, so
+ * the explicit reservation request writes the relay-hop protocol id against the
+ * relay itself. From then on, discovery CAN refill a freed slot on its own — but
+ * only when the relay answers at that moment (a hangup while the relay stays up;
+ * measured at ~25 ms). A relay that is down when the slot frees fails that one
+ * discovery attempt, which poisons the store's `relayFilter` against it, and
+ * nothing in libp2p tries again: a relay RESTART still needs the supervisor, which
+ * un-poisons the filter before every attempt ({@link clearRelayFilterEntry}). Two
+ * mechanisms in production, one guarantee; the specs disable discovery's half
+ * (`forgetRelayProtocol` in `relay-reservation.spec.ts`) so they prove the
+ * supervisor's.
  */
 import type { Libp2p, PeerId } from '@libp2p/interface';
 /**
@@ -133,6 +168,20 @@ export interface CircuitRelayTransportLike {
  * live rather than a stale snapshot.
  */
 export declare function circuitMultiaddrs(node: Libp2p): string[];
+/**
+ * The node's `/p2p-circuit` multiaddrs THROUGH the relays `addrs` name — the ones
+ * whose `/p2p/<relayPeerId>/p2p-circuit` component names one of them. This is the
+ * "held" question a supervisor over a SUBSET of the node's relays has to ask: a
+ * strand node runs one supervisor per relay, and relay X's supervisor must not be
+ * satisfied by relay Y's addr, or a lost X is never re-driven.
+ *
+ * Falls back to EVERY circuit addr when any entry names no relay peer id (no
+ * `/p2p/` component, or unparsable): such an addr can still be dialed and reserved
+ * through, but the addr it earns cannot be attributed to it, so "any circuit addr"
+ * is the only answer that does not mark a live reservation as lost. The control
+ * node passes its whole relay list, so its answer is the same either way.
+ */
+export declare function circuitMultiaddrsVia(node: Libp2p, addrs: readonly string[]): string[];
 /**
  * The running node's circuit-relay transport, or `null` when it has none.
  *
@@ -174,6 +223,19 @@ export interface RelayReservationSupervisorOptions extends RelayReserveOptions {
     minBackoffMs?: number;
     /** Backoff ceiling. Default 60_000. */
     maxBackoffMs?: number;
+    /**
+     * Awaited before every drive AFTER the first — never before the first attempt,
+     * which the caller has typically prepared for already. A hook that throws or
+     * rejects is logged and the drive still runs: the hook is preparation, and a
+     * failed preparation must not cost the attempt itself.
+     *
+     * What a strand node uses it for: re-announcing its delegate peer id to the relay
+     * about to be re-dialed. A party control node running the relay server admits a
+     * strand node on an in-memory delegate grant, and a relay restart drops every
+     * grant it held — so a re-drive that did not re-announce first would be denied
+     * at the relay's connection gate.
+     */
+    beforeRedrive?: () => Promise<void> | void;
 }
 /**
  * A running retry loop for one node + relay list. Obtained from
@@ -217,6 +279,12 @@ export interface RelayReservationSupervisor {
  *    If that lands a reservation, rejoin the healthy path above; if not, sleep
  *    the current backoff and double it up to `maxBackoffMs`.
  *
+ * "Held" is judged PER RELAY — a circuit addr through one of `addrs`' relays
+ * ({@link circuitMultiaddrsVia}) — so several loops over one node, one relay each
+ * (a strand node), each re-drive exactly the relay they own. Every drive after the
+ * first is preceded by the optional `beforeRedrive` hook
+ * ({@link RelayReservationSupervisorOptions}).
+ *
  * Starts immediately; the first tick runs before this returns.
  */
 export declare function superviseRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReservationSupervisorOptions): RelayReservationSupervisor;