@serfab/cadre-core 0.13.0 → 1.1.0

package/dist/cadre-node.d.ts

@@ -1,11 +1,12 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
-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 { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, 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 { type ControlCohortReconcileResult } from './control-cohort.js';
 import { EnrollmentService } from './enrollment.js';
 import { ControlDatabase } from './control-database.js';
 import { SeedBootstrapService } from './seed-bootstrap.js';
@@ -91,10 +92,11 @@ export declare class CadreNode implements SAppIdLookup {
     private _running;
     /**
      * The control database's own raw storage (cache-wrapped), resolved once per
-     * `start()` and released in {@link cleanup}. Owning it is what keeps
-     * `config.storage.provider('control')` a once-per-runtime call: a `stop()` then
-     * `start()` cycle on this object re-resolves against a live cache, and never
-     * orphans the previous wrapper's registration in the shared cache pool.
+     * `start()` and released in {@link cleanup}. Owning it is what keeps the
+     * provider call for the control scope — `controlStorageScope(partyId)`, see
+     * `storage-scope.ts` — a once-per-runtime call: a `stop()` then `start()` cycle
+     * on this object re-resolves against a live cache, and never orphans the
+     * previous wrapper's registration in the shared cache pool.
      */
     private controlStorage;
     /**
@@ -150,6 +152,14 @@ export declare class CadreNode implements SAppIdLookup {
     private controlBringUpInFlight;
     /** Map of strandId -> sAppConfig for sAppId filtering and management */
     private sAppConfigs;
+    /**
+     * Strands the control network advertises that no local sAppConfig claims — the
+     * backlog behind `strand:discovered`. Maintained in {@link handleStrandAdded}
+     * (added), {@link addStrand} (claimed), {@link detachStrand} (stopped or its
+     * control row vanished) and {@link cleanup}. Read through
+     * {@link getDiscoveredStrands}.
+     */
+    private discoveredStrands;
     /**
      * Most-recently pushed invite addresses (see {@link setInviteAddresses}).
      * When non-null these take priority over `libp2pNode.getMultiaddrs()` when
@@ -277,37 +287,89 @@ export declare class CadreNode implements SAppIdLookup {
      */
     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
-     * strings (parsed lazily, at dial time). Written by
-     * {@link recordSeedBootstrapPeers}; read only by
-     * {@link dialColdStartBootstrap} while the control database still has no
-     * siblings to dial.
+     * PENDING strand membership invitations learned at formation, keyed by strandId — the
+     * single-use `Strand.Invite` credential a closed-strand formation result carried back
+     * ({@link FormStrandResult.membershipInvite}), waiting for this node's strand bring-up
+     * to redeem (`consumeInvite` seats the `Strand.Member` row under this party's own key
+     * — the `strand-node-binds-member-peer` half of the party-identity chain).
+     *
+     * IN-MEMORY, deliberately, like {@link crossPartyStrandAddrs}: a restarted joiner
+     * re-forms from scratch anyway (durability is
+     * `backlog/feat-cross-party-strand-addr-durability`'s problem), and re-forming issues
+     * a fresh invitation. A re-formation against the same strand REPLACES the entry — the
+     * fresh invitation supersedes one that may have expired. The party key the invitation
+     * admits, by contrast, IS persisted (`StrandPartyKey`, seated by
+     * {@link adoptFormationMembershipInvite} before the entry lands here), so a lost
+     * invitation never orphans an identity.
+     *
+     * INVALIDATION is owned by the strand's bring-up membership reconciler
+     * (`strand-membership-reconciler.ts`, wired via `StartStrandConfig.pendingMembershipInvite`
+     * in {@link launchStrand}): it deletes the entry once the invitation is redeemed, burned
+     * against an already-seated member, or found dead (expired / cancelled / consumed
+     * elsewhere / the strand sealed). Until the strand is actually launched here the entry
+     * just waits.
+     *
+     * NOTE: entries live for the node's lifetime (one small pair per formed closed
+     * strand), the same unbounded-keys tripwire {@link crossPartyStrandAddrs} documents —
+     * if a node ever forms strands at scale, evict alongside that map.
+     */
+    private readonly pendingMembershipInvites;
+    /**
+     * Founder launches refused because the strand was founded before the per-party
+     * identity split (`PreSplitStrandIdentityError`), keyed by strandId. Read by
+     * {@link issueStrandMembershipInvite}, which rethrows the recorded error so a bound
+     * redemption against the strand is rejected as "must be recreated" — not told to retry
+     * because the runtime is not live (a refused fresh launch leaves none) or failed by the
+     * `Strand.Invite` gate (a refused in-place founding leaves a joiner instance up whose
+     * party key is no manager).
+     *
+     * Written and cleared by {@link launchStrand}; also cleared by {@link detachStrand},
+     * {@link unpublishStrand} and {@link cleanup}, so a recreated id starts clean.
+     * In-memory: after a restart the next founder launch of the strand records it again;
+     * until then issuance still reads the fingerprint off the live rows whenever a runtime
+     * is up — only a strand with no runtime at all answers retryably meanwhile.
+     */
+    private readonly strandLaunchRefusals;
+    /**
+     * Dial targets learned out of band, keyed by peer id, valued by the multiaddr
+     * strings this node was handed (parsed lazily, at dial time). Two writers:
+     * {@link recordSeedBootstrapPeers} retains the owner-flagged peers of every seed
+     * this node applies, and {@link addDrone} retains the addresses of every node
+     * this node adds. Two readers: {@link dialColdStartBootstrap} dials every entry
+     * while the control database still has no siblings, and
+     * {@link resolveControlDialAddrs} falls back to a sibling's entry when neither
+     * its signed record nor the address book yields an address.
      *
      * A STORE rather than a plain map (see `bootstrap-peer-store.ts`), because the
      * targets must outlive the process: a node seeded into a party it could not
      * reach has nothing else on disk naming that party's addresses (`applySeed`
      * writes no control row, and `CadrePeer` fills in only after a connection
      * succeeds), so an in-memory-only set left it stranded permanently across a
-     * restart. Constructed (or adopted from `config.bootstrapPeers.store`) by
+     * restart. An owner that added a node it cannot be dialed by is in the same
+     * position: the added node's row stays unsigned, so unresolvable, until that
+     * node self-publishes over a connection only the owner can open. Constructed (or
+     * adopted from `config.bootstrapPeers.store`) by
      * {@link initializeBootstrapPeerStore} during {@link start}; deliberately NOT
      * cleared by {@link cleanup}, so it survives a stop()→start() cycle of the same
      * node instance — same lifecycle as {@link trustedOwnerStore}. Durability
-     * depends on the injected backend: Node gets a file-backed store from the CLI,
-     * RN/browser stay ephemeral for now.
+     * depends on the injected backend; the default is in-memory.
      *
      * Deliberately NOT the libp2p peer store, which {@link peerStoreAddrs} already
      * reads for the steady-state path. The peer store is shared with everything
      * libp2p discovers, so "dial every entry" would grow into dialing arbitrary
      * discovered peers as the node lives longer; this store holds exactly the peers
-     * an owner-signed, trust-anchored seed nominated as owners. `applySeed` merges
-     * the same addresses into the peer store as well, so the two never disagree —
-     * this one is just the precisely-scoped subset.
+     * an owner-signed, trust-anchored seed nominated as owners, and the nodes this
+     * node chose to add. `applySeed` also merges a seed's addresses into the peer
+     * store, where they age out; an added node's addresses are never merged there,
+     * because only verified addresses go into the address book (see
+     * {@link warmSiblingAddrBook}).
      *
-     * A later seed OVERWRITES an entry rather than merging, so a re-seed after an
+     * A later record OVERWRITES an entry rather than merging, so a re-seed after an
      * owner's address changes replaces the stale address instead of accumulating
-     * dead ones. Entries are never evicted: they are the node's only way back into
-     * the party if it is ever stranded again.
+     * dead ones, and {@link warmSiblingAddrBook} replaces an entry with the addresses
+     * the sibling's signed record resolves to when they differ. Only this node's own
+     * {@link removePeer} evicts an entry: otherwise they are the node's only way back
+     * to those peers if it is ever stranded again.
      */
     private bootstrapPeerStore;
     /**
@@ -365,6 +427,19 @@ export declare class CadreNode implements SAppIdLookup {
      * both read "no row yet" and race a duplicate INSERT (a `CadrePeer` PK conflict).
      */
     private registerSelfInFlight;
+    /**
+     * When this node last PUBLISHED its own `CadrePeer` address record (inserted or
+     * refreshed), or null if it never has in this session. Stamped by
+     * {@link noteSelfRecordPublished} on every successful publish, wherever it was driven
+     * from — the boot pass, the heartbeat, an address change, a drain or an explicit call.
+     *
+     * Read by {@link escalateIfSelfRecordStale} for the one consequence worth an operator's
+     * attention: once this gap exceeds {@link DEFAULT_PEER_RECORD_MAX_AGE_MS}, every other
+     * machine in the party is already discarding this node's address as stale.
+     */
+    private lastSelfRecordPublishAt;
+    /** Say-once latch for {@link escalateIfSelfRecordStale}; re-armed by the next publish. */
+    private selfRecordStaleWarned;
     /**
      * Re-replication queue for owner `authorizePeer` writes that committed while
      * this node was alone — `controlNode.getConnections().length === 0` at write
@@ -398,6 +473,14 @@ export declare class CadreNode implements SAppIdLookup {
      * exactly a "removals from before this lifetime" case).
      */
     private reissuedHeldRevocations;
+    /**
+     * Whether this process has seen the singleton `Revocation` ledger marker filed — its own
+     * `'opened'` or an `'already-open'` answer, in {@link openRevocationLedgerIfDue}. A
+     * record of work done, not a cached authorization answer: the marker can never be
+     * deleted (`NoDelete`), so this can only go stale if the database itself is replaced,
+     * which is why stop() clears it with the other per-process replication state.
+     */
+    private revocationLedgerOpened;
     /** This node's own `CadrePeer` self-write committed local-only (re-touched on growth). */
     private pendingSelfPeerWrite;
     /** This node's own `DeviceToken` self-write committed local-only (re-touched on growth). */
@@ -488,6 +571,23 @@ export declare class CadreNode implements SAppIdLookup {
      * Get all strand instances
      */
     getStrands(): Map<string, StrandInstance>;
+    /**
+     * Strands the control network advertises that no local sAppConfig claims —
+     * the backlog behind `strand:discovered`.
+     *
+     * The event fires once per strand, and it can fire before the app has
+     * subscribed (the watcher's first poll runs inside `start()`). So an app that
+     * auto-joins discovered strands must subscribe FIRST and then drain this map,
+     * not rely on the event alone. Entries leave the map when the strand is
+     * claimed ({@link addStrand}) or its control row disappears.
+     *
+     * Bounded by the number of strands this party has that this node does not run
+     * — the control database holds only this party's rows — so there is no cap and
+     * no eviction policy to reason about.
+     *
+     * Returns a snapshot; mutating it does not affect the node.
+     */
+    getDiscoveredStrands(): Map<string, StrandRow>;
     /**
      * Get a specific strand instance
      */
@@ -596,10 +696,10 @@ export declare class CadreNode implements SAppIdLookup {
      */
     getEnrolledMachineStore(): EnrolledMachineStore | null;
     /**
-     * The node-local cold-start bootstrap-peer store (null before {@link start}) —
-     * the retained owner addresses {@link reconcileControlCohort}'s cold-start
-     * branch re-dials. Exposed for diagnostics and for a host that wants to show
-     * "what would this node dial if it is stranded?".
+     * The node-local bootstrap-peer store (null before {@link start}) — the dial
+     * targets learned out of band that {@link reconcileControlCohort} falls back to.
+     * Exposed for diagnostics and for a host that wants to show "what would this
+     * node dial if it is stranded?".
      */
     getBootstrapPeerStore(): BootstrapPeerStore | null;
     /**
@@ -695,9 +795,8 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * Keyed off `relayAddrs` AND `listenAddrs`, so a hand-written `/p2p-circuit` entry
+     * in `listenAddrs` — a 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
@@ -972,6 +1071,55 @@ export declare class CadreNode implements SAppIdLookup {
     registerSelf(): Promise<SelfRegistrationOutcome>;
     /** The body of {@link registerSelf}; serialised by its single-flight guard. */
     private publishSelfRecord;
+    /**
+     * Record that this node's own address record just landed, and re-arm the stale-record
+     * warning. Called from BOTH publishing paths of {@link publishSelfRecord} and nowhere
+     * else — a `skipped` publish wrote nothing, so it must not refresh the stamp.
+     */
+    private noteSelfRecordPublished;
+    /**
+     * Report an abandoned control write to the embedding app.
+     *
+     * Every control write funnels through `ControlDatabase.lockedWithRetry`, which now tells
+     * this node when it gives one up. Foreground writes ALSO reject to their caller; the
+     * background ones ({@link startRecordRefresh}'s republish and the two replication
+     * drains) are fired unawaited with a `debug`-only catch, so this event is the only thing
+     * that reaches an app at all.
+     *
+     * Reporting only — the one operator-visible escalation lives on the republish path
+     * ({@link escalateIfSelfRecordStale}), where the consequence is measurable.
+     */
+    private noteControlWriteAbandoned;
+    /**
+     * Escalate ONE failed self-address republish to the operator — once — when the node has
+     * not published its own record for longer than a record stays fresh.
+     *
+     * The bar is the CONSEQUENCE, not a failure count: a resolver discards a `CadrePeer`
+     * record older than {@link DEFAULT_PEER_RECORD_MAX_AGE_MS} (15 minutes) and the heartbeat
+     * re-stamps at half that, so by the time this gap opens every other machine in the party
+     * has already stopped accepting this node's address. A count would fire far too early —
+     * one failed heartbeat is already half the budget, and a single miss costs nothing.
+     *
+     * Say-once, re-armed by the next successful publish ({@link noteSelfRecordPublished}), so
+     * a node that stays broken warns once rather than every 7.5 minutes.
+     *
+     * A node that has never published in this session is skipped: it has no record out there
+     * to go stale, and the reason it has none (not a member yet, no signing key, revoked) is
+     * already logged by `registerSelf` itself.
+     *
+     * Only a FAILED republish is checked. A heartbeat whose publish reports `skipped` neither
+     * stamps nor warns, so a node that stops being able to publish without erroring — revoked,
+     * or its row removed — goes quiet here. That is the intended reading: a revoked node has
+     * nothing to publish and its unreachability is the point, not a fault to report.
+     *
+     * NOTE: the second `console.*` in this library, and the reason
+     * {@link warnIfAnnounceAddrsDiscardRelay}'s note says a third should not simply be added:
+     * both are operator warnings about a configuration/health condition an embedder cannot
+     * see otherwise, and both have an event beside them (`control:write-abandoned` carries
+     * the underlying write failure). A third such condition should surface through
+     * {@link CadreNodeEvents} alone unless it likewise degrades the whole party in silence.
+     */
+    private escalateIfSelfRecordStale;
     /**
      * Sign this node's address record for publication, stamped strictly later than
      * `existing` (the row it is about to replace, or null for a first insert) so a
@@ -1076,7 +1224,7 @@ export declare class CadreNode implements SAppIdLookup {
      * 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 peerStoreAddrs}), and a retained out-of-band dial target
      * ({@link bootstrapDialAddrs}).
      *
      * An address naming a DIFFERENT trailing peer id is dropped: it does not reach
@@ -1089,14 +1237,14 @@ export declare class CadreNode implements SAppIdLookup {
      * 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
+     * retained 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}).
+     * retained one ({@link bootstrapDialAddrs}).
      */
     private bindAddrToPeer;
     /** Parse multiaddr strings, dropping (and logging) any that fail to parse. */
@@ -1110,13 +1258,32 @@ export declare class CadreNode implements SAppIdLookup {
      * `self:peer:update` (all wired in {@link startRecordRefresh}).
      *
      * Concurrent triggers collapse into a single in-flight pass
-     * (see {@link reconcileControlCohortInFlight}) so two passes never double-dial.
+     * (see {@link reconcileControlCohortInFlight}) so two passes never double-dial;
+     * a call that joins an in-flight pass resolves to THAT pass's result.
      * Best-effort throughout: a failure to resolve/dial any one sibling is logged
      * and the pass continues; the whole pass is a no-op when the node is alone.
+     *
+     * Resolves to the peers the pass dialled ({@link ControlCohortReconcileResult}),
+     * so a caller can tell a link this pass opened from one something else opened —
+     * the pass skips a peer that is already connected. The timer and event triggers
+     * discard it.
      */
-    reconcileControlCohort(): Promise<void>;
+    reconcileControlCohort(): Promise<ControlCohortReconcileResult>;
     /** Body of {@link reconcileControlCohort}; serialised by its single-flight guard. */
     private runReconcileControlCohort;
+    /**
+     * The owner-only half of the reconcile pass's ledger-marker step: file the singleton
+     * `Revocation` marker ({@link SeedBootstrapService.openRevocationLedger}) unless this
+     * process has already seen it filed. The connectivity gate is the caller's
+     * ({@link runReconcileControlCohort}); why the marker exists is on
+     * {@link ControlDatabase.openRevocationLedger}.
+     *
+     * Sets {@link revocationLedgerOpened} on `'opened'` or `'already-open'`. A node that
+     * cannot sign as an owner does nothing: it picks the owner's marker up the first time it
+     * reads the table, like any other replicated row. Best-effort like every step of the
+     * pass — a failure is logged and leaves the flag clear, so the next connected pass retries.
+     */
+    private openRevocationLedgerIfDue;
     /**
      * Resolve every sibling's signed address record once and merge what resolves
      * into the control node's libp2p **address book** (peerStore). Returns the
@@ -1136,6 +1303,9 @@ export declare class CadreNode implements SAppIdLookup {
      * resolves to nothing (revoked, stale, untrusted) is not written at all, so its
      * existing entry ages out on its own.
      *
+     * The same resolution also keeps a sibling's retained out-of-band dial target
+     * current ({@link refreshDialHint}).
+     *
      * NOTE: this resolves EVERY sibling serially before the dial loop below runs,
      * so it costs one record query per sibling per reconcile pass (~15s) and each
      * one delays the pass's first dial. A cadre is a handful of devices, so today
@@ -1143,6 +1313,28 @@ export declare class CadreNode implements SAppIdLookup {
      * into one query, merge only on change, or move the warm pass after the dials.
      */
     private warmSiblingAddrBook;
+    /**
+     * Replace a sibling's retained out-of-band dial target (see
+     * {@link bootstrapPeerStore}) with the addresses its signed record just resolved
+     * to, when the two differ — so an address change this node saw while the record
+     * was fresh (a new port, a new LAN address) is what it dials after a relaunch
+     * that outlives the record's freshness window.
+     *
+     * Only a sibling that already HAS an entry (`retained`) is refreshed: the store
+     * holds peers learned out of band and must not grow into a copy of every
+     * sibling's addresses. An empty resolution leaves the entry alone — a stale or
+     * not-yet-signed record is exactly when the entry is needed. The comparison is
+     * order-insensitive and runs on the retained addresses after binding them to the
+     * peer id, so an entry recorded without `/p2p/` suffixes is not rewritten merely
+     * for lacking them.
+     *
+     * NOTE: replaces rather than merges, so the entry becomes exactly what the
+     * sibling announces. If a node's signed record ever lists fewer addresses this
+     * node can reach than it was added with (say an announce override naming only a
+     * public address, for a node added by its LAN address), a relaunch dials the
+     * worse set; merge the two lists here if that shows up.
+     */
+    private refreshDialHint;
     /**
      * {@link resolvePeerAddrs} for one sibling, best-effort: a control-DB read
      * failure yields `[]` (and the cold-start fallback then gets its turn) rather
@@ -1150,37 +1342,78 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private resolveSiblingAddrs;
     /**
-     * Budget for ONE proactive dial of the reconcile pass — steady-state sibling
+     * Time limits for dialing ONE control-network peer from its candidate
+     * addresses ({@link dialPeerAddrs}): the reconcile pass's steady-state sibling
      * ({@link dialControlSibling}) and cold-start bootstrap peer
-     * ({@link dialBootstrapPeer}) alike, since both feed a whole address list to
-     * one `dial()` and both run in a sequential loop that the next entry waits on.
+     * ({@link dialBootstrapPeer}) dials, and — handed to every
+     * {@link SeedBootstrapService} this node builds — `applySeed`'s owner dials and
+     * `dialInvite`.
      *
-     * See {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} for why the pass bounds
-     * this itself rather than inheriting each address's libp2p attempt timeout.
+     * See {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} for why a peer's dial is
+     * bounded as a whole, and {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}
+     * for why each address is bounded as well.
      */
-    private controlDialTimeoutMs;
+    private controlDialBudget;
     /**
      * Dial one sibling from its already-resolved addresses, best-effort. Returns
-     * whether a dial was attempted (false when no address resolves).
+     * whether the dial resolved (false when no address resolves or the dial fails).
      *
      * A per-peer failure (NAT, offline, relay down, connection-gater denial, or
-     * the {@link controlDialTimeoutMs} budget expiring) is logged and swallowed so
-     * one unreachable sibling never aborts the pass — exactly like
+     * the {@link controlDialBudget} expiring) is logged and swallowed so one
+     * unreachable sibling never aborts the pass — exactly like
      * {@link SeedBootstrapService.applySeed}'s owner-dial loop. A failed dial is
      * simply retried on the next pass.
      */
     private dialControlSibling;
     /**
-     * A sibling's control-network dial addresses for the reconcile pass.
-     *
-     * Primary (steady state): the signed, fresh, trust-gated control addresses
-     * `resolved` for it by {@link warmSiblingAddrBook} — passed in rather than
-     * re-resolved, so the pass makes one record query per sibling. Fallback (cold
-     * start): the libp2p peerStore entries `applySeed` populated, used only while
-     * the record is not yet resolvable. Returns `[]` (never throws) when neither
-     * yields an address — that sibling is skipped this pass.
+     * A sibling's control-network dial addresses for the reconcile pass, from the
+     * first of three sources that yields any:
+     *
+     *  1. the signed, fresh, trust-gated control addresses `resolved` for it by
+     *     {@link warmSiblingAddrBook} — passed in rather than re-resolved, so the
+     *     pass makes one record query per sibling;
+     *  2. the libp2p address book ({@link peerStoreAddrs}) — the entries `applySeed`
+     *     and identify put there, until they age out;
+     *  3. the sibling's retained out-of-band dial target ({@link retainedDialAddrs}).
+     *     For a node that cannot listen, this is the only source for a sibling it
+     *     added but has not yet connected to: the added node's row stays unsigned
+     *     until it self-publishes, which needs the connection this dial opens. It is
+     *     also what a relaunch that outlived the record's freshness window uses.
+     *
+     * Returns `[]` (never throws) when none yields an address — that sibling is
+     * skipped this pass.
+     *
+     * The list may name transports this node cannot dial (a lent node reports TCP
+     * and `/ws` addresses to a phone that dials WebSockets only). That needs no
+     * filtering here: libp2p's dial queue (`calculateMultiaddrs`, libp2p 3.1.3)
+     * rejects an address no transport can dial before touching the network, so
+     * such an address costs a log line.
+     *
+     * The list is NOT handed to one `dial()`. libp2p tries a multi-address dial's
+     * addresses one after another under a single deadline, with no limit per
+     * address, and sorts loopback addresses last — so one or two addresses that
+     * never answer used up the whole deadline before the address that worked was
+     * tried. {@link dialPeerAddrs} dials each address on its own time limit instead.
      */
     private resolveControlDialAddrs;
+    /**
+     * A sibling's retained out-of-band dial target (see {@link bootstrapPeerStore}),
+     * bound to its peer id through {@link bootstrapDialAddrs}; `[]` when it has none.
+     *
+     * These addresses are never merged into the libp2p address book: they are
+     * unverified, and the address book takes only verified ones (see
+     * `mergePeerAddrs`). Layers that dial by bare peer id use the connection this
+     * dial opens, and after it drops the next reconcile pass dials again.
+     *
+     * NOTE: an entry is consulted here only for a current sibling, so a peer revoked
+     * by another owner is not dialed from it, even though the entry stays (only this
+     * node's own {@link removePeer} forgets one). The cold-start branch
+     * ({@link dialColdStartBootstrap}) still dials every entry while there are no
+     * siblings at all; if entries for revoked peers ever cause dial churn there,
+     * prune entries whose peer has a retired `CadrePeer` row during the membership
+     * refresh.
+     */
+    private retainedDialAddrs;
     /**
      * Cold-start fallback: the libp2p peerStore multiaddrs for `peerId` (seeded by
      * {@link SeedBootstrapService.applySeed}). Returns `[]` on a missing entry or any
@@ -1213,15 +1446,33 @@ export declare class CadreNode implements SAppIdLookup {
      * signature-checked against a trust-anchored signer before this runs, and the
      * flag only *selects a dial target*; a dial grants no authority.
      *
-     * Self is excluded. `createSeed` projects EVERY `CadrePeer` row, so an owner
-     * that applies a seed minted after it joined finds itself in the owner list;
-     * retaining that would make the cold-start pass dial this node forever (the
-     * steady-state pass filters self out of its sibling list for the same reason).
+     * Addressless peers and self are skipped by {@link retainDialTarget}.
      */
     private recordSeedBootstrapPeers;
     /**
-     * Cold-start branch of the reconcile pass: re-dial the seed's owner peers
-     * while the control database still has no siblings to dial.
+     * Retain (or replace) one peer's out-of-band dial target in
+     * {@link bootstrapPeerStore}. Shared by every writer: seed intake, {@link addDrone}
+     * and {@link refreshDialHint}.
+     *
+     * Fire-and-log: the entry is visible synchronously by the store's contract, and
+     * the promise tracks durability only. A persist failure costs restart survival,
+     * never this session's dial set — the same trade
+     * `SeedBootstrapService.anchorAcceptedSigner` makes — so it is logged rather than
+     * failing a seed or an add that has already been accepted.
+     *
+     * Two peers are never retained. One with no address: there is nothing to dial.
+     * And self: `createSeed` projects EVERY `CadrePeer` row, so an owner that applies
+     * a seed minted after it joined finds itself in the owner list, and `addDrone`
+     * could be handed this node's own id. Retaining self would make the cold-start
+     * pass dial this node forever (the steady-state pass filters self out of its
+     * sibling list for the same reason).
+     */
+    private retainDialTarget;
+    /**
+     * Cold-start branch of the reconcile pass: re-dial every retained out-of-band
+     * dial target (see {@link bootstrapPeerStore}) — in practice the owner peers of
+     * the seeds this node applied — while the control database still has no
+     * siblings to dial.
      *
      * `SeedBootstrapService.applySeed` dials those owners exactly ONCE, best-effort.
      * When that single dial fails — owner momentarily down, relay reservation not
@@ -1244,13 +1495,14 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private dialColdStartBootstrap;
     /**
-     * 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.
+     * Bind a retained dial target's addresses (see {@link bootstrapPeerStore}) to
+     * its peer id, so the dial authenticates the peer it is aiming at rather than
+     * trusting whoever answers.
      *
      * 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 —
+     * (an entry 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.
      */
@@ -1508,6 +1760,15 @@ export declare class CadreNode implements SAppIdLookup {
      * `control:disconnected` emit, which a never-connected start has no edge for.
      */
     private cleanup;
+    /**
+     * A gated joiner's database was just published (`StartStrandConfig.onWritable`): the
+     * instance is `'active'` now, so re-arm its idle timer as any activity would. Nothing
+     * records activity on a gated joiner, so its idle timer may already have fired — the
+     * instance read `'idle'` with a hibernate timer pending — and without this the flip
+     * back to `'active'` would leave that timer to quiesce a strand the app just started
+     * using. Emits `strand:writable` after the timers are settled.
+     */
+    private handleStrandWritable;
     private handleStrandIdle;
     /**
      * Hibernate a strand: release its strand-network resources via the strand
@@ -1601,13 +1862,32 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * 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
-     * network (via {@link publishStrand} or another member), a failed launch keeps
-     * being re-attempted in the background — each failure re-emitting `strand:error`
-     * — until it succeeds. {@link detachStrand} (reached via {@link stopStrand}) is
-     * what abandons a strand for good.
+     * automatic relaunch need it. That background relaunch covers only a strand the
+     * WATCHER launched: it forgets a row whose `onStrandAdded` threw and re-attempts it
+     * on a later poll (each failure re-emitting `strand:error`) until it succeeds. A
+     * strand claimed here after it was DISCOVERED gets no such retry — the watcher
+     * already recorded it in its `knownStrands` when it offered it as
+     * `strand:discovered`, and no later poll re-offers a strand it knows. This call has
+     * also already dropped it from {@link getDiscoveredStrands}, so a failed claim
+     * leaves the strand dormant until the caller retries or the node restarts (see
+     * `backlog/bug-discovered-strand-lost-when-claim-fails`).
+     * {@link detachStrand} (reached via {@link stopStrand}) is what abandons a strand
+     * for good.
      */
     addStrand(config: StrandConfig): Promise<StrandInstance>;
+    /**
+     * Resolve once a launched strand is writable — its database published to the app and
+     * its status `'active'` — or reject with the retryable `StrandAwaitingFirstSyncError`
+     * after `timeoutMs` (default `strandFirstSync.timeoutMs`, else
+     * `DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`). The promise form of the `strand:writable`
+     * event, for a caller that attached without waiting ({@link StrandConfig.awaitFirstSync}
+     * `false`) or that holds a strand the watcher launched. Resolves immediately for a
+     * strand that is already writable; rejects immediately for one this node does not run.
+     * A hibernating strand is not woken — wake it first if that is what is wanted.
+     */
+    whenStrandWritable(strandId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<StrandInstance>;
     /**
      * Publish a strand row to the shared control database under this node's own
      * owner identity, so other cadre members discover it via control-network
@@ -1652,10 +1932,16 @@ export declare class CadreNode implements SAppIdLookup {
      * Failing loudly here is intentional: a silently-unpublished strand would run
      * as a local-only island that no peer could ever discover or join.
      *
+     * A CLOSED strand's publish also seats this party's own membership identity key —
+     * the `StrandPartyKey` row {@link ensureStrandPartyKey} documents — which is what the
+     * founder bootstrap derives `Member.Key`/`Manager.MemberKey` from. The
+     * `memberPrivateKey` ARGUMENT stays the strand-wide read secret formation hands to
+     * joiners; it derives nobody's identity.
+     *
      * @param strandId - Unique strand identifier (typically the same id passed to
      *   {@link addStrand}).
      * @param type - `'o'` for open (default) or `'c'` for closed.
-     * @param memberPrivateKey - Optional membership key for a closed strand.
+     * @param memberPrivateKey - Optional shared membership (read) key for a closed strand.
      * @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.
@@ -1725,10 +2011,12 @@ export declare class CadreNode implements SAppIdLookup {
      * is an owner-signed control-plane write like every other, not "destroy the network".
      *
      * Irreversible for a closed strand (`Type='c'`): the row carries `MemberPrivateKey`,
-     * this party's membership secret for that network, and it is stored nowhere else.
-     * With it gone the party can never again admit a member to that closed strand, and a
-     * re-published row would carry a DIFFERENT key that does not match the membership
-     * already written into the strand's RBAC layer. The strand id itself is NOT
+     * this party's read secret for that network, and the strand's `StrandPartyKey` row —
+     * this party's own membership identity, removed (and tombstoned) in the SAME
+     * transaction — is stored nowhere else either. With both gone the party can never
+     * again sign as its seated member/manager there, and a re-published row mints a fresh
+     * identity that does not match the membership already written into the strand's RBAC
+     * layer. The strand id itself is NOT
      * blacklisted: a fresh owner-signed {@link publishStrand} re-seats it under a new
      * stamp — only the unsigned consent re-seat is permanently foreclosed (the removal's
      * `Revocation` tombstone names the id, which the consent branch of
@@ -1768,6 +2056,55 @@ export declare class CadreNode implements SAppIdLookup {
      *   there throws over a completed removal.
      */
     unpublishStrand(strandId: string): Promise<void>;
+    /**
+     * Seat this party's own strand membership identity key — the `StrandPartyKey` row —
+     * for `strandId`, minting a fresh one when none is given, and adopting the stored one
+     * when a row already exists. Insert-if-absent and stable thereafter: the founding
+     * `Member.Key` must not change across restarts, or the bootstrap's insert-if-absent
+     * guards stop matching.
+     *
+     * This is the identity half of the closed-strand key split: the row's `PrivateKey` —
+     * NOT the strand row's shared `MemberPrivateKey`, which formation hands to every
+     * joining party — is what the founder bootstrap derives `Member.Key`/`Manager.MemberKey`
+     * from. It replicates to every machine this party owns (same plaintext-at-rest stance
+     * as `MemberPrivateKey`; docs/strands.md → "Closed-Strand Member Key Handling") and is
+     * never put on the formation wire.
+     *
+     * Called internally by {@link publishStrand} (closed strands mint at publish) and by a
+     * founder launch that finds no row (a publish interrupted before its mint); public so a
+     * test harness — or a joiner flow that persists a formation-issued identity — can seat
+     * a specific key deliberately.
+     *
+     * @param strandId - The strand the key is this party's identity for.
+     * @param partyMemberPrivateKey - Optional specific key (base64 protobuf, as
+     *   `generateStrandMemberKey` mints). When a row already holds a DIFFERENT key this
+     *   throws — a party has one identity per strand; rotation is a deliberate
+     *   remove-then-insert, not a silent swap.
+     * @returns The live party key: the one just seated, or the stored one.
+     */
+    ensureStrandPartyKey(strandId: string, partyMemberPrivateKey?: string): Promise<string>;
+    /**
+     * Resolve the party membership key a closed strand's launch threads into the founder
+     * bootstrap: the explicit attach-time key when given, else the party's persisted
+     * `StrandPartyKey` row, else — on the one machine whose owner key the row names as
+     * founder — a freshly minted-and-persisted key, which seats the identity for a publish
+     * that was interrupted before its mint. Everyone else resolves undefined: non-founding
+     * machines never mint (no mint race between a party's machines), and only a founder
+     * bootstrap needs the key at all.
+     *
+     * Minting does NOT repair a strand founded before the key split: its founding
+     * membership was seated under the shared `MemberPrivateKey`, and nothing re-seats it —
+     * the founder bootstrap refuses such a strand (`PreSplitStrandIdentityError`) instead.
+     *
+     * NOTE: "founding machine" here is the ROW's provenance, not the launch's resolved
+     * `founder` flag — so an explicit `founder: false` over a row this machine published
+     * still mints, an owner-signed write a caller that said "I am not founding" did not ask
+     * for. Harmless (the party needs that identity for the strand either way, and the mint
+     * is insert-if-absent) and unreachable today: the one explicit `founder: false` caller
+     * passes a row with a null `FounderOwnerKey`. If a caller ever pairs `founder: false`
+     * with its own published row, gate the mint on the resolved flag too.
+     */
+    private resolveStrandPartyKey;
     /**
      * Publish an owner-signed `FormationInvite` (open-invitation token) to the
      * shared control database, so a later {@link formStrand} redemption can be
@@ -1882,8 +2219,17 @@ export declare class CadreNode implements SAppIdLookup {
      * now the tracked instance is founded in place
      * ({@link StrandInstanceManager.foundExistingStrand}), waking it first if quiesced
      * so the bootstrap actually runs before this resolves.
+     *
+     * A founder launch refused as pre-split (`PreSplitStrandIdentityError`) is recorded in
+     * {@link strandLaunchRefusals} for the formation arm, then rethrown; a founder launch
+     * that succeeds clears the record (it ran the bootstrap's pre-split check and passed).
      */
     private launchStrand;
+    /**
+     * The launch itself, for {@link launchStrand} (which documents the behaviour): found a
+     * tracked instance in place, or start a fresh one.
+     */
+    private startOrFoundStrand;
     /**
      * Resolve a strand's discovery seed — the dialable strand-network multiaddr
      * strings for cohort siblings. Membership comes from the control network's
@@ -1983,10 +2329,10 @@ export declare class CadreNode implements SAppIdLookup {
      * Recorded OPTIMISTICALLY at announce time: `collectStrandAddrs` folds
      * per-peer failure to `[]` and reports no per-peer success, and threading
      * success out would change its API for little gain. A failed INITIAL announce
-     * is fatal-at-start anyway (the relay denies the reservation,
-     * `libp2p.start()` throws, and wake/check-in re-resume retries with a fresh
-     * announce); a failed REFRESH retries within `DELEGATE_GRANT_TTL_MS / 2`
-     * (15 min), still inside the 30 min TTL.
+     * costs the strand supervisor its first attempt only (the relay denies the
+     * reservation; every re-drive re-announces first through
+     * {@link announceDelegateToRelay}); a failed REFRESH retries within
+     * `DELEGATE_GRANT_TTL_MS / 2` (15 min), still inside the 30 min TTL.
      */
     private recordDelegateAnnounces;
     /**
@@ -2003,6 +2349,37 @@ export declare class CadreNode implements SAppIdLookup {
      * target, which must not stack up per strand.
      */
     private refreshDelegateGrants;
+    /**
+     * Announce ONE strand's delegate peerId to ONE relay, UNTHROTTLED — the
+     * `beforeRedrive` hook of that strand node's per-relay reservation supervisor
+     * (`strand-instance-manager.ts` → `buildStrandRuntime`), run before every
+     * re-drive after the first attempt.
+     *
+     * Why a re-drive must re-announce first: a party control node running the relay
+     * server admits the strand node's derived peerId on an in-memory delegate grant
+     * (`delegate-admission.ts`), and a relay restart drops every grant it held
+     * without telling the announcer. {@link refreshDelegateGrants} would re-announce
+     * on its own at most every `DELEGATE_GRANT_TTL_MS / 2` (15 min) per (relay,
+     * strand) — far slower than the supervisor's backoff — so without this the first
+     * re-drives after a relay restart would be denied at the relay's connection gate.
+     * The throttle map is updated afterwards, so the periodic pass does not announce
+     * again right away.
+     *
+     * Against a dedicated ops relay (no strand-addr RPC) the request fails per-peer
+     * and `collectStrandAddrs` folds it to `[]`: one wasted protocol negotiation per
+     * re-drive attempt, bounded by the supervisor's backoff. Never throws on that
+     * path; a relay addr that names no peer id is logged and skipped (the hook's
+     * caller runs the drive regardless).
+     *
+     * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
+     * timeouts (10 s each: dial by peer id, then by addr) before the 10 s drive even
+     * starts, so one failed re-drive can hold the supervisor `driving` for ~30 s.
+     * Bounded and harmless while the relay is unreachable anyway; if recovery
+     * latency after a relay comes back ever matters, skip the announce when the
+     * control node holds no connection to the relay (the drive's own dial fails
+     * faster) rather than shortening the strand-addr timeout.
+     */
+    private announceDelegateToRelay;
     /** One strand's share of {@link refreshDelegateGrants}: announce to the relays whose grant is due. */
     private announceDelegateToDueRelays;
     /**
@@ -2087,22 +2464,32 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
      * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
-     * intact, so on the next node restart (or watcher poll) the strand is rediscovered and
-     * surfaces as `strand:discovered` again. Party-wide removal is {@link unpublishStrand}.
+     * intact, so on the next node RESTART the strand is rediscovered and surfaces as
+     * `strand:discovered` again — not on the next watcher poll, which never re-offers a
+     * strand it has already seen (`StrandWatcher.knownStrands` retains the id for the life
+     * of the process). The stop also drops the strand from {@link getDiscoveredStrands},
+     * so a drain cannot undo a deliberate stop. Party-wide removal is
+     * {@link unpublishStrand}.
      */
     stopStrand(strandId: string): Promise<void>;
     /**
      * Local teardown for one strand, shared by the caller-driven {@link stopStrand} and the
-     * watcher-driven `handleStrandRemoved`: untrack hibernation, drop the sApp config, stop
-     * the instance, emit `strand:stopped`. Touches no control-plane row — which side of the
-     * removal the node is on is the caller's concern, not this method's.
+     * watcher-driven `handleStrandRemoved`: untrack hibernation, drop the sApp config and any
+     * recorded launch refusal, stop the instance, emit `strand:stopped`. Touches no
+     * control-plane row — which side of the removal the node is on is the caller's concern,
+     * not this method's.
      *
      * The stop + emit are skipped when the strand manager holds no instance for `strandId` —
      * e.g. a party owner that published a strand's row but never ran it locally, or an
      * explicit {@link stopStrand} for an id this node never started. `hibernationManager`
-     * untrack and the `sAppConfigs` delete stay unconditional (both are no-ops when there is
-     * nothing to remove), so a launch that failed before an instance was ever tracked still
-     * gets its stray sApp config cleared.
+     * untrack and the `sAppConfigs` / {@link strandLaunchRefusals} / {@link discoveredStrands}
+     * deletes stay unconditional (all no-ops when there is nothing to remove), so a launch
+     * that failed before an instance was ever tracked still gets its stray entries cleared.
+     *
+     * Dropping the {@link discoveredStrands} entry here covers both callers, and both
+     * readings are the intended one: `handleStrandRemoved` arrives because the control row
+     * is gone, and an explicit {@link stopStrand} is a deliberate abandonment — neither
+     * strand may be re-offered to a later `getDiscoveredStrands()` drain.
      */
     private detachStrand;
     /**
@@ -2209,6 +2596,11 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     *
+     * `network.requireRelay === false` softens only the outcome below: a first
+     * attempt that lands no `/p2p-circuit` address is logged instead of thrown, and
+     * `start()` carries on with the retry supervisor already running in the
+     * background (the same supervisor {@link reserveRelays} always starts).
      */
     private driveControlRelayReservation;
     /**
@@ -2573,6 +2965,20 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Add a drone to the cadre (for phone/server adding provider-hosted node).
      * Creates authorization and seed for drone initialization.
+     *
+     * Also retains the drone's handed-over addresses as a durable dial target (see
+     * {@link bootstrapPeerStore}). The drone cannot dial an owner that does not
+     * listen (a phone), and its `CadrePeer` row stays unsigned — so unresolvable —
+     * until it self-publishes over a connection; this node therefore has to open
+     * that connection from the addresses it was handed, on this launch or a later
+     * one.
+     *
+     * Nothing is dialed here: the drone has not received the seed yet. After
+     * delivering it, call {@link reconcileControlCohort} to dial straight away;
+     * otherwise the next timed reconcile pass does. A pass already in flight is
+     * joined rather than restarted, and one that listed siblings before this add
+     * does not dial the drone, so a caller waiting for the connection should allow
+     * for one more timed pass.
      */
     addDrone(options: AddDroneOptions): Promise<DroneInitResult>;
     /**
@@ -2629,6 +3035,78 @@ export declare class CadreNode implements SAppIdLookup {
      * @returns The member key and strand info if successful
      */
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
+    /**
+     * Adopt an approved closed-strand formation's membership half on the JOINER:
+     *
+     * 1. Mint-or-reuse this party's own strand identity — {@link ensureStrandPartyKey}
+     *    with no explicit key returns the stored `StrandPartyKey` row when one exists (a
+     *    re-formation by an existing member party: lost addresses, an app reinstall with
+     *    an intact control DB) and mints + persists a fresh one otherwise. The invitation
+     *    will admit THIS key's public half as the `Strand.Member`.
+     * 2. Stage the invitation in {@link pendingMembershipInvites} for the strand
+     *    bring-up flow (`strand-node-binds-member-peer`) to redeem via `consumeInvite`.
+     *
+     * Throws — failing the whole {@link formStrand} — when the identity cannot be
+     * persisted: a joiner "joined" without a persistable identity could never become a
+     * member, and failing loudly beats a silent half-member. The formation itself has
+     * already succeeded by then and its one-time token is SPENT, so the error says so:
+     * recovery is fixing the underlying cause (no owner signing key / control DB write
+     * rejected) and redeeming a FRESH invitation.
+     */
+    private adoptFormationMembershipInvite;
+    /**
+     * The pending single-use membership invitation a closed-strand formation carried back
+     * for `strandId`, or `undefined` when none is staged — the seam the strand bring-up
+     * membership reconciler (`strand-membership-reconciler.ts`) reads to redeem the
+     * joiner's `Strand.Member` seat. `undefined` therefore also means "already redeemed,
+     * burned, or found dead": the reconciler clears the entry as soon as it settles the
+     * invitation, so a caller polling this sees it disappear on its own. In-memory only;
+     * see {@link pendingMembershipInvites} for lifetime and re-formation semantics.
+     */
+    getPendingMembershipInvite(strandId: string): StrandMembershipInvite | undefined;
+    /**
+     * Responder-side issuer behind the formation manager's `issueMembershipInvite` seam
+     * (see `StrandFormationManagerOptions.issueMembershipInvite` for the contract this
+     * implements): mint a single-use `Strand.Invite` against the LIVE host strand so a
+     * validated joiner can seat its own `Strand.Member` row.
+     *
+     * - Open host strand → `null` (no members, nothing to invite into).
+     * - Closed host strand whose founder launch was refused as pre-split
+     *   ({@link strandLaunchRefusals}) → rethrow the recorded `PreSplitStrandIdentityError`;
+     *   the manager maps it to the NON-retryable `HOST_STRAND_MUST_BE_RECREATED_REASON`.
+     * - Closed host strand with no `StrandPartyKey` row → throw: this party's identity is
+     *   the invite's issuing manager, and without it nothing can sign the issuance. (The
+     *   founder's publish/launch paths mint it, so this is a not-yet-converged sibling.)
+     *   The manager maps the throw to a clean retryable rejection BEFORE the formation
+     *   token is spent.
+     * - Closed host strand with no running local instance/database → throw, same mapping:
+     *   a joiner admitted without an invitation would look joined and never become a
+     *   member, and a responder not running the strand cannot serve its sync anyway.
+     * - Closed host strand whose LIVE rows carry the pre-split fingerprint
+     *   (`assertNotPreSplitStrand`) → throw `PreSplitStrandIdentityError`, same mapping as
+     *   the recorded refusal. Covers the responders that never ran a refused founder launch:
+     *   a sibling machine of the founding party, or a node restarted since the refusal.
+     *
+     * The recorded refusal is checked first: it is an in-memory read and the only
+     * permanent diagnosis. Identity is checked BEFORE the runtime: it is the cheaper read
+     * and the more actionable diagnosis when both are missing (a missing runtime is
+     * transient, a missing identity is not), and it keeps the branch reachable without
+     * standing a strand runtime up.
+     *
+     * The invitation expires `MEMBERSHIP_INVITE_TTL_MS` from now — see that constant for
+     * the slow-joiner / lost-result tradeoff.
+     *
+     * NOTE: the issuing identity must be a `Strand.Manager` (the schema's `InviteValid`
+     * gate), and only the FOUNDING party's key is seated as one. Today only the founder
+     * party can host a bound formation at all — a joining party never gets the host
+     * strand's control `Strand` row, so `resolveStrand` reports `missing` on it — so this
+     * never bites. If a joined party is ever able to host formations into a strand it
+     * joined (re-invite / multi-hop join), issuance here fails the manager gate and every
+     * such redemption rejects with the retryable-sounding
+     * `MEMBERSHIP_INVITE_UNAVAILABLE_REASON` forever; that flow needs manager delegation,
+     * not a retry.
+     */
+    private issueStrandMembershipInvite;
     /**
      * 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