@serfab/cadre-core 1.4.0 → 1.6.0

package/dist/peer-dial.js.map

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

package/dist/peer-join-backfill.d.ts

@@ -8,6 +8,13 @@ import { BlockTransferClient, type IRawStorage } from '@optimystic/db-p2p';
  * changes it or starts exporting it.
  */
 export declare const MAX_BLOCK_MESSAGE_BYTES: number;
+/**
+ * Consecutive failed catch-up runs against ONE peer before the module says so on
+ * `console.warn` rather than only in its DEBUG log. At the default backoff that is reached
+ * about 35 seconds in (5 s + 10 s + 20 s), which is late enough to have ruled out a blip and
+ * early enough to be the first thing an operator sees about a machine that is not catching up.
+ */
+export declare const PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES = 3;
 /** Tuning for the per-peer catch-up. Every field optional; defaults in {@link DEFAULT_PEER_JOIN_BACKFILL}. */
 export interface PeerJoinBackfillConfig {
     /** Default true. False disables the catch-up entirely (the pre-existing behaviour). */
@@ -20,10 +27,28 @@ export interface PeerJoinBackfillConfig {
     maxChunkBytes?: number;
     /** Max blocks per push message. Default 64. */
     maxChunkBlocks?: number;
-    /** Per-push dial deadline, ms. Default 3000 (matches SpreadOnChurnMonitor). */
+    /**
+     * Per-push dial deadline, ms. Default {@link peerJoinPushBudget}'s `dialTimeoutMs` — four link
+     * round trips at the declared link, 14 000 ms as shipped. NOT a fixed number: a relayed dial
+     * costs a fixed number of exchanges, so a host on a slower link moves this (and every other
+     * cadre dial budget) by declaring `NetworkConfig.linkRoundTripMs`. Naming it here still wins
+     * over the derived value — `link-budget.ts` has the counts and the measurement.
+     */
     dialTimeoutMs?: number;
-    /** Per-push response deadline, ms. Default 10_000 (matches SpreadOnChurnMonitor). */
+    /**
+     * Per-push response deadline, ms. Default {@link peerJoinPushBudget}'s `responseTimeoutMs` —
+     * two link round trips at the declared link plus a transfer allowance for the chunk's own
+     * bytes, 13 000 ms as shipped. Derived differently from {@link dialTimeoutMs} because it
+     * bounds a data transfer over a connection that is already open, not a dial.
+     */
     responseTimeoutMs?: number;
+    /**
+     * First wait before re-running a catch-up whose last run did not complete cleanly, ms.
+     * Default 5000. Doubles per consecutive failure up to {@link maxRetryBackoffMs}.
+     */
+    retryBackoffMs?: number;
+    /** Ceiling on that doubling wait, ms. Default 60_000. */
+    maxRetryBackoffMs?: number;
 }
 /** The resolved defaults every {@link PeerJoinBackfill} starts from. */
 export declare const DEFAULT_PEER_JOIN_BACKFILL: Required<PeerJoinBackfillConfig>;
@@ -105,8 +130,18 @@ export declare class PeerJoinBackfill {
      * reconnect, which is exactly what the re-arm exists to avoid.
      */
     private readonly rearmAfterFlight;
-    /** Pending per-peer debounce timers, cleared on stop. */
+    /** Pending per-peer timers — the debounce, or a backoff re-arm. Cleared on stop. */
     private readonly timers;
+    /** Consecutive non-clean runs per peer, cleared when one finishes cleanly. */
+    private readonly failures;
+    /**
+     * Epoch ms before which a peer's catch-up must not be re-run, set alongside a backoff timer
+     * that will run it. Its presence is what makes `connection:open` churn free: a schedule
+     * arriving inside the wait is dropped, rather than collapsing the backoff to the debounce.
+     */
+    private readonly retryAfter;
+    /** Peers already reported on `console.warn`; reset when a run finally lands cleanly. */
+    private readonly warned;
     private readonly onConnectionOpen;
     private loggedNoListBlockIds;
     constructor(deps: PeerJoinBackfillDeps, config?: PeerJoinBackfillConfig);
@@ -133,6 +168,25 @@ export declare class PeerJoinBackfill {
      * caught up, or this backfill is stopped.
      */
     catchUpPeer(peerId: PeerId): Promise<PeerJoinBackfillResult>;
-    /** The actual copy. `clean` = every chunk pushed and the remote persisted every block. */
+    /** Whether this network's libp2p node still holds a connection to that peer. */
+    private isConnected;
+    /**
+     * Re-arm one peer's catch-up after a run whose push failed, on a wait that doubles
+     * per consecutive failure up to `maxRetryBackoffMs`. Sets {@link retryAfter} alongside the
+     * timer, which is what makes `connection:open` churn inside the wait free.
+     */
+    private scheduleRetryWithBackoff;
+    /**
+     * Say ONCE per peer, outside the DEBUG log, that its catch-up is not landing. Without this a
+     * machine on a link too slow for a relayed dial produces no statement that anything is wrong:
+     * the peer never appears to hold the blocks, and the only trace is a DEBUG line naming a dial
+     * timeout. Reset when a run finally lands cleanly, so a peer that recovers can report again.
+     */
+    private warnPersistentFailure;
+    /**
+     * The actual copy. `clean` = every chunk pushed and the remote persisted every block.
+     * `pushFailed` = at least one push THREW, which is the only non-clean outcome a retry can
+     * change; the others are verdicts (denied, inert store, blocks the receiver refused).
+     */
     private runCatchUp;
 }

package/dist/peer-join-backfill.js

@@ -1,5 +1,6 @@
 import debug from 'debug';
 import { BlockTransferClient } from '@optimystic/db-p2p';
+import { peerJoinPushBudget } from './link-budget.js';
 // Peer-join whole-store block catch-up, shared by the STRAND networks and the CONTROL
 // network. On `connection:open` (debounced) it pushes every committed, materialized block
 // in the local raw store to the new peer, so a machine that joined after blocks were
@@ -40,19 +41,75 @@ import { BlockTransferClient } from '@optimystic/db-p2p';
 //   `scheduleConnectedPeers()` on a membership change (the production join order is
 //   connect-then-authorize, so the denial at dial time is the expected first pass).
 //
-// NOTE: a failing dial to a non-speaking peer costs one dial timeout per connection:open
-// from such a peer, and is never memoized (only clean runs are). Bounded today by the
-// debounce plus the unreachable-peer bail in `runCatchUp` — one dial per event, not one
-// per chunk. If a node ever holds many such connections, or the enumeration ahead of the
-// first chunk gets expensive, pre-check `libp2p.peerStore` for this network's
-// block-transfer protocol before enumerating.
+// Both per-push deadlines are DERIVED from the declared link round trip
+// (`link-budget.ts`), not fixed milliseconds. That is not tuning — it is what makes this
+// module work at all over a relay. Opening a relayed connection costs a fixed number of
+// exchanges, so the 3000 ms this catch-up used to allow its dial could never finish one
+// above 375 ms of one-way link delay: the catch-up existed so that a machine which joined
+// after blocks were committed physically ends up holding them, and through a relay on any
+// link slow enough to matter it had never once managed to. The reproduction is
+// `packages/integration-tests/src/scenarios/relayed-dial-cost-by-latency.integration.ts`.
 //
-// NOTE: a run that fails is retried only when that peer next opens a connection (or, with
-// an `authorizePeer` gate wired, when `scheduleConnectedPeers()` is driven). Over a stable
-// connection a transient push failure therefore leaves the peer partially copied until the
-// next reconnect (read repair still covers reads meanwhile). If these meshes ever hold
-// long-lived connections where that matters, re-arm the debounce timer with a backoff on a
-// non-clean run instead of waiting for connection:open.
+// It does NOT work at every speed. Above the declared link, libp2p's own dial and
+// inbound-upgrade limits — derived from the same declaration — abandon the connection before
+// any deadline here is consulted, and the listener's one makes that failure look like an absent
+// peer rather than a timeout. That is also what happens when the machine being caught up
+// declared a FASTER link than this one, since its limit is the listener's. See
+// `link-budget.ts` ("libp2p's own two limits", "What still fails at the supported link").
+//
+// RETRY, and why it backs off. A run whose PUSH FAILED — the transport threw, which is what
+// a dial or response deadline expiring looks like here — re-arms on a doubling backoff
+// (`retryBackoffMs` to `maxRetryBackoffMs`), and a `connection:open` arriving while that wait
+// is outstanding is DROPPED rather than collapsing it back to the debounce. Both halves are
+// load-bearing:
+//
+// - Without the re-arm, a transient push failure over a stable connection left the peer
+//   partially copied until its next reconnect (read repair still covered reads meanwhile).
+// - Without dropping churn inside the wait, a peer that cannot be reached at all is
+//   re-dialled on every `connection:open` forever. That is not hypothetical: the 2026-09-26
+//   relayed reproduction shows one peer re-opening a connection about every 14.5 s for a
+//   200-second run, each event starting a catch-up whose dial could not possibly finish.
+//   The connection kept re-appearing because Optimystic's own block-transfer push path
+//   budgets its dial at `transferTimeoutMs ?? 30000` — the one dial budget in the stack
+//   above the measured relayed setup cost — so it succeeded where this one could not.
+//
+// A NON-CLEAN run is NOT on its own enough to re-arm, and the distinction is what keeps the
+// backoff from becoming a worse problem than the one it fixes. `clean` also goes false for
+// outcomes no amount of retrying can change: the membership gate DENIED the peer; this
+// network's raw storage implements no `listBlockIds`, so the catch-up is inert; or the
+// receiver reported blocks in `missing`, which it does per block for a payload it cannot
+// parse and for a revision whose retained commit proof this node does not hold (a push
+// carrying no proof is refused outright by a receiver running the default
+// `requirePushCertificate: true`, and an unretained proof is the ordinary case — see
+// {@link Chunk.proofs}). Re-arming on those would re-push the WHOLE store to that peer every
+// `maxRetryBackoffMs` for as long as the node runs, and report the failure below as a link
+// budget problem when nothing about the link is wrong. All three still leave the peer
+// un-memoized, so its next `connection:open` retries — the behaviour that predates the
+// backoff, and the right one for a verdict rather than a timeout. Denial in particular is
+// re-driven on purpose by `scheduleConnectedPeers()` the moment the membership commit lands,
+// because the control network's join order is connect-then-authorize.
+//
+// A re-arm is also skipped when the peer is no longer CONNECTED. This module's trigger is
+// `connection:open`, so a peer that went away already has one: re-arming instead would leave
+// a machine dialing a peer it cannot see once a minute for the rest of its uptime.
+//
+// After `PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES` consecutive failures one `console.warn`
+// names the peer and the budget, because otherwise a machine on a too-slow link says
+// nothing at all: the connection simply never appears and only a DEBUG log mentions a dial
+// timeout.
+//
+// NOTE: a failing dial to a non-speaking peer costs one dial timeout per attempt, and is
+// never memoized (only clean runs are). Bounded by the backoff above plus the
+// unreachable-peer bail in `runCatchUp` — one dial per attempt, not one per chunk. If a node
+// ever holds many such connections, or the enumeration ahead of the first chunk gets
+// expensive, pre-check `libp2p.peerStore` for this network's block-transfer protocol before
+// enumerating.
+//
+// NOTE: a peer that disconnects INSIDE a backoff wait still costs the one attempt that wait
+// was already armed for — the connectivity check is made when the re-arm is decided, not when
+// the timer fires, and this module subscribes to `connection:open` only. One dial, not a
+// recurring one; if a node ever holds many transient peers, subscribe to `connection:close`
+// and clear the pending timer there.
 const log = debug('sereus:cadre:peer-join-backfill');
 /**
  * The block-transfer protocol's hard cap on one length-prefixed message. Mirrors
@@ -61,6 +118,13 @@ const log = debug('sereus:cadre:peer-join-backfill');
  * changes it or starts exporting it.
  */
 export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
+/**
+ * Consecutive failed catch-up runs against ONE peer before the module says so on
+ * `console.warn` rather than only in its DEBUG log. At the default backoff that is reached
+ * about 35 seconds in (5 s + 10 s + 20 s), which is late enough to have ruled out a blip and
+ * early enough to be the first thing an operator sees about a machine that is not catching up.
+ */
+export const PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES = 3;
 /** The resolved defaults every {@link PeerJoinBackfill} starts from. */
 export const DEFAULT_PEER_JOIN_BACKFILL = {
     enabled: true,
@@ -68,8 +132,13 @@ export const DEFAULT_PEER_JOIN_BACKFILL = {
     maxBlocks: 10000,
     maxChunkBytes: 1024 * 1024,
     maxChunkBlocks: 64,
-    dialTimeoutMs: 3000,
-    responseTimeoutMs: 10000
+    // Derived at the DEFAULT declared link, for a `PeerJoinBackfill` built without a host's
+    // declaration (this module's own tests, an embedder driving it directly). The two production
+    // construction sites pass `peerJoinPushBudget(network?.linkRoundTripMs)` so a host that
+    // declares a slower link moves both — see `link-budget.ts`.
+    ...peerJoinPushBudget(),
+    retryBackoffMs: 5000,
+    maxRetryBackoffMs: 60000
 };
 function emptyResult() {
     return { offered: 0, accepted: 0, rejected: [], uncommitted: 0, unmaterialized: 0, capped: 0, oversized: [], denied: false };
@@ -110,8 +179,18 @@ export class PeerJoinBackfill {
          * reconnect, which is exactly what the re-arm exists to avoid.
          */
         this.rearmAfterFlight = new Set();
-        /** Pending per-peer debounce timers, cleared on stop. */
+        /** Pending per-peer timers — the debounce, or a backoff re-arm. Cleared on stop. */
         this.timers = new Map();
+        /** Consecutive non-clean runs per peer, cleared when one finishes cleanly. */
+        this.failures = new Map();
+        /**
+         * Epoch ms before which a peer's catch-up must not be re-run, set alongside a backoff timer
+         * that will run it. Its presence is what makes `connection:open` churn free: a schedule
+         * arriving inside the wait is dropped, rather than collapsing the backoff to the debounce.
+         */
+        this.retryAfter = new Map();
+        /** Peers already reported on `console.warn`; reset when a run finally lands cleanly. */
+        this.warned = new Set();
         this.loggedNoListBlockIds = false;
         this.config = { ...DEFAULT_PEER_JOIN_BACKFILL, ...config };
         this.createPushClient = deps.createPushClient
@@ -142,6 +221,7 @@ export class PeerJoinBackfill {
         }
         this.timers.clear();
         this.rearmAfterFlight.clear();
+        this.retryAfter.clear();
         log('[%s] stopped', this.deps.label);
     }
     /**
@@ -178,6 +258,13 @@ export class PeerJoinBackfill {
             this.rearmAfterFlight.add(key);
             return;
         }
+        // A peer whose last run failed is already re-armed on a backoff timer that will run it, so
+        // DROP this schedule instead of shortening the wait — otherwise a peer that cannot be
+        // reached is re-dialled on every connection:open forever (see the module comment's retry
+        // paragraph). A denied run never gets here: it does not set a backoff.
+        const retryAt = this.retryAfter.get(key);
+        if (retryAt !== undefined && Date.now() < retryAt)
+            return;
         const existing = this.timers.get(key);
         if (existing)
             clearTimeout(existing);
@@ -198,7 +285,7 @@ export class PeerJoinBackfill {
         }
         this.inFlight.add(key);
         try {
-            const { result, clean } = await this.runCatchUp(peerId);
+            const { result, clean, pushFailed } = await this.runCatchUp(peerId);
             // NOTE: a run that hit `maxBlocks` is still "clean" and still memoizes the peer, so
             // the tail past the ceiling never reaches it. Deliberate: enumeration is not
             // resumable, so not memoizing would re-push the same prefix on every reconnect
@@ -206,6 +293,19 @@ export class PeerJoinBackfill {
             // realistically exceed maxBlocks, the fix is a resumable cursor, not either policy.
             if (clean && !this.stopped) {
                 this.done.add(key);
+                this.failures.delete(key);
+                this.retryAfter.delete(key);
+                this.warned.delete(key);
+            }
+            else if (pushFailed && !this.stopped && this.started && this.isConnected(peerId)) {
+                // `pushFailed`, not `!clean`: a denial, an inert store and a receiver's per-block
+                // rejection are all verdicts a retry cannot change, and re-arming on them would
+                // re-push the whole store to that peer forever. See the module comment.
+                //
+                // Gated on `started` too: the re-arm exists to REPLACE a connection:open-driven retry,
+                // so a caller driving `catchUpPeer` by hand against a backfill that was never started
+                // owns its own retry policy and must not be left holding a background timer.
+                this.scheduleRetryWithBackoff(peerId);
             }
             log('[%s] catch-up peer=%s offered=%d accepted=%d rejected=%d uncommitted=%d unmaterialized=%d capped=%d oversized=%d denied=%s done=%s', this.deps.label, key, result.offered, result.accepted, result.rejected.length, result.uncommitted, result.unmaterialized, result.capped, result.oversized.length, result.denied, clean);
             return result;
@@ -225,7 +325,53 @@ export class PeerJoinBackfill {
             }
         }
     }
-    /** The actual copy. `clean` = every chunk pushed and the remote persisted every block. */
+    /** Whether this network's libp2p node still holds a connection to that peer. */
+    isConnected(peerId) {
+        return this.deps.libp2p.getConnections(peerId).length > 0;
+    }
+    /**
+     * Re-arm one peer's catch-up after a run whose push failed, on a wait that doubles
+     * per consecutive failure up to `maxRetryBackoffMs`. Sets {@link retryAfter} alongside the
+     * timer, which is what makes `connection:open` churn inside the wait free.
+     */
+    scheduleRetryWithBackoff(peerId) {
+        const key = peerId.toString();
+        const failures = (this.failures.get(key) ?? 0) + 1;
+        this.failures.set(key, failures);
+        const delayMs = Math.min(this.config.retryBackoffMs * 2 ** (failures - 1), this.config.maxRetryBackoffMs);
+        this.retryAfter.set(key, Date.now() + delayMs);
+        const existing = this.timers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        this.timers.set(key, setTimeout(() => {
+            this.timers.delete(key);
+            this.retryAfter.delete(key);
+            void this.catchUpPeer(peerId);
+        }, delayMs));
+        log('[%s] catch-up peer=%s failed %d time(s) in a row; retrying in %dms', this.deps.label, key, failures, delayMs);
+        this.warnPersistentFailure(key, failures);
+    }
+    /**
+     * Say ONCE per peer, outside the DEBUG log, that its catch-up is not landing. Without this a
+     * machine on a link too slow for a relayed dial produces no statement that anything is wrong:
+     * the peer never appears to hold the blocks, and the only trace is a DEBUG line naming a dial
+     * timeout. Reset when a run finally lands cleanly, so a peer that recovers can report again.
+     */
+    warnPersistentFailure(key, failures) {
+        if (failures < PEER_JOIN_BACKFILL_WARN_AFTER_FAILURES || this.warned.has(key))
+            return;
+        this.warned.add(key);
+        console.warn(`[cadre:${this.deps.label}] peer-join block catch-up to peer ${key} has failed ${failures} times in a row `
+            + `(dial budget ${this.config.dialTimeoutMs}ms, response budget ${this.config.responseTimeoutMs}ms). `
+            + 'That peer may not be holding blocks committed before it joined. If it is reachable only through a relay, '
+            + 'these budgets and libp2p\'s own connection limits are derived from network.linkRoundTripMs (see link-budget.ts); '
+            + 'a link slower than that declaration, or a peer that declared a faster one, cannot open a relayed connection at all.');
+    }
+    /**
+     * The actual copy. `clean` = every chunk pushed and the remote persisted every block.
+     * `pushFailed` = at least one push THREW, which is the only non-clean outcome a retry can
+     * change; the others are verdicts (denied, inert store, blocks the receiver refused).
+     */
     async runCatchUp(peerId) {
         const result = emptyResult();
         const { storage } = this.deps;
@@ -243,7 +389,7 @@ export class PeerJoinBackfill {
             }
             if (!authorized) {
                 result.denied = true;
-                return { result, clean: false };
+                return { result, clean: false, pushFailed: false };
             }
         }
         if (!storage.listBlockIds) {
@@ -251,7 +397,7 @@ export class PeerJoinBackfill {
                 this.loggedNoListBlockIds = true;
                 log('[%s] raw storage does not implement listBlockIds(); backfill is inert', this.deps.label);
             }
-            return { result, clean: false };
+            return { result, clean: false, pushFailed: false };
         }
         const client = this.createPushClient(peerId);
         const encoder = new TextEncoder();
@@ -363,7 +509,7 @@ export class PeerJoinBackfill {
             log('[%s] peer=%s catch-up CAPPED at %d blocks; %d block id(s) not attempted', this.deps.label, peerId.toString(), this.config.maxBlocks, result.capped);
         }
         const clean = !chunkFailed && result.rejected.length === 0;
-        return { result, clean };
+        return { result, clean, pushFailed: chunkFailed };
     }
 }
 //# sourceMappingURL=peer-join-backfill.js.map

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

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

package/dist/relay-reservation.d.ts

@@ -81,7 +81,11 @@
  * And because discovery is out of reach, 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.
+ * loop is what makes a lost reservation recover without a page reload. Single-shot
+ * but not unstoppable: the primitive takes an `AbortSignal` and the loop trips it
+ * from `stop()`, because a drive left running against a node being torn down both
+ * 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
@@ -125,12 +129,45 @@ export interface RelayReservationState {
      */
     retryAtMs: number | null;
 }
-/** How long {@link driveRelayReservation} waits for a reservation to appear. */
-export declare const DEFAULT_RELAY_RESERVE_TIMEOUT_MS = 10000;
+/**
+ * How long {@link driveRelayReservation} waits for a reservation to appear, at the DEFAULT
+ * declared link round trip: `RELAY_RESERVATION_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS`
+ * (3500 ms) = 14 000 ms, where it was a fixed 10_000 before it was derived.
+ *
+ * Counted rather than chosen because this one deadline bounds the whole drive — dial the relay,
+ * request the reservation, wait — and each of those costs a fixed number of exchanges, not a
+ * fixed number of milliseconds. `link-budget.ts` carries the counts, the measurement behind
+ * them, and what still fails at the supported link whatever this says.
+ *
+ * A host on a slower link moves it by declaring `NetworkConfig.linkRoundTripMs`, which both
+ * call sites thread in (`CadreNode.reserveRelays` for the control node,
+ * `StrandInstanceManager`'s per-relay supervisors for a strand). This constant is the fallback
+ * for a caller that declares nothing.
+ */
+export declare const DEFAULT_RELAY_RESERVE_TIMEOUT_MS: number;
 export declare const DEFAULT_RELAY_RESERVE_POLL_MS = 250;
 export interface RelayReserveOptions {
     timeoutMs?: number;
     pollMs?: number;
+    /**
+     * Ends an in-flight drive early. Aborting is not a failure: the drive returns
+     * `{ error: null, cancelled: true }` and clears every timer it holds, so the
+     * process is free to exit immediately instead of trailing the teardown that
+     * cancelled it.
+     */
+    signal?: AbortSignal;
+}
+/** What one {@link driveRelayReservation} came back with. */
+export interface RelayReserveResult {
+    /** Why no reservation landed; `null` when one did — or when the drive was cancelled. */
+    error: string | null;
+    /**
+     * The drive ended because its caller's `signal` tripped, not because of anything
+     * the relay did. Separate from `error` because `error: null` means "a reservation
+     * landed" and a cancelled drive landed nothing: folded together, a caller would
+     * read cancellation as success. `cancelled: true` always implies `error: null`.
+     */
+    cancelled: boolean;
 }
 /**
  * The slice of `@libp2p/utils`' `Filter` (a cuckoo filter) that the reservation
@@ -205,18 +242,27 @@ export declare function findCircuitRelayTransport(node: Libp2p): CircuitRelayTra
  * (`error: null`).
  *
  * `timeoutMs` bounds the WHOLE drive — dials, reservation requests and the wait
- * share one deadline.
+ * share one deadline. `opts.signal` bounds it from the other side: every phase
+ * below returns as soon as it trips, and the drive reports `cancelled` rather than
+ * inventing a failure for a relay that was never given a chance to answer.
  */
-export declare function driveRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReserveOptions): Promise<{
-    error: string | null;
-}>;
+export declare function driveRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReserveOptions): Promise<RelayReserveResult>;
 /** Gap between liveness checks while a reservation is held. */
 export declare const DEFAULT_RELAY_CHECK_MS = 5000;
 /** Backoff before the first re-drive after a failed attempt. */
 export declare const DEFAULT_RELAY_MIN_BACKOFF_MS = 2000;
 /** Ceiling the backoff doubles up to. */
 export declare const DEFAULT_RELAY_MAX_BACKOFF_MS = 60000;
-export interface RelayReservationSupervisorOptions extends RelayReserveOptions {
+/**
+ * Everything one drive takes, minus its `signal`, plus the loop's own cadence.
+ *
+ * `signal` is omitted rather than inherited because these options are handed
+ * straight to every drive: a caller-supplied one would cancel each attempt without
+ * the loop knowing, leaving it to reschedule drives that return immediately and
+ * forever. The way to cancel a supervisor is
+ * {@link RelayReservationSupervisor.stop}, which owns the signal it passes down.
+ */
+export interface RelayReservationSupervisorOptions extends Omit<RelayReserveOptions, 'signal'> {
     /** Gap between liveness checks while a reservation is held. Default 5_000. */
     checkMs?: number;
     /** Backoff before the first re-drive after a failure. Default 2_000. */
@@ -256,9 +302,11 @@ export interface RelayReservationSupervisor {
     /** Reason the last drive produced no reservation; `null` once one is held. */
     readonly lastError: string | null;
     /**
-     * Idempotent. Clears the timer so no further drive is scheduled. A drive that
-     * is ALREADY in flight is not aborted — {@link driveRelayReservation} takes no
-     * signal — but its result is discarded and nothing follows it.
+     * Idempotent. Clears the timer so no further drive is scheduled, and CANCELS the
+     * drive already in flight: it stops dialing or polling, clears every timer it
+     * holds and reports `cancelled`, so a teardown does not trail an attempt against
+     * the node it is dismantling. That result is discarded — a cancelled drive is
+     * not a failure — and nothing follows it.
      */
     stop(): void;
 }