@serfab/cadre-core 1.16.0 → 1.18.0

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

@@ -11,16 +11,16 @@
  * founder from a joiner; sereus can, because the launch knows whether it is founding.
  *
  * The invariant this module enforces: **a machine that has never held this strand's
- * `Strand.Header` row, and has not read every `App` table once, must not commit to it.**
- * The founder writes the Header in its bootstrap; every other machine can only receive it
- * from a peer, so "no local Header" means "never synced". The gate therefore holds the
+ * `Strand.Header` row, and has not read every `Strand` and `App` table once, must not commit
+ * to it.** The founder writes the Header in its bootstrap; every other machine can only receive
+ * it from a peer, so "no local Header" means "never synced". The gate therefore holds the
  * 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 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.
+ * unset and the instance reports `'syncing'` — and probes, whenever data lands in the strand's
+ * store and on a backstop timer, until the Header is readable AND a read of each other table
+ * settles, at which point the database is published and the instance goes `'active'`. A
+ * machine whose store already holds the Header and every other 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
@@ -29,22 +29,28 @@
  * 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
- * separately), and a write to a table whose collection this machine has not yet fetched
- * invents one exactly as a lone joiner did. Measured on the reference chat schema
- * (2026-09-16, direct connections, Header-only probe): the joiner's participant + message
- * written the instant `addStrand` resolved diverged in 3 of 4 runs. Reading each table once
- * pulls its collection while the founder is reachable, so the write that follows appends.
+ * Why the other tables too: the Header is ONE collection. It reaches a joiner ahead of the
+ * founder's other collections (peer-join backfill and pull-on-read deliver those separately),
+ * and a write to a table whose collection this machine has not yet fetched invents one exactly
+ * as a lone joiner did. Measured on the reference chat schema (2026-09-16, direct connections,
+ * Header-only probe): the joiner's participant + message written the instant `addStrand`
+ * resolved diverged in 3 of 4 runs. The same holds for the `Strand` tables, which reach a joiner
+ * by the same backfill: the membership loop writes `ConsumedInvite`, `Member` and `MemberPeer`
+ * about a second after publication, and a manager writes `Invite`, `CancelledInvite`, `Manager`
+ * and `Revocation`. Reading each table once pulls its collection while the founder is
+ * reachable, so the write that follows appends.
  *
- * Every probe is a read (`Strand.Header`, then `select count(1)` on each `App` table). Reads
- * never invent a collection (Optimystic's `Collection.open` resolves undefined on an
- * authoritatively absent header, and throws on an unreachable one), so probing is safe to
- * repeat and a throw is just "not yet". A table nobody has written yet reads as absent on
- * every machine; the first write to it still creates its collection — see `docs/strands.md`
- * ("Joining") for that residual.
+ * Every probe read is `select 1 from <table> limit 1` (`Strand.Header`, then each other `Strand`
+ * table, then each `App` table, skipping those already seen settled): opening the table fetches
+ * its collection header, and one row walks the root to the first leaf. Reads never commit a
+ * collection (one ruled authoritatively absent is staged empty in memory only, and an
+ * unreachable one throws), so probing is safe to repeat and a throw is just "not yet". Every
+ * table declared at founding has a collection from the start (the founder bootstrap commits the
+ * rest empty before its founding transaction writes the Header and the membership rows), so a
+ * probe read fetches it; a table a later schema version adds reads as absent until its first
+ * write creates the collection — see `docs/strands.md` ("Joining") for that residual.
  *
- * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for every launch, armed
+ * Owned by `StrandInstanceManager`: created in `buildStrandDatabase` for every database build, 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
@@ -62,11 +68,22 @@
  * it), a joiner's catalog will fork against the founder's — gate the schema apply on the
  * Header too, or have optimystic open the catalog read-only when a peer already holds it.
  */
-import type { Database } from '@quereus/quereus';
 import type { StrandDatabase } from './strand-database.js';
 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 a gated launch goes without probing when no data lands in the strand's store: the
+ * gate probes when data arrives, and this long after its last probe settled when none has. It
+ * covers a probe that failed for a reason no storage event follows — a consult that missed its
+ * deadline while the founder held the block, or a push that never comes.
+ *
+ * Why 2 s: arrivals wake the gate, so this timer is the fallback rather than the main path. At
+ * the supported 3 s link round trip one consult takes about 6 s (two round trips, per the 1.8.0
+ * measurements on {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS}), so a 2 s idle gap after a failed
+ * probe adds at most a third of one probe round, and it is under 1% of that 360 s budget. Shorter
+ * brings back the cost of polling (the gate re-probed every 500 ms before it woke on arrivals);
+ * much longer (5 s) delays the case with no storage event by most of a probe round for nothing.
+ */
+export declare const DEFAULT_STRAND_FIRST_SYNC_BACKSTOP_MS = 2000;
 /**
  * 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,
@@ -97,6 +114,37 @@ export declare const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
  * 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.
  *
+ * AT THE SUPPORTED LINK ON `@optimystic/*` 1.17.0 (2026-10-21), 1 500 ms one-way, the same
+ * scenario, one run per arm, with the probe reading every `Strand` table as well as the `App`
+ * one (`debt-first-sync-gate-reads-every-strand-table`); the kept-store arm was not run:
+ *  - Fresh join: writable at 28.7 s and NOT gated, as on 1.15.0.
+ *  - Re-attach over an EMPTY store: writable at 105.8 and 105.9 s over two runs, the row A wrote
+ *    while B was away readable at the same moment. B's first database build fails at 7.0 s (no
+ *    seed peer has answered; `StrandInstanceManager.deferUnreachableJoin` retries it), B's strand
+ *    node connects to A's at 15.1 s, the retried build's `connectToStrand` takes 21.2 s, and the
+ *    launch's first probe then takes 72.6 s and passes with no read failing, so the gate never
+ *    arms.
+ *  - The same arm with the probe held to the Header and the `App` table (one run, otherwise the
+ *    same build): that probe took 12.1 s, writable at 45.4 s, the row at 63.5 s. So the seven
+ *    `Strand` reads cost about 60 s here, about 8.6 s each, against about 6 s for each of the
+ *    baseline's two reads — more than the 42 s estimated from one 6 s consult per read.
+ *
+ * AT THE SUPPORTED LINK ON `@optimystic/*` 1.15.0 (2026-10-20), 1 500 ms one-way, the same
+ * scenario, one fresh-join run, with the one-row probes woken by data landing in the store
+ * (`first-sync-gate-probes-cheaply`; the full-count probes polled every 500 ms gave the same
+ * figures):
+ *  - Fresh join: writable at 28.8 s, and NOT gated. The launch waits 27.3 s in
+ *    `connectToStrand` for its seed peer (it hydrates the founder's catalog, 9 tables), and by
+ *    then the store holds the strand: the first probe passed in 24 ms.
+ *  - The strand case of `message-cost-accounting` (two relay-only parties on loopback) agrees:
+ *    B's `addStrand` took 471 ms, with 13 `sync` streams to A, 4 block reads from the Header
+ *    probe and 8 from the table probes. Its two tables are empty, so a full count would fetch
+ *    the same blocks as a one-row read.
+ *  - Neither arms the gate, so neither times the woken path. That was checked on
+ *    `harness-topology`'s cross-party share (a joiner launched with no seed, dialed afterwards)
+ *    with the backstop raised to 10 s: the founder's join backfill push opened the gate 2.1 s
+ *    after it armed.
+ *
  * AT THE SUPPORTED LINK ON `@optimystic/*` 1.8.0 (2026-09-29), 1 500 ms one-way, the read
  * deadline derived from the declared link at 7 000 ms (`cohortReadDeadlineMs` in
  * `link-budget.ts`; the plugin's `COHORT_READ_DEADLINE_MS` is the same number), and cadre
@@ -153,19 +201,19 @@ export declare const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
  * 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 (82 s, a fresh join at the supported link on 1.7.0; the
- * worst on 1.8.0 is 64 s) by about 3.6x, the reporter's re-attach by 2x and the device join by
- * about 1.7x. Kept at 300 s on 2026-09-29, and again after the 1.8.0 re-measure the same day,
- * by the rule that re-measure applied and the next one should: keep it while the
- * worst harness sample is at most 100 s, which holds a margin of at least 3x; otherwise raise
- * it to 3x the worst sample, rounded up to the next whole minute. 240 s was rejected earlier:
- * 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.
+ * 360 s clears the worst harness sample (105.9 s, a re-attach over an empty store at the
+ * supported link on 1.17.0) by about 3.4x, the reporter's re-attach by 2.4x and the device join
+ * by about 2x. Set by the rule every re-measure applies: keep it while the worst harness sample
+ * is at most 100 s, which holds a margin of at least 3x; otherwise raise it to 3x the worst
+ * sample, rounded up to the next whole minute. The 1.17.0 sample crossed 100 s, and 3x 105.9 s
+ * is 318 s, so 360 s (2026-10-21); the 1.7.0 and 1.8.0 re-measures (worst 82 s and 64 s) had
+ * kept the 300 s before it. 240 s was rejected earlier: 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 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
+ * NOTE: accepted tradeoff — what 360 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 six
  * 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
@@ -174,7 +222,7 @@ export declare const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
  * "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 = 300000;
+export declare const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 360000;
 /** Embedder-facing tuning for the gate, threaded from `CadreNodeConfig.strandFirstSync`. */
 export interface StrandFirstSyncConfig {
     /**
@@ -183,8 +231,11 @@ export interface StrandFirstSyncConfig {
      * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS}.
      */
     timeoutMs?: number;
-    /** Probe cadence while gated. Default {@link DEFAULT_STRAND_FIRST_SYNC_POLL_MS}. */
-    pollIntervalMs?: number;
+    /**
+     * While gated, probe this long after the last probe settled when no data has landed in the
+     * strand's store. Default {@link DEFAULT_STRAND_FIRST_SYNC_BACKSTOP_MS}.
+     */
+    backstopMs?: number;
 }
 /**
  * Thrown by `CadreNode.addStrand` / `whenStrandWritable` when a machine has not received the
@@ -199,82 +250,119 @@ export declare class StrandAwaitingFirstSyncError extends Error {
     readonly waitedMs: number;
     constructor(strandId: string, waitedMs: number);
 }
-/**
- * Whether this machine holds the strand's `Strand.Header` row — the "has synced at least
- * once (or founded)" signal. A read, never a write: it cannot invent the collection. A
- * throwing read (an unreachable cohort mid-sync, a store still hydrating) reports `false`
- * with a log, since the caller's only response to either answer is "probe again".
- */
-export declare function strandHeaderHeld(db: Database, label: string): Promise<boolean>;
-/**
- * Whether a read of every `App` table settles on this machine — the "each app collection
- * has been fetched from the cohort, or is authoritatively absent" signal. Only a throwing
- * read (an unreachable cohort) reports `false`; an empty table is a settled read.
- */
-export declare function appTablesReadable(db: Database, label: string): Promise<boolean>;
-/**
- * The gate's whole probe: the Header is held AND every app table has been read once. The
- * app tables are read only once the Header is — a joiner with no peer would otherwise pay
- * one failing network read per table per probe for nothing.
- */
-export declare function strandFirstSyncComplete(db: Database, label: string): Promise<boolean>;
 export interface StrandFirstSyncGateDeps {
     /** Log tag naming which strand this gate holds (the strand id). */
     label: string;
-    /** The initialized database being held back from the app until the Header is held. */
+    /** The initialized database being held back from the app until the first sync completes. */
     database: StrandDatabase;
     /**
-     * Called exactly once, on the gate's own probe loop, when the first sync completes.
-     * NOT called by {@link StrandFirstSyncGate.open} — a caller that force-opens the gate
-     * (a founder bootstrap it just ran) publishes the database itself.
+     * Called exactly once, from the gate's own probe, when the first sync completes. NOT called
+     * by {@link StrandFirstSyncGate.open} — a caller that force-opens the gate (a founder
+     * bootstrap it just ran) publishes the database itself.
      */
     onHeaderHeld: () => void;
-    /** Timer seam for the probe loop; omit for real (unref'd) timeouts. */
+    /**
+     * Subscribe `onChange` to every block landing in this strand's store — a push such as join
+     * backfill, a fetched block, a commit — and return the unsubscribe. `buildStrandDatabase`
+     * passes the strand node's `storageRepo.onAnyCollectionChange`. Omitted (test doubles, a node
+     * without it), the gate probes on its backstop alone.
+     */
+    subscribeStorageChanges?: (onChange: () => void) => () => void;
+    /** Timer seam for the probe schedule; omit for real (unref'd) timeouts. */
     scheduler?: TimeoutScheduler;
 }
 /**
- * Holds one launch's `StrandDatabase` until {@link strandFirstSyncComplete}. Probes are
- * sequential (the next is scheduled only after the previous read settles), so a slow
- * network read never stacks probes.
+ * Holds one launch's `StrandDatabase` until the first sync completes: the `Strand.Header` row is
+ * held and a read of every `Strand` and `App` table has settled. What a probe established is
+ * remembered for the gate's lifetime, so a later probe — the gate's own, after the caller's
+ * {@link probeOnce} — reads only what is still missing. A gate lives for one database build, so a
+ * hibernation wake or a deferred-join retry starts over, and over a store that holds everything
+ * every read answers locally.
+ *
+ * While armed it probes when data lands in the strand's store
+ * ({@link StrandFirstSyncGateDeps.subscribeStorageChanges}, coalesced over
+ * `TABLE_CHANGE_COALESCE_MS`), and {@link StrandFirstSyncConfig.backstopMs} after its last probe
+ * settled when nothing has. Probes run on `scheduleRuns`: one at a time, and data landing during
+ * one produces exactly one more.
+ *
+ * The wake source is the node's storage-wide change feed rather than a table watch
+ * (`StrandDatabase.watchTables`): the Optimystic plugin arms a table's replicated-change bridge
+ * only after the table initializes successfully, and the tables the gate waits on are the ones
+ * whose collection could not be fetched yet, so a table watch would not hear the push that
+ * delivers them. Each strand has its own libp2p node and store, so the feed hears this strand
+ * only.
  *
  * NOTE: a probe's reads dial the founder, through the relay when that is the only route, even
  * while the founder is unreachable: one run of `joiner-first-commit-over-slow-relay` logged 17
  * `hop connect denied` at the relay in about 10 s, each a few frames on the joiner's relay
- * connection. If that connection ever shows saturated while no strand member is connected, hold
- * the probe while the strand member redial (`strand-peer-redial.ts`) reports none connected.
+ * connection, when the gate re-probed every 500 ms and re-read every table. It now probes on
+ * arrivals and a 2 s backstop and skips what it holds, so expect fewer. If that connection ever
+ * shows saturated while no strand member is connected, hold the probe while the strand member
+ * redial (`strand-peer-redial.ts`) reports none connected.
  */
 export declare class StrandFirstSyncGate {
     private readonly deps;
     private readonly scheduler;
-    private readonly pollIntervalMs;
-    private timer;
+    private readonly backstopMs;
+    private readonly progress;
+    private probes;
+    private unsubscribeStorage;
+    private listening;
+    /**
+     * Data landed since the last probe started (or, before any probe, since {@link listen}), so one
+     * is already due and will read it.
+     */
+    private landedSinceProbe;
     private stopped;
     private opened;
-    private probing;
     constructor(deps: StrandFirstSyncGateDeps, config?: StrandFirstSyncConfig);
     /** The database this gate is holding back. */
     get database(): StrandDatabase;
-    /** True once the Header was seen (or the gate was force-opened); the loop is then done. */
+    /** True once the first sync completed (or the gate was force-opened); probing is then done. */
     get isOpen(): boolean;
-    /** Arm the probe loop. The first probe runs after one interval — the caller already probed once. */
+    /** Whether a block landed since the last probe started, or since {@link listen} when none has. */
+    get heardDataSinceProbe(): boolean;
+    /**
+     * Subscribe to the storage change feed ahead of {@link start}, so a block landing before the
+     * gate is armed is heard: {@link heardDataSinceProbe} reports it, and `start` then probes at
+     * once. For a first join, which skips the caller's first probe unless a member's push already
+     * landed while the database was initializing.
+     */
+    listen(): void;
+    /**
+     * Arm the probe schedule. It probes when data lands, or one backstop later; and at once when
+     * data already landed since the last probe (or since {@link listen}). Without `listen`, data
+     * that landed between the caller's probe and this call raised no event the gate heard, so
+     * that first backstop is what catches it.
+     */
     start(): void;
     /**
-     * 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 without probing: the caller is publishing the database itself — a launch whose first
+     * probe passed (or a founder's), which never armed the schedule, or a founder bootstrap just
+     * run against the gated database. Stops probing; `onHeaderHeld` is NOT invoked.
      */
     open(): void;
-    /** Disarm the loop; a probe already in flight completes and is then ignored. */
+    /** Disarm: unsubscribe and drop the schedule; a probe already in flight completes and is then ignored. */
     stop(): void;
-    private schedule;
-    private probe;
     /**
-     * One probe's answer, with a throw from OUTSIDE {@link strandFirstSyncComplete}'s own read
-     * guards — the `App` schema lookup, or `getDatabase()` itself — reported as "not yet" like
-     * any failing read. The loop is scheduled from `void this.probe()`, so an escaping rejection
-     * would be unhandled AND leave nothing scheduled: the strand would stay gated for the whole
-     * `timeoutMs` and never recover, which is the one failure this gate must not have.
+     * One probe's answer, reading only what this gate has not yet seen settled. A throw from
+     * OUTSIDE the probe's own read guards — a schema lookup, or `getDatabase()` itself — is
+     * reported as "not yet" like any failing read, so the caller's first probe cannot fail the
+     * launch over it and the gate's log says what happened.
+     */
+    probeOnce(): Promise<boolean>;
+    /**
+     * NOTE: a probe's own reads can land blocks (a fetched block, a read-repair), which fires this
+     * feed and schedules one follow-up probe. Each follow-up means a block newly arrived, so they
+     * stop when nothing new lands; if gated launches ever show probe storms in the logs, ignore
+     * events while a probe is in flight.
      */
-    private probeHeld;
+    private subscribeStorage;
+    /**
+     * Called synchronously by the store after each block lands, so it only arms a timer. A push
+     * lands its blocks one by one; only the first since the last probe started arms one, since
+     * that probe has not started yet and will read the rest.
+     */
+    private onDataLanded;
+    private probe;
 }