@serfab/cadre-core 0.7.1 → 0.9.0

package/dist/strand-database.js

@@ -1,122 +1,107 @@
 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 { 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');
 /**
- * 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 {
     constructor(config) {
         this.db = null;
-        this.collectionFactory = null;
+        this.shutdownStrand = null;
         this.initialized = false;
         this.config = config;
     }
     /**
-     * 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() {
         if (this.initialized) {
             log('StrandDatabase for strand %s already initialized', this.config.strandId);
             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 = 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 = {
-            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);
-        log('Optimystic plugin registered for strand %s (mode=%s, transactor=%s, persistentStorage=%s)', sid, mode, defaultTransactor, mode === 'bootstrap' && !!rawStorage);
-        // Register vtables and functions manually since we need access to collectionFactory
-        for (const vtable of pluginResult.vtables) {
-            this.db.registerModule(vtable.name, vtable.module, vtable.auxData);
-        }
-        for (const func of pluginResult.functions) {
-            this.db.registerFunction(func.schema);
-        }
-        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');
-        // 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',
+        log('Initializing StrandDatabase for strand: %s (sApp: %s v%s, mode=%s)', sid, this.config.sAppConfig.id, this.config.sAppConfig.version, mode);
+        this.db = new Database();
+        // 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);
     }
-    async executeSchema() {
-        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;
-    `;
-        await this.db.exec(wrappedSchema);
-        log('sApp schema applied to strand %s', this.config.strandId);
+    /**
+     * 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}.
+     */
+    async bootstrapFounder() {
+        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,
+        });
+    }
+    /**
+     * 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).
+     */
+    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.');
+        }
+        return strandMemberKeyPair(memberPrivateKey);
     }
     /**
      * Get the underlying database for queries
@@ -126,15 +111,18 @@ export class StrandDatabase {
         return this.db;
     }
     /**
-     * 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() {
-        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;

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-formation-manager.d.ts

@@ -1,6 +1,6 @@
 import type { Libp2p } from '@libp2p/interface';
 import type { OpenInvitation, FormStrandResult, StrandFormationDisclosure } from './types.js';
-import type { DisclosureValidator, FormationUsageRecorder, StrandProvisioner } from './strand-solicitation.js';
+import type { DisclosureValidator, FormationUsageRecorder, StrandProvisioner, FormationResponseValidator } from './strand-solicitation.js';
 /**
  * Configuration for StrandFormationManager
  */
@@ -20,12 +20,14 @@ export interface StrandFormationManagerConfig {
  * Options for creating a StrandFormationManager
  */
 export interface StrandFormationManagerOptions {
-    /** Validates disclosures from initiators */
+    /** Validates disclosures from initiators (responder side) */
     disclosureValidator?: DisclosureValidator;
-    /** Records and validates token usage */
+    /** Records and validates token usage (responder side) */
     formationUsageRecorder?: FormationUsageRecorder;
-    /** Provisions strands after validation */
+    /** Provisions strands after validation (responder side) */
     strandProvisioner?: StrandProvisioner;
+    /** Validates the responder's result (initiator side); defaults to a structural check */
+    formationResponseValidator?: FormationResponseValidator;
     /** This party's ID for identification */
     partyId: string;
     /** This party's cadre peer addresses */
@@ -34,22 +36,29 @@ export interface StrandFormationManagerOptions {
     config?: StrandFormationManagerConfig;
 }
 /**
- * StrandFormationManager bridges cadre-core's strand solicitation interfaces
- * with strand-proto's SessionManager for actual protocol handling over libp2p.
+ * StrandFormationManager drives the native cadre-core formation transport
+ * (`strand-formation-protocol.ts`) from cadre-core's strand-solicitation interfaces.
  *
- * It implements SessionHooks by delegating to the existing interfaces:
- * - DisclosureValidator -> validateIdentity
- * - FormationUsageRecorder -> validateToken
- * - StrandProvisioner -> provisionStrand
+ * Responder side: a {@link FormationListener} wires the inbound protocol to
+ * {@link FormationUsageRecorder} (token), {@link DisclosureValidator} (identity),
+ * and {@link StrandProvisioner} (provisioning), disclosing this party's real
+ * identity + cadre only after validation.
+ *
+ * Initiator side: {@link formStrand} dials the responder carrying the real
+ * disclosure/token/cadre, then validates the responder's result via the
+ * {@link FormationResponseValidator} (or a built-in structural check).
  */
 export declare class StrandFormationManager {
-    private readonly sessionManager;
     private readonly disclosureValidator?;
     private readonly formationUsageRecorder?;
     private readonly strandProvisioner?;
+    private readonly formationResponseValidator?;
     private readonly partyId;
     private readonly cadrePeerAddrs;
-    private registeredNodes;
+    private readonly config;
+    private readonly listener;
+    private readonly registeredNodes;
+    private dialerSessions;
     constructor(options: StrandFormationManagerOptions);
     /**
      * Register this manager as a protocol handler on a libp2p node.
@@ -61,12 +70,11 @@ export declare class StrandFormationManager {
      */
     unregisterResponder(node: Libp2p, protocolId?: string): void;
     /**
-     * Form a strand with a responder via an open invitation.
+     * Form a strand with a responder via an open invitation (initiator side).
      *
-     * This is the initiator-side operation. It:
-     * 1. Converts the OpenInvitation to a BootstrapLink
-     * 2. Calls SessionManager.initiateBootstrap()
-     * 3. Returns the result as a FormStrandResult
+     * Builds a contact message carrying the real token + disclosure + this party's
+     * real cadre addresses, dials the responder over the native protocol, and
+     * validates the responder's result before returning.
      */
     formStrand(invitation: OpenInvitation, disclosure: StrandFormationDisclosure, node: Libp2p): Promise<FormStrandResult>;
     /**
@@ -76,10 +84,62 @@ export declare class StrandFormationManager {
         listeners: number;
         dialers: number;
     };
+    private validateToken;
+    private validateDisclosure;
+    /**
+     * Responder-side provisioning. Routes on how the invite resolves
+     * ({@link ResolvedHostStrand}), and can REJECT post-validation by returning a
+     * {@link ResponderProvisionOutcome} with `approved: false` — `runSession` turns that
+     * into a clean, non-disclosing reply instead of a dropped result frame.
+     *
+     * - **bound** (host strand present): provision-then-record — write the single
+     *   `FormationUsage` consent row against the pre-existing strand (record-only) and
+     *   return it + its membership key (a read-gating secret disclosed only here, behind the
+     *   token + disclosure validation `runSession` already enforced).
+     * - **missing** (invite names a host strand absent on this responder, e.g. unconverged):
+     *   reject cleanly + retryably, writing NO usage row — recording usage here would fail the
+     *   deferred `StrandExists` CHECK at commit and drop the frame.
+     * - **unbound** (no binding): the responder-provisions fallback — see {@link provisionUnbound}.
+     *
+     * Defense-in-depth: known provisioning/redeem failures (notably the concurrent
+     * `(Token, UseNumber)` PK collision when two redemptions of one unbound single-use invite
+     * race) are caught and mapped to a logged, retry-suggesting rejection rather than a thrown
+     * insert + a silently-closed stream. The LOG-before-reject keeps this a deliberate
+     * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
+     * not control-flow-by-exception.
+     */
+    private provisionAsResponder;
+    /**
+     * Responder-provisions fallback (invite binds no host strand). Precedence:
+     *
+     * 1. `recorder.provisionAndRecord` present (a real DB recorder) → atomic create-strand +
+     *    record-consent, so the unbound redemption is single-use just like the bound path.
+     *    Returns the new strand (+ key, null for an open responder-provisioned strand).
+     * 2. else `strandProvisioner` present → the legacy/mock contract: provision a bare strand,
+     *    NO inline usage write (those callers record usage explicitly via
+     *    `recordFormationComplete`, or assert transport invariants only). Threads the invite's
+     *    REAL `sAppId`.
+     * 3. else → a structural placeholder (no recorder + no provisioner ⇒ no single-use semantics
+     *    exist to enforce).
+     *
+     * Plan tradeoff — option (a) "record usage on the fallback" over (b) "remove the fallback":
+     * (a) closes the single-use hole with a targeted atomic create+record and leaves the
+     * `StrandProvisioner` mock-transport tests untouched; (b) would delete the provisioner
+     * surface and churn ~6 unit + ~6 integration sites for ZERO production benefit (production
+     * — `cadre-web.ts` / `cadre-phone.ts` — always publishes strand-BOUND invites and treats
+     * the responder-provisions placeholder as failure). The broader "should this fallback exist
+     * at all?" question lives in backlog `formation-initiatorcreates-cover-or-remove`.
+     */
+    private provisionUnbound;
+    /** Wrap a provision result as an approving {@link ResponderProvisionOutcome}. */
+    private approve;
     /**
-     * Create SessionHooks that delegate to our interfaces
+     * The invite's authoritative `sAppId` for the responder-provisions fallback, read back
+     * from the recorder's `isTokenValid` invitation (the real `FormationInvite.sAppId`).
+     * Empty string when no recorder is wired or the invitation omits it.
      */
-    private createSessionHooks;
+    private resolveInviteSAppId;
+    private validateResponse;
 }
 /**
  * Create a StrandFormationManager with the given options