@serfab/cadre-core 1.18.0 → 1.19.1

package/dist/cadre-node.d.ts

@@ -1,6 +1,7 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, FoundStrandOptions, FoundStrandBackgroundResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, SeedAckMessage, SeedDeliveryTarget, AddDroneOptions, DroneInitResult, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, CadreInviteStatus, CadreMachine, CadreOwnerKey, MachineRemovalPlan, MachineRemovalResult, OwnerKeyRemovalPlan, OwnerKeyRemovalResult, RemoveOwnerOptions, CadreRemoval, CadreInvitationReach, CreateCadreInvitationOptions, CreateCadreInvitationResult, RedeemCadreInvitationOptions, RedeemCadreInvitationResult, CreateOwnerGrantOptions, CreateOwnerGrantResult, OwnerGrantStatus, RedeemOwnerGrantOptions, RedeemOwnerGrantResult, JoinWithOwnerGrantResult, ResolveDeviceTokenOpts, PendingJoinStatus } from './types.js';
+import { type StrandLeaveOptions, type StrandOfflineMode } from './strand-offline.js';
 import { type TrustedOwnerStore, type TrustSource } from './trusted-owner-store.js';
 import { type OwnerSign, type OwnerSigner } from './owner-signer.js';
 import { type BootstrapPeerStore } from './bootstrap-peer-store.js';
@@ -2441,6 +2442,17 @@ export declare class CadreNode implements SAppIdLookup {
      * using. Emits `strand:writable` after the timers are settled.
      */
     private handleStrandWritable;
+    /**
+     * A status from a strand's offline queue (`StartStrandConfig.offline`). The queue sending counts
+     * as activity ({@link isSendingStatus}), so a check-in window that finds the cohort reachable stays
+     * up while the queue drains, and the idle timer does not cut a drain short. Recorded through the
+     * hibernation manager, not {@link recordStrandActivity}, whose push fan-out would wake other phones.
+     *
+     * Not on a strand being quiesced: activity there wakes it again once the quiesce ends, which would
+     * undo a `hibernateAll` made as the app went to the background. A send that quiesce cuts short was
+     * journaled before it went out, and the next build's restore re-sends it under the same action id.
+     */
+    private handleOfflineStatus;
     private handleStrandIdle;
     /**
      * Hibernate a strand: release its strand-network resources via the strand
@@ -2595,6 +2607,24 @@ export declare class CadreNode implements SAppIdLookup {
     whenStrandWritable(strandId: string, options?: {
         timeoutMs?: number;
     }): Promise<StrandInstance>;
+    /**
+     * Switch a strand between offline mode, where a commit resolves once the transaction is queued on
+     * this machine, and online mode (docs/strands.md → "Offline mode"). Affects transactions begun from
+     * now on; one already open keeps the acknowledgement it began with. The mode belongs to the strand:
+     * a hibernating strand takes it at its next build, and it lasts across hibernation and every
+     * rebuild until the process exits, after which the strand starts in `strandOffline.initialMode`.
+     *
+     * @throws StrandOfflineUnavailableError when `CadreNodeConfig.strandOffline` is not configured.
+     * @throws when this node does not run the strand.
+     */
+    setStrandOfflineMode(strandId: string, mode: StrandOfflineMode): void;
+    /**
+     * A strand's offline mode ({@link setStrandOfflineMode}); `'online'` on a node without
+     * `strandOffline`. The queue's own view, with what it holds, is `strand.database.offline.queueState()`.
+     *
+     * @throws when this node does not run the strand.
+     */
+    getStrandOfflineMode(strandId: string): StrandOfflineMode;
     /**
      * 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
@@ -2845,14 +2875,22 @@ export declare class CadreNode implements SAppIdLookup {
      * caller ever needs removal to mean "and erase the local copy", that is a separate purge
      * step, not a widening of this method.
      *
+     * Refuses while the strand's offline queue on this machine holds transactions, unless
+     * `options.discardQueued` (docs/strands.md → "Leaving a strand with unsent transactions"). The
+     * check and the discard run before the control-plane delete, so a delete refused afterwards
+     * leaves the discarded transactions discarded.
+     *
      * @param strandId - The `Strand` row id to remove (as passed to {@link publishStrand}).
+     * @param options - `discardQueued`: withdraw the queued transactions that were never sent, and remove.
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not
+     *   set; nothing was removed.
      * @throws if the node is not started, has no owner signer wired, the id is blank, or
      *   the signer is not an enrolled owner (the schema's `Strand.AuthorizedDelete` rejects
      *   the write and the row survives). A rejection does NOT imply the row survived: the
      *   local stop runs after the control-plane delete has already committed, so a failure
      *   there throws over a completed removal.
      */
-    unpublishStrand(strandId: string): Promise<void>;
+    unpublishStrand(strandId: string, options?: StrandLeaveOptions): 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
@@ -3400,11 +3438,36 @@ export declare class CadreNode implements SAppIdLookup {
      * The other members of the strand are not told, and this party's membership row in the
      * strand stays, so a later re-formation reuses the same identity.
      *
+     * Refuses while the strand's offline queue on this machine holds transactions, unless
+     * `options.discardQueued` (docs/strands.md → "Leaving a strand with unsent transactions"). The
+     * check and the discard run before the party-wide row is removed, so a removal refused
+     * afterwards leaves the discarded transactions discarded.
+     *
+     * @param options - `discardQueued`: withdraw the queued transactions that were never sent, and leave.
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not
+     *   set; nothing was left.
      * @throws when a party-wide row exists and this machine cannot sign its removal (not an
      *   enrolled owner) — {@link stopStrand} stops the strand on this machine only — or when
      *   the party-wide table cannot be read.
      */
-    forgetJoinedStrand(strandId: string): Promise<void>;
+    forgetJoinedStrand(strandId: string, options?: StrandLeaveOptions): Promise<void>;
+    /**
+     * Before a leave changes anything: refuse while the strand's offline queue holds transactions,
+     * unless the app asked to discard them (docs/strands.md → "Leaving a strand with unsent
+     * transactions"). Transactions Optimystic will not withdraw stay in the journal, named in one
+     * warning, and the leave goes on: they may already be saved, and a cohort that never returns
+     * would otherwise block the leave forever.
+     *
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not set.
+     * @throws when a hibernating strand has to be woken to discard and the wake fails.
+     */
+    private settleQueueBeforeLeave;
+    /**
+     * Discard from the strand's live queue, waking a hibernating strand first (its queue is back
+     * once a build restores it from the journal), and return what was kept. `undefined` when the
+     * wake built no database (no seed peer has answered), so there was no queue to discard from.
+     */
+    private discardQueuedForLeave;
     /**
      * Record `row` as a join from another party when this party's control database names it
      * neither as its own strand nor as a party-wide join — the one case nothing else would

package/dist/cadre-node.js

@@ -9,6 +9,7 @@ import { controlClusterPolicy, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WIND
 import { generatePrivateKey } from '@optimystic/quereus-plugin-crypto';
 import { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { strandTransportKey } from './strand-transport-key.js';
+import { isSendingStatus, StrandOfflineUnavailableError, StrandQueueNotEmptyError } from './strand-offline.js';
 import { assertScopeKeyCharset, assertStrandScopeKey, controlStorageScope, InvalidStrandIdError, isValidStrandScopeKey } from './storage-scope.js';
 import { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
 import { assertNotPreSplitStrand, issueInvite, PreSplitStrandIdentityError, readStrandHeaderSAppId } from './strand-membership-writer.js';
@@ -58,6 +59,7 @@ import { StrandWakeService, dialWake } from './strand-wake-protocol.js';
 import { StrandAddrService, collectStrandAddrs } from './strand-addr-protocol.js';
 import { DelegateAdmissionStore, extractCircuitRelayTargets, dueRelayAnnounces, prunePeerStrandKeys, peerStrandKey, recordRelayRefusals, relaysNotRefusing } from './delegate-admission.js';
 import { relayCircuitAddrs, resolveListenAddrs, resolveTransportOptions, RelayReservationFailedError } from './relay-addrs.js';
+import { selfAddressesChanged } from './self-address-update.js';
 import { nodeTransportsOption } from './node-transports.js';
 import { resolveRelayServer } from './relay-server.js';
 import { replacesAdvertisedAddrs, resolveAnnounceAddrs } from './announce-addrs.js';
@@ -3243,8 +3245,11 @@ export class CadreNode {
         }, { label: 'control-reconcile', backstopMs });
         // Address churn re-publishes the self record AND re-checks the control cohort:
         // a relay-reservation rotation / NAT change can drop a sibling connection, so
-        // the next pass should re-observe and re-dial it.
-        this.selfPeerUpdateHandler = () => {
+        // the next pass should re-observe and re-dial it. Only address churn: libp2p also
+        // fires this for a protocol handler registered or removed (see selfAddressesChanged).
+        this.selfPeerUpdateHandler = (event) => {
+            if (!selfAddressesChanged(event.detail))
+                return;
             republish('self:peer:update');
             this.controlReconcileRuns?.trigger(0);
         };
@@ -5238,6 +5243,23 @@ export class CadreNode {
         void this.recordReplicaSAppId(strandId);
         this.emit('strand:writable', { strandId });
     }
+    /**
+     * A status from a strand's offline queue (`StartStrandConfig.offline`). The queue sending counts
+     * as activity ({@link isSendingStatus}), so a check-in window that finds the cohort reachable stays
+     * up while the queue drains, and the idle timer does not cut a drain short. Recorded through the
+     * hibernation manager, not {@link recordStrandActivity}, whose push fan-out would wake other phones.
+     *
+     * Not on a strand being quiesced: activity there wakes it again once the quiesce ends, which would
+     * undo a `hibernateAll` made as the app went to the background. A send that quiesce cuts short was
+     * journaled before it went out, and the next build's restore re-sends it under the same action id.
+     */
+    handleOfflineStatus(event) {
+        const instance = this.strandManager.getInstance(event.strandId);
+        if (instance && isSendingStatus(event.status) && !this.strandManager.isQuiescing(event.strandId)) {
+            this.hibernationManager.recordActivity(instance);
+        }
+        this.emit('strand:offline-status', event);
+    }
     // Hibernation callbacks
     async handleStrandIdle(strandId) {
         const instance = this.strandManager.getInstance(strandId);
@@ -5640,6 +5662,31 @@ export class CadreNode {
             timeoutMs: options?.timeoutMs ?? this.config.strandFirstSync?.timeoutMs
         });
     }
+    /**
+     * Switch a strand between offline mode, where a commit resolves once the transaction is queued on
+     * this machine, and online mode (docs/strands.md → "Offline mode"). Affects transactions begun from
+     * now on; one already open keeps the acknowledgement it began with. The mode belongs to the strand:
+     * a hibernating strand takes it at its next build, and it lasts across hibernation and every
+     * rebuild until the process exits, after which the strand starts in `strandOffline.initialMode`.
+     *
+     * @throws StrandOfflineUnavailableError when `CadreNodeConfig.strandOffline` is not configured.
+     * @throws when this node does not run the strand.
+     */
+    setStrandOfflineMode(strandId, mode) {
+        if (!this.config.strandOffline) {
+            throw new StrandOfflineUnavailableError(strandId);
+        }
+        this.strandManager.setOfflineMode(strandId, mode);
+    }
+    /**
+     * A strand's offline mode ({@link setStrandOfflineMode}); `'online'` on a node without
+     * `strandOffline`. The queue's own view, with what it holds, is `strand.database.offline.queueState()`.
+     *
+     * @throws when this node does not run the strand.
+     */
+    getStrandOfflineMode(strandId) {
+        return this.strandManager.offlineMode(strandId);
+    }
     /**
      * 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
@@ -6008,16 +6055,25 @@ export class CadreNode {
      * caller ever needs removal to mean "and erase the local copy", that is a separate purge
      * step, not a widening of this method.
      *
+     * Refuses while the strand's offline queue on this machine holds transactions, unless
+     * `options.discardQueued` (docs/strands.md → "Leaving a strand with unsent transactions"). The
+     * check and the discard run before the control-plane delete, so a delete refused afterwards
+     * leaves the discarded transactions discarded.
+     *
      * @param strandId - The `Strand` row id to remove (as passed to {@link publishStrand}).
+     * @param options - `discardQueued`: withdraw the queued transactions that were never sent, and remove.
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not
+     *   set; nothing was removed.
      * @throws if the node is not started, has no owner signer wired, the id is blank, or
      *   the signer is not an enrolled owner (the schema's `Strand.AuthorizedDelete` rejects
      *   the write and the row survives). A rejection does NOT imply the row survived: the
      *   local stop runs after the control-plane delete has already committed, so a failure
      *   there throws over a completed removal.
      */
-    async unpublishStrand(strandId) {
+    async unpublishStrand(strandId, options) {
         const signer = this.requireOwnerSigner(`unpublish strand ${strandId}`);
         const trimmed = requireNonBlank(strandId, 'strand id');
+        await this.settleQueueBeforeLeave(trimmed, options);
         // One approval: the strand delete and its party key's, each with its tombstone.
         const removed = await signer.approve({ partyId: this.partyId, action: `Remove the strand ${trimmed} from the cadre` }, (sign) => this.controlDatabase.deleteStrand(trimmed, signer.publicKey, sign));
         // Gate on `removed`: the absent-row no-op wrote nothing, so warning about an
@@ -6454,6 +6510,14 @@ export class CadreNode {
             onWritable: (writableStrandId) => this.handleStrandWritable(writableStrandId),
             onCommitDurability: (commit) => this.emit('strand:commit-durability', commit),
             onCommitHeld: (held) => this.emit('strand:commit-held', held),
+            offline: this.config.strandOffline && {
+                ...this.config.strandOffline,
+                onOfflineStatus: (event) => this.handleOfflineStatus(event),
+                onQueueState: (event) => this.emit('strand:queue-state', event),
+                onAppSchemaDeferred: (event) => this.emit('strand:app-schema-deferred', event),
+                onAppSchemaApplied: (event) => this.emit('strand:app-schema-applied', event),
+                onAppSchemaFailed: (event) => this.emit('strand:error', event)
+            },
             // Re-announce the delegate to ONE relay before the strand node's reservation
             // supervisor re-drives it (see announceDelegateToRelay). Retained with the
             // launch config, so a hibernation wake's rebuilt supervisors get it too.
@@ -7128,18 +7192,70 @@ export class CadreNode {
      * The other members of the strand are not told, and this party's membership row in the
      * strand stays, so a later re-formation reuses the same identity.
      *
+     * Refuses while the strand's offline queue on this machine holds transactions, unless
+     * `options.discardQueued` (docs/strands.md → "Leaving a strand with unsent transactions"). The
+     * check and the discard run before the party-wide row is removed, so a removal refused
+     * afterwards leaves the discarded transactions discarded.
+     *
+     * @param options - `discardQueued`: withdraw the queued transactions that were never sent, and leave.
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not
+     *   set; nothing was left.
      * @throws when a party-wide row exists and this machine cannot sign its removal (not an
      *   enrolled owner) — {@link stopStrand} stops the strand on this machine only — or when
      *   the party-wide table cannot be read.
      */
-    async forgetJoinedStrand(strandId) {
+    async forgetJoinedStrand(strandId, options) {
         if (!this._running) {
             throw new Error('CadreNode not running');
         }
+        await this.settleQueueBeforeLeave(strandId, options);
         await this.joinedStrands.leave(strandId);
         this.forgetStrandPeers(strandId, 'forgetJoinedStrand');
         await this.stopStrand(strandId);
     }
+    /**
+     * Before a leave changes anything: refuse while the strand's offline queue holds transactions,
+     * unless the app asked to discard them (docs/strands.md → "Leaving a strand with unsent
+     * transactions"). Transactions Optimystic will not withdraw stay in the journal, named in one
+     * warning, and the leave goes on: they may already be saved, and a cohort that never returns
+     * would otherwise block the leave forever.
+     *
+     * @throws StrandQueueNotEmptyError when the queue holds transactions and `discardQueued` is not set.
+     * @throws when a hibernating strand has to be woken to discard and the wake fails.
+     */
+    async settleQueueBeforeLeave(strandId, options) {
+        const queued = this.strandManager.queuedTransactionIds(strandId);
+        if (queued.length === 0) {
+            return;
+        }
+        if (options?.discardQueued !== true) {
+            throw new StrandQueueNotEmptyError(strandId, queued);
+        }
+        const kept = await this.discardQueuedForLeave(strandId);
+        if (kept === undefined) {
+            console.warn(`[sereus] strand ${strandId}: leaving with ${queued.length} queued transaction(s) not discarded ` +
+                `(${queued.join(', ')}): the strand's database could not be built to reach its queue. They stay in ` +
+                'this machine\'s offline journal and come back if this machine attaches the strand again.');
+        }
+        else if (kept.length > 0) {
+            console.warn(`[sereus] strand ${strandId}: leaving with ${kept.length} queued transaction(s) that could not be ` +
+                `discarded (${kept.join(', ')}): each was sent, or is being sent, and the strand's members may already ` +
+                'hold it. They stay in this machine\'s offline journal and settle if this machine attaches the strand again.');
+        }
+    }
+    /**
+     * Discard from the strand's live queue, waking a hibernating strand first (its queue is back
+     * once a build restores it from the journal), and return what was kept. `undefined` when the
+     * wake built no database (no seed peer has answered), so there was no queue to discard from.
+     */
+    async discardQueuedForLeave(strandId) {
+        const kept = this.strandManager.discardQueuedTransactions(strandId);
+        if (kept !== undefined) {
+            return kept;
+        }
+        await this.wakeStrand(strandId);
+        return this.strandManager.discardQueuedTransactions(strandId);
+    }
     /**
      * Record `row` as a join from another party when this party's control database names it
      * neither as its own strand nor as a party-wide join — the one case nothing else would