@serfab/cadre-core 1.13.0 → 1.15.0

package/src/strand-commit-durability.ts

@@ -0,0 +1,116 @@
+import debug from 'debug';
+import { durabilityRank } from '@optimystic/db-core';
+import type { WriteDurability } from '@optimystic/db-core';
+import type { CommitFullyHeld, SqlCommitDurability } from '@serfab/quereus-plugin-sereus';
+
+const log = debug('sereus:cadre:strand-commit-durability');
+
+/** What one commit on a strand wrote, and whether it survives this machine stopping for good. */
+export interface StrandCommitDurability {
+  readonly strandId: string;
+  /** `StampId()` inside the committed transaction. */
+  readonly transactionId: string;
+  /**
+   * Another member holds every block the commit wrote: the overall answer is `majority` or `full`
+   * and no block was abandoned (`torn`). False for `local`, `unrouted`, an unknown overall, or a
+   * torn commit. Becomes true once `strand:commit-held` fires for the commit.
+   */
+  readonly heldElsewhere: boolean;
+  /**
+   * When {@link heldElsewhere} is false: `strand:commit-held` will fire for this commit if it
+   * reaches the others while this database stays open. False means nothing will say so.
+   */
+  readonly followed: boolean;
+  /** The plugin's report, for per-table detail. */
+  readonly report: SqlCommitDurability;
+}
+
+/** A commit that was held only below full replication is now held by every member of its cohort. */
+export interface StrandCommitHeld {
+  readonly strandId: string;
+  readonly transactionId: string;
+}
+
+/** Where a strand database forwards each commit's durability and each held commit. */
+export interface StrandCommitListeners {
+  onCommitDurability?: (commit: StrandCommitDurability) => void;
+  onCommitHeld?: (event: StrandCommitHeld) => void;
+}
+
+// NOTE: if an app reads a commit's durability later than 256 commits after it, raise this or let
+// the app pass the id up front.
+const RECENT_COMMIT_LIMIT = 256;
+
+/**
+ * `majority` counts: a strict majority of a cohort of at least two is at least two machines, so
+ * the write survives this one stopping. A torn commit does not, though it can succeed as `majority`
+ * (Optimystic clamps a torn `full` to it): its abandoned blocks are held by nobody. The one place
+ * this rule lives; apps read the field.
+ */
+function isHeldElsewhere(overall: WriteDurability | undefined): boolean {
+  return overall !== undefined
+    && durabilityRank(overall.quorum) >= durabilityRank('majority')
+    && (overall.torn?.length ?? 0) === 0;
+}
+
+/**
+ * The durability of the most recent commits on one strand database, by transaction id. The
+ * plugin reports a commit — and a `covered` commit is held — before the statement that made it
+ * resolves, so an app that learns its id from `returning StampId()` reads the answer from here
+ * afterwards. Each entry is frozen and replaced when the commit becomes held, so a value read
+ * from {@link get} never changes under its reader.
+ */
+export class StrandCommitRecord {
+  private readonly commits = new Map<string, StrandCommitDurability>();
+
+  constructor(
+    private readonly strandId: string,
+    private readonly listeners: StrandCommitListeners
+  ) {}
+
+  get(transactionId: string): StrandCommitDurability | undefined {
+    return this.commits.get(transactionId);
+  }
+
+  /** A plugin `onCommitDurability` report: record it, then forward it. */
+  reportCommit(report: SqlCommitDurability): void {
+    const commit = Object.freeze({
+      strandId: this.strandId,
+      transactionId: report.transactionId,
+      heldElsewhere: isHeldElsewhere(report.durability.overall),
+      followed: report.followed,
+      report
+    });
+    this.remember(commit);
+    this.forward('durability', report.transactionId, () => this.listeners.onCommitDurability?.(commit));
+  }
+
+  /** A plugin `onCommitFullyHeld` event: mark the commit held, then forward it — also for one no longer recorded. */
+  reportHeld({ transactionId }: CommitFullyHeld): void {
+    const recorded = this.commits.get(transactionId);
+    if (recorded) {
+      this.commits.set(transactionId, Object.freeze({ ...recorded, heldElsewhere: true }));
+    }
+    this.forward('held', transactionId, () => this.listeners.onCommitHeld?.({ strandId: this.strandId, transactionId }));
+  }
+
+  private remember(commit: StrandCommitDurability): void {
+    this.commits.set(commit.transactionId, commit);
+    if (this.commits.size > RECENT_COMMIT_LIMIT) {
+      const oldest = this.commits.keys().next().value!;
+      this.commits.delete(oldest);
+    }
+  }
+
+  /**
+   * Run an app's handler isolated: it runs inside the commit, and a throw reaching the plugin
+   * would be logged there as the plugin's own listener failing.
+   */
+  private forward(kind: string, transactionId: string, deliver: () => void): void {
+    try {
+      deliver();
+    } catch (error) {
+      log('strand %s: %s handler threw for transaction %s: %O', this.strandId, kind, transactionId, error);
+    }
+  }
+}

package/src/strand-database.ts

@@ -7,11 +7,13 @@ 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';
 
 const log = debug('sereus:cadre:strand-db');
 const timing = debug('sereus:cadre:timing');
 
-export interface StrandDatabaseConfig {
+export interface StrandDatabaseConfig extends StrandCommitListeners {
   /** The strand ID */
   strandId: string;
   /**
@@ -63,10 +65,12 @@ export interface StrandDatabaseConfig {
  * 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()`.)
+ * 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;
@@ -74,9 +78,12 @@ export class StrandDatabase {
   private resolvedTransactor: SereusPluginResult['transactor'] | null = null;
   private readonly config: StrandDatabaseConfig;
   private initialized = false;
+  private readonly commits: StrandCommitRecord;
+  private unsubscribeCommits: (() => void) | null = null;
 
   constructor(config: StrandDatabaseConfig) {
     this.config = config;
+    this.commits = new StrandCommitRecord(config.strandId, config);
   }
 
   /**
@@ -103,10 +110,8 @@ export class StrandDatabase {
     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;
+    //  - `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.
@@ -126,14 +131,16 @@ export class StrandDatabase {
     });
     this.shutdownStrand = result.shutdown;
     this.resolvedTransactor = result.transactor;
+    // 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() so buildStrandRuntime's rollback tears the half-built strand
-    // down rather than leaking a node. Joiners skip this — their rows arrive via sync.
+    // 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();
     }
@@ -142,6 +149,15 @@ export class StrandDatabase {
     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.
    *
@@ -247,6 +263,19 @@ export class StrandDatabase {
     return this.db!;
   }
 
+  /**
+   * 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
@@ -261,11 +290,14 @@ export class StrandDatabase {
 
   /**
    * 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.
+   * 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.
+    this.unsubscribeCommits?.();
+    this.unsubscribeCommits = null;
     if (this.shutdownStrand) {
       await this.shutdownStrand();
       this.shutdownStrand = null;

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

@@ -55,7 +55,7 @@
  * seed 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. (One with a seed cannot until a seed peer answers — Optimystic refuses the
- * absence ruling — and is rebuilt on a timer by `StrandInstanceManager.deferUnreachableJoin`.) That is the same "two histories under one id" shape this gate
+ * absence ruling — and retries its database build on a timer, `StrandInstanceManager.deferUnreachableJoin`.) 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
@@ -294,6 +294,12 @@ export interface StrandFirstSyncGateDeps {
  * 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.
+ *
+ * NOTE: a probe's reads dial the founder, through the relay when that is the only route, even
+ * while the founder is unreachable: one run of `joiner-first-commit-over-slow-relay` logged 17
+ * `hop connect denied` at the relay in about 10 s, each a few frames on the joiner's relay
+ * connection. If that connection ever shows saturated while no strand member is connected, hold
+ * the probe while the strand member redial (`strand-peer-redial.ts`) reports none connected.
  */
 export class StrandFirstSyncGate {
   private readonly scheduler: TimeoutScheduler;