@serfab/cadre-core 1.14.0 → 1.16.0

package/src/strand-peer-redial.ts

@@ -0,0 +1,307 @@
+/**
+ * A running strand node redialing the strand's other members itself, when it holds a
+ * connection to none of them, with the dial budget the host's declared link gives a
+ * relayed connection.
+ *
+ * Why. Below cadre-core the only thing that redials a strand peer is FRET's maintenance:
+ * its pings and neighbour announcements open the connection themselves (`dial: true`) under
+ * a fixed 2 000 ms limit on the whole call (`MAINTENANCE_RPC_TIMEOUT_MS` in `p2p-fret`'s
+ * `fret-service.ts`). Opening a relayed connection takes longer than that on a slow link:
+ * about 9 s on a 20 ms per-frame cap with a 70%-busy event loop
+ * (`joiner-first-commit-over-slow-relay`, whose slow-restart arm reproduces this), where
+ * {@link relayedDialBudgetMs} allows 21.5 s at the default declaration. Each such redial is
+ * cut off part-way through the handshake, from both sides, for as long as the link stays that
+ * slow. And after a restart nothing else dials a strand peer: a cross-party strand's launch
+ * seed is empty, and cadre-core's address passes only fill the address book. Two phones that
+ * restarted then never reconnect, and a write either made alone never reaches the other.
+ *
+ * What it does. One loop per strand runtime, started in `StrandInstanceManager`'s runtime
+ * build and stopped with the runtime (stop, quiesce, failed build), so a hibernating strand
+ * never dials. Each look at the node:
+ * - a member connected: nothing to do; look again in {@link STRAND_REDIAL_CHECK_MS}, or as
+ *   soon as a peer disconnects.
+ * - no member connected and none known: likewise nothing (a founder alone, a storage replica
+ *   before anyone arrives).
+ * - no member connected and some known: dial every known member at once
+ *   ({@link dialPeerAddrs}, direct addresses before relayed ones), each address with the
+ *   relayed-dial budget. A round that connects to one goes back to watching; one that does
+ *   not waits a backoff starting at that budget and doubling to
+ *   {@link STRAND_REDIAL_MAX_BACKOFF_MS}.
+ *
+ * Who is known: every peer the node's FRET table holds a verified signed address record for
+ * (`strand-fret-addrs.ts`), plus the launch seed (sibling strand addresses and a formation's
+ * carried addresses). Who counts as connected: a peer FRET labels `'member'` (it has seen it
+ * speak this strand's protocols), or a seed peer. Neither ever includes a configured relay, a
+ * peer FRET labels `'foreign'`, or a peer the revocation gate refuses. The relay matters most:
+ * the strand node is connected to it throughout and FRET files it with a record like any
+ * peer, so counting it would leave this loop idle exactly when it is needed.
+ *
+ * NOTE: this compensates for FRET's 2 000 ms maintenance dial limit, which cannot open a
+ * relayed connection on a slow link (upstream half:
+ * `blocked/fret-maintenance-ping-dial-budget-below-a-relayed-dial`). If FRET's maintenance
+ * dial ever takes a limit derived from the declared link, this loop becomes a backstop and
+ * may be deleted, as `peer-join-backfill.ts` says of itself.
+ */
+
+import debug from 'debug';
+import type { Multiaddr } from '@multiformats/multiaddr';
+import { relayedDialBudgetMs } from './link-budget.js';
+import { CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS, SelfRelayOnlyError, dialPeerAddrs, type AddrDialer, type PeerDialBudget } from './peer-dial.js';
+import { groupAddrsByPeerId } from './peer-addr-book.js';
+import { strandFretMembership, strandFretPeerAddrs, type FretAddrHost, type FretMembership } from './strand-fret-addrs.js';
+import { defaultTimeoutScheduler, type TimeoutScheduler } from './timeout-scheduler.js';
+
+const log = debug('sereus:cadre:strand-redial');
+
+/**
+ * Gap between looks while a member is connected or none is known. While a member is
+ * connected a look reads FRET's labels and the connection list and checks no signature
+ * ({@link strandFretMembership}); a disconnect also triggers a look at once.
+ */
+export const STRAND_REDIAL_CHECK_MS = 5_000;
+
+/**
+ * Ceiling on the wait between failed rounds. A member that is gone for good is dialed this
+ * often for as long as FRET keeps its record (up to 14 days after it was last confirmed).
+ */
+export const STRAND_REDIAL_MAX_BACKOFF_MS = 5 * 60_000;
+
+/** The loop's dial budget and cadence. */
+export interface StrandRedialTimings {
+  /** Limit on one address's dial, and on one member's addresses together. */
+  budget: PeerDialBudget;
+  /** Wait after the first failed round; doubled after each further one. */
+  minBackoffMs: number;
+  /** Ceiling the backoff doubles up to. */
+  maxBackoffMs: number;
+  /** Gap between looks while nothing needs dialing. */
+  checkMs: number;
+}
+
+/**
+ * The timings at a declared link round trip: {@link relayedDialBudgetMs} per address, the
+ * same whole-budget count per member as the control cohort's dials (dead direct addresses
+ * a record lists ahead of the relayed one that works), and a first backoff of one per-address
+ * budget.
+ */
+export function strandRedialTimings(linkRoundTripMs?: number): StrandRedialTimings {
+  const perAddressMs = relayedDialBudgetMs(linkRoundTripMs);
+  return {
+    budget: { perAddressMs, totalMs: CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS * perAddressMs },
+    minBackoffMs: perAddressMs,
+    maxBackoffMs: STRAND_REDIAL_MAX_BACKOFF_MS,
+    checkMs: STRAND_REDIAL_CHECK_MS
+  };
+}
+
+/** The slice of a strand's libp2p node the loop uses. Structurally satisfied by db-p2p's node. */
+export interface RedialNode extends AddrDialer {
+  services?: FretAddrHost['services'];
+  getConnections(): ReadonlyArray<{ remotePeer: { toString(): string } }>;
+  addEventListener(type: 'peer:disconnect', listener: () => void): void;
+  removeEventListener(type: 'peer:disconnect', listener: () => void): void;
+}
+
+export interface StrandRedialDeps {
+  /** Names the strand in logs. */
+  label: string;
+  node: RedialNode;
+  /**
+   * The launch seed: multiaddr strings, each naming its peer in a trailing `/p2p/`.
+   *
+   * NOTE: read once, at runtime build. Addresses a re-formation carries while the strand runs
+   * reach the peerStore (`recordFormationStrandAddrs`) but not this loop until the runtime is
+   * rebuilt; if a re-formed strand is seen not reconnecting until relaunch, read the seed per round.
+   */
+  seed: readonly string[];
+  /** Peer ids never dialed nor counted as members: the relays the node reserves on. */
+  excluded: ReadonlySet<string>;
+  /** The revocation gate's current verdict, asked of peers and of this node itself; absent for an open strand. */
+  isRevoked?: (peerId: string) => boolean;
+  /** Omit for real (unref'd) timers. */
+  scheduler?: TimeoutScheduler;
+}
+
+/** A running redial loop; its only imperative is {@link stop}. */
+export interface StrandPeerRedial {
+  /** Idempotent. No look or round starts after it; dials in flight run out on their own deadlines, and their result is discarded. */
+  stop(): void;
+}
+
+/** How a look ended: nothing needed dialing or a round connected (`'watch'`), or a round reached no member (`'retry'`). */
+type LookOutcome = 'watch' | 'retry';
+
+/** Start the loop; its first look runs at once. */
+export function superviseStrandPeerRedial(deps: StrandRedialDeps, timings: StrandRedialTimings): StrandPeerRedial {
+  return new StrandPeerRedialLoop(deps, timings);
+}
+
+class StrandPeerRedialLoop implements StrandPeerRedial {
+  private readonly scheduler: TimeoutScheduler;
+  private readonly seed: Map<string, Multiaddr[]>;
+  private readonly selfId: string;
+  private backoffMs: number;
+  private timer: unknown = null;
+  /**
+   * Whether the pending wait is a plain gap between looks, which a disconnect cuts short. A
+   * backoff after a failed round is not cut short, or a flapping relay connection would turn
+   * the backoff into a dial on every flap; and while a look or round runs there is no wait.
+   */
+  private watching = false;
+  private stopped = false;
+  private readonly onDisconnect = (): void => {
+    if (this.watching && !this.stopped) {
+      this.cancelTimer();
+      void this.tick();
+    }
+  };
+
+  constructor(private readonly deps: StrandRedialDeps, private readonly timings: StrandRedialTimings) {
+    this.scheduler = deps.scheduler ?? defaultTimeoutScheduler;
+    this.seed = groupAddrsByPeerId([...deps.seed]);
+    this.selfId = deps.node.peerId.toString();
+    this.backoffMs = timings.minBackoffMs;
+    deps.node.addEventListener('peer:disconnect', this.onDisconnect);
+    void this.tick();
+  }
+
+  stop(): void {
+    if (this.stopped) {
+      return;
+    }
+    this.stopped = true;
+    this.cancelTimer();
+    this.deps.node.removeEventListener('peer:disconnect', this.onDisconnect);
+  }
+
+  private async tick(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    this.watching = false;
+    let outcome: LookOutcome = 'watch';
+    try {
+      outcome = await this.lookAndDial();
+    } catch (error) {
+      // A node torn down under the look throws from its table export or connection list.
+      log('strand %s: redial look failed (looking again in %dms): %o', this.deps.label, this.timings.checkMs, error);
+    }
+    if (this.stopped) {
+      return;
+    }
+    this.watching = outcome === 'watch';
+    const waitMs = outcome === 'watch' ? this.resetBackoff() : this.nextBackoff();
+    this.timer = this.scheduler.setTimeout(() => {
+      this.timer = null;
+      void this.tick();
+    }, waitMs);
+  }
+
+  /**
+   * One look, and a round of dials when it finds no member connected but some known. A node
+   * whose own party was removed dials nobody: the strand keeps running for the session, but a
+   * removed party must not keep dialing the strand's peers (`CadreNode.forgetRevokedJoin`).
+   */
+  private async lookAndDial(): Promise<LookOutcome> {
+    if (this.deps.isRevoked?.(this.selfId) === true) {
+      return 'watch';
+    }
+    const membership = strandFretMembership(this.deps.node);
+    if (this.memberConnected(membership)) {
+      return 'watch';
+    }
+    const known = await this.knownMembers(membership);
+    if (known.size === 0 || this.stopped) {
+      return 'watch';
+    }
+    log('strand %s: no member connected; dialing %d known member(s)', this.deps.label, known.size);
+    if (await this.dialAny(known)) {
+      log('strand %s: reconnected to a member', this.deps.label);
+      return 'watch';
+    }
+    log('strand %s: no known member answered; next round in %dms', this.deps.label, this.backoffMs);
+    return 'retry';
+  }
+
+  /** The gap between looks, with the backoff started over. */
+  private resetBackoff(): number {
+    this.backoffMs = this.timings.minBackoffMs;
+    return this.timings.checkMs;
+  }
+
+  /**
+   * The wait after a round that reached no member, doubling the next one up to the cap.
+   *
+   * NOTE: a round whose dials failed within milliseconds (a relay connection that is still
+   * closing, the member's relay reservation not back yet) waits as long as one whose dials ran
+   * out their budget. In `joiner-first-commit-over-slow-relay`'s third arm that first wait is what
+   * leaves the joiner writable with no member connected. If reconnecting within seconds of a cut
+   * ever matters, retry a round that failed that fast after a short delay instead.
+   *
+   * NOTE: one such fast failure is `ConnectionClosedError: The connection muxer is "closed"`. A
+   * relay that aborts its connection to this node cannot tell it so (`@libp2p/websockets`'
+   * listener resets with close code 1006, which the `ws` package refuses to send;
+   * `blocked/report-libp2p-websockets-buffered-amount`, second arm), so this node keeps a dead
+   * relay connection until its own monitor drops it, up to 65 s, and every relayed dial reuses
+   * it. If rounds keep failing that way, close a relay connection whose muxer is closed before
+   * the next round instead of waiting it out.
+   */
+  private nextBackoff(): number {
+    const waitMs = this.backoffMs;
+    this.backoffMs = Math.min(waitMs * 2, this.timings.maxBackoffMs);
+    return waitMs;
+  }
+
+  private eligible(peerId: string): boolean {
+    return peerId !== this.selfId && !this.deps.excluded.has(peerId) && this.deps.isRevoked?.(peerId) !== true;
+  }
+
+  /** Whether an open connection reaches a peer FRET has seen speak this strand's protocols, or a seed peer. */
+  private memberConnected(membership: ReadonlyMap<string, FretMembership>): boolean {
+    return this.deps.node.getConnections().some((connection) => {
+      const peerId = connection.remotePeer.toString();
+      return this.eligible(peerId) && (membership.get(peerId) === 'member' || this.seed.has(peerId));
+    });
+  }
+
+  /** The members to dial, each with its candidate addresses: verified FRET records first, then the seed's. */
+  private async knownMembers(membership: ReadonlyMap<string, FretMembership>): Promise<Map<string, Multiaddr[]>> {
+    const { peers } = await strandFretPeerAddrs(this.deps.node);
+    const known = new Map<string, Multiaddr[]>();
+    for (const [peerId, addrs] of [...peers, ...this.seed]) {
+      if (!this.eligible(peerId) || membership.get(peerId) === 'foreign') {
+        continue;
+      }
+      known.set(peerId, unionAddrs(known.get(peerId) ?? [], addrs));
+    }
+    return known;
+  }
+
+  /** Dial every member in `known` at once; resolves to whether any connected. */
+  private async dialAny(known: ReadonlyMap<string, Multiaddr[]>): Promise<boolean> {
+    const members = [...known];
+    const outcomes = await Promise.allSettled(members.map(([peerId, addrs]) =>
+      dialPeerAddrs(this.deps.node, peerId, addrs, this.timings.budget, `strand ${this.deps.label} redial of ${peerId}`)
+    ));
+    outcomes.forEach((outcome, i) => {
+      if (outcome.status === 'rejected') {
+        const reason = outcome.reason instanceof SelfRelayOnlyError ? 'reachable only by relaying through this node' : outcome.reason;
+        log('strand %s: redial of %s failed: %o', this.deps.label, members[i][0], reason);
+      }
+    });
+    return outcomes.some((outcome) => outcome.status === 'fulfilled');
+  }
+
+  private cancelTimer(): void {
+    if (this.timer !== null) {
+      this.scheduler.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/** `primary` then the entries of `extra` it lacks, compared as strings. */
+function unionAddrs(primary: readonly Multiaddr[], extra: readonly Multiaddr[]): Multiaddr[] {
+  const seen = new Set(primary.map((addr) => addr.toString()));
+  return [...primary, ...extra.filter((addr) => !seen.has(addr.toString()))];
+}

package/src/strand-wake-protocol.ts

@@ -30,7 +30,7 @@ import type { Multiaddr } from '@multiformats/multiaddr';
 import type { StrandInstance, WakeRequest, WakeAck } from './types.js';
 import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
 import { type ControlStream, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
-import { tryAddrsInTurn } from './peer-dial.js';
+import { dialAddr, tryAddrsInTurn } from './peer-dial.js';
 import { relayedRequestBudgetMs } from './link-budget.js';
 
 const log = debug('sereus:cadre:strand-wake');
@@ -356,12 +356,14 @@ export async function dialWake(
 }
 
 /**
- * Open one stream, send the request, half-close, and read the ack.
+ * Dial one address, open one stream, send the request, half-close, and read the ack.
  *
- * `signal` is the per-attempt deadline from {@link dialWake}: it goes to
- * `dialProtocol` so a timeout during connect aborts the dial, and into
- * {@link exchangeFrame} so a timeout after the stream is open resets it —
- * releasing the otherwise unbounded ack-read.
+ * The address is dialed outside libp2p's dial queue (`dialAddr`), so another dial of
+ * the target in flight cannot capture this attempt; an open connection is still reused.
+ *
+ * `signal` is the per-attempt deadline from {@link dialWake}: it goes to the dial so a
+ * timeout during connect aborts it, and into {@link exchangeFrame} so a timeout after
+ * the stream is open resets it — releasing the otherwise unbounded ack-read.
  */
 async function sendWake(
   node: Libp2p,
@@ -371,12 +373,13 @@ async function sendWake(
   timeoutMs: number,
   signal: AbortSignal,
 ): Promise<WakeAck> {
+  const connection = await dialAddr(node, addr, signal, 'Wake dial');
   // `runOnLimitedConnection: true`: the target may be reachable only over a
   // circuit-relay connection (the signaling-first addr), which libp2p marks
   // "limited". The wake exchange is a single tiny request→ack well within the
   // relay's data/duration cap, so opening it on the limited connection is safe
   // and is the whole point of dialing the relay address.
-  const rawStream = await node.dialProtocol(addr, protocolId, { runOnLimitedConnection: true, signal });
+  const rawStream = await connection.newStream(protocolId, { runOnLimitedConnection: true, signal });
 
   const ack = await exchangeFrame(
     rawStream as unknown as ControlStream,

package/src/types.ts

@@ -8,6 +8,7 @@ import type { StrandRevocationEnforcementConfig } from './strand-revocation-enfo
 import type { StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
 import type { StrandFirstSyncConfig } from './strand-first-sync-gate.js';
 import type { StrandDatabase } from './strand-database.js';
+import type { StrandCommitDurability, StrandCommitHeld } from './strand-commit-durability.js';
 import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
 import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
@@ -17,9 +18,10 @@ import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
-import type { CadreInvitation } from './cadre-invite-protocol.js';
+import type { CadreInvitation, CadreInviteAddressOutcome } from './cadre-invite-protocol.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 import type { FormationRejectionCode } from './strand-formation-rejection.js';
+import type { ListenTransportOptions } from './relay-addrs.js';
 
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
@@ -401,6 +403,20 @@ export interface NetworkConfig {
    * ```
    */
   transports?: Libp2pTransports;
+  /**
+   * Builds `@optimystic/db-p2p`'s default transport list, for the one case where cadre has to
+   * pass a list itself while {@link transports} is unset: a node with configured relays, which
+   * is built with libp2p's relay discovery switched off (`node-transports.ts`). Called with the
+   * switches the node's listen entries imply (`wsPort` when one names WebSocket). Ignored when
+   * {@link transports} is set.
+   *
+   * A Node host passes `nodeDefaultTransports` from the Node-only
+   * `@serfab/cadre-core/node-default-transports` subpath, as `cadre-cli` does. It is injected
+   * rather than built in, because that list names `@libp2p/tcp`, which must stay out of the
+   * graph React Native and browser bundles reach. Left unset, such a node is built from
+   * db-p2p's own list with relay discovery on.
+   */
+  defaultTransports?: (listen: ListenTransportOptions) => Libp2pTransports;
   /**
    * Crypto primitives for the Noise handshake and the encrypted connection that
    * follows, threaded to both the control node and every strand's cohort node — every
@@ -625,6 +641,16 @@ export interface NetworkConfig {
  * kept it (the same pair aborted at a 200ms stall only when the deadline was 300ms). An
  * interval strictly above the deadline is what makes the 30 seconds real.
  *
+ * WHY THE OTHER END'S PING HANDLER CAPS IT TOO. The node being pinged echoes through
+ * `@libp2p/ping`'s inbound handler, which aborts the ping stream when its own timer fires; the
+ * pinging node's monitor sees the reset and aborts the connection exactly as it would on its
+ * own timeout. So this deadline is only real up to the handler timeout of the node being
+ * pinged, which has to stay above it. The deployed relay sets its handler to 60 s for that
+ * reason (`ops/docker/libp2p-infra/src/main.ts`). Every cadre node's handler is Optimystic's
+ * bare `ping()`, `@libp2p/ping`'s 10 s, and nothing here can move it
+ * (`tickets/blocked/optimystic-ping-handler-timeout-below-the-monitor-deadline.md`): between
+ * two cadre nodes, a ping whose echo takes longer than 10 s still drops the connection.
+ *
  * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
  * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
  * over a relayed circuit measured 3016 ms at 1500 ms one-way). At the slowest link sereus
@@ -1642,6 +1668,24 @@ export interface CadreNodeEvents {
    * watcher auto-launched) hangs its "waiting for the other member" screen on the pair.
    */
   'strand:writable': { strandId: string };
+  /**
+   * Emitted after every commit on a strand's database that wrote something, with whether
+   * another member already holds it (`heldElsewhere`) and whether `strand:commit-held` will
+   * say when it does (`followed`). Synchronous, inside the commit, before the app's statement
+   * returns: keep handlers short. Covers every commit on the strand database, cadre-core's own
+   * membership writes included, so filter by the ids you hold — the `StampId()` a
+   * `returning StampId() as Tx` statement gave you. The same record is readable afterwards with
+   * `StrandDatabase.commitDurability(tx)`. See docs/strands.md, "A commit's durability".
+   */
+  'strand:commit-durability': StrandCommitDurability;
+  /**
+   * Emitted once when a commit reported `followed` below full replication becomes held by every
+   * member of its cohort — the moment a write made while the others were away reaches them.
+   * Synchronous, like `strand:commit-durability`, and can come right after it inside the same
+   * commit. Never emitted for a commit made before your listener attached, or one forgotten
+   * because its database closed, hibernated or the node restarted.
+   */
+  'strand:commit-held': StrandCommitHeld;
   /**
    * Emitted when this node discovers it is no longer a member of a CLOSED
    * strand — its party was removed by a manager, or it left. Detected by the
@@ -1776,6 +1820,18 @@ export interface CadreNodeEvents {
    * matching predicate for a reader that subscribed too late to see the event.
    */
   'claim:accepted': NodeClaimRecord;
+  /**
+   * Emitted once per node object when this node learns that an owner removed it from the
+   * cadre: a `CadrePeer` tombstone names its peer id, it has no live `CadrePeer` row, and a
+   * membership refresh of this process had seen its live row before. `CadreNode.removedFromCadre`
+   * is the matching query for a reader that subscribed too late.
+   *
+   * BEST-EFFORT: it fires only if the tombstone reached this node before the other machines
+   * cut it off, so a machine that was offline at removal time usually never sees it. Nothing
+   * is stopped or deleted for you; the node only stops its owner re-issue drains, which can no
+   * longer succeed. Stopping the node and deleting the cadre's data are the embedder's.
+   */
+  'cadre:removed': CadreRemoval;
 }
 
 // ============================================================================
@@ -1791,8 +1847,8 @@ export interface CadreNodeEvents {
  * PeerId by reading the record, re-verifying the self-signature against
  * `publicKey`, checking freshness, and applying a trust gate.
  *
- * The signature covers `peerId`, the comma-joined `addrs`, and `updatedAt` — see
- * `peerRecordSignedPayload`. `publicKey` is NOT inside the signed payload: it is
+ * The signature covers `peerId`, the comma-joined `addrs`, `updatedAt` and `profile` —
+ * see `peerRecordSignedPayload`. `publicKey` is NOT inside the signed payload: it is
  * the key the signature is verified *with*, and its libp2p-identity binding to
  * `peerId` is checked separately at resolve time, so re-signing it would be
  * redundant.
@@ -1806,6 +1862,12 @@ export interface PeerAddressRecord {
   addrs: string[];
   /** epoch ms — freshness; strictly increasing per peer. */
   updatedAt: number;
+  /**
+   * The publisher's own {@link CadreNodeConfig.profile}: `'transaction'` is an app (phone,
+   * browser), `'storage'` an always-on node. Null on a row the machine has not yet
+   * self-published (an owner or an invitation seated it).
+   */
+  profile: NodeProfile | null;
   /** ed25519 self-signature over the signed payload, base64url. */
   sig: string;
 }
@@ -1828,8 +1890,16 @@ export interface PeerAddressRecord {
 export interface CadrePeerRow {
   /** libp2p peer ID (base58btc) — the row key. */
   peerId: string;
+  /** ed25519 public key (base64url) stored for the peer, or null (not ed25519, or a row written before the column). */
+  publicKey: string | null;
   /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
   multiaddr: string | null;
+  /** The machine's freshness stamp (epoch ms); 0 when it has never self-published. */
+  updatedAt: number;
+  /** The machine's self-declared node profile; null until it self-publishes. */
+  profile: NodeProfile | null;
+  /** The machine's self-signature over its address record (`peerRecordSignedPayload`); null until it self-publishes. */
+  sig: string | null;
   /** Single-use anti-replay nonce the voucher signature, or the usage row, is bound to. */
   stampId: string | null;
   /** ed25519 public key (base64url) of the owner that vouched this row, or that issued the invitation that admitted it. */
@@ -1919,6 +1989,107 @@ export interface InvitationChain {
   invites: Map<string, CadreInviteRow>;
 }
 
+/**
+ * One machine of the cadre as `CadreNode.listMachines` reports it: a live `CadrePeer` row,
+ * or a live `OwnerKey` whose key derives a peer id with no `CadrePeer` row (an owner key
+ * seated for a machine not yet admitted, or a founder that never self-published).
+ *
+ * `profile` and `lastPublishedAt` are the machine's own claim only when the row's
+ * self-signature verifies; both are null otherwise, so an owner re-vouch that bumped
+ * `UpdatedAt` without re-signing, or a row the machine never published, reports nothing
+ * rather than someone else's stamp.
+ */
+export interface CadreMachine {
+  peerId: string;
+  /** ed25519 public key (base64url) behind `peerId`; null when the id is not ed25519. */
+  publicKey: string | null;
+  /** This node itself. */
+  isSelf: boolean;
+  /** `publicKey` is a live `OwnerKey` here. */
+  isOwner: boolean;
+  /** Has a live `CadrePeer` row; false for an owner key with no machine row. */
+  isMember: boolean;
+  /** Passes this node's authorized-membership predicate now (`CadreNode.listAuthorizedMembers`; always false for self, which that set excludes). */
+  trusted: boolean;
+  /** The machine's self-published node profile; null until it publishes, or when its signature does not verify. */
+  profile: NodeProfile | null;
+  /** `UpdatedAt` of its self-signed record, re-stamped while it runs; null on the same terms as `profile`. */
+  lastPublishedAt: number | null;
+  /** `CadrePeer.VouchOwner` (or `OwnerKey.VouchOwner` for an owner-only entry): the owner that vouched it, or the issuer of the invitation that admitted it. */
+  vouchedBy: string | null;
+}
+
+/** Why `CadreNode.removeMachine` refuses by name (`MachineRemovalRefusedError.code`). */
+export type MachineRemovalRefusal =
+  /** This node holds no enrolled owner key, so it cannot sign the removal. */
+  | 'not-an-owner'
+  /** The machine is this node: an owner cannot sign its own `OwnerKey` removal, so ask another owner. */
+  | 'self'
+  /** The machine holds the only live owner key here (`MinOneOwner`). */
+  | 'last-owner';
+
+/**
+ * What `CadreNode.removeMachine` would do for one machine, read without writing
+ * (`CadreNode.planMachineRemoval`), for an app's confirmation step.
+ */
+export interface MachineRemovalPlan {
+  /** The machine as listed, or null when no live row names it here (already removed). */
+  machine: CadreMachine | null;
+  refusal: MachineRemovalRefusal | null;
+  /** The machine's key is a live owner key, so the removal also retires it. */
+  removesOwnerKey: boolean;
+  /** Rows the machine's owner key vouched, which stop passing the membership predicate everywhere once it is removed unless re-vouched first. Empty unless `removesOwnerKey`. */
+  dependents: {
+    /** Live `OwnerKey` rows whose `VouchOwner` is the machine's key, this node's own excluded. */
+    owners: string[];
+    /** Live `CadrePeer` rows whose `VouchOwner` is the machine's key, the machine itself and this node excluded. */
+    peers: string[];
+  };
+  /** Live `CadreInvite` keys the machine could redeem to come back: targeted at it, or already redeemed by it with uses left. */
+  invitations: string[];
+  /** This node's own `OwnerKey` or `CadrePeer` row was vouched by the machine. It cannot re-vouch its own rows; another owner has to re-add it afterwards. */
+  ownDependency: boolean;
+}
+
+/** Options for `CadreNode.removeMachine`. */
+export interface RemoveMachineOptions {
+  /** Dependents to re-vouch under this node's key before the removal; each must appear in the plan's `dependents`. */
+  revouch?: {
+    owners?: readonly string[];
+    peers?: readonly string[];
+  };
+}
+
+/** What `CadreNode.removeMachine` wrote. All false and empty when no live row named the machine here. */
+export interface MachineRemovalResult {
+  removedPeer: boolean;
+  removedOwnerKey: boolean;
+  removedDeviceToken: boolean;
+  /** `CadreInvite` keys whose withdrawal tombstone this call filed. */
+  withdrawnInvitations: string[];
+  /** Dependents re-vouched under this node's key before the removal. */
+  revouched: {
+    owners: string[];
+    peers: string[];
+  };
+}
+
+/**
+ * This node's own removal from its cadre, as it learned it: the `CadrePeer` tombstone naming
+ * its peer id, read after it had seen its own live row (`CadreNode.removedFromCadre`, the
+ * `cadre:removed` event; "Removing a machine" in docs/architecture.md).
+ */
+export interface CadreRemoval {
+  /** The cadre this node was removed from (`CadreNode.partyId`). */
+  partyId: string;
+  /** The `StampId` the tombstone retired. */
+  stampId: string;
+  /** The owner key that filed the tombstone, when its signature verifies and the key is in this node's trusted-owner anchor; null otherwise. */
+  signerKey: string | null;
+  /** When this node learned of the removal (epoch ms). */
+  at: number;
+}
+
 /**
  * One {@link CadreInviteRow} with its standing, as `ControlDatabase.listCadreInviteStatuses`
  * (and `CadreNode.listCadreInvitations`) reports it. `live` is the redemption's own test:
@@ -2433,13 +2604,58 @@ export interface CreateCadreInvitationOptions {
   uses?: number;
 }
 
+/**
+ * Where a phone could redeem a cadre invitation from, judged on the addresses of machines
+ * other than the one that minted it — the answer to "can the new app join once this one is
+ * closed?". A minting machine that is itself always on can therefore read `issuer-only`.
+ */
+export type CadreInvitationReach =
+  /** Another machine has a relayed (`/p2p-circuit`), public-name or public-IP WebSocket address. */
+  | 'anywhere'
+  /** Other machines are named, but only at private or loopback addresses: works on their network only. */
+  | 'local-network'
+  /** The bundle names no other machine at an address a phone can dial. */
+  | 'issuer-only';
+
 /** What `CadreNode.createCadreInvitation` returns: the bundle, and the same encoded for sharing. */
 export interface CreateCadreInvitationResult {
   invitation: CadreInvitation;
-  /** `encodeCadreInvitation(invitation)`: base64url JSON for a QR code, a paste or a link. */
+  /** `encodeCadreInvitation(invitation)`: `sereus-invite:1.` and base64url JSON, for a QR code, a paste or a link. */
   encoded: string;
+  /** Whether a device could redeem it once the minting machine is gone; see {@link CadreInvitationReach}. */
+  reach: CadreInvitationReach;
 }
 
+/** How `CadreNode.redeemCadreInvitation` runs. */
+export interface RedeemCadreInvitationOptions {
+  /**
+   * Keep making passes over the bundle's addresses while every answer is retryable, until a
+   * member accepts, one refuses finally, the invitation expires, or `signal` aborts.
+   * Default false: one pass.
+   */
+  waitForMember?: boolean;
+  /** Ends the pause and the pass in flight; the call then throws the signal's reason. */
+  signal?: AbortSignal;
+  /** Called at each pass and each pause; an exception it throws is logged and ignored. */
+  onProgress?: (progress: CadreJoinProgress) => void;
+}
+
+/** A redemption's progress, as `RedeemCadreInvitationOptions.onProgress` reports it. */
+export type CadreJoinProgress =
+  | { state: 'redeeming'; pass: number }
+  | {
+      state: 'waiting';
+      pass: number;
+      /** Epoch ms of the next pass. */
+      retryAtMs: number;
+      /**
+       * `'no-member-answered'`: every address failed to dial or answer. `'member-not-ready'`: at
+       * least one member answered with a retryable refusal (issuer-unknown, busy, conflict, internal).
+       */
+      reason: 'no-member-answered' | 'member-not-ready';
+      outcomes: readonly CadreInviteAddressOutcome[];
+    };
+
 /** What `CadreNode.redeemCadreInvitation` returns once a member accepted. */
 export interface RedeemCadreInvitationResult {
   /** The member machine that admitted this device, when its address named one. */