@serfab/cadre-core 1.8.0 → 1.10.0

package/src/strand-network-state.ts

@@ -0,0 +1,243 @@
+/**
+ * Node-local, NON-replicated **strand network state**: for each strand this node
+ * runs, the last network state Optimystic's db-p2p saved for that strand's libp2p
+ * node — its FRET routing table (each peer entry carrying the peer's signed libp2p
+ * address record), the network-size high-water mark, and which of those peers were
+ * seen serving the strand. db-p2p reads it back once when the strand node is built
+ * and re-imports the table, which hands every record to the libp2p peerStore, so a
+ * restarted strand node already has addresses for the peers it was talking to
+ * (gotchoices/sereus#18).
+ *
+ * The payload is opaque here. db-p2p owns its version fence (a snapshot whose
+ * `version` it does not write is discarded whole) and FRET owns table validation
+ * (a structurally corrupt table is refused, a stale record dropped). This module
+ * checks only that an entry is a plain object with a numeric `version`, and never
+ * rewrites one.
+ *
+ * Three implementations mirroring `bootstrap-peer-store.ts` (same "must outlive the
+ * process, storage differs per platform" problem; both persistent forms share
+ * `node-local-snapshot.ts`):
+ *  - {@link MemoryStrandNetworkStateStore} (this module, cross-platform) — ephemeral;
+ *    the default when no store is injected via `CadreNodeConfig.strandNetworkState`.
+ *    A node using it restarts with an empty routing table.
+ *  - {@link PersistentStrandNetworkStateStore} (this module, cross-platform) —
+ *    durable over any `DurableSlot` the embedding app supplies.
+ *  - `FileStrandNetworkStateStore` — the above over a Node file in the node's state
+ *    directory; Node-only, behind the subpath
+ *    `@serfab/cadre-core/strand-network-state-file` so `node:fs` never lands in the
+ *    RN/browser graph.
+ *
+ * One store per NODE holding every strand, keyed by strand id, so the embedder
+ * wires one slot, like the other node-local stores.
+ *
+ * **Nothing here is trust-bearing.** A routing-table entry grants no authority:
+ * every address record is signed by the peer it names and verified by FRET at
+ * import, and the dialed peer authenticates by peer id at the handshake.
+ */
+import debug from 'debug';
+import type { NetworkStatePersistence, PersistedNetworkState } from '@optimystic/db-p2p';
+import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:strand-network-state');
+
+export interface StrandNetworkStateStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/**
+	 * The last state saved for `strandId`, or undefined. Synchronous: served from the
+	 * in-memory half of the store. The returned object is the stored one — callers
+	 * must not mutate it.
+	 */
+	load(strandId: string): PersistedNetworkState | undefined;
+
+	/**
+	 * Replace the strand's state. Implementations MUST reflect it in {@link load}
+	 * SYNCHRONOUSLY; the returned promise tracks durability only. The store keeps
+	 * `state` itself, so the caller must not mutate it afterwards (db-p2p builds a
+	 * fresh object per save).
+	 */
+	save(strandId: string, state: PersistedNetworkState): Promise<void>;
+
+	/**
+	 * Drop the strand's state — for a strand this node unpublished or left, whose
+	 * peers must not be re-imported by a later launch. A no-op for the stored state
+	 * when nothing is held, but {@link forgetGeneration} advances either way. Same
+	 * contract as {@link save}: reflected synchronously, the promise tracks durability.
+	 */
+	forget(strandId: string): Promise<void>;
+
+	/**
+	 * How many times `strandId` has been forgotten through this store instance.
+	 * {@link strandNetworkStatePersistence} compares it against the value it captured
+	 * to drop a save that arrives after the forget.
+	 */
+	forgetGeneration(strandId: string): number;
+}
+
+/** Per-strand forget counts; the in-process half of {@link StrandNetworkStateStore.forgetGeneration}. */
+class ForgetGenerations {
+	private readonly counts = new Map<string, number>();
+
+	of(strandId: string): number {
+		return this.counts.get(strandId) ?? 0;
+	}
+
+	advance(strandId: string): void {
+		this.counts.set(strandId, this.of(strandId) + 1);
+	}
+}
+
+/**
+ * Ephemeral in-memory store for nodes without durable storage (tests, and the
+ * default when nothing is injected). Same contract, no disk: a strand relaunched in
+ * the same process re-imports its table (a hibernation resume, a stop()→start()),
+ * and a restarted process starts with none.
+ */
+export class MemoryStrandNetworkStateStore implements StrandNetworkStateStore {
+	private readonly strands = new Map<string, PersistedNetworkState>();
+	private readonly generations = new ForgetGenerations();
+
+	constructor(readonly partyId: string) {}
+
+	load(strandId: string): PersistedNetworkState | undefined {
+		return this.strands.get(strandId);
+	}
+
+	async save(strandId: string, state: PersistedNetworkState): Promise<void> {
+		this.strands.set(strandId, state);
+	}
+
+	async forget(strandId: string): Promise<void> {
+		this.generations.advance(strandId);
+		if (this.strands.delete(strandId)) {
+			log('strand %s: network state forgotten (party=%s)', strandId, this.partyId);
+		}
+	}
+
+	forgetGeneration(strandId: string): number {
+		return this.generations.of(strandId);
+	}
+}
+
+/**
+ * What the store persists: `strands` maps strandId -> the state db-p2p saved. An
+ * entry that is not a plain object with a numeric `version` is dropped and its
+ * siblings kept (`drop-entry`): nothing here is trust-bearing, and one damaged
+ * strand must not cost every other strand its routing table. Everything past that
+ * structural check is db-p2p's and FRET's to judge at import.
+ */
+const STRAND_NETWORK_STATE_SNAPSHOT_SPEC: NodeLocalSnapshotSpec<PersistedNetworkState> = {
+	label: 'strand network state',
+	payloadKey: 'strands',
+	unusableEntry: 'drop-entry',
+	acceptEntry: (_strandId, raw) => {
+		if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined;
+		if (typeof (raw as { version?: unknown }).version !== 'number') return undefined;
+		return raw as PersistedNetworkState;
+	}
+};
+
+/**
+ * Durable {@link StrandNetworkStateStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileStrandNetworkStateStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load and persist policy — what an absent, corrupt,
+ * foreign-party or unreadable slot does (the last one THROWS), and what a failed
+ * persist does — is documented once on `NodeLocalSnapshot`. Writes are serialised
+ * in-process by the snapshot's write chain, so several strand nodes saving at once
+ * cannot interleave partial snapshots.
+ *
+ * NOTE: an entry leaves only through {@link forget}, and nothing ages one out. A
+ * strand this machine detached because the strand watcher saw its control row gone
+ * (another machine of the party unpublished or left it), or one stopped and never
+ * relaunched, keeps its entry and it is rewritten with every save. The watcher path
+ * (`CadreNode.handleStrandRemoved`) does not forget because its removal is not proof
+ * the strand is gone: its query answers an empty list while the control database is
+ * absent. If snapshots grow on machines that host many short-lived strands, or a
+ * re-published strand id is seen importing its predecessor's table, drop entries at
+ * {@link open} that are older than FRET's own 14-day record age.
+ */
+export class PersistentStrandNetworkStateStore implements StrandNetworkStateStore {
+	private readonly generations = new ForgetGenerations();
+
+	private constructor(private readonly snapshot: NodeLocalSnapshot<PersistedNetworkState>) {}
+
+	/** Load (or cold-start) the party's strand network state from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentStrandNetworkStateStore> {
+		return new PersistentStrandNetworkStateStore(
+			await NodeLocalSnapshot.open(slot, partyId, STRAND_NETWORK_STATE_SNAPSHOT_SPEC)
+		);
+	}
+
+	get partyId(): string {
+		return this.snapshot.partyId;
+	}
+
+	load(strandId: string): PersistedNetworkState | undefined {
+		return this.snapshot.get(strandId);
+	}
+
+	/**
+	 * Replace, visible via {@link load} synchronously, then the full snapshot is persisted.
+	 *
+	 * NOTE: every save rewrites the party's whole snapshot — every strand's table —
+	 * and db-p2p saves on every `connection:open`. Fine for a handful of strands; if
+	 * slot writes show up in profiles, move to one slot per strand or coalesce saves.
+	 */
+	save(strandId: string, state: PersistedNetworkState): Promise<void> {
+		return this.snapshot.put(strandId, state);
+	}
+
+	/** Forget, gone from {@link load} synchronously, then persisted — unless nothing was there. */
+	forget(strandId: string): Promise<void> {
+		this.generations.advance(strandId);
+		if (this.snapshot.has(strandId)) {
+			log('strand %s: network state forgotten (party=%s); persisting', strandId, this.partyId);
+		}
+		return this.snapshot.remove(strandId);
+	}
+
+	forgetGeneration(strandId: string): number {
+		return this.generations.of(strandId);
+	}
+}
+
+/**
+ * Adapts one strand's slice of the store to db-p2p's `NodeOptions.persistence`.
+ * Build one per strand runtime (`StrandInstanceManager.buildStrandRuntime` does).
+ *
+ * A save is dropped once the strand has been forgotten after this adapter was
+ * built: db-p2p saves fire-and-forget on connection events, so a node being torn
+ * down can still save after `forget(strandId)`, which would put the entry back.
+ * Saving resumes with the next runtime built for the strand (a relaunch or a
+ * hibernation resume), which builds a new adapter.
+ *
+ * NOTE: a strand that keeps running after its state was forgotten (self-revocation
+ * forgets but stops nothing) saves nothing more until its runtime is rebuilt. If a
+ * removed party is routinely re-admitted without a relaunch, re-arm saving at
+ * re-admission.
+ *
+ * NOTE: db-p2p saves on `connection:open` and on a changed serving verdict, not when
+ * a peer's addresses change. A peer whose address rotates during a long connection
+ * (a relay reservation moving) is saved with its old record until the next save,
+ * which matters only to a restart in between. If restarts are seen dialing rotated
+ * addresses, the fix is upstream: db-p2p saving when FRET's table changes.
+ */
+export function strandNetworkStatePersistence(
+	store: StrandNetworkStateStore,
+	strandId: string
+): NetworkStatePersistence {
+	const generation = store.forgetGeneration(strandId);
+	return {
+		load: async () => store.load(strandId),
+		save: async (state) => {
+			if (store.forgetGeneration(strandId) !== generation) {
+				log('strand %s: dropping a network-state save that arrived after the strand was forgotten', strandId);
+				return;
+			}
+			await store.save(strandId, state);
+		}
+	};
+}

package/src/strand-solicitation.ts

@@ -16,6 +16,7 @@ import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
 import { mintPlaceholderStrandId } from './strand-id.js';
 import {
   StrandFormationManager,
+  type CadrePeerAddrsSource,
   type MembershipInviteIssuer,
   type StrandFormationManagerConfig
 } from './strand-formation-manager.js';
@@ -110,9 +111,11 @@ export interface FormationUsageRecorder {
   isTokenUsed(token: string): Promise<boolean>;
 
   /**
-   * Check if a token is valid and not expired
+   * Check if a token is valid and not expired. An invalid answer says why: `'unknown'` (no
+   * invitation row here — it may not have replicated yet) or `'expired'`. An answer without
+   * a reason is treated as `'unknown'`, the retryable one.
    */
-  isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }>;
+  isTokenValid(token: string): Promise<{ valid: boolean; reason?: 'unknown' | 'expired'; invitation?: OpenInvitation }>;
 
   /**
    * Resolve the host strand an invite binds to, classifying it as unbound / bound /
@@ -213,7 +216,7 @@ export interface StrandSolicitationServiceOptions {
   /** Party ID for this node (used in protocol messages) */
   partyId?: string;
   /** Cadre peer addresses for this node */
-  cadrePeerAddrs?: string[];
+  cadrePeerAddrs?: CadrePeerAddrsSource;
   /**
    * This node's live STRAND-network multiaddrs for a strand it is running (responder
    * side), carried back to a validated joiner as its cross-party discovery seed. Wired
@@ -251,7 +254,7 @@ export class StrandSolicitationService {
   private readonly strandProvisioner?: StrandProvisioner;
   private readonly formationResponseValidator?: FormationResponseValidator;
   private readonly partyId: string;
-  private readonly cadrePeerAddrs: string[];
+  private readonly cadrePeerAddrs: CadrePeerAddrsSource;
   private readonly resolveStrandAddrs?: (strandId: string) => string[];
   private readonly issueMembershipInvite?: MembershipInviteIssuer;
   private formationManager?: StrandFormationManager;
@@ -446,6 +449,16 @@ export class StrandSolicitationService {
     log('Registered minted invitation %s (expires %d)', token, expiresAtMs);
   }
 
+  /**
+   * Take over every token `previous` minted or published, so a service that replaces it
+   * on a node keeps the connection gate open for invitations already handed out.
+   */
+  adoptMintedInvitations(previous: StrandSolicitationService): void {
+    for (const [token, expiresAtMs] of previous.mintedInvitations) {
+      this.mintedInvitations.set(token, expiresAtMs);
+    }
+  }
+
   /**
    * Does this node currently expect a stranger — i.e. is at least one open
    * invitation unexpired and not yet fully consumed? Sole input to the

package/src/types.ts

@@ -11,12 +11,13 @@ 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';
 import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
-import type { StrandPeerBookStore } from './strand-peer-book.js';
+import type { StrandNetworkStateStore } from './strand-network-state.js';
 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 { RevocableTable } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
+import type { FormationRejectionCode } from './strand-formation-rejection.js';
 
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
@@ -478,8 +479,9 @@ export interface NetworkConfig {
    * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
    * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
    * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
-   * its request dials and responses, its block pushes, and libp2p's `dialTimeout` and
-   * `inboundUpgradeTimeout` on every node. Reaching another machine through a
+   * its request dials and responses, its block pushes, and libp2p's `addressDialTimeout`,
+   * `dialTimeout` and `inboundUpgradeTimeout` on every node, cadre adding its admission decisions
+   * to the three that open a connection. Reaching another machine through a
    * relay costs a fixed number of exchanges, so a deadline written as milliseconds has a link
    * speed above which it can never open a connection — which is the defect this declaration
    * exists to make impossible to reintroduce one budget at a time. The counts, the measurement behind them,
@@ -496,8 +498,12 @@ export interface NetworkConfig {
    * Refused where the libp2p node is built — inside `CadreNode.start()` for the control
    * network, inside `CadreNode.addStrand` for a strand — if it is not a finite number above
    * zero, because every consumer multiplies it into a deadline where a zero means "give up at
-   * once" and a `NaN` means "never". Optimystic refuses, in the same place, a value above its
-   * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
+   * once" and a `NaN` means "never". A value above about 10.8 hours is refused in the same place,
+   * by Optimystic: the request dial cadre states from it (eleven round trips plus two admission
+   * decisions, `optimysticDialLimits` in `link-budget.ts`) then exceeds its
+   * `MAX_RPC_DIAL_TIMEOUT_MS` (about 4.97 days), and its error names `rpcDeadlines.dialTimeoutMs`.
+   * That is below Optimystic's own `MAX_LINK_ROUND_TRIP_MS` (about 13.3 hours) and far above any
+   * real link, so cadre adds no check of its own.
    */
   linkRoundTripMs?: number;
   /**
@@ -569,8 +575,8 @@ export interface NetworkConfig {
      * so an address that never answers cannot use up the time the peer's other
      * addresses needed. Defaults to
      * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
-     * here replaces that whole derived budget, including its allowance for the
-     * called machine's admission decision (`relayedDialBudgetMs`).
+     * here replaces that whole derived budget, including its allowances for the
+     * relay's and the called machine's admission decisions (`relayedDialBudgetMs`).
      */
     perAddressDialTimeoutMs?: number;
     /**
@@ -631,15 +637,11 @@ export interface NetworkConfig {
  *
  * WHY THE DEADLINE IS PINNED rather than given room to adapt. `pingTimeout` is an
  * adaptive-timeout init, and equal `minTimeout`/`maxTimeout` clamp it to one value on
- * every libp2p version. Under libp2p 3.1.3, which sereus resolves today, it is already
- * flat at `minTimeout`: `ConnectionMonitor` asks its `AdaptiveTimeout` for a deadline but
- * never calls `cleanUp` to report how long the ping took, so the moving average the
- * deadline derives from stays at zero. libp2p 3.3 does report ping durations back, and a
- * ceiling above `pingInterval` would then let the deadline grow past the interval and put
- * the overlapping-ping abort above straight back. Pinning both ends keeps the interval's
- * margin true on the version bump instead of making it something to remember. It also
- * sidesteps 3.3's other surprise: the monitor keeps one `AdaptiveTimeout` for all of a
- * node's connections, so one slow peer would otherwise lengthen the deadline for every
+ * every libp2p version. libp2p 3.3 reports each ping's duration back to the monitor's
+ * `AdaptiveTimeout`, so a ceiling above `pingInterval` would let the deadline grow past the
+ * interval and put the overlapping-ping abort above straight back. Pinning both ends keeps
+ * the interval's margin true. It also sidesteps the monitor keeping one `AdaptiveTimeout`
+ * for all of a node's connections, so one slow peer cannot lengthen the deadline for every
  * connection on that node.
  */
 export const DEFAULT_CONNECTION_MONITOR = Object.freeze({
@@ -1030,32 +1032,29 @@ export interface CadreNodeConfig {
   };
 
   /**
-   * Node-local strand peer book (see `strand-peer-book.ts`): per strand, the strand
-   * peers this node has met — the other parties' strand transport peers a formation
-   * carried back, and every strand peer observed on a live connection — with their
-   * last-known addresses. Read on every launch, hibernation resume and periodic
-   * address refresh, so a restarted machine dials the peers it was talking to before
-   * anything else, instead of coming back up alone (gotchoices/sereus#18). Sibling
-   * of {@link bootstrapPeers} — same NON-replicated, per-party, injected-backend
-   * shape — and, like it, nothing here is trust-bearing: dial hints only, each
-   * bound to its peer id. Entries age out after 14 days (`STRAND_PEER_MAX_AGE_MS`,
-   * overridable per store via `StrandPeerBookOptions.maxAgeMs`).
-   *
-   * Absent ⇒ an in-memory store is created at start() (ephemeral: the book dies
-   * with the process, and a cross-party strand whose only contact was the other
-   * party does not re-mesh after a restart until a fresh formation). Every
-   * reference embedder injects a durable backend over the same slot kind as its
-   * bootstrap-peer store. A new platform needs no new store class: supply a
-   * `DurableSlot` and inject `PersistentStrandPeerBookStore.open(slot, partyId)`.
-   */
-  strandPeers?: {
+   * Node-local strand network state (see `strand-network-state.ts`): per strand, the
+   * state Optimystic's db-p2p saves for the strand's libp2p node — its FRET routing
+   * table, each entry carrying the peer's signed address record. A strand node reads
+   * it back when it is built and re-imports the table, so a restarted machine already
+   * holds addresses for the strand peers it was talking to (gotchoices/sereus#18).
+   * Sibling of {@link bootstrapPeers} — same NON-replicated, per-party,
+   * injected-backend shape — and, like it, nothing here is trust-bearing: FRET
+   * verifies every record at import.
+   *
+   * Absent ⇒ an in-memory store is created at start() (ephemeral: a restarted process
+   * starts every strand with an empty routing table). Every reference embedder
+   * injects a durable backend over the same slot kind as its bootstrap-peer store. A
+   * new platform needs no new store class: supply a `DurableSlot` and inject
+   * `PersistentStrandNetworkStateStore.open(slot, partyId)`.
+   */
+  strandNetworkState?: {
     /**
-     * Injected store instance — e.g. a `FileStrandPeerBookStore` from the
-     * Node-only subpath `@serfab/cadre-core/strand-peer-book-file`, persisted in
+     * Injected store instance — e.g. a `FileStrandNetworkStateStore` from the
+     * Node-only subpath `@serfab/cadre-core/strand-network-state-file`, persisted in
      * the node's state directory. Its `partyId` must match
      * `controlNetwork.partyId`; start() fails closed on a mismatch.
      */
-    store?: StrandPeerBookStore;
+    store?: StrandNetworkStateStore;
   };
 
   /**
@@ -1201,6 +1200,69 @@ export interface StrandRow {
   FounderOwnerKey: string | null;
 }
 
+/**
+ * A `CadreControl.PendingJoin` row: a join this party asked for through another party's
+ * invitation, readable by every machine of the party. Each outcome carries only its own
+ * columns (the schema's `OutcomeShape` check): `'joined'` sets `StrandId` (and, for a
+ * closed strand, `MembershipInvite`), `'failed'` sets `FailureCode`, and a pending row
+ * (`Outcome: null`) sets neither.
+ */
+export interface PendingJoinRow {
+  /** base64url sha256 of the invitation token (`pendingJoinId`). */
+  Id: string;
+  /** `CadreNode.encodeInvitation` of the invitation. A bearer credential. */
+  Invitation: string;
+  /** `canonicalJson` of the disclosure the requester gave. */
+  Disclosure: string;
+  /** Epoch ms. */
+  RequestedAt: number;
+  /** Epoch ms; no attempt starts at or after it. */
+  ExpiresAt: number;
+  Outcome: null | 'joined' | 'failed';
+  /** Epoch ms the outcome was recorded; null while pending. */
+  OutcomeAt: number | null;
+  /** `'joined'`: the strand the formation returned. */
+  StrandId: string | null;
+  /** `'joined'`, closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
+  MembershipInvite: string | null;
+  /** `'failed'`: a `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
+  FailureCode: string | null;
+  /** `'failed'`: human-readable text. */
+  FailureReason: string | null;
+  /** Single-use nonce of this row incarnation; `ControlDatabase.replacePendingJoin` names it as the row it replaces. */
+  StampId: string;
+}
+
+/**
+ * A join this party asked for through `CadreNode.requestJoin`, as one machine sees it.
+ *
+ * `pending`, `joined` and `failed` come from the party-wide `PendingJoin` row and read the same
+ * on every machine. `trying` (an attempt is running on this machine) and `waiting` (this
+ * machine's last attempt failed in a way worth retrying) are this machine's own view of a
+ * pending row, so two machines can report different states for it.
+ */
+export interface PendingJoinStatus {
+  /** `PendingJoin.Id`: the sha256 of the invitation token. */
+  id: string;
+  sAppId: string;
+  /** Epoch ms. */
+  requestedAt: number;
+  /** Epoch ms; no attempt starts at or after it. */
+  expiresAt: number;
+  state: 'pending' | 'trying' | 'waiting' | 'joined' | 'failed';
+  /** `'waiting'`: when this machine tries again, epoch ms. */
+  nextAttemptAt?: number;
+  /**
+   * `'waiting'`: why this machine's last attempt failed. `'unreachable'` means no answer came
+   * back; `'local'` means the attempt failed on this machine before an answer.
+   */
+  lastError?: { code: FormationRejectionCode | 'unrecognized' | 'unreachable' | 'local'; reason: string };
+  /** `'joined'`: the strand the join produced. */
+  strandId?: string;
+  /** `'failed'`: a `FormationRejectionCode`, `'expired'`, or `'local'` (approved, then a step on the joining machine failed). */
+  failure?: { code: string; reason: string };
+}
+
 /**
  * sApp configuration provided by the hosting application when creating a strand.
  * This is what the app developer provides - NOT loaded from the network.
@@ -1377,7 +1439,13 @@ export interface OpenInvitation {
   sAppId: string;
   /** When this invitation expires */
   expiration: Date;
-  /** Bootstrap addresses to contact the inviter's cadre */
+  /**
+   * Addresses of the inviting party's machines, each ending in `/p2p/<peerId>`: the minting
+   * machine's own first, then up to three of its siblings with up to four addresses each
+   * (`CadreNode.createOpenInvitation`). A joiner tries the machines in order, one formation
+   * session each, so an entry may be dead by the time it is used; one that names no machine
+   * is ignored.
+   */
   bootstrap: string[];
 }
 
@@ -1397,7 +1465,11 @@ export interface StrandMembershipInvite {
    * The invite ed25519 PRIVATE seed (base64url). A single-use bearer credential:
    * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
    * handling as `memberPrivateKey` — delivered only inside the validated,
-   * post-approval formation result, never written to either side's control DB.
+   * post-approval formation result. The inviting side never writes it to its control
+   * DB. The joining side may copy it into its own `PendingJoin` row
+   * (`MembershipInvite`), owner-signed and party-private like
+   * `JoinedStrand.MemberPrivateKey`, so a join finished on one machine of the party
+   * can be seated by whichever machine launches the strand first.
    */
   invitePrivateKey: string;
 }
@@ -1604,6 +1676,13 @@ export interface CadreNodeEvents {
    * or connection state change.
    */
   'control:write-abandoned': ControlRetryAbandonment;
+  /**
+   * Emitted when this machine's view of a join asked for with `CadreNode.requestJoin` changes:
+   * its own attempt started or ended, or a pass read an outcome another owner machine wrote.
+   * Owner machines only, since only they run the retry loop. A dismissed join emits nothing
+   * further; `listPendingJoins` no longer names it.
+   */
+  'pendingJoin:changed': PendingJoinStatus;
   /** Emitted when a seed is received via the seed protocol */
   'seed:received': { partyId: string; peerId: string };
   /** Emitted when a seed is successfully applied */

package/dist/strand-peer-book-file.d.ts

@@ -1,12 +0,0 @@
-import type { StrandPeerBookOptions, StrandPeerBookStore } from './strand-peer-book.js';
-/**
- * File-backed {@link StrandPeerBookStore}. Open via {@link open}, which loads the
- * existing file and returns the cross-platform store over it; an absent, corrupt,
- * or wrong-party file is a cold start (empty book) and structurally junk or
- * aged-out entries are dropped, while a present-but-unreadable file throws. Those
- * rules and their reasoning live on `NodeLocalSnapshot.open`.
- */
-export declare const FileStrandPeerBookStore: {
-    /** Load (or cold-start) the party's strand peer book from a file in `dir`. */
-    open(dir: string, partyId: string, options?: StrandPeerBookOptions): Promise<StrandPeerBookStore>;
-};

package/dist/strand-peer-book-file.js

@@ -1,37 +0,0 @@
-/**
- * Node-only file-backed {@link StrandPeerBookStore}: one JSON file per party under
- * a configured directory (the node's state directory — `cadre-cli` passes
- * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated strand
- * peer book (the strand peers this node has met, with their last-known addresses).
- *
- * Nothing but the file itself lives here: the envelope, load policy, per-entry
- * validation, the merge rule and the serialised snapshot writes are cross-platform
- * in `PersistentStrandPeerBookStore` / `node-local-snapshot.ts`, and the file is a
- * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of the
- * package's cross-platform default entry (`./index.js`) — import it from the
- * dedicated subpath instead:
- *
- * ```ts
- * import { FileStrandPeerBookStore } from '@serfab/cadre-core/strand-peer-book-file';
- * ```
- *
- * Same isolation pattern as `bootstrap-peer-store-file.ts` / `key-store-file.ts`.
- */
-import { FileDurableSlot } from './file-durable-slot.js';
-import { PersistentStrandPeerBookStore } from './strand-peer-book.js';
-/** Base name of the store file: `<dir>/strand-peers.<encoded partyId>.json`. */
-const SLOT_NAME = 'strand-peers';
-/**
- * File-backed {@link StrandPeerBookStore}. Open via {@link open}, which loads the
- * existing file and returns the cross-platform store over it; an absent, corrupt,
- * or wrong-party file is a cold start (empty book) and structurally junk or
- * aged-out entries are dropped, while a present-but-unreadable file throws. Those
- * rules and their reasoning live on `NodeLocalSnapshot.open`.
- */
-export const FileStrandPeerBookStore = {
-    /** Load (or cold-start) the party's strand peer book from a file in `dir`. */
-    async open(dir, partyId, options) {
-        return PersistentStrandPeerBookStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId, options);
-    }
-};
-//# sourceMappingURL=strand-peer-book-file.js.map

package/dist/strand-peer-book-file.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"strand-peer-book-file.js","sourceRoot":"","sources":["../src/strand-peer-book-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAGtE,gFAAgF;AAChF,MAAM,SAAS,GAAG,cAAc,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAe,EAAE,OAA+B;QACvE,OAAO,6BAA6B,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3G,CAAC;CACD,CAAC"}