@serfab/cadre-core 0.13.0 → 1.1.0

package/src/strand-network-config.ts

@@ -19,16 +19,32 @@
  * The reachability model this rests on: **a strand node is not separately dialable
  * at a published fixed address.** It is reached through (a) its ephemeral direct
  * listener plus the addresses peers observe for it, and (b) circuit relay —
- * `network.relayAddrs` resolves to per-relay `<relay>/p2p-circuit` listen entries
- * that strand nodes DO inherit correctly, because the port inside such an entry is
- * the relay's, not a local bind (`relay-addrs.ts`).
+ * `network.relayAddrs` resolves to ONE bare `/p2p-circuit` SEARCH listen entry PER
+ * relay, and the strand runtime (`strand-instance-manager.ts`) runs one
+ * reservation supervisor per relay over the dial addrs this module returns beside
+ * them ({@link StrandNodeAddrs.relayAddrs}). The same route the control node takes,
+ * for the same reason the configured `<relay>/p2p-circuit` shape was retired
+ * everywhere (`relay-addrs.ts`): a configured listener loses its address on a relay
+ * restart, on either side hanging up, and on libp2p's own reservation refresh, and
+ * recovers from none of them. One search entry per relay rather than one for all,
+ * because a search listener registers exactly ONE pending reservation and libp2p
+ * fills a pending reservation with exactly one relay — so N relays need N listeners,
+ * each with a supervisor that owns it.
  *
- * Everything else in `NetworkConfig` — `relayAddrs`, `transports`,
- * `connectionGater`, `enableRelay` — is inherited by the caller; this module
- * only owns the two host-endpoint fields above. One caveat on `connectionGater`:
- * an OPEN strand's node gets it unchanged, while a CLOSED strand's node composes
- * revoked-peer denial onto it in `strand-instance-manager.ts` (every supplied
- * hook still honored — see `strand-revocation-enforcer.ts`).
+ * A hand-written `<relay>/p2p-circuit` entry in `listenAddrs` counts as a relay
+ * (its dial prefix is supervised like a `relayAddrs` entry) — the control node
+ * rejects that entry outright, so in production it never reaches here, but a
+ * strand built straight from such a config must not get an unsupervised configured
+ * listener either. A hand-written BARE `/p2p-circuit` (the browser shape,
+ * `reference-app-web`) passes through unchanged when no relay is named, and is
+ * absorbed by the per-relay entries when one is.
+ *
+ * Everything else in `NetworkConfig` — `transports`, `connectionGater`,
+ * `enableRelay` — is inherited by the caller; this module only owns the two
+ * host-endpoint fields above and the relay listen shape. One caveat on
+ * `connectionGater`: an OPEN strand's node gets it unchanged, while a CLOSED strand's
+ * node composes revoked-peer denial onto it in `strand-instance-manager.ts` (every
+ * supplied hook still honored — see `strand-revocation-enforcer.ts`).
  *
  * It does carry one non-address option out with them: the WebSocket transport switch
  * a `/ws` listen entry implies (`relay-addrs.ts` → `resolveTransportOptions`). That is
@@ -38,7 +54,14 @@
  */
 
 import { multiaddr, type Component } from '@multiformats/multiaddr';
-import { resolveListenAddrs, resolveTransportOptions } from './relay-addrs.js';
+import {
+  DEFAULT_DIRECT_LISTEN_ADDR,
+  RELAY_SEARCH_LISTEN_ADDR,
+  isConfiguredCircuitListenAddr,
+  relayCircuitAddrs,
+  resolveTransportOptions
+} from './relay-addrs.js';
+import { extractCircuitRelayTargets } from './delegate-admission.js';
 import type { NetworkConfig } from './types.js';
 
 /**
@@ -59,7 +82,9 @@ export interface StrandNodeAddrs {
   /**
    * Listen entries for this strand node, or `undefined` when the operator
    * configured neither `listenAddrs` nor `relayAddrs` — in which case the caller
-   * omits the option and inherits `@optimystic/db-p2p`'s own default.
+   * omits the option and inherits `@optimystic/db-p2p`'s own default. Carries one
+   * bare `/p2p-circuit` entry per entry of {@link relayAddrs}, deliberately NOT
+   * deduplicated: each one is its own listener with its own pending reservation.
    */
   listenAddrs?: string[];
   /**
@@ -70,14 +95,28 @@ export interface StrandNodeAddrs {
    * `/ws` strand listen entry binds nothing and libp2p reports nothing.
    */
   wsPort?: number;
+  /**
+   * The relays this strand node reserves through, as DIRECT dial addrs
+   * (`<host>/p2p/<relayPeerId>`, no `/p2p-circuit`), one per relay, in config order,
+   * deduplicated by relay peer id — the union of `network.relayAddrs` and any
+   * hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs`. Present only
+   * when at least one relay is named.
+   *
+   * NOT a `createLibp2pNode` option: the caller (`strand-instance-manager.ts`)
+   * destructures it off before spreading the rest, and starts one
+   * `superviseRelayReservation` per entry over the node it built.
+   */
+  relayAddrs?: string[];
 }
 
 /**
- * The strand-node view of `network`: the control node's resolved listen entries with
- * every fixed direct port rewritten to an ephemeral one, and no announce fields.
+ * The strand-node view of `network`: the operator's direct listen entries with every
+ * fixed port rewritten to an ephemeral one, one bare `/p2p-circuit` search entry per
+ * relay, the relay dial addrs those entries are supervised against, and no announce
+ * fields.
  *
- * Validation is unchanged and still fail-fast — `resolveListenAddrs` throws here on a
- * malformed `relayAddrs` entry exactly as it does for the control node.
+ * Validation is fail-fast exactly as it is for the control node — `relayCircuitAddrs`
+ * throws here on a malformed `relayAddrs` entry.
  *
  * NOTE: announce entries are no longer validated on this path at all; the CONTROL
  * node's own build (`cadre-node.ts`) is the only thing that parses them, and it runs
@@ -87,22 +126,61 @@ export interface StrandNodeAddrs {
  * would then go unreported until the control node's own build.
  */
 export function strandNodeAddrs(network: NetworkConfig | undefined): StrandNodeAddrs {
-  // The default `'configured'` relay route, deliberately NOT the control node's
-  // `'search'` route: nothing drives an explicit reservation for a strand node, so a
-  // bare `/p2p-circuit` search entry would register a pending reservation nobody fills
-  // and leave every NAT'd strand node undialable. See `relay-addrs.ts`.
-  const listenAddrs = resolveListenAddrs(network);
-  if (!listenAddrs) {
+  const relayAddrs = strandRelayAddrs(network);
+  const configured = network?.listenAddrs;
+  if (!configured && relayAddrs.length === 0) {
     return {};
   }
   // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
   // empty — rewriting must never resurrect a direct listener that was opted out of.
-  const rewritten = dedupe(listenAddrs.map(ephemeralPortListenAddr));
+  // Naming a relay with no `listenAddrs` keeps the direct listener the control node
+  // keeps in that case (`relay-addrs.ts`), so a relay ADDS reachability rather than
+  // replacing it.
+  const direct = configured ?? [DEFAULT_DIRECT_LISTEN_ADDR];
+  // Every circuit entry — the configured shape (now a relay in `relayAddrs`) and a
+  // hand-written bare search entry alike — is replaced by the per-relay search entries
+  // once a relay is named; with none, the operator's entries pass through as written.
+  const kept = relayAddrs.length > 0 ? direct.filter((addr) => !isCircuitListenAddr(addr)) : direct;
+  // The search entries are appended AFTER the dedupe on purpose: they are identical
+  // strings, and each one must survive as its own listener (see the module doc).
+  //
+  // NOTE: every bare entry also makes libp2p start its own relay discovery whenever
+  // that listener's slot is empty (launch, and every loss). Measured on a node with
+  // no peer router: one peer-store scan plus a random walk that fails at once
+  // (`NoPeerRoutersError`) per loss event — no dial churn. If strand nodes ever get
+  // a peer router (a DHT), that walk turns into real dials on every relay loss;
+  // cap or disable `circuitRelayTransport`'s discovery then.
+  const listenAddrs = [
+    ...dedupe(kept.map(ephemeralPortListenAddr)),
+    ...relayAddrs.map(() => RELAY_SEARCH_LISTEN_ADDR)
+  ];
   // Classified AFTER the ephemeral rewrite, so the check reads what this strand node
   // will actually bind. Zeroing a port cannot change an entry's transport — only the
   // `tcp`/`udp` component's value moves — so `/ip4/0.0.0.0/tcp/4002/ws` still resolves
-  // to WebSocket as `/ip4/0.0.0.0/tcp/0/ws`.
-  return { listenAddrs: rewritten, ...resolveTransportOptions(network, rewritten) };
+  // to WebSocket as `/ip4/0.0.0.0/tcp/0/ws`; a bare `/p2p-circuit` is `'circuit'`.
+  return {
+    listenAddrs,
+    ...resolveTransportOptions(network, listenAddrs),
+    ...(relayAddrs.length > 0 && { relayAddrs })
+  };
+}
+
+/**
+ * The relays a strand node built from `network` reserves through, as direct dial
+ * addrs: every `relayAddrs` entry (validated — a malformed one throws, naming the
+ * field) plus the relay named by any hand-written `<relay>/p2p-circuit` listen entry,
+ * deduplicated by relay PEER ID with the first spelling winning — two spellings of one
+ * relay would otherwise get two supervisors fighting over one reservation slot.
+ */
+function strandRelayAddrs(network: NetworkConfig | undefined): string[] {
+  const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
+  const handWritten = (network?.listenAddrs ?? []).filter(isConfiguredCircuitListenAddr);
+  return extractCircuitRelayTargets([...configured, ...handWritten]).map((relay) => relay.relayAddr);
+}
+
+/** Any `/p2p-circuit` listen entry — bare or configured; an unparsable entry is not one. */
+function isCircuitListenAddr(listenAddr: string): boolean {
+  return listenAddr === RELAY_SEARCH_LISTEN_ADDR || isConfiguredCircuitListenAddr(listenAddr);
 }
 
 /**

package/src/strand-solicitation.ts

@@ -7,7 +7,8 @@ import { sign } from '@optimystic/quereus-plugin-crypto';
 import type {
   OpenInvitation,
   FormStrandResult,
-  StrandFormationDisclosure
+  StrandFormationDisclosure,
+  StrandMembershipInvite
 } from './types.js';
 // control-database does not import this service, so these imports introduce no cycle.
 import { generateStampId, formationConsentMessage } from './control-database.js';
@@ -199,6 +200,14 @@ export interface StrandSolicitationServiceOptions {
    * by `CadreNode`; unwired, the responder discloses no strand addresses.
    */
   resolveStrandAddrs?: (strandId: string) => string[];
+  /**
+   * Issue a single-use strand membership invitation against the live host strand a
+   * bound closed-strand redemption resolved to (responder side). Wired by `CadreNode`;
+   * see `StrandFormationManagerOptions.issueMembershipInvite` for the full contract
+   * (null = open strand, throw = reject the redemption retryably, unwired = mock/test
+   * posture: approve with no invitation).
+   */
+  issueMembershipInvite?: (strandId: string) => Promise<StrandMembershipInvite | null>;
   /** Configuration for the formation manager */
   formationConfig?: StrandFormationManagerConfig;
 }
@@ -224,6 +233,7 @@ export class StrandSolicitationService {
   private readonly partyId: string;
   private readonly cadrePeerAddrs: string[];
   private readonly resolveStrandAddrs?: (strandId: string) => string[];
+  private readonly issueMembershipInvite?: (strandId: string) => Promise<StrandMembershipInvite | null>;
   private formationManager?: StrandFormationManager;
   private readonly formationConfig?: StrandFormationManagerConfig;
   /**
@@ -247,6 +257,7 @@ export class StrandSolicitationService {
     this.partyId = options?.partyId ?? `party-${Date.now()}`;
     this.cadrePeerAddrs = options?.cadrePeerAddrs ?? [];
     this.resolveStrandAddrs = options?.resolveStrandAddrs;
+    this.issueMembershipInvite = options?.issueMembershipInvite;
     this.formationConfig = options?.formationConfig;
     log('StrandSolicitationService created for party: %s', this.partyId);
   }
@@ -265,6 +276,7 @@ export class StrandSolicitationService {
         partyId: this.partyId,
         cadrePeerAddrs: this.cadrePeerAddrs,
         resolveStrandAddrs: this.resolveStrandAddrs,
+        issueMembershipInvite: this.issueMembershipInvite,
         config: this.formationConfig
       });
     }
@@ -353,6 +365,9 @@ export class StrandSolicitationService {
         // Carry the host strand's membership key delivered over the protocol (closed-strand
         // provision-then-record). invitePrivateKey stays the initiator's generated signing key.
         memberPrivateKey: result.memberPrivateKey,
+        // The joiner's own single-use membership invitation into a closed host strand
+        // (already shape-checked by the manager); absent for open/unbound.
+        membershipInvite: result.membershipInvite,
         // The responder's live strand-network addresses, or `[]` when it had none to give.
         strandAddrs: result.strandAddrs
       };

package/src/strand-wake-protocol.ts

@@ -30,7 +30,8 @@ import type { Libp2p, Connection } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { StrandInstance, WakeRequest, WakeAck } from './types.js';
 import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
-import { type ControlStream, writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
+import { type ControlStream, writeFrame, exchangeFrame, readStreamToEnd } from './control-stream.js';
+import { tryAddrsInTurn } from './peer-dial.js';
 
 const log = debug('sereus:cadre:strand-wake');
 
@@ -60,8 +61,10 @@ const DEFAULT_WAKE_TIMEOUT_MS = 10_000;
  *
  * This makes the TARGET PEER the unit rather than the address — the same
  * decision, for the same reason, as
- * `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` in `control-cohort.ts`, and the same
- * chosen number. 20 s is deliberately wider than one attempt timeout so a
+ * `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` in `peer-dial.ts`, though not the same
+ * number: that one is sized to fit several dead addresses ahead of a working one,
+ * while a wake target is expected to be awake and reachable on its first or second
+ * address. 20 s is deliberately wider than one attempt timeout so a
  * reachable peer whose signaling address is stale still gets a genuine try at
  * its direct one; a peer needing longer than that is not "asleep and reachable",
  * which is the only case a wake is for. The last attempt inside the budget gets
@@ -271,12 +274,6 @@ export interface DialWakeOptions {
   protocolId?: string;
 }
 
-/** One candidate's outcome, kept so the thrown error can name every attempt. */
-interface WakeDialFailure {
-  addr: Multiaddr;
-  error: Error;
-}
-
 /**
  * Sender side: dial a target's control-network address(es), send a
  * {@link WakeRequest} over `WAKE_PROTOCOL`, and return the peer's {@link WakeAck}.
@@ -289,16 +286,18 @@ interface WakeDialFailure {
  * dropped.
  *
  * Throws if no address is dialable — with an error naming EVERY candidate and
- * why it failed, not merely the last one. That distinction is not cosmetic:
- * with only the last candidate's message the failure that mattered (usually the
- * signaling address, tried first) is invisible outside a debug log, and the
- * surfaced message points at whichever address happened to be tried last.
+ * why it failed, not merely the last one ({@link tryAddrsInTurn}). That
+ * distinction is not cosmetic: with only the last candidate's message the
+ * failure that mattered (usually the signaling address, tried first) is
+ * invisible outside a debug log, and the surfaced message points at whichever
+ * address happened to be tried last.
  *
  * The candidate loop is deliberately explicit rather than one
  * `dialProtocol(addrs)` call. libp2p sorts any multi-address dial with
  * `defaultAddressSorter`, whose `circuitRelayAddressesLast` pass would demote
  * exactly the signaling address this ordering puts first — silently inverting
- * it, with no per-dial sorter override to opt out of.
+ * it, with no per-dial sorter override to opt out of. For the same reason this
+ * does not use `dialPeerAddrs`, which puts relayed addresses last.
  */
 export async function dialWake(
   node: Libp2p,
@@ -310,58 +309,14 @@ export async function dialWake(
     throw new Error('No dialable address for wake target');
   }
   const protocolId = options.protocolId ?? WAKE_PROTOCOL;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS;
-  const budgetMs = options.budgetMs ?? DEFAULT_WAKE_DIAL_BUDGET_MS;
-  const deadline = Date.now() + budgetMs;
-
-  const failures: WakeDialFailure[] = [];
-  for (const addr of addrs) {
-    // Whatever is left of the whole-call budget caps this attempt, so the last
-    // candidate inside the budget still gets a real (if shortened) try.
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) {
-      failures.push({ addr, error: new Error(`not tried — the ${budgetMs}ms wake dial budget was spent on earlier addresses`) });
-      continue;
-    }
-    const attemptMs = Math.min(timeoutMs, remaining);
-    try {
-      // One deadline per attempt: its signal aborts the in-flight dialProtocol and
-      // resets the live stream, so neither the connect nor the ack-read leaks.
-      return await withDeadline(
-        attemptMs,
-        `Wake dial ${addr.toString()}`,
-        (signal) => sendWake(node, addr, protocolId, request, attemptMs, signal),
-      );
-    } catch (err) {
-      failures.push({ addr, error: err instanceof Error ? err : new Error(String(err)) });
-      log('Wake dial to %s failed: %o', addr.toString(), err);
-    }
-  }
-  throw wakeDialError(failures);
-}
-
-/**
- * Fold every candidate's failure into the one error {@link dialWake} throws.
- *
- * A single candidate throws its own error unchanged, so a one-address wake reads
- * exactly as it always has (and `rejects.toThrow(/timed out/)` still means what
- * it says). Several candidates produce one message naming each address and its
- * cause, with the FIRST failure as `cause` — the first candidate is the
- * signaling address, which is the one that matters when a relayed peer goes
- * unreachable.
- */
-function wakeDialError(failures: WakeDialFailure[]): Error {
-  if (failures.length === 0) {
-    return new Error('Wake dial failed');
-  }
-  if (failures.length === 1) {
-    return failures[0].error;
-  }
-  const detail = failures.map((f) => `${f.addr.toString()} — ${f.error.message}`).join('; ');
-  return new Error(
-    `Wake dial failed for all ${failures.length} candidate addresses: ${detail}`,
-    { cause: failures[0].error },
-  );
+  const budget = {
+    perAddressMs: options.timeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS,
+    totalMs: options.budgetMs ?? DEFAULT_WAKE_DIAL_BUDGET_MS,
+  };
+  // The attempt's signal aborts the in-flight dialProtocol and resets the live
+  // stream, so neither the connect nor the ack-read leaks.
+  return await tryAddrsInTurn(addrs, budget, 'Wake dial', (addr, signal, attemptMs) =>
+    sendWake(node, addr, protocolId, request, attemptMs, signal));
 }
 
 /**

package/src/strand-watcher.ts

@@ -244,6 +244,12 @@ export class StrandWatcher {
         }
       }
     } catch (error) {
+      // NOTE: a machine cut off from its party before it ever received the `Strand` block
+      // fails this read `cohort-unreachable` on every poll and logs here (observed in
+      // `control-cohort-edge-carries-data`). Harmless: nothing was ever launched from a block
+      // this machine never held, and this catch keeps the known set. Do not answer it as
+      // empty the way `ControlDatabase.queryRevokedStamps` does for `Revocation` — an empty
+      // answer here runs the removed-strand loop above. Revisit if the log volume matters.
       log('Error polling strands: %o', error);
     }
   }

package/src/timed-step.ts

@@ -0,0 +1,28 @@
+import debug from 'debug';
+
+const timing = debug('sereus:cadre:timing');
+
+/**
+ * Await one step of a longer operation between two `sereus:cadre:timing` lines:
+ * `[<scope>:<id>] <step>: start` before it, then `<step>: <n>ms` — or
+ * `<step>: failed after <n>ms` — once it settles. The start line is what matters on a
+ * device: a step that never settles leaves a start with no matching end, so a trace
+ * names the step that hung rather than only the last one that finished.
+ *
+ * The text is built here rather than passed as `%s`/`%d` arguments: `debug`'s browser
+ * build, which React Native bundles, leaves placeholders for the console to fill, and
+ * RN's console prints them unfilled, so a device trace would read `[%s:%s] %s: start`.
+ */
+export async function timedStep<T>(scope: string, id: string, step: string, op: () => Promise<T>): Promise<T> {
+	const label = `[${scope}:${id}] ${step}`;
+	timing(`${label}: start`);
+	const t0 = performance.now();
+	try {
+		const result = await op();
+		timing(`${label}: ${Math.round(performance.now() - t0)}ms`);
+		return result;
+	} catch (error) {
+		timing(`${label}: failed after ${Math.round(performance.now() - t0)}ms`);
+		throw error;
+	}
+}

package/src/timeout-scheduler.ts

@@ -0,0 +1,28 @@
+/**
+ * The timer seam shared by the strand bring-up loops that re-arm themselves one step at a
+ * time — the first-sync write gate's probe loop (`strand-first-sync-gate.ts`) and the
+ * membership reconciler's retry ladder (`strand-membership-reconciler.ts`). `setTimeout`
+ * rather than a repeating interval because the next step is armed only once the previous
+ * one settles, so a slow network read never stacks steps behind it, and because the delay
+ * can differ per step.
+ *
+ * Tests inject a hand-cranked clock; production omits it and gets real timers, `unref`'d so
+ * a loop that is only waiting never holds a Node process open (the call is optional —
+ * browsers and React Native return a plain handle with no `unref`).
+ */
+
+/** Timer seam for a self-rescheduling loop; omit for real (unref'd) timeouts. */
+export interface TimeoutScheduler {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+/** Real timers, `unref`'d where the runtime supports it. */
+export const defaultTimeoutScheduler: TimeoutScheduler = {
+  setTimeout: (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    (handle as { unref?: () => void }).unref?.();
+    return handle;
+  },
+  clearTimeout: (handle) => clearTimeout(handle as Parameters<typeof clearTimeout>[0])
+};