@serfab/cadre-core 1.14.0 → 1.16.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, SeedAckMessage, SeedDeliveryTarget, AddDroneOptions, DroneInitResult, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, CadreInviteStatus, CreateCadreInvitationOptions, CreateCadreInvitationResult, RedeemCadreInvitationResult, ResolveDeviceTokenOpts, PendingJoinStatus } from './types.js';
+import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, SeedAckMessage, SeedDeliveryTarget, AddDroneOptions, DroneInitResult, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, CadreInviteStatus, CadreMachine, MachineRemovalPlan, MachineRemovalResult, RemoveMachineOptions, CadreRemoval, CadreInvitationReach, CreateCadreInvitationOptions, CreateCadreInvitationResult, RedeemCadreInvitationOptions, RedeemCadreInvitationResult, ResolveDeviceTokenOpts, PendingJoinStatus } 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 StrandNetworkStateStore } from './strand-network-state.js';
 import { type EnrolledMachineStore } from './enrolled-machine-store.js';
+import { type JoinedStrandRecord } from './joined-strand-store.js';
 import { type SAppIdLookup } from './strand-watcher.js';
 import { type ControlCohortReconcileResult } from './control-cohort.js';
 import { EnrollmentService } from './enrollment.js';
@@ -90,8 +91,9 @@ export declare class CadreNode implements SAppIdLookup {
     private controlBackfill;
     /**
      * Devices whose invitation redemption this member has verified and is admitting right now,
-     * each with its count of overlapping redemptions. The control backfill's gate admits them
-     * as it admits a member, for that window only ({@link catchUpRedeemingDevice}).
+     * each with its count of overlapping redemptions. The control backfill's gate and the
+     * control cohort choice (Optimystic's `isNetworkMember`) count them as members, for that
+     * window only ({@link admitRedeemingDevice}); the per-stream gate never does.
      */
     private readonly admittingDevices;
     private strandWatcher;
@@ -141,6 +143,8 @@ export declare class CadreNode implements SAppIdLookup {
     private pushFanoutService;
     /** Backing field for the {@link running} / {@link isRunning} getters. */
     private _running;
+    /** The {@link stop} in progress, or null; a concurrent `stop()` awaits it. */
+    private stopInFlight;
     /**
      * The control database's own raw storage (cache-wrapped), resolved once per
      * `start()` and released in {@link cleanup}. Owning it is what keeps the
@@ -247,13 +251,15 @@ export declare class CadreNode implements SAppIdLookup {
     private bootstrapPeerIds;
     /**
      * Materialized in-memory snapshot of the AUTHORIZED member peer ids (the
-     * {@link listAuthorizedMembers} result), consulted by the per-stream
-     * control-DB gate ({@link authorizeInboundControlStream}). That predicate
-     * runs on EVERY inbound Optimystic control-DB stream and must never await a
-     * control-DB read: those reads pull blocks over the very protocols the
-     * predicate gates, which closes a circular wait that ends in mutual denial
-     * (the upstream gate is fail-closed on timeout, unlike the fail-open
-     * connection gater). So the set is refreshed OUT OF BAND instead — after
+     * {@link listAuthorizedMembers} result), consulted through
+     * {@link isControlNetworkMember} by the per-stream control-DB gate
+     * ({@link authorizeInboundControlStream}) and by Optimystic's cohort choice
+     * (`isNetworkMember`). The stream gate runs on EVERY inbound Optimystic
+     * control-DB stream and must never await a control-DB read: those reads pull
+     * blocks over the very protocols the predicate gates, which closes a circular
+     * wait that ends in mutual denial (the upstream gate is fail-closed on
+     * timeout, unlike the fail-open connection gater). Optimystic's predicate is
+     * synchronous by contract. So the set is refreshed OUT OF BAND instead — after
      * start, on every {@link reconcileControlCohort} pass (15s cadence), and
      * immediately after every LOCAL membership mutation so a just-vouched peer
      * is admitted without waiting for the timer. That last refresh is AUTOMATIC:
@@ -262,7 +268,11 @@ export declare class CadreNode implements SAppIdLookup {
      * writer has to remember. A change that arrives by REPLICATION is picked up
      * on the next timed refresh — bounded staleness, acceptable because this gate
      * is defense in depth: rows an unadmitted peer manages to write are still
-     * disbelieved at read time by the voucher-anchored predicate.
+     * disbelieved at read time by the voucher-anchored predicate. For cohort
+     * choice the same window means a member whose row arrived by replication is
+     * left out of this node's control-block cohorts until that refresh.
+     * Optimystic reads the predicate live on every lookup, so replacing this set
+     * is the whole re-evaluation; there is no per-peer reclassify call to make.
      */
     private authorizedControlPeers;
     /**
@@ -274,6 +284,17 @@ export declare class CadreNode implements SAppIdLookup {
     private membershipGateDirty;
     private membershipGateDrain;
     private membershipGateDeferDepth;
+    /**
+     * This node's own `CadrePeer` row as a membership refresh last read it live, or null until
+     * one has. Reporting a removal needs it ({@link noteOwnRemoval}). Kept across
+     * stop()→start(), like {@link removal}.
+     */
+    private ownLiveRow;
+    /**
+     * The removal this node learned of ({@link removedFromCadre}), or null. Set once and never
+     * cleared, so `cadre:removed` fires once per node object.
+     */
+    private removal;
     /**
      * In-memory delegate admission grants (see `delegate-admission.ts`): the
      * strand-node transport peerIds this party's members have announced over the
@@ -554,9 +575,11 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * from — the boot pass, the heartbeat, an address change, a drain, a reconcile pass or an
+     * explicit call.
      *
-     * Read by {@link escalateIfSelfRecordStale} for the one consequence worth an operator's
+     * Read by {@link publishFirstSelfRecord}, which stops trying once it is set, and 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.
      */
@@ -724,6 +747,7 @@ export declare class CadreNode implements SAppIdLookup {
      * Stop the cadre node
      */
     stop(): Promise<void>;
+    private stopRunning;
     /**
      * Subscribe to events
      */
@@ -803,12 +827,19 @@ export declare class CadreNode implements SAppIdLookup {
      * {@link start} has built the anchor.
      *
      * While true the node admits strangers' CONNECTIONS (the claim seed has to ride one)
-     * and refuses their control-database streams ({@link authorizeInboundControlStream})
+     * and refuses them control-database streams and cohort places ({@link isControlNetworkMember})
      * and relay reservations ({@link admitControlRelayReservation}): an unclaimed node has
      * no siblings to replicate from and must not become a public relay while it waits.
      * cadre-cli reports this on `/status`; `claim:accepted` is the event form.
      */
     isAwaitingClaim(): boolean;
+    /**
+     * The removal from the cadre this node has learned of, or null: the query form of
+     * `cadre:removed`, for an embedder that subscribed after it fired. Kept once set, across
+     * stop()→start() and a later re-admission, because the embedder acts on it once (stops this
+     * node, deletes the cadre's data); a re-added machine joins again from a fresh node.
+     */
+    removedFromCadre(): CadreRemoval | null;
     /**
      * Construct (or adopt) the node-local cold-start bootstrap-peer store (see
      * {@link bootstrapPeerStore}). Synchronous: an injected store has already
@@ -881,6 +912,29 @@ export declare class CadreNode implements SAppIdLookup {
      * strand restart with?".
      */
     getStrandNetworkStateStore(): StrandNetworkStateStore | null;
+    /**
+     * The strands this machine joined from another party and has not published party-wide
+     * (see {@link CadreNodeConfig.joinedStrands}). Publication needs a control connection,
+     * so a one-node party's joins live here until it holds one; `exportStrandBundle` reads
+     * it beside the `JoinedStrand` table.
+     *
+     * @throws when the node is not started.
+     */
+    listUnpublishedJoinedStrands(): Promise<JoinedStrandRecord[]>;
+    /**
+     * The strand-network addresses a formation carried for `strandId` (see
+     * {@link formationStrandAddrs}), as kept: attributed per peer. Empty when none were
+     * carried or the strand's peers were forgotten. A copy; the node keeps its own list.
+     */
+    getCarriedStrandAddrs(strandId: string): string[];
+    /**
+     * Seat `addrs` as the addresses a formation carried for `strandId`, exactly as a
+     * formation of this node's own would ({@link recordFormationStrandAddrs}): a strand
+     * move seats the exporting node's list here so the first launch has a cross-party
+     * seed. The usual rules apply: a list naming a peer replaces the strand's earlier
+     * one, and a list naming none records nothing.
+     */
+    recordCarriedStrandAddrs(strandId: string, addrs: readonly string[]): Promise<void>;
     /**
      * The node-local trusted-owner anchor (null before {@link start}). This is
      * the set the authorized-membership predicate and seed-trust anchor consult —
@@ -943,7 +997,7 @@ export declare class CadreNode implements SAppIdLookup {
      * connect-then-authorize — on every committed membership change via
      * {@link refreshAuthorizedControlPeers}'s `scheduleConnectedPeers()` call.
      * The one non-member the gate admits is a device whose invitation
-     * redemption this member is admitting ({@link catchUpRedeemingDevice}).
+     * redemption this member is admitting ({@link admitRedeemingDevice}).
      *
      * 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
@@ -951,18 +1005,23 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private startControlBackfill;
     /**
-     * Push this member's control store to a device whose invitation redemption has verified,
-     * and wait for the push, before the redemption seats the invitation's row and writes the
-     * device's rows (the handler's `catchUpDevice`; `CadreInviteHandler.catchUpDeviceIfLive`
-     * says why those writes need it).
-     * The device is admitted at the backfill's gate for the length of the push only.
+     * Admit a device whose invitation redemption has verified to this member's control
+     * replication until the returned release is called (the handler's `admitDevice`;
+     * `CadreInviteHandler.admitDeviceIfLive` says why the redemption's writes need it): push it
+     * this member's control store and wait for the push, with the device counted as a member by
+     * the backfill's gate and by the control cohort choice ({@link admittingDevices}), so the
+     * seat and the admission that follow are written to the device too. A failed push releases
+     * at once and rethrows: in the cohort without the store, the device would refuse the
+     * commits and tear the writes. With no backfill on this node nothing is admitted.
      *
      * Through {@link PeerJoinBackfill.forceCatchUpPeer}, not `catchUpPeer`: the device's own
      * `peer:identify` scheduled a run a moment earlier, which was denied if it passed the gate
      * before the device was added here, and `catchUpPeer` would answer that run's in-flight
      * status with an empty result.
      */
-    private catchUpRedeemingDevice;
+    private admitRedeemingDevice;
+    /** Count one more redemption admitting `peerId`; the returned release undoes it, once. */
+    private countAdmittingDevice;
     /**
      * The control database's cache-wrapped raw storage, resolved from
      * `config.storage.provider` on first use and then held in {@link controlStorage}
@@ -1167,13 +1226,17 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private admitControlPeerUnconditionally;
     /**
-     * Per-stream authorization for the protocol guard's `members-snapshot` class
-     * (`control-protocol-guard.ts`): the four Optimystic control-DB protocols
-     * (`/optimystic/control-<party>/{repo,cluster,sync,block-transfer}/…`), FRET's
-     * five, and any protocol nobody classed. Also wired as Optimystic's
-     * `authorizeInboundStream` in {@link createControlNode} for the four DB
-     * protocols. The fail-closed layer behind the fail-open connection gater.
-     * Control node ONLY: strand cohort nodes legitimately serve cross-party peers.
+     * The membership rule this control node applies to a remote peer, without logging. Two
+     * consumers: the per-stream gate ({@link authorizeInboundControlStream}, who may SEND to
+     * this node on a members-only protocol) and Optimystic's `isNetworkMember` (who this node
+     * sends control writes TO — which peers can be a control block's cohort member or
+     * coordinator), which adds only a device whose verified invitation redemption is being
+     * written ({@link admittingDevices}). One rule for both keeps the outbound choice as
+     * permissive as the inbound acceptance: a joining node's cohort must include the inviter
+     * its empty anchor or empty snapshot lets replicate to it, or it would see a self-only
+     * cohort, rule an existing collection absent and found a second copy. Sereus builds the
+     * control node with `bootstrapNodes: []`, so Optimystic's refused-bootstrap-peer guard
+     * does not cover that.
      *
      * The STRICT SUBSET of {@link admitInboundControlConnection}: the same
      * "no basis to judge" admissions (shared via
@@ -1182,40 +1245,54 @@ export declare class CadreNode implements SAppIdLookup {
      * grant). The first two exist so a stranger can reach `/sereus/formation/1.0.0`
      * and `/sereus/cadre-invite/1.0.0` — neither is gated here, and admitting a
      * stranger to `repo` while an invitation is live is exactly the hole this
-     * gate closes. A DELEGATE-admitted connection (a member's strand node
+     * rule closes. A DELEGATE-admitted connection (a member's strand node
      * holding a circuit-relay reservation, see `delegate-admission.ts`) is
-     * likewise exactly a case this gate must still refuse: the delegate gets
-     * the connection and never the control DB.
+     * likewise refused: the delegate gets the connection and never the control DB.
      *
      * Refuses everyone, ahead of every admission below, while this node is waiting to be
      * claimed ({@link isAwaitingClaim}). The empty-anchor and empty-snapshot admissions
      * exist so a brand-new node can take replication from the siblings that will
      * authorize it; an unclaimed node has no siblings yet, and the rows that will
      * authorize anyone arrive only after the claim, over the owner's streams that the
-     * same two admissions then let in. Configured bootstrap infra is refused too: a
-     * relay opens no control-database stream.
+     * same two admissions then let in. Its cohort is itself alone meanwhile, which costs
+     * nothing: it built its control database with zero connections. Configured bootstrap
+     * infra is refused too: a relay opens no control-database stream.
      *
      * Otherwise admits when ANY of:
      *  1. a shared-baseline check admits (not running / no DB, empty anchor,
-     *     configured bootstrap infra);
+     *     configured bootstrap infra — which Optimystic still classifies `foreign`,
+     *     since a relay serves none of the party's database protocols);
      *  2. the materialized authorized set is empty — cold start, before the
      *     rows that would authorize anyone have replicated in;
      *  3. the peer IS in the materialized authorized set.
      *
      * Deliberately SYNCHRONOUS and pure in-memory — see
      * {@link authorizedControlPeers} for why a control-DB read here would
-     * deadlock into mutual denial. With a sync predicate the upstream deadline
-     * (`authorizeInboundStreamTimeoutMs`) never trips, so it stays at its
-     * default.
+     * deadlock into mutual denial.
      *
      * NOTE: the snapshot keys on PEER ID, so a node with no persistent identity
      * key never lands a `CadrePeer` row ({@link registerSelf} skips) and its
-     * siblings deny its control-DB streams once their own snapshot is non-empty —
-     * owner status is a KEY, not a peer id, so being the owner does not exempt it.
-     * Harmless today (a real deployment persists its identity; the ephemeral-owner
-     * case appears only in tests, which configure the owner as bootstrap infra —
-     * `push-wake-e2e.integration.ts` design note 3). If an ephemeral-identity node
-     * ever becomes a supported deployment, this gate needs a key-based admission.
+     * siblings deny its control-DB streams, and leave it out of their cohorts, once
+     * their own snapshot is non-empty — owner status is a KEY, not a peer id, so
+     * being the owner does not exempt it. Harmless today (a real deployment persists
+     * its identity; the ephemeral-owner case appears only in tests, which configure
+     * the owner as bootstrap infra — `push-wake-e2e.integration.ts` design note 3).
+     * If an ephemeral-identity node ever becomes a supported deployment, this rule
+     * needs a key-based admission.
+     */
+    private isControlNetworkMember;
+    /**
+     * Per-stream authorization for the protocol guard's `members-snapshot` class
+     * (`control-protocol-guard.ts`): the four Optimystic control-DB protocols
+     * (`/optimystic/control-<party>/{repo,cluster,sync,block-transfer}/…`), FRET's
+     * five, and any protocol nobody classed. Also wired as Optimystic's
+     * `authorizeInboundStream` in {@link createControlNode} for the four DB
+     * protocols. The fail-closed layer behind the fail-open connection gater.
+     * Control node ONLY: strand cohort nodes legitimately serve cross-party peers.
+     *
+     * Admits exactly the peers {@link isControlNetworkMember} does, and logs why it
+     * refused one. With a sync predicate the upstream deadline
+     * (`authorizeInboundStreamTimeoutMs`) never trips, so it stays at its default.
      */
     private authorizeInboundControlStream;
     /**
@@ -1235,9 +1312,50 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * The trusted-owner anchor sync ({@link syncOwnerAnchor}) runs FIRST, so the snapshot
      * built here judges `CadrePeer` rows against the anchor as the `OwnerKey` table now
-     * has it. The invitation chain both reads may need is loaded at most once per refresh.
+     * has it. The invitation chain both reads may need, and the tombstone list the sync and
+     * the two end-of-refresh checks ({@link hangUpRevokedControlPeers}, then
+     * {@link noteOwnRemoval}) read, are each loaded at most once per refresh.
      */
     private refreshAuthorizedControlPeers;
+    /**
+     * Hang up this node's control connections to every peer that a `CadrePeer` tombstone names
+     * and that has no live `CadrePeer` row: a machine removed from the cadre, whose streams the
+     * protocol guard already refuses but whose open connection would otherwise stay up until it
+     * dropped on its own. Runs at the end of every membership refresh: on the remover from the
+     * removal's own membership notification, so the connection is closed before
+     * {@link removeMachine} returns; on every other machine from the refresh that follows the
+     * replicated tombstone.
+     *
+     * Denies only on evidence held, the strand enforcer's rule (`strand-revocation-enforcer.ts`):
+     * a peer that merely dropped out of the authorized snapshot (an anchor read that failed, a
+     * voucher whose owner is gone) keeps its connection, self is never hung up, and a peer with a
+     * tombstone AND a live row under a fresh stamp was re-admitted and keeps its connection too.
+     * The tombstones are the refresh's own read (`loadTombstones`, shared with
+     * {@link syncOwnerAnchor}), taken only when some connected peer has no live row, so a cadre
+     * with every connection accounted for costs nothing here. A failed `hangUp` is logged and
+     * retried by the next refresh. Never rejects.
+     */
+    private hangUpRevokedControlPeers;
+    /**
+     * Learn that an owner removed this node from the cadre, at the end of every membership
+     * refresh: a `CadrePeer` tombstone names this node's peer id, `rows` (the refresh's own
+     * retired-stamp-filtered read) has no live row for it, and an earlier refresh of this process
+     * saw one ({@link ownLiveRow}). Then it records {@link removal} and emits `cadre:removed`,
+     * once. Nothing is stopped here: stopping and deleting are the embedder's, whose storage,
+     * saved starts and process lifetime they are.
+     *
+     * The "seen live" condition keeps a machine joining again, whose fresh store can sync the old
+     * tombstone before its new row, from reporting itself removed. A re-admission under a fresh
+     * stamp is a live row, so a tombstone plus a live row is never a removal. The tombstones are
+     * the refresh's shared read, taken only once the own row is missing. Never rejects.
+     */
+    private noteOwnRemoval;
+    /**
+     * The tombstone's signer when its signature verifies and the key is in this node's
+     * trusted-owner anchor, else null. A tombstone that fails this is still a removal (every
+     * other machine honours it, and this node's own row is gone), so it is logged, not refused.
+     */
+    private anchoredRevocationSigner;
     /**
      * Add the configured `controlNetwork.bootstrapNodes` to the control node's address book
      * and dial each peer once — what `@libp2p/bootstrap` would have done had the node been
@@ -1270,6 +1388,18 @@ export declare class CadreNode implements SAppIdLookup {
      * reference apps), and a write it signed would only be refused.
      */
     private enrolledOwnerSigningKey;
+    /**
+     * Whether this node can act as an owner of its cadre: its identity key is wired as its
+     * owner signing key ({@link initializeSeedBootstrap}) and enrolled in the live `OwnerKey`
+     * set ({@link enrolledOwnerSigningKey}). What the owner-only flows (`createCadreInvitation`,
+     * `claimNode`, `rentNode`) need; false before `start()`, and on a machine that joined as a
+     * member. The reference apps' "is this device an owner" check.
+     */
+    isOwner(): Promise<boolean>;
+    /** {@link enrolledOwnerSigningKey} judged against an owner set the caller has already read. */
+    private ownerSigningKeyEnrolledIn;
+    /** This machine's identity key as an owner signing key, when its seed bootstrap is wired to sign; enrollment not yet checked. */
+    private ownerSigningKeyCandidate;
     /**
      * Schedule the node's initial self-record publish + ongoing refresh shortly
      * after start (non-blocking). {@link registerSelf} is idempotent and safely
@@ -1407,17 +1537,30 @@ export declare class CadreNode implements SAppIdLookup {
      */
     getIdentityOwnerKey(): Ed25519KeyPair;
     /**
-     * Publish this node's own address record from the reconcile pass, for a CLAIMED node that
-     * has not published one this session. Its owner writes its `CadrePeer` row only after the
-     * claim is accepted (`claimNode`), so the row reaches this node by replication, after the
-     * boot-time publish and the first-growth drain have both found nothing to publish; without
-     * this the record would wait for the heartbeat ({@link startRecordRefresh}), and the cadre
-     * could not resolve the node's addresses until then. The reconcile pass is where replicated
-     * membership is picked up, so each pass tries until the first publish lands. A try before
-     * the row has arrived is a `skipped` publish: one `CadrePeer` read. A claimed node later
-     * removed from its cadre never publishes again, so it pays that read on every pass.
-     */
-    private publishSelfRecordOnceClaimed;
+     * Publish this node's own address record from the reconcile pass until its first publish of
+     * this session lands. A node with no owner key — seeded (`addDrone`, `cadre enroll add`),
+     * claimed (`claimNode`) or otherwise authorized after it booted — cannot insert its own
+     * `CadrePeer` row; the row an owner wrote for it reaches it by replication once the two
+     * connect, usually after the boot-time publish and the first-growth drain have both found
+     * nothing to publish. Without this the record would wait for the heartbeat
+     * ({@link startRecordRefresh}), and the cadre could not resolve the node's addresses until
+     * then. The reconcile pass is where replicated membership is picked up, so each pass tries.
+     * It also retries an owner's boot-time publish that failed.
+     *
+     * A try before the row has arrived is a `skipped` publish: one `CadrePeer` read. Not tried
+     * while the node waits to be claimed (it has no row and no party yet) or once it has learned
+     * it was removed (nothing to publish). A removed node that never saw its own row live in this
+     * process does not learn it was removed ({@link noteOwnRemoval}), and pays that read on every
+     * pass.
+     *
+     * Connected-only: a row written elsewhere arrives over a connection, and an owner's publish
+     * committed alone is local-only and forks its own history — a restarted owner whose embedder
+     * runs a pass before it reconnects would write its row on the stale side of the fork, and
+     * then never see rows written while it was down (`cadre-invite-any-member` runs that pass and
+     * fails every time without this condition). The boot-time publish and the first-growth drain already try at the node's lone and
+     * first-connection moments; this retries on the passes after.
+     */
+    private publishFirstSelfRecord;
     /**
      * Collect this node's current dialable addresses for publication, signaling
      * (`/p2p-circuit`) first. Prefers the best invite/NAT-resolved set and folds
@@ -1480,8 +1623,9 @@ export declare class CadreNode implements SAppIdLookup {
      * ({@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).
+     * `peerId`, so it does not belong in this peer's candidate list (`dialPeerAddrs`
+     * binds every address to the peer it is given and drops the same shape one
+     * layer lower; here it is dropped before it can reach the address book).
      */
     private normalizeDialAddrs;
     /**
@@ -1654,9 +1798,9 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * 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.3.11)
-     * rejects an address no transport can dial before touching the network, so
-     * such an address costs a log line.
+     * filtering here: libp2p's transport manager rejects an address no transport
+     * can dial before touching the network (`TransportUnavailableError`), 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, and sorts loopback
@@ -3147,6 +3291,15 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * Passing an empty list stops the supervisor and resets the posture to `none`
      * without dialing or waiting.
+     *
+     * NOTE: on a node with no `network.relayAddrs` (a browser tab with a hand-written
+     * bare `/p2p-circuit`), libp2p's relay discovery stays on, because it was the only
+     * thing filling that slot before this call. Such a tab connected to some other
+     * relay-capable peer it identifies (a party member running the relay server) can
+     * lose its one slot to that peer before this supervisor's request runs, the theft
+     * `nodeTransportsOption` prevents on configured nodes (`relay-reservation.ts`). If a
+     * tab is ever seen reserved through a relay it was not asked to use, build that
+     * node through `withoutRelayDiscovery` too, or have the tab configure `relayAddrs`.
      */
     reserveRelays(addrs: string[], opts?: RelayReservationSupervisorOptions): Promise<RelayReservationState>;
     /**
@@ -3238,6 +3391,11 @@ export declare class CadreNode implements SAppIdLookup {
      * {@link isMember}). Rows whose stamp is retired in `CadreControl.Revocation`
      * never reach here: {@link ControlDatabase.queryCadrePeers} excludes them, so a
      * revoked peer is not addressable either.
+     *
+     * NOTE: answers the whole `CadrePeerRow`, past the two fields declared; the integration
+     * harness (`owner-cli-node.ts`, `OwnerCliMemberRow.sig`) reads `sig` off it through the admin
+     * channel to tell a row another member seated from one the subject published itself. Narrow
+     * this to the declared fields only together with that reader.
      */
     listMembers(): Promise<Array<{
         peerId: string;
@@ -3319,6 +3477,14 @@ export declare class CadreNode implements SAppIdLookup {
      * source so the membership refresh can share one load with {@link syncOwnerAnchor}.
      */
     private collectAuthorizedMembers;
+    /** The invitation chain, loaded only when some row in `rows` is invitation-admitted. */
+    private chainFor;
+    /**
+     * The authorized members among `rows`, already read: checks 1 to 4 of
+     * {@link listAuthorizedMembers}' predicate (check 5 is `queryCadrePeers`'s), so the membership
+     * refresh can judge the rows it has to read anyway for the hang-up of removed peers.
+     */
+    private authorizedAmong;
     /**
      * Checks 2–4 of the authorized-membership predicate (see
      * {@link listAuthorizedMembers}) for one `CadrePeer` row, by the kind of proof it
@@ -3357,7 +3523,8 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * NOTE: cost per membership refresh is one `OwnerKey` read and one `Revocation` read (the
      * tombstone list, whose `OwnerKey` stamps are handed to `queryOwnerKeyRows` so it does not
-     * read the retired set again), plus the invitation chain when some owner row is
+     * read the retired set again, and which the hang-up of removed peers shares through
+     * `loadTombstones`), plus the invitation chain when some owner row is
      * invitation-admitted — shared with the membership read through `loadChain`; the memo
      * suggestion on {@link loadInvitationChain} covers that part. Before the Revocation ledger
      * marker is filed that one read is a cohort consult per refresh, which
@@ -3365,6 +3532,7 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * @param retry - forwarded to every read; `false` on the refresh path, for the reason on
      *   {@link refreshAuthorizedControlPeers}.
+     * @param loadTombstones - the refresh's shared tombstone read ({@link revocationSource}).
      */
     private syncOwnerAnchor;
     /**
@@ -3387,6 +3555,8 @@ export declare class CadreNode implements SAppIdLookup {
      * {@link loadInvitationChain}, every later call shares that load.
      */
     private invitationChainSource;
+    /** A per-refresh {@link RevocationSource}: one `queryRevocations` read, shared by every caller in the pass. */
+    private revocationSource;
     /**
      * The usage and invitation rows {@link hasAnchoredProof} and {@link syncOwnerAnchor}
      * resolve an invitation-admitted row through, keyed for lookup. Both reads honour `retry`
@@ -3563,6 +3733,10 @@ export declare class CadreNode implements SAppIdLookup {
      * Remove a previously-authorized peer from the cadre.
      * Signs the peer ID with the owner key and deletes the CadrePeer row.
      *
+     * Removes the `CadrePeer` row only. The call that removes a machine completely (its owner
+     * key, its push token and the invitations it could come back through, in one transaction)
+     * is {@link removeMachine}.
+     *
      * @param peerId - The peer ID to remove
      */
     removePeer(peerId: string): Promise<void>;
@@ -3582,10 +3756,82 @@ export declare class CadreNode implements SAppIdLookup {
      * tombstone rides the committed-delete seam ({@link noteGuardedDelete}), so one committed
      * while alone is re-issued on cohort growth like every other removal.
      *
+     * Removes the `OwnerKey` row only. The call that removes a machine completely, its owner key
+     * included, is {@link removeMachine}.
+     *
      * @param ownerPublicKeyB64 - the owner's ed25519 public key (base64url).
      * @returns `true` when the row was removed, `false` when the key is not a live owner here.
      */
     removeOwner(ownerPublicKeyB64: string): Promise<boolean>;
+    /**
+     * The cadre's machines as an app lists them ({@link CadreMachine}): one entry per live
+     * `CadrePeer` row, judged by this node's membership predicate, plus one per live `OwnerKey`
+     * whose key names a machine with no row (`describeMachines` in `machine-removal.ts`).
+     * Unlocked reads with the default retry.
+     */
+    listMachines(): Promise<CadreMachine[]>;
+    /**
+     * What {@link removeMachine} would do for `peerId`, read without writing, for an app's
+     * confirmation step ({@link MachineRemovalPlan}): whether this node may remove it, whether its
+     * owner key goes with it, which rows that key vouched (so the app can offer to keep them by
+     * re-vouching), which invitations it could come back through, and whether this node's own
+     * rows depend on it (`planMachineRemoval` in `machine-removal.ts`).
+     */
+    planMachineRemoval(peerId: string): Promise<MachineRemovalPlan>;
+    /**
+     * Remove a machine from the cadre completely, signed by this node's owner key: its
+     * `CadrePeer` row, its `OwnerKey` row when its key is an owner, its `DeviceToken` row (a
+     * removed phone must not be push-woken) and a withdrawal of every live invitation it could
+     * redeem to come back, in ONE transaction ({@link ControlDatabase.removeMachine}), with a
+     * `Revocation` tombstone per row so the removal holds on every machine
+     * ("Deletes made while alone" in docs/architecture.md).
+     *
+     * Steps: re-plan ({@link planMachineRemoval}) and throw {@link MachineRemovalRefusedError} on a
+     * refusal; check `options.revouch` against the plan's dependents and throw before any write
+     * when it names anything else; **re-vouch first**, under this node's key, the dependents the
+     * caller chose to keep (`ControlDatabase.revouchOwnerKey`, `reauthorizePeer`), so they are
+     * never untrusted in between, and stop before the removal if one fails (re-vouches already
+     * made stay, harmlessly); then the removal transaction. Afterwards this node forgets the
+     * machine as a dial target, and the refresh the write notifies hangs up its control
+     * connection ({@link hangUpRevokedControlPeers}) before this resolves.
+     *
+     * Not undone by this call: the machine keeps every row and strand block it already synced
+     * and the party's strand member keys (`tickets/blocked/decide-removed-machine-strand-access`).
+     * A fresh invitation re-admits it later under fresh stamps.
+     *
+     * @returns what was written ({@link MachineRemovalResult}); all false when no live row names
+     *   the machine here (already removed elsewhere).
+     * @throws {MachineRemovalRefusedError} `'not-an-owner'`, `'self'` or `'last-owner'`.
+     */
+    removeMachine(peerId: string, options?: RemoveMachineOptions): Promise<MachineRemovalResult>;
+    /**
+     * The reads behind {@link listMachines}: the live `CadrePeer` and `OwnerKey` rows and the
+     * machines projected from them, with this node's membership predicate as the `trusted` test.
+     */
+    private readMachines;
+    /** {@link planMachineRemoval} with the rows it was judged from, which {@link removeMachine} re-vouches dependents by. */
+    private planMachineRemovalWith;
+    /**
+     * The re-vouch step of {@link removeMachine}: every chosen dependent row is rebound to this
+     * node's key BEFORE the removal, so no reader ever judges it against an owner that is gone.
+     * Owners through `ControlDatabase.revouchOwnerKey` (a delete-and-re-add under a fresh stamp,
+     * the only rebinding `OwnerKey.NoUpdate` allows); peers through the owner re-touch
+     * (`reauthorizePeer`), which rewrites `VouchOwner`/`VouchSig` and clears `VouchUsage`.
+     *
+     * The peer re-touch keeps the row's `UpdatedAt` where it is. The owner branch of
+     * `CadrePeer.AuthorizedUpdate` does not require a bump, and bumping a self-published row
+     * would leave its `Sig` unverifiable, so unresolvable and unlisted as self-published, until
+     * the machine's next heartbeat (the NOTE on that constraint); the write-while-alone drain
+     * bumps because it re-issues an otherwise unchanged row, whereas here the voucher itself
+     * changes. A row never self-published carries no stamp to keep and gets the clock.
+     *
+     * A failure rethrows and stops the call before the removal; re-vouches already made stay
+     * (the row is only re-signed by a current owner) and the caller retries. An owner re-vouch
+     * committed alone is not re-issued on growth (the add half has no re-issue path,
+     * `tickets/backlog/debt-owner-key-add-while-alone-has-no-reissue`), so it is logged as
+     * {@link addOwner} logs it; the peer re-touches are re-issued by the existing drain.
+     */
+    private revouchDependents;
     /**
      * Create a seed from the current control network state.
      * The seed contains peer information and is signed by an owner.
@@ -3706,6 +3952,20 @@ export declare class CadreNode implements SAppIdLookup {
      * Use when both nodes are NAT'd (phone-to-phone).
      */
     addPhoneWithRelay(phonePeerId: string): Promise<DroneInitResult>;
+    /**
+     * Where a device could redeem a cadre invitation minted now from, once this machine is gone
+     * ({@link CadreInvitationReach}): the same member selection {@link createCadreInvitation}
+     * makes, judged without minting anything. `rentNode` reads it to choose between inviting a
+     * provider's container and claiming it; `local-network` counts as not reachable there, since
+     * the container is never on a member's LAN. Requires a started node.
+     */
+    invitationReach(): Promise<CadreInvitationReach>;
+    /**
+     * The `members` a cadre invitation minted now would name, and how far they reach: one
+     * selection behind both {@link createCadreInvitation} and {@link invitationReach}, so the
+     * two cannot disagree.
+     */
+    private selectInvitationMembers;
     /**
      * Mint an owner-signed cadre invitation that a device can redeem at ANY member machine of
      * this party, the owner offline included ({@link redeemCadreInvitation}). Requires the
@@ -3723,9 +3983,13 @@ export declare class CadreNode implements SAppIdLookup {
      * only, never the raw replicated `OwnerKey` table, because the device anchors whatever
      * arrives and a stranger's genesis-inserted key must not ride an invitation into a fresh
      * node's anchor; an empty anchor is refused because a reply could not be checked), and
-     * the addresses of this machine first
-     * ({@link resolveInviteAddresses}, which honours pushed NAT addresses) then up to three
-     * other members ({@link siblingInvitationAddrs}).
+     * at most six addresses: this machine's first ({@link resolveInviteAddresses}, which
+     * honours pushed NAT addresses), then two each of up to three other members
+     * (`selectCadreInvitationMembers`), so the encoded text fits a QR code.
+     *
+     * The result's `reach` says where a device could redeem it from once this machine is gone
+     * (`cadreInvitationReach`, judged on the other members' addresses only), so an app can warn
+     * before handing over an invitation only it could answer.
      *
      * The row commits locally and replicates like any other control write; minted while
      * alone (a phone with no connection), it reaches the other members through the
@@ -3762,7 +4026,7 @@ export declare class CadreNode implements SAppIdLookup {
      * Steps: refuse an invitation for another party; pin its `ownerKeys` into the node-local
      * anchor (`'invite'` provenance — the pin sticks even if the redemption then fails, as it
      * does for a seed invite, so a later attempt or seed from the same owner is anchored);
-     * sign the request; dial the listed members in order ({@link redeemAtMembers}); on
+     * sign the request; dial the listed members in order (`redeemAtMembers`); on
      * acceptance verify the reply against the pinned keys, merge its dial hints into the peer
      * store, retain the answering member as a cold-start dial target, refresh the membership
      * gate and start a cohort reconcile pass. This node then syncs the control database over
@@ -3771,11 +4035,20 @@ export declare class CadreNode implements SAppIdLookup {
      * A device that is already a member (a restart with the invitation still configured) is
      * answered as accepted by the member's idempotent redemption, with no second usage row.
      *
+     * One pass over the listed members by default. With `options.waitForMember` the call keeps
+     * making passes while every answer is retryable — for a device redeeming while no
+     * always-on member is up — until a member accepts, one refuses finally, the invitation
+     * expires (thrown as the `invite-spent` refusal) or `options.signal` aborts
+     * (`redeemInPasses`). The request is signed once, before the first pass, and every pass
+     * sends it: its `usageStampId` keys the usage row, so a member that admitted this node on a
+     * pass whose reply was lost answers the next as already a member. `options.onProgress`
+     * reports each pass and pause.
+     *
      * When the invitation grants ownership, the member seats this node's key as an `OwnerKey`
-     * row by consent. The caller still has to wire that key for signing afterwards —
-     * `initializeSeedBootstrap(ownKey)`, which anchors it; never `ensureOwnerKey`, the row is
-     * already there. Other machines derive this node's key into their anchors from the row's
-     * stored proof on their next membership refresh ({@link syncOwnerAnchor}).
+     * row by consent. The caller still has to wire that key for signing afterwards, with
+     * {@link wireOwnKeyIfOwner}; never `ensureOwnerKey`, the row is already there. Other
+     * machines derive this node's key into their anchors from the row's stored proof on their
+     * next membership refresh ({@link syncOwnerAnchor}).
      *
      * Limit: the reply check ({@link verifyRedeemReply}) does not authenticate the member. A
      * forged bundle, or a legitimate one whose addresses were swapped, dials a machine that
@@ -3786,10 +4059,29 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * @throws `CadreInviteRejectedError` on a final refusal, `CadreInviteReplyInvalidError` on
      *   an acceptance that fails the reply check, `CadreInviteUnreachableError` when every
-     *   listed address was tried without an acceptance, and a plain `Error` for the
-     *   preconditions above.
+     *   listed address was tried without an acceptance (one pass only), the signal's reason on
+     *   an abort, and a plain `Error` for the preconditions above.
+     */
+    redeemCadreInvitation(invitation: CadreInvitation, options?: RedeemCadreInvitationOptions): Promise<RedeemCadreInvitationResult>;
+    /**
+     * If this node's identity key is a live `OwnerKey` here, wire it for signing
+     * ({@link initializeSeedBootstrap}) and return true; otherwise change nothing and return
+     * false. For a machine that joined someone else's cadre by invitation: after an
+     * owner-granting redemption, and on every later start. A redemption seats the request's
+     * `peerKey`, the key behind this node's peer id, so the identity key is the one to look for.
+     *
+     * Unlike `ensureOwnerKey` it never inserts an `OwnerKey` row, so a machine that joined a
+     * cadre can never genesis-insert itself into it, and a non-owner never anchors its own key.
+     * An owner whose key is already wired (an earlier call) is answered true with nothing redone.
+     *
+     * NOTE: a node running the listener-only seed service ({@link enableSeedListener}) cannot be
+     * wired this way: libp2p takes one seed handler, and {@link initializeSeedBootstrap} would
+     * register a second. Nothing that joins by invitation enables the listener today; if one
+     * does, replace the listener here rather than beside it.
+     *
+     * @throws when the node is not started.
      */
-    redeemCadreInvitation(invitation: CadreInvitation): Promise<RedeemCadreInvitationResult>;
+    wireOwnKeyIfOwner(): Promise<boolean>;
     /**
      * Replace this node's strand solicitation service — the formation responder every node
      * installs at {@link start}, and the initiator side of {@link formStrand}. Optional: call it
@@ -3842,17 +4134,21 @@ export declare class CadreNode implements SAppIdLookup {
      */
     createOpenInvitation(sAppId: string, expirationMs?: number): Promise<OpenInvitation>;
     /**
-     * Addresses of the party's other machines for an invitation's bootstrap list — an open
-     * strand invitation's ({@link createOpenInvitation}) or a cadre invitation's
-     * ({@link createCadreInvitation}); {@link selectInvitationSiblingAddrs} picks which. The
-     * source is each authorized member's signed `CadrePeer` record ({@link resolvePeerRecord}),
-     * so a machine whose record is missing, stale or untrusted is left out; live connections
-     * only order them.
+     * Addresses of the party's other machines for an open strand invitation's bootstrap list
+     * ({@link createOpenInvitation}); {@link selectInvitationSiblingAddrs} picks which.
+     */
+    private siblingInvitationAddrs;
+    /**
+     * The party's other machines an invitation may name — an open strand invitation
+     * ({@link siblingInvitationAddrs}) or a cadre invitation ({@link createCadreInvitation}) —
+     * and which of them this node is connected to. The source is each authorized member's
+     * signed `CadrePeer` record ({@link resolvePeerRecord}), so a machine whose record is
+     * missing, stale or untrusted is left out; live connections only order them.
      *
      * Best-effort: a failed read leaves the invitation naming this machine alone, which is what
      * it named before siblings were added.
      */
-    private siblingInvitationAddrs;
+    private resolveInvitationSiblings;
     /**
      * Form a strand with a responder via an open invitation: one attempt, from this machine, with
      * nothing recorded party-wide. {@link requestJoin} is the path that keeps trying.