@serfab/cadre-core 1.14.0 → 1.16.0

package/dist/provider/rent-node.js

@@ -0,0 +1,220 @@
+/**
+ * Rent a node from a hosting provider and add it to this node's cadre, by whichever of the two
+ * join paths fits (`docs/architecture.md` → "Renting a node from an app"):
+ *
+ * - **invitation**, when the cadre has a member the container can reach from the provider's
+ *   network (`CadreNode.invitationReach()` reads `anywhere`): mint a single-use, non-owner
+ *   invitation and create the container with it; the container joins by itself and the app
+ *   watches `getContainer(id).join`.
+ * - **claim**, otherwise (a phone that is the cadre's only member, or members reachable only on
+ *   their LAN, which the provider's container is never on): create the container, poll for its
+ *   node code, and claim it from this node.
+ *
+ * Nothing here persists anything: which container belongs to which cadre is the app's record,
+ * and {@link finishRental} is how an app resumes a rental it was killed in the middle of. The
+ * node code carries the claim secret, so neither the code nor the decoded payload is ever
+ * logged, only the container id and the peer id.
+ */
+import debug from 'debug';
+import { decodeNodeClaimPayload } from '../node-claim-payload.js';
+import { ProviderApiError } from './client.js';
+const log = debug('sereus:cadre:provider-rent');
+export class RentNodeError extends Error {
+    constructor(code, containerId) {
+        super(`rentNode: ${code}${containerId ? ` (container ${containerId})` : ''}`);
+        this.code = code;
+        this.containerId = containerId;
+        this.name = 'RentNodeError';
+    }
+}
+/**
+ * The provider's enrolment window is 60 s and an image pull can precede it. Bounds the
+ * container's start, not an exchange over the link, so it is not derived from the link budget.
+ */
+// eslint-disable-next-line no-restricted-syntax -- link-independent: bounds the container's start (an image pull plus the provider's 60 s enrolment window), not an exchange over the link
+export const DEFAULT_NODE_CODE_DEADLINE_MS = 120000;
+export const NODE_CODE_POLL_MS = 2000;
+/** Lifetime of the invitation a rental mints: long enough for the container to start and redeem, short enough to limit a leaked bundle. */
+export const RENTAL_INVITATION_TTL_MS = 15 * 60000;
+/**
+ * Rent a node and add it to `node`'s cadre; see the module doc for the path choice.
+ *
+ * The claim path's `claimNode` can take up to the per-peer dial limit plus the seed request
+ * when no address answers (its doc: 114.5 s at the default link); no timeout is added on top
+ * of it, and `onProgress('claiming')` is the app's cue to show a slow hint. Two calls at once
+ * on one node both mint or both create; serializing them is the app's.
+ *
+ * @throws {RentNodeError} `not-an-owner`, or `node-not-ready` once the container exists.
+ * @throws {ProviderApiError} when the provider refused a request (a lapsed subscription is `403 QUOTA_EXCEEDED`).
+ * @throws {ClaimRefusedError} or {PeerUnreachableError} from `claimNode`, as it throws them.
+ */
+export async function rentNode(node, client, options = {}) {
+    await requireOwner(node);
+    const reach = await node.invitationReach();
+    log('renting a node for party %s; invitation reach %s → %s path', node.partyId, reach, reach === 'anywhere' ? 'invitation' : 'claim');
+    return reach === 'anywhere'
+        ? await rentByInvitation(node, client, options)
+        : await rentByClaim(node, client, options);
+}
+/**
+ * Resume a rental: for an app that was killed mid-flow or hit the node-code deadline.
+ *
+ * - a `stopped` or `error` container → `RentNodeError('container-gone')`;
+ * - a claim container not yet claimed → the code, then `claimNode`, as {@link rentNode} would;
+ * - a claim container claimed into this cadre → done. The provider withholds the code once a
+ *   claim is folded, so the claim is not re-run; one claimed by another cadre's owner →
+ *   `RentNodeError('claimed-by-another')`;
+ * - an invitation container → done while `pending` or `accepted` (the app watches `join`), or
+ *   the failed outcome, after which the app deletes the container and rents again (the claim
+ *   path is chosen then if the member that answered is gone).
+ */
+export async function finishRental(node, client, containerId, options = {}) {
+    await requireOwner(node);
+    const report = await client.getContainer(containerId);
+    const kind = joinKindOf(report, containerId);
+    if (kind === 'claim') {
+        return await finishClaim(node, client, report, options);
+    }
+    const join = report.join;
+    if (join?.kind === 'invitation' && join.state === 'failed') {
+        return { containerId, outcome: 'failed', error: join.error, retryable: join.retryable };
+    }
+    return invitationResult(report.container);
+}
+async function requireOwner(node) {
+    if (!await node.isOwner())
+        throw new RentNodeError('not-an-owner');
+}
+async function rentByInvitation(node, client, options) {
+    report(options, 'inviting');
+    const { invitation, encoded } = await node.createCadreInvitation({ grantsOwner: false, uses: 1, expiresInMs: RENTAL_INVITATION_TTL_MS });
+    report(options, 'creating');
+    let container;
+    try {
+        container = await client.createContainer({ join: { kind: 'invitation', invitation: encoded }, profile: options.profile ?? 'storage' });
+    }
+    catch (error) {
+        await withdrawQuietly(node, invitation.invite.key);
+        throw error;
+    }
+    log('container %s created with an invitation; it joins by itself', container.id);
+    report(options, 'done');
+    return invitationResult(container);
+}
+/** A create that failed leaves no live invitation behind; a withdrawal that fails too is logged, and the create's error is what the caller sees. */
+async function withdrawQuietly(node, key) {
+    try {
+        await node.withdrawCadreInvitation(key);
+    }
+    catch (error) {
+        log('withdrawing invitation %s after a failed create failed too: %o', key, error);
+    }
+}
+async function rentByClaim(node, client, options) {
+    report(options, 'creating');
+    const container = await client.createContainer({ join: { kind: 'claim' }, profile: options.profile ?? 'storage' });
+    log('container %s created for a claim', container.id);
+    return await claimContainer(node, client, container.id, options);
+}
+/** Poll for the node code, then claim; the second half of the claim path, shared with {@link finishRental}. */
+async function claimContainer(node, client, containerId, options) {
+    report(options, 'waiting-for-code');
+    const { code, peerId } = await awaitNodeCode(client, containerId, options);
+    report(options, 'claiming');
+    // The claim is the owner's signature; the app asked the user before calling.
+    await node.claimNode(decodeNodeClaimPayload(code));
+    log('container %s claimed; its node is %s', containerId, peerId);
+    report(options, 'done');
+    return { containerId, join: 'claim', peerId };
+}
+/**
+ * `getNodeCode` every poll interval until it answers or the deadline passes. A container that
+ * dies meanwhile (`409 CONTAINER_GONE`) is `container-gone`, the same code `finishRental` gives
+ * one found dead, so an app handles both at one site.
+ */
+async function awaitNodeCode(client, containerId, options) {
+    const deadline = Date.now() + (options.nodeCodeDeadlineMs ?? DEFAULT_NODE_CODE_DEADLINE_MS);
+    const poll = options.nodeCodePollMs ?? NODE_CODE_POLL_MS;
+    for (;;) {
+        const answer = await requestNodeCode(client, containerId);
+        if (!('notReady' in answer))
+            return answer;
+        if (Date.now() >= deadline) {
+            log('container %s has no node code by the deadline', containerId);
+            throw new RentNodeError('node-not-ready', containerId);
+        }
+        await sleep(poll);
+    }
+}
+async function requestNodeCode(client, containerId) {
+    try {
+        return await client.getNodeCode(containerId);
+    }
+    catch (error) {
+        if (error instanceof ProviderApiError && error.code === 'CONTAINER_GONE')
+            throw new RentNodeError('container-gone', containerId);
+        throw error;
+    }
+}
+async function finishClaim(node, client, report, options) {
+    const { container, join } = report;
+    if (join?.kind === 'claim' && join.state === 'claimed')
+        return judgeClaimed(node, report);
+    try {
+        return await claimContainer(node, client, container.id, options);
+    }
+    catch (error) {
+        // The node was claimed between the read and the code request; judge the fresh record.
+        if (error instanceof ProviderApiError && error.code === 'ALREADY_CLAIMED') {
+            return judgeClaimed(node, await client.getContainer(container.id));
+        }
+        throw error;
+    }
+}
+/**
+ * A claimed container is this cadre's when the claim named this party.
+ *
+ * NOTE: the row `claimNode` writes after the node accepts is not re-run here, because the
+ * provider withholds the code once the claim is folded. An app killed between the node
+ * accepting and that one local insert has a node that belongs to this owner with no row for it
+ * on this machine, the window the React Native app's accepted tradeoff for cadre-host claims
+ * names; the remedy is to delete the container and rent again. Revisit if a device run sees it.
+ */
+function judgeClaimed(node, report) {
+    const { container, join } = report;
+    if (join?.kind !== 'claim' || join.state !== 'claimed')
+        throw new RentNodeError('container-gone', container.id);
+    if (join.partyId !== node.partyId) {
+        log('container %s was claimed into another party', container.id);
+        throw new RentNodeError('claimed-by-another', container.id);
+    }
+    return { containerId: container.id, join: 'claim', ...(container.peerId ? { peerId: container.peerId } : {}) };
+}
+/** Which path a container is on; refuses one that is gone or was never a rental. */
+function joinKindOf(report, containerId) {
+    const { container, join } = report;
+    if (container.status === 'stopped' || container.status === 'error')
+        throw new RentNodeError('container-gone', containerId);
+    // The join state is folded from the node's first `/status` read, so a container still
+    // starting carries only the kind it was created with.
+    const kind = join?.kind ?? container.join?.kind;
+    if (kind === undefined)
+        throw new RentNodeError('not-a-rental', containerId);
+    return kind;
+}
+function invitationResult(container) {
+    return { containerId: container.id, join: 'invitation', ...(container.peerId ? { peerId: container.peerId } : {}) };
+}
+function report(options, step) {
+    try {
+        options.onProgress?.(step);
+    }
+    catch (error) {
+        log('onProgress(%s) threw; ignored: %o', step, error);
+    }
+}
+function sleep(ms) {
+    // A plain timer, not an unref'd one: a Node process renting from a script must stay up for it.
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=rent-node.js.map

package/dist/provider/rent-node.js.map

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

package/dist/relay-addrs.d.ts

@@ -50,7 +50,10 @@
  * 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`.
+ * other. A node with configured relays is built with that discovery switched off
+ * altogether when it has a transport list to wrap (`node-transports.ts`), because it
+ * CAN reach a relay-capable peer in its own namespace and take the configured relay's
+ * slot. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 import type { NetworkConfig } from './types.js';
 import type { RelayReservationState } from './relay-reservation.js';
@@ -136,9 +139,11 @@ export interface ListenTransportOptions {
  *
  * - **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}).
+ *   `@optimystic/db-p2p` already knows how to add it, so `cadre-core` flips db-p2p's own
+ *   switch ({@link WS_TRANSPORT_SWITCH_PORT}). A node with configured relays is the one
+ *   case where cadre passes the transport list itself (`node-transports.ts`, to switch
+ *   relay discovery off); when the embedder gave none, that list comes from
+ *   `network.defaultTransports`, which reads the same switch.
  * - **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

package/dist/relay-addrs.js

@@ -50,7 +50,10 @@
  * 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`.
+ * other. A node with configured relays is built with that discovery switched off
+ * altogether when it has a transport list to wrap (`node-transports.ts`), because it
+ * CAN reach a relay-capable peer in its own namespace and take the configured relay's
+ * slot. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 import { multiaddr } from '@multiformats/multiaddr';
 import { circuitRelayTargetOrThrow } from './delegate-admission.js';
@@ -169,9 +172,11 @@ const WS_TRANSPORT_SWITCH_PORT = 0;
  *
  * - **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}).
+ *   `@optimystic/db-p2p` already knows how to add it, so `cadre-core` flips db-p2p's own
+ *   switch ({@link WS_TRANSPORT_SWITCH_PORT}). A node with configured relays is the one
+ *   case where cadre passes the transport list itself (`node-transports.ts`, to switch
+ *   relay discovery off); when the embedder gave none, that list comes from
+ *   `network.defaultTransports`, which reads the same switch.
  * - **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

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":"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"}

package/dist/relay-reservation.d.ts

@@ -73,12 +73,33 @@
  * relay's address. So it asks the relay for a slot directly, via the
  * circuit-relay transport's own reservation store.
  *
+ * ⚠️ WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF. Discovery does reach SOME
+ * peers: every connected peer whose identify lists the relay-hop protocol, and a
+ * storage-profile member's strand node runs the relay server in the same
+ * `/optimystic/strand-<id>/…` namespace as this node's strand node (control nodes
+ * share `/optimystic/control-<partyId>/…` the same way). Discovery reserves on such
+ * a peer as soon as it connects, and that takes one of the slots the configured
+ * relays' supervisors were going to fill. Worse, the reservation store runs one
+ * request at a time and, when a request takes the last free slot, clears its queue
+ * with `@libp2p/utils`' `Queue.clear()`, which drops a queued job WITHOUT ever
+ * settling its promise — so a supervisor whose `addRelay` was queued behind it
+ * waits out its whole deadline (gotchoices/sereus#34). A reservation discovery picks is
+ * also unmanaged: no supervisor re-drives it, the status does not count it, and a
+ * member's strand node goes away whenever that member hibernates. So every node
+ * whose bare search entries cadre generated for configured relays is built through
+ * {@link withoutRelayDiscovery} (`node-transports.ts`), and its slots are filled by
+ * the supervisors alone — given a transport list to wrap, which React Native and
+ * browser embedders always pass and a Node host passes as
+ * `network.defaultTransports` (cadre-cli does). A hand-written bare `/p2p-circuit`
+ * with no configured relay keeps discovery, since nothing else would fill that slot.
+ *
  * Status is derived from the node's LIVE multiaddrs on every read rather than
  * cached at drive time: when a relay restarts or the connection drops, libp2p's
  * listener clears its listening addrs and the circuit multiaddr disappears, so a
  * cached snapshot would keep claiming `reserved` for a node nothing can dial.
  *
- * And because discovery is out of reach, nothing would ever ASK again either —
+ * And because discovery is either off or blind to the relay, nothing would ever
+ * ASK again either —
  * 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. Single-shot
@@ -87,20 +108,20 @@
  * logs failures that read as real and — through the timers it still holds — keeps
  * the process alive for the rest of its `timeoutMs`.
  *
- * 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
+ * What switching discovery off costs: 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, and with discovery on it refilled a slot freed by a hangup (while the
+ * relay stays up) within ~25 ms, measured. With it off that refill waits for the
+ * supervisor's next liveness check ({@link DEFAULT_RELAY_CHECK_MS}, 5 s while held).
+ * A relay RESTART always needed the supervisor, which un-poisons the store's
+ * `relayFilter` before every attempt ({@link clearRelayFilterEntry}). The specs
+ * that build their own clients keep discovery on and disable its refill
  * (`forgetRelayProtocol` in `relay-reservation.spec.ts`) so they prove the
  * supervisor's.
  */
 import type { Libp2p, PeerId } from '@libp2p/interface';
+import type { Libp2pTransports } from '@optimystic/db-p2p';
 /**
  * Relay-reservation posture for a node that reserves through the SEARCH listen
  * addr (bare `/p2p-circuit`) — every cadre control node, whether its relays came
@@ -232,6 +253,19 @@ export declare function circuitMultiaddrsVia(node: Libp2p, addrs: readonly strin
  * module to the discovery wait that never fires.
  */
 export declare function findCircuitRelayTransport(node: Libp2p): CircuitRelayTransportLike | null;
+/**
+ * `transports` with libp2p's relay discovery switched off in the circuit-relay transport any of
+ * them builds, for a node whose bare `/p2p-circuit` slots cadre's own supervisors fill (see the
+ * module header, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other transport is built
+ * untouched.
+ *
+ * Each factory is wrapped rather than the built node patched afterwards: libp2p calls the
+ * factories in its constructor, and `@optimystic/db-p2p` builds with `start: false`, so the
+ * switch lands before anything starts. Patching the running node instead races — db-p2p starts
+ * the node before `createLibp2pNode` returns, and a cohort-seed connection in that window has
+ * already queued a discovered reservation.
+ */
+export declare function withoutRelayDiscovery(transports: Libp2pTransports): Libp2pTransports;
 /**
  * Dial every relay in `addrs`, ask the first one that answers for a reservation
  * slot, then wait until a `/p2p-circuit` address appears.
@@ -317,8 +351,9 @@ export interface RelayReservationSupervisor {
  * it still is — the thing that makes a lost reservation recover on its own.
  *
  * Needed because nothing else re-drives: libp2p re-fills a search listener's
- * freed slot from relay DISCOVERY, and a cadre node's namespaced identify puts
- * discovery permanently out of reach (see the module header). Without this loop a
+ * freed slot from relay DISCOVERY, which cannot see a stock-identify relay from a
+ * cadre node's namespaced identify, and which is switched off outright on every
+ * node whose slots cadre supervises (see the module header). Without this loop a
  * relay restart left a browser tab undialable until the user reloaded the page.
  *
  * Per tick:
@@ -378,9 +413,9 @@ export declare function clearRelayFilterEntry(store: RelayReservationStoreLike,
  * NOBODY IS GOING TO TRY AGAIN. A lost reservation does come back on its own now,
  * as long as a {@link RelayReservationSupervisor} is running — that loop is the
  * only thing that re-drives, since libp2p re-fills a search listener's freed slot
- * from relay DISCOVERY, which a cadre node's namespaced identify puts permanently
- * out of reach (see the module header). So `error` means the supervisor was
- * stopped, was never started, or there is no node at all.
+ * from relay DISCOVERY, which cannot see a stock-identify relay and is switched off
+ * on every node cadre supervises (see the module header). So `error` means the
+ * supervisor was stopped, was never started, or there is no node at all.
  *
  * `retryAtMs` is the supervisor's next scheduled tick (`null` while a drive runs
  * or when there is no supervisor); it both selects `retrying` and is passed

package/dist/relay-reservation.js

@@ -73,12 +73,33 @@
  * relay's address. So it asks the relay for a slot directly, via the
  * circuit-relay transport's own reservation store.
  *
+ * ⚠️ WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF. Discovery does reach SOME
+ * peers: every connected peer whose identify lists the relay-hop protocol, and a
+ * storage-profile member's strand node runs the relay server in the same
+ * `/optimystic/strand-<id>/…` namespace as this node's strand node (control nodes
+ * share `/optimystic/control-<partyId>/…` the same way). Discovery reserves on such
+ * a peer as soon as it connects, and that takes one of the slots the configured
+ * relays' supervisors were going to fill. Worse, the reservation store runs one
+ * request at a time and, when a request takes the last free slot, clears its queue
+ * with `@libp2p/utils`' `Queue.clear()`, which drops a queued job WITHOUT ever
+ * settling its promise — so a supervisor whose `addRelay` was queued behind it
+ * waits out its whole deadline (gotchoices/sereus#34). A reservation discovery picks is
+ * also unmanaged: no supervisor re-drives it, the status does not count it, and a
+ * member's strand node goes away whenever that member hibernates. So every node
+ * whose bare search entries cadre generated for configured relays is built through
+ * {@link withoutRelayDiscovery} (`node-transports.ts`), and its slots are filled by
+ * the supervisors alone — given a transport list to wrap, which React Native and
+ * browser embedders always pass and a Node host passes as
+ * `network.defaultTransports` (cadre-cli does). A hand-written bare `/p2p-circuit`
+ * with no configured relay keeps discovery, since nothing else would fill that slot.
+ *
  * Status is derived from the node's LIVE multiaddrs on every read rather than
  * cached at drive time: when a relay restarts or the connection drops, libp2p's
  * listener clears its listening addrs and the circuit multiaddr disappears, so a
  * cached snapshot would keep claiming `reserved` for a node nothing can dial.
  *
- * And because discovery is out of reach, nothing would ever ASK again either —
+ * And because discovery is either off or blind to the relay, nothing would ever
+ * ASK again either —
  * 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. Single-shot
@@ -87,23 +108,22 @@
  * logs failures that read as real and — through the timers it still holds — keeps
  * the process alive for the rest of its `timeoutMs`.
  *
- * 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
+ * What switching discovery off costs: 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, and with discovery on it refilled a slot freed by a hangup (while the
+ * relay stays up) within ~25 ms, measured. With it off that refill waits for the
+ * supervisor's next liveness check ({@link DEFAULT_RELAY_CHECK_MS}, 5 s while held).
+ * A relay RESTART always needed the supervisor, which un-poisons the store's
+ * `relayFilter` before every attempt ({@link clearRelayFilterEntry}). The specs
+ * that build their own clients keep discovery on and disable its refill
  * (`forgetRelayProtocol` in `relay-reservation.spec.ts`) so they prove the
  * supervisor's.
  */
 import debug from 'debug';
 import { multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
-import { trailingPeerId } from './peer-record.js';
+import { trailingPeerId } from './peer-dial.js';
 import { relayReservationBudgetMs } from './link-budget.js';
 const log = debug('sereus:cadre:relay-reservation');
 /**
@@ -218,6 +238,54 @@ function isReservationStore(value) {
     const store = value;
     return typeof store.addRelay === 'function' && typeof store.hasReservation === 'function';
 }
+/**
+ * `transports` with libp2p's relay discovery switched off in the circuit-relay transport any of
+ * them builds, for a node whose bare `/p2p-circuit` slots cadre's own supervisors fill (see the
+ * module header, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other transport is built
+ * untouched.
+ *
+ * Each factory is wrapped rather than the built node patched afterwards: libp2p calls the
+ * factories in its constructor, and `@optimystic/db-p2p` builds with `start: false`, so the
+ * switch lands before anything starts. Patching the running node instead races — db-p2p starts
+ * the node before `createLibp2pNode` returns, and a cohort-seed connection in that window has
+ * already queued a discovered reservation.
+ */
+export function withoutRelayDiscovery(transports) {
+    return transports.map((factory) => (components) => switchOffRelayDiscovery(factory(components)));
+}
+/** Logged once per process, not per node: every node in it runs the same `@libp2p/circuit-relay-v2`. */
+let reportedDiscoveryFieldMissing = false;
+/**
+ * Clear `transport`'s `discovery` when it is the circuit-relay transport — duck-typed by its
+ * reservation store, as {@link findCircuitRelayTransport} finds it.
+ *
+ * `@libp2p/circuit-relay-v2` 4.2.13 has no init option for this, but declares the field optional
+ * and guards every use (`this.discovery?.startDiscovery()`, `start`/`stop` skip a non-startable
+ * value), so `undefined` before `start()` registers no relay-hop topology and never runs a
+ * peer-store scan.
+ */
+function switchOffRelayDiscovery(transport) {
+    if (typeof transport !== 'object' || transport === null) {
+        return transport;
+    }
+    const candidate = transport;
+    if (!isReservationStore(candidate.reservationStore)) {
+        return transport;
+    }
+    if (!Object.prototype.hasOwnProperty.call(candidate, 'discovery')) {
+        // Not thrown: a node with discovery left on still works, it is only exposed to the slot theft
+        // again — which the `withoutRelayDiscovery` spec in `relay-reservation.spec.ts` reproduces.
+        if (!reportedDiscoveryFieldMissing) {
+            reportedDiscoveryFieldMissing = true;
+            console.warn('cadre: the circuit-relay transport has no `discovery` field to switch off — the ' +
+                '@libp2p/circuit-relay-v2 shape changed. libp2p relay discovery stays on, and it can take a ' +
+                'configured relay\'s reservation slot.');
+        }
+        return transport;
+    }
+    candidate.discovery = undefined;
+    return transport;
+}
 /** Sentinel resolved by the wait arm of {@link requestOneReservation}'s race. */
 const WAIT_OVER = Symbol('relay-reservation-wait-over');
 /**
@@ -314,10 +382,12 @@ export async function driveRelayReservation(node, addrs, opts) {
     const { connected, error: dialError } = await dialRelays(node, addrs, deadline, signal);
     const attempt = await requestReservation(node, connected, deadline, signal);
     // NOTE: a REJECTED reservation still spends the rest of the deadline polling,
-    // because discovery may independently land one (only the no-transport case is
-    // `fatal`). So a misconfigured node reports its now-legible reason a full
-    // `timeoutMs` late. If startup latency on that path ever matters, shorten the
-    // wait once every connected relay has rejected — do not skip it outright.
+    // because on a node that kept libp2p's relay discovery (a hand-written bare
+    // `/p2p-circuit` driven through `reserveRelays`) discovery may independently land
+    // one (only the no-transport case is `fatal`). So a misconfigured node reports its
+    // now-legible reason a full `timeoutMs` late. If startup latency on that path ever
+    // matters, shorten the wait once every connected relay has rejected — do not skip
+    // it outright.
     if (!attempt.fatal && (await waitForCircuitReservation(node, addrs, deadline, pollMs, signal))) {
         return { error: null, cancelled: false };
     }
@@ -410,9 +480,10 @@ function firstDialError(addrs, results) {
  *
  * Sequential, not concurrent: a bare `/p2p-circuit` listener registers exactly
  * ONE pending reservation, so a second concurrent `addRelay` would be rejected
- * with `HadEnoughRelaysError` — noise, not a failure. Running discovery is not a
- * conflict either; `addRelay` dedupes through its own peer queue, so a relay that
- * genuinely is discoverable still reserves exactly once.
+ * with `HadEnoughRelaysError` — noise, not a failure. Discovery naming the SAME
+ * relay is not a conflict (`addRelay` dedupes through its own peer queue); discovery
+ * naming a DIFFERENT peer is, which is why it is off on every node cadre supervises
+ * (module header).
  */
 async function requestReservation(node, connected, deadline, signal) {
     if (connected.length === 0) {
@@ -459,6 +530,17 @@ async function requestReservation(node, connected, deadline, signal) {
  * race settling some other way, aborted in the `finally`. Out-racing the deadline
  * timer is not enough: the loser stays pending, and a pending timer is what holds
  * a Node process open past the stop that asked for it.
+ *
+ * NOTE: the reservation store's `Queue.clear()` drops a queued job unsettled whenever
+ * a reservation takes the last pending slot. With relay discovery off, the slots never
+ * outnumber the supervised relays, so a first request cannot be dropped that way. A
+ * REFRESH of a held reservation that is queued at the moment another relay's first
+ * reservation takes the last slot still is, and that reservation then lapses at the
+ * relay unrefreshed. If that is ever observed, or anything besides the supervisors
+ * gains a way to fill these slots, also end this wait on the store's
+ * `relay:found-enough-relays` event while this relay holds no reservation. The real
+ * fix — `#checkReservationCount` aborting queued jobs instead of clearing them —
+ * belongs to js-libp2p.
  */
 async function requestOneReservation(store, relay, deadline, signal) {
     const waitOver = new AbortController();
@@ -554,8 +636,9 @@ export const DEFAULT_RELAY_MAX_BACKOFF_MS = 60000;
  * it still is — the thing that makes a lost reservation recover on its own.
  *
  * Needed because nothing else re-drives: libp2p re-fills a search listener's
- * freed slot from relay DISCOVERY, and a cadre node's namespaced identify puts
- * discovery permanently out of reach (see the module header). Without this loop a
+ * freed slot from relay DISCOVERY, which cannot see a stock-identify relay from a
+ * cadre node's namespaced identify, and which is switched off outright on every
+ * node whose slots cadre supervises (see the module header). Without this loop a
  * relay restart left a browser tab undialable until the user reloaded the page.
  *
  * Per tick:
@@ -815,9 +898,9 @@ class RelayReservationLoop {
  * NOBODY IS GOING TO TRY AGAIN. A lost reservation does come back on its own now,
  * as long as a {@link RelayReservationSupervisor} is running — that loop is the
  * only thing that re-drives, since libp2p re-fills a search listener's freed slot
- * from relay DISCOVERY, which a cadre node's namespaced identify puts permanently
- * out of reach (see the module header). So `error` means the supervisor was
- * stopped, was never started, or there is no node at all.
+ * from relay DISCOVERY, which cannot see a stock-identify relay and is switched off
+ * on every node cadre supervises (see the module header). So `error` means the
+ * supervisor was stopped, was never started, or there is no node at all.
  *
  * `retryAtMs` is the supervisor's next scheduled tick (`null` while a drive runs
  * or when there is no supervisor); it both selects `retrying` and is passed