@serfab/cadre-core 0.8.1 → 0.10.0

package/src/strand-instance-manager.ts

@@ -2,6 +2,7 @@ import debug from 'debug';
 import type { PrivateKey } from '@libp2p/interface';
 import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
 import { StrandDatabase } from './strand-database.js';
+import { StrandBackfill, type StrandBackfillConfig } from './strand-backfill.js';
 import { assertSchemaSignature } from './schema-verification.js';
 import type {
   StrandInstance,
@@ -16,6 +17,8 @@ import type {
   StrandMode,
   Libp2pNodeWithRepo
 } from './types.js';
+import { resolveStrandClusterSize, STRAND_CLUSTER_POLICY } from './types.js';
+import { resolveListenAddrs } from './relay-addrs.js';
 
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
@@ -48,11 +51,30 @@ export interface StartStrandConfig {
   requireSignedSchemas?: boolean;
   /**
    * Whether this node founds the strand (vs. joins it). Forwarded to the
-   * StrandDatabase so the founder bootstrap (Header, founding Member/Authority)
+   * StrandDatabase so the founder bootstrap (Header, founding Member/Manager)
    * runs once at bring-up. Joiners leave this unset and write nothing. See
    * {@link StrandConfig.founder}.
    */
   founder?: boolean;
+  /**
+   * Number of nodes Optimystic is told this strand's replication cluster should
+   * have. Same rule as {@link CadreNodeConfig.strandClusterSize}, which CadreNode
+   * forwards here: every node on the strand should use the same value, and it is
+   * frozen when the strand's libp2p node is created. Defaults to
+   * `DEFAULT_STRAND_CLUSTER_SIZE` (4); values below `MIN_CLUSTER_SIZE` (2) are
+   * rejected by `resolveStrandClusterSize`. Strand-only — the
+   * control network's breadth is the fixed `CONTROL_REPLICATION_BREADTH`.
+   */
+  clusterSize?: number;
+  /**
+   * Tuning for the strand peer-join block catch-up ({@link StrandBackfill}),
+   * forwarded from {@link CadreNodeConfig.strandBackfill}. When the strand's
+   * libp2p node connects to a peer this runtime has not yet caught up, every
+   * block in the strand's own raw store is pushed to it. Runs only on
+   * `networked` strands with per-strand storage; `{ enabled: false }` restores
+   * the pre-existing no-backfill behaviour.
+   */
+  backfill?: StrandBackfillConfig;
 }
 
 /**
@@ -132,6 +154,15 @@ export class StrandInstanceManager {
    * without the caller re-threading storage/network/profile/key/sApp config.
    */
   private launchConfigs: Map<string, StartStrandConfig> = new Map();
+  /**
+   * The per-strand peer-join block catch-up, keyed by strand id. Private (not on
+   * the public {@link StrandInstance}) because it is runtime plumbing with the
+   * same lifetime as the strand's libp2p node: created in `buildStrandRuntime`,
+   * stopped and dropped in `releaseRuntime` — so quiesce → resume rebuilds it
+   * with a fresh caught-up-peer memo, which is intended (a resumed node may have
+   * missed writes).
+   */
+  private backfills: Map<string, StrandBackfill> = new Map();
   private stopping = false;
 
   constructor() {
@@ -160,7 +191,16 @@ export class StrandInstanceManager {
   }
 
   /**
-   * Start a new strand instance
+   * Start a new strand instance.
+   *
+   * A failed launch leaves NOTHING tracked: the instance and its retained launch
+   * config are both dropped before the error is rethrown, so the strand id is
+   * free for a genuine retry. This matches the pre-registration failure path
+   * (a rejected schema signature, which throws before anything is recorded) —
+   * both failure modes of this call leave the same residue: none. Callers learn
+   * of the failure from the rejected promise (and, on the control-discovered
+   * path, from CadreNode's `strand:error` event), not from an error record left
+   * behind in `instances`.
    */
   async startStrand(config: StartStrandConfig): Promise<StrandInstance> {
     const { strandRow, sAppConfig } = config;
@@ -201,7 +241,10 @@ export class StrandInstanceManager {
       memberPrivateKey: strandRow.MemberPrivateKey ?? undefined,
       connectedPeers: 0,
       lastActivity: new Date(),
-      latencyHint
+      latencyHint,
+      // Seed only — buildStrandRuntime overwrites this with the same resolution,
+      // so an instance that errors mid-build still reads sensibly.
+      mode: config.mode ?? 'networked'
     };
 
     this.instances.set(strandId, instance);
@@ -213,9 +256,15 @@ export class StrandInstanceManager {
       log('Strand %s started successfully with sApp %s', strandId, sAppConfig.id);
       return instance;
     } catch (error) {
+      // Status/error first — the (now discarded) record is still what `log` reports on.
       instance.status = 'error';
       instance.error = error instanceof Error ? error.message : String(error);
       log('Failed to start strand %s: %s', strandId, instance.error);
+      // Drop the dead record so this strand id can be launched again. Keep the
+      // `launchConfigs` has an entry iff `instances` does invariant — resumeStrand
+      // reads both, and a config without an instance would strand the config.
+      this.instances.delete(strandId);
+      this.launchConfigs.delete(strandId);
       throw error;
     }
   }
@@ -231,6 +280,7 @@ export class StrandInstanceManager {
   private async buildStrandRuntime(instance: StrandInstance, config: StartStrandConfig): Promise<void> {
     const strandId = instance.strandId;
     const { sAppConfig } = config;
+    const mode = config.mode ?? 'networked';
 
     // Resolve storage for this strand. If a factory function is provided, it is
     // called with the strandId to create strand-specific storage (e.g.,
@@ -240,43 +290,60 @@ export class StrandInstanceManager {
       log('Strand %s using provided storage provider', strandId);
     }
 
-    // Note: protocolPrefix would be used by libp2p services, but createLibp2pNode
-    // may not support it yet - tracked for future implementation.
-    const _protocolPrefix = `/sereus/strand/${strandId}`;
+    // db-p2p namespaces every one of the node's protocol ids by network name
+    // (`/optimystic/<networkName>/...`), so anything dialing this node's own
+    // services must derive its prefix from the SAME string the node was built
+    // with — hence one binding for both, not two literals that can drift.
+    const networkName = `strand-${strandId}`;
+    const protocolPrefix = `/optimystic/${networkName}`;
 
     // Determine relay mode: if explicitly set in config, use that;
     // otherwise default to true for storage profile nodes.
     const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
+    const listenAddrs = resolveListenAddrs(config.network);
 
     try {
       let t0 = performance.now();
       const node = await createLibp2pNode({
         port: 0, // Random port
         bootstrapNodes: config.bootstrapNodes ?? [],
-        networkName: `strand-${strandId}`,
+        networkName,
         storage: strandStorage,
         fretProfile: config.profile === 'storage' ? 'core' : 'edge',
         relay: enableRelay,
-        clusterSize: 3,
-        clusterPolicy: {
-          allowDownsize: true,
-          sizeTolerance: 0.5
-        },
+        clusterSize: resolveStrandClusterSize(config.clusterSize),
+        // Deliberately NOT CONTROL_CLUSTER_POLICY: a strand is application data with its own
+        // breadth reasoning, and the shape match with the control policy is a coincidence.
+        clusterPolicy: STRAND_CLUSTER_POLICY,
         arachnode: {
           enableRingZulu: config.profile === 'storage'
         },
         ...(config.privateKey && { privateKey: config.privateKey }),
         ...(config.network?.transports && { transports: config.network.transports }),
-        ...(config.network?.listenAddrs && { listenAddrs: config.network.listenAddrs }),
+        // NOTE: strand nodes receive the same RESOLVED listen addrs as the
+        // control node. A fixed-port listen addr (e.g. cadre-cli's example
+        // `/ip4/0.0.0.0/tcp/4001`) would have control + strand nodes racing to
+        // bind one port — EADDRINUSE. Unverified; if a deployment configures a
+        // fixed port and strands fail to start, rewrite the port per node here.
+        // An inherited `/p2p-circuit` addr, by contrast, is deliberate — it is
+        // what gives a NAT'd strand node a reachable relay slot — and works
+        // because the launch path announces this strand's derived peerId to
+        // the relay first (delegate admission; see cadre-node.ts). Those circuit
+        // entries come either from a hand-written `network.listenAddrs` or from
+        // `network.relayAddrs`, which `resolveListenAddrs` folds into the same list.
+        ...(listenAddrs && { listenAddrs }),
         ...(config.network?.connectionGater && { connectionGater: config.network.connectionGater })
       }) as Libp2pNodeWithRepo;
       timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
 
       instance.libp2pNode = node;
+      // Assigned on every runtime (re)build — resume re-enters here with
+      // resumeConfig, so a bootstrap → networked shift refreshes the field.
+      instance.mode = mode;
 
       // Create and initialize the StrandDatabase. In bootstrap mode the same
       // strandStorage instance also backs the optimystic local transactor so
-      // DML lands on the host's persistent storage (e.g. MMKV on RN). Sharing
+      // DML lands on the host's persistent storage (e.g. LevelDB on RN). Sharing
       // the instance — not creating a second one over the same id+prefix —
       // avoids cache divergence between the libp2p and database paths.
       //
@@ -288,11 +355,11 @@ export class StrandInstanceManager {
         sAppConfig,
         libp2pNode: node,
         coordinatedRepo: node.coordinatedRepo,
-        mode: config.mode ?? 'networked',
+        mode,
         rawStorage: strandStorage,
         // Founder bootstrap inputs: the strand's type drives which membership rows
         // are written, and the closed-strand MemberPrivateKey derives the founding
-        // Member/Authority key. Both come off the control-network strand row.
+        // Member/Manager key. Both come off the control-network strand row.
         strandType: config.strandRow.Type,
         memberPrivateKey: config.strandRow.MemberPrivateKey ?? undefined,
         founder: config.founder
@@ -301,6 +368,28 @@ export class StrandInstanceManager {
       await strandDb.initialize();
       timing('[buildStrandRuntime:%s] strandDatabase.initialize: %dms', strandId, Math.round(performance.now() - t0));
 
+      // Peer-join block catch-up: push this strand's own blocks to each newly
+      // connected peer, so a machine that joined after blocks were committed
+      // still ends up physically holding them (a bootstrap strand has no mesh
+      // to catch up, and without per-strand storage there is nothing to copy).
+      if (mode === 'networked' && strandStorage && config.backfill?.enabled !== false) {
+        if (node.keyNetwork) {
+          const backfill = new StrandBackfill({
+            strandId,
+            libp2p: node,
+            peerNetwork: node.keyNetwork,
+            storage: strandStorage,
+            // The same prefix the receiver registered its block-transfer handler
+            // under — derived from networkName above, never re-spelled here.
+            protocolPrefix
+          }, config.backfill);
+          backfill.start();
+          this.backfills.set(strandId, backfill);
+        } else {
+          log('Strand %s: libp2p node exposes no keyNetwork; peer-join block catch-up is inert', strandId);
+        }
+      }
+
       instance.status = 'active';
       instance.lastActivity = new Date();
     } catch (error) {
@@ -323,6 +412,14 @@ export class StrandInstanceManager {
    * Shared by `quiesceStrand`, `stopStrand`, and that rollback path.
    */
   private async releaseRuntime(instance: StrandInstance): Promise<void> {
+    // Backfill first — before the database closes and the libp2p node stops — so
+    // no NEW catch-up push is issued against a torn-down transport. A push already
+    // in flight is not awaited; it fails into the module's own per-chunk catch.
+    const backfill = this.backfills.get(instance.strandId);
+    if (backfill) {
+      backfill.stop();
+      this.backfills.delete(instance.strandId);
+    }
     if (instance.database) {
       await instance.database.close();
       instance.database = undefined;

package/src/strand-member-key.ts

@@ -1,6 +1,6 @@
 import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf } from '@libp2p/crypto/keys';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-import { authorityKeyFromLibp2p, type AuthorityKeyPair } from './authority-key.js';
+import { ed25519KeyPairFromLibp2p, type Ed25519KeyPair } from './ed25519-key.js';
 
 /**
  * Mint a fresh ed25519 strand member private key, encoded as base64 protobuf.
@@ -22,18 +22,18 @@ export async function generateStrandMemberKey(): Promise<string> {
  * base64url keypair the strand RBAC constraints consume.
  *
  * The `Strand` control-layer `MemberPrivateKey` is the closed-strand read-gating
- * secret; the founding `Member.Key`/`Authority.MemberKey` (the strand RBAC layer)
+ * secret; the founding `Member.Key`/`Manager.MemberKey` (the strand RBAC layer)
  * are *derived from it* — they are the `publicKeyB64` of the keypair this returns.
  * Decode the protobuf to a libp2p private key, then reuse
- * {@link authorityKeyFromLibp2p} so the same seed→public derivation used for node
- * authority keys yields a stable `{ privateKeyB64, publicKeyB64 }` whose public
+ * {@link ed25519KeyPairFromLibp2p} so the same seed→public derivation used for node
+ * owner keys yields a stable `{ privateKeyB64, publicKeyB64 }` whose public
  * key a later strand signature verifies against.
  *
  * @param memberPrivateKey - The strand's `MemberPrivateKey` (base64 protobuf).
- * @returns The base64url seed/public-key pair for founding membership/authority.
+ * @returns The base64url seed/public-key pair for founding membership/manager.
  * @throws If the decoded key is not Ed25519 or the raw bytes are malformed.
  */
-export function strandMemberKeyPair(memberPrivateKey: string): AuthorityKeyPair {
+export function strandMemberKeyPair(memberPrivateKey: string): Ed25519KeyPair {
   const privateKey = privateKeyFromProtobuf(uint8ArrayFromString(memberPrivateKey, 'base64'));
-  return authorityKeyFromLibp2p(privateKey);
+  return ed25519KeyPairFromLibp2p(privateKey);
 }

package/src/strand-member-registry.ts

@@ -2,13 +2,13 @@ import debug from 'debug';
 import type { Database, SqlValue } from '@quereus/quereus';
 import type { MemberRegistration } from './types.js';
 import type { MemberRegistry, MemberVerifier } from './enrollment.js';
-import type { AuthorityKeyPair } from './authority-key.js';
+import type { Ed25519KeyPair } from './ed25519-key.js';
 import {
   verifyStrandPayload,
   consumeInvite,
-  addMemberByAuthority,
+  addMemberByManager,
+  listOutstandingInvites,
 } from './strand-membership-writer.js';
-import { canonicalDatetime } from './canonical-datetime.js';
 
 const log = debug('sereus:cadre:strand-member-registry');
 
@@ -37,10 +37,10 @@ export type StrandAdmission =
       readonly invitePrivateKey: string;
     }
   | {
-      /** Admit directly by authority signature (the authority-side join). */
-      readonly mode: 'authority';
-      /** The admitting authority's strand keypair. */
-      readonly authorityKeyPair: AuthorityKeyPair;
+      /** Admit directly by manager signature (the manager-side join). */
+      readonly mode: 'manager';
+      /** The admitting manager's strand keypair. */
+      readonly managerKeyPair: Ed25519KeyPair;
     };
 
 /**
@@ -80,11 +80,11 @@ export class StrandMemberVerifier implements MemberVerifier {
    * single-use, and cryptographic gates are all enforced by the deferred
    * `Strand.*` constraints when the member is actually written.
    *
-   * Expired invites are filtered out so this pre-flight matches the on-engine
-   * `ConsumedInvite.NotExpired` gate — `Now` is canonicalised the same way the
-   * writer canonicalises it, so `Expiration > ?` compares like-for-like canonical
-   * strings. A member that already holds a `ConsumedInvite` short-circuits above,
-   * regardless of any invite's expiry.
+   * "Outstanding" is {@link listOutstandingInvites}: an `Invite` that is neither
+   * already consumed, nor cancelled by a manager, nor expired. All three exclusions
+   * mirror gates the actual write would hit (`ConsumedInvite`'s primary key,
+   * `NotCancelled`, `NotExpired`), so this pre-flight does not report a door the
+   * constraints will slam. A raw `Invite` count would over-report on all three.
    */
   async isAuthorizedToJoin(_strandId: string, memberKey: string): Promise<boolean> {
     const consumed = await scalarCount(
@@ -93,15 +93,20 @@ export class StrandMemberVerifier implements MemberVerifier {
       [memberKey],
     );
     if (consumed > 0) {
+      // NOTE: a REVOKED member still bears its stale ConsumedInvite row (the table is
+      // insert-only, and revocation does not delete it), so this short-circuit says
+      // "authorized" for a party that can no longer actually join. Harmless because the
+      // on-engine constraints are the real gate — Member.Authorized's invite branch
+      // requires a FRESH consumption row, which a stale one is not — and this pre-flight
+      // only decides whether attempting the write is worthwhile.
       return true;
     }
-    const nowCanonical = await canonicalDatetime(this.db, Date.now());
-    const invites = await scalarCount(
-      this.db,
-      'select count(1) as c from Strand.Invite where Expiration is null or Expiration > ?',
-      [nowCanonical],
-    );
-    return invites > 0;
+    // NOTE: materialises the whole outstanding set to answer a non-empty question (the
+    // former code was a single `select count(1)`). Deliberate — sharing one definition of
+    // "outstanding" with the manager-facing enumeration beats a second, drifting copy of
+    // the three exclusions. If this pre-flight ever runs hot on a strand with many
+    // invitations, add a short-circuiting variant rather than re-inlining the rules.
+    return (await listOutstandingInvites(this.db)).length > 0;
   }
 }
 
@@ -115,8 +120,8 @@ export class StrandMemberVerifier implements MemberVerifier {
  * `Member.Authorized` is taken:
  * - `invite`  → {@link consumeInvite} (atomic `Member` + `ConsumedInvite`), the
  *   invitee-side flow that redeems a single-use invite.
- * - `authority` → {@link addMemberByAuthority}, the authority-side flow that
- *   seats a member already trusted by an authority.
+ * - `manager` → {@link addMemberByManager}, the manager-side flow that
+ *   seats a member already trusted by a manager.
  *
  * Scoped to one strand's db; the `strandId` argument is accepted for interface
  * compatibility but writes target this db's `Strand.*` tables.
@@ -152,8 +157,8 @@ export class StrandMemberRegistry implements MemberRegistry {
       return;
     }
 
-    await addMemberByAuthority(this.db, {
-      authorityKeyPair: this.admission.authorityKeyPair,
+    await addMemberByManager(this.db, {
+      managerKeyPair: this.admission.managerKeyPair,
       memberKey,
     });
   }