@serfab/cadre-core 1.7.0 → 1.8.0

package/dist/strand-instance-manager.d.ts

@@ -34,8 +34,15 @@ export declare function liveStrandStatus(instance: StrandInstance): 'active' | '
  */
 export interface StartStrandConfig {
     strandRow: StrandRow;
-    /** sApp configuration provided by the hosting application */
-    sAppConfig: SAppConfig;
+    /**
+     * sApp configuration provided by the hosting application. Absent for a **storage
+     * replica** — a strand this node stores and serves without the app installed
+     * (`CadreNodeConfig.hostUnclaimedStrands`): no schema signature check, no `App`
+     * schema, no `sAppInfo` on the instance, and the default latency hint. A replica is
+     * always a joiner; `StrandDatabase` refuses to found one. An app that later claims the
+     * strand upgrades the running replica in place ({@link StrandInstanceManager.attachSApp}).
+     */
+    sAppConfig?: SAppConfig;
     storage?: StorageConfig;
     network?: NetworkConfig;
     profile: NodeProfile;
@@ -364,6 +371,23 @@ export declare class StrandInstanceManager {
      * wake becomes the better trade.
      */
     private strandStorages;
+    /**
+     * 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.
+     */
+    private runtimeBuilds;
+    /**
+     * 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.
+     */
+    private transitions;
     private stopping;
     constructor();
     /**
@@ -395,6 +419,18 @@ export declare class StrandInstanceManager {
      * hibernation wake never re-enters the embedder's provider.
      */
     startStrand(config: StartStrandConfig): Promise<StrandInstance>;
+    /** Hold `build` in {@link runtimeBuilds} until it settles, and settle as it does. */
+    private trackRuntimeBuild;
+    /**
+     * 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.
+     */
+    private settleRuntimeBuilds;
     /**
      * Build (or rebuild) the libp2p node + StrandDatabase for an instance and
      * attach them, transitioning it to `active`. Shared by `startStrand` (fresh
@@ -509,11 +545,26 @@ export declare 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.
      */
     quiesceStrand(strandId: string): Promise<void>;
+    /** Body of {@link quiesceStrand}. */
+    private runQuiesce;
+    /**
+     * 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: string): boolean;
     /**
      * Resume a previously-quiesced strand: rebuild its libp2p node + StrandDatabase
      * from the retained launch config and re-attach them, transitioning it back to
@@ -521,8 +572,22 @@ export declare 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.
      */
     resumeStrand(strandId: string, overrides?: ResumeStrandOverrides): Promise<StrandInstance>;
+    /** Record `transition` as the latest for `strandId` until it settles. */
+    private holdTransition;
+    /** Wait for the transition requested before this one. Never rejects: its failure belongs to its caller. */
+    private settleTransition;
+    /** Body of {@link resumeStrand}; at most one runs per strand at a time. */
+    private runResume;
     /**
      * Honor a founder request against an ALREADY-TRACKED strand — the seam that
      * closes the "whoever launches first decides whether the bootstrap runs" gap:
@@ -539,7 +604,8 @@ export declare 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
@@ -555,6 +621,39 @@ export declare class StrandInstanceManager {
      *   whose `'needs-resume'` wake fails owes the same withdrawal.
      */
     foundExistingStrand(strandId: string, resolvePartyKey?: () => Promise<string | undefined>): Promise<'already-founder' | 'bootstrapped' | 'needs-resume'>;
+    /**
+     * 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.
+     */
+    attachSApp(strandId: string, sAppConfig: SAppConfig, options?: {
+        requireSignedSchemas?: boolean;
+    }): Promise<'attached' | 'already-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
@@ -575,6 +674,14 @@ export declare class StrandInstanceManager {
     whenWritable(strandId: string, options?: {
         timeoutMs?: number;
     }): Promise<StrandInstance>;
+    /**
+     * 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.
+     */
+    whenRuntimeBuilt(strandId: string): Promise<StrandInstance | undefined>;
     /**
      * 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

package/dist/strand-instance-manager.js

@@ -14,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');
 /**
@@ -99,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.
@@ -204,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');
     }
@@ -259,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,
@@ -269,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
@@ -289,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',
@@ -305,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) {
@@ -326,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
@@ -353,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
@@ -423,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.
@@ -435,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'
@@ -452,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
@@ -663,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
@@ -671,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);
@@ -934,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
@@ -959,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`);
@@ -997,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;
@@ -1025,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
@@ -1054,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 {
@@ -1066,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
@@ -1117,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
@@ -1146,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);
         }