@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/strand-instance-manager.js

@@ -2,13 +2,45 @@ import debug from 'debug';
 import { createLibp2pNode } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
-import { StrandBackfill } from './strand-backfill.js';
+import { PeerJoinBackfill } from './peer-join-backfill.js';
+import { StrandRevocationEnforcer, createRevocationConnectionGater, readStrandRevocationRows } from './strand-revocation-enforcer.js';
+import { StrandMembershipReconciler } 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 { resolveStrandClusterSize, STRAND_CLUSTER_POLICY } from './types.js';
-import { resolveListenAddrs } from './relay-addrs.js';
-import { resolveAnnounceAddrs } from './announce-addrs.js';
+import { StrandFirstSyncGate, StrandAwaitingFirstSyncError, strandFirstSyncComplete, DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS } from './strand-first-sync-gate.js';
+import { resolveStrandClusterSize, strandClusterPolicy } from './types.js';
+import { strandNodeAddrs } from './strand-network-config.js';
+import { superviseRelayReservation } from './relay-reservation.js';
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
+/**
+ * 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) {
+    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) {
+    return instance.database ? 'active' : 'syncing';
+}
 /**
  * Get the isolated storage path for a specific strand.
  *
@@ -82,6 +114,52 @@ export class StrandInstanceManager {
          * missed writes).
          */
         this.backfills = new Map();
+        /**
+         * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
+         * id. Same lifecycle rationale as {@link backfills}: created in
+         * `buildStrandRuntime`, stopped and dropped in `releaseRuntime`, so quiesce →
+         * resume rebuilds it with a fresh (initially empty, fail-open) snapshot.
+         */
+        this.revocationEnforcers = 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.
+         */
+        this.membershipReconcilers = 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.
+         */
+        this.firstSyncGates = 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.
+         */
+        this.writableWaiters = 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`.
+         */
+        this.relaySupervisors = 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.
@@ -146,6 +224,14 @@ export class StrandInstanceManager {
             throw new Error('StrandInstanceManager is stopping');
         }
         if (this.instances.has(strandId)) {
+            // Callers resolve founder-ness BEFORE reaching here (CadreNode.launchStrand) and
+            // honor a founder request on a tracked instance via foundExistingStrand — so a
+            // founder flag arriving at this early return against a non-founder retained
+            // config is a dropped bootstrap, and must never again be silent.
+            if (config.founder === true && this.launchConfigs.get(strandId)?.founder !== true) {
+                log('startStrand: strand %s is already running but was NOT launched as founder — ' +
+                    'this early return DROPS the founder request; use foundExistingStrand', strandId);
+            }
             log('Strand %s already running', strandId);
             return this.instances.get(strandId);
         }
@@ -212,8 +298,9 @@ export class StrandInstanceManager {
      * Build (or rebuild) the libp2p node + StrandDatabase for an instance and
      * attach them, transitioning it to `active`. Shared by `startStrand` (fresh
      * launch) and `resumeStrand` (rehydrating a quiesced instance). Reads all
-     * volatile inputs (bootstrapNodes, network, profile, privateKey, sApp config)
-     * from `config`, so the caller controls the cohort-derived values. Storage is the
+     * volatile inputs (bootstrapNodes, servingMachines, network, profile,
+     * privateKey, sApp config) from `config`, so the caller controls the
+     * cohort-derived values. Storage is the
      * one input it does NOT re-read from `config`: that belongs to the instance and
      * comes from `strandStorages`.
      */
@@ -232,16 +319,66 @@ 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`.
-        const listenAddrs = resolveListenAddrs(config.network);
+        // 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), 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
+        // predicates; its deny set starts empty (admit everything — fail-open, same
+        // posture as bring-up everywhere here) and is first populated after the
+        // strand database initializes below. Registered in the map immediately so
+        // the failure rollback (releaseRuntime) tears it down like every other
+        // runtime component. Open strands skip it entirely: their Member/MemberPeer
+        // tables are empty by schema (`OnlyClosed`), so there is nothing to derive
+        // a deny set from — arming would be pointless polling.
+        const revocationEnforcer = config.strandRow.Type === 'c' && config.revocationEnforcement?.enabled !== false
+            ? new StrandRevocationEnforcer({
+                label: strandId,
+                readRows: () => {
+                    const database = instance.database;
+                    if (!database) {
+                        throw new Error(`strand ${strandId} has no live database`);
+                    }
+                    return readStrandRevocationRows(database.getDatabase());
+                },
+                // Read per sweep, never captured: this closure is built BEFORE the
+                // libp2p node exists (its options embed the enforcer's predicates),
+                // and `releaseRuntime` clears the field again on quiesce. Undefined
+                // therefore means "no transport right now", which the enforcer
+                // treats as "nothing to tear down".
+                getNetwork: () => instance.libp2pNode,
+                onSelfRevoked: () => config.onSelfRevoked?.(strandId)
+            }, config.revocationEnforcement)
+            : undefined;
+        if (revocationEnforcer) {
+            this.revocationEnforcers.set(strandId, revocationEnforcer);
+        }
+        // Closed strands compose revoked-peer denial onto the caller's gater and arm
+        // the fail-closed per-stream gate; open strands keep the raw configured gater
+        // (their peers are legitimately cross-party and nothing is ever revoked).
+        const revocationGateOptions = revocationEnforcer
+            ? {
+                connectionGater: createRevocationConnectionGater(revocationEnforcer, config.network?.connectionGater),
+                authorizeInboundStream: (remotePeerId, protocol) => revocationEnforcer.authorizeStream(remotePeerId, protocol)
+            }
+            : config.network?.connectionGater
+                ? { connectionGater: config.network.connectionGater }
+                : {};
         try {
+            // Bound once: the breadth is also the ceiling on the repair yardstick below, and the
+            // two must be derived from the same resolution. Inside the `try` deliberately — a
+            // rejected clusterSize is a build failure that runs the same cleanup as any other.
+            const strandClusterSize = resolveStrandClusterSize(config.clusterSize);
             let t0 = performance.now();
             const node = await createLibp2pNode({
                 port: 0, // Random port
@@ -250,50 +387,54 @@ export class StrandInstanceManager {
                 storage: strandStorage,
                 fretProfile: config.profile === 'storage' ? 'core' : 'edge',
                 relay: enableRelay,
-                clusterSize: resolveStrandClusterSize(config.clusterSize),
+                clusterSize: strandClusterSize,
                 // Deliberately NOT CONTROL_CLUSTER_POLICY: a strand is application data with its own
                 // breadth reasoning, and the shape match with the control policy is a coincidence.
-                clusterPolicy: STRAND_CLUSTER_POLICY,
+                //
+                // The builder declares this node's block-repair corroboration yardstick from the
+                // count of machines SERVING this strand, capped at the breadth above (a block
+                // never lives on more machines than the cohort is wide). Given no count — the
+                // production path today, since no per-strand serving count exists yet — it
+                // returns the frozen STRAND_CLUSTER_POLICY itself, declaring nothing. Resolved
+                // HERE rather than at `startStrand`, so a wake from hibernation would pick up a
+                // serving set that changed while the strand slept.
+                clusterPolicy: strandClusterPolicy(strandClusterSize, config.servingMachines),
                 arachnode: {
                     enableRingZulu: config.profile === 'storage'
                 },
                 ...(config.privateKey && { privateKey: config.privateKey }),
                 ...(config.network?.transports && { transports: config.network.transports }),
-                // NOTE: strand nodes receive the same RESOLVED listen addrs as the
-                // control node. A fixed-port listen addr (e.g. cadre-cli's example
-                // `/ip4/0.0.0.0/tcp/4001`) would have control + strand nodes racing to
-                // bind one port — EADDRINUSE. Unverified; if a deployment configures a
-                // fixed port and strands fail to start, rewrite the port per node here.
-                // An inherited configured `/p2p-circuit` addr, by contrast, is deliberate —
-                // it is what gives a NAT'd strand node a reachable relay slot — and 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 `resolveListenAddrs` folds into the same list
-                // on the configured route this call takes (see the comment above it).
-                ...(listenAddrs && { listenAddrs }),
-                // A strand node behind a reverse proxy has the same advertising need as the
-                // control node, and inherits the same `NetworkConfig` — so it announces the same
-                // addresses.
-                //
-                // NOTE: an announce addr naming a PORT therefore names the control node's port,
-                // not this strand node's — the same second-node-on-one-host problem the listen
-                // NOTE above describes, and the reason both belong to one fix. It is currently
-                // unreachable: naming a fixed public port means configuring a fixed
-                // `listenAddrs` port, and that collides at bind time before any strand node gets
-                // far enough to advertise anything. Whatever gives strand nodes their own listen
-                // port has to give them their own announce addrs in the same pass, or a strand
-                // will advertise an address that reaches the control node. Tracked as an arm of
-                // `tickets/backlog/strand-network-nat-relay-reachability.md`.
-                ...resolveAnnounceAddrs(config.network),
-                ...(config.network?.connectionGater && { connectionGater: config.network.connectionGater })
+                // 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. 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
+                // strands) — resolved above, before the try.
+                ...revocationGateOptions
             });
             timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
             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,
@@ -301,32 +442,104 @@ 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
+            // first read lands the empty snapshot admits everyone (fail-open).
+            revocationEnforcer?.start();
             // Peer-join block catch-up: push this strand's own blocks to each newly
             // connected peer, so a machine that joined after blocks were committed
             // still ends up physically holding them (without per-strand storage there
-            // is nothing to copy). Armed for EVERY stored strand: `StrandBackfill`
+            // is nothing to copy). Armed for EVERY stored strand: `PeerJoinBackfill`
             // only does work when the strand's libp2p node reports a peer connection,
             // so on a device that is genuinely alone it is inert, and arming it at
             // launch is what closes the "founded alone, never replicates" hole — a
             // peer that joins later gets the founder's blocks without any relaunch.
+            // No `authorizePeer` gate, deliberately — see the module comment in
+            // peer-join-backfill.ts for the strand-side argument (and why the control
+            // network, which DOES gate, is different).
             //
-            // NOTE: cost is one StrandBackfill object + one `connection:open` listener
+            // NOTE: cost is one PeerJoinBackfill object + one `connection:open` listener
             // per running strand — linear in strand count, negligible at the handful a
             // device or host runs today. If a node ever hosts strands by the hundred,
             // move to one shared listener that dispatches by strand id.
             if (strandStorage && config.backfill?.enabled !== false) {
                 if (node.keyNetwork) {
-                    const backfill = new StrandBackfill({
-                        strandId,
+                    const backfill = new PeerJoinBackfill({
+                        label: strandId,
                         libp2p: node,
                         peerNetwork: node.keyNetwork,
                         storage: strandStorage,
@@ -341,8 +554,26 @@ export class StrandInstanceManager {
                     log('Strand %s: libp2p node exposes no keyNetwork; peer-join block catch-up is inert', strandId);
                 }
             }
-            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
@@ -356,17 +587,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.
      */
     async releaseRuntime(instance) {
-        // 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);
@@ -374,6 +618,29 @@ export class StrandInstanceManager {
             backfill.stop();
             this.backfills.delete(instance.strandId);
         }
+        // The revoked-peer enforcer goes with the runtime it gated: a resume
+        // rebuilds it with a fresh (initially empty, fail-open) snapshot.
+        const revocationEnforcer = this.revocationEnforcers.get(instance.strandId);
+        if (revocationEnforcer) {
+            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;
@@ -384,6 +651,45 @@ 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.
+     */
+    startRelaySupervisors(strandId, node, relayDialAddrs, config) {
+        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.
+     */
+    async awaitFirstRelayAttempts(strandId) {
+        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
@@ -408,6 +714,84 @@ export class StrandInstanceManager {
             log('Failed to dispose storage cache for strand %s: %o', strandId, error);
         }
     }
+    /**
+     * Refresh a strand's revoked-peer deny set NOW — and, with it, run the
+     * teardown sweep that hangs up every connected revoked peer.
+     *
+     * The gate is otherwise poll-driven (default
+     * `DEFAULT_REVOCATION_POLL_INTERVAL_MS`), because neither a replicated
+     * revocation nor a local `revokeMember`/`leaveStrand` raises anything this
+     * runtime can hook. A caller that just wrote a revocation against the
+     * strand's database should follow it with this call, which makes the cut
+     * immediate instead of waiting out the interval.
+     *
+     * Quiet no-op — matching `quiesceStrand`'s posture — when the strand is not
+     * tracked, is quiesced, is open, or has the gate disabled: in every one of
+     * those cases there is no enforcer to refresh. Never rejects (the enforcer's
+     * refresh contains its own failures), and resolves only once the sweep has
+     * finished.
+     */
+    async refreshRevocationEnforcement(strandId) {
+        const enforcer = this.revocationEnforcers.get(strandId);
+        if (!enforcer) {
+            log('refreshRevocationEnforcement: strand %s has no armed revocation enforcer', strandId);
+            return;
+        }
+        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) {
+        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,
@@ -434,9 +818,9 @@ export class StrandInstanceManager {
      * Resume a previously-quiesced strand: rebuild its libp2p node + StrandDatabase
      * from the retained launch config and re-attach them, transitioning it back to
      * `active`. `overrides` re-applies volatile inputs that may have changed since
-     * launch (the cohort `bootstrapNodes` seed) and updates the retained config so
-     * a later resume reuses the latest values. Returns the live instance unchanged
-     * if it is already running.
+     * launch (the cohort `bootstrapNodes` seed and the strand's `servingMachines`
+     * count) and updates the retained config so a later resume reuses the latest
+     * values. Returns the live instance unchanged if it is already running.
      */
     async resumeStrand(strandId, overrides) {
         if (this.stopping) {
@@ -457,9 +841,20 @@ export class StrandInstanceManager {
         log('Resuming strand instance: %s', strandId);
         const tTotal = performance.now();
         // Re-apply volatile inputs and persist them so a subsequent resume reuses them.
+        // Each `??` matters: a resume that passes no override must keep the retained value,
+        // and a resume that passes one must leave it retained for the next resume — otherwise
+        // a later no-override wake silently reverts to whatever launch time saw.
         const resumeConfig = {
             ...launchConfig,
-            bootstrapNodes: overrides?.bootstrapNodes ?? launchConfig.bootstrapNodes
+            bootstrapNodes: overrides?.bootstrapNodes ?? launchConfig.bootstrapNodes,
+            // NOTE: `??` retains, so an override can raise or lower the count but cannot CLEAR it
+            // back to "this node no longer knows" — the direction that would declare nothing. Moot
+            // while nothing feeds `servingMachines` at all; if a source lands
+            // (`backlog/feat-strand-yardstick-from-serving-machines`) that can legitimately lose the
+            // count — a strand whose member rows became unreadable — this merge must gain an explicit
+            // clear rather than silently declaring a stale number over a serving set it can no longer
+            // see. Same applies to `bootstrapNodes` above, where a stale seed is harmless.
+            servingMachines: overrides?.servingMachines ?? launchConfig.servingMachines
         };
         this.launchConfigs.set(strandId, resumeConfig);
         instance.status = 'starting';
@@ -476,6 +871,223 @@ export class StrandInstanceManager {
             throw error;
         }
     }
+    /**
+     * Honor a founder request against an ALREADY-TRACKED strand — the seam that
+     * closes the "whoever launches first decides whether the bootstrap runs" gap:
+     * an instance first launched as a joiner (an app's own attach, or a watcher
+     * poll winning the launch race) used to swallow a later founder request
+     * silently, leaving the strand active with no `Strand.Header`.
+     *
+     * Flips the RETAINED launch config's `founder` to true, so every later
+     * quiesce → resume rebuild founds as well (the bootstrap is insert-if-absent —
+     * {@link StrandDatabase.ensureFounderBootstrap} — so re-running it per rebuild
+     * writes nothing twice), and runs the bootstrap against the live database now.
+     *
+     * @returns how the request resolved:
+     * - `'already-founder'` — the retained config already founds; nothing to do.
+     * - `'bootstrapped'` — config flipped and the live database ran the bootstrap.
+     * - `'needs-resume'` — config flipped, but the instance is quiesced (no live
+     *   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, resolvePartyKey) {
+        const instance = this.instances.get(strandId);
+        const config = this.launchConfigs.get(strandId);
+        if (!instance || !config) {
+            throw new Error(`Cannot found strand ${strandId}: not tracked`);
+        }
+        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, partyMemberPrivateKey });
+        if (!instance.database && !this.firstSyncGates.has(strandId)) {
+            return 'needs-resume';
+        }
+        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) {
+        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, options) {
+        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((resolve, reject) => {
+            const waiters = this.writableWaiters.get(strandId) ?? new Set();
+            this.writableWaiters.set(strandId, waiters);
+            const settle = () => {
+                clearTimeout(timer);
+                waiters.delete(waiter);
+                if (waiters.size === 0) {
+                    this.writableWaiters.delete(strandId);
+                }
+            };
+            const waiter = {
+                resolve: () => { settle(); resolve(instance); },
+                reject: (error) => { settle(); reject(error); }
+            };
+            const timer = setTimeout(() => waiter.reject(new StrandAwaitingFirstSyncError(strandId, Date.now() - startedAt)), timeoutMs);
+            timer.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.
+     */
+    publishDatabase(instance, database) {
+        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. */
+    rejectWritableWaiters(strandId, reason) {
+        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) {
+        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.
+     *
+     * Separate from {@link foundExistingStrand} because a caller that resolved
+     * `'needs-resume'` and woke the strand must not assume the wake's own rebuild
+     * founded it: `HibernationManager` COALESCES wakes, so a wake already in flight
+     * when the config flipped had already read the PRE-flip config and rebuilt as a
+     * joiner. Re-running the bootstrap costs one insert-if-absent probe per table
+     * 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.
+     */
+    async ensureFounderBootstrap(strandId) {
+        const instance = this.instances.get(strandId);
+        if (!instance) {
+            throw new Error(`Cannot run the founder bootstrap for strand ${strandId}: not tracked`);
+        }
+        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.');
+        }
+        // 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);
+        }
+    }
     /**
      * Stop a strand instance
      */
@@ -487,6 +1099,7 @@ export class StrandInstanceManager {
         }
         log('Stopping strand instance: %s', strandId);
         instance.status = 'stopping';
+        this.rejectWritableWaiters(strandId, 'was stopped');
         try {
             await this.releaseRuntime(instance);
             instance.status = 'stopped';