@serfab/cadre-core 0.7.1 → 0.8.1

package/src/strand-database.ts

@@ -1,33 +1,17 @@
 import debug from 'debug';
-import { Database, registerPlugin } from '@quereus/quereus';
-import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
-import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
+import { Database } from '@quereus/quereus';
+import { 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 { IRawStorage } from '@optimystic/db-p2p';
 import type { SAppConfig, StrandMode } from './types.js';
+import { bootstrapFounderMembership } from './strand-membership-writer.js';
+import { strandMemberKeyPair } from './strand-member-key.js';
 
 const log = debug('sereus:cadre:strand-db');
 const timing = debug('sereus:cadre:timing');
 
-/**
- * Minimal interface for the CollectionFactory returned by the optimystic plugin.
- * We only need the methods we actually use.
- */
-interface CollectionFactory {
-  registerLibp2pNode(networkName: string, node: Libp2p, coordinatedRepo: IRepo): void;
-  shutdown(): Promise<void>;
-}
-
-/** Result of registering the optimystic plugin */
-interface OptimysticPluginResult {
-  collectionFactory: CollectionFactory;
-  vtables: Array<{ name: string; module: unknown; auxData: unknown }>;
-  functions: Array<{ schema: unknown }>;
-  hydrate: (db: Database) => Promise<{ tables: number; indexes: number }>;
-  [key: string]: unknown;
-}
-
 export interface StrandDatabaseConfig {
   /** The strand ID */
   strandId: string;
@@ -51,15 +35,43 @@ export interface StrandDatabaseConfig {
    * across the two consumers.
    */
   rawStorage?: IRawStorage;
+  /**
+   * 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`+`Authority`.
+   */
+  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`/`Authority.MemberKey`. Absent for open strands.
+   */
+  memberPrivateKey?: 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;
 }
 
 /**
- * StrandDatabase manages the sApp schema for a strand using Quereus with Optimystic backend.
- * Each strand instance has its own isolated database with the sApp's schema applied.
+ * 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` never *creates* the node;
+ * `StrandInstanceManager` owns the node lifecycle. (The strand connection's
+ * `shutdown` still stops the injected node via the collection factory, so the
+ * manager's own `node.stop()` is an idempotent second stop — see `close()`.)
  */
 export class StrandDatabase {
   private db: Database | null = null;
-  private collectionFactory: CollectionFactory | null = null;
+  private shutdownStrand: SereusPluginResult['shutdown'] | null = null;
   private readonly config: StrandDatabaseConfig;
   private initialized = false;
 
@@ -68,7 +80,9 @@ export class StrandDatabase {
   }
 
   /**
-   * Initialize the database - register plugins and execute sApp schema
+   * 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) {
@@ -76,127 +90,83 @@ export class StrandDatabase {
       return;
     }
 
-    log('Initializing StrandDatabase for strand: %s (sApp: %s v%s)',
-      this.config.strandId,
-      this.config.sAppConfig.id,
-      this.config.sAppConfig.version
-    );
-
-    // Create database instance
-    this.db = new Database();
     const sid = this.config.strandId;
-
-    // Register crypto plugin (provides digest, sign, verify functions)
-    let t0 = performance.now();
-    await registerPlugin(this.db, cryptoPlugin);
-    timing('[strandDb:%s] cryptoPlugin: %dms', sid, Math.round(performance.now() - t0));
-    log('Registered crypto plugin');
-
-    // Register optimystic plugin. In `bootstrap` mode we route through the
-    // local transactor so a solo node can initialize (schema apply etc.)
-    // without network round trips. In `networked` mode the network transactor
-    // is used. Mode is fixed for the lifetime of this Database instance; the
-    // caller must restart the strand to transition modes.
-    t0 = performance.now();
-    const networkName = `strand-${sid}`;
     const mode: StrandMode = this.config.mode ?? 'networked';
-    const defaultTransactor = mode === 'bootstrap' ? 'local' : 'network';
-    // In bootstrap mode the local transactor IS the data path. Hand the plugin
-    // the strand's raw storage (same instance the libp2p node uses) so writes
-    // persist to the host backend instead of in-memory storage.
-    const rawStorage = this.config.rawStorage;
-    const pluginConfig: Record<string, unknown> = {
-      default_transactor: defaultTransactor,
-      default_key_network: 'libp2p',
-      default_network_name: networkName,
-      enable_cache: true,
-    };
-    if (mode === 'bootstrap' && rawStorage) {
-      pluginConfig.rawStorageFactory = () => rawStorage;
-    }
-    // The plugin's published signature is `Record<string, SqlValue>` but it
-    // also reads `rawStorageFactory` (a function reference) from the same map.
-    // Cast through unknown rather than widen the public type.
-    const pluginResult = optimysticPlugin(
-      this.db,
-      pluginConfig as unknown as Parameters<typeof optimysticPlugin>[1]
-    ) as OptimysticPluginResult;
-    log('Optimystic plugin registered for strand %s (mode=%s, transactor=%s, persistentStorage=%s)',
-      sid, mode, defaultTransactor, mode === 'bootstrap' && !!rawStorage);
+    log('Initializing StrandDatabase for strand: %s (sApp: %s v%s, mode=%s)',
+      sid, this.config.sAppConfig.id, this.config.sAppConfig.version, mode);
 
-    // Register vtables and functions manually since we need access to collectionFactory
-    for (const vtable of pluginResult.vtables as Array<{ name: string; module: unknown; auxData: unknown }>) {
-      this.db.registerModule(vtable.name, vtable.module as any, vtable.auxData);
-    }
-    for (const func of pluginResult.functions as Array<{ schema: unknown }>) {
-      this.db.registerFunction(func.schema as any);
-    }
-    timing('[strandDb:%s] optimysticPlugin: %dms', sid, Math.round(performance.now() - t0));
-
-    this.collectionFactory = pluginResult.collectionFactory;
-
-    // Inject the libp2p node into the collection factory
-    t0 = performance.now();
-    this.collectionFactory.registerLibp2pNode(
-      networkName,
-      this.config.libp2pNode,
-      this.config.coordinatedRepo
-    );
-    timing('[strandDb:%s] registerLibp2pNode: %dms', sid, Math.round(performance.now() - t0));
-    log('Registered libp2p node with collection factory');
+    this.db = new Database();
 
-    // Set optimystic as the default virtual table module so that
-    // `declare schema` tables (which omit USING) are backed by optimystic
-    // instead of the built-in memory module.
-    t0 = performance.now();
-    this.db.setDefaultVtabName('optimystic');
-    this.db.setDefaultVtabArgs({
-      networkName,
-      transactor: defaultTransactor,
-      keyNetwork: 'libp2p',
+    // Delegate to the shared composition. The node is injected, so:
+    //  - `connectToStrand` never creates a node (its `createdNode` stays null);
+    //    `StrandInstanceManager` owns the node lifecycle. Its `shutdown` does
+    //    still stop the injected node via the collection factory, so the
+    //    manager's later `node.stop()` is an idempotent second stop;
+    //  - `storage` (the strand's raw storage, same instance the node uses) is
+    //    handed to the plugin's local transactor in bootstrap mode so DML lands
+    //    on the host backend rather than in-memory.
+    const t0 = performance.now();
+    const result = await connectToStrand(this.db, {
+      strandId: sid,
+      schema: this.config.sAppConfig.schema,
+      mode,
+      storage: this.config.rawStorage,
+      libp2pNode: this.config.libp2pNode,
+      coordinatedRepo: this.config.coordinatedRepo,
+      enableCache: true,
     });
-    timing('[strandDb:%s] setDefaultVtab: %dms', sid, Math.round(performance.now() - t0));
-    log('Set default vtab to optimystic (networkName=%s, transactor=%s)', networkName, defaultTransactor);
-
-    // Hydrate Quereus's catalog from any persisted optimystic vtab schemas
-    // before running `apply schema App;`. Without this, a warm restart diffs
-    // the wrapped DDL against an empty catalog and re-emits CREATE TABLE /
-    // CREATE INDEX for every persisted object — which round-trips through
-    // optimystic storage and is the cause of the ~160s warm-start regression
-    // tracked in strand-database-must-hydrate-catalog-before-apply-schema.
-    // No-op on first launch (empty storage).
-    t0 = performance.now();
-    const hydrated = await pluginResult.hydrate(this.db);
-    timing('[strandDb:%s] hydrate: %dms (tables=%d, indexes=%d)',
-      sid, Math.round(performance.now() - t0), hydrated.tables, hydrated.indexes);
-    log('Hydrated catalog for strand %s (tables=%d, indexes=%d)',
-      sid, hydrated.tables, hydrated.indexes);
-
-    // Execute the sApp schema DDL
-    t0 = performance.now();
-    await this.executeSchema();
-    timing('[strandDb:%s] executeSchema: %dms', sid, Math.round(performance.now() - t0));
+    this.shutdownStrand = result.shutdown;
+    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() so buildStrandRuntime's rollback tears the half-built strand
+    // down rather than leaking a node. 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 async executeSchema(): Promise<void> {
-    const rawSchema = this.config.sAppConfig.schema;
-    log('Applying sApp schema for strand %s', this.config.strandId);
-
-    // Wrap the raw schema DDL in a declarative schema block and apply it.
-    // This ensures proper schema management with diff/apply semantics.
-    // The schema is applied to a named schema 'App' to keep it isolated.
-    const wrappedSchema = `
-      declare schema App {
-        ${rawSchema}
-      }
-      apply schema App;
-    `;
+  /**
+   * Run the founder membership bootstrap against the freshly-composed strand DB.
+   *
+   * Derives the founding keypair from the closed-strand `memberPrivateKey` (the
+   * `Member.Key`/`Authority.MemberKey` are its public key); a closed strand with no
+   * `memberPrivateKey` throws, because it could never seat a founding authority.
+   * 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;
+    await bootstrapFounderMembership(this.db!, {
+      strandId,
+      type: strandType,
+      sApp: sAppConfig,
+      founderKeyPair,
+    });
+  }
 
-    await this.db!.exec(wrappedSchema);
-    log('sApp schema applied to strand %s', this.config.strandId);
+  /**
+   * Derive the founding keypair for a closed strand from its `memberPrivateKey`,
+   * failing loudly when the key is absent (a closed strand with no founding
+   * Authority can never admit anyone).
+   */
+  private deriveFounderKeyPair(strandId: string, memberPrivateKey: string | undefined) {
+    if (!memberPrivateKey) {
+      throw new Error(
+        `Cannot found closed strand ${strandId}: the strand row has no MemberPrivateKey. ` +
+        'A closed strand needs a founding Member/Authority derived from that key.',
+      );
+    }
+    return strandMemberKeyPair(memberPrivateKey);
   }
 
   /**
@@ -208,15 +178,18 @@ export class StrandDatabase {
   }
 
   /**
-   * Close the database and cleanup resources
+   * Close the database and cleanup resources. Runs the strand-connection
+   * shutdown (collection-factory teardown, which also stops the injected node),
+   * then closes the `Database`. `StrandInstanceManager.releaseRuntime` issues a
+   * further idempotent `node.stop()` after this returns.
    */
   async close(): Promise<void> {
-    if (this.collectionFactory) {
-      await this.collectionFactory.shutdown();
-      this.collectionFactory = null;
+    if (this.shutdownStrand) {
+      await this.shutdownStrand();
+      this.shutdownStrand = null;
     }
     if (this.db) {
-      this.db.close();
+      void this.db.close();
       this.db = null;
     }
     this.initialized = false;
@@ -229,4 +202,3 @@ export class StrandDatabase {
     }
   }
 }
-