@serfab/cadre-core 1.9.0 → 1.10.0

package/dist/cadre-node.js

@@ -32,12 +32,16 @@ import { PeerJoinBackfill } from './peer-join-backfill.js';
 import { deriveCohortMembers } from './strand-cohort.js';
 import { selectControlCohortDials, DEFAULT_CONTROL_COHORT_RECONCILE_MS, DEFAULT_CONTROL_COHORT_TARGET_DEGREE } from './control-cohort.js';
 import { dialPeerAddrs, SelfRelayOnlyError, CONTROL_COHORT_DIAL_ADDRESS_ATTEMPTS } from './peer-dial.js';
-import { ADMISSION_DECISION_TIMEOUT_MS, declaredCohortReadDeadlineMs, peerJoinPushBudget, relayAdmissionReserveDeadlineMs, relayReservationBudgetMs, relayedDialBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { ADMISSION_DECISION_TIMEOUT_MS, declaredCohortReadDeadlineMs, optimysticDialLimits, peerJoinPushBudget, relayAdmissionReserveDeadlineMs, relayReservationBudgetMs, relayedDialBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 import { EnrollmentService } from './enrollment.js';
 import { HibernationManager } from './hibernation-manager.js';
-import { ControlDatabase, isStrandIdConflict } from './control-database.js';
+import { ControlDatabase, isPendingJoinConflict, isStrandIdConflict, pendingJoinId } from './control-database.js';
+import { FormationPostApprovalError } from './strand-formation-rejection.js';
+import { PendingJoinRunner, membershipInvitesToStage, parseStoredDisclosure, requestedPendingJoin } from './pending-join-runner.js';
 import { SeedBootstrapService } from './seed-bootstrap.js';
 import { StrandSolicitationService } from './strand-solicitation.js';
+import { ControlFormationUsageRecorder } from './control-formation-recorder.js';
+import { selectInvitationSiblingAddrs } from './invitation-bootstrap.js';
 import { createMembershipConnectionGater, DEFAULT_ENROLLMENT_WINDOW_MS, UnauthorizedReservationBudget } from './membership-connection-gater.js';
 import { StrandWakeService, dialWake } from './strand-wake-protocol.js';
 import { StrandAddrService, collectStrandAddrs } from './strand-addr-protocol.js';
@@ -250,6 +254,15 @@ export class CadreNode {
         this.strandWatcher = null;
         this.seedBootstrapService = null;
         this.strandSolicitationService = null;
+        /**
+         * The service whose formation handler is registered on the control node. Trails
+         * {@link strandSolicitationService} while {@link initializeStrandSolicitation} swaps a new
+         * one in: the field is set at once so concurrent callers reuse it, the handler only when
+         * its queued swap runs.
+         */
+        this.registeredSolicitation = null;
+        /** Tail of the queued formation-handler swaps ({@link swapFormationResponder}). */
+        this.solicitationSwaps = Promise.resolve();
         this.strandWakeService = null;
         /**
          * Control-network strand-address responder. Answers a co-cadre sibling's
@@ -517,6 +530,20 @@ export class CadreNode {
          * `unpublishStrand` / `forgetJoinedStrand` as {@link formationStrandAddrs} is.
          */
         this.pendingMembershipInvites = new Map();
+        /**
+         * Invite keys of the membership invitations this process has staged, by
+         * {@link adoptFormationMembershipInvite} or from a `joined` `PendingJoin` row
+         * ({@link stageMembershipInvitesFromPendingJoins}), so one the reconciler has settled is not
+         * staged again by the next pending-join pass. Same lifetime as
+         * {@link pendingMembershipInvites}: a restarted process stages each live one once more, and the
+         * reconciler settles it again (spent, or the party already seated).
+         */
+        this.stagedMembershipInviteKeys = new Set();
+        /**
+         * The pending-join retry loop (`pending-join-runner.ts`): built by {@link start}, stopped by
+         * {@link cleanup}. It acts only while this machine is an enrolled owner.
+         */
+        this.pendingJoinRunner = null;
         /**
          * Founder launches refused because the strand was founded before the per-party
          * identity split (`PreSplitStrandIdentityError`), keyed by strandId. Read by
@@ -1010,6 +1037,11 @@ export class CadreNode {
                 onDelegateAnnounce: (announcer, strandId, delegate) => this.grantDelegateAdmission(announcer, strandId, delegate),
             });
             await this.strandAddrService.initialize(this.controlNode);
+            // Answer strand formation for this party from now on. Every machine of a party
+            // holds the replicated FormationInvite/FormationUsage rows, so an always-on one can
+            // check a token for an inviter that is offline. After the control database is up,
+            // so the responder never reads a database that cannot answer yet.
+            await this.installDefaultFormationResponder();
             // Server-side push-wake fan-out: only when push is configured.
             if (this.config.push) {
                 this.pushFanoutService = this.buildPushFanout(this.config.push);
@@ -1043,6 +1075,8 @@ export class CadreNode {
             await this.driveControlRelayReservation();
             // Schedule self-registration in background
             this.scheduleSelfRegistration();
+            // Last: its first pass may dial another party's machines.
+            this.startPendingJoinRunner();
         }
         catch (error) {
             log('Failed to start CadreNode: %o', error);
@@ -1593,11 +1627,15 @@ export class CadreNode {
             // replaces the default whole (see DEFAULT_CONNECTION_MONITOR).
             connectionMonitor: network?.connectionMonitor ?? DEFAULT_CONNECTION_MONITOR,
             // The declared link every cadre budget is derived from, stated to Optimystic too so it
-            // derives its own deadlines from the same number: its request dials and responses, its
-            // block pushes, and libp2p's `dialTimeout` and `inboundUpgradeTimeout`. Always stated,
-            // default included: undeclared, Optimystic keeps LAN deadlines that cannot open a
-            // relayed connection at the link sereus supports (`link-budget.ts`).
+            // derives its own deadlines from the same number: its request responses, its block
+            // pushes, and libp2p's `inboundUpgradeTimeout`. Always stated, default included:
+            // undeclared, Optimystic keeps LAN deadlines that cannot open a relayed connection at the
+            // link sereus supports (`link-budget.ts`).
             linkRoundTripMs: resolveLinkRoundTripMs(network?.linkRoundTripMs),
+            // The three limits on opening a connection (libp2p's per-address and whole-dial limits,
+            // and Optimystic's request dial): Optimystic's derivation from the same link plus the
+            // relay's and the called machine's admission decisions, which run on this dial's clock.
+            ...optimysticDialLimits(network?.linkRoundTripMs),
             // `{ wsPort }` when a listen entry names WebSocket, otherwise `{}` — and always
             // `{}` when `network.transports` is set, since the embedder owns transport policy
             // then. Spread NEXT to `transports` because the two answer the same question.
@@ -1670,11 +1708,9 @@ export class CadreNode {
      *     `StrandSolicitationService.hasOutstandingInvitation`). A formation
      *     initiator is another party's peer by design and its token is only
      *     checkable inside the protocol, so the gate asks the coarser question
-     *     "does this node expect a stranger at all?". Merely REGISTERING the
-     *     responder ({@link initializeStrandSolicitation}) no longer suspends
-     *     stranger denial — eager registration (as `reference-app-rn` does at
-     *     bring-up) and `formStrand`'s lazy initialization both leave the gate
-     *     armed, because neither mints an invitation.
+     *     "does this node expect a stranger at all?". REGISTERING the responder
+     *     does not suspend stranger denial: every node registers one at
+     *     {@link start}, and registering mints no invitation.
      *
      * Ordering is semantically free (the checks are OR'd) but decides who pays:
      * checks 1-3 are in-memory, 4/5 share one control-DB read, and only a peer
@@ -1706,6 +1742,11 @@ export class CadreNode {
      * layer is fail-open behind `ADMISSION_DECISION_TIMEOUT_MS`, so the live
      * read is safe here — unlike the per-stream gate, which must consult the
      * materialized {@link authorizedControlPeers} snapshot instead.
+     * NOTE: check 6 adds a second control read (`hasOutstandingFormationInvite`) for a
+     * stranger with no locally minted invitation in play, on every node now that every
+     * node runs the responder — a relay-enabled storage node included. If stranger
+     * connections to such a node ever arrive fast enough for that read to show, cache
+     * the answer for a few seconds.
      * NOTE: on a relay-DISABLED node, a sibling whose membership row has not yet
      * replicated here is denied until the row converges (typically via the
      * owner); either side's next outbound reconcile dial (outbound is never
@@ -2549,19 +2590,27 @@ export class CadreNode {
      * handling, is what keeps a mixed list from taking a whole peer offline.
      */
     async resolvePeerAddrs(peerId, opts = {}) {
+        return (await this.resolvePeerRecord(peerId, opts))?.addrs ?? [];
+    }
+    /**
+     * {@link resolvePeerAddrs} with the record's `UpdatedAt` kept beside the addresses, for a
+     * caller that ranks peers by how recently they published. `null` wherever that returns `[]`
+     * for a failed gate.
+     */
+    async resolvePeerRecord(peerId, opts) {
         if (!this.controlDatabase) {
             throw new Error('CadreNode must be started before resolving peer addrs');
         }
         const record = await this.controlDatabase.queryPeerRecord(peerId);
         if (!record) {
             log('resolvePeerAddrs: no record for %s', peerId);
-            return [];
+            return null;
         }
         // publicKey <-> peerId binding: the stored key must be the one embedded in
         // the requested Ed25519 peer id (also rejects a non-Ed25519 / missing key).
         if (!record.publicKey || ed25519PublicKeyB64FromPeerId(peerId) !== record.publicKey) {
             log('resolvePeerAddrs: publicKey does not match peerId for %s', peerId);
-            return [];
+            return null;
         }
         // Self-signature over (peerId, addrs, updatedAt).
         if (!verifyPeerRecordSignature(record)) {
@@ -2569,13 +2618,13 @@ export class CadreNode {
             // no addrs — a not-yet-self-published row)" from a genuinely corrupt or
             // mixed-revision row. Sig/addrs are public replicated data.
             log('resolvePeerAddrs: signature verification failed for %s (updatedAt=%d, addrs=%o, sig=%s)', peerId, record.updatedAt, record.addrs, record.sig ? `${record.sig.slice(0, 16)}…` : '(empty)');
-            return [];
+            return null;
         }
         // Freshness: never hand back a dead relay reservation.
         const maxAgeMs = opts.maxAgeMs ?? DEFAULT_PEER_RECORD_MAX_AGE_MS;
         if (!isPeerRecordFresh(record.updatedAt, maxAgeMs, Date.now())) {
             log('resolvePeerAddrs: record for %s is stale (updatedAt=%d, maxAgeMs=%d)', peerId, record.updatedAt, maxAgeMs);
-            return [];
+            return null;
         }
         // Pluggable trust gate (defaults to current-member).
         const trustPolicy = opts.trustPolicy ?? currentMemberTrustPolicy();
@@ -2587,7 +2636,7 @@ export class CadreNode {
         });
         if (!trusted) {
             log('resolvePeerAddrs: trust policy rejected %s', peerId);
-            return [];
+            return null;
         }
         // Order signaling-first (the on-record order was what we verified above),
         // optionally restrict to signaling addrs, then parse — dropping any addr
@@ -2597,7 +2646,7 @@ export class CadreNode {
         if (opts.signalingOnly) {
             addrs = addrs.filter(isSignalingAddr);
         }
-        return this.normalizeDialAddrs(this.parseMultiaddrs(addrs), peerId);
+        return { addrs: this.normalizeDialAddrs(this.parseMultiaddrs(addrs), peerId), updatedAt: record.updatedAt };
     }
     /**
      * Guarantee every address handed to a control-network dial terminates in
@@ -3131,15 +3180,18 @@ export class CadreNode {
      *
      * 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)
+     * 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.
      *
      * 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.
+     * addresses one after another under a single deadline, and sorts loopback
+     * addresses last — so one or two addresses that never answer use up most of
+     * the deadline before the address that works is tried. libp2p 3.3's
+     * per-address `addressDialTimeout` does not prevent that: cadre sizes it for a
+     * cold relayed open through two admission decisions (`optimysticDialLimits`,
+     * 39 s at the default declared link).
+     * {@link dialPeerAddrs} dials each address on its own time limit instead.
      */
     async resolveControlDialAddrs(peerId, resolved) {
         if (resolved.length > 0) {
@@ -3504,6 +3556,8 @@ export class CadreNode {
         }
         // 4. In-session pending owner authorize writes.
         await this.drainPendingPeerWrites();
+        // 5. `PendingJoin` rows this process wrote while alone. Their tombstones went out in step 1.
+        await this.pendingJoinRunner?.reissueWritesMadeAlone();
     }
     /**
      * Re-touch this node's own `DeviceToken` row (re-sign + bump `UpdatedAt` via
@@ -4147,6 +4201,10 @@ export class CadreNode {
         // it is stopped here.
         this.relayReserveSupervisor?.stop();
         this.relayReserveSupervisor = null;
+        // Before anything it reads is torn down. An attempt in flight is not awaited (NOTE at
+        // `PendingJoinRunner.stop`).
+        this.pendingJoinRunner?.stop();
+        this.pendingJoinRunner = null;
         // Drop the rest of the relay-reservation posture: a torn-down node holds no
         // reservation, so neither a restarted instance nor a caller inspecting a failed
         // start reports the previous attempt's `reserved`.
@@ -4185,11 +4243,14 @@ export class CadreNode {
             await this.pushFanoutService.close().catch((err) => log('Push fan-out close failed: %o', err));
             this.pushFanoutService = null;
         }
-        // Unregister strand solicitation service
-        if (this.strandSolicitationService && this.controlNode) {
-            await this.strandSolicitationService.unregisterResponder(this.controlNode);
-            this.strandSolicitationService = null;
+        // Unregister the formation responder once any queued swap has run, so no swap
+        // registers a handler after this. A restarted node installs a fresh one.
+        await this.solicitationSwaps;
+        if (this.registeredSolicitation && this.controlNode) {
+            await this.registeredSolicitation.unregisterResponder(this.controlNode);
         }
+        this.registeredSolicitation = null;
+        this.strandSolicitationService = null;
         // Stop strand watcher
         if (this.strandWatcher) {
             await this.strandWatcher.stop();
@@ -5658,9 +5719,9 @@ export class CadreNode {
      * caller runs the drive regardless).
      *
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
-     * timeouts (dial by peer id, then by addr; 23 s each at the default declared link round trip)
+     * timeouts (dial by peer id, then by addr; 28.5 s each at the default declared link round trip)
      * before the reservation drive even starts, so one failed re-drive holds the supervisor
-     * `driving` for those 46 s plus the drive's own deadline — 64 s at the default, and longer on
+     * `driving` for those 57 s plus the drive's own deadline — 75 s at the default, and longer on
      * a host that declared a slower one (`link-budget.ts`).
      * Bounded and harmless while the relay is unreachable anyway; if recovery
      * latency after a relay comes back ever matters, skip the announce when the
@@ -6581,6 +6642,9 @@ export class CadreNode {
             ...(this.trustedOwnerStore ? { trustedOwners: this.trustedOwnerStore } : {}),
         }), this.controlNode, this.controlDatabase);
         log('Seed bootstrap service initialized');
+        // Embedders wire the owner key after start(), so the runner's first pass usually found
+        // this machine not yet an owner; without this it would wait a full poll interval.
+        this.pendingJoinRunner?.kick();
     }
     /**
      * Push the multiaddrs that future invites should advertise. Pass `null` to
@@ -7260,19 +7324,32 @@ export class CadreNode {
     // Strand Solicitation API (native cadre-core formation transport)
     // ============================================================================
     /**
-     * Initialize the strand solicitation service.
-     * This enables forming strands with other parties via open invitations.
+     * 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
+     * only to customize the responder (an approver, a provisioner, formation deadlines). The
+     * new service's handler replaces the previous one's on the control node, and invitations
+     * the previous service minted stay outstanding.
+     *
+     * Without `options.formationUsageRecorder`, tokens are checked against this party's
+     * replicated `FormationInvite`/`FormationUsage` rows ({@link ControlFormationUsageRecorder}).
+     * A responder that accepts every token is reachable only by constructing
+     * {@link StrandSolicitationService} directly.
      *
      * @param options - Configuration for the solicitation service
      */
     async initializeStrandSolicitation(options) {
-        if (!this.controlNode) {
+        const controlNode = this.controlNode;
+        const controlDatabase = this.controlDatabase;
+        if (!controlNode || !controlDatabase) {
             throw new Error('CadreNode must be started before initializing strand solicitation');
         }
         const service = new StrandSolicitationService({
             ...options,
+            formationUsageRecorder: options?.formationUsageRecorder ?? new ControlFormationUsageRecorder(controlDatabase),
             partyId: this.config.controlNetwork.partyId,
-            cadrePeerAddrs: this.getMultiaddrs(),
+            // Read per formation: the responder is installed during start, before a relay
+            // reservation gives a relay-only node any address, and addresses change after.
+            cadrePeerAddrs: () => this.getMultiaddrs(),
             // Every formation deadline derives from this node's declared link, like every other
             // dial budget here; a caller's own declaration on the formation config still wins.
             formationConfig: {
@@ -7288,25 +7365,60 @@ export class CadreNode {
             // issuer here would admit joiners under someone else's authority.
             issueMembershipInvite: (strandId, signal) => this.issueStrandMembershipInvite(strandId, signal)
         });
-        // Set before the registration is awaited, so a concurrent createOpenInvitation /
-        // formStrand uses this service instead of building a second one whose handler
-        // would collide; a failed registration puts the previous service back.
-        // NOTE: same stray-handler caveat as installSeedBootstrapService — a failed
-        // peer-store merge leaves the formation handler registered, so a retry is a duplicate.
         const previous = this.strandSolicitationService;
+        if (previous) {
+            service.adoptMintedInvitations(previous);
+        }
+        // Set before the swap is awaited, so a concurrent createOpenInvitation / formStrand
+        // uses this service instead of building another.
         this.strandSolicitationService = service;
+        const swap = this.solicitationSwaps.then(() => this.swapFormationResponder(service, controlNode));
+        // The queue only orders swaps; a failed one rejects this call's own await below.
+        this.solicitationSwaps = swap.catch(() => undefined);
+        await swap;
+        log('Strand solicitation service initialized');
+    }
+    /**
+     * Answer formation from start. Log-and-continue: a node that cannot is still useful, and
+     * {@link createOpenInvitation} / {@link formStrand} install the responder when it is missing.
+     */
+    async installDefaultFormationResponder() {
+        try {
+            await this.initializeStrandSolicitation();
+        }
+        catch (error) {
+            log('Formation responder not installed at start; createOpenInvitation/formStrand will retry: %o', error);
+        }
+    }
+    /**
+     * Move the control node's formation handler from the registered service to `service`.
+     * Queued by {@link initializeStrandSolicitation} so swaps run one at a time: libp2p allows
+     * one handler per protocol id, and two overlapping swaps would each find the other's
+     * handler in the way. A failed swap registers the previous service again, points
+     * {@link strandSolicitationService} back at it unless a later call has replaced it, and
+     * rethrows.
+     *
+     * NOTE: same stray-handler caveat as {@link installSeedBootstrapService} — a failed
+     * peer-store merge leaves the formation handler registered, so the restore below (and a
+     * retry) rejects as a duplicate.
+     */
+    async swapFormationResponder(service, controlNode) {
+        const previous = this.registeredSolicitation;
         try {
-            await service.registerResponder(this.controlNode);
+            await previous?.unregisterResponder(controlNode);
+            await service.registerResponder(controlNode);
+            this.registeredSolicitation = service;
         }
         catch (error) {
             if (this.strandSolicitationService === service)
                 this.strandSolicitationService = previous;
+            await previous?.registerResponder(controlNode).catch((restoreError) => log('Re-registering the previous formation responder failed; none answers until the next initializeStrandSolicitation: %o', restoreError));
             throw error;
         }
-        log('Strand solicitation service initialized');
     }
     /**
-     * Get the strand solicitation service (for advanced use)
+     * Get the strand solicitation service (for advanced use). Non-null on a started node unless
+     * the install at {@link start} failed.
      */
     getStrandSolicitationService() {
         return this.strandSolicitationService;
@@ -7314,28 +7426,66 @@ export class CadreNode {
     /**
      * Create an open invitation for others to form strands with this party.
      *
+     * The invitation's bootstrap list names this machine first (it is the one most likely to
+     * run the host strand), then a few of the party's other machines
+     * ({@link siblingInvitationAddrs}), so a joiner can still form while this one is offline.
+     *
      * @param sAppId - The sApp to use for formed strands
      * @param expirationMs - How long the invitation is valid (ms from now)
      * @returns The open invitation to share out-of-band
+     * @throws when neither this machine nor any other machine of the party has an address
      */
     async createOpenInvitation(sAppId, expirationMs = 24 * 60 * 60 * 1000 // 24 hours default
     ) {
         if (!this.strandSolicitationService) {
-            // Create a temporary service for creating invitations
+            // Only when the install at start failed.
             await this.initializeStrandSolicitation();
         }
-        const bootstrap = this.getMultiaddrs();
+        const bootstrap = [...this.getMultiaddrs(), ...await this.siblingInvitationAddrs()];
         if (bootstrap.length === 0) {
             throw new Error('No multiaddrs available for invitation');
         }
         return await this.strandSolicitationService.createOpenInvitation(sAppId, expirationMs, bootstrap);
     }
     /**
-     * Form a strand with a responder via an open invitation.
+     * Addresses of the party's other machines for an invitation's bootstrap list
+     * ({@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.
+     *
+     * Best-effort: a failed read leaves the invitation naming this machine alone, which is what
+     * it named before siblings were added.
+     */
+    async siblingInvitationAddrs() {
+        const controlNode = this.controlNode;
+        if (!controlNode || !this.controlDatabase) {
+            return [];
+        }
+        try {
+            const siblings = [];
+            for (const { peerId } of await this.listAuthorizedMembers()) {
+                const resolved = await this.resolvePeerRecord(peerId, {});
+                if (resolved && resolved.addrs.length > 0) {
+                    siblings.push({ peerId, updatedAt: resolved.updatedAt, addrs: resolved.addrs.map(String) });
+                }
+            }
+            const connected = new Set(controlNode.getConnections().map((c) => c.remotePeer.toString()));
+            return selectInvitationSiblingAddrs(siblings, connected);
+        }
+        catch (error) {
+            log('createOpenInvitation: resolving the other machines failed; the invitation names only this one: %o', error);
+            return [];
+        }
+    }
+    /**
+     * 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.
      *
      * @param invitation - The open invitation received out-of-band
      * @param disclosure - Identity/context information to share with the responder
      * @returns The member key and strand info if successful
+     * @throws `FormationRejectedError` or `FormationUnreachableError` when the formation fails, and
+     *   `FormationPostApprovalError` when it was approved and a step on this machine then failed
      */
     async formStrand(invitation, disclosure = {}) {
         if (!this.controlNode) {
@@ -7356,6 +7506,171 @@ export class CadreNode {
         await this.rememberFormedStrand(result);
         return result;
     }
+    /**
+     * Ask to join through `invitation` and have the party keep trying until the join works, the
+     * invitation is used up or expires, or the request is dismissed: across restarts, and from
+     * any owner machine of the party (`docs/strands.md` → "Joining while the inviter is
+     * offline"). Records a party-wide `PendingJoin` row, runs one attempt on this machine at
+     * once, and returns the status after it: `'joined'` when the inviter answered yes, `'waiting'`
+     * when it was unreachable or not ready, `'failed'` when it refused for good.
+     *
+     * Asking again for an invitation whose request is still pending adopts that request as it
+     * is; asking again after it finished starts a fresh one. Later changes arrive as
+     * `pendingJoin:changed`. A joined strand is offered through `strand:discovered` like any
+     * {@link formStrand} join. Do not also call {@link formStrand} with the same invitation:
+     * nothing coordinates the two, and one of them gets `token-spent`.
+     *
+     * @throws on a machine that is not an enrolled owner (the row is owner-signed), and on an
+     *   invitation already past its expiration
+     */
+    async requestJoin(invitation, disclosure = {}) {
+        const { database, runner } = this.requirePendingJoins();
+        const signer = await this.requireOwnerSigner('requestJoin needs an enrolled owner machine of this party, because the party-wide join request is ' +
+            'owner-signed. formStrand(invitation, disclosure) joins once from this machine, with no retries.');
+        const now = Date.now();
+        const expiresAt = invitation.expiration.getTime();
+        if (!Number.isFinite(expiresAt)) {
+            throw new Error('The invitation carries no valid expiration');
+        }
+        if (now >= expiresAt) {
+            throw new Error(`The invitation expired at ${invitation.expiration.toISOString()}; ask the inviter for a fresh one`);
+        }
+        const requested = requestedPendingJoin(pendingJoinId(invitation.token), this.encodeInvitation(invitation), disclosure, expiresAt, now);
+        const row = await this.recordJoinRequest(database, requested, signer);
+        log('requestJoin: pending join %s recorded; attempting now', row.Id);
+        return runner.attemptNow(row);
+    }
+    /**
+     * Every join asked for with {@link requestJoin} and not dismissed, pending or finished, as this
+     * machine sees it (see `PendingJoinStatus` for which states are machine-local).
+     */
+    async listPendingJoins() {
+        const { database, runner } = this.requirePendingJoins();
+        return (await database.queryPendingJoins()).map((row) => runner.statusOf(row));
+    }
+    /**
+     * Remove a join request party-wide. On a pending request this cancels it: every owner machine
+     * stops at its next read, and an attempt already running does not record its outcome (a join
+     * it made stays on that machine, as any {@link formStrand} join does). Owner machines only.
+     * Resolves `false` when there was no such request.
+     */
+    async dismissPendingJoin(id) {
+        const { database, runner } = this.requirePendingJoins();
+        const { ownerKey, signMessage } = await this.requireOwnerSigner('dismissPendingJoin needs an enrolled owner machine of this party: the removal is owner-signed');
+        const removed = await database.deletePendingJoin(id, ownerKey, signMessage);
+        runner.forgetRow(id);
+        return removed;
+    }
+    requirePendingJoins() {
+        if (!this._running || !this.controlDatabase || !this.pendingJoinRunner) {
+            throw new Error('CadreNode must be started before using pending joins');
+        }
+        return { database: this.controlDatabase, runner: this.pendingJoinRunner };
+    }
+    /** This machine's owner key and signer for an owner-signed control write, or a throw carrying `refusal`. */
+    async requireOwnerSigner(refusal) {
+        const signingKey = await this.enrolledOwnerSigningKey();
+        if (!signingKey) {
+            throw new Error(refusal);
+        }
+        return { ownerKey: signingKey.publicKeyB64, signMessage: signMessageWith(signingKey.privateKeyB64) };
+    }
+    /**
+     * Write a join request's row, or adopt the party's existing row for the same invitation: a
+     * pending one as it is, a finished one replaced by `requested` (the user asked again).
+     */
+    async recordJoinRequest(database, requested, { ownerKey, signMessage }) {
+        let written;
+        try {
+            written = await database.insertPendingJoin(requested, ownerKey, signMessage);
+        }
+        catch (error) {
+            if (!isPendingJoinConflict(error)) {
+                throw error;
+            }
+            const existing = await database.queryPendingJoin(requested.Id);
+            if (!existing) {
+                throw new Error(`A removed join request for this invitation (${requested.Id}) is still held on this machine until its ` +
+                    'clean-up runs, which needs a connection to the party. Ask again once connected.', { cause: error });
+            }
+            if (existing.Outcome === null) {
+                return existing;
+            }
+            written = await database.replacePendingJoin(existing.StampId, requested, ownerKey, signMessage);
+        }
+        this.pendingJoinRunner?.noteWritten(written);
+        return written;
+    }
+    /** Build and start the pending-join retry loop over this node (see {@link pendingJoinRunner}). */
+    startPendingJoinRunner() {
+        const database = () => {
+            if (!this.controlDatabase) {
+                throw new Error('CadreNode is stopped: no control database for pending joins');
+            }
+            return this.controlDatabase;
+        };
+        const outcomeSigner = () => this.requireOwnerSigner('Cannot record a pending join outcome: this machine is not an enrolled owner of the party');
+        this.pendingJoinRunner = new PendingJoinRunner({
+            selfId: this.controlNode.peerId.toString(),
+            linkRoundTripMs: this.config.network?.linkRoundTripMs,
+            isOwner: async () => (await this.enrolledOwnerSigningKey()) !== null,
+            // NOTE: one owner-key read and one `PendingJoin` read per pass (30 s); for a party that never
+            // asked for a join the second reads a never-written block, which consults the cohort. If it
+            // shows up in a device profile, poll more slowly while the table reads empty.
+            readRows: () => database().queryPendingJoins(),
+            readRow: (id) => database().queryPendingJoin(id),
+            attempt: (row) => this.formStrand(this.pendingJoinInvitation(row), parseStoredDisclosure(row)),
+            replace: async (expectedStampId, next) => {
+                const { ownerKey, signMessage } = await outcomeSigner();
+                return database().replacePendingJoin(expectedStampId, next, ownerKey, signMessage);
+            },
+            remove: async (id) => {
+                const { ownerKey, signMessage } = await outcomeSigner();
+                return database().deletePendingJoin(id, ownerKey, signMessage);
+            },
+            isAlone: () => this.committedAlone(),
+            sAppIdOf: (row) => this.pendingJoinSAppId(row),
+            observeRows: (rows) => this.stageMembershipInvitesFromPendingJoins(rows),
+            emit: (status) => this.emit('pendingJoin:changed', status),
+        });
+        this.pendingJoinRunner.start();
+    }
+    /** The invitation a `PendingJoin` row stores. A failure names the row, never the invitation, which is a bearer credential. */
+    pendingJoinInvitation(row) {
+        try {
+            return this.decodeInvitation(row.Invitation);
+        }
+        catch {
+            throw new Error(`PendingJoin ${row.Id}: the stored invitation does not decode`);
+        }
+    }
+    pendingJoinSAppId(row) {
+        try {
+            return this.decodeInvitation(row.Invitation).sAppId;
+        }
+        catch {
+            log('PendingJoin %s: the stored invitation does not decode; reporting no sApp', row.Id);
+            return '';
+        }
+    }
+    /**
+     * Stage the membership invitation of each `joined` row this process has not staged yet, so a
+     * closed strand joined on another owner machine is seated by whichever machine launches it
+     * first; the party key it admits is the replicated `StrandPartyKey` row the finishing machine
+     * seated. A strand that already has an invitation staged keeps it, for the reconciler to
+     * settle first.
+     */
+    stageMembershipInvitesFromPendingJoins(rows) {
+        for (const { rowId, strandId, invite } of membershipInvitesToStage(rows, this.stagedMembershipInviteKeys, Date.now())) {
+            this.stagedMembershipInviteKeys.add(invite.inviteKey);
+            if (this.pendingMembershipInvites.has(strandId)) {
+                continue;
+            }
+            this.pendingMembershipInvites.set(strandId, invite);
+            log('pending join %s: staged its membership invitation for strand %s', rowId, strandId);
+            this.strandManager.notifyMembershipInviteStaged(strandId);
+        }
+    }
     /**
      * Remember the strand a formation just joined (see {@link joinedStrandStore}), so it
      * is re-offered after a restart even when the app is killed before its `addStrand`, and
@@ -7377,7 +7692,7 @@ export class CadreNode {
             });
         }
         catch (error) {
-            throw new Error(`Formation for strand ${result.strandId} was approved (its one-time token is spent), but ` +
+            throw new FormationPostApprovalError(result.strandId, `Formation for strand ${result.strandId} was approved (its one-time token is spent), but ` +
                 'remembering the join in this node\'s joined-strand store failed, so the strand would not ' +
                 'come back after a restart. Fix the store (usually the configured keyStore), then redeem a ' +
                 'fresh invitation.', { cause: error });
@@ -7410,12 +7725,13 @@ export class CadreNode {
             await this.ensureStrandPartyKey(strandId);
         }
         catch (error) {
-            throw new Error(`Formation for strand ${strandId} was approved (its one-time token is spent), but ` +
+            throw new FormationPostApprovalError(strandId, `Formation for strand ${strandId} was approved (its one-time token is spent), but ` +
                 'persisting this party\'s membership identity (StrandPartyKey) failed — the joiner ' +
                 'cannot become a member without it. Fix the underlying cause, then redeem a fresh ' +
                 'invitation (the delivered one dies with this error).', { cause: error });
         }
         this.pendingMembershipInvites.set(strandId, invite);
+        this.stagedMembershipInviteKeys.add(invite.inviteKey);
         log('formStrand: staged membership invitation for strand %s (party key persisted)', strandId);
         this.strandManager.notifyMembershipInviteStaged(strandId);
     }