@serfab/cadre-core 0.12.0 → 1.0.0

package/src/seed-bootstrap.ts

@@ -5,6 +5,7 @@ import type { Libp2p, Connection } from '@libp2p/interface';
 import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { type ControlStream, writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
+import { dialPeerAddrs, DEFAULT_PEER_DIAL_BUDGET, type PeerDialBudget } from './peer-dial.js';
 import type {
   ControlNetworkSeed,
   SeedPeer,
@@ -19,7 +20,8 @@ import type {
   CadreInvite,
   PeerAddressRecord,
   DeviceTokenRecord,
-  RevocationRow
+  RevocationRow,
+  RevocationLedgerOpenResult
 } from './types.js';
 import type { ControlDatabase } from './control-database.js';
 import { generateStampId } from './control-database.js';
@@ -120,6 +122,22 @@ function seedRejected(error: string): ApplySeedResult {
   return { success: false, peersAdded: 0, error, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
 }
 
+/**
+ * Parse each address, dropping (and logging) any that is malformed, so one bad
+ * entry cannot keep a peer's valid addresses from being dialed.
+ */
+function parseDialAddrs(addrs: readonly string[]): Multiaddr[] {
+  const parsed: Multiaddr[] = [];
+  for (const addr of addrs) {
+    try {
+      parsed.push(multiaddr(addr));
+    } catch (error) {
+      log('Skipping malformed dial address %s: %o', addr, error);
+    }
+  }
+  return parsed;
+}
+
 /**
  * Configuration for the SeedBootstrapService
  */
@@ -183,6 +201,14 @@ export interface SeedBootstrapConfig {
    * direction than the receiver knobs above.
    */
   seedDeliverTimeoutMs?: number;
+  /**
+   * Time limits for each peer this service dials from a list of addresses —
+   * {@link SeedBootstrapService.applySeed}'s owner dials and
+   * {@link SeedBootstrapService.dialInvite} — per address and per peer (see
+   * `peer-dial.ts`). Defaults to {@link DEFAULT_PEER_DIAL_BUDGET}; a `CadreNode`
+   * passes its `network.controlCohort` limits.
+   */
+  dialBudget?: PeerDialBudget;
 }
 
 /**
@@ -220,6 +246,7 @@ export class SeedBootstrapService {
   private readonly seedReadTimeoutMs: number;
   private readonly maxConcurrentSeeds: number;
   private readonly seedDeliverTimeoutMs: number;
+  private readonly dialBudget: PeerDialBudget;
   /** In-flight inbound seed streams, used to enforce {@link maxConcurrentSeeds}. */
   private activeStreams = 0;
   private eventCallbacks: SeedEventCallbacks = {};
@@ -230,6 +257,7 @@ export class SeedBootstrapService {
     this.seedReadTimeoutMs = config.seedReadTimeoutMs ?? DEFAULT_SEED_READ_TIMEOUT_MS;
     this.maxConcurrentSeeds = config.maxConcurrentSeeds ?? DEFAULT_MAX_CONCURRENT_SEEDS;
     this.seedDeliverTimeoutMs = config.seedDeliverTimeoutMs ?? DEFAULT_SEED_DELIVER_TIMEOUT_MS;
+    this.dialBudget = config.dialBudget ?? DEFAULT_PEER_DIAL_BUDGET;
 
     // Derive public key from private key if not provided
     if (config.ownerPrivateKey && !config.ownerPublicKey) {
@@ -618,6 +646,29 @@ export class SeedBootstrapService {
     );
   }
 
+  /**
+   * Owner filing of the singleton `Revocation` ledger marker, so the table is never a
+   * never-written block that the storage layer re-consults on every read.
+   *
+   * The signature, the insert-if-absent guard and the `'already-open'` mapping are
+   * {@link ControlDatabase.openRevocationLedger}'s. What stays here is the owner-key
+   * precondition.
+   *
+   * @throws if no owner private key is configured or the control database is not
+   *   initialized.
+   */
+  async openRevocationLedger(): Promise<RevocationLedgerOpenResult> {
+    // Fail fast on a keyless service before any DB work (see removePeer): a
+    // non-owner cannot sign the marker's append digest.
+    const ownerKey = this.requireOwnerPublicKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    return this.controlDatabase.openRevocationLedger(
+      ownerKey, message => this.signMessageBytes(message),
+    );
+  }
+
   /**
    * Create a seed from the current control network state.
    * The seed contains peer information and is signed by an owner.
@@ -756,6 +807,13 @@ export class SeedBootstrapService {
     // throws, which would report a healthy owner as "seeded but stranded".
     // Optional-chained: partial libp2p handles (unit-test doubles) omit `peerId`,
     // and an undefined self simply matches nothing.
+    // Every one of an owner's addresses is a candidate, each on its own time limit
+    // (`dialPeerAddrs`), so an owner whose first address never answers neither
+    // stalls seed application nor goes undialed at its other addresses.
+    // NOTE: `handleSeedStream` acks only after this loop, so an unreachable owner
+    // can hold the ack for up to `dialBudget.totalMs` (30 s) each, past a sender's
+    // 10 s `seedDeliverTimeoutMs`; the seed is still applied. If senders start
+    // reporting accepted seeds as timed out, ack before dialing.
     const selfPeerId = this.libp2pNode.peerId?.toString();
     let ownerDialsAttempted = 0;
     let ownerDialsFailed = 0;
@@ -765,10 +823,10 @@ export class SeedBootstrapService {
       }
       ownerDialsAttempted++;
       try {
-        const addr = multiaddr(peer.multiaddrs[0]);
+        const addrs = parseDialAddrs(peer.multiaddrs);
 
-        log('Dialing owner peer: %s', peer.peerId);
-        await this.libp2pNode.dial(addr);
+        log('Dialing owner peer: %s (%d addr(s))', peer.peerId, addrs.length);
+        await dialPeerAddrs(this.libp2pNode, addrs, this.dialBudget, `Owner dial of ${peer.peerId}`);
       } catch (error) {
         ownerDialsFailed++;
         log('Failed to dial peer %s: %o', peer.peerId, error);
@@ -1133,6 +1191,13 @@ export class SeedBootstrapService {
    * 2. Creates a seed including all current peers
    * 3. Returns the seed for sending to provider API
    *
+   * Nothing here dials the drone or remembers its addresses beyond the unsigned
+   * `CadrePeer` row, which no resolver accepts. `CadreNode.addDrone` is the entry
+   * point that also retains them as a durable dial target, so the adder's
+   * reconcile pass can open the connection — the drone cannot dial an owner that
+   * does not listen. Call `CadreNode.reconcileControlCohort()` after delivering
+   * the seed to dial at once.
+   *
    * @param options - Drone peer info from provider API
    * @returns Seed and encoded seed for drone initialization
    */
@@ -1327,21 +1392,14 @@ export class SeedBootstrapService {
 
     log('Dialing invite owner with %d addresses', invite.ownerAddrs.length);
 
-    // Try each owner address until one succeeds
-    let lastError: Error | null = null;
-    for (const addrStr of invite.ownerAddrs) {
-      try {
-        const addr = multiaddr(addrStr);
-        await this.libp2pNode.dial(addr);
-        log('Connected to owner at: %s', addrStr);
-        return;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        log('Failed to dial %s: %o', addrStr, error);
-      }
+    const addrs = parseDialAddrs(invite.ownerAddrs);
+    if (addrs.length === 0) {
+      throw new Error('No owner addresses available');
     }
-
-    throw lastError ?? new Error('No owner addresses available');
+    // Each address on its own time limit, so one that never answers cannot hold
+    // the invitee back from the rest (`dialPeerAddrs`).
+    const connection = await dialPeerAddrs(this.libp2pNode, addrs, this.dialBudget, 'Invite owner dial');
+    log('Connected to owner at: %s', connection.remoteAddr.toString());
   }
 }
 

package/src/storage-scope.ts

@@ -0,0 +1,78 @@
+/**
+ * storage-scope.ts — the scope keys `CadreNodeConfig.storage.provider` is called with.
+ *
+ * A provider is a factory cadre-core invokes once per **scope**: once for the control
+ * database and once for each strand. A strand's scope key is its strand id; the control
+ * database's scope key is what this module mints.
+ *
+ * WHY THE CONTROL SCOPE CARRIES THE PARTY ID. The control database holds the party's
+ * own records — its strands, owner keys, peers, invitations, revocations. Two parties
+ * on one device must therefore not share one control store, or a node started for
+ * party B reads party A's rows as if party A had written them for B. Every other
+ * party-scoped store in this codebase already knows this: `PersistentTrustedOwnerStore`,
+ * `PersistentBootstrapPeerStore` and `PersistentEnrolledMachineStore` each take a
+ * `partyId` and fail closed on a mismatch. Putting the party id in the key here means
+ * no embedder has to know it belongs there, and none can get it wrong.
+ *
+ * WHY IT IS ENCODED. A party id is arbitrary text — nothing in cadre-core validates
+ * its shape, and the React Native reference app lets a user type one into Settings.
+ * Scope keys reach real namespaces unescaped: cadre-cli builds `${config.path}/${scope}`,
+ * React Native a LevelDB filename, the browser an IndexedDB database name. A party id
+ * containing `/` or `..` would escape the CLI's storage directory. Base64url keeps every
+ * key inside `[A-Za-z0-9._-]` — the charset embedders already rely on, and the same
+ * encoding the React Native app's `secureStoreKeySegment` uses on a party id for the
+ * same reason.
+ *
+ * THE STRAND ARM OF THAT CHARSET RULE IS NOT YET ENFORCED. The strand scope key is
+ * `StrandRow.Id`, and the ids cadre-core itself mints are `strand-<digits>-<base36>`
+ * / `strand-<hex>`, which satisfy the charset. But a strand row replicated into the
+ * control database by another node in the party carries whatever id THAT node wrote,
+ * and nothing validates its shape before `resolveStrandStorage` hands it to the
+ * provider. See `tickets/backlog/bug-strand-scope-key-charset-unenforced`.
+ */
+
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+
+/**
+ * Prefix marking a scope key as a control database rather than a strand.
+ *
+ * Not exported: `controlStorageScope` mints these keys and `isControlStorageScope`
+ * recognizes them, which is the whole surface a caller needs.
+ */
+const CONTROL_SCOPE_PREFIX = 'control-';
+
+/**
+ * The storage scope key for a party's control database.
+ *
+ * Returns `control-` followed by the base64url encoding of `partyId`'s UTF-8 bytes,
+ * so the whole key stays within `[A-Za-z0-9._-]` and is safe to use directly as a
+ * file name, directory name or database name. See the module comment for why the
+ * encoding is load-bearing rather than decorative.
+ *
+ * To read a party id back off a device — from, say, a LevelDB file named
+ * `sereus-control-MTExMTExMTEtMjIyMi00MzMzLTg0NDQtNTU1NTU1NTU1NTU1` — in a browser or
+ * Node console, with no dependency on this package:
+ * ```js
+ * const b64 = key.slice('control-'.length).replace(/-/g, '+').replace(/_/g, '/');
+ * new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
+ * ```
+ * The `TextDecoder` step is not optional: `atob` alone yields one character per BYTE,
+ * so a party id with any non-ASCII character in it decodes to mojibake.
+ */
+export function controlStorageScope(partyId: string): string {
+	return CONTROL_SCOPE_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base64url');
+}
+
+/**
+ * Whether a scope key names a control database rather than a strand.
+ *
+ * A prefix test. Safe as one against the strand ids cadre-core mints, which are
+ * `strand-`-prefixed (`strand-formation-manager.ts`, `strand-solicitation.ts`,
+ * `control-formation-recorder.ts`) and so can never collide. It is NOT a security
+ * boundary: a strand id replicated in from another node is unvalidated text that
+ * could begin `control-`, which is one more reason to close the gap the module
+ * comment names.
+ */
+export function isControlStorageScope(scope: string): boolean {
+	return scope.startsWith(CONTROL_SCOPE_PREFIX);
+}

package/src/strand-database.ts

@@ -27,11 +27,21 @@ export interface StrandDatabaseConfig {
    */
   strandType: 'o' | 'c';
   /**
-   * The closed-strand `MemberPrivateKey` (base64 protobuf) from the strand row.
-   * Required when `founder` is true and `strandType` is `'c'` — it derives the
-   * founding `Member.Key`/`Manager.MemberKey`. Absent for open strands.
+   * The closed-strand `MemberPrivateKey` (base64 protobuf) from the strand row —
+   * the strand-wide read secret every joining party receives. Carried for the
+   * strand's read-gating story only; it derives NOBODY's identity (that used to be
+   * this key's second job, which let any joiner sign as the founding manager —
+   * gotchoices/sereus#4). Absent for open strands.
    */
   memberPrivateKey?: string;
+  /**
+   * THIS party's own strand membership private key (base64 protobuf), from the
+   * control-layer `StrandPartyKey` row (or supplied explicitly at attach). Required
+   * when `founder` is true and `strandType` is `'c'` — it derives the founding
+   * `Member.Key`/`Manager.MemberKey`. Never shared outside the party; absent for
+   * open strands and for joiners that have not yet persisted one.
+   */
+  partyMemberPrivateKey?: string;
   /**
    * Whether this node founds the strand. When true, {@link initialize} runs the
    * one-time founder membership bootstrap after the schema is applied. Joiners
@@ -120,38 +130,68 @@ export class StrandDatabase {
   /**
    * Run the founder membership bootstrap against the freshly-composed strand DB.
    *
-   * Derives the founding keypair from the closed-strand `memberPrivateKey` (the
-   * `Member.Key`/`Manager.MemberKey` are its public key); a closed strand with no
-   * `memberPrivateKey` throws, because it could never seat a founding manager.
-   * Open strands derive no keypair (Header only). Idempotent — see
-   * {@link bootstrapFounderMembership}.
+   * Derives the founding keypair from this PARTY's own `partyMemberPrivateKey` (the
+   * `Member.Key`/`Manager.MemberKey` are its public key) — deliberately NOT from the
+   * strand row's shared `MemberPrivateKey`, which every joining party receives and could
+   * therefore use to forge the founder's identity. A closed strand with no
+   * `partyMemberPrivateKey` throws, because it could never seat a founding manager.
+   * The shared key's public half IS passed, but only so the bootstrap can refuse a strand
+   * founded under it before the split (`PreSplitStrandIdentityError`). Open strands derive
+   * no keypair (Header only). Idempotent — see {@link bootstrapFounderMembership}.
    */
   private async bootstrapFounder(): Promise<void> {
-    const { strandId, strandType, memberPrivateKey, sAppConfig } = this.config;
-    const founderKeyPair = strandType === 'c'
-      ? this.deriveFounderKeyPair(strandId, memberPrivateKey)
-      : undefined;
+    const { strandId, strandType, memberPrivateKey, partyMemberPrivateKey, sAppConfig } = this.config;
+    const closed = strandType === 'c';
     await bootstrapFounderMembership(this.db!, {
       strandId,
       type: strandType,
       sApp: sAppConfig,
-      founderKeyPair,
+      founderKeyPair: closed ? this.deriveFounderKeyPair(strandId, partyMemberPrivateKey) : undefined,
+      sharedMemberPublicKey: closed && memberPrivateKey
+        ? strandMemberKeyPair(memberPrivateKey).publicKeyB64
+        : undefined,
     });
   }
 
   /**
-   * Derive the founding keypair for a closed strand from its `memberPrivateKey`,
-   * failing loudly when the key is absent (a closed strand with no founding
-   * Manager can never admit anyone).
+   * Derive the founding keypair for a closed strand from the party's own
+   * `partyMemberPrivateKey`, failing loudly when the key is absent (a closed strand
+   * with no founding Manager can never admit anyone).
    */
-  private deriveFounderKeyPair(strandId: string, memberPrivateKey: string | undefined) {
-    if (!memberPrivateKey) {
+  private deriveFounderKeyPair(strandId: string, partyMemberPrivateKey: string | undefined) {
+    if (!partyMemberPrivateKey) {
       throw new Error(
-        `Cannot found closed strand ${strandId}: the strand row has no MemberPrivateKey. ` +
-        'A closed strand needs a founding Member/Manager derived from that key.',
+        `Cannot found closed strand ${strandId}: this party has no StrandPartyKey for it. ` +
+        'A closed strand needs a founding Member/Manager derived from the party\'s own ' +
+        'membership key (minted at publishStrand, or at the founder launch that follows a ' +
+        'publish interrupted before its mint) — the shared MemberPrivateKey deliberately ' +
+        'no longer derives anyone\'s identity.',
       );
     }
-    return strandMemberKeyPair(memberPrivateKey);
+    return strandMemberKeyPair(partyMemberPrivateKey);
+  }
+
+  /**
+   * Run the founder membership bootstrap against an ALREADY-LIVE database — the
+   * seam {@link StrandInstanceManager.foundExistingStrand} uses when a founder
+   * request arrives for an instance that was first launched as a joiner.
+   * Idempotent: every bootstrap write is insert-if-absent
+   * ({@link bootstrapFounderMembership}), so calling it on an instance that
+   * already founded writes nothing. On success also flips the captured config's
+   * `founder`, so this object's own record of how it was launched stays coherent
+   * with what actually ran (a construction-time `founder: false` is a statement
+   * about the launch, not a permanent identity); a refused bootstrap leaves it a joiner.
+   *
+   * @param partyMemberPrivateKey - The party's own membership key, for a closed strand
+   *   whose original (joiner) launch resolved none — e.g. the `StrandPartyKey` row had
+   *   not been written or replicated yet. The captured config's key wins when both
+   *   exist: it is the identity this instance launched under.
+   */
+  async ensureFounderBootstrap(partyMemberPrivateKey?: string): Promise<void> {
+    this.ensureInitialized();
+    this.config.partyMemberPrivateKey ??= partyMemberPrivateKey;
+    await this.bootstrapFounder();
+    this.config.founder = true;
   }
 
   /**

package/src/strand-first-sync-gate.ts

@@ -0,0 +1,258 @@
+/**
+ * The first-sync write gate for a JOINING machine.
+ *
+ * A machine that has never received anything from another member of a strand must not
+ * commit to it. With no strand peer connected, Optimystic's cohort for every block is the
+ * machine itself, so the first write to a table finds no collection locally and INVENTS
+ * one — exactly what a founder writing alone legitimately does. When the connection comes
+ * up, two independently created histories share one collection id: Optimystic keeps one and
+ * drops the other's commits, or never reconciles them at all. The joiner's own rows silently
+ * vanish (`joining-machine-writes-before-first-sync-fork-tables`). Optimystic cannot tell a
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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`).
+ *
+ * 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
+ * hash-named blocks, measured 2026-09-16) alone, during `connectToStrand`'s schema apply,
+ * before any peer contact. That is the same "two histories under one id" shape this gate
+ * exists to prevent, and it is only safe because both sides derive byte-identical content
+ * from the same schema text. If the catalog ever carries per-machine or ordering-dependent
+ * content (optimystic's own `0.5-same-named-tables-in-two-schemas-share-storage` re-keys
+ * 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 debug from 'debug';
+import type { Database } from '@quereus/quereus';
+import type { StrandDatabase } from './strand-database.js';
+import { defaultTimeoutScheduler, type TimeoutScheduler } from './timeout-scheduler.js';
+
+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}. Measured: over a direct connection the
+ * joiner reads the founder's rows about 1.3 s after `addStrand` would previously have
+ * resolved; a relayed path is slower, and a phone that just redeemed an invitation has the
+ * host reachable moments ago, so 30 s is generous without leaving an app hanging.
+ */
+export const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 30_000;
+
+/** 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
+   * {@link DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS}.
+   */
+  timeoutMs?: number;
+  /** Probe cadence while gated. Default {@link DEFAULT_STRAND_FIRST_SYNC_POLL_MS}. */
+  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.
+ */
+export class StrandAwaitingFirstSyncError extends Error {
+  readonly strandId: string;
+  readonly waitedMs: number;
+
+  constructor(strandId: string, waitedMs: number) {
+    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."
+    );
+    this.name = 'StrandAwaitingFirstSyncError';
+    this.strandId = strandId;
+    this.waitedMs = waitedMs;
+  }
+}
+
+/**
+ * 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 async function strandHeaderHeld(db: Database, label: string): Promise<boolean> {
+  try {
+    for await (const row of db.eval('select count(1) as Count from Strand.Header')) {
+      return ((row.Count as number) ?? 0) > 0;
+    }
+    return false;
+  } catch (error) {
+    log('[%s] Header probe failed (treated as not yet held): %s', label,
+      error instanceof Error ? error.message : String(error));
+    return false;
+  }
+}
+
+/** The tables the sApp declared in the `App` schema, by name; views excluded. */
+function appTableNames(db: Database): string[] {
+  const app = db.schemaManager.getSchema('App');
+  return app ? Array.from(app.getAllTables()).filter((table) => !table.isView).map((table) => table.name) : [];
+}
+
+/**
+ * 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 async function appTablesReadable(db: Database, label: string): Promise<boolean> {
+  for (const table of appTableNames(db)) {
+    try {
+      for await (const _row of db.eval(`select count(1) as Count from App."${table}"`)) {
+        break;
+      }
+    } catch (error) {
+      log('[%s] App.%s probe failed (treated as not yet synced): %s', label, table,
+        error instanceof Error ? error.message : String(error));
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * 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 async function strandFirstSyncComplete(db: Database, label: string): Promise<boolean> {
+  return await strandHeaderHeld(db, label) && await appTablesReadable(db, label);
+}
+
+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. */
+  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.
+   */
+  onHeaderHeld: () => void;
+  /** Timer seam for the probe loop; 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.
+ */
+export class StrandFirstSyncGate {
+  private readonly scheduler: TimeoutScheduler;
+  private readonly pollIntervalMs: number;
+  private timer: unknown;
+  private stopped = false;
+  private opened = false;
+  private probing = false;
+
+  constructor(private readonly deps: StrandFirstSyncGateDeps, config?: StrandFirstSyncConfig) {
+    this.scheduler = deps.scheduler ?? defaultTimeoutScheduler;
+    this.pollIntervalMs = config?.pollIntervalMs ?? DEFAULT_STRAND_FIRST_SYNC_POLL_MS;
+  }
+
+  /** The database this gate is holding back. */
+  get database(): StrandDatabase {
+    return this.deps.database;
+  }
+
+  /** True once the Header was seen (or the gate was force-opened); the loop is then done. */
+  get isOpen(): boolean {
+    return this.opened;
+  }
+
+  /** Arm the probe loop. The first probe runs after one interval — the caller already probed once. */
+  start(): void {
+    if (this.stopped || this.opened || this.timer !== undefined) return;
+    this.schedule();
+    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(): void {
+    if (this.opened) return;
+    this.opened = true;
+    this.stop();
+    log('[%s] first-sync gate opened by the caller (Header written locally)', this.deps.label);
+  }
+
+  /** Disarm the loop; a probe already in flight completes and is then ignored. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer !== undefined) {
+      this.scheduler.clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private schedule(): void {
+    this.timer = this.scheduler.setTimeout(() => {
+      this.timer = undefined;
+      void this.probe();
+    }, this.pollIntervalMs);
+  }
+
+  private async probe(): Promise<void> {
+    if (this.stopped || this.opened || this.probing) return;
+    this.probing = true;
+    const held = await strandFirstSyncComplete(this.deps.database.getDatabase(), this.deps.label)
+      .finally(() => { this.probing = false; });
+    // Re-check after the await: a release or a force-open may have landed mid-read.
+    if (this.stopped || this.opened) return;
+    if (!held) {
+      this.schedule();
+      return;
+    }
+    this.opened = true;
+    this.stop();
+    log('[%s] first-sync gate opened: Strand.Header and every App table read from a peer', this.deps.label);
+    this.deps.onHeaderHeld();
+  }
+}