@serfab/cadre-core 1.15.0 → 1.17.0

package/src/strand-cohort.ts

@@ -1,3 +1,5 @@
+import type { NodeProfile } from './types.js';
+
 /**
  * A single CadrePeer membership row, as returned by
  * `ControlDatabase.queryCadrePeers()`.
@@ -6,6 +8,8 @@ export interface CohortPeerRow {
   peerId: string;
   /** Comma-joined list of multiaddr strings; `''` when no addrs were recorded. */
   multiaddr: string | null;
+  /** The machine's self-declared profile; null or absent until it self-publishes. */
+  profile?: NodeProfile | null;
 }
 
 /**

package/src/strand-database.ts

@@ -76,6 +76,7 @@ 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;
@@ -131,6 +132,7 @@ export class StrandDatabase {
     });
     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)',
@@ -181,6 +183,7 @@ export class StrandDatabase {
       sharedMemberPublicKey: closed && memberPrivateKey
         ? strandMemberKeyPair(memberPrivateKey).publicKeyB64
         : undefined,
+      createEmptyCollections: this.createEmptyCollections!,
     });
   }
 

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

@@ -40,9 +40,10 @@
  * Every probe is a read (`Strand.Header`, then `select count(1)` on each `App` table). Reads
  * never invent a collection (Optimystic's `Collection.open` resolves undefined on an
  * authoritatively absent header, and throws on an unreachable one), so probing is safe to
- * repeat and a throw is just "not yet". A table nobody has written yet reads as absent on
- * every machine; the first write to it still creates its collection — see `docs/strands.md`
- * ("Joining") for that residual.
+ * repeat and a throw is just "not yet". Every table declared at founding has a collection
+ * from the start (the founder bootstrap commits them all before the Header), so a probe read
+ * fetches it; a table a later schema version adds reads as absent until its first write
+ * creates the collection — see `docs/strands.md` ("Joining") for that residual.
  *
  * Owned by `StrandInstanceManager`: created in `buildStrandRuntime` for every launch, armed
  * only for a non-founder launch whose first probe fails, stopped and dropped in

package/src/strand-instance-manager.ts

@@ -142,7 +142,7 @@ export interface StartStrandConfig {
    * StrandDatabase so the founder bootstrap (Header, founding Member/Manager)
    * runs once at bring-up. Joiners leave this unset and write nothing. Callers
    * resolve it BEFORE calling `startStrand` (`CadreNode.launchStrand` derives it
-   * from the row's `FounderOwnerKey` when no explicit flag is given — see
+   * from the row's `FounderPeerId` when no explicit flag is given — see
    * {@link StrandConfig.founder}); a founder request that arrives while the
    * instance is already tracked goes through {@link StrandInstanceManager.foundExistingStrand},
    * never through a repeat `startStrand`.

package/src/strand-membership-writer.ts

@@ -305,6 +305,12 @@ export interface FounderBootstrapParams {
    * holds no shared key has nothing to compare against). Ignored for an open strand.
    */
   sharedMemberPublicKey?: string;
+  /**
+   * Commit an empty collection for every table the strand declares, resolving to how many
+   * it committed: the composition's `createEmptyCollections`. Run once, on the founding run
+   * that finds no `Header` — see {@link createDeclaredCollections}.
+   */
+  createEmptyCollections: () => Promise<number>;
 }
 
 /**
@@ -356,12 +362,6 @@ async function strandTableCount(db: Database, table: 'Header' | 'Member' | 'Mana
  * `Revocation` schema comment already flags, tracked by `debt-strand-tombstone-reap`
  * — this wants a stored "founding closed" marker rather than a scan per call.
  *
- * NOTE: on a strand that has never revoked anyone, `Strand.Revocation` has never been
- * written, so this node does not hold its block, and the storage layer consults the
- * block's cohort on every read of a block it does not hold — this scan and every
- * `NotRevoked` insert check pay that per call. Not measured, and cheap while strand
- * membership writes are rare; if they become frequent, file a singleton marker row in
- * the strand schema the way the control schema does (`ControlDatabase.openRevocationLedger`).
  */
 async function strandHasManagerRevocation(db: Database): Promise<boolean> {
   for await (const row of db.eval('select TableName from Strand.Revocation')) {
@@ -373,7 +373,50 @@ async function strandHasManagerRevocation(db: Database): Promise<boolean> {
 }
 
 /**
- * Insert the singleton `Strand.Header` if absent.
+ * Found the strand if its `Strand.Header` is absent: commit every declared table's
+ * collection ({@link createDeclaredCollections}), then insert the Header. A Header
+ * already present means the strand was founded before, so both are skipped.
+ */
+async function foundIfHeaderAbsent(db: Database, params: FounderBootstrapParams): Promise<void> {
+  if (await strandTableCount(db, 'Header') > 0) {
+    log('Header already present for strand %s; skipping', params.strandId);
+    return;
+  }
+  await createDeclaredCollections(params);
+  await insertHeader(db, params);
+}
+
+/**
+ * Commit an empty collection for every table the strand declares, so a read of a table
+ * nobody has written is answered from local storage instead of asking the block's cohort
+ * to prove the collection absent, and still answers with the other members offline.
+ * Peer-join backfill hands these collections to every joiner.
+ *
+ * Only while the Header is absent, and before it is written: a machine cannot write to a
+ * strand before it holds the Header (`strand-first-sync-gate.ts`), so no other machine can
+ * yet have created any of these collections and this cannot fork one. On a founder restart
+ * the Header is present and this does not run; running it there could commit an empty
+ * second history beside a table a joiner wrote while the founder was away. A crash between
+ * this and the Header repeats it on the next run, which commits only the collections still
+ * missing.
+ *
+ * NOTE: one `sync()` per collection, in sequence. Measured 2026-10-17 on a lone node over the
+ * network transactor (`connectToStrand`, then the step alone, 3 runs each): a nine-table app
+ * schema (20 collections with the strand's own) took 32–82 ms in memory and 465–486 ms on
+ * `FileRawStorage`; the reference chat schema (13 collections) 19–30 ms and 298–350 ms. About
+ * 23 ms per collection on disk, once per strand, before `foundStrand` returns. If founding
+ * latency starts to matter (slower phone storage, much larger schemas), commit them as one
+ * batch through a coordinator, the way the transaction bridge's `commitBatchLegacy` does.
+ */
+async function createDeclaredCollections(params: FounderBootstrapParams): Promise<void> {
+  const t0 = performance.now();
+  const committed = await params.createEmptyCollections();
+  log('Committed %d empty collections for strand %s in %dms',
+    committed, params.strandId, Math.round(performance.now() - t0));
+}
+
+/**
+ * Insert the singleton `Strand.Header`.
  *
  * Every `Header` column is NOT NULL (Quereus defaults unqualified columns to NOT
  * NULL; the table declares no `null` columns), so all eight are supplied non-null.
@@ -381,11 +424,7 @@ async function strandHasManagerRevocation(db: Database): Promise<boolean> {
  * rather than inserting null. `Header` carries only `InsertOnly` + a singleton PK,
  * so the insert needs no `with context`.
  */
-async function insertHeaderIfAbsent(db: Database, params: FounderBootstrapParams): Promise<void> {
-  if (await strandTableCount(db, 'Header') > 0) {
-    log('Header already present for strand %s; skipping', params.strandId);
-    return;
-  }
+async function insertHeader(db: Database, params: FounderBootstrapParams): Promise<void> {
   await db.exec(
     `insert into Strand.Header
        (Id, Type, sAppId, sAppVersion, sAppSchema, sAppSignature, Engine, EngineVersion)
@@ -504,6 +543,10 @@ export async function assertNotPreSplitStrand(db: Database, strandId: string, sh
  * Optimystic sync. Every write is insert-if-absent (guarded by a row count) so a
  * restart / founder re-`addStrand` is a no-op and never double-inserts.
  *
+ * On the run that finds no `Header`, it first commits an empty collection for every
+ * table the `Strand` and `App` schemas declare, so no read of a declared table ever
+ * needs another member to prove it empty ({@link createDeclaredCollections}).
+ *
  * Behavior by strand type:
  * - **Open (`'o'`)**: insert `Header` only. `Member`/`Manager`/`Invite` are
  *   `OnlyClosed` and would trip that constraint — they are skipped entirely.
@@ -523,8 +566,9 @@ export async function assertNotPreSplitStrand(db: Database, strandId: string, sh
  * key seated.
  *
  * @param db - The strand's Quereus database (schema already applied).
- * @param params - Strand id/type, the sApp config for the Header, and (closed only)
- *   the derived founder keypair and the shared-derived public key to refuse.
+ * @param params - Strand id/type, the sApp config for the Header, the composition's
+ *   empty-collection step, and (closed only) the derived founder keypair and the
+ *   shared-derived public key to refuse.
  * @throws If `type === 'c'` and no `founderKeyPair` is supplied.
  * @throws {PreSplitStrandIdentityError} If `type === 'c'` and a `Strand.Member` or
  *   `Strand.Manager` row is `sharedMemberPublicKey`.
@@ -546,8 +590,9 @@ export async function bootstrapFounderMembership(db: Database, params: FounderBo
     await assertNotPreSplitStrand(db, strandId, sharedMemberPublicKey);
   }
 
-  // Header is written for every strand; Member/Manager are closed-only.
-  await insertHeaderIfAbsent(db, params);
+  // Every table's collection and the Header are written for every strand; Member/Manager
+  // are closed-only.
+  await foundIfHeaderAbsent(db, params);
 
   if (type === 'o') {
     // Open strand: Member/Manager/Invite are OnlyClosed — nothing else to write.

package/src/strand-move.ts

@@ -21,9 +21,9 @@
  * Built over `CadreNode`'s public surface, so `cadre-node.ts` does not grow by the feature.
  */
 import debug from 'debug';
-import { sign } from '@optimystic/quereus-plugin-crypto';
 import type { PersistedNetworkState } from '@optimystic/db-p2p';
 import type { CadreNode } from './cadre-node.js';
+import type { OwnerSign } from './owner-signer.js';
 import {
 	isPendingJoinConflict,
 	isStrandIdConflict,
@@ -98,10 +98,10 @@ export interface StrandMoveReport {
 	pendingJoinsMoved: number;
 }
 
-/** {@link adoptStrandBundle} refused before any write: the running node's key is not an owner of its party. */
+/** {@link adoptStrandBundle} refused before any write: the running node's owner key is not an owner of its party. */
 export class StrandMoveNotOwnerError extends Error {
 	constructor(readonly partyId: string) {
-		super(`Cannot adopt strands into party ${partyId}: this node's key is not one of its owners, and every re-seated row is owner-signed`);
+		super(`Cannot adopt strands into party ${partyId}: this node's owner key is not one of its owners, and every re-seated row is owner-signed`);
 		this.name = 'StrandMoveNotOwnerError';
 	}
 }
@@ -201,10 +201,11 @@ async function exportFormationInvites(database: ControlDatabase, now: number): P
 }
 
 /**
- * Seat `bundle` in the running node's party, every row owner-signed by the node's own identity
- * key. Refuses up front, with a typed error and no write, when that key is not an owner of the
- * party ({@link StrandMoveNotOwnerError}) or the bundle came from this very party
- * ({@link StrandMoveSamePartyError}).
+ * Seat `bundle` in the running node's party, every row owner-signed through the node's owner
+ * signer (`CadreNode.getOwnerSigner`, wired here by `wireOwnKeyIfOwner` when it is not yet),
+ * in one approval for the whole bundle. Refuses up front, with a typed error and no write, when
+ * that signer's key is not an owner of the party ({@link StrandMoveNotOwnerError}) or the
+ * bundle came from this very party ({@link StrandMoveSamePartyError}).
  *
  * Strands first, then the invitations, then the pending joins. Every write is idempotent (a row
  * already present with the same content is skipped and counted as moved), so the same bundle
@@ -221,11 +222,28 @@ export async function adoptStrandBundle(node: CadreNode, bundle: StrandBundle):
 	if (bundle.partyId === node.partyId) {
 		throw new StrandMoveSamePartyError(node.partyId);
 	}
-	if (!(await node.wireOwnKeyIfOwner())) {
+	const owner = (await node.wireOwnKeyIfOwner()) ? node.getOwnerSigner() : null;
+	if (owner === null) {
 		throw new StrandMoveNotOwnerError(node.partyId);
 	}
-	const owner = node.getIdentityOwnerKey();
-	const signer: OwnerSigner = { ownerKey: owner.publicKeyB64, signMessage: signMessageWith(owner.privateKeyB64) };
+	const action = `Move ${bundle.strands.length} strand(s) from the cadre ${bundle.partyId} into this one`;
+	return await owner.approve({ partyId: node.partyId, action }, (sign) =>
+		adoptUnderApproval(node, database, bundle, { ownerKey: owner.publicKey, sign }));
+}
+
+/** An open owner approval: the key every row is written under, and the approval's `sign`. */
+interface OwnerApproval {
+	ownerKey: string;
+	sign: OwnerSign;
+}
+
+/** {@link adoptStrandBundle}'s writes, every one signed inside the one approval `approval`. */
+async function adoptUnderApproval(
+	node: CadreNode,
+	database: ControlDatabase,
+	bundle: StrandBundle,
+	approval: OwnerApproval
+): Promise<StrandMoveReport> {
 	const report: StrandMoveReport = {
 		fromPartyId: bundle.partyId,
 		moved: [],
@@ -236,15 +254,15 @@ export async function adoptStrandBundle(node: CadreNode, bundle: StrandBundle):
 		pendingJoinsMoved: 0
 	};
 	for (const entry of bundle.strands) {
-		await adoptStrand(node, database, signer, entry, report);
+		await adoptStrand(node, database, approval, entry, report);
 	}
 	const settled = settledStrands(report);
 	const now = Date.now();
 	for (const invite of bundle.formationInvites) {
-		await adoptFormationInvite(node, database, invite, settled, report, now);
+		await adoptFormationInvite(node, database, approval.sign, invite, settled, report, now);
 	}
 	for (const join of bundle.pendingJoins) {
-		await adoptPendingJoin(database, signer, join, report);
+		await adoptPendingJoin(database, approval, join, report);
 	}
 	log('adopt(%s ← %s): %d moved, %d refused, %d failed; %d invitation(s) moved, %d dropped; %d pending join(s)',
 		node.partyId, bundle.partyId, report.moved.length, report.refused.length, report.failed.length,
@@ -252,11 +270,6 @@ export async function adoptStrandBundle(node: CadreNode, bundle: StrandBundle):
 	return report;
 }
 
-interface OwnerSigner {
-	ownerKey: string;
-	signMessage: (message: Uint8Array) => string;
-}
-
 /** The strands an adoption has decided on, by outcome, for the invitations bound to them. */
 interface SettledStrands {
 	moved: Set<string>;
@@ -282,7 +295,7 @@ function settledStrands(report: StrandMoveReport): SettledStrands {
 async function adoptStrand(
 	node: CadreNode,
 	database: ControlDatabase,
-	signer: OwnerSigner,
+	approval: OwnerApproval,
 	entry: StrandBundleEntry,
 	report: StrandMoveReport
 ): Promise<void> {
@@ -297,12 +310,12 @@ async function adoptStrand(
 		}
 		await seatStrandPeers(node, entry);
 		if (entry.partyKey !== null) {
-			await node.ensureStrandPartyKey(strandId, entry.partyKey);
+			await node.ensureStrandPartyKey(strandId, entry.partyKey, approval.sign);
 		}
 		if (entry.kind === 'own') {
-			await node.publishStrand(strandId, entry.row.Type, entry.row.MemberPrivateKey ?? undefined);
+			await node.publishStrand(strandId, entry.row.Type, entry.row.MemberPrivateKey ?? undefined, approval.sign);
 		} else {
-			await seatJoinedStrand(database, signer, entry.row, live.joined);
+			await seatJoinedStrand(database, approval, entry.row, live.joined);
 		}
 		report.moved.push(strandId);
 	} catch (error) {
@@ -377,7 +390,7 @@ async function seatStrandPeers(node: CadreNode, entry: StrandBundleEntry): Promi
  */
 async function seatJoinedStrand(
 	database: ControlDatabase,
-	signer: OwnerSigner,
+	approval: OwnerApproval,
 	row: StrandBundleEntry['row'],
 	existing: StrandRow | null
 ): Promise<void> {
@@ -385,7 +398,7 @@ async function seatJoinedStrand(
 		return;
 	}
 	try {
-		await database.insertJoinedStrand(row, signer.ownerKey, signer.signMessage);
+		await database.insertJoinedStrand(row, approval.ownerKey, approval.sign);
 	} catch (error) {
 		if (!isStrandIdConflict(error, 'JoinedStrand')) {
 			throw error;
@@ -412,6 +425,7 @@ async function seatJoinedStrand(
 async function adoptFormationInvite(
 	node: CadreNode,
 	database: ControlDatabase,
+	sign: OwnerSign,
 	invite: FormationInviteEntry,
 	settled: SettledStrands,
 	report: StrandMoveReport,
@@ -434,7 +448,7 @@ async function adoptFormationInvite(
 				expiresAtMs: invite.expiresAtMs ?? undefined,
 				totalUses: invite.usesLeft ?? undefined,
 				strandId: invite.strandId ?? undefined
-			});
+			}, sign);
 		}
 		report.invitationsMoved += 1;
 	} catch (error) {
@@ -464,15 +478,15 @@ async function adoptFormationInvite(
  */
 async function adoptPendingJoin(
 	database: ControlDatabase,
-	signer: OwnerSigner,
+	approval: OwnerApproval,
 	join: PendingJoin,
 	report: StrandMoveReport
 ): Promise<void> {
 	const { StampId: _stampId, outcome, ...request } = join;
 	try {
-		const live = await seatJoinRequest(database, signer, request);
+		const live = await seatJoinRequest(database, approval, request);
 		if (live !== null && outcome !== null && live.outcome === null) {
-			await database.recordJoinOutcome(live, outcome, signer.ownerKey, signer.signMessage);
+			await database.recordJoinOutcome(live, outcome, approval.ownerKey, approval.sign);
 		}
 		report.pendingJoinsMoved += 1;
 	} catch (error) {
@@ -487,9 +501,9 @@ async function adoptPendingJoin(
  * own ask, left alone) or a dismissed one whose retired stamp is still held until the reap
  * pass (the party chose not to have it).
  */
-async function seatJoinRequest(database: ControlDatabase, signer: OwnerSigner, request: JoinRequestFields): Promise<PendingJoin | null> {
+async function seatJoinRequest(database: ControlDatabase, approval: OwnerApproval, request: JoinRequestFields): Promise<PendingJoin | null> {
 	try {
-		return await database.insertJoinRequest(request, signer.ownerKey, signer.signMessage);
+		return await database.insertJoinRequest(request, approval.ownerKey, approval.sign);
 	} catch (error) {
 		if (!isPendingJoinConflict(error)) {
 			throw error;
@@ -557,7 +571,7 @@ function isOpenJoin(join: PendingJoin, nowMs: number): boolean {
 	return join.outcome === null && nowMs < join.ExpiresAt;
 }
 
-/** Content only: `Type` and the read secret. `FounderOwnerKey` is provenance, and a moved strand's changes. */
+/** Content only: `Type` and the read secret. The founder columns are provenance, and a moved strand's change. */
 function sameStrandContent(live: StrandRow, desired: StrandBundleEntry['row']): boolean {
 	return live.Type === desired.Type && (live.MemberPrivateKey ?? null) === (desired.MemberPrivateKey ?? null);
 }
@@ -575,11 +589,6 @@ function requireControlDatabase(node: CadreNode, action: string): ControlDatabas
 	return database;
 }
 
-function signMessageWith(privateKeyB64: string): (message: Uint8Array) => string {
-	return (message: Uint8Array): string =>
-		sign(message, privateKeyB64, 'ed25519', 'bytes', 'base64url', 'base64url') as string;
-}
-
 function errorText(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }

package/src/strand-peer-redial.ts

@@ -234,9 +234,8 @@ class StrandPeerRedialLoop implements StrandPeerRedial {
    *
    * NOTE: a round whose dials failed within milliseconds (a relay connection that is still
    * closing, the member's relay reservation not back yet) waits as long as one whose dials ran
-   * out their budget. In `joiner-first-commit-over-slow-relay`'s third arm that first wait is what
-   * leaves the joiner writable with no member connected. If reconnecting within seconds of a cut
-   * ever matters, retry a round that failed that fast after a short delay instead.
+   * out their budget. If reconnecting within seconds of a cut ever matters, retry a round that
+   * failed that fast after a short delay instead.
    *
    * NOTE: one such fast failure is `ConnectionClosedError: The connection muxer is "closed"`. A
    * relay that aborts its connection to this node cannot tell it so (`@libp2p/websockets`'