@serfab/cadre-core 1.6.0 → 1.8.0

package/dist/strand-instance-manager.js

@@ -3,6 +3,8 @@ import { createLibp2pNode } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
 import { PeerJoinBackfill } from './peer-join-backfill.js';
+import { StrandPeerObserver } from './strand-peer-observer.js';
+import { StrandPeerBookSwap } from './strand-peer-book-swap.js';
 import { StrandRevocationEnforcer, createRevocationConnectionGater, readStrandRevocationRows } from './strand-revocation-enforcer.js';
 import { StrandMembershipReconciler } from './strand-membership-reconciler.js';
 import { removeMemberPeer } from './strand-membership-writer.js';
@@ -12,8 +14,9 @@ import { assertStrandScopeKey } from './storage-scope.js';
 import { StrandFirstSyncGate, StrandAwaitingFirstSyncError, strandFirstSyncComplete, DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS } from './strand-first-sync-gate.js';
 import { DEFAULT_CONNECTION_MONITOR, resolveStrandClusterSize, strandClusterPolicy } from './types.js';
 import { strandNodeAddrs } from './strand-network-config.js';
+import { resolveRelayServer } from './relay-server.js';
 import { superviseRelayReservation } from './relay-reservation.js';
-import { connectionManagerTimeouts, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { declaredCohortReadDeadlineMs, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
 /**
@@ -97,6 +100,24 @@ function resolveStrandStorage(provider, strandId) {
     // lifetime — so the wrap survives every runtime rebuild the instance goes through.
     return wrapStorageWithCache(storage, strandId);
 }
+/**
+ * Verify an sApp's schema signature (fail-closed unless `requireSignedSchemas` is
+ * false) and project the config onto the instance's `sAppInfo`.
+ */
+function verifiedSAppInfo(strandId, sAppConfig, requireSignedSchemas) {
+    assertSchemaSignature(sAppConfig, { requireSignature: requireSignedSchemas ?? true });
+    log('Strand %s sApp schema signature verified (author: %s)', strandId, sAppConfig.id);
+    return {
+        id: sAppConfig.id,
+        version: sAppConfig.version,
+        schema: sAppConfig.schema,
+        signature: sAppConfig.signature
+    };
+}
+/** Log wording for what a launch runs: the sApp and its version, or a storage replica. */
+function describeSApp(sAppConfig) {
+    return sAppConfig ? `sApp: ${sAppConfig.id} v${sAppConfig.version}` : 'storage replica';
+}
 /**
  * Manages individual strand instances - creates and destroys isolated libp2p nodes
  * for each strand the cadre participates in.
@@ -119,6 +140,23 @@ export class StrandInstanceManager {
          * missed writes).
          */
         this.backfills = new Map();
+        /**
+         * The per-strand peer-book observation writer (`strand-peer-observer.ts`), keyed
+         * by strand id. Same lifecycle rationale as {@link backfills}: started in
+         * `buildStrandRuntime` right after the libp2p node exists, stopped and dropped in
+         * `releaseRuntime`, so quiesce → resume re-arms it on the rebuilt node. Only
+         * present when the launch config supplied `onStrandPeerIdentified`.
+         */
+        this.peerObservers = new Map();
+        /**
+         * Per-strand strand peer book SWAP driver ({@link StrandPeerBookSwap}) — the signed
+         * exchange of book entries between strand peers. Same lifetime as the peer-book
+         * observer above: armed in `buildStrandRuntime` right after the libp2p node exists
+         * (its protocol handler must be registered before an early peer dials it), stopped
+         * and dropped in `releaseRuntime`. Only present when the launch config supplied
+         * `strandPeerBook`.
+         */
+        this.peerBookSwaps = new Map();
         /**
          * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
          * id. Same lifecycle rationale as {@link backfills}: created in
@@ -185,6 +223,23 @@ export class StrandInstanceManager {
          * wake becomes the better trade.
          */
         this.strandStorages = new Map();
+        /**
+         * The runtime build in flight per strand id (`buildStrandRuntime`, from `startStrand` or
+         * `resumeStrand`), present until it settles. The instance is tracked for the whole build,
+         * with its database not yet constructed or not yet initialized, so a caller that must act
+         * on the FINISHED runtime ({@link attachSApp}, {@link whenRuntimeBuilt}) waits on this instead. A failed build's
+         * rejection belongs to the call that started it.
+         */
+        this.runtimeBuilds = new Map();
+        /**
+         * The latest resume or quiesce requested per strand id, present until it settles. Each one
+         * starts only once the one requested before it has settled, so a wake that lands during a
+         * quiesce rebuilds after it, and a quiesce requested during a rebuild releases what that
+         * rebuild finished. The WHOLE operation, not its entry in {@link runtimeBuilds}: that settles
+         * before a resume's own catch records `'error'`, so a joiner awaiting it could read a stale
+         * status.
+         */
+        this.transitions = new Map();
         this.stopping = false;
         log('StrandInstanceManager created');
     }
@@ -240,7 +295,7 @@ export class StrandInstanceManager {
             log('Strand %s already running', strandId);
             return this.instances.get(strandId);
         }
-        log('Starting strand instance: %s (sApp: %s v%s)', strandId, sAppConfig.id, sAppConfig.version);
+        log('Starting strand instance: %s (%s)', strandId, describeSApp(sAppConfig));
         const tTotal = performance.now();
         // The id becomes two names below: the storage scope key the embedder's provider
         // turns into a directory or database name, and `networkName` in buildStrandRuntime,
@@ -250,17 +305,7 @@ export class StrandInstanceManager {
         // function returns early when no provider is configured — a node with no storage
         // still reaches buildStrandRuntime and still mints the protocol prefix.
         assertStrandScopeKey(strandId);
-        // Verify schema signature before proceeding (fail-closed by default)
-        const requireSignature = config.requireSignedSchemas ?? true;
-        assertSchemaSignature(sAppConfig, { requireSignature });
-        log('Strand %s sApp schema signature verified (author: %s)', strandId, sAppConfig.id);
-        // Convert SAppConfig to SAppInfo for the instance
-        const sAppInfo = {
-            id: sAppConfig.id,
-            version: sAppConfig.version,
-            schema: sAppConfig.schema,
-            signature: sAppConfig.signature
-        };
+        const sAppInfo = sAppConfig ? verifiedSAppInfo(strandId, sAppConfig, config.requireSignedSchemas) : undefined;
         // Resolve this strand's storage ONCE, before anything is recorded. If a factory
         // function is provided, it is called with the strandId to create strand-specific
         // storage (e.g. strand-isolated directories). A provider that throws therefore
@@ -270,7 +315,7 @@ export class StrandInstanceManager {
             log('Strand %s using provided storage provider', strandId);
         }
         // Determine latency hint: sApp config > default
-        const latencyHint = sAppConfig.latencyHint ?? config.defaultLatencyHint;
+        const latencyHint = sAppConfig?.latencyHint ?? config.defaultLatencyHint;
         const instance = {
             strandId,
             status: 'starting',
@@ -286,9 +331,9 @@ export class StrandInstanceManager {
             this.strandStorages.set(strandId, strandStorage);
         }
         try {
-            await this.buildStrandRuntime(instance, config);
+            await this.trackRuntimeBuild(strandId, this.buildStrandRuntime(instance, config));
             timing('[startStrand:%s] total: %dms', strandId, Math.round(performance.now() - tTotal));
-            log('Strand %s started successfully with sApp %s', strandId, sAppConfig.id);
+            log('Strand %s started successfully (%s)', strandId, describeSApp(sAppConfig));
             return instance;
         }
         catch (error) {
@@ -307,6 +352,34 @@ export class StrandInstanceManager {
             throw error;
         }
     }
+    /** Hold `build` in {@link runtimeBuilds} until it settles, and settle as it does. */
+    async trackRuntimeBuild(strandId, build) {
+        this.runtimeBuilds.set(strandId, build);
+        try {
+            await build;
+        }
+        finally {
+            if (this.runtimeBuilds.get(strandId) === build) {
+                this.runtimeBuilds.delete(strandId);
+            }
+        }
+    }
+    /**
+     * Wait until no runtime build of `strandId` is in flight. Never rejects: a failed build
+     * is reported by the call that started it, and the caller re-reads the instance after.
+     *
+     * NOTE: after a failed launch the re-read sees the instance gone only because
+     * `startStrand`'s catch deletes it synchronously, and its continuation is queued before
+     * this waiter's. If that cleanup ever awaits before `instances.delete`, a waiter can act
+     * on the dying record; move the cleanup inside the tracked promise then.
+     */
+    async settleRuntimeBuilds(strandId) {
+        for (let build = this.runtimeBuilds.get(strandId); build; build = this.runtimeBuilds.get(strandId)) {
+            await build.catch((error) => {
+                log('Strand %s: the runtime build waited on failed (reported by its launcher): %o', strandId, error);
+            });
+        }
+    }
     /**
      * Build (or rebuild) the libp2p node + StrandDatabase for an instance and
      * attach them, transitioning it to `active`. Shared by `startStrand` (fresh
@@ -334,9 +407,9 @@ export class StrandInstanceManager {
         // with — hence one binding for both, not two literals that can drift.
         const networkName = `strand-${strandId}`;
         const protocolPrefix = `/optimystic/${networkName}`;
-        // Determine relay mode: if explicitly set in config, use that;
-        // otherwise default to true for storage profile nodes.
-        const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
+        // Whether this node runs the circuit-relay server, and its init — the same
+        // resolution the control node takes from the same config (`relay-server.ts`).
+        const relayServer = resolveRelayServer(config.network, config.profile);
         // The strand-node VIEW of the machine's one `NetworkConfig`, not the control
         // node's resolution: fixed direct listen ports become ephemeral (two nodes cannot
         // bind one port), the announce config is dropped (it names the control node's
@@ -404,7 +477,12 @@ export class StrandInstanceManager {
                 networkName,
                 storage: strandStorage,
                 fretProfile: config.profile === 'storage' ? 'core' : 'edge',
-                relay: enableRelay,
+                relay: relayServer.enabled,
+                // NOTE: unlike the control node, a strand node has no unauthorized-reservation budget,
+                // so with the per-connection cap off any peer that reaches this node can hold one of
+                // `maxReservations` slots and forward uncapped through it. If strand relays are ever
+                // abused for bandwidth, give strand nodes a budget or a capped init of their own.
+                ...(relayServer.enabled && { relayServerInit: relayServer.init }),
                 clusterSize: strandClusterSize,
                 // Deliberately NOT CONTROL_CLUSTER_POLICY: a strand is application data with its own
                 // breadth reasoning, and the shape match with the control policy is a coincidence.
@@ -416,11 +494,12 @@ export class StrandInstanceManager {
                 // returns the frozen STRAND_CLUSTER_POLICY itself, declaring nothing. Resolved
                 // HERE rather than at `startStrand`, so a wake from hibernation would pick up a
                 // serving set that changed while the strand slept.
-                // The read deadline is the same field the control node reads, because the two
-                // networks ride one link; absent, the base policy's COHORT_READ_DEADLINE_MS stands.
+                // The read deadline is settled by the same helper the control node uses, because the
+                // two networks ride one link: the host's own, else derived from its declared
+                // `linkRoundTripMs`, else nothing, and the base policy's COHORT_READ_DEADLINE_MS stands.
                 clusterPolicy: strandClusterPolicy(strandClusterSize, {
                     servingMachines: config.servingMachines,
-                    cohortQueryTimeoutMs: config.network?.cohortQueryTimeoutMs
+                    cohortQueryTimeoutMs: declaredCohortReadDeadlineMs(config.network)
                 }),
                 arachnode: {
                     enableRingZulu: config.profile === 'storage'
@@ -433,10 +512,10 @@ export class StrandInstanceManager {
                 // widened ping deadline has to reach the strand nodes too (see
                 // DEFAULT_CONNECTION_MONITOR).
                 connectionMonitor: config.network?.connectionMonitor ?? DEFAULT_CONNECTION_MONITOR,
-                // The same declared-link limits the control node takes, and for the same reason: a
-                // strand node is the listener for every other member's strand node (`link-budget.ts`,
-                // `connectionManagerTimeouts`).
-                connectionManager: connectionManagerTimeouts(config.network?.linkRoundTripMs),
+                // The same declared link the control node states, and for the same reason: a strand
+                // node is also the listener for every other member's strand node, and Optimystic
+                // derives that listener's limit from this (`link-budget.ts`).
+                linkRoundTripMs: resolveLinkRoundTripMs(config.network?.linkRoundTripMs),
                 // Listen entries plus the WebSocket transport switch they imply — a strand node
                 // announces nothing the operator configured (`strand-network-config.ts`), and
                 // spreads AFTER `transports` above because the switch is a no-op whenever the
@@ -454,6 +533,46 @@ export class StrandInstanceManager {
             });
             timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
             instance.libp2pNode = node;
+            // The peer-book observation writer, armed BEFORE the database bring-up below
+            // (unlike the backfill) because the bootstrap dials that follow `libp2p.start()`
+            // land during that bring-up, and they are exactly the peers worth remembering:
+            // identify for an early peer may already have fired by the time anything after
+            // the database initializes runs. Registered in the map immediately so the
+            // failure rollback (releaseRuntime) stops it like every other runtime component.
+            const onStrandPeerIdentified = config.onStrandPeerIdentified;
+            if (onStrandPeerIdentified) {
+                const observer = new StrandPeerObserver({
+                    label: strandId,
+                    libp2p: node,
+                    protocolPrefix,
+                    onObserved: (observation) => onStrandPeerIdentified(strandId, observation)
+                });
+                this.peerObservers.set(strandId, observer);
+                observer.start();
+            }
+            // The strand peer book SWAP, armed at the same moment and for the same reason as
+            // the observer: a peer that dials this node's swap handler before it is registered
+            // fails its exchange and sits out a ten-minute throttle. The own entry is signed
+            // now and re-signed on every address change, which covers the relay reservation
+            // landing below (`self:peer:update` fires when the circuit addr is added), so no
+            // separate post-relay step is needed. Registered in the map immediately so the
+            // failure rollback (releaseRuntime) stops it like every other runtime component.
+            //
+            // NOTE: this is a third `peer:identify` listener per running strand, beside the
+            // observer's and the backfill's — see the backfill's NOTE below for when to fold
+            // them into one dispatcher.
+            if (config.strandPeerBook) {
+                const swap = new StrandPeerBookSwap({
+                    strandId,
+                    libp2p: node,
+                    protocolPrefix,
+                    store: config.strandPeerBook,
+                    privateKey: config.privateKey,
+                    linkRoundTripMs: config.network?.linkRoundTripMs
+                });
+                this.peerBookSwaps.set(strandId, swap);
+                swap.start();
+            }
             // One reservation supervisor PER RELAY, started now so the first attempts
             // overlap the database bring-up below (the relay is never in a strand's
             // Optimystic cohort — its protocol ids are namespaced `/optimystic/strand-<id>/…`
@@ -566,7 +685,7 @@ export class StrandInstanceManager {
             // peer-join-backfill.ts for the strand-side argument (and why the control
             // network, which DOES gate, is different).
             //
-            // NOTE: cost is one PeerJoinBackfill object + one `connection:open` listener
+            // NOTE: cost is one PeerJoinBackfill object + one `peer:identify` listener
             // per running strand — linear in strand count, negligible at the handful a
             // device or host runs today. If a node ever hosts strands by the hundred,
             // move to one shared listener that dispatches by strand id.
@@ -604,7 +723,7 @@ export class StrandInstanceManager {
             // failing here would only trade that for `StrandWatcher`'s full-rebuild retry.
             //
             // NOTE: a relay that is down costs this launch one full drive — the reservation budget
-            // counted from the declared link round trip, 14 s at its default (`link-budget.ts`) — and
+            // counted from the declared link round trip, 18 s at its default (`link-budget.ts`) — and
             // `StrandWatcher` launches strands one at a time, so N strands cost N of those in
             // bring-up during a relay outage, and MORE on a host that declared a slower link. If that
             // ever matters, stop awaiting here (the circuit addr then lands after `active`) rather
@@ -612,8 +731,9 @@ export class StrandInstanceManager {
             t0 = performance.now();
             await this.awaitFirstRelayAttempts(strandId);
             timing('[buildStrandRuntime:%s] relay first attempts: %dms', strandId, Math.round(performance.now() - t0));
+            // No `lastActivity` stamp: bringing a runtime up is not activity. A check-in marks
+            // activity before its resume and must see only what landed while the strand was up.
             instance.status = liveStrandStatus(instance);
-            instance.lastActivity = new Date();
             if (instance.status === 'syncing') {
                 log('Strand %s launched as a joiner with no Strand.Header held yet — writes are withheld until ' +
                     'a member of the strand is reached', strandId);
@@ -661,6 +781,20 @@ export class StrandInstanceManager {
             backfill.stop();
             this.backfills.delete(instance.strandId);
         }
+        // The peer-book observer goes with the node it listened on; a resume re-arms
+        // one on the rebuilt node.
+        const peerObserver = this.peerObservers.get(instance.strandId);
+        if (peerObserver) {
+            peerObserver.stop();
+            this.peerObservers.delete(instance.strandId);
+        }
+        // The book swap likewise: unsubscribed and its handler unregistered while the node is
+        // still up; a resume re-arms one, which re-signs the own entry over the new addresses.
+        const peerBookSwap = this.peerBookSwaps.get(instance.strandId);
+        if (peerBookSwap) {
+            this.peerBookSwaps.delete(instance.strandId);
+            await peerBookSwap.stop();
+        }
         // The revoked-peer enforcer goes with the runtime it gated: a resume
         // rebuilds it with a fresh (initially empty, fail-open) snapshot.
         const revocationEnforcer = this.revocationEnforcers.get(instance.strandId);
@@ -861,23 +995,53 @@ export class StrandInstanceManager {
      * Quiesce a strand: release its strand-network resources (stop the libp2p node,
      * close the StrandDatabase) while RETAINING the instance record — identity,
      * sAppInfo, keys, latency hint, metadata — and its launch config so it can be
-     * resumed later. Mechanically this is `stopStrand` minus the instance/config
-     * deletion. The caller sets the post-quiesce status (e.g. `hibernating`).
-     * No-ops when the strand is missing or already quiesced.
+     * resumed later, then mark it `hibernating`. Mechanically this is `stopStrand` minus
+     * the instance/config deletion. A tracked strand with no runtime left (a failed
+     * rebuild already released it) is only marked; an untracked one is left alone.
+     *
+     * Ordered with {@link resumeStrand} (see {@link transitions}): it starts once the resume
+     * or launch build before it has settled, so it releases a finished runtime, and the
+     * status write is its last step, so a resume requested meanwhile writes after it. A call
+     * made while another quiesce is the latest request joins it. A failed release leaves the
+     * status as it was and rejects.
      */
     async quiesceStrand(strandId) {
+        const previous = this.transitions.get(strandId);
+        if (previous?.kind === 'quiesce') {
+            log('quiesceStrand: strand %s — joining the quiesce already requested', strandId);
+            return previous.operation;
+        }
+        const operation = this.runQuiesce(strandId, previous);
+        this.holdTransition(strandId, { kind: 'quiesce', operation });
+        return operation;
+    }
+    /** Body of {@link quiesceStrand}. */
+    async runQuiesce(strandId, previous) {
+        await this.settleTransition(strandId, previous);
+        await this.settleRuntimeBuilds(strandId);
         const instance = this.instances.get(strandId);
         if (!instance) {
             log('quiesceStrand: strand %s not found', strandId);
             return;
         }
-        if (!instance.libp2pNode && !instance.database) {
+        if (instance.libp2pNode || instance.database) {
+            log('Quiescing strand instance: %s', strandId);
+            await this.releaseRuntime(instance);
+            log('Strand %s quiesced (resources released, instance retained)', strandId);
+        }
+        else {
             log('quiesceStrand: strand %s already quiesced', strandId);
-            return;
         }
-        log('Quiescing strand instance: %s', strandId);
-        await this.releaseRuntime(instance);
-        log('Strand %s quiesced (resources released, instance retained)', strandId);
+        instance.status = 'hibernating';
+    }
+    /**
+     * Whether the latest runtime transition requested for `strandId` is a quiesce that has
+     * not finished. Its handles may still be attached and its status still live, but it is on
+     * its way to `hibernating`, so a caller that needs it up must {@link resumeStrand} it — the
+     * resume runs after the quiesce — rather than treat it as live.
+     */
+    isQuiescing(strandId) {
+        return this.transitions.get(strandId)?.kind === 'quiesce';
     }
     /**
      * Resume a previously-quiesced strand: rebuild its libp2p node + StrandDatabase
@@ -886,11 +1050,58 @@ export class StrandInstanceManager {
      * launch (the cohort `bootstrapNodes` seed and the strand's `servingMachines`
      * count) and updates the retained config so a later resume reuses the latest
      * values. Returns the live instance unchanged if it is already running.
+     *
+     * Overlapping calls share one rebuild: a call made while a resume is the latest request
+     * for the strand — a wake landing during a check-in — joins it and settles exactly as it
+     * does, `'error'` status included. The joiner's own `overrides` are ignored; the first
+     * resume's seed wins, and both callers resolved the cohort seed moments apart. A call made
+     * while a quiesce is the latest request runs after that quiesce and rebuilds (see
+     * {@link transitions}), and one made while `startStrand` is still building waits for that
+     * build rather than starting a second.
      */
     async resumeStrand(strandId, overrides) {
         if (this.stopping) {
             throw new Error('StrandInstanceManager is stopping');
         }
+        // No `await` between this read and `holdTransition`, or a second caller slips through
+        // and builds.
+        const previous = this.transitions.get(strandId);
+        if (previous?.kind === 'resume') {
+            log('resumeStrand: strand %s — joining the resume already in flight', strandId);
+            return previous.operation;
+        }
+        const operation = this.runResume(strandId, previous, overrides);
+        this.holdTransition(strandId, { kind: 'resume', operation });
+        return operation;
+    }
+    /** Record `transition` as the latest for `strandId` until it settles. */
+    holdTransition(strandId, transition) {
+        this.transitions.set(strandId, transition);
+        const release = () => {
+            if (this.transitions.get(strandId) === transition) {
+                this.transitions.delete(strandId);
+            }
+        };
+        // The rejection itself reaches the caller through the operation returned to it.
+        void transition.operation.then(release, release);
+    }
+    /** Wait for the transition requested before this one. Never rejects: its failure belongs to its caller. */
+    async settleTransition(strandId, previous) {
+        if (!previous) {
+            return;
+        }
+        await previous.operation.catch((error) => {
+            log('Strand %s: the %s queued ahead failed (reported by its caller): %o', strandId, previous.kind, error);
+        });
+    }
+    /** Body of {@link resumeStrand}; at most one runs per strand at a time. */
+    async runResume(strandId, previous, overrides) {
+        // Before any "already live" test: a quiesce ahead still has the handles attached, and
+        // mid-build (a launch still building) the libp2p node is attached while the database is
+        // not. A failed launch has already dropped the instance, and the check below reports it
+        // untracked.
+        await this.settleTransition(strandId, previous);
+        await this.settleRuntimeBuilds(strandId);
         const instance = this.instances.get(strandId);
         if (!instance) {
             throw new Error(`Cannot resume strand ${strandId}: not tracked`);
@@ -924,7 +1135,7 @@ export class StrandInstanceManager {
         this.launchConfigs.set(strandId, resumeConfig);
         instance.status = 'starting';
         try {
-            await this.buildStrandRuntime(instance, resumeConfig);
+            await this.trackRuntimeBuild(strandId, this.buildStrandRuntime(instance, resumeConfig));
             timing('[resumeStrand:%s] total: %dms', strandId, Math.round(performance.now() - tTotal));
             log('Strand %s resumed successfully', strandId);
             return instance;
@@ -952,7 +1163,8 @@ export class StrandInstanceManager {
      * - `'already-founder'` — the retained config already founds; nothing to do.
      * - `'bootstrapped'` — config flipped and the live database ran the bootstrap.
      * - `'needs-resume'` — config flipped, but the instance is quiesced (no live
-     *   database), so the bootstrap could not run here: the CALLER must wake the
+     *   database) or being quiesced (its database is closing), so the bootstrap could
+     *   not run here: the CALLER must wake the
      *   strand (`CadreNode.wakeStrand`, which owns the hibernation bookkeeping this
      *   manager does not) so the rebuild — which now founds — runs it.
      * @param resolvePartyKey - Asked for the party's own membership key when (and only
@@ -981,7 +1193,7 @@ export class StrandInstanceManager {
         // A fresh object rather than mutating in place: startStrand retains the CALLER'S
         // config object, which is not ours to rewrite.
         this.launchConfigs.set(strandId, { ...config, founder: true, partyMemberPrivateKey });
-        if (!instance.database && !this.firstSyncGates.has(strandId)) {
+        if (this.isQuiescing(strandId) || (!instance.database && !this.firstSyncGates.has(strandId))) {
             return 'needs-resume';
         }
         try {
@@ -993,6 +1205,70 @@ export class StrandInstanceManager {
         }
         return 'bootstrapped';
     }
+    /**
+     * Give a tracked storage replica ({@link StartStrandConfig.sAppConfig} absent) the app's
+     * schema in place — the seam for an app on this machine claiming a strand this node was
+     * already hosting. No runtime rebuild: the libp2p node, its peer id and connections, the
+     * store and its warm cache all stay, and the new `App` tables read the blocks the replica
+     * already holds. Callers attach BEFORE {@link foundExistingStrand}: the founder bootstrap
+     * writes the sApp into `Strand.Header` and refuses a database that has none.
+     *
+     * A runtime build in flight (the replica's launch, or a hibernation wake) is waited out
+     * first, so the attach acts on the database that build produced. Then, in order: the
+     * schema signature is checked before anything changes; the retained launch config takes
+     * the sApp, so every later rebuild applies it through `composeStrand`; the live database —
+     * published, or still held by the first-sync gate — gets the schema; and only then does
+     * the instance record `sAppInfo` and the sApp's latency hint. A quiesced instance gets the
+     * config alone, and its next resume applies the schema.
+     *
+     * @returns `'already-attached'` when the instance already runs an sApp — a DIFFERENT one
+     *   is logged and left as it is, as a second claim of a claimed strand always has been —
+     *   else `'attached'`.
+     * @throws when the strand is not tracked (a caller bug, or a launch that failed while
+     *   this waited on it); when the schema signature is refused, having changed nothing; and
+     *   whatever the live apply throws (e.g. a quiesce closed the database mid-apply) — the
+     *   retained config then still carries the sApp and `sAppInfo` stays unset, so the next
+     *   claim retries the apply.
+     *
+     * NOTE: two claims of one replica racing each other both pass the `sAppInfo` check and
+     * apply concurrently; the loser of the declarative diff can reject, and its `addStrand`
+     * retry then resolves `'already-attached'`. Needs an app calling `addStrand` twice at once
+     * (or beside a watcher retry); if it is ever seen, chain attaches per strand id.
+     */
+    async attachSApp(strandId, sAppConfig, options = {}) {
+        await this.settleRuntimeBuilds(strandId);
+        const instance = this.instances.get(strandId);
+        const config = this.launchConfigs.get(strandId);
+        if (!instance || !config) {
+            throw new Error(`Cannot attach an sApp to strand ${strandId}: not tracked`);
+        }
+        if (instance.sAppInfo) {
+            if (instance.sAppInfo.id !== sAppConfig.id) {
+                log('attachSApp: strand %s already runs sApp %s — the claim for sApp %s is ignored', strandId, instance.sAppInfo.id, sAppConfig.id);
+            }
+            return 'already-attached';
+        }
+        const sAppInfo = verifiedSAppInfo(strandId, sAppConfig, options.requireSignedSchemas);
+        // A fresh object rather than mutating in place: startStrand retains the CALLER'S
+        // config object, which is not ours to rewrite.
+        this.launchConfigs.set(strandId, { ...config, sAppConfig });
+        const database = instance.database ?? this.firstSyncGates.get(strandId)?.database;
+        if (database) {
+            await database.attachAppSchema(sAppConfig);
+        }
+        else {
+            log('attachSApp: strand %s is quiesced — its next resume applies the sApp schema', strandId);
+        }
+        instance.sAppInfo = sAppInfo;
+        if (sAppConfig.latencyHint) {
+            // HibernationManager reads the hint whenever it arms a timer, so the app's hint governs
+            // from the next one: a timer already armed runs once at the old duration, and a replica
+            // launched under a realtime default was never tracked, so it stays up until relaunched.
+            instance.latencyHint = sAppConfig.latencyHint;
+        }
+        log('Strand %s upgraded from storage replica to %s', strandId, describeSApp(sAppConfig));
+        return 'attached';
+    }
     /**
      * Whether `strandId` is launched but still waiting for its first sync — a joiner whose
      * runtime is up while its database is withheld (status `'syncing'`, or `'idle'` after
@@ -1044,6 +1320,17 @@ export class StrandInstanceManager {
             waiters.add(waiter);
         });
     }
+    /**
+     * The tracked instance once no runtime build of it is in flight, or `undefined` when none
+     * is tracked by then — never launched, or the launch waited on failed and dropped its
+     * record. For a caller about to hand a tracked instance to an app: until its build settles
+     * the instance is `'starting'` with no database, and a failed launch leaves no instance.
+     * Never rejects; a failed build is reported by the call that started it.
+     */
+    async whenRuntimeBuilt(strandId) {
+        await this.settleRuntimeBuilds(strandId);
+        return this.instances.get(strandId);
+    }
     /**
      * Hand a launch's database to the app: set `instance.database`, retire the gate that
      * held it, release every {@link whenWritable} waiter, and — when the launch had already
@@ -1073,9 +1360,11 @@ export class StrandInstanceManager {
             this.firstSyncGates.delete(strandId);
         }
         instance.database = database;
-        instance.lastActivity = new Date();
         const wasGated = instance.status !== 'starting';
         if (wasGated) {
+            // A Header delivered by a peer is strand activity; a publish during bring-up is not
+            // (see the build's end in `buildStrandRuntime`).
+            instance.lastActivity = new Date();
             instance.status = 'active';
             log('Strand %s is now writable: Strand.Header held', strandId);
         }