@serfab/cadre-core 0.11.0 → 0.13.0

package/dist/cadre-node.d.ts

@@ -1,9 +1,10 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
-import type { CadreNodeConfig, StrandInstance, StrandConfig, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts } from './types.js';
+import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts } from './types.js';
 import { type Ed25519KeyPair } from './ed25519-key.js';
 import { type TrustedOwnerStore, type TrustSource } from './trusted-owner-store.js';
 import { type BootstrapPeerStore } from './bootstrap-peer-store.js';
+import { type EnrolledMachineStore } from './enrolled-machine-store.js';
 import { type SAppIdLookup } from './strand-watcher.js';
 import { EnrollmentService } from './enrollment.js';
 import { ControlDatabase } from './control-database.js';
@@ -57,6 +58,14 @@ export declare class CadreNode implements SAppIdLookup {
     private trustedOwnerStore;
     private controlNode;
     private controlDatabase;
+    /**
+     * The CONTROL network's peer-join block catch-up — same module as the
+     * per-strand ones, but membership-gated (see {@link startControlBackfill}).
+     * Created in {@link start} after the control node and database are up, stopped
+     * and dropped in {@link cleanup} before either is torn down, so a stop()→
+     * start() cycle rebuilds it with a fresh caught-up-peer memo.
+     */
+    private controlBackfill;
     private strandWatcher;
     private strandManager;
     private hibernationManager;
@@ -103,10 +112,11 @@ export declare class CadreNode implements SAppIdLookup {
     private windowWaiters;
     private eventHandlers;
     /**
-     * Relay multiaddrs the caller asked {@link reserveRelays} to reserve through.
-     * Empty (the default) means nobody asked, so {@link getRelayReservationState}
-     * reports `none` — this whole surface is opt-in and dormant for the CLI/host
-     * nodes, which use the configured `network.relayAddrs` route instead.
+     * Relay multiaddrs the caller asked {@link reserveRelays} to reserve through —
+     * or, on a node that names `network.relayAddrs`, the ones
+     * {@link driveControlRelayReservation} asked for at the end of {@link start}.
+     * Empty (the default) means neither happened, so {@link getRelayReservationState}
+     * reports `none`.
      */
     private relayReserveAddrs;
     /**
@@ -121,6 +131,23 @@ export declare class CadreNode implements SAppIdLookup {
      * supervisor to hold one — i.e. the pre-start `control node unavailable` case.
      */
     private relayReserveError;
+    /**
+     * True from just before the control libp2p node is created until
+     * {@link ControlDatabase.initialize} has settled — the connection gate's
+     * BRING-UP QUIET PERIOD (`membership-connection-gater.ts`), during which this
+     * node refuses every control connection in both directions.
+     *
+     * The invariant: the control database is built while this node holds zero
+     * control connections. Every same-party sibling connected in that window joins
+     * the Optimystic cohort the bring-up's block probes consult, and a sibling that
+     * has not yet replicated this node's `CadrePeer` row refuses them all — which
+     * fails `start()` outright and cannot be retried into convergence (writing the
+     * row that would clear the refusal needs the database being built).
+     *
+     * Cleared on FAILURE as well as success ({@link cleanup} clears it), so
+     * teardown is never gated.
+     */
+    private controlBringUpInFlight;
     /** Map of strandId -> sAppConfig for sAppId filtering and management */
     private sAppConfigs;
     /**
@@ -181,12 +208,25 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * In-memory delegate admission grants (see `delegate-admission.ts`): the
      * strand-node transport peerIds this party's members have announced over the
-     * strand-addr RPC, admitted at the CONNECTION level so a member's NAT'd
-     * strand node can hold a circuit-relay reservation on this node. Consulted
-     * ONLY by {@link admitInboundControlConnection}; the fail-closed per-stream
-     * gate ({@link authorizeInboundControlStream}) never honors it.
+     * strand-addr RPC, admitted at the CONNECTION and RESERVATION levels so a
+     * member's NAT'd strand node can hold a circuit-relay reservation on this
+     * node (without spending the unauthorized-reservation budget). Consulted
+     * ONLY by {@link admitInboundControlConnection} and
+     * {@link admitControlRelayReservation}; the fail-closed per-stream gate
+     * ({@link authorizeInboundControlStream}) never honors it.
      */
     private readonly delegateAdmission;
+    /**
+     * Bounded budget of concurrent circuit-relay reservations granted to peers
+     * this node cannot (yet) place as members — the boot-ordering window where a
+     * genuine sibling reserves before its `CadrePeer` row has replicated here.
+     * Consulted only by {@link admitControlRelayReservation} (the gater's
+     * `denyInboundRelayReservation` policy); authorized members and announced
+     * delegates are admitted before it and never counted. Cap from
+     * `network.unauthorizedRelayReservationCap` (default
+     * `MAX_UNAUTHORIZED_RELAY_RESERVATIONS`).
+     */
+    private readonly unauthorizedRelayReservations;
     /**
      * When this node last ANNOUNCED a delegate, keyed `<targetPeerId>\n<strandId>`
      * (the peer announced TO, not the delegate). Throttles
@@ -206,6 +246,36 @@ export declare class CadreNode implements SAppIdLookup {
      * stale stamp.
      */
     private readonly strandPeerAddrRefreshAt;
+    /**
+     * CROSS-PARTY strand-network addresses learned at formation, keyed by strandId — the
+     * responder's live strand addrs, carried back on the formation result
+     * (`FormationResultMessage.strandAddrs`) and recorded by {@link formStrand}.
+     *
+     * This is the ONLY cross-party discovery input there is. The strand-addr RPC that
+     * resolves a strand's addresses is membership-gated and answers own-party siblings
+     * only, so without this map a joiner's cohort seed for a two-party strand is empty and
+     * the mesh never forms.
+     *
+     * Read by {@link resolveCohortSeed} (launch + hibernation resume) and re-merged by
+     * every {@link refreshStrandPeerAddrs} pass — the re-merge is what keeps the entries
+     * alive past the peerStore's one-hour address expiry, since nothing can re-resolve
+     * them.
+     *
+     * IN-MEMORY and ONE-SHOT, deliberately (see `docs/strands.md`): the addresses die with
+     * the process, and a restarted initiator with no sibling running the strand is back to
+     * an empty seed until the durability work lands
+     * (`backlog/feat-cross-party-strand-addr-durability`). They are also never refreshed,
+     * so a responder whose relay reservation rotates before the initiator dials leaves a
+     * dead entry behind; recovery today is a fresh invitation.
+     *
+     * NOTE: entries are kept for the node's lifetime, including across a
+     * {@link stopStrand} — a stopped strand may be rediscovered by the watcher and must
+     * still get its seed. Each strand's list is capped at `MAX_STRAND_ADDRS`, but the
+     * number of KEYS is bounded only by the strands this node has ever formed as an
+     * initiator (not by time); if a node ever forms strands at scale, evict on
+     * `unpublishStrand` or cap the map.
+     */
+    private readonly crossPartyStrandAddrs;
     /**
      * Cold-start bootstrap dial targets: the owner-flagged peers of every seed
      * this node has applied, keyed by peer id, valued by the seed's multiaddr
@@ -240,6 +310,34 @@ export declare class CadreNode implements SAppIdLookup {
      * the party if it is ever stranded again.
      */
     private bootstrapPeerStore;
+    /**
+     * Node-local record of the party's enrolled-machine count (see
+     * `enrolled-machine-store.ts`), kept so the CONTROL node can declare a
+     * block-repair yardstick at bring-up. Constructed (or adopted from
+     * `config.enrolledMachines.store`) by {@link initializeEnrolledMachineStore};
+     * written by {@link refreshAuthorizedControlPeers}. Like
+     * {@link bootstrapPeerStore} it is deliberately NOT cleared by {@link cleanup},
+     * so it survives a stop()→start() cycle of the same node instance.
+     */
+    private enrolledMachineStore;
+    /**
+     * The enrolled-machine count this node's CONTROL libp2p node was (or will be)
+     * built with — read out of {@link enrolledMachineStore} during {@link start},
+     * before {@link createControlNode}, and consumed by
+     * {@link buildControlNodeOptions}.
+     *
+     * A captured FIELD rather than a live `store.count()` read, deliberately: the
+     * store moves as membership changes, but Optimystic froze the policy when the
+     * node was built, so this field is the honest answer to "what did this node
+     * actually declare?" and does not drift away from the running node. It is
+     * re-read on each {@link start}, which is what makes a stop()→start() cycle pick
+     * up a count recorded during the previous run.
+     *
+     * `undefined` — a brand-new node, an unreadable slot, or the ephemeral default
+     * store — means "this node does not know", which `controlClusterPolicy` answers
+     * with the frozen base policy itself.
+     */
+    private declaredEnrolledMachines;
     /** Initial self-registration timer (see {@link scheduleSelfRegistration}). */
     private selfRegistrationTimer;
     /** TTL heartbeat that re-publishes the self record before it goes stale. */
@@ -471,6 +569,32 @@ export declare class CadreNode implements SAppIdLookup {
      * must never enter this node's dial loop.
      */
     private initializeBootstrapPeerStore;
+    /**
+     * Construct (or adopt) the node-local enrolled-machine store and capture the
+     * count this run will declare into {@link declaredEnrolledMachines}.
+     *
+     * Synchronous for the same reason {@link initializeBootstrapPeerStore} is: an
+     * injected store has already loaded its persisted count by the time it is handed
+     * in (its `open` is the async part), and the in-memory default has nothing to
+     * load. Must run BEFORE {@link createControlNode} — that is the whole point of
+     * the record; see `enrolled-machine-store.ts`.
+     *
+     * The store instance is kept across stop()→start() (so a count recorded during
+     * the previous run is not lost with the ephemeral default), but the DECLARED
+     * count is re-read every time — which is how a restart applies a number the
+     * previous run learned.
+     *
+     * A store scoped to a different party is a configuration error, fail closed. It
+     * is only a repair hint, but a hint sized by a foreign party's membership is a
+     * number nobody chose, and the mismatch always means a miswired embedder.
+     */
+    private initializeEnrolledMachineStore;
+    /**
+     * The node-local enrolled-machine store (null before {@link start}) — what this
+     * node last knew about its party's size. Exposed for diagnostics and for a host
+     * that wants to show which repair yardstick the next launch will declare.
+     */
+    getEnrolledMachineStore(): EnrolledMachineStore | null;
     /**
      * The node-local cold-start bootstrap-peer store (null before {@link start}) —
      * the retained owner addresses {@link reconcileControlCohort}'s cold-start
@@ -503,6 +627,44 @@ export declare class CadreNode implements SAppIdLookup {
      */
     trustOwnerKeys(keys: Iterable<string>, source: Exclude<TrustSource, 'genesis'>): Promise<void>;
     private createControlNode;
+    /**
+     * The control libp2p node's Optimystic network name — ONE binding for every
+     * derivation from it (`db-p2p` namespaces all of the node's protocol ids as
+     * `/optimystic/<networkName>/...`), so the node options and the block-transfer
+     * protocol prefix the control backfill dials can never drift apart.
+     */
+    private controlNetworkName;
+    /**
+     * Arm the CONTROL network's peer-join block catch-up: push every block in the
+     * control database's own raw store to each newly connected AUTHORIZED member
+     * this runtime has not yet caught up. This is what physically replicates
+     * control blocks committed while the writer was alone — the named
+     * collection-header blocks written once at genesis above all, whose revision
+     * never moves again, so no later commit ever carries them to a member that
+     * joined after them. Without it, such a member that restarts offline reads
+     * the affected control tables as EMPTY, silently (`isMember()` answers false
+     * for peers it knew about before the restart).
+     *
+     * Unlike the per-strand instances (see `strand-instance-manager.ts`), pushes
+     * are gated on {@link isAuthorizedMember}, judged at push time: the control
+     * network's inbound connection gate deliberately admits non-members in
+     * several states (seed delivery to an un-enrolled node, an open enrollment
+     * window, an outstanding invitation, configured bootstrap/relay peers), and
+     * pushing the whole control store to such a peer would hand a stranger the
+     * party's entire membership, addresses and strand list. The receiving side
+     * needs no work of its own: `createLibp2pNode` registers the block-transfer
+     * handler on every node it builds, control node included, and this node's
+     * per-stream gate (`authorizeInboundControlStream`) covers the inbound
+     * direction. A denied peer is retried on its next `connection:open`, and —
+     * because the production join order is connect-then-authorize — on every
+     * committed membership change via {@link refreshAuthorizedControlPeers}'s
+     * `scheduleConnectedPeers()` call.
+     *
+     * No-ops (logged) when the embedder configured no control storage or the
+     * node exposes no key network — the backfill would have nothing to read or
+     * no way to dial.
+     */
+    private startControlBackfill;
     /**
      * The control database's cache-wrapped raw storage, resolved from
      * `config.storage.provider` on first use and then held in {@link controlStorage}
@@ -522,6 +684,27 @@ export declare class CadreNode implements SAppIdLookup {
      * operation count.
      */
     private resolveControlStorage;
+    /**
+     * Warn the operator when `network.announceAddrs` will silently cost this node the
+     * relay reachability it also configured.
+     *
+     * A non-empty announce set REPLACES everything libp2p advertises, so the
+     * `/p2p-circuit` address earned by a relay reservation is dropped from the node's
+     * advertised addresses even though the reservation itself is still held — peers
+     * behind NAT stop being able to reach it through that relay. Not an error: an
+     * operator whose relay slot is decorative may genuinely want only the announced
+     * address, so this reports and proceeds.
+     *
+     * Keyed off the RESOLVED listen addrs rather than `relayAddrs` alone, so a
+     * hand-written `/p2p-circuit` entry in `listenAddrs` — the same reservation by the
+     * longer route — is caught too.
+     *
+     * NOTE: the only direct `console.*` in this library — a boot-time operator warning, not a
+     * diagnostic trace (those use `debug`, which an operator never sees without `DEBUG=`). If a
+     * second such warning ever appears here, route both through a `CadreNodeEvents` entry the
+     * embedder surfaces instead of growing a console surface inside a library.
+     */
+    private warnIfAnnounceAddrsDiscardRelay;
     /**
      * Map this node's config onto the control network's libp2p node options.
      *
@@ -531,6 +714,15 @@ export declare class CadreNode implements SAppIdLookup {
      * only caller in production is `createControlNode`.
      */
     private buildControlNodeOptions;
+    /**
+     * Does this node's CONTROL libp2p run the circuit-relay server? An explicit
+     * `network.enableRelay` wins; otherwise storage-profile nodes default to on
+     * (better connectivity/uptime). Shared by {@link buildControlNodeOptions}
+     * (which configures the server from it) and
+     * {@link admitInboundControlConnection} (whose deny/admit-for-relay branch
+     * must agree with whether a reservation is even servable here).
+     */
+    private relayServerEnabled;
     /**
      * Decide whether an inbound CONTROL-network connection from `remotePeerId`
      * should be admitted — the policy behind the connection gater wired in
@@ -540,7 +732,7 @@ export declare class CadreNode implements SAppIdLookup {
      * `membership-connection-gater.ts` for the layer's rationale and the
      * stranger-open protocol allowlist).
      *
-     * Admits when ANY of:
+     * Returns `'admit'` when ANY of:
      *  1. a shared-baseline check admits ({@link admitControlPeerUnconditionally}
      *     — not running / DB torn down, absent-or-empty trusted-owner anchor, or
      *     configured bootstrap/relay infrastructure);
@@ -577,17 +769,69 @@ export declare class CadreNode implements SAppIdLookup {
      *    this node yet is denied even though the formation handler would have
      *    accepted it, exactly like the unreplicated-membership-row case below.
      *
+     * When every check falls through, the verdict depends on whether this node
+     * runs the circuit-relay server ({@link relayServerEnabled}): without one,
+     * `'deny'`; with one, `'admit-for-relay'` — a circuit-relay reservation is
+     * established by the reserving peer DIALING the relay, so a connection deny
+     * here kills the reservation, and that deny is NOT self-healing: an outbound
+     * reconcile re-dial re-establishes a data link, but no outbound dial can
+     * grant the remote peer a reservation, and a relay-only peer has no address
+     * of its own to dial back — the reservation IS its address. The gater admits
+     * such a connection, decides the reservation via
+     * {@link admitControlRelayReservation}, and drops the connection if no
+     * reservation is admitted in time (see `membership-connection-gater.ts` →
+     * "The relay-reservation seam").
+     *
      * NOTE: check 4/5 runs a control-DB read per inbound connection
      * (`listAuthorizedMembers`); connections are rare and cadres small, and this
      * layer is fail-open behind `ADMISSION_DECISION_TIMEOUT_MS`, so the live
      * read is safe here — unlike the per-stream gate, which must consult the
      * materialized {@link authorizedControlPeers} snapshot instead.
-     * NOTE: a sibling whose membership row has not yet replicated to
-     * this node is denied until the row converges (typically via the owner);
-     * either side's next outbound reconcile dial (outbound is never gated)
-     * re-establishes the link — self-healing, but visible as a transient deny.
+     * NOTE: on a relay-DISABLED node, a sibling whose membership row has not yet
+     * replicated here is denied until the row converges (typically via the
+     * owner); either side's next outbound reconcile dial (outbound is never
+     * gated) re-establishes the DATA link — self-healing for data, visible as a
+     * transient deny. That self-healing story never covered a reservation, which
+     * is exactly why the relay-enabled path above exists.
      */
     private admitInboundControlConnection;
+    /**
+     * Should `remotePeerId` be granted a circuit-relay reservation slot on this
+     * node's relay server? The policy behind the gater's
+     * `denyInboundRelayReservation` hook (see `membership-connection-gater.ts` →
+     * "The relay-reservation seam"); the circuit-relay server consults it per
+     * RESERVE request, so it is never called on a node whose relay server is off.
+     *
+     * Admits when ANY of:
+     *  1. a shared-baseline check admits ({@link admitControlPeerUnconditionally}
+     *     — not running / DB torn down, absent-or-empty trusted-owner anchor, or
+     *     configured bootstrap/relay infrastructure);
+     *  2. the peer holds a live delegate admission grant — a member's strand
+     *     node reserving here (see `delegate-admission.ts`); never counted
+     *     against the unauthorized budget;
+     *  3. the authorized-member set is empty (cold start) or the peer IS an
+     *     authorized member — members are never counted against the budget; or
+     *  4. the peer takes (or already holds) a slot in the bounded
+     *     unauthorized-reservation budget — the boot-ordering window where a
+     *     genuine member reserves before its `CadrePeer` row replicates here.
+     *     Cap via `network.unauthorizedRelayReservationCap` (0 = refuse every
+     *     unauthorized reservation).
+     *
+     * Every uncounted admission also RELEASES the budget slot the peer may hold
+     * from an earlier reservation taken while it was still unplaceable — a member
+     * that boots, reserves, and only then has its row replicate here would
+     * otherwise keep that slot spent for the rest of the entry's TTL.
+     *
+     * The connection gate's stranger carve-outs (an open enrollment window, an
+     * outstanding formation invitation) deliberately do NOT extend here: they
+     * exist so a stranger's SEED or FORMATION stream can ride a connection, and
+     * neither needs relay capacity. A genuine invitee that does need a relay slot
+     * takes one from the budget like any other unplaced peer, so an open window
+     * never becomes an unbounded grant of this node's forwarding capacity.
+     */
+    private admitControlRelayReservation;
+    /** Admit a reservation on the peer's own merits, giving back any budget slot it still holds. */
+    private admitReservationUncounted;
     /**
      * Hold the control-network inbound gate open for not-yet-authorized peers
      * until `untilEpochMs` (extends, never shrinks, an already-open window).
@@ -599,7 +843,8 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Record (or refresh) a delegate admission grant: `delegatePeerId` is the
      * transport peerId of `announcerPeerId`'s strand-`strandId` node, admitted
-     * at the CONNECTION level (all a circuit-relay reservation needs) for
+     * at the CONNECTION and RESERVATION levels (all a circuit-relay reservation
+     * needs, without spending the unauthorized-reservation budget) for
      * `DELEGATE_GRANT_TTL_MS`. Called by the strand-addr responder after its
      * authorized-membership gate has passed; public so tests can drive the
      * admission policy without a full strand launch. A re-announce for the same
@@ -677,6 +922,12 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * The SOLE caller is {@link drainMembershipGate}, which serializes refreshes —
      * so two reads can no longer settle out of order.
+     *
+     * Reads WITHOUT the transient-failure retry, deliberately: `ControlDatabase` drives
+     * this listener with its write lock HELD (`notifyMembershipChanged`), so a retrying
+     * read here would sleep its backoff holding the lock and stall every other local
+     * writer. Nothing is lost — this refresh already keeps the previous snapshot on
+     * failure and is re-driven by the next membership write and by the timed reconcile.
      */
     private refreshAuthorizedControlPeers;
     /**
@@ -737,6 +988,24 @@ export declare class CadreNode implements SAppIdLookup {
      * producing an unresolvable row.
      */
     private getSelfSigningKey;
+    /**
+     * Does the `Strand` row name THIS machine as its founder — i.e. is its
+     * `FounderOwnerKey` this node's own owner key (the key behind its PeerId)?
+     * A null/absent column (a consent-seated strand, or a hand-built row) and a
+     * node with no owner key both derive `false`: without a positive match this
+     * machine must attach, never bootstrap. Pure key derivation, no I/O — cheap
+     * enough for {@link launchStrand}'s tracked-instance early return.
+     *
+     * NOTE: reads "one owner key per machine" — the reference model, where the owner
+     * key IS the key behind the PeerId. Two machines running the SAME identity key
+     * would both derive `true` and each bootstrap on its own replica, which is the
+     * double-`Header` hazard this derivation exists to avoid. Unreachable today: that
+     * configuration also gives both machines one PeerId, which already breaks control
+     * networking well before any strand launches. Revisit if machines ever share an
+     * owner key while holding distinct transport identities — the derivation would
+     * then need a per-machine discriminator (the `CadrePeer` PeerId) on the row.
+     */
+    private isSelfFoundedRow;
     /**
      * The owner keypair (base64url Ed25519) derived from this node's resolved
      * identity key. In the single-key reference model the owner signing key is
@@ -787,8 +1056,49 @@ export declare class CadreNode implements SAppIdLookup {
      * Survivors are returned signaling (`/p2p-circuit`) first, filtered to
      * signaling-only when requested, as parsed `Multiaddr`s (unparsable addrs
      * dropped). Any gate failure yields an empty array rather than throwing.
+     *
+     * Every returned address is normalized to terminate in `/p2p/<peerId>` — see
+     * {@link normalizeDialAddrs} for why that invariant, not each dial site's own
+     * handling, is what keeps a mixed list from taking a whole peer offline.
      */
     resolvePeerAddrs(peerId: string, opts?: ResolveOpts): Promise<Multiaddr[]>;
+    /**
+     * Guarantee every address handed to a control-network dial terminates in
+     * `/p2p/<peerId>`, with no duplicates — the invariant every dial path
+     * downstream relies on.
+     *
+     * `libp2p.dial(addrs)` requires that the addresses in ONE dial either all name
+     * a peer id or none do; a list mixing a circuit address (which ends in
+     * `/p2p/<target>`) with a bare direct one (which ends in `/tcp/…`) makes that
+     * call throw, and the whole peer is then silently skipped rather than one bad
+     * address.
+     *
+     * Applied by ALL THREE sources of control-dial candidates, so no call site
+     * invents its own rule and none can produce a mixed list: the signed record
+     * ({@link resolvePeerAddrs}), the libp2p address book
+     * ({@link peerStoreAddrs}), and a seed's retained owner addresses
+     * ({@link bootstrapDialAddrs}).
+     *
+     * An address naming a DIFFERENT trailing peer id is dropped: it does not reach
+     * `peerId`, so it does not belong in this peer's candidate list (libp2p's own
+     * dial queue filters the same shape out one layer lower).
+     */
+    private normalizeDialAddrs;
+    /**
+     * One address bound to `peerId`, or `null` when it cannot be — logged either
+     * way, never thrown, so every caller's list-shaping stays total.
+     *
+     * Used both to normalize addresses this node DIALS (a `CadrePeer` row, a
+     * seed-supplied bootstrap addr) and to normalize the ones it ANNOUNCES
+     * ({@link getStrandMultiaddrs}); the rule is the same either way — an address
+     * that does not reach `peerId` is not an address for `peerId`.
+     *
+     * `withTrailingPeerId` encapsulates `/p2p/<peerId>`, which throws on a peer id
+     * that does not parse. Unreachable for a `CadrePeer` row (the binding gate
+     * above parsed it already) and for our own node's id, reachable for a
+     * seed-supplied one ({@link bootstrapDialAddrs}).
+     */
+    private bindAddrToPeer;
     /** Parse multiaddr strings, dropping (and logging) any that fail to parse. */
     private parseMultiaddrs;
     /**
@@ -875,6 +1185,16 @@ export declare class CadreNode implements SAppIdLookup {
      * Cold-start fallback: the libp2p peerStore multiaddrs for `peerId` (seeded by
      * {@link SeedBootstrapService.applySeed}). Returns `[]` on a missing entry or any
      * parse/lookup failure — never throws.
+     *
+     * Normalized through {@link normalizeDialAddrs} for the same reason
+     * {@link resolvePeerAddrs} is, and with more cause: the address book hands back
+     * a list that is inherently MIXED. `@libp2p/peer-store`'s
+     * `dedupeFilterAndSortAddresses` strips a trailing `/p2p/<peerId>` only when
+     * that id is the address's FIRST `/p2p/` component, so a direct address
+     * round-trips bare while a relayed one — whose first `/p2p/` names the relay —
+     * keeps its suffix (the same asymmetry `peer-addr-book.ts`'s `addrKey` exists
+     * to absorb). Feeding both to one `dial()` is exactly the
+     * `InvalidParametersError` that skipped the whole peer.
      */
     private peerStoreAddrs;
     /**
@@ -927,11 +1247,12 @@ export declare class CadreNode implements SAppIdLookup {
      * Bind a bootstrap peer's seed addresses to its peer id, so the dial
      * authenticates the peer it is aiming at rather than trusting whoever answers.
      *
-     * An address that already carries `/p2p/<id>` must carry THIS peer's id or it
-     * is dropped (a seed that disagrees with itself is not a dial target); one
-     * that carries none — an `addressOverrides`-published record, say — gets the
-     * id encapsulated. Unencapsulatable addresses are dropped rather than dialed
-     * bare.
+     * The same {@link normalizeDialAddrs} rule the resolved and address-book paths
+     * use, on the third and last source of control-dial candidates: an address that
+     * already terminates in `/p2p/<id>` must carry THIS peer's id or it is dropped
+     * (a seed that disagrees with itself is not a dial target); one that does not —
+     * a bare listen addr, or a relay hop with the destination missing — gets the id
+     * encapsulated; an unencapsulatable one is dropped rather than dialed bare.
      */
     private bootstrapDialAddrs;
     /** Dial one cold-start bootstrap peer, best-effort. Returns whether it connected. */
@@ -1180,6 +1501,12 @@ export declare class CadreNode implements SAppIdLookup {
     expireDeviceToken(peerId: string): Promise<void>;
     private handleStrandAdded;
     private handleStrandRemoved;
+    /**
+     * Return this node to its pre-{@link start} state. The ONE teardown — `stop()` and
+     * a failed `start()` both come here, so anything a stopped node must not still be
+     * doing belongs in this method and not in `stop()`. `stop()` adds only the
+     * `control:disconnected` emit, which a never-connected start has no edge for.
+     */
     private cleanup;
     private handleStrandIdle;
     /**
@@ -1202,8 +1529,8 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort input
      * first: the discovery seed may have grown since the strand last ran. Shared by
-     * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so
-     * both apply the same fresh seed resolution. `resumeStrand` is idempotent
+     * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so both
+     * apply the same fresh resolution. `resumeStrand` is idempotent
      * (returns the live instance unchanged) as a backstop against double-resume.
      */
     private resumeStrandRuntime;
@@ -1264,6 +1591,14 @@ export declare class CadreNode implements SAppIdLookup {
      * Add a strand with its sApp configuration.
      * The hosting application must provide the sApp schema when creating a strand.
      *
+     * This is the ATTACH half only — it starts the local instance and never publishes the
+     * `Strand` row. A joiner (the row arrived over the control network) wants exactly this; a
+     * FOUNDER wants {@link foundStrand}, which publishes and attaches in one resumable call.
+     * With no explicit `founder` flag, founder-ness is derived from the row's
+     * `FounderOwnerKey` (see {@link StrandConfig.founder}) — so attaching a row THIS machine
+     * published (e.g. re-attaching its own orphan after a restart) founds it, and attaching
+     * anyone else's row joins, without the caller needing to know which it is.
+     *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
      * automatic relaunch need it. So once the strand's row is visible on the control
@@ -1278,16 +1613,41 @@ export declare class CadreNode implements SAppIdLookup {
      * owner identity, so other cadre members discover it via control-network
      * sync (their {@link StrandWatcher} fires `strand:discovered`).
      *
-     * This is the owner-signed `Strand` INSERT that {@link addStrand}
-     * deliberately omits: `addStrand` only starts the LOCAL strand instance,
-     * whereas publishing makes the strand visible cadre-wide. A typical creator
-     * does both (start locally + publish); a discovering peer only does
-     * `addStrand` (the row already exists).
+     * **Founding a strand is TWO steps** — this one (publish the row cadre-wide) and
+     * {@link addStrand} (start the local instance, `founder: true` to write the strand's
+     * `Header`/founding membership). `addStrand` deliberately omits the insert: it only
+     * starts the LOCAL instance, whereas publishing makes the strand visible cadre-wide. A
+     * discovering peer only does `addStrand` (the row already exists). Callers founding a
+     * strand should use {@link foundStrand}, which performs both steps and is safe to
+     * re-run — hand-rolling the pair is what left strands half-founded when an app was
+     * killed between them.
+     *
+     * **Idempotent for identical content.** A live row whose `(Type, MemberPrivateKey)` match
+     * the arguments is the state this call would have produced, so the call logs and returns
+     * that row instead of writing — a publish interrupted after it committed can be repeated.
+     * DIFFERENT content on the same id throws, naming the columns that differ, rather than
+     * surfacing the raw `UNIQUE constraint failed: Strand.Id`: silently accepting it would
+     * let a retry reopen a closed strand or swap the key gating its reads. The read and the
+     * insert are not atomic, so a concurrent founder (two machines of one party, same id) is
+     * caught on the insert's uniqueness rejection and resolved the same way — re-read, no-op
+     * on a match, rethrow otherwise. Never an overwrite either way.
+     *
+     * A tombstoned strand is NOT resurrected here: {@link unpublishStrand} deletes the row, so
+     * the idempotent branch is unreachable and the ordinary publish path re-seats it, exactly
+     * as that method documents.
+     *
+     * **Already stuck on `UNIQUE constraint failed: Strand.Id`?** The row is already published
+     * — attach, do NOT republish: `addStrand` (or {@link foundStrand}) with the id and, for a
+     * closed strand, the `MemberPrivateKey` read back from the row. `unpublishStrand` + a
+     * fresh publish also clears it for an OPEN strand, but is destructive for a closed one
+     * (the key exists nowhere else). No app-data wipe is needed for either.
      *
      * The insert is signed with the ed25519 key behind this node's PeerId — which
      * {@link ed25519KeyPairFromLibp2p} also exposes as the node's owner keypair,
-     * so peer identity and owner key are one and the same. That key must be
-     * enrolled in `OwnerKey` (e.g. via {@link ControlDatabase.ensureOwnerKey}
+     * so peer identity and owner key are one and the same. That key is also persisted on the
+     * row as `FounderOwnerKey` (the schema pins the column to the verified signer), which is
+     * what later lets any launch derive "this machine is the founder" from the row alone.
+     * The key must be enrolled in `OwnerKey` (e.g. via {@link ControlDatabase.ensureOwnerKey}
      * at genesis) or the schema's `Strand.AuthorizedInsert` constraint rejects the write.
      * Failing loudly here is intentional: a silently-unpublished strand would run
      * as a local-only island that no peer could ever discover or join.
@@ -1296,10 +1656,62 @@ export declare class CadreNode implements SAppIdLookup {
      *   {@link addStrand}).
      * @param type - `'o'` for open (default) or `'c'` for closed.
      * @param memberPrivateKey - Optional membership key for a closed strand.
-     * @throws if the node is not started, exposes no owner signing key, the id is blank, or
-     *   the control DB rejects the (unauthorized) insert.
-     */
-    publishStrand(strandId: string, type?: 'o' | 'c', memberPrivateKey?: string): Promise<void>;
+     * @returns The live `Strand` row — the one just inserted, or the matching one already
+     *   there. A closed strand's caller should carry THIS row's `MemberPrivateKey` forward:
+     *   on a repeat it is the stored key, not the argument.
+     * @throws if the node is not started, exposes no owner signing key, the id is blank, a
+     *   row with the same id holds different content, or the control DB rejects the
+     *   (unauthorized) insert.
+     */
+    publishStrand(strandId: string, type?: 'o' | 'c', memberPrivateKey?: string): Promise<StrandRow>;
+    /**
+     * Found a strand — publish its row cadre-wide AND start the local instance as its
+     * founder — in one resumable call. The single entry point for creating a strand; a
+     * caller joining one someone else founded uses {@link addStrand} alone.
+     *
+     * Safe to re-run from any point of interruption, which hand-rolling
+     * {@link publishStrand} + {@link addStrand} is not. Either half can already have
+     * happened:
+     *
+     * - **row already published** → the stored row is adopted rather than re-published, so a
+     *   run killed after the insert committed no longer dies on
+     *   `UNIQUE constraint failed: Strand.Id`. For a closed strand the row's STORED
+     *   `MemberPrivateKey` wins over `config.memberPrivateKey`: a caller that mints a key per
+     *   attempt (as the reference apps do) would otherwise present a key that does not match
+     *   the membership already seated in the strand.
+     * - **instance already running** → the tracked instance is returned, and — because the
+     *   `Strand` row records its publishing machine (`FounderOwnerKey`) — a founder request
+     *   against an instance that was first launched as a joiner now runs the (idempotent,
+     *   insert-if-absent) founder bootstrap on it rather than silently skipping it
+     *   ({@link StrandInstanceManager.foundExistingStrand}). So a strand that something else
+     *   attached first — the reference RN app's `strand:discovered` handler after a restart,
+     *   or this node's own {@link StrandWatcher} poll winning `launchStrand`'s
+     *   `resolveCohortSeed` window — still ends up with its `Strand.Header` written.
+     *
+     * Founder-ness is resolved FROM THE ROW, not assumed: this machine founds iff the
+     * resolved row's `FounderOwnerKey` is its own owner key. A fresh publish records this
+     * machine, so the common path founds; a machine that lost a concurrent founding race to
+     * a sibling adopts the sibling's row and ATTACHES instead — deliberately, since two
+     * machines bootstrapping the same strand on separate replicas is the double-`Header`
+     * hazard. The returned {@link FoundStrandResult.founded} says which happened.
+     *
+     * `Type` is compared, not adopted: a stored row of the other type means the caller and
+     * the control plane disagree about what this strand IS, so it throws.
+     *
+     * @returns The instance AND the row the strand actually runs under — read the membership
+     *   key from the returned row, not from a freshly minted one ({@link FoundStrandResult}).
+     * @throws if the node is not started, the id is blank, a published row of the same id has
+     *   a different `Type`, or either half rejects.
+     */
+    foundStrand(config: FoundStrandConfig): Promise<FoundStrandResult>;
+    /**
+     * Resume onto an already-published `Strand` row: keep its stored content, reject a type
+     * disagreement. The stored `MemberPrivateKey` is authoritative — see {@link foundStrand}
+     * for why a caller-minted key must lose here (and why that is NOT the same rule as
+     * {@link publishStrand}'s, which throws on a key mismatch because it is being asked to
+     * WRITE that key, not to resume onto what already exists).
+     */
+    private adoptPublishedStrand;
     /**
      * Remove this party's `Strand` row from the shared control database — the owner-signed
      * inverse of {@link publishStrand}.
@@ -1451,14 +1863,25 @@ export declare class CadreNode implements SAppIdLookup {
      * seed, starts the strand, and registers it with the hibernation manager
      * before emitting `strand:started`.
      *
-     * Idempotent no-op when the strand manager already tracks `strand.Id` — the
-     * ordinary founding sequence is `addStrand` (starts it locally) followed by
-     * `publishStrand` (makes it visible), so this node's own `StrandWatcher`
-     * rediscovers a row it already started and calls this again via
-     * `handleStrandAdded`. Without the guard that re-entry would resolve a fresh
+     * Founder-ness: an explicit `founder` argument wins (the formation/responder flows pass
+     * one deliberately — their consent-seated rows carry a null `FounderOwnerKey`); when
+     * unset it is DERIVED from the row, so the control-discovered path
+     * (`handleStrandAdded`) and a restart's re-attach found this machine's own strands
+     * without the caller having to know. The derivation is pure key comparison — no I/O.
+     *
+     * Idempotent when the strand manager already tracks `strand.Id` — the watcher
+     * rediscovers a row this node already started and calls this again via
+     * `handleStrandAdded`; without the guard that re-entry would resolve a fresh
      * (already-connected) cohort seed and re-emit `strand:started` for an
      * instance that never stopped. The guard runs before the cohort-seed RPC
-     * fan-out, so a rediscovery costs nothing beyond the map lookup.
+     * fan-out, so a rediscovery costs nothing beyond the map lookup plus the (pure)
+     * founder derivation. NOT a silent no-op any more when the launch resolves as a
+     * FOUNDER: the tracked instance may have been launched first as a joiner (an app
+     * attach, or this node's own watcher poll winning the `resolveCohortSeed` window
+     * below), which used to drop the founder request and leave the strand headerless —
+     * now the tracked instance is founded in place
+     * ({@link StrandInstanceManager.foundExistingStrand}), waking it first if quiesced
+     * so the bootstrap actually runs before this resolves.
      */
     private launchStrand;
     /**
@@ -1488,6 +1911,13 @@ export declare class CadreNode implements SAppIdLookup {
      * for a relay we are not yet connected to.
      */
     private resolveCohortSeed;
+    /**
+     * The own-party half of {@link resolveCohortSeed}: strand-network addresses resolved
+     * from CONNECTED cohort siblings over the control-mesh strand-addr RPC, doubling as
+     * the delegate announcement when `delegatePeerId` is given. Empty when the control DB
+     * or node is absent (not yet started / torn down).
+     */
+    private resolveSiblingSeed;
     /**
      * The co-cadre siblings worth sending a strand-addr RPC to right now: cohort
      * members (self excluded) we already hold an open control connection to. They
@@ -1521,11 +1951,25 @@ export declare class CadreNode implements SAppIdLookup {
     private connectedSiblingTargets;
     /**
      * The circuit relays this node's strand nodes would reserve through: the
-     * union of the RESOLVED listen addrs' circuits — a hand-written
-     * `network.listenAddrs` circuit entry or a `network.relayAddrs` entry, which
-     * the strand node inherits verbatim either way — and the control node's own
-     * live `/p2p-circuit` multiaddrs (a reservation this node discovered rather
-     * than configured).
+     * union of CONFIGURED relays — `network.relayAddrs`, plus any hand-written
+     * `network.listenAddrs` circuit entry, both of which a strand node inherits
+     * verbatim — and the control node's own live `/p2p-circuit` multiaddrs (a
+     * reservation this node discovered rather than configured).
+     *
+     * The CONFIGURED half reads `network.relayAddrs` and `network.listenAddrs`
+     * directly rather than going through {@link resolveListenAddrs}: the control
+     * node's resolution takes the `'search'` route, whose bare `/p2p-circuit` entry
+     * names no relay, so a configured relay would be unannounceable here until this
+     * node's own reservation landed — and the announce must be in place BEFORE a
+     * strand node dials its reservation, since the relay's membership gate does not
+     * know the strand's derived peerId (see delegate-admission.ts). Configuration is
+     * authoritative; the live multiaddrs only ADD relays nobody configured.
+     *
+     * The `listenAddrs` half is now unreachable on a control node — `relay-addrs.ts`
+     * rejects a hand-written `<relay>/p2p-circuit` listen entry outright, because the
+     * bring-up quiet period denies the dial that listener makes from inside
+     * `libp2p.start()`. Kept because it costs one spread and this is the one place
+     * that would silently stop announcing if that rejection is ever relaxed.
      *
      * NOTE: a relay the STRAND node discovers on its own (autorelay — in neither
      * source) gets no announcement, and a membership-gated one will deny it; fine
@@ -1587,9 +2031,18 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private refreshStrandPeerAddrs;
     /**
-     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, then
-     * merge their answers into this strand's address book. Errors are logged and
-     * swallowed so one strand's failure never costs the others their refresh.
+     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, union their
+     * answers with this strand's cross-party contact addresses, and merge the lot into the
+     * strand's address book. Errors are logged and swallowed so one strand's failure never
+     * costs the others their refresh.
+     *
+     * `targets` may be EMPTY — a solo node, or one whose only control peers are strangers.
+     * The cross-party addresses still have to be re-merged in that case: they were learned
+     * at formation and can never be re-resolved, so this periodic re-merge is the ONLY
+     * thing standing between them and the peerStore's one-hour expiry. A strand with
+     * neither a sibling to ask nor a contact entry does nothing and leaves its throttle
+     * unstamped, so the next reconcile tick retries rather than sitting out the whole
+     * refresh interval having done nothing.
      */
     private refreshOneStrandPeerAddrs;
     /**
@@ -1610,6 +2063,15 @@ export declare class CadreNode implements SAppIdLookup {
      * handshake, and a bad entry costs one failed dial that ages out at the
      * peerStore's one-hour expiry. No new gating here — cross-party strand trust is
      * `backlog/strand-network-nat-relay-reachability`.
+     *
+     * NOTE: one input does NOT age out — the cross-party addresses a formation
+     * carried back ({@link crossPartyStrandAddrs}). Nothing can re-resolve them, so
+     * {@link refreshStrandPeerAddrs} re-merges the same stored list every pass, which
+     * also means a junk entry from a responder survives for the node's lifetime rather
+     * than an hour. Bounded to {@link MAX_STRAND_ADDRS} per strand, from a party this
+     * node deliberately formed a strand with, and still authority-free — so the
+     * exposure is a handful of failed dials, not a trust hole. Evict on
+     * `unpublishStrand` if that ever stops being an acceptable price.
      */
     private mergeStrandPeerAddrs;
     /**
@@ -1719,16 +2181,48 @@ export declare class CadreNode implements SAppIdLookup {
      * Get the control network node (for advanced use)
      */
     getControlNode(): Libp2p | null;
+    /**
+     * The boot-path half of {@link reserveRelays}: reserve through every
+     * `network.relayAddrs` entry, or fail `start()`.
+     *
+     * WHY IT RUNS HERE, AT THE END. `network.relayAddrs` used to resolve to a
+     * CONFIGURED circuit listener, which libp2p dials from inside `libp2p.start()`
+     * — so the relay was already a connected peer, and therefore already in this
+     * node's Optimystic cohort, before `ControlDatabase.initialize()` ran. Building
+     * that database is a long chain of cohort-consulting block probes (catalog
+     * hydration, then one per table, then the indexes), and a sibling that has not
+     * yet replicated this node's `CadrePeer` row correctly refuses every one of
+     * them, so bring-up died on `BlockUnavailableError` — deterministically, on
+     * every boot of a relay-only node. Retrying could not converge either: the
+     * condition that clears the refusal is this node's own row reaching the
+     * sibling, and writing that row needs the database the retry is building.
+     *
+     * So the invariant is ordering, not retrying: the control database is built
+     * while this node holds ZERO control connections (a cohort of one, entirely
+     * local), and only then does it reach out. Everything above in {@link start}
+     * has completed by the time this runs.
+     *
+     * BUDGET: the supervisor's first attempt — `relay-reservation.ts`'s
+     * `DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, 10 s — is what `start()` waits on — deliberately the module default rather
+     * than a boot-specific one. A healthy dial-plus-reserve is sub-second even over
+     * a WAN, so 10 s is slack for a slow link; going much longer would make a dead
+     * relay indistinguishable from a hung start, and much shorter would fail nodes
+     * on links that were merely slow. The retries carry on in the background after
+     * this resolves, exactly as they do for a {@link reserveRelays} caller.
+     */
+    private driveControlRelayReservation;
     /**
      * Start keeping a relay reservation: dial the given relay(s) from the control
      * node, ask the first one that answers for a reservation slot, wait until the
      * resulting `/p2p-circuit` address makes this node dialable — and keep a
      * supervisor running that re-drives whenever the reservation is later lost.
      *
-     * For nodes that listen on the bare `/p2p-circuit` SEARCH addr (a browser tab)
-     * rather than a configured `network.relayAddrs` circuit listener — see
-     * `relay-reservation.ts` for why the two are alternatives and why configuring
-     * both is a regression. Opt-in: nothing calls this for the CLI/host nodes.
+     * The FAIL-SOFT entry point, for a caller that discovers its relay at runtime
+     * (a browser tab, a host UI). A node that names `network.relayAddrs` gets the
+     * same drive from {@link driveControlRelayReservation} at the end of
+     * {@link start}, which is fail-fast instead. Both fill the pending reservation
+     * the bare `/p2p-circuit` search listener registered; calling this afterwards
+     * simply replaces the supervisor with one over the new list.
      *
      * Resolves once the FIRST attempt has settled, exactly as it did when it drove
      * once; the retries continue in the background until {@link stop} or the next
@@ -1790,13 +2284,40 @@ export declare class CadreNode implements SAppIdLookup {
      * Push the multiaddrs that future invites should advertise. Pass `null` to
      * revert to the libp2p-reported addresses (the default). The host calls this
      * at spawn and on every NAT change.
+     *
+     * Entries need NOT carry a `/p2p/<peerId>` suffix — {@link resolveInviteAddresses}
+     * appends this node's own before anything publishes or dials them (see
+     * {@link normalizeSelfAddrs}). Passing them suffixed is equally fine.
      */
     setInviteAddresses(addresses: string[] | null): void;
     /**
      * Resolve the addresses to embed in invites. Prefers pushed addresses, then
-     * any config-supplied resolver, then the libp2p-observed multiaddrs.
+     * any config-supplied resolver, then the libp2p-observed multiaddrs. The two
+     * app-supplied sources are normalized onto `/p2p/<self>` (see
+     * {@link normalizeSelfAddrs}) so neither hook has to remember the suffix;
+     * libp2p's own addresses already carry it.
      */
     private resolveInviteAddresses;
+    /**
+     * Normalize addresses an app handed us for THIS node onto `/p2p/<self>`, the
+     * same invariant {@link normalizeDialAddrs} enforces on the way out.
+     *
+     * `setInviteAddresses` (the admin API `PUT /admin/invite-addresses`) and
+     * `network.inviteAddressResolver` both take arbitrary strings, and whatever
+     * they return ends up in this node's published `CadrePeer` record — so ONE
+     * unsuffixed entry from either hook is enough to give every sibling in the
+     * party a mixed candidate list for this peer. Establishing the suffix here,
+     * where those strings enter the system, means neither hook has to know the
+     * rule; `cadre-host`'s `buildInviteAddresses` already appends it, and
+     * re-normalizing an already-suffixed address is a no-op.
+     *
+     * Unparsable and other-peer-addressed entries are passed through untouched
+     * rather than dropped: publication is not the place to police an address's
+     * validity, and {@link resolvePeerAddrs} already drops both on the read side.
+     * Before `start()` resolves an identity there is no peer id to append, so the
+     * list is returned as given.
+     */
+    private normalizeSelfAddrs;
     /**
      * Enumerate the cadre's `CadrePeer` membership — the ADDRESSABLE surface (see
      * {@link isMember}). Rows whose stamp is retired in `CadreControl.Revocation`
@@ -1853,8 +2374,13 @@ export declare class CadreNode implements SAppIdLookup {
      * legit member goes un-authorized on readers that only pin the new key. Full
      * rotation handling (re-vouch on rotate) is the
      * `flip-strand-membership-rotation-known-gap` work, not this predicate's.
+     *
+     * @param retry - Whether the underlying membership read may retry a transient cluster
+     *   failure. Only {@link refreshAuthorizedControlPeers} passes `false`, because it runs
+     *   as the control database's membership listener with that database's write lock held;
+     *   see its comment.
      */
-    listAuthorizedMembers(): Promise<Array<{
+    listAuthorizedMembers(retry?: boolean): Promise<Array<{
         peerId: string;
         multiaddr: string | null;
     }>>;
@@ -1940,6 +2466,23 @@ export declare class CadreNode implements SAppIdLookup {
      * best-effort (a failed read keeps the previous snapshot); never rejects.
      */
     refreshMembershipGate(reason?: string): Promise<void>;
+    /**
+     * Re-materialize a CLOSED strand's revoked-peer deny set now, and hang up any
+     * connected peer it newly covers — the strand-side counterpart to
+     * {@link refreshMembershipGate}.
+     *
+     * Unlike that one, NOTHING calls this automatically: strand membership is
+     * written through the strand's own `Database` handle
+     * (`strand-membership-writer.ts`), which raises no notification this runtime
+     * can hook, and a revocation that arrives by REPLICATION raises none either.
+     * The gate therefore polls (default 30 s). An app that has just called
+     * `revokeMember` or `leaveStrand` should follow the write with this call so
+     * the cut is immediate rather than up to one poll interval late.
+     *
+     * Quiet no-op for a strand that is not running, is quiesced, is open, or has
+     * the gate disabled. Never rejects; resolves once the sweep has finished.
+     */
+    refreshRevocationEnforcement(strandId: string): Promise<void>;
     /**
      * The single in-flight refresh loop behind {@link refreshMembershipGate}: read
      * until the stale flag stays clear, then release the slot.
@@ -2086,6 +2629,17 @@ export declare class CadreNode implements SAppIdLookup {
      * @returns The member key and strand info if successful
      */
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
+    /**
+     * Remember the responder's strand-network addresses for a strand this node just
+     * formed, so the strand's discovery seed has something to work with when the app
+     * launches it (see {@link crossPartyStrandAddrs}).
+     *
+     * Scoped strictly to `strandId`: these addresses reach ONE strand node of ONE other
+     * party and must never seed another strand's mesh or the control peerStore. An empty
+     * list is recorded as no entry at all rather than an empty one, so a later formation
+     * against the same strand that DOES disclose addresses is not shadowed.
+     */
+    private recordCrossPartyStrandAddrs;
     /**
      * Encode an open invitation for out-of-band delivery (QR, link, etc.).
      */