@serfab/cadre-core 0.12.0 → 0.13.0

package/src/strand-instance-manager.ts

@@ -3,7 +3,13 @@ import type { PrivateKey } from '@libp2p/interface';
 import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
-import { StrandBackfill, type StrandBackfillConfig } from './strand-backfill.js';
+import { PeerJoinBackfill, type PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import {
+  StrandRevocationEnforcer,
+  createRevocationConnectionGater,
+  readStrandRevocationRows,
+  type StrandRevocationEnforcementConfig
+} from './strand-revocation-enforcer.js';
 import { assertSchemaSignature } from './schema-verification.js';
 import type {
   StrandInstance,
@@ -17,9 +23,8 @@ import type {
   RawStorageProvider,
   Libp2pNodeWithRepo
 } from './types.js';
-import { resolveStrandClusterSize, STRAND_CLUSTER_POLICY } from './types.js';
-import { resolveListenAddrs } from './relay-addrs.js';
-import { resolveAnnounceAddrs } from './announce-addrs.js';
+import { resolveStrandClusterSize, strandClusterPolicy } from './types.js';
+import { strandNodeAddrs } from './strand-network-config.js';
 
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
@@ -47,8 +52,12 @@ export interface StartStrandConfig {
   /**
    * Whether this node founds the strand (vs. joins it). Forwarded to the
    * StrandDatabase so the founder bootstrap (Header, founding Member/Manager)
-   * runs once at bring-up. Joiners leave this unset and write nothing. See
-   * {@link StrandConfig.founder}.
+   * runs once at bring-up. Joiners leave this unset and write nothing. Callers
+   * resolve it BEFORE calling `startStrand` (`CadreNode.launchStrand` derives it
+   * from the row's `FounderOwnerKey` when no explicit flag is given — see
+   * {@link StrandConfig.founder}); a founder request that arrives while the
+   * instance is already tracked goes through {@link StrandInstanceManager.foundExistingStrand},
+   * never through a repeat `startStrand`.
    */
   founder?: boolean;
   /**
@@ -62,24 +71,87 @@ export interface StartStrandConfig {
    */
   clusterSize?: number;
   /**
-   * Tuning for the strand peer-join block catch-up ({@link StrandBackfill}),
+   * Machines that SERVE THIS STRAND (this node included), for the strand node's
+   * block-repair corroboration yardstick — see `resolveRepairYardstick`. It must be
+   * an authenticated per-strand count: the machines that actually run a node for this
+   * strand, not the machines that exist.
+   *
+   * **The party's enrolled-machine count is NOT this number and must never be passed
+   * here.** A strand launches only on machines whose embedding app registered its sApp
+   * config (`CadreNode.addStrand`), so a closed strand shared by two machines of a
+   * three-machine party is served by two. Passing three over-declares, and
+   * over-declaring is the unsafe direction: at a declaration of 3 or more Optimystic
+   * pins the repair corroboration floor at two corroborating peers, which a cohort
+   * that can only ever field one peer can never reach — so the strand can never repair
+   * a block (`cluster-fetch:no-quorum`, surfacing as reads failing with `Missing
+   * block`). That regression is why this field was renamed off "enrolledMachines":
+   * `bug-strand-yardstick-counts-party-machines`.
+   *
+   * **Nothing feeds it in production today.** No authenticated per-strand serving count
+   * exists yet, so `CadreNode` passes nothing and the strand node runs the frozen
+   * `STRAND_CLUSTER_POLICY` — declaring no yardstick, which leaves the known,
+   * upstream-tracked single-voter exposure
+   * (`backlog/debt-read-repair-single-voter-corroboration`). Building the count is
+   * `backlog/feat-strand-yardstick-from-serving-machines`; this field and its
+   * threading are the seam it plugs into.
+   *
+   * Volatile when a source does exist: re-resolve it on every resume beside the cohort
+   * seed, since machines join and leave a strand while it hibernates. Omitting it means
+   * "this node does not know", which declares nothing.
+   */
+  servingMachines?: number;
+  /**
+   * Tuning for the strand peer-join block catch-up ({@link PeerJoinBackfill}),
    * forwarded from {@link CadreNodeConfig.strandBackfill}. When the strand's
    * libp2p node connects to a peer this runtime has not yet caught up, every
    * block in the strand's own raw store is pushed to it. Runs only on strands
    * with per-strand storage; `{ enabled: false }` restores the pre-existing
    * no-backfill behaviour.
    */
-  backfill?: StrandBackfillConfig;
+  backfill?: PeerJoinBackfillConfig;
+  /**
+   * Tuning for the CLOSED-strand revoked-peer gate
+   * ({@link StrandRevocationEnforcer}), forwarded from
+   * {@link CadreNodeConfig.strandRevocationEnforcement}. Armed only for
+   * `strandRow.Type === 'c'` (an open strand has no membership rows to derive a
+   * deny set from); `{ enabled: false }` restores the pre-existing behaviour
+   * (a removed party's peers keep being served).
+   */
+  revocationEnforcement?: StrandRevocationEnforcementConfig;
+
+  /**
+   * 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
+   * per removal (re-armed if the party is re-admitted; a resume also rebuilds the
+   * enforcer and may legitimately re-fire), and only for closed strands with the
+   * gate armed. `CadreNode`
+   * wires it to its `strand:revoked` event; nothing is stopped or torn down on
+   * this node's behalf — what to do about it is the app's call.
+   */
+  onSelfRevoked?: (strandId: string) => void;
 }
 
 /**
- * Volatile inputs re-resolved when resuming a quiesced strand. The cohort
- * discovery seed is the only one — it grows as peers are learned since the
- * strand first launched.
+ * Volatile inputs re-resolved when resuming a quiesced strand — the ones that can
+ * have moved since it last ran, and that the rebuilt libp2p node freezes again. Each
+ * one omitted keeps the value the retained launch config already holds, so a resume
+ * that passes nothing rebuilds the strand exactly as it last ran.
  */
 export interface ResumeStrandOverrides {
-  /** Freshly-resolved cohort discovery seed (multiaddr strings). */
+  /**
+   * Freshly-resolved cohort discovery seed (multiaddr strings). Grows as peers are
+   * learned since the strand first launched.
+   */
   bootstrapNodes?: string[];
+  /**
+   * Freshly-read count of the machines serving this strand, for the repair yardstick
+   * (see {@link StartStrandConfig.servingMachines} — including why the party's
+   * enrolled-machine count is not it). Moves whenever a machine starts or stops
+   * serving the strand, which a hibernating strand does not otherwise notice. Nothing
+   * passes it today. Omitting it here does NOT mean "unknown" the way omitting it from
+   * {@link StartStrandConfig} does — it retains the last value; see `resumeStrand`.
+   */
+  servingMachines?: number;
 }
 
 /**
@@ -162,7 +234,14 @@ export class StrandInstanceManager {
    * with a fresh caught-up-peer memo, which is intended (a resumed node may have
    * missed writes).
    */
-  private backfills: Map<string, StrandBackfill> = new Map();
+  private backfills: Map<string, PeerJoinBackfill> = 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.
+   */
+  private revocationEnforcers: Map<string, StrandRevocationEnforcer> = 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.
@@ -235,6 +314,14 @@ export class StrandInstanceManager {
     }
 
     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)!;
     }
@@ -309,8 +396,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`.
    */
@@ -340,9 +428,65 @@ export class StrandInstanceManager {
     // 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) 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);
+
+    // 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: string, protocol: string) =>
+            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
@@ -351,43 +495,38 @@ 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. 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).
+        ...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
       }) as Libp2pNodeWithRepo;
       timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
 
@@ -414,23 +553,32 @@ export class StrandInstanceManager {
       await strandDb.initialize();
       timing('[buildStrandRuntime:%s] strandDatabase.initialize: %dms', strandId, Math.round(performance.now() - t0));
 
+      // 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,
@@ -478,6 +626,13 @@ 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);
+    }
     if (instance.database) {
       await instance.database.close();
       instance.database = undefined;
@@ -513,6 +668,32 @@ export class StrandInstanceManager {
     }
   }
 
+  /**
+   * 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: string): Promise<void> {
+    const enforcer = this.revocationEnforcers.get(strandId);
+    if (!enforcer) {
+      log('refreshRevocationEnforcement: strand %s has no armed revocation enforcer', strandId);
+      return;
+    }
+    await enforcer.refresh();
+  }
+
   /**
    * Quiesce a strand: release its strand-network resources (stop the libp2p node,
    * close the StrandDatabase) while RETAINING the instance record — identity,
@@ -541,9 +722,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: string, overrides?: ResumeStrandOverrides): Promise<StrandInstance> {
     if (this.stopping) {
@@ -566,9 +747,20 @@ export class StrandInstanceManager {
     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: StartStrandConfig = {
       ...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);
 
@@ -586,6 +778,77 @@ export class StrandInstanceManager {
     }
   }
 
+  /**
+   * 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.
+   * @throws when the strand is not tracked — this seam exists only for the
+   *   tracked-instance launch path; an untracked id is a caller bug.
+   */
+  async foundExistingStrand(strandId: string): Promise<'already-founder' | 'bootstrapped' | 'needs-resume'> {
+    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';
+    }
+    // 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) {
+      return 'needs-resume';
+    }
+    await this.ensureFounderBootstrap(strandId);
+    return 'bootstrapped';
+  }
+
+  /**
+   * 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.
+   *
+   * @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: string): Promise<void> {
+    const instance = this.instances.get(strandId);
+    if (!instance) {
+      throw new Error(`Cannot run the founder bootstrap for strand ${strandId}: not tracked`);
+    }
+    if (!instance.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();
+  }
+
   /**
    * Stop a strand instance
    */

package/src/strand-membership-writer.ts

@@ -852,6 +852,13 @@ export interface RevokeMemberParams {
  * (`Member.MinOneMember`, a local-count floor with the cross-node caveat its
  * schema NOTE states).
  *
+ * Callers running inside a cadre runtime should follow this write with
+ * `CadreNode.refreshRevocationEnforcement(strandId)`. The removed party's
+ * machines are refused at the network layer by the strand's revoked-peer gate
+ * (`strand-revocation-enforcer.ts`), which polls for membership changes because
+ * this bare `Database` handle raises no event the runtime can hook — so without
+ * that call the cut lands up to one poll interval (default 30 s) later.
+ *
  * @param db - The closed strand's database.
  * @param params - The revoking manager keypair and the target member key.
  * @throws If `Member.Authorized` rejects (a non-manager or same-transaction
@@ -907,6 +914,11 @@ export interface LeaveStrandParams {
  * The same floors as {@link revokeMember} apply: a manager must resign first
  * (`NotAManager`) and the last member cannot leave (`MinOneMember`).
  *
+ * Like {@link revokeMember}, a caller inside a cadre runtime should follow this
+ * with `CadreNode.refreshRevocationEnforcement(strandId)` — here it is what
+ * makes the departing node notice its own departure promptly (the gate emits
+ * `strand:revoked` when it finds this node's own peer id revoked).
+ *
  * @param db - The closed strand's database.
  * @param params - The departing member's own keypair.
  * @throws If `Member.Authorized`, `Member.NotAManager`, or `Member.MinOneMember`
@@ -1207,7 +1219,17 @@ async function deleteOwnMemberPeer(db: Database, params: RemoveOwnPeerParams, st
   await insertRevocation(db, 'MemberPeer', stampId, memberKeyPair);
 }
 
-/** The manager branch: a manager signs the manager-remove-tagged digest + tombstone. */
+/**
+ * The manager branch: a manager signs the manager-remove-tagged digest + tombstone.
+ *
+ * NOTE: clearing an ORPHANED binding (one whose member was already removed) also
+ * forgets the NETWORK DENIAL of that peer id. The orphaned `MemberPeer` row IS
+ * the record the strand revoked-peer gate derives its deny set from
+ * (`strand-revocation-enforcer.ts`) — the `Strand.Revocation` tombstone keeps
+ * only the stamp, not the peer id — so once the orphan is cleared, remaining
+ * members' nodes resume answering and dialing that peer. Only clear a binding
+ * that should never have existed, or a peer that is truly gone.
+ */
 async function deleteMemberPeerByManager(
   db: Database,
   params: RemoveMemberPeerByManagerParams,