@serfab/cadre-core 1.19.0 → 1.19.1

package/src/strand-database.ts

@@ -1,352 +1,466 @@
-import debug from 'debug';
-import { Database } from '@quereus/quereus';
-import { applyAppSchema, connectToStrand } from '@serfab/quereus-plugin-sereus';
-import type { SereusPluginResult } from '@serfab/quereus-plugin-sereus';
-import type { Libp2p } from '@libp2p/interface';
-import type { IRepo } from '@optimystic/db-core';
-import type { SAppConfig } from './types.js';
-import { bootstrapFounderMembership } from './strand-membership-writer.js';
-import { strandMemberKeyPair } from './strand-member-key.js';
-import { StrandCommitRecord } from './strand-commit-durability.js';
-import type { StrandCommitDurability, StrandCommitListeners } from './strand-commit-durability.js';
-import { TableWatchRegistry } from './table-change-watch.js';
-import type { TableChangeWatch, TableChangeWatchOptions } from './table-change-watch.js';
-
-const log = debug('sereus:cadre:strand-db');
-const timing = debug('sereus:cadre:timing');
-
-export interface StrandDatabaseConfig extends StrandCommitListeners {
-  /** The strand ID */
-  strandId: string;
-  /**
-   * sApp configuration containing the schema. Absent for a storage replica — a strand
-   * this node stores and serves without the app installed: only the `Strand` membership
-   * schema is applied, and such a database can never found (see {@link founderSApp}).
-   */
-  sAppConfig?: SAppConfig;
-  /** Libp2p node for the strand network */
-  libp2pNode: Libp2p;
-  /** Coordinated repo from the libp2p node */
-  coordinatedRepo: IRepo;
-  /**
-   * Strand type (`'o'` open / `'c'` closed) from the control-network strand row.
-   * Drives the founder bootstrap: open strands get a `Header` only; closed strands
-   * also get the founding `Member`+`Manager`.
-   */
-  strandType: 'o' | 'c';
-  /**
-   * 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
-   * leave this false and write nothing (rows arrive via sync). Defaults to false.
-   */
-  founder?: boolean;
-  /**
-   * Whether a closed strand's founder bootstrap also writes this machine's `Strand.MemberPeer`
-   * binding (for `libp2pNode`'s peer id) in the founding transaction. That binding is the
-   * membership reconciler's job; the founding run that seats the founding `Member` writes it
-   * too, which saves the reconciler's commit. False whenever the reconciler is disarmed, so a
-   * fixture that hand-drives the membership writers sees only the rows it wrote. Defaults to false.
-   */
-  bindFounderPeer?: boolean;
-}
-
-/**
- * StrandDatabase manages the sApp schema for a strand using Quereus with the
- * Optimystic backend. Each strand instance has its own isolated database with
- * the sApp's schema applied.
- *
- * This class owns the `Database` lifecycle (creation, `getDatabase()`, `close()`)
- * but delegates the actual SQL-surface composition — plugin registration, node
- * wiring, catalog hydration, schema apply — to `connectToStrand` from
- * `@serfab/quereus-plugin-sereus`, the single shared composition. The libp2p
- * node is injected here, so `connectToStrand` neither creates nor stops it:
- * `StrandInstanceManager` owns the node lifecycle, and a failed or closed
- * database leaves the node running.
- *
- * One instance is one attempt: a failed {@link initialize} is closed and a new
- * instance built for the next attempt.
- */
-export class StrandDatabase {
-  private db: Database | null = null;
-  private shutdownStrand: SereusPluginResult['shutdown'] | null = null;
-  private resolvedTransactor: SereusPluginResult['transactor'] | null = null;
-  private createEmptyCollections: SereusPluginResult['createEmptyCollections'] | null = null;
-  private readonly config: StrandDatabaseConfig;
-  private initialized = false;
-  private readonly commits: StrandCommitRecord;
-  private unsubscribeCommits: (() => void) | null = null;
-  /** Subscriptions handed out by {@link watchTables}. */
-  private readonly tableWatches = new TableWatchRegistry();
-
-  constructor(config: StrandDatabaseConfig) {
-    this.config = config;
-    this.commits = new StrandCommitRecord(config.strandId, config);
-  }
-
-  /**
-   * Initialize the database — create the `Database` and delegate the strand
-   * SQL-surface composition (plugins, node wiring, hydrate, schema apply) to
-   * `connectToStrand` with the injected libp2p node.
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) {
-      log('StrandDatabase for strand %s already initialized', this.config.strandId);
-      return;
-    }
-
-    const sid = this.config.strandId;
-    const { sAppConfig } = this.config;
-    if (this.config.founder === true) {
-      // Before composing anything: a founder that cannot write its Header must not
-      // leave a half-built connection behind.
-      this.founderSApp();
-    }
-    log('Initializing StrandDatabase for strand: %s (%s)', sid,
-      sAppConfig ? `sApp: ${sAppConfig.id} v${sAppConfig.version}` : 'storage replica');
-
-    this.db = new Database();
-
-    // Delegate to the shared composition. The node is injected, so:
-    //  - `connectToStrand` never creates or stops a node; `StrandInstanceManager`
-    //    owns the node lifecycle;
-    //  - no `storage` is passed: the plugin consumes it only to build a local
-    //    transactor's raw-storage factory or to create a node it was not given,
-    //    and cadre-core always injects the node and runs the network transactor.
-    //    (The plugin keeps its `storage` option for the browser entry point.)
-    const t0 = performance.now();
-    //
-    // A storage replica passes no schema, so no `App` tables are declared. A warm restart's
-    // hydrate may still load `App` table definitions persisted in the replicated store into
-    // the catalog — declarative metadata, nothing the app supplied runs — and the first-sync
-    // probe then reads those tables once from blocks this node holds.
-    const result = await connectToStrand(this.db, {
-      strandId: sid,
-      schema: sAppConfig?.schema,
-      libp2pNode: this.config.libp2pNode,
-      coordinatedRepo: this.config.coordinatedRepo,
-      enableCache: true,
-    });
-    this.shutdownStrand = result.shutdown;
-    this.resolvedTransactor = result.transactor;
-    this.createEmptyCollections = result.createEmptyCollections;
-    // Before the founder bootstrap, so its commits are reported like any other.
-    this.subscribeToCommits(result);
-    timing('[strandDb:%s] connectToStrand: %dms (hydrated tables=%d, indexes=%d)',
-      sid, Math.round(performance.now() - t0),
-      result.hydrated?.tables ?? 0, result.hydrated?.indexes ?? 0);
-
-    // Founder-only: write the one-time membership bootstrap now that the schema is
-    // applied (connectToStrand has returned). A throw here propagates out of
-    // initialize(), and the caller closes this half-built database (close() runs the
-    // composition's shutdown). Joiners skip this — their rows arrive via sync.
-    if (this.config.founder === true) {
-      await this.bootstrapFounder();
-    }
-
-    this.initialized = true;
-    log('StrandDatabase for strand %s initialized successfully', sid);
-  }
-
-  private subscribeToCommits(result: SereusPluginResult): void {
-    const unsubscribeDurability = result.onCommitDurability(report => this.commits.reportCommit(report));
-    const unsubscribeHeld = result.onCommitFullyHeld(event => this.commits.reportHeld(event));
-    this.unsubscribeCommits = () => {
-      unsubscribeDurability();
-      unsubscribeHeld();
-    };
-  }
-
-  /**
-   * Run the founder membership bootstrap against the freshly-composed strand DB.
-   *
-   * 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`). The strand node's
-   * peer id is passed under {@link StrandDatabaseConfig.bindFounderPeer}: the same node, so
-   * the same id, the membership reconciler binds. Open strands derive no keypair (Header
-   * only). Idempotent — see {@link bootstrapFounderMembership}.
-   */
-  private async bootstrapFounder(): Promise<void> {
-    const { strandId, strandType, memberPrivateKey, partyMemberPrivateKey, libp2pNode, bindFounderPeer } = this.config;
-    const closed = strandType === 'c';
-    await bootstrapFounderMembership(this.db!, {
-      strandId,
-      type: strandType,
-      sApp: this.founderSApp(),
-      founderKeyPair: closed ? this.deriveFounderKeyPair(strandId, partyMemberPrivateKey) : undefined,
-      sharedMemberPublicKey: closed && memberPrivateKey
-        ? strandMemberKeyPair(memberPrivateKey).publicKeyB64
-        : undefined,
-      founderPeerId: closed && bindFounderPeer === true ? libp2pNode.peerId.toString() : undefined,
-      createEmptyCollections: this.createEmptyCollections!,
-    });
-  }
-
-  /**
-   * The sApp a founder bootstrap records in the `Strand.Header`. Throws for a storage
-   * replica (no sApp config): its Header's sApp columns would have nothing to say.
-   * `CadreNode` always launches a replica as a joiner, so this guards a future caller.
-   */
-  private founderSApp(): SAppConfig {
-    const { sAppConfig, strandId } = this.config;
-    if (!sAppConfig) {
-      throw new Error(
-        `Cannot found strand ${strandId} as a storage replica: the founder bootstrap writes ` +
-        'the sApp id and version into Strand.Header, and a replica has no sApp config.',
-      );
-    }
-    return sAppConfig;
-  }
-
-  /**
-   * 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, partyMemberPrivateKey: string | undefined) {
-    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 when the strand is published, or at the founder launch for ' +
-        'a closed row stored without one) — the shared MemberPrivateKey deliberately ' +
-        'no longer derives anyone\'s identity.',
-      );
-    }
-    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;
-  }
-
-  /**
-   * Give a live storage replica the app's schema: apply `App` to the already-composed
-   * database — same libp2p node, same store, so the new tables read the blocks this node
-   * already holds — and record the sApp, so a later {@link ensureFounderBootstrap} has it
-   * for the `Header`. Idempotent: the apply is a declarative diff, so re-applying the same
-   * schema emits nothing. A failed apply records nothing.
-   */
-  async attachAppSchema(sAppConfig: SAppConfig): Promise<void> {
-    this.ensureInitialized();
-    await applyAppSchema(this.db!, sAppConfig.schema);
-    this.config.sAppConfig = sAppConfig;
-    log('StrandDatabase for strand %s attached sApp %s v%s', this.config.strandId, sAppConfig.id, sAppConfig.version);
-  }
-
-  /**
-   * Get the underlying database for queries
-   */
-  getDatabase(): Database {
-    this.ensureInitialized();
-    return this.db!;
-  }
-
-  /**
-   * Subscribe `onChange` to changes in this strand's tables (`'Strand.Member'`, …): commits
-   * made here and changes replicated into this node's storage alike, on the single-flight
-   * schedule `table-change-watch.ts` describes. {@link close} disposes every subscription
-   * still live; a hibernated strand's database is closed and rebuilt on wake, so a consumer
-   * subscribes again on the new instance.
-   */
-  watchTables(tables: readonly string[], onChange: () => Promise<void>, options: TableChangeWatchOptions): TableChangeWatch {
-    this.ensureInitialized();
-    return this.tableWatches.watch(this.db!, tables, onChange, options);
-  }
-
-  /**
-   * The durability of a recent commit on this database, by its `StampId()` — the id a single
-   * `insert … returning StampId() as Tx` statement returns. Read it after that statement
-   * resolves: the plugin reports the commit before the statement returns, and a commit already
-   * held everywhere is marked held by then too. `undefined` for a commit that wrote nothing, one
-   * made before this database was built, or one more than 256 commits back. Each value is a
-   * snapshot: read again after `strand:commit-held` to see the change.
-   */
-  commitDurability(transactionId: string): StrandCommitDurability | undefined {
-    this.ensureInitialized();
-    return this.commits.get(transactionId);
-  }
-
-  /**
-   * The Optimystic transactor this strand's connection resolved to — always
-   * `'network'` here, since cadre-core passes no `transactor` option and takes
-   * the plugin's default. Exposed so a spec measuring or asserting the network
-   * path (`strand-solo-write-budget.spec.ts`) can pin the engine it ran on
-   * rather than assume it.
-   */
-  getTransactor(): SereusPluginResult['transactor'] {
-    this.ensureInitialized();
-    return this.resolvedTransactor!;
-  }
-
-  /**
-   * Close the database and cleanup resources. Runs the strand-connection
-   * shutdown (collection-factory teardown; the injected node keeps running),
-   * then closes the `Database`. Safe on an instance whose {@link initialize}
-   * failed part-way.
-   */
-  async close(): Promise<void> {
-    // First, so an event from the closing connection reaches no app handler or table watch.
-    this.unsubscribeCommits?.();
-    this.unsubscribeCommits = null;
-    this.tableWatches.disposeAll();
-    if (this.shutdownStrand) {
-      await this.shutdownStrand();
-      this.shutdownStrand = null;
-    }
-    // Again: a subscription taken during the await above would keep its timers past close.
-    this.tableWatches.disposeAll();
-    if (this.db) {
-      void this.db.close();
-      this.db = null;
-    }
-    this.resolvedTransactor = null;
-    this.initialized = false;
-    log('StrandDatabase for strand %s closed', this.config.strandId);
-  }
-
-  private ensureInitialized(): void {
-    if (!this.initialized || !this.db) {
-      throw new Error(`StrandDatabase for strand ${this.config.strandId} not initialized. Call initialize() first.`);
-    }
-  }
-}
+import debug from 'debug';
+import { Database } from '@quereus/quereus';
+import { applyAppSchema, connectToStrand } from '@serfab/quereus-plugin-sereus';
+import type { SereusPluginResult, StrandOfflineController } from '@serfab/quereus-plugin-sereus';
+import type { Libp2p } from '@libp2p/interface';
+import type { IRepo } from '@optimystic/db-core';
+import type { IKVStore } from '@optimystic/db-p2p';
+import type { SAppConfig } from './types.js';
+import { bootstrapFounderMembership } from './strand-membership-writer.js';
+import { strandMemberKeyPair } from './strand-member-key.js';
+import { StrandCommitRecord } from './strand-commit-durability.js';
+import type { StrandCommitDurability, StrandCommitListeners } from './strand-commit-durability.js';
+import { TableWatchRegistry } from './table-change-watch.js';
+import type { TableChangeWatch, TableChangeWatchOptions } from './table-change-watch.js';
+import { discardQueued, StrandOfflineReport } from './strand-offline.js';
+import type { StrandAppSchemaState, StrandOfflineListeners, StrandOfflineMode, StrandOfflineQueue } from './strand-offline.js';
+
+const log = debug('sereus:cadre:strand-db');
+const timing = debug('sereus:cadre:timing');
+
+export interface StrandDatabaseConfig extends StrandCommitListeners {
+  /** The strand ID */
+  strandId: string;
+  /**
+   * sApp configuration containing the schema. Absent for a storage replica — a strand
+   * this node stores and serves without the app installed: only the `Strand` membership
+   * schema is applied, and such a database can never found (see {@link founderSApp}).
+   */
+  sAppConfig?: SAppConfig;
+  /** Libp2p node for the strand network */
+  libp2pNode: Libp2p;
+  /** Coordinated repo from the libp2p node */
+  coordinatedRepo: IRepo;
+  /**
+   * Strand type (`'o'` open / `'c'` closed) from the control-network strand row.
+   * Drives the founder bootstrap: open strands get a `Header` only; closed strands
+   * also get the founding `Member`+`Manager`.
+   */
+  strandType: 'o' | 'c';
+  /**
+   * 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
+   * leave this false and write nothing (rows arrive via sync). Defaults to false.
+   */
+  founder?: boolean;
+  /**
+   * Whether a closed strand's founder bootstrap also writes this machine's `Strand.MemberPeer`
+   * binding (for `libp2pNode`'s peer id) in the founding transaction. That binding is the
+   * membership reconciler's job; the founding run that seats the founding `Member` writes it
+   * too, which saves the reconciler's commit. False whenever the reconciler is disarmed, so a
+   * fixture that hand-drives the membership writers sees only the rows it wrote. Defaults to false.
+   */
+  bindFounderPeer?: boolean;
+  /**
+   * Turn on the connection's offline queue (docs/strands.md → "Offline mode"). Absent: no queue,
+   * and {@link StrandDatabase.offline} is undefined.
+   */
+  offline?: StrandDatabaseOffline;
+}
+
+/** {@link StrandDatabaseConfig.offline}: one build's journal, the strand's mode, and where to report. */
+export interface StrandDatabaseOffline extends StrandOfflineListeners {
+  /**
+   * This build's journal, resolved by {@link StrandDatabase.initialize}, so a launch released while
+   * it resolves is caught like one released during the rest of the build. A throw fails initialize.
+   */
+  journal: () => IKVStore | Promise<IKVStore>;
+  /**
+   * The strand's mode, read at the end of {@link StrandDatabase.initialize} and at every
+   * {@link StrandDatabase.applyOfflineMode}, never captured, so the newest choice wins.
+   */
+  mode: () => StrandOfflineMode;
+}
+
+/**
+ * StrandDatabase manages the sApp schema for a strand using Quereus with the
+ * Optimystic backend. Each strand instance has its own isolated database with
+ * the sApp's schema applied.
+ *
+ * This class owns the `Database` lifecycle (creation, `getDatabase()`, `close()`)
+ * but delegates the actual SQL-surface composition — plugin registration, node
+ * wiring, catalog hydration, schema apply — to `connectToStrand` from
+ * `@serfab/quereus-plugin-sereus`, the single shared composition. The libp2p
+ * node is injected here, so `connectToStrand` neither creates nor stops it:
+ * `StrandInstanceManager` owns the node lifecycle, and a failed or closed
+ * database leaves the node running.
+ *
+ * One instance is one attempt: a failed {@link initialize} is closed and a new
+ * instance built for the next attempt.
+ */
+export class StrandDatabase {
+  private db: Database | null = null;
+  private shutdownStrand: SereusPluginResult['shutdown'] | null = null;
+  private resolvedTransactor: SereusPluginResult['transactor'] | null = null;
+  private createEmptyCollections: SereusPluginResult['createEmptyCollections'] | null = null;
+  private readonly config: StrandDatabaseConfig;
+  private initialized = false;
+  private readonly commits: StrandCommitRecord;
+  private unsubscribeCommits: (() => void) | null = null;
+  private offlineQueue: StrandOfflineController | null = null;
+  private offlineReport: StrandOfflineReport | null = null;
+  /** Subscriptions handed out by {@link watchTables}. */
+  private readonly tableWatches = new TableWatchRegistry();
+
+  constructor(config: StrandDatabaseConfig) {
+    this.config = config;
+    this.commits = new StrandCommitRecord(config.strandId, config);
+  }
+
+  /**
+   * Initialize the database — create the `Database` and delegate the strand
+   * SQL-surface composition (plugins, node wiring, hydrate, schema apply) to
+   * `connectToStrand` with the injected libp2p node.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      log('StrandDatabase for strand %s already initialized', this.config.strandId);
+      return;
+    }
+
+    const sid = this.config.strandId;
+    const { sAppConfig } = this.config;
+    if (this.config.founder === true) {
+      // Before composing anything: a founder that cannot write its Header must not
+      // leave a half-built connection behind.
+      this.founderSApp();
+    }
+    log('Initializing StrandDatabase for strand: %s (%s)', sid,
+      sAppConfig ? `sApp: ${sAppConfig.id} v${sAppConfig.version}` : 'storage replica');
+
+    const offline = this.config.offline && { journal: await this.config.offline.journal() };
+    this.db = new Database();
+
+    // Delegate to the shared composition. The node is injected, so:
+    //  - `connectToStrand` never creates or stops a node; `StrandInstanceManager`
+    //    owns the node lifecycle;
+    //  - no `storage` is passed: the plugin consumes it only to build a local
+    //    transactor's raw-storage factory or to create a node it was not given,
+    //    and cadre-core always injects the node and runs the network transactor.
+    //    (The plugin keeps its `storage` option for the browser entry point.)
+    const t0 = performance.now();
+    //
+    // A storage replica passes no schema, so no `App` tables are declared. A warm restart's
+    // hydrate may still load `App` table definitions persisted in the replicated store into
+    // the catalog — declarative metadata, nothing the app supplied runs — and the first-sync
+    // probe then reads those tables once from blocks this node holds.
+    const result = await connectToStrand(this.db, {
+      strandId: sid,
+      schema: sAppConfig?.schema,
+      libp2pNode: this.config.libp2pNode,
+      coordinatedRepo: this.config.coordinatedRepo,
+      enableCache: true,
+      offline,
+    });
+    this.shutdownStrand = result.shutdown;
+    this.resolvedTransactor = result.transactor;
+    this.createEmptyCollections = result.createEmptyCollections;
+    // Before the founder bootstrap, so its commits are reported like any other.
+    this.subscribeToCommits(result);
+    this.followOffline(result);
+    timing('[strandDb:%s] connectToStrand: %dms (hydrated tables=%d, indexes=%d)',
+      sid, Math.round(performance.now() - t0),
+      result.hydrated?.tables ?? 0, result.hydrated?.indexes ?? 0);
+
+    // Founder-only: write the one-time membership bootstrap now that the schema is
+    // applied (connectToStrand has returned). A throw here propagates out of
+    // initialize(), and the caller closes this half-built database (close() runs the
+    // composition's shutdown). Joiners skip this — their rows arrive via sync.
+    // NOTE: a bootstrap with rows to write while `hydrate` restored queued transactions is refused
+    // (`StrandOfflineQueueBusyError`), failing every build, so that queue could never drain. Not
+    // reachable today: rows are written only while the founding is incomplete (Member empty, or no
+    // Manager and none retired), and an incomplete founding fails the build before the database is
+    // ever published for the app to queue in. If a founder is ever published with its founding
+    // incomplete, skip the bootstrap here while the queue is non-empty and run it once the queue drains.
+    if (this.config.founder === true) {
+      await this.bootstrapFounder();
+    }
+
+    // After `hydrate` restored the queue and after the founder bootstrap (its `Strand` writes are
+    // network-acknowledged in either mode); before the first-sync probe, so in offline mode a read
+    // the cohort cannot answer is served from this machine's copy there as it is to the app.
+    this.applyOfflineMode();
+    this.initialized = true;
+    log('StrandDatabase for strand %s initialized successfully', sid);
+  }
+
+  private subscribeToCommits(result: SereusPluginResult): void {
+    const unsubscribeDurability = result.onCommitDurability(report => this.commits.reportCommit(report));
+    const unsubscribeHeld = result.onCommitFullyHeld(event => this.commits.reportHeld(event));
+    this.unsubscribeCommits = () => {
+      unsubscribeDurability();
+      unsubscribeHeld();
+    };
+  }
+
+  private followOffline(result: SereusPluginResult): void {
+    const { offline } = this.config;
+    if (!offline) {
+      return;
+    }
+    this.offlineQueue = result.offline ?? null;
+    this.offlineReport = new StrandOfflineReport(this.config.strandId, offline, result);
+  }
+
+  /**
+   * Put the queue in the strand's current mode ({@link StrandDatabaseOffline.mode}). It sets the
+   * acknowledgement of transactions begun from now on; an open one keeps the one it began with.
+   * No-op without a queue, and before {@link initialize} has composed one (it applies the mode itself).
+   */
+  applyOfflineMode(): void {
+    const queue = this.offlineQueue;
+    if (!queue || !this.config.offline) {
+      return;
+    }
+    if (this.config.offline.mode() === 'offline') {
+      queue.enter();
+    } else {
+      queue.exit();
+    }
+  }
+
+  /**
+   * The database was handed to the app (`StrandInstanceManager.publishDatabase`): report the
+   * queue's state, since restored transactions' `queued` statuses were delivered before anything
+   * subscribed, and an `App` schema apply still waiting for the queue.
+   */
+  reportPublished(): void {
+    this.offlineReport?.published();
+  }
+
+  /**
+   * Run the founder membership bootstrap against the freshly-composed strand DB.
+   *
+   * 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`). The strand node's
+   * peer id is passed under {@link StrandDatabaseConfig.bindFounderPeer}: the same node, so
+   * the same id, the membership reconciler binds. Open strands derive no keypair (Header
+   * only). Idempotent — see {@link bootstrapFounderMembership}.
+   */
+  private async bootstrapFounder(): Promise<void> {
+    const { strandId, strandType, memberPrivateKey, partyMemberPrivateKey, libp2pNode, bindFounderPeer } = this.config;
+    const closed = strandType === 'c';
+    await bootstrapFounderMembership(this.db!, {
+      strandId,
+      type: strandType,
+      sApp: this.founderSApp(),
+      founderKeyPair: closed ? this.deriveFounderKeyPair(strandId, partyMemberPrivateKey) : undefined,
+      sharedMemberPublicKey: closed && memberPrivateKey
+        ? strandMemberKeyPair(memberPrivateKey).publicKeyB64
+        : undefined,
+      founderPeerId: closed && bindFounderPeer === true ? libp2pNode.peerId.toString() : undefined,
+      createEmptyCollections: this.createEmptyCollections!,
+    });
+  }
+
+  /**
+   * The sApp a founder bootstrap records in the `Strand.Header`. Throws for a storage
+   * replica (no sApp config): its Header's sApp columns would have nothing to say.
+   * `CadreNode` always launches a replica as a joiner, so this guards a future caller.
+   */
+  private founderSApp(): SAppConfig {
+    const { sAppConfig, strandId } = this.config;
+    if (!sAppConfig) {
+      throw new Error(
+        `Cannot found strand ${strandId} as a storage replica: the founder bootstrap writes ` +
+        'the sApp id and version into Strand.Header, and a replica has no sApp config.',
+      );
+    }
+    return sAppConfig;
+  }
+
+  /**
+   * 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, partyMemberPrivateKey: string | undefined) {
+    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 when the strand is published, or at the founder launch for ' +
+        'a closed row stored without one) — the shared MemberPrivateKey deliberately ' +
+        'no longer derives anyone\'s identity.',
+      );
+    }
+    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;
+  }
+
+  /**
+   * Give a live storage replica the app's schema: apply `App` to the already-composed
+   * database — same libp2p node, same store, so the new tables read the blocks this node
+   * already holds — and record the sApp, so a later {@link ensureFounderBootstrap} has it
+   * for the `Header`. Idempotent: the apply is a declarative diff, so re-applying the same
+   * schema emits nothing. A failed apply records nothing.
+   */
+  async attachAppSchema(sAppConfig: SAppConfig): Promise<void> {
+    this.ensureInitialized();
+    // NOTE: unlike the connect-time apply (`applyAppSchemaAfterQueue`), this is not deferred behind
+    // the offline queue: a replica writes no app transactions, so no queued transaction wrote an
+    // `App` table and `QueuedEntriesBlockSchemaChangeError` cannot refuse it. If a replica ever
+    // writes app rows offline, route this through the deferral instead of throwing.
+    await applyAppSchema(this.db!, sAppConfig.schema);
+    this.config.sAppConfig = sAppConfig;
+    log('StrandDatabase for strand %s attached sApp %s v%s', this.config.strandId, sAppConfig.id, sAppConfig.version);
+  }
+
+  /**
+   * Get the underlying database for queries
+   */
+  getDatabase(): Database {
+    this.ensureInitialized();
+    return this.db!;
+  }
+
+  /**
+   * Subscribe `onChange` to changes in this strand's tables (`'Strand.Member'`, …): commits
+   * made here and changes replicated into this node's storage alike, on the single-flight
+   * schedule `table-change-watch.ts` describes. {@link close} disposes every subscription
+   * still live; a hibernated strand's database is closed and rebuilt on wake, so a consumer
+   * subscribes again on the new instance.
+   */
+  watchTables(tables: readonly string[], onChange: () => Promise<void>, options: TableChangeWatchOptions): TableChangeWatch {
+    this.ensureInitialized();
+    return this.tableWatches.watch(this.db!, tables, onChange, options);
+  }
+
+  /**
+   * The durability of a recent commit on this database, by its `StampId()` — the id a single
+   * `insert … returning StampId() as Tx` statement returns. Read it after that statement
+   * resolves: the plugin reports the commit before the statement returns, and a commit already
+   * held everywhere is marked held by then too. `undefined` for a commit that wrote nothing, one
+   * made before this database was built, or one more than 256 commits back. Each value is a
+   * snapshot: read again after `strand:commit-held` to see the change.
+   */
+  commitDurability(transactionId: string): StrandCommitDurability | undefined {
+    this.ensureInitialized();
+    return this.commits.get(transactionId);
+  }
+
+  /**
+   * The strand connection's offline queue (docs/strands.md → "Offline mode"), or `undefined` on a
+   * node without `strandOffline`. The mode is set through `CadreNode.setStrandOfflineMode`, which
+   * outlives this database; listeners taken here die with it, as {@link watchTables} subscriptions do.
+   */
+  get offline(): StrandOfflineQueue | undefined {
+    this.ensureInitialized();
+    return this.offlineQueue ?? undefined;
+  }
+
+  /**
+   * Whether this database runs the `App` schema its launch was given. `'waiting-for-queue'` while
+   * queued transactions hold the apply back, so `StrandInstance.sAppInfo` names a version whose new
+   * tables or columns are not here yet; check this before relying on them.
+   */
+  appSchemaState(): StrandAppSchemaState {
+    this.ensureInitialized();
+    return this.offlineReport?.appSchemaState() ?? 'applied';
+  }
+
+  /**
+   * The transaction ids the offline queue lists (`entries()`, the ones a restore has not put back
+   * yet included), or `undefined` with no queue: none configured, not composed yet, or closed.
+   * Unlike {@link offline} it does not require {@link initialize} to have finished, so the manager
+   * can read a database still being built or about to close.
+   */
+  queuedTransactionIds(): readonly string[] | undefined {
+    return this.offlineQueue?.entries().map((entry) => entry.transactionId);
+  }
+
+  /** {@link discardQueued} on this database's queue; `undefined` with no queue, as {@link queuedTransactionIds}. */
+  discardQueuedTransactions(): readonly string[] | undefined {
+    return this.offlineQueue ? discardQueued(this.offlineQueue) : undefined;
+  }
+
+  /**
+   * The Optimystic transactor this strand's connection resolved to — always
+   * `'network'` here, since cadre-core passes no `transactor` option and takes
+   * the plugin's default. Exposed so a spec measuring or asserting the network
+   * path (`strand-solo-write-budget.spec.ts`) can pin the engine it ran on
+   * rather than assume it.
+   */
+  getTransactor(): SereusPluginResult['transactor'] {
+    this.ensureInitialized();
+    return this.resolvedTransactor!;
+  }
+
+  /**
+   * Close the database and cleanup resources. Runs the strand-connection
+   * shutdown (collection-factory teardown; the injected node keeps running),
+   * then closes the `Database`. Safe on an instance whose {@link initialize}
+   * failed part-way.
+   */
+  async close(): Promise<void> {
+    // First, so an event from the closing connection reaches no app handler or table watch.
+    this.unsubscribeCommits?.();
+    this.unsubscribeCommits = null;
+    this.offlineReport?.release();
+    this.offlineReport = null;
+    this.offlineQueue = null;
+    this.tableWatches.disposeAll();
+    if (this.shutdownStrand) {
+      await this.shutdownStrand();
+      this.shutdownStrand = null;
+    }
+    // Again: a subscription taken during the await above would keep its timers past close.
+    this.tableWatches.disposeAll();
+    if (this.db) {
+      void this.db.close();
+      this.db = null;
+    }
+    this.resolvedTransactor = null;
+    this.initialized = false;
+    log('StrandDatabase for strand %s closed', this.config.strandId);
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized || !this.db) {
+      throw new Error(`StrandDatabase for strand ${this.config.strandId} not initialized. Call initialize() first.`);
+    }
+  }
+}