@serfab/cadre-core 1.7.0 → 1.8.0

package/src/strand-instance-manager.ts

@@ -43,8 +43,9 @@ import type {
 } from './types.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, type RelayReservationSupervisor } 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');
@@ -89,8 +90,15 @@ export function liveStrandStatus(instance: StrandInstance): 'active' | 'syncing'
  */
 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;
@@ -311,6 +319,11 @@ export interface ResumeStrandOverrides {
   servingMachines?: number;
 }
 
+/** A {@link StrandInstanceManager.resumeStrand} or {@link StrandInstanceManager.quiesceStrand} of one strand. */
+type RuntimeTransition =
+  | { kind: 'resume'; operation: Promise<StrandInstance> }
+  | { kind: 'quiesce'; operation: Promise<void> };
+
 /**
  * Get the isolated storage path for a specific strand.
  *
@@ -374,6 +387,26 @@ function resolveStrandStorage(
   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: string, sAppConfig: SAppConfig, requireSignedSchemas: boolean | undefined): SAppInfo {
+  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: SAppConfig | undefined): string {
+  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.
@@ -479,6 +512,23 @@ export class StrandInstanceManager {
    * wake becomes the better trade.
    */
   private strandStorages: Map<string, IRawStorage> = 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.
+   */
+  private runtimeBuilds: Map<string, Promise<void>> = 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.
+   */
+  private transitions: Map<string, RuntimeTransition> = new Map();
   private stopping = false;
 
   constructor() {
@@ -543,7 +593,7 @@ export class StrandInstanceManager {
       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
@@ -555,18 +605,7 @@ export class StrandInstanceManager {
     // 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: 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
@@ -578,7 +617,7 @@ export class StrandInstanceManager {
     }
 
     // Determine latency hint: sApp config > default
-    const latencyHint = sAppConfig.latencyHint ?? config.defaultLatencyHint;
+    const latencyHint = sAppConfig?.latencyHint ?? config.defaultLatencyHint;
 
     const instance: StrandInstance = {
       strandId,
@@ -597,9 +636,9 @@ export class StrandInstanceManager {
     }
 
     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) {
       // Status/error first — the (now discarded) record is still what `log` reports on.
@@ -618,6 +657,35 @@ export class StrandInstanceManager {
     }
   }
 
+  /** Hold `build` in {@link runtimeBuilds} until it settles, and settle as it does. */
+  private async trackRuntimeBuild(strandId: string, build: Promise<void>): Promise<void> {
+    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.
+   */
+  private async settleRuntimeBuilds(strandId: string): Promise<void> {
+    for (let build = this.runtimeBuilds.get(strandId); build; build = this.runtimeBuilds.get(strandId)) {
+      await build.catch((error: unknown) => {
+        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
@@ -649,9 +717,9 @@ export class StrandInstanceManager {
     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
@@ -725,7 +793,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.
@@ -737,11 +810,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'
@@ -754,10 +828,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
@@ -973,7 +1047,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
@@ -982,8 +1056,9 @@ export class StrandInstanceManager {
       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);
@@ -1257,24 +1332,54 @@ 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: string): Promise<void> {
+    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}. */
+  private async runQuiesce(strandId: string, previous: RuntimeTransition | undefined): Promise<void> {
+    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;
     }
+    instance.status = 'hibernating';
+  }
 
-    log('Quiescing strand instance: %s', strandId);
-    await this.releaseRuntime(instance);
-    log('Strand %s quiesced (resources released, instance retained)', strandId);
+  /**
+   * 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 {
+    return this.transitions.get(strandId)?.kind === 'quiesce';
   }
 
   /**
@@ -1284,11 +1389,65 @@ 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: string, overrides?: ResumeStrandOverrides): Promise<StrandInstance> {
     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. */
+  private holdTransition(strandId: string, transition: RuntimeTransition): void {
+    this.transitions.set(strandId, transition);
+    const release = (): void => {
+      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. */
+  private async settleTransition(strandId: string, previous: RuntimeTransition | undefined): Promise<void> {
+    if (!previous) {
+      return;
+    }
+    await (previous.operation as Promise<unknown>).catch((error: unknown) => {
+      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. */
+  private async runResume(
+    strandId: string,
+    previous: RuntimeTransition | undefined,
+    overrides?: ResumeStrandOverrides
+  ): Promise<StrandInstance> {
+    // 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`);
@@ -1325,7 +1484,7 @@ export class StrandInstanceManager {
 
     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;
@@ -1353,7 +1512,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
@@ -1386,7 +1546,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 {
@@ -1398,6 +1558,75 @@ 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: string,
+    sAppConfig: SAppConfig,
+    options: { requireSignedSchemas?: boolean } = {}
+  ): Promise<'attached' | 'already-attached'> {
+    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
@@ -1453,6 +1682,18 @@ export class StrandInstanceManager {
     });
   }
 
+  /**
+   * 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: string): Promise<StrandInstance | undefined> {
+    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
@@ -1482,9 +1723,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);
     }

package/src/strand-membership-writer.ts

@@ -1919,6 +1919,18 @@ export async function sealStrand(
   log('Sealed strand: sole manager %s stepped down', managerKeyPair.publicKeyB64);
 }
 
+/**
+ * The sApp id the strand's singleton `Strand.Header` names, or `undefined` when no
+ * Header row is held yet. A storage replica reads it to learn which app the strand it
+ * hosts belongs to (`CadreNode.getSAppId`).
+ */
+export async function readStrandHeaderSAppId(db: Database): Promise<string | undefined> {
+  for await (const row of db.eval('select sAppId from Strand.Header')) {
+    return typeof row.sAppId === 'string' ? row.sAppId : undefined;
+  }
+  return undefined;
+}
+
 /**
  * Whether the strand is `Type = 'c'` (closed). Reads the singleton `Header` via
  * the same `db.eval` scan idiom as {@link strandTableCount}; a strand with no

package/src/strand-peer-book-protocol.ts

@@ -28,7 +28,7 @@
  *
  * 1. Open strands have no shared member key at all, and the book has to work there.
  * 2. A member-key signature proves only "some member said this", so any member could
- *    forge another member's address and cost every peer a 14 s relayed dial per
+ *    forge another member's address and cost every peer a 16 s relayed dial per
  *    launch; a self-signature is a claim only the named peer can make.
  * 3. On a closed strand the member key is shared by every machine of a party, so it
  *    cannot identify a machine anyway.
@@ -88,12 +88,6 @@ export const STRAND_PEER_ISSUED_AT_SKEW_MS = 5 * 60 * 1000;
  */
 export const MAX_BOOK_FRAME_SIZE = 64 * 1024;
 
-/** Default time the receiver waits for the inbound request frame before aborting (ms). */
-const DEFAULT_READ_TIMEOUT_MS = 10_000;
-
-/** Default time the client waits for the whole exchange (ms). */
-const DEFAULT_EXCHANGE_TIMEOUT_MS = 10_000;
-
 /** Default cap on concurrent inbound swap streams a single strand node serves. */
 const DEFAULT_MAX_CONCURRENT = 100;
 
@@ -320,8 +314,12 @@ export interface StrandPeerBookServiceDeps {
 	onEntries(entries: SignedStrandPeerEntry[], fromPeerId: string): void;
 	/** Clock, for tests. Default `Date.now`. */
 	now?: () => number;
-	/** Default {@link DEFAULT_READ_TIMEOUT_MS}. */
-	readTimeoutMs?: number;
+	/**
+	 * How long the receiver waits for the inbound request frame (ms). Required for the same
+	 * reason as {@link ExchangeStrandPeerBookOptions.timeoutMs}: the swap gives both sides one
+	 * link-derived deadline.
+	 */
+	readTimeoutMs: number;
 	/** Default {@link DEFAULT_MAX_CONCURRENT}. Over it, an empty frame is returned unread. */
 	maxConcurrent?: number;
 }
@@ -341,7 +339,7 @@ export class StrandPeerBookService {
 	private activeStreams = 0;
 
 	constructor(private readonly deps: StrandPeerBookServiceDeps) {
-		this.readTimeoutMs = deps.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS;
+		this.readTimeoutMs = deps.readTimeoutMs;
 		this.maxConcurrent = deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
 		this.now = deps.now ?? Date.now;
 	}
@@ -427,8 +425,13 @@ async function closeQuietly(stream: ControlStream): Promise<void> {
 export interface ExchangeStrandPeerBookOptions {
 	/** This strand node's own peer id: a returned entry naming it is dropped. */
 	selfPeerId: string;
-	/** Whole-exchange deadline (ms). Default {@link DEFAULT_EXCHANGE_TIMEOUT_MS}. */
-	timeoutMs?: number;
+	/**
+	 * Whole-exchange deadline (ms). Required, with no fallback here: the exchange crosses the
+	 * link, so its deadline derives from the declared link round trip (`link-budget.ts`), and
+	 * the caller is the one that knows the declaration. A default in this module would be a
+	 * second number free to drift from that derivation.
+	 */
+	timeoutMs: number;
 	/** Clock, for tests. Default `Date.now`. */
 	now?: () => number;
 }
@@ -444,7 +447,7 @@ export async function exchangeStrandPeerBook(
 	request: StrandPeerBookFrame,
 	options: ExchangeStrandPeerBookOptions
 ): Promise<SignedStrandPeerEntry[]> {
-	const timeoutMs = options.timeoutMs ?? DEFAULT_EXCHANGE_TIMEOUT_MS;
+	const { timeoutMs } = options;
 	const remotePeerId = connection.remotePeer.toString();
 	assertBookFrameFits(request);
 	// One deadline for the stream open and the exchange together: its signal aborts the

package/src/strand-peer-book.ts

@@ -14,6 +14,13 @@
  * cohort each held only self, the strand reported `active`, local writes
  * succeeded, nothing replicated.
  *
+ * NOTE: interim, to be replaced (maintainer decision, 2026-09-28). FRET's
+ * `plan/10-feat-address-hints-in-neighbor-exchange` carries signed peer records in
+ * its neighbour exchange and its saved routing table. Once a FRET release with it
+ * reaches `@optimystic/db-p2p`, remove this book and the swap and pass db-p2p
+ * `persistence` for strand nodes instead; `blocked/retire-strand-peer-book-for-fret-address-hints`
+ * tracks that.
+ *
  * NOTE: accepted design boundary (maintainer decision, 2026-09-27) — this is a
  * per-machine record in the machine's own storage, NOT a registry inside the
  * strand database. An in-strand registry (`Strand.MemberPeer` rows carrying
@@ -60,7 +67,7 @@ const log = debug('sereus:cadre:strand-peer-book');
  * Cap on the peers remembered per strand. When full, the entry with the smallest
  * `max(issuedAt, lastSeenAt)` is evicted. Sixteen is generous for the parties a
  * strand has today (two, occasionally a few), and it bounds the worst case of a
- * launch dialing dead entries: a failed relayed dial costs up to 14 s at the
+ * launch dialing dead entries: a failed relayed dial costs up to 16 s at the
  * declared link, so the cap — with aging — is what keeps a stale book from
  * stalling bring-up for minutes.
  */

package/src/strand-peer-observer.ts

@@ -16,7 +16,7 @@
  *
  * Throttled to one report per peer per {@link STRAND_PEER_OBSERVE_THROTTLE_MS}
  * unless the address set changed, so a flapping relayed connection — identify
- * fires on every reconnect, every 14 s at worst — does not rewrite the node-local
+ * fires on every reconnect, every 16 s at worst — does not rewrite the node-local
  * slot each time. Best-effort throughout: nothing here throws into a libp2p event
  * handler.
  *

package/src/strand-revocation-enforcer.ts

@@ -118,7 +118,8 @@
 import debug from 'debug';
 import type { ConnectionGater, PeerId, MultiaddrConnection } from '@libp2p/interface';
 import type { Database } from '@quereus/quereus';
-import { ADMISSION_DECISION_TIMEOUT_MS, decideWithinDeadline } from './membership-connection-gater.js';
+import { decideWithinDeadline } from './membership-connection-gater.js';
+import { ADMISSION_DECISION_TIMEOUT_MS } from './link-budget.js';
 
 const log = debug('sereus:cadre:strand-revocation');