@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/storage-scope.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 declare function controlStorageScope(partyId: string): string;
+/**
+ * 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 declare function isControlStorageScope(scope: string): boolean;

package/dist/storage-scope.js

@@ -0,0 +1,75 @@
+/**
+ * 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) {
+    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) {
+    return scope.startsWith(CONTROL_SCOPE_PREFIX);
+}
+//# sourceMappingURL=storage-scope.js.map

package/dist/storage-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-scope.js","sourceRoot":"","sources":["../src/storage-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,UAAU,IAAI,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IAClD,OAAO,oBAAoB,GAAG,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC;AACtG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,KAAK,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;AAC/C,CAAC"}

package/dist/strand-database.d.ts

@@ -19,11 +19,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
@@ -61,19 +71,39 @@ export declare 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 bootstrapFounder;
     /**
-     * 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;
+    /**
+     * 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.
+     */
+    ensureFounderBootstrap(partyMemberPrivateKey?: string): Promise<void>;
     /**
      * Get the underlying database for queries
      */

package/dist/strand-database.js

@@ -73,35 +73,65 @@ 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}.
      */
     async bootstrapFounder() {
-        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).
      */
-    deriveFounderKeyPair(strandId, memberPrivateKey) {
-        if (!memberPrivateKey) {
-            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.');
+    deriveFounderKeyPair(strandId, partyMemberPrivateKey) {
+        if (!partyMemberPrivateKey) {
+            throw new Error(`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) {
+        var _a;
+        this.ensureInitialized();
+        (_a = this.config).partyMemberPrivateKey ?? (_a.partyMemberPrivateKey = partyMemberPrivateKey);
+        await this.bootstrapFounder();
+        this.config.founder = true;
     }
     /**
      * Get the underlying database for queries

package/dist/strand-database.js.map

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

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

@@ -0,0 +1,152 @@
+/**
+ * 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 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 `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 declare const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 30000;
+/** 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 declare class StrandAwaitingFirstSyncError extends Error {
+    readonly strandId: string;
+    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. */
+    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 declare class StrandFirstSyncGate {
+    private readonly deps;
+    private readonly scheduler;
+    private readonly pollIntervalMs;
+    private timer;
+    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. */
+    get isOpen(): boolean;
+    /** 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(): void;
+    /** Disarm the loop; a probe already in flight completes and is then ignored. */
+    stop(): void;
+    private schedule;
+    private probe;
+}