@serfab/cadre-core 0.13.0 → 1.0.0

package/src/strand-instance-manager.ts

@@ -10,7 +10,21 @@ import {
   readStrandRevocationRows,
   type StrandRevocationEnforcementConfig
 } from './strand-revocation-enforcer.js';
+import {
+  StrandMembershipReconciler,
+  type PendingMembershipInviteSource,
+  type StrandMembershipReconciliationConfig
+} from './strand-membership-reconciler.js';
+import { removeMemberPeer } from './strand-membership-writer.js';
+import { strandMemberKeyPair } from './strand-member-key.js';
 import { assertSchemaSignature } from './schema-verification.js';
+import {
+  StrandFirstSyncGate,
+  StrandAwaitingFirstSyncError,
+  strandFirstSyncComplete,
+  DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS,
+  type StrandFirstSyncConfig
+} from './strand-first-sync-gate.js';
 import type {
   StrandInstance,
   StrandRow,
@@ -25,10 +39,46 @@ import type {
 } from './types.js';
 import { resolveStrandClusterSize, strandClusterPolicy } from './types.js';
 import { strandNodeAddrs } from './strand-network-config.js';
+import { superviseRelayReservation, type RelayReservationSupervisor } from './relay-reservation.js';
 
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
 
+/** One caller blocked in {@link StrandInstanceManager.whenWritable}. */
+interface WritableWaiter {
+  resolve: () => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Whether a tracked instance is launched but waiting for its first sync: the runtime is
+ * up (`libp2pNode` set) while the database is still withheld (`database` unset). That
+ * is the first-sync gate's state regardless of what `status` says — the hibernation
+ * manager's idle timer can flip a long-gated joiner to `'idle'` without changing it.
+ *
+ * NOTE: `status` is therefore not the source of truth for "gated": a joiner that reaches
+ * nobody for `idleTimeout` (5 min at the interactive hint) reads `'idle'`, then
+ * `'hibernating'`, while still holding no database. Harmless today — every decision the
+ * runtime makes goes through this predicate, {@link StrandInstanceManager.publishDatabase}
+ * announces on the idle-flipped instance exactly as on a `'syncing'` one, and an app that
+ * shows "waiting for the other member" on `'syncing'` merely sees "idle" instead after
+ * five minutes. If an app ever needs the gated LABEL to survive the idle flip, make the
+ * hibernation manager's idle transition preserve `'syncing'` rather than adding a flag.
+ */
+export function isAwaitingFirstSync(instance: StrandInstance): boolean {
+  return instance.libp2pNode !== undefined && instance.database === undefined;
+}
+
+/**
+ * The status a LIVE instance (runtime rebuilt or woken) should report: `'active'` once its
+ * database is published, `'syncing'` while the first-sync gate still withholds it. Every
+ * site that would otherwise write `'active'` after a build or a wake goes through this,
+ * so a gated joiner never reads as writable.
+ */
+export function liveStrandStatus(instance: StrandInstance): 'active' | 'syncing' {
+  return instance.database ? 'active' : 'syncing';
+}
+
 /**
  * Configuration for starting a strand instance
  */
@@ -60,6 +110,17 @@ export interface StartStrandConfig {
    * never through a repeat `startStrand`.
    */
   founder?: boolean;
+  /**
+   * THIS party's own strand membership private key (base64 protobuf) for a closed
+   * strand — the identity the founder bootstrap derives `Member.Key` /
+   * `Manager.MemberKey` from. Resolved by the caller (`CadreNode.launchStrand`: an
+   * explicit attach-time key, else the control-layer `StrandPartyKey` row, healed by
+   * mint-on-launch for the founding machine) and retained with the launch config, so a
+   * hibernation wake rebuilds under the same identity. Deliberately NOT the strand
+   * row's shared `MemberPrivateKey` (see `StrandDatabaseConfig.partyMemberPrivateKey`).
+   * Absent for open strands, and for joiners with no persisted party key.
+   */
+  partyMemberPrivateKey?: string;
   /**
    * Number of nodes Optimystic is told this strand's replication cluster should
    * have. Same rule as {@link CadreNodeConfig.strandClusterSize}, which CadreNode
@@ -119,6 +180,28 @@ export interface StartStrandConfig {
    */
   revocationEnforcement?: StrandRevocationEnforcementConfig;
 
+  /**
+   * The staged formation membership invitation for THIS strand — the seam the
+   * bring-up membership reconciler (`strand-membership-reconciler.ts`) reads to
+   * redeem the party's `Strand.Member` seat, and clears once the invitation is
+   * spent, burned, or dead. `CadreNode.launchStrand` wires it over its in-memory
+   * `pendingMembershipInvites` map; read lazily per pass, so a re-formation that
+   * replaces the entry between passes is picked up. Only consulted for closed
+   * strands launched with a {@link partyMemberPrivateKey}; harmless otherwise.
+   */
+  pendingMembershipInvite?: PendingMembershipInviteSource;
+
+  /**
+   * Tuning for the CLOSED-strand membership reconciler, forwarded from
+   * {@link CadreNodeConfig.strandMembershipReconciliation}. Armed only for
+   * closed strands launched with a {@link partyMemberPrivateKey};
+   * `{ enabled: false }` disarms the loop (test fixtures that hand-drive the
+   * membership writers). When it names no `pollIntervalMs` the reconciler
+   * mirrors {@link revocationEnforcement}'s cadence — as its IDLE cadence and
+   * the cap of its unfinished-join retry ladder, not as a flat retry interval.
+   */
+  membershipReconciliation?: StrandMembershipReconciliationConfig;
+
   /**
    * Called when THIS node's own peer id turns up in the strand's revoked set —
    * this node's party was removed from the closed strand, or left it. Fires once
@@ -129,6 +212,40 @@ export interface StartStrandConfig {
    * this node's behalf — what to do about it is the app's call.
    */
   onSelfRevoked?: (strandId: string) => void;
+
+  /**
+   * Tuning for the JOINING machine's first-sync write gate (`strand-first-sync-gate.ts`),
+   * forwarded from {@link CadreNodeConfig.strandFirstSync}: the Header probe cadence while
+   * a non-founder launch is `'syncing'`, and the default budget {@link whenWritable} waits
+   * before rejecting. Founders and machines that already hold the Header are never gated.
+   */
+  firstSync?: StrandFirstSyncConfig;
+
+  /**
+   * Called when a launch that came up `'syncing'` (see {@link firstSync}) becomes
+   * writable: the strand's `Strand.Header` arrived from a peer — or a founder request
+   * ran the bootstrap against the gated database — and `instance.database` is now set.
+   * Never called for a launch that was writable when `startStrand`/`resumeStrand`
+   * resolved. `CadreNode` wires it to its `strand:writable` event. Retained with the
+   * launch config, so a hibernation resume that comes up gated announces too.
+   */
+  onWritable?: (strandId: string) => void;
+
+  /**
+   * Re-announce this strand's delegate peer id (`delegatePeerId` — the strand
+   * node's own transport peer id) to ONE relay (`relayAddr`, a direct dial addr
+   * with a trailing `/p2p/<relayPeerId>`), unthrottled. Awaited before every
+   * relay-reservation RE-drive of that relay — never before the first attempt,
+   * which the launch/resume seed pass has already announced for.
+   *
+   * Why: a party control node running the relay server admits the strand node on
+   * an in-memory delegate grant that a relay restart drops, so a re-drive that did
+   * not re-announce first would be denied at the relay's gate. `CadreNode` wires
+   * its own control-mesh announce here; a throw or rejection is logged by the
+   * supervisor and the re-drive still runs. Retained with the launch config, so a
+   * hibernation wake's rebuilt supervisors carry it too.
+   */
+  announceDelegateToRelay?: (strandId: string, relayAddr: string, delegatePeerId: string) => Promise<void>;
 }
 
 /**
@@ -242,6 +359,45 @@ export class StrandInstanceManager {
    * resume rebuilds it with a fresh (initially empty, fail-open) snapshot.
    */
   private revocationEnforcers: Map<string, StrandRevocationEnforcer> = new Map();
+  /**
+   * The per-strand membership reconciler (closed strands launched with a party
+   * key only), keyed by strand id. Same lifecycle rationale as {@link backfills}:
+   * created in `buildStrandRuntime`, stopped and dropped in `releaseRuntime`, so
+   * quiesce → resume rebuilds it and re-runs the idempotent join ladder (redeem a
+   * staged invitation, write this machine's own `MemberPeer` binding) from scratch.
+   */
+  private membershipReconcilers: Map<string, StrandMembershipReconciler> = new Map();
+  /**
+   * The per-strand first-sync gate (`strand-first-sync-gate.ts`), keyed by strand id:
+   * holds a launch's `StrandDatabase` while it is NOT yet published on the instance.
+   * Present from the moment the database object exists in `buildStrandRuntime` until
+   * {@link publishDatabase} hands it to the app — so it doubles as the rollback handle
+   * for a failed `initialize()` — and, for a joiner that holds no `Strand.Header` yet,
+   * for as long as the launch stays `'syncing'`. Same lifecycle as {@link backfills}:
+   * stopped (its database closed) and dropped in `releaseRuntime`, so a quiesce →
+   * resume rebuild re-probes over the same store. An entry and `instance.database`
+   * are mutually exclusive.
+   */
+  private firstSyncGates: Map<string, StrandFirstSyncGate> = new Map();
+  /**
+   * Callers blocked in {@link whenWritable}, keyed by strand id. Resolved by
+   * {@link publishDatabase}, rejected by {@link stopStrand}; each waiter also carries
+   * its own timeout. Deliberately NOT cleared by `releaseRuntime`: a waiter outlives a
+   * quiesce → resume cycle, since the rebuild is what may finally publish the database.
+   */
+  private writableWaiters: Map<string, Set<WritableWaiter>> = new Map();
+  /**
+   * The per-strand relay-reservation supervisors — ONE PER CONFIGURED RELAY, each
+   * over the node's own bare `/p2p-circuit` listener for that relay
+   * (`strand-network-config.ts`) — keyed by strand id. Same lifecycle rationale as
+   * {@link backfills}: started in `buildStrandRuntime` right after the libp2p node
+   * exists, stopped FIRST and dropped in `releaseRuntime` (before the database
+   * closes and the node stops, so no re-drive dials a node being torn down), so
+   * quiesce → resume rebuilds them over the new node. What makes a strand node's
+   * lost relay slot come back on its own — the control node has the same loop in
+   * `CadreNode.reserveRelays`.
+   */
+  private relaySupervisors: Map<string, RelayReservationSupervisor[]> = new Map();
   /**
    * The resolved (cache-wrapped) raw storage per strand id — the instance's OWN
    * store, resolved once in `startStrand` and held until `stopStrand` disposes it.
@@ -420,20 +576,19 @@ export class StrandInstanceManager {
     // Determine relay mode: if explicitly set in config, use that;
     // otherwise default to true for storage profile nodes.
     const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
-    // The CONFIGURED relay route (the default), 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 that
-    // never gets filled and leave the strand node undialable. The ordering hazard
-    // that pushed the control node onto the search route does not exist here — a
-    // strand node's protocol ids are namespaced `/optimystic/strand-<id>/…`, so a
-    // relay dialed from inside `libp2p.start()` is never in the strand's cohort and
-    // cannot refuse its database bring-up. See `relay-addrs.ts`.
-    //
     // The strand-node VIEW of the machine's one `NetworkConfig`, not the control
     // node's resolution: fixed direct listen ports become ephemeral (two nodes cannot
-    // bind one port) and the announce config is dropped (it names the control node's
-    // address). See `strand-network-config.ts` for both, and for the tradeoff.
-    const addrOptions = strandNodeAddrs(config.network);
+    // bind one port), the announce config is dropped (it names the control node's
+    // address), and every configured relay becomes one bare `/p2p-circuit` SEARCH
+    // listener plus a dial addr in `relayAddrs` for the per-relay supervisor started
+    // below — the same route the control node takes, because the configured
+    // `<relay>/p2p-circuit` shape loses its address on a relay restart, a hangup, or
+    // libp2p's own reservation refresh and recovers from none of them. See
+    // `strand-network-config.ts` for all three, and `relay-reservation.ts`.
+    //
+    // `relayAddrs` is destructured OFF: it is not a `createLibp2pNode` option, and
+    // spreading it would hand db-p2p a key it does not know.
+    const { relayAddrs: relayDialAddrs = [], ...addrOptions } = strandNodeAddrs(config.network);
 
     // The CLOSED-strand revoked-peer gate (see strand-revocation-enforcer.ts).
     // Constructed BEFORE the libp2p node because the node's options embed its
@@ -515,13 +670,12 @@ export class StrandInstanceManager {
         // Listen entries plus the WebSocket transport switch they imply — a strand node
         // announces nothing the operator configured (`strand-network-config.ts`), and
         // spreads AFTER `transports` above because the switch is a no-op whenever the
-        // embedder supplied its own factories. An inherited configured `/p2p-circuit` entry is
-        // deliberate and survives the derivation untouched: it is what gives a NAT'd
-        // strand node a reachable relay slot, and it works because the launch path
-        // announces this strand's derived peerId to the relay first (delegate admission;
-        // see cadre-node.ts). Those circuit entries come either from a hand-written
-        // `network.listenAddrs` or from `network.relayAddrs`, which the resolution folds
-        // into the same list on the configured route this call takes (see above).
+        // embedder supplied its own factories. The bare `/p2p-circuit` entries (one per
+        // relay) open no connection here; each registers a pending reservation that the
+        // matching supervisor below fills, which is what gives a NAT'd strand node a
+        // reachable relay slot — and works against a party-run relay because the launch
+        // path announced this strand's derived peerId to it first (delegate admission;
+        // see cadre-node.ts).
         ...addrOptions,
         // The raw configured gater (open strands), or the revocation-composed
         // gater plus the fail-closed per-stream revoked-peer gate (closed
@@ -532,10 +686,21 @@ export class StrandInstanceManager {
 
       instance.libp2pNode = node;
 
+      // One reservation supervisor PER RELAY, started now so the first attempts
+      // overlap the database bring-up below (the relay is never in a strand's
+      // Optimystic cohort — its protocol ids are namespaced `/optimystic/strand-<id>/…`
+      // — so an open relay connection cannot disturb that bring-up). Their first
+      // attempts are awaited before the strand goes `active`, below. Registered in the
+      // map immediately so the failure rollback (releaseRuntime) stops them like every
+      // other runtime component.
+      this.relaySupervisors.set(strandId, this.startRelaySupervisors(strandId, node, relayDialAddrs, config));
+
       // Create and initialize the StrandDatabase.
       //
-      // Attach before initialize so a failed init is cleaned up by
-      // releaseRuntime below (close() is safe on a partially-initialized db).
+      // Held by the first-sync gate (registered before initialize) rather than attached
+      // to the instance: a failed init is then cleaned up by releaseRuntime below through
+      // the gate (close() is safe on a partially-initialized db), and the app only ever
+      // sees `instance.database` once this machine is allowed to write to the strand.
       t0 = performance.now();
       const strandDb = new StrandDatabase({
         strandId,
@@ -543,16 +708,81 @@ export class StrandInstanceManager {
         libp2pNode: node,
         coordinatedRepo: node.coordinatedRepo,
         // Founder bootstrap inputs: the strand's type drives which membership rows
-        // are written, and the closed-strand MemberPrivateKey derives the founding
-        // Member/Manager key. Both come off the control-network strand row.
+        // are written, and the PARTY's own key (partyMemberPrivateKey, resolved by the
+        // caller from the control-layer StrandPartyKey row) derives the founding
+        // Member/Manager key. The row's shared MemberPrivateKey rides along as the
+        // read-gating secret only — it derives nobody's identity.
         strandType: config.strandRow.Type,
         memberPrivateKey: config.strandRow.MemberPrivateKey ?? undefined,
+        partyMemberPrivateKey: config.partyMemberPrivateKey,
         founder: config.founder
       });
-      instance.database = strandDb;
+      const gate = new StrandFirstSyncGate({
+        label: strandId,
+        database: strandDb,
+        onHeaderHeld: () => this.publishDatabase(instance, strandDb)
+      }, config.firstSync);
+      this.firstSyncGates.set(strandId, gate);
       await strandDb.initialize();
       timing('[buildStrandRuntime:%s] strandDatabase.initialize: %dms', strandId, Math.round(performance.now() - t0));
 
+      // The first-sync write gate. A founder just wrote the Header in its bootstrap; any
+      // other machine may commit only once it holds the Header — which it can only have
+      // received from a peer (now, or on an earlier run over the same store) — and has read
+      // each App table once, so their collections are fetched too. Publishing the database
+      // is what makes the strand writable to the app; until then the instance stays
+      // `'syncing'` and the gate re-probes on its cadence. Everything armed below reads
+      // `instance.database` lazily, so the reconciler and enforcer wait with it — and
+      // `publishDatabase` kicks the reconciler when the wait ends, so a joiner's membership
+      // rows land with the strand rather than one retry later.
+      t0 = performance.now();
+      if (config.founder === true || await strandFirstSyncComplete(strandDb.getDatabase(), strandId)) {
+        this.publishDatabase(instance, strandDb);
+      } else {
+        gate.start();
+      }
+      timing('[buildStrandRuntime:%s] first-sync probe: %dms', strandId, Math.round(performance.now() - t0));
+
+      // The membership reconciler: finish this party's join on every machine —
+      // redeem a staged formation invitation if one is pending, then write the
+      // durable machine→party binding (Strand.MemberPeer). Armed here, the one
+      // seam where the strand's transport peer id and a live Database both exist
+      // for launch AND hibernation resume, for closed strands that carry the
+      // party's own membership key. start() kicks an immediate pass WITHOUT
+      // awaiting it — a joiner at this instant has not synced the founder's rows
+      // and may lack write quorum, so bring-up is never blocked; an unfinished join
+      // then retries on a short doubling ladder capped at the configured
+      // pollIntervalMs (which is also the flat cadence while nobody has admitted this
+      // party yet), and the loop stops once the member row and this machine's own
+      // binding are both in place. Armed AFTER the gate above, so a gated launch
+      // always has a reconciler registered by the time the gate can publish.
+      if (config.strandRow.Type === 'c' && config.partyMemberPrivateKey
+        && config.membershipReconciliation?.enabled !== false) {
+        const reconciler = new StrandMembershipReconciler({
+          label: strandId,
+          partyMemberPrivateKey: config.partyMemberPrivateKey,
+          // Read per pass, never captured — same lifecycle argument as the
+          // enforcer's getNetwork: quiesce drops both handles.
+          getDatabase: () => instance.database?.getDatabase(),
+          getOwnPeerId: () => instance.libp2pNode?.peerId.toString(),
+          pendingInvite: config.pendingMembershipInvite,
+          // The enforcer's CURRENT snapshot view of this node's own peer id — the
+          // reconciler stops rather than fight a self-revocation. Absent when the
+          // gate is disarmed (fail-open: the loop just runs).
+          isSelfRevoked: revocationEnforcer
+            ? () => {
+                const ownPeerId = instance.libp2pNode?.peerId.toString();
+                return ownPeerId !== undefined && revocationEnforcer.isRevoked(ownPeerId);
+              }
+            : undefined
+        }, {
+          pollIntervalMs: config.membershipReconciliation?.pollIntervalMs
+            ?? config.revocationEnforcement?.pollIntervalMs
+        });
+        this.membershipReconcilers.set(strandId, reconciler);
+        reconciler.start();
+      }
+
       // Arm the revoked-peer deny-set poll now that the database it reads
       // exists. start() kicks an immediate refresh WITHOUT awaiting it —
       // bring-up and resume are never blocked on a membership read; until the
@@ -593,8 +823,27 @@ export class StrandInstanceManager {
         }
       }
 
-      instance.status = 'active';
+      // The relay supervisors' FIRST attempts, all of them, before `active`: the happy
+      // path still publishes its circuit addr before `addStrand` resolves (the
+      // strand-addr RPC answers read it, and the same-party circuit scenario asserts
+      // it). Fail-SOFT — a first attempt that lands nothing does not fail the launch.
+      // The strand's database is up, and the supervisor keeps trying on its backoff;
+      // failing here would only trade that for `StrandWatcher`'s full-rebuild retry.
+      //
+      // NOTE: a relay that is down costs this launch one full drive (10 s), and
+      // `StrandWatcher` launches strands one at a time — so N strands cost N × 10 s
+      // of bring-up during a relay outage. If that ever matters, stop awaiting here
+      // (the circuit addr then lands after `active`) rather than shortening the drive.
+      t0 = performance.now();
+      await this.awaitFirstRelayAttempts(strandId);
+      timing('[buildStrandRuntime:%s] relay first attempts: %dms', strandId, Math.round(performance.now() - t0));
+
+      instance.status = liveStrandStatus(instance);
       instance.lastActivity = new Date();
+      if (instance.status === 'syncing') {
+        log('Strand %s launched as a joiner with no Strand.Header held yet — writes are withheld until ' +
+          'a member of the strand is reached', strandId);
+      }
     } catch (error) {
       // Roll back any partially-attached runtime so the instance is left with
       // NEITHER handle. Otherwise the `libp2pNode || database` "already live"
@@ -608,17 +857,30 @@ export class StrandInstanceManager {
   }
 
   /**
-   * Release an instance's strand-network runtime: close the StrandDatabase, then
-   * stop the libp2p node (construction order in reverse), clearing both fields
-   * and zeroing connectedPeers. Tolerant of partially-built state — either handle
-   * may be absent — so it doubles as rollback for a failed `buildStrandRuntime`.
-   * Shared by `quiesceStrand`, `stopStrand`, and that rollback path.
+   * Release an instance's strand-network runtime: stop the relay supervisors and
+   * the other background loops, close the StrandDatabase, then stop the libp2p
+   * node (construction order in reverse), clearing both fields and zeroing
+   * connectedPeers. Tolerant of partially-built state — either handle may be
+   * absent — so it doubles as rollback for a failed `buildStrandRuntime`. Shared
+   * by `quiesceStrand`, `stopStrand`, and that rollback path.
    *
    * Leaves `strandStorages` untouched by design — the store outlives the runtime it
    * was built into, which is what makes a resume warm. Only `stopStrand` disposes it.
    */
   private async releaseRuntime(instance: StrandInstance): Promise<void> {
-    // Backfill first — before the database closes and the libp2p node stops — so
+    // Relay supervisors FIRST of all — before anything below is torn down — so no
+    // re-drive is scheduled against a node being stopped. `stop()` is synchronous
+    // and never awaits a drive, so a relay that is down cannot delay this teardown.
+    // NOTE: a drive ALREADY in flight cannot be aborted (the drive takes no
+    // AbortSignal — `backlog/bug-relay-drive-not-cancellable`); it fails soft
+    // against the stopped node within its own 10 s deadline and its result is
+    // discarded.
+    const relaySupervisors = this.relaySupervisors.get(instance.strandId);
+    if (relaySupervisors) {
+      relaySupervisors.forEach((supervisor) => supervisor.stop());
+      this.relaySupervisors.delete(instance.strandId);
+    }
+    // Backfill next — before the database closes and the libp2p node stops — so
     // no NEW catch-up push is issued against a torn-down transport. A push already
     // in flight is not awaited; it fails into the module's own per-chunk catch.
     const backfill = this.backfills.get(instance.strandId);
@@ -633,6 +895,22 @@ export class StrandInstanceManager {
       revocationEnforcer.stop();
       this.revocationEnforcers.delete(instance.strandId);
     }
+    // The membership reconciler likewise: a resume rebuilds it and re-runs the
+    // idempotent ladder, which is what makes resume-after-partial-join heal.
+    const membershipReconciler = this.membershipReconcilers.get(instance.strandId);
+    if (membershipReconciler) {
+      membershipReconciler.stop();
+      this.membershipReconcilers.delete(instance.strandId);
+    }
+    // A still-gated database (a joiner that never received the Header, or a launch whose
+    // initialize() failed) is closed through its gate; a published one through the
+    // instance. Never both — publishing moves the handle from the gate to the instance.
+    const gate = this.firstSyncGates.get(instance.strandId);
+    if (gate) {
+      gate.stop();
+      this.firstSyncGates.delete(instance.strandId);
+      await gate.database.close();
+    }
     if (instance.database) {
       await instance.database.close();
       instance.database = undefined;
@@ -644,6 +922,53 @@ export class StrandInstanceManager {
     instance.connectedPeers = 0;
   }
 
+  /**
+   * One {@link superviseRelayReservation} per relay dial addr, each over exactly
+   * that relay so "held" is judged per relay (`circuitMultiaddrsVia`) and losing
+   * one relay re-drives only that one. Default timings — the control node's (2 s
+   * doubling to 60 s between failed attempts, a 5 s liveness check while held).
+   *
+   * Each supervisor's `beforeRedrive` is the caller's
+   * {@link StartStrandConfig.announceDelegateToRelay} for THIS relay and THIS
+   * node's peer id, so a re-drive after a relay restart is preceded by a fresh
+   * delegate grant on the relay about to be dialed. Returns `[]` when no relay is
+   * configured — the strand then simply has no circuit listener to fill.
+   */
+  private startRelaySupervisors(
+    strandId: string,
+    node: Libp2pNodeWithRepo,
+    relayDialAddrs: readonly string[],
+    config: StartStrandConfig
+  ): RelayReservationSupervisor[] {
+    if (relayDialAddrs.length === 0) {
+      return [];
+    }
+    const announce = config.announceDelegateToRelay;
+    const delegatePeerId = node.peerId.toString();
+    return relayDialAddrs.map((relayAddr) => superviseRelayReservation(node, [relayAddr], {
+      ...(announce && { beforeRedrive: () => announce(strandId, relayAddr, delegatePeerId) })
+    }));
+  }
+
+  /**
+   * Wait for every relay supervisor's first attempt to settle, concurrently, and log
+   * the ones that landed nothing. Never throws — a strand whose relay is unreachable
+   * at launch still comes up, with its supervisors retrying in the background.
+   */
+  private async awaitFirstRelayAttempts(strandId: string): Promise<void> {
+    const supervisors = this.relaySupervisors.get(strandId) ?? [];
+    if (supervisors.length === 0) {
+      return;
+    }
+    await Promise.all(supervisors.map((supervisor) => supervisor.firstAttempt));
+    supervisors.forEach((supervisor) => {
+      if (supervisor.lastError !== null) {
+        log('Strand %s: relay reservation not held after the first attempt (retrying in the background): %s',
+          strandId, supervisor.lastError);
+      }
+    });
+  }
+
   /**
    * Drop the strand's owned store and release this strand's claim on its cache. The
    * wrapper counts holders, so the cache is emptied and unregistered from the shared
@@ -694,6 +1019,60 @@ export class StrandInstanceManager {
     await enforcer.refresh();
   }
 
+  /**
+   * Best-effort removal of THIS machine's own `Strand.MemberPeer` binding — the
+   * self arm of `removeMemberPeer`, signed with the retained launch config's party
+   * key. Called by `CadreNode.unpublishStrand` BEFORE the local stop, while the
+   * strand database and transport are still live: after the unpublish commits, the
+   * party's `StrandPartyKey` control row is gone, so no restart could ever sign
+   * this removal again — the in-memory retained key is the last chance.
+   *
+   * Never throws. Quiet no-op for a strand that is untracked, open, or launched
+   * without a party key; a quiesced (hibernating) strand, or a strand whose write
+   * quorum is already unreachable, leaves the stale binding behind with a log —
+   * it grants nothing today (admission is not allowlist-gated) and only
+   * mis-credits diversity. The strand's own membership reconciler is stopped —
+   * and its in-flight pass awaited — FIRST, so a pass that was already past its
+   * own stopped check cannot re-register the binding this is about to clear.
+   *
+   * NOTE: deliberately NOT handled here (or anywhere yet): clearing the bindings
+   * of a machine removed from the CADRE at the control layer, or of a party's
+   * OTHER machines when the party unpublishes — the party still holds the key on
+   * every surviving machine and can clear from any of them, and the stale rows
+   * grant nothing while admission is deny-list only. Revisit when
+   * `feat-strand-member-allowlist-admission` lands and a stale binding starts
+   * granting admission rather than merely mis-crediting diversity.
+   */
+  async clearOwnMemberPeerBinding(strandId: string): Promise<void> {
+    const instance = this.instances.get(strandId);
+    const config = this.launchConfigs.get(strandId);
+    if (!instance || !config || config.strandRow.Type !== 'c' || !config.partyMemberPrivateKey) {
+      return;
+    }
+    const reconciler = this.membershipReconcilers.get(strandId);
+    if (reconciler) {
+      reconciler.stop();
+      await reconciler.settle();
+    }
+    const db = instance.database?.getDatabase();
+    const peerId = instance.libp2pNode?.peerId.toString();
+    if (!db || !peerId) {
+      log('clearOwnMemberPeerBinding: strand %s has no live runtime — own MemberPeer binding left in place', strandId);
+      return;
+    }
+    try {
+      // Background write on the app's database: never join a transaction the app has open.
+      await removeMemberPeer(db, {
+        memberKeyPair: strandMemberKeyPair(config.partyMemberPrivateKey),
+        peerId
+      }, { joinOpenTransaction: false });
+      log('clearOwnMemberPeerBinding: strand %s — own binding for peer %s cleared', strandId, peerId);
+    } catch (error) {
+      log('clearOwnMemberPeerBinding: strand %s — best-effort clear failed (strand may already be unreachable): %o',
+        strandId, error);
+    }
+  }
+
   /**
    * Quiesce a strand: release its strand-network resources (stop the libp2p node,
    * close the StrandDatabase) while RETAINING the instance record — identity,
@@ -797,10 +1176,22 @@ export class StrandInstanceManager {
    *   database), so the bootstrap could not run here: the CALLER must wake the
    *   strand (`CadreNode.wakeStrand`, which owns the hibernation bookkeeping this
    *   manager does not) so the rebuild — which now founds — runs it.
+   * @param resolvePartyKey - Asked for the party's own membership key when (and only
+   *   when) a CLOSED strand's retained config carries none — the instance was launched
+   *   as a joiner before its `StrandPartyKey` row existed or replicated. The resolved
+   *   key is retained alongside the founder flip so the bootstrap (now, or on the
+   *   caller's wake for `'needs-resume'`) can seat the founding Member/Manager.
    * @throws when the strand is not tracked — this seam exists only for the
    *   tracked-instance launch path; an untracked id is a caller bug.
+   * @throws whatever the live bootstrap throws (e.g. `PreSplitStrandIdentityError`),
+   *   after {@link withdrawFounderRequest} — so a retry re-attempts the founding rather
+   *   than resolving `'already-founder'` over an instance that never founded. A caller
+   *   whose `'needs-resume'` wake fails owes the same withdrawal.
    */
-  async foundExistingStrand(strandId: string): Promise<'already-founder' | 'bootstrapped' | 'needs-resume'> {
+  async foundExistingStrand(
+    strandId: string,
+    resolvePartyKey?: () => Promise<string | undefined>
+  ): Promise<'already-founder' | 'bootstrapped' | 'needs-resume'> {
     const instance = this.instances.get(strandId);
     const config = this.launchConfigs.get(strandId);
     if (!instance || !config) {
@@ -809,16 +1200,151 @@ export class StrandInstanceManager {
     if (config.founder === true) {
       return 'already-founder';
     }
+    const partyMemberPrivateKey =
+      config.partyMemberPrivateKey
+        ?? (config.strandRow.Type === 'c' ? await resolvePartyKey?.() : undefined);
     // A fresh object rather than mutating in place: startStrand retains the CALLER'S
     // config object, which is not ours to rewrite.
-    this.launchConfigs.set(strandId, { ...config, founder: true });
-    if (!instance.database) {
+    this.launchConfigs.set(strandId, { ...config, founder: true, partyMemberPrivateKey });
+    if (!instance.database && !this.firstSyncGates.has(strandId)) {
       return 'needs-resume';
     }
-    await this.ensureFounderBootstrap(strandId);
+    try {
+      await this.ensureFounderBootstrap(strandId);
+    } catch (error) {
+      this.withdrawFounderRequest(strandId);
+      throw error;
+    }
     return 'bootstrapped';
   }
 
+  /**
+   * Whether `strandId` is launched but still waiting for its first sync — a joiner whose
+   * runtime is up while its database is withheld (status `'syncing'`, or `'idle'` after
+   * the hibernation manager's idle timer fired on it). `false` for a writable, quiesced,
+   * or untracked strand. The predicate {@link whenWritable}'s callers gate on.
+   */
+  isAwaitingFirstSync(strandId: string): boolean {
+    const instance = this.instances.get(strandId);
+    return instance !== undefined && isAwaitingFirstSync(instance);
+  }
+
+  /**
+   * Resolve once the strand's database is published to the app — immediately for a
+   * writable strand — or reject with {@link StrandAwaitingFirstSyncError} after
+   * `timeoutMs` (default: the retained launch config's `firstSync.timeoutMs`, else
+   * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS}). The rejection is RETRYABLE: nothing is
+   * torn down, the gate keeps probing, and a later call waits afresh. A quiesced
+   * (hibernating) strand is not woken here — the wait spans a resume, so a caller that
+   * wants one wakes it (`CadreNode.wakeStrand`) and waits. Rejects immediately for an
+   * untracked strand, and whenever the strand is stopped while a wait is pending.
+   */
+  whenWritable(strandId: string, options?: { timeoutMs?: number }): Promise<StrandInstance> {
+    const instance = this.instances.get(strandId);
+    if (!instance) {
+      return Promise.reject(new Error(`Cannot wait for strand ${strandId} to become writable: not tracked`));
+    }
+    if (instance.database) {
+      return Promise.resolve(instance);
+    }
+    const timeoutMs = options?.timeoutMs
+      ?? this.launchConfigs.get(strandId)?.firstSync?.timeoutMs
+      ?? DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS;
+    const startedAt = Date.now();
+    return new Promise<StrandInstance>((resolve, reject) => {
+      const waiters = this.writableWaiters.get(strandId) ?? new Set<WritableWaiter>();
+      this.writableWaiters.set(strandId, waiters);
+      const settle = (): void => {
+        clearTimeout(timer);
+        waiters.delete(waiter);
+        if (waiters.size === 0) {
+          this.writableWaiters.delete(strandId);
+        }
+      };
+      const waiter: WritableWaiter = {
+        resolve: () => { settle(); resolve(instance); },
+        reject: (error) => { settle(); reject(error); }
+      };
+      const timer = setTimeout(
+        () => waiter.reject(new StrandAwaitingFirstSyncError(strandId, Date.now() - startedAt)),
+        timeoutMs);
+      (timer as { unref?: () => void }).unref?.();
+      waiters.add(waiter);
+    });
+  }
+
+  /**
+   * Hand a launch's database to the app: set `instance.database`, retire the gate that
+   * held it, release every {@link whenWritable} waiter, and — when the launch had already
+   * been reported gated — flip it `'active'` and announce it through the retained config's
+   * `onWritable`. "Reported gated" is any status but `'starting'`: `'syncing'`, or the
+   * `'idle'` the hibernation manager's idle timer flips a long-gated joiner to (see
+   * {@link isAwaitingFirstSync}) — the Header arriving after that flip must announce too,
+   * or an app hanging on `strand:writable` never learns the strand opened. A publish that
+   * lands while the instance is still `'starting'` (the Header arrived during the rest of
+   * bring-up) announces nothing: `startStrand` / `resumeStrand` are about to report the
+   * strand `'active'`, and `strand:writable` is defined as the follow-up to a gated
+   * launch, never a duplicate of `strand:started`.
+   *
+   * It is also the one seam where a WITHHELD database becomes available, so it kicks the
+   * membership reconciler: on a gated launch that loop's own immediate pass ran while
+   * `instance.database` was still unset, found no database, and would otherwise not try
+   * again until its retry timer fired. A launch that was never gated publishes here BEFORE
+   * the reconciler is constructed, so there is nothing registered to kick and the loop's own
+   * immediate pass already sees the database — which is why the kick needs no `wasGated`
+   * test of its own.
+   */
+  private publishDatabase(instance: StrandInstance, database: StrandDatabase): void {
+    const strandId = instance.strandId;
+    const gate = this.firstSyncGates.get(strandId);
+    if (gate) {
+      gate.open();
+      this.firstSyncGates.delete(strandId);
+    }
+    instance.database = database;
+    instance.lastActivity = new Date();
+    const wasGated = instance.status !== 'starting';
+    if (wasGated) {
+      instance.status = 'active';
+      log('Strand %s is now writable: Strand.Header held', strandId);
+    }
+    const waiters = this.writableWaiters.get(strandId);
+    if (waiters) {
+      this.writableWaiters.delete(strandId);
+      waiters.forEach((waiter) => waiter.resolve());
+    }
+    if (wasGated) {
+      this.launchConfigs.get(strandId)?.onWritable?.(strandId);
+    }
+    // Not awaited: publishing must stay synchronous, and the pass chains on the loop's own
+    // tail, so it cannot overlap a pass already in flight.
+    void this.membershipReconcilers.get(strandId)?.reconcile();
+  }
+
+  /** Reject every {@link whenWritable} waiter for a strand that is going away. */
+  private rejectWritableWaiters(strandId: string, reason: string): void {
+    const waiters = this.writableWaiters.get(strandId);
+    if (!waiters) {
+      return;
+    }
+    this.writableWaiters.delete(strandId);
+    waiters.forEach((waiter) => waiter.reject(new Error(`Strand ${strandId} ${reason} before becoming writable`)));
+  }
+
+  /**
+   * Undo {@link foundExistingStrand}'s founder flip after the founding it promised
+   * failed, so the retained config again says what this instance actually runs as (a
+   * joiner) and the next founder request re-attempts the bootstrap. The resolved party
+   * key stays retained — it is this party's identity for the strand either way. No-op
+   * when the strand is untracked or its config does not found.
+   */
+  withdrawFounderRequest(strandId: string): void {
+    const config = this.launchConfigs.get(strandId);
+    if (config?.founder === true) {
+      this.launchConfigs.set(strandId, { ...config, founder: false });
+    }
+  }
+
   /**
    * Run the (idempotent) founder bootstrap against a tracked strand's LIVE
    * database, independently of what the retained launch config says.
@@ -831,6 +1357,11 @@ export class StrandInstanceManager {
    * and is the only thing that makes "founding resolves once the Header is
    * written" true on that path.
    *
+   * A strand still `'syncing'` (its database withheld behind the first-sync gate) is
+   * founded through the gate: the bootstrap writes the Header this machine was waiting
+   * to receive, so a successful run publishes the database and the strand goes
+   * `'active'` — the one legitimate way a joiner launch becomes writable without a peer.
+   *
    * @throws when the strand is not tracked, or is still quiesced (no live
    *   database) — both mean the bootstrap did NOT run, which a founder request
    *   must never swallow.
@@ -840,13 +1371,21 @@ export class StrandInstanceManager {
     if (!instance) {
       throw new Error(`Cannot run the founder bootstrap for strand ${strandId}: not tracked`);
     }
-    if (!instance.database) {
+    const gate = this.firstSyncGates.get(strandId);
+    const database = instance.database ?? gate?.database;
+    if (!database) {
       throw new Error(
         `Cannot run the founder bootstrap for strand ${strandId}: it is quiesced, so there ` +
         'is no live database to write to — resume it first.'
       );
     }
-    await instance.database.ensureFounderBootstrap();
+    // Forward the RETAINED config's party key: a foundExistingStrand that flipped a
+    // joiner launch to founder may have resolved a key the live database's captured
+    // config (built at the original launch) never saw.
+    await database.ensureFounderBootstrap(this.launchConfigs.get(strandId)?.partyMemberPrivateKey);
+    if (!instance.database) {
+      this.publishDatabase(instance, database);
+    }
   }
 
   /**
@@ -861,6 +1400,7 @@ export class StrandInstanceManager {
 
     log('Stopping strand instance: %s', strandId);
     instance.status = 'stopping';
+    this.rejectWritableWaiters(strandId, 'was stopped');
 
     try {
       await this.releaseRuntime(instance);