@serfab/cadre-core 1.7.0 → 1.9.0

package/src/control-authorization.ts

@@ -39,6 +39,7 @@ export const CONTROL_TABLES = [
   'ValidationKey',
   'Strand',
   'StrandPartyKey',
+  'JoinedStrand',
   'CadrePeer',
   'DeviceToken',
   'FormationInvite',
@@ -64,7 +65,7 @@ export type ControlTable = typeof CONTROL_TABLES[number];
  * (`control-database.ts`) so the lightweight signers — `peer-authorization.ts`'s
  * `revocationDigest` — can type against it without pulling in the runtime.
  */
-export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'DeviceToken'>;
+export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' | 'DeviceToken'>;
 
 /**
  * What a signature authorizes, scoped to one table rule — or, for

package/src/control-cohort.ts

@@ -28,6 +28,12 @@ import type { CohortPeerRow } from './strand-cohort.js';
  * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
  * In the same spirit as the 5s strand-watch poll but lighter, since a control
  * cohort changes far less often than strand activity.
+ *
+ * An interval between pass starts, not a deadline on a pass. Passes are
+ * single-flight, so a pass that runs longer than this is joined rather than
+ * stacked, and the effective cadence becomes the pass length: one unreachable
+ * sibling's dial alone can take the whole per-peer dial budget (64 s at the
+ * default declared link).
  */
 export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
 

package/src/control-database.ts

@@ -100,7 +100,9 @@ export class FormationAbortedError extends Error {
  *
  * Raised off the committed-count check ({@link ControlDatabase.assertSeatRemains}) ahead of
  * the write, inside {@link ControlDatabase.redeemInvitation} /
- * {@link ControlDatabase.recordFormationUsage} — and off nothing else. It exists because
+ * {@link ControlDatabase.recordFormationUsage}, and off the unlocked pre-check
+ * `ControlFormationUsageRecorder.authorizeUsage` runs before the manager issues a membership
+ * pass — and off nothing else. It exists because
  * without it the refusal surfaces as a generic `CHECK constraint failed: Authorized` from the
  * schema's own count-based cap clause, which the manager reports as a retryable
  * `Formation conflict, retry` — telling the joiner to retry something that can never succeed.
@@ -293,26 +295,33 @@ const GUARDED_KEY_COLUMN: Readonly<Record<RevocableTable, GuardedKeyColumn>> = {
   ValidationKey: 'Key',
   Strand: 'Id',
   StrandPartyKey: 'Id',
+  JoinedStrand: 'Id',
   DeviceToken: 'PeerId',
 };
 
+/** The control tables keyed by a strand id whose repeat insert a caller may treat as idempotent. */
+type StrandIdTable = Extract<RevocableTable, 'Strand' | 'JoinedStrand'>;
+
 /**
- * The rejection a second insert of an already-seated strand id produces, as the optimystic
- * vtab words it (`uniqueConstraintMessage`, qualified by table name only — no schema
- * prefix, matching `test/control-constraint-helpers.ts`'s `expectUniqueViolation`).
+ * The rejection a second insert of an already-seated strand id into `table` produces, as
+ * the optimystic vtab words it (`uniqueConstraintMessage`, qualified by table name only —
+ * no schema prefix, matching `test/control-constraint-helpers.ts`'s `expectUniqueViolation`).
  *
- * `Strand.StampId` is unique too, but a fresh stamp is minted per insert attempt, so only
- * the primary key can collide on a repeat publish. Matching the column explicitly keeps
- * any OTHER uniqueness failure out of the idempotency branch.
+ * Each table's `StampId` is unique too, but a fresh stamp is minted per insert attempt, so
+ * only the primary key can collide on a repeat publish. Matching the column explicitly
+ * keeps any OTHER uniqueness failure out of the idempotency branch.
  */
-const STRAND_ID_CONFLICT = /UNIQUE constraint failed: Strand\.Id\b/i;
+function strandIdConflictPattern(table: StrandIdTable): RegExp {
+  return new RegExp(`UNIQUE constraint failed: ${table}\\.Id\\b`, 'i');
+}
 
 /**
- * Did this write fail because the strand id is already seated?
+ * Did this write to `table` fail because the strand id is already seated there?
  *
  * {@link CadreNode.publishStrand} uses this to tell "my own earlier publish already
  * landed" (re-read, and no-op when the row matches) apart from every other rejection —
- * an unauthorized signer, a retired stamp — which must keep surfacing.
+ * an unauthorized signer, a retired stamp — which must keep surfacing. For `JoinedStrand`
+ * the same test tells "another machine of this party already published this join" apart.
  *
  * Matched by TEXT, not by type: the typed engine error does not survive the trip out of
  * optimystic (same constraint the retry classifiers in `control-write-retry.ts` document).
@@ -321,8 +330,8 @@ const STRAND_ID_CONFLICT = /UNIQUE constraint failed: Strand\.Id\b/i;
  * `publish-strand.spec.ts` repeat-publish cases assert against the live engine error, so a
  * reword reddens there.
  */
-export function isStrandIdConflict(error: unknown): boolean {
-  return errorChainMatches(error, STRAND_ID_CONFLICT);
+export function isStrandIdConflict(error: unknown, table: StrandIdTable): boolean {
+  return errorChainMatches(error, strandIdConflictPattern(table));
 }
 
 /**
@@ -339,7 +348,7 @@ export const REVOCATION_LEDGER_MARKER = {
 
 /**
  * The rejection a second insert of the ledger marker produces: the optimystic vtab's
- * primary-key wording (see {@link STRAND_ID_CONFLICT}), naming both columns of
+ * primary-key wording (see {@link strandIdConflictPattern}), naming both columns of
  * `Revocation`'s composite key. Applied only to the marker's own insert, whose key
  * ('Revocation', 'opened') no row but the marker can hold (`RowIsGone`), and `Revocation`
  * has no other unique constraint.
@@ -362,10 +371,12 @@ function errorChainMatches(error: unknown, pattern: RegExp): boolean {
  * `CadrePeer.AuthorizedDelete` in the schema). `Strand` and `StrandPartyKey` are
  * deliberately absent: their rows carry `MemberPrivateKey` / `PrivateKey` — party
  * secrets stored nowhere else (tickets/backlog/debt-strand-tombstone-reap.md owns any
- * future change). `OwnerKey` has no production removal path and `MinOneOwner` makes an
- * automated owner-key reap a party-bricking hazard.
+ * future change). `JoinedStrand` also carries a `MemberPrivateKey` but IS reapable: that
+ * secret is the joined strand's shared read key, which its founding party and every member
+ * hold, so a reaped row is recoverable by re-forming. `OwnerKey` has no production removal
+ * path and `MinOneOwner` makes an automated owner-key reap a party-bricking hazard.
  */
-export const REAPABLE_TABLES = ['CadrePeer', 'DeviceToken', 'ValidationKey'] as const satisfies readonly RevocableTable[];
+export const REAPABLE_TABLES = ['CadrePeer', 'DeviceToken', 'ValidationKey', 'JoinedStrand'] as const satisfies readonly RevocableTable[];
 export type ReapableTable = (typeof REAPABLE_TABLES)[number];
 
 /**
@@ -378,6 +389,16 @@ export type ReapableTable = (typeof REAPABLE_TABLES)[number];
 const REAPABLE_TABLE_SET: ReadonlySet<RevocableTable> = new Set<RevocableTable>(REAPABLE_TABLES);
 const isReapableTable = (table: RevocableTable): table is ReapableTable => REAPABLE_TABLE_SET.has(table);
 
+/** A `JoinedStrand` row as a {@link StrandRow}; the schema's `KnownType` check backs the `Type` cast. */
+function joinedStrandRow(row: Record<string, SqlValue>): StrandRow {
+  return {
+    Id: row.Id as string,
+    MemberPrivateKey: row.MemberPrivateKey as string | null,
+    Type: row.Type as 'o' | 'c',
+    FounderOwnerKey: null,
+  };
+}
+
 /**
  * Notified after a `CadreControl.CadrePeer` row write has COMMITTED.
  *
@@ -559,7 +580,7 @@ export class ControlDatabase {
     // NOTE: this is where a slow launch is felt. Duration is (raw-storage operations
     // issued) × per-operation storage latency: ~1ms/op on an idle machine, but
     // 50-90ms/op on a loaded disk or a phone's flash under launch contention. A cold
-    // start now reaches the backend 45 times (9 tables + 1 index, 20 distinct blocks
+    // start now reaches the backend 48 times (10 tables + 1 index, 23 distinct blocks
     // — dominated by its genuine writes), a warm restart 13, because cadre-core
     // wraps every embedder storage in `@optimystic/db-p2p`'s write-through cache
     // (@serfab/quereus-plugin-sereus's cached-storage.ts). Uncached the same start issued ~2000 operations — the
@@ -629,6 +650,11 @@ export class ControlDatabase {
     //    exactly why `initialize` hydrates persisted optimystic schemas BEFORE getting here.
     //    A table the live catalog already lists generates no statements at all, which is what
     //    makes an apply over an already-complete schema (a warm start) a no-op.
+    //    NOTE: a table the catalog lists with DIFFERENT constraint text diffs to
+    //    `alter table ... drop constraint`, which the optimystic module refuses, so a store
+    //    written by a build with older constraint text fails here on every start (policy:
+    //    recreate, docs/architecture.md after the Control Network table). If backwards
+    //    compatibility becomes a requirement, this apply is the migration site.
     //  - a failed apply is taken back WHOLE (Quereus 4.20.0). The migration loop keeps an
     //    undo journal; when a step fails it runs that journal in reverse, re-renders the
     //    catalog, compares it against a fingerprint taken BEFORE the apply, and only then
@@ -879,6 +905,29 @@ export class ControlDatabase {
     return null;
   }
 
+  /**
+   * Every strand this party joined from another party (`CadreControl.JoinedStrand`), shaped
+   * as a {@link StrandRow} so a reader can treat it like one of the party's own. A joiner
+   * never founds, so `FounderOwnerKey` is always null. Read raw, like {@link queryStrands}:
+   * no retired-stamp filter.
+   */
+  async queryJoinedStrands(): Promise<StrandRow[]> {
+    this.ensureInitialized();
+    const rows = await this.readRows('select Id, Type, MemberPrivateKey from CadreControl.JoinedStrand', undefined, 'joined-strands');
+    return rows.map(joinedStrandRow);
+  }
+
+  /** Single-row sibling of {@link queryJoinedStrands}: the joined strand with this id, or null. */
+  async queryJoinedStrand(strandId: string): Promise<StrandRow | null> {
+    this.ensureInitialized();
+    const rows = await this.readRows(
+      'select Id, Type, MemberPrivateKey from CadreControl.JoinedStrand where Id = ?',
+      [strandId],
+      'joined-strand'
+    );
+    return rows.length === 0 ? null : joinedStrandRow(rows[0]!);
+  }
+
   /**
    * Count rows in a CadreControl table as seen by THIS database instance.
    *
@@ -1095,6 +1144,11 @@ export class ControlDatabase {
     return this.queryStampId('StrandPartyKey', strandId);
   }
 
+  /** `JoinedStrand` stamp nonce — bound into {@link deleteJoinedStrand}'s remove digest. */
+  queryJoinedStrandStampId(strandId: string): Promise<string | null> {
+    return this.queryStampId('JoinedStrand', strandId);
+  }
+
   /**
    * Read THIS party's own strand membership private key (base64 protobuf; decode with
    * `strandMemberKeyPair`) for one strand, or null when no `StrandPartyKey` row exists.
@@ -1606,6 +1660,56 @@ export class ControlDatabase {
     return this.lockedWithRetry(() => this.deleteGuardedRow('StrandPartyKey', strandId, ownerKey, signMessage), {}, 'strand-party-key-delete');
   }
 
+  /**
+   * Record, party-wide, a strand this party joined from another party (`JoinedStrand` row),
+   * using an owner signature.
+   *
+   * Mirrors {@link insertStrand}: the owner signs the canonical row-bound authorization
+   * message over (Id, Type, MemberPrivateKey, StampId) — binding the read secret, so a
+   * captured approval can only reproduce the row it approved — and the StampId is persisted
+   * as a unique column for single-use anti-replay.
+   *
+   * Fails with a `JoinedStrand.Id` uniqueness violation when the id is already recorded;
+   * `isStrandIdConflict(error, 'JoinedStrand')` identifies that case.
+   */
+  async insertJoinedStrand(
+    row: Pick<StrandRow, 'Id' | 'Type' | 'MemberPrivateKey'>,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting joined strand: %s (type: %s)', row.Id, row.Type);
+
+    const stampId = generateStampId(this.config.libp2pNode.peerId.toString());
+
+    // Field order MUST match the schema's JoinedStrand `AuthorizedInsert` verify:
+    // Id, Type, MemberPrivateKey ('' when null), StampId.
+    const message = buildAuthorizationMessage('CadreControl.JoinedStrand', 'add', [row.Id, row.Type, row.MemberPrivateKey ?? '', stampId]);
+    const signature = signMessage(message);
+
+    await this.execWrite(`
+      insert into CadreControl.JoinedStrand (Id, Type, MemberPrivateKey, StampId)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, ?)
+    `, [ownerKey, signature, row.Id, row.Type, row.MemberPrivateKey, stampId], 'joined-strand-insert');
+
+    log('Joined strand inserted: %s', row.Id);
+  }
+
+  /**
+   * Owner-signed removal of one `JoinedStrand` row. Mirrors {@link deleteStrandPartyKey}:
+   * `'remove'`-tagged digest over (Id, StampId), `Revocation` tombstone in the same
+   * transaction. A no-op (no throw, no tombstone) when the row does not exist — `false`
+   * then, `true` when a row was actually removed.
+   */
+  deleteJoinedStrand(
+    strandId: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.lockedWithRetry(() => this.deleteGuardedRow('JoinedStrand', strandId, ownerKey, signMessage), {}, 'joined-strand-delete');
+  }
+
   /**
    * Insert a validation key into the control database using an owner signature.
    *
@@ -2082,7 +2186,7 @@ export class ControlDatabase {
    *   reads from this node (every other node already filters it by tombstone). A revoked
    *   node therefore keeps its own copy of its own row; "a node that learns it has been
    *   revoked should shut itself down" is a distinct behaviour and its own ticket.
-   *   `ValidationKey` has no self notion and is not special-cased.
+   *   `ValidationKey` and `JoinedStrand` have no self notion and are not special-cased.
    *
    * A per-row failure is logged and skipped rather than aborting the sweep: an abort would
    * starve every tombstone after the failing one on every subsequent pass, and each row is