@serfab/cadre-core 1.5.0 → 1.7.0

package/dist/strand-first-sync-gate.d.ts

@@ -17,9 +17,17 @@
  * freshly initialized `StrandDatabase` back from the app — `StrandInstance.database` stays
  * unset and the instance reports `'syncing'` — and probes on a cadence until the Header is
  * readable AND a read of each app table settles, at which point the database is published
- * and the instance goes `'active'`. A machine that already holds the Header (a restart, a
- * hibernation resume, a founder) passes the probe on the first try and is never gated, so
- * offline-first writes on a machine that has synced before keep working.
+ * and the instance goes `'active'`. A machine whose store already holds the Header and every
+ * app table (a founder, and normally a restart or a hibernation resume) passes the probe on
+ * the first try and is never gated, so offline-first writes on a machine that has synced
+ * before keep working.
+ *
+ * "Has synced before" is decided by what the local store actually holds, not by whether this
+ * machine once read the strand: a machine that left soon after its first sync can hold less
+ * than it read, and is then gated like a joiner. The re-attach measurement on
+ * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS} saw exactly that — a machine back over the store
+ * it kept, without the `Strand.Header` collection it had read before it left. Gating it is
+ * right: writing into a collection this machine does not hold would fork it.
  *
  * Why the app tables too: the Header is ONE collection. It reaches a joiner ahead of the
  * founder's app-table collections (peer-join backfill and pull-on-read deliver those
@@ -36,10 +44,12 @@
  * every machine; the first write to it still creates its collection — see `docs/strands.md`
  * ("Joining") for that residual.
  *
- * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for a non-founder launch
- * whose first probe finds no Header, stopped and dropped in `releaseRuntime` (so a quiesce →
- * resume rebuild re-probes over the same store), and force-opened when a founder request
- * runs the bootstrap against the still-gated database (`foundExistingStrand`).
+ * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for every launch, armed
+ * only for a non-founder launch whose first probe fails, stopped and dropped in
+ * `releaseRuntime` (so a quiesce → resume rebuild re-probes over the same store), and opened
+ * by `publishDatabase` whenever the database is published without its loop — a launch that
+ * needed no gate, or a founder request that ran the bootstrap against the still-gated
+ * database (`foundExistingStrand`).
  *
  * NOTE: the gate covers app and membership tables, not the schema catalog. Every launch —
  * joiner or founder — writes the catalog collection (`optimystic/schema` plus two
@@ -57,48 +67,80 @@ import { type TimeoutScheduler } from './timeout-scheduler.js';
 /** How often a gated launch re-probes (`Strand.Header`, then every `App` table) while waiting for its first sync. */
 export declare const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
 /**
- * How long `CadreNode.addStrand` waits for a joining machine's first sync before rejecting
- * with {@link StrandAwaitingFirstSyncError}.
+ * How long `CadreNode.addStrand` waits for a machine's first sync before rejecting with
+ * {@link StrandAwaitingFirstSyncError}. It has to cover the slowest attach sereus carries,
+ * which is not a first join: a machine RE-attaching through a relay on a slow link can take
+ * longer than one joining for the first time.
  *
  * Measured over a DIRECT connection (2026-09-16): the joiner reads the founder's rows about
- * 1.3 s after `addStrand` would previously have resolved. That is still the fast case, and it
- * is not what this budget has to cover.
+ * 1.3 s after `addStrand` would previously have resolved. That is the fast case, and it is not
+ * what this budget has to cover.
  *
- * Measured over a RELAYED SLOW LINK (2026-09-26): one Windows developer machine, two
+ * Every harness figure below was taken on one shape: one Windows developer machine, two
  * relay-only `CadreNode`s (`listenAddrs: []`) on a shared loopback dedicated relay, with a
  * 900 ms one-way per-frame outbound delay applied to every websocket by
  * `integration-tests/src/harness/ws-latency.ts` in `pipelined` mode — frames stay overlapped
  * in flight, so the figure is latency and bandwidth stays unlimited; the harness's other mode
  * (`serial`) is a per-socket frame-rate cap and its delays are NOT comparable
- * (`docs/testing.md` → "Link latency"). A round trip therefore costs about
- * 1.8 s. Time from `addStrand` to writable, for a machine holding nothing of the strand yet:
- * 23, 27, 31 and 41 s over four runs at optimystic's 1000 ms cohort read deadline, and 35, 42
- * and 46 s over three runs at a 5000 ms one. **The second band is the one in force**: sereus
- * declares 5000 ms (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`),
- * because 1000 ms is shorter than one round trip on that link and leaves every cohort read with
- * no answer to corroborate against. Widening that deadline makes a consult against a peer that
- * cannot answer cost longer, and this phase runs several of those — which is why the two bands
- * are both recorded here, and why a change to either number has to be weighed against the
- * other. 120 s clears the worst sample of the band in force by about 2.6x. The previous 30 s
- * default sat INSIDE the first band, so roughly half of those joins were rejected as "not
- * writable yet" while the sync was progressing normally and went on to complete.
+ * (`docs/testing.md` → "Link latency"). A round trip therefore costs about 1.8 s. Times run
+ * from the `addStrand` call to writable.
+ *
+ * FRESH JOIN (2026-09-26), a machine holding nothing of the strand yet: 23, 27, 31 and 41 s
+ * over four runs at optimystic's 1000 ms cohort read deadline, and 35, 42 and 46 s over three
+ * runs at a 5000 ms one; the re-attach scenario below later took 38.7, 38.7 and 56.9 s for
+ * the same fresh join. **The 5000 ms band, 35-57 s, is the one in force**: sereus declares
+ * 5000 ms (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`), because
+ * 1000 ms is shorter than one round trip on that link and leaves every cohort read with no
+ * answer to corroborate against. Widening that deadline makes a consult against a peer that
+ * cannot answer cost longer, and this phase runs several of those — which is why both bands
+ * are recorded here, and why a change to either number has to be weighed against the other.
+ *
+ * RE-ATTACH (2026-09-26, the opt-in
+ * `integration-tests/src/scenarios/strand-reattach-first-sync-measure.integration.ts` — re-run
+ * it before changing this number): B attached once on an undelayed link, left with
+ * `stopStrand`, A wrote while it was away, the delay was raised, and B called `addStrand`
+ * again.
+ *  - Over an EMPTY store (one minted per launch, cadre's default with no storage provider):
+ *    gated in all four runs and writable at 38.7-56.8 s, the same as a fresh join.
+ *  - Over the store it KEPT (a phone with durable storage), bimodal. In 3 of 8 runs the store
+ *    held everything and the launch came up writable (5.6 s, the launch itself). In the other
+ *    5 it lacked the `Strand.Header` collection B had read on its first attach, so B was gated
+ *    like a joiner and became writable at 64.1-78.7 s — the slowest attach measured, about
+ *    twice a fresh join. Why syncing over a partial store is slower sits inside optimystic
+ *    (`tickets/blocked/report-reattach-over-partial-replica-to-optimystic`).
+ *  - Neither a redial nor catching up on missed writes explains the time: B's strand node
+ *    connected to A's at 11 s in every arm, fresh join included, and a run with 20 missed
+ *    writes fell inside the run-to-run spread of those with 1.
+ * This budget covers WRITABLE, not caught up: in the gated kept-store runs the row A wrote
+ * while B was away became readable only at 140-162 s.
+ *
+ * Two samples from outside this harness, neither reproduced here and neither discarded: a
+ * reporter's re-attach of the same shape (optimystic #22; their harness, storage and delay
+ * injector are unknown to us) opened the gate at about 150 s, after the previous 120 s budget
+ * had already rejected; and a real Galaxy S7 joining fresh through relay.sereus.org took 178 s.
+ *
+ * 300 s clears the worst harness sample (79 s) by about 3.8x, the reporter's re-attach by 2x
+ * and the device join by about 1.7x. 240 s was rejected: it clears the device join by only
+ * 1.35x, and that sample was not a re-attach. History: the original 30 s sat INSIDE the 1000 ms
+ * fresh band and refused about half of those joins while their sync was progressing normally;
+ * 120 s was sized from fresh joins only and refused the reporter's re-attach.
  *
- * NOTE: accepted tradeoff — what 120 s costs. This wait is what an app's `addStrand` sits in
- * before it is told "not yet", so a strand none of whose members is reachable at all takes two
- * minutes to report instead of thirty seconds. The slow report was weighed against refusing
- * joins that were working, and the refusal is the worse failure. The cost is bounded — the
- * rejection is retryable, the strand stays launched and keeps probing, and `strand:writable`
- * fires the moment the sync lands, so an app that listens for the event rather than awaiting
- * the call is unaffected either way. Revisit if the gate ever learns whether ANY other member
- * is connected: "no peer at all" could then be reported at once and this budget would only
- * ever be spent on a sync that is actually in progress.
+ * NOTE: accepted tradeoff — what 300 s costs. This wait is what an app's `addStrand` sits in
+ * before it is told "not yet", so a strand none of whose members is reachable at all takes five
+ * minutes to report instead of two. The slow report was weighed against refusing attaches that
+ * were working, and the refusal is the worse failure. The cost is bounded — the rejection is
+ * retryable, the strand stays launched and keeps probing, and `strand:writable` fires the
+ * moment the sync lands, so an app that listens for the event rather than awaiting the call is
+ * unaffected either way. Revisit if the gate ever learns whether ANY other member is connected:
+ * "no peer at all" could then be reported at once and this budget would only ever be spent on a
+ * sync that is actually in progress — worth more the longer this budget gets.
  */
-export declare const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 120000;
+export declare const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 300000;
 /** Embedder-facing tuning for the gate, threaded from `CadreNodeConfig.strandFirstSync`. */
 export interface StrandFirstSyncConfig {
     /**
-     * Default wait for `CadreNode.addStrand` (and `whenStrandWritable`) before a joining
-     * machine that has reached no other member is reported as not yet writable. Default
+     * Default wait for `CadreNode.addStrand` (and `whenStrandWritable`) before a machine whose
+     * first sync has not completed is reported as not yet writable. Default
      * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS}.
      */
     timeoutMs?: number;
@@ -106,11 +148,12 @@ export interface StrandFirstSyncConfig {
     pollIntervalMs?: number;
 }
 /**
- * Thrown by `CadreNode.addStrand` / `whenStrandWritable` when a joining machine has not
- * received the strand's data from any other member within the wait budget. RETRYABLE: the
- * strand stays launched and keeps probing, so a later `addStrand` (or `whenStrandWritable`)
- * for the same strand completes the attach once another member is reachable; the
- * `strand:writable` event fires at that moment too.
+ * Thrown by `CadreNode.addStrand` / `whenStrandWritable` when a machine has not received the
+ * strand's data from another member within the wait budget — because no other member is
+ * reachable, or because one is and the sync is still arriving over a slow link; the gate
+ * cannot tell the two apart. RETRYABLE: the strand stays launched and keeps probing, so a
+ * later `addStrand` (or `whenStrandWritable`) for the same strand completes the attach once
+ * the data has arrived; the `strand:writable` event fires at that moment too.
  */
 export declare class StrandAwaitingFirstSyncError extends Error {
     readonly strandId: string;
@@ -171,8 +214,10 @@ export declare class StrandFirstSyncGate {
     /** Arm the probe loop. The first probe runs after one interval — the caller already probed once. */
     start(): void;
     /**
-     * Force-open: the caller has just written the Header itself (a founder bootstrap run
-     * against the gated database). Stops the loop; `onHeaderHeld` is NOT invoked.
+     * Open without the probe loop: the caller is publishing the database itself — a launch
+     * whose first probe passed (or a founder's), which never armed the loop, or a founder
+     * bootstrap just run against the gated database. Stops the loop; `onHeaderHeld` is NOT
+     * invoked.
      */
     open(): void;
     /** Disarm the loop; a probe already in flight completes and is then ignored. */

package/dist/strand-first-sync-gate.js

@@ -17,9 +17,17 @@
  * freshly initialized `StrandDatabase` back from the app — `StrandInstance.database` stays
  * unset and the instance reports `'syncing'` — and probes on a cadence until the Header is
  * readable AND a read of each app table settles, at which point the database is published
- * and the instance goes `'active'`. A machine that already holds the Header (a restart, a
- * hibernation resume, a founder) passes the probe on the first try and is never gated, so
- * offline-first writes on a machine that has synced before keep working.
+ * and the instance goes `'active'`. A machine whose store already holds the Header and every
+ * app table (a founder, and normally a restart or a hibernation resume) passes the probe on
+ * the first try and is never gated, so offline-first writes on a machine that has synced
+ * before keep working.
+ *
+ * "Has synced before" is decided by what the local store actually holds, not by whether this
+ * machine once read the strand: a machine that left soon after its first sync can hold less
+ * than it read, and is then gated like a joiner. The re-attach measurement on
+ * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS} saw exactly that — a machine back over the store
+ * it kept, without the `Strand.Header` collection it had read before it left. Gating it is
+ * right: writing into a collection this machine does not hold would fork it.
  *
  * Why the app tables too: the Header is ONE collection. It reaches a joiner ahead of the
  * founder's app-table collections (peer-join backfill and pull-on-read deliver those
@@ -36,10 +44,12 @@
  * every machine; the first write to it still creates its collection — see `docs/strands.md`
  * ("Joining") for that residual.
  *
- * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for a non-founder launch
- * whose first probe finds no Header, stopped and dropped in `releaseRuntime` (so a quiesce →
- * resume rebuild re-probes over the same store), and force-opened when a founder request
- * runs the bootstrap against the still-gated database (`foundExistingStrand`).
+ * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for every launch, armed
+ * only for a non-founder launch whose first probe fails, stopped and dropped in
+ * `releaseRuntime` (so a quiesce → resume rebuild re-probes over the same store), and opened
+ * by `publishDatabase` whenever the database is published without its loop — a launch that
+ * needed no gate, or a founder request that ran the bootstrap against the still-gated
+ * database (`foundExistingStrand`).
  *
  * NOTE: the gate covers app and membership tables, not the schema catalog. Every launch —
  * joiner or founder — writes the catalog collection (`optimystic/schema` plus two
@@ -57,56 +67,90 @@ const log = debug('sereus:cadre:strand-first-sync');
 /** How often a gated launch re-probes (`Strand.Header`, then every `App` table) while waiting for its first sync. */
 export const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
 /**
- * How long `CadreNode.addStrand` waits for a joining machine's first sync before rejecting
- * with {@link StrandAwaitingFirstSyncError}.
+ * How long `CadreNode.addStrand` waits for a machine's first sync before rejecting with
+ * {@link StrandAwaitingFirstSyncError}. It has to cover the slowest attach sereus carries,
+ * which is not a first join: a machine RE-attaching through a relay on a slow link can take
+ * longer than one joining for the first time.
  *
  * Measured over a DIRECT connection (2026-09-16): the joiner reads the founder's rows about
- * 1.3 s after `addStrand` would previously have resolved. That is still the fast case, and it
- * is not what this budget has to cover.
+ * 1.3 s after `addStrand` would previously have resolved. That is the fast case, and it is not
+ * what this budget has to cover.
  *
- * Measured over a RELAYED SLOW LINK (2026-09-26): one Windows developer machine, two
+ * Every harness figure below was taken on one shape: one Windows developer machine, two
  * relay-only `CadreNode`s (`listenAddrs: []`) on a shared loopback dedicated relay, with a
  * 900 ms one-way per-frame outbound delay applied to every websocket by
  * `integration-tests/src/harness/ws-latency.ts` in `pipelined` mode — frames stay overlapped
  * in flight, so the figure is latency and bandwidth stays unlimited; the harness's other mode
  * (`serial`) is a per-socket frame-rate cap and its delays are NOT comparable
- * (`docs/testing.md` → "Link latency"). A round trip therefore costs about
- * 1.8 s. Time from `addStrand` to writable, for a machine holding nothing of the strand yet:
- * 23, 27, 31 and 41 s over four runs at optimystic's 1000 ms cohort read deadline, and 35, 42
- * and 46 s over three runs at a 5000 ms one. **The second band is the one in force**: sereus
- * declares 5000 ms (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`),
- * because 1000 ms is shorter than one round trip on that link and leaves every cohort read with
- * no answer to corroborate against. Widening that deadline makes a consult against a peer that
- * cannot answer cost longer, and this phase runs several of those — which is why the two bands
- * are both recorded here, and why a change to either number has to be weighed against the
- * other. 120 s clears the worst sample of the band in force by about 2.6x. The previous 30 s
- * default sat INSIDE the first band, so roughly half of those joins were rejected as "not
- * writable yet" while the sync was progressing normally and went on to complete.
+ * (`docs/testing.md` → "Link latency"). A round trip therefore costs about 1.8 s. Times run
+ * from the `addStrand` call to writable.
+ *
+ * FRESH JOIN (2026-09-26), a machine holding nothing of the strand yet: 23, 27, 31 and 41 s
+ * over four runs at optimystic's 1000 ms cohort read deadline, and 35, 42 and 46 s over three
+ * runs at a 5000 ms one; the re-attach scenario below later took 38.7, 38.7 and 56.9 s for
+ * the same fresh join. **The 5000 ms band, 35-57 s, is the one in force**: sereus declares
+ * 5000 ms (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`), because
+ * 1000 ms is shorter than one round trip on that link and leaves every cohort read with no
+ * answer to corroborate against. Widening that deadline makes a consult against a peer that
+ * cannot answer cost longer, and this phase runs several of those — which is why both bands
+ * are recorded here, and why a change to either number has to be weighed against the other.
+ *
+ * RE-ATTACH (2026-09-26, the opt-in
+ * `integration-tests/src/scenarios/strand-reattach-first-sync-measure.integration.ts` — re-run
+ * it before changing this number): B attached once on an undelayed link, left with
+ * `stopStrand`, A wrote while it was away, the delay was raised, and B called `addStrand`
+ * again.
+ *  - Over an EMPTY store (one minted per launch, cadre's default with no storage provider):
+ *    gated in all four runs and writable at 38.7-56.8 s, the same as a fresh join.
+ *  - Over the store it KEPT (a phone with durable storage), bimodal. In 3 of 8 runs the store
+ *    held everything and the launch came up writable (5.6 s, the launch itself). In the other
+ *    5 it lacked the `Strand.Header` collection B had read on its first attach, so B was gated
+ *    like a joiner and became writable at 64.1-78.7 s — the slowest attach measured, about
+ *    twice a fresh join. Why syncing over a partial store is slower sits inside optimystic
+ *    (`tickets/blocked/report-reattach-over-partial-replica-to-optimystic`).
+ *  - Neither a redial nor catching up on missed writes explains the time: B's strand node
+ *    connected to A's at 11 s in every arm, fresh join included, and a run with 20 missed
+ *    writes fell inside the run-to-run spread of those with 1.
+ * This budget covers WRITABLE, not caught up: in the gated kept-store runs the row A wrote
+ * while B was away became readable only at 140-162 s.
+ *
+ * Two samples from outside this harness, neither reproduced here and neither discarded: a
+ * reporter's re-attach of the same shape (optimystic #22; their harness, storage and delay
+ * injector are unknown to us) opened the gate at about 150 s, after the previous 120 s budget
+ * had already rejected; and a real Galaxy S7 joining fresh through relay.sereus.org took 178 s.
+ *
+ * 300 s clears the worst harness sample (79 s) by about 3.8x, the reporter's re-attach by 2x
+ * and the device join by about 1.7x. 240 s was rejected: it clears the device join by only
+ * 1.35x, and that sample was not a re-attach. History: the original 30 s sat INSIDE the 1000 ms
+ * fresh band and refused about half of those joins while their sync was progressing normally;
+ * 120 s was sized from fresh joins only and refused the reporter's re-attach.
  *
- * NOTE: accepted tradeoff — what 120 s costs. This wait is what an app's `addStrand` sits in
- * before it is told "not yet", so a strand none of whose members is reachable at all takes two
- * minutes to report instead of thirty seconds. The slow report was weighed against refusing
- * joins that were working, and the refusal is the worse failure. The cost is bounded — the
- * rejection is retryable, the strand stays launched and keeps probing, and `strand:writable`
- * fires the moment the sync lands, so an app that listens for the event rather than awaiting
- * the call is unaffected either way. Revisit if the gate ever learns whether ANY other member
- * is connected: "no peer at all" could then be reported at once and this budget would only
- * ever be spent on a sync that is actually in progress.
+ * NOTE: accepted tradeoff — what 300 s costs. This wait is what an app's `addStrand` sits in
+ * before it is told "not yet", so a strand none of whose members is reachable at all takes five
+ * minutes to report instead of two. The slow report was weighed against refusing attaches that
+ * were working, and the refusal is the worse failure. The cost is bounded — the rejection is
+ * retryable, the strand stays launched and keeps probing, and `strand:writable` fires the
+ * moment the sync lands, so an app that listens for the event rather than awaiting the call is
+ * unaffected either way. Revisit if the gate ever learns whether ANY other member is connected:
+ * "no peer at all" could then be reported at once and this budget would only ever be spent on a
+ * sync that is actually in progress — worth more the longer this budget gets.
  */
-export const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 120000;
+export const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 300000;
 /**
- * Thrown by `CadreNode.addStrand` / `whenStrandWritable` when a joining machine has not
- * received the strand's data from any other member within the wait budget. RETRYABLE: the
- * strand stays launched and keeps probing, so a later `addStrand` (or `whenStrandWritable`)
- * for the same strand completes the attach once another member is reachable; the
- * `strand:writable` event fires at that moment too.
+ * Thrown by `CadreNode.addStrand` / `whenStrandWritable` when a machine has not received the
+ * strand's data from another member within the wait budget — because no other member is
+ * reachable, or because one is and the sync is still arriving over a slow link; the gate
+ * cannot tell the two apart. RETRYABLE: the strand stays launched and keeps probing, so a
+ * later `addStrand` (or `whenStrandWritable`) for the same strand completes the attach once
+ * the data has arrived; the `strand:writable` event fires at that moment too.
  */
 export class StrandAwaitingFirstSyncError extends Error {
     constructor(strandId, waitedMs) {
-        super(`Strand ${strandId} is not writable yet: no member of this strand has been reachable ` +
-            `since this machine joined, so it has not received the strand's data (waited ${waitedMs} ms). ` +
-            'The strand stays launched and keeps trying — call addStrand again, or wait for the ' +
-            "'strand:writable' event, once another member is reachable.");
+        super(`Strand ${strandId} is not writable yet: this machine has not yet received the strand's data ` +
+            `from another member (waited ${waitedMs} ms). Either no other member is reachable, or the ` +
+            'link to one is slow and the sync is still in progress. The strand stays launched and keeps ' +
+            'trying — call addStrand or whenStrandWritable(strandId) again to keep waiting, or listen ' +
+            "for the 'strand:writable' event.");
         this.name = 'StrandAwaitingFirstSyncError';
         this.strandId = strandId;
         this.waitedMs = waitedMs;
@@ -192,15 +236,17 @@ export class StrandFirstSyncGate {
         log('[%s] first-sync gate armed: no Strand.Header held yet; probing every %dms', this.deps.label, this.pollIntervalMs);
     }
     /**
-     * Force-open: the caller has just written the Header itself (a founder bootstrap run
-     * against the gated database). Stops the loop; `onHeaderHeld` is NOT invoked.
+     * Open without the probe loop: the caller is publishing the database itself — a launch
+     * whose first probe passed (or a founder's), which never armed the loop, or a founder
+     * bootstrap just run against the gated database. Stops the loop; `onHeaderHeld` is NOT
+     * invoked.
      */
     open() {
         if (this.opened)
             return;
         this.opened = true;
         this.stop();
-        log('[%s] first-sync gate opened by the caller (Header written locally)', this.deps.label);
+        log('[%s] database published by the caller; first-sync gate not needed or force-opened', this.deps.label);
     }
     /** Disarm the loop; a probe already in flight completes and is then ignored. */
     stop() {

package/dist/strand-first-sync-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"strand-first-sync-gate.js","sourceRoot":"","sources":["../src/strand-first-sync-gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strand-first-sync-gate.js","sourceRoot":"","sources":["../src/strand-first-sync-gate.ts"],"names":[],"mappings":"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"}

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

@@ -1,5 +1,7 @@
 import type { PrivateKey } from '@libp2p/interface';
 import { type PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import { type StrandPeerObservation } from './strand-peer-observer.js';
+import type { StrandPeerBookStore } from './strand-peer-book.js';
 import { type StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
 import { type PendingMembershipInviteSource, type StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
 import { type StrandFirstSyncConfig } from './strand-first-sync-gate.js';
@@ -200,6 +202,26 @@ export interface StartStrandConfig {
      * hibernation wake's rebuilt supervisors carry it too.
      */
     announceDelegateToRelay?: (strandId: string, relayAddr: string, delegatePeerId: string) => Promise<void>;
+    /**
+     * Called when the strand's libp2p node identifies a STRAND peer — one whose
+     * identify result names this strand's block-transfer protocol, so never the
+     * circuit relay or a bootstrap node — with the addresses it is dialable at
+     * (`strand-peer-observer.ts`). Throttled per peer; must not throw. `CadreNode`
+     * wires it to the node-local strand peer book, which is what lets a restarted
+     * machine dial the peers it was talking to. Absent ⇒ nothing is observed.
+     * Retained with the launch config, so a hibernation wake re-arms it on the
+     * rebuilt node.
+     */
+    onStrandPeerIdentified?: (strandId: string, observation: StrandPeerObservation) => void;
+    /**
+     * The node-local strand peer book the book SWAP reads and writes
+     * (`strand-peer-book-swap.ts`): the strand node signs its own addresses with
+     * {@link privateKey}, exchanges signed entries with every strand peer it identifies,
+     * and files what verifies. Absent ⇒ no swap runs — a peer that dials this node's
+     * swap handler gets no answer. `CadreNode` passes its book store. Retained with the
+     * launch config, so a hibernation wake re-arms the swap on the rebuilt node.
+     */
+    strandPeerBook?: StrandPeerBookStore;
 }
 /**
  * Volatile inputs re-resolved when resuming a quiesced strand — the ones that can
@@ -259,6 +281,23 @@ export declare class StrandInstanceManager {
      * missed writes).
      */
     private backfills;
+    /**
+     * 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`.
+     */
+    private peerObservers;
+    /**
+     * 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`.
+     */
+    private peerBookSwaps;
     /**
      * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
      * id. Same lifecycle rationale as {@link backfills}: created in

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';
@@ -13,7 +15,7 @@ import { StrandFirstSyncGate, StrandAwaitingFirstSyncError, strandFirstSyncCompl
 import { DEFAULT_CONNECTION_MONITOR, resolveStrandClusterSize, strandClusterPolicy } from './types.js';
 import { strandNodeAddrs } from './strand-network-config.js';
 import { superviseRelayReservation } from './relay-reservation.js';
-import { peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { connectionManagerTimeouts, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
 /**
@@ -119,6 +121,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
@@ -433,6 +452,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),
                 // 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
@@ -450,6 +473,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>/…`
@@ -562,7 +625,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.
@@ -600,7 +663,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, 8 s at its default (`link-budget.ts`) — and
+            // counted from the declared link round trip, 14 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
@@ -657,6 +720,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);