@serfab/cadre-core 1.8.0 → 1.10.0

package/src/control-database.ts

@@ -7,7 +7,7 @@ import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
 import { digest, randomBytes } from '@optimystic/quereus-plugin-crypto';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow, PushPlatform } from './types.js';
+import type { StrandRow, PendingJoinRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow, PushPlatform } from './types.js';
 import { CONTROL_SCHEMA } from './control-schema.js';
 import { canonicalDatetime } from './canonical-datetime.js';
 import { controlAuthorizationFields, CONTROL_TABLES } from './control-authorization.js';
@@ -296,22 +296,55 @@ const GUARDED_KEY_COLUMN: Readonly<Record<RevocableTable, GuardedKeyColumn>> = {
   Strand: 'Id',
   StrandPartyKey: 'Id',
   JoinedStrand: 'Id',
+  PendingJoin: 'Id',
   DeviceToken: 'PeerId',
 };
 
+/** A guarded table an owner may remove a row from (no production `OwnerKey` removal path exists yet). */
+type RemovableTable = Exclude<RevocableTable, 'OwnerKey'>;
+
+/**
+ * One row incarnation's owner-signed removal, ready for {@link ControlDatabase.execGuardedRemoval}:
+ * the row's own `'remove'` signature over (key, stamp), and the tombstone's separate
+ * `Revocation` signature over (table, key, stamp). Retiring a stamp is permanent and
+ * party-wide, so the delete's signature deliberately does not cover it; the digests are
+ * domain-separated and neither replays as the other.
+ */
+interface GuardedRemoval {
+  readonly ref: RevokedRowRef & { readonly tableName: RemovableTable };
+  readonly signature: string;
+  readonly revocationSignature: string;
+}
+
+function signGuardedRemoval(
+  tableName: RemovableTable,
+  rowKey: string,
+  stampId: string,
+  signMessage: (message: Uint8Array) => string
+): GuardedRemoval {
+  return {
+    ref: { tableName, rowKey, stampId },
+    signature: signMessage(buildAuthorizationMessage(`CadreControl.${tableName}`, 'remove', [rowKey, stampId])),
+    revocationSignature: signMessage(buildAuthorizationMessage('CadreControl.Revocation', 'remove', [tableName, rowKey, stampId])),
+  };
+}
+
 /** The control tables keyed by a strand id whose repeat insert a caller may treat as idempotent. */
 type StrandIdTable = Extract<RevocableTable, 'Strand' | 'JoinedStrand'>;
 
+/** The control tables keyed by an `Id` column whose repeat insert a caller may classify. */
+type IdKeyedTable = StrandIdTable | Extract<RevocableTable, 'PendingJoin'>;
+
 /**
- * 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`).
+ * The rejection a second insert of an already-seated 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`).
  *
  * 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.
+ * only the primary key can collide on a repeat insert. Matching the column explicitly
+ * keeps any OTHER uniqueness failure out of the caller's idempotency branch.
  */
-function strandIdConflictPattern(table: StrandIdTable): RegExp {
+function idConflictPattern(table: IdKeyedTable): RegExp {
   return new RegExp(`UNIQUE constraint failed: ${table}\\.Id\\b`, 'i');
 }
 
@@ -331,7 +364,46 @@ function strandIdConflictPattern(table: StrandIdTable): RegExp {
  * reword reddens there.
  */
 export function isStrandIdConflict(error: unknown, table: StrandIdTable): boolean {
-  return errorChainMatches(error, strandIdConflictPattern(table));
+  return errorChainMatches(error, idConflictPattern(table));
+}
+
+/**
+ * Did {@link ControlDatabase.insertPendingJoin} fail because the party already holds a
+ * `PendingJoin` row for this invitation? The caller adopts the existing row instead.
+ * Text-matched, failing closed, like {@link isStrandIdConflict}.
+ *
+ * NOTE: the existing row may be one {@link ControlDatabase.queryPendingJoin} hides (its stamp
+ * is retired and no reap pass has removed it yet), so an adopting re-read can come back empty
+ * until the next reap pass.
+ */
+export function isPendingJoinConflict(error: unknown): boolean {
+  return errorChainMatches(error, idConflictPattern('PendingJoin'));
+}
+
+/**
+ * The `PendingJoin.Id` of an invitation: the base64url sha256 `digest` of its token. One row
+ * per invitation, and the `Revocation` tombstone that names a removed row carries this, never
+ * the bearer token itself.
+ */
+export function pendingJoinId(token: string): string {
+  return digest([token], 'sha256', 'base64url') as string;
+}
+
+/**
+ * {@link ControlDatabase.replacePendingJoin} found that the live `PendingJoin` row is not the
+ * incarnation the caller read: another write replaced or removed it first (a sibling machine
+ * recorded an outcome, or the user dismissed the join). Nothing was written; the caller
+ * re-reads and decides again. `liveStampId` is null when the row is gone.
+ */
+export class PendingJoinChangedError extends Error {
+  constructor(
+    readonly id: string,
+    readonly expectedStampId: string,
+    readonly liveStampId: string | null,
+  ) {
+    super(`PendingJoin ${id} changed: expected stamp ${expectedStampId}, found ${liveStampId ?? 'no row'}`);
+    this.name = 'PendingJoinChangedError';
+  }
 }
 
 /**
@@ -348,7 +420,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 strandIdConflictPattern}), naming both columns of
+ * primary-key wording (see {@link idConflictPattern}), 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.
@@ -373,10 +445,12 @@ function errorChainMatches(error: unknown, pattern: RegExp): boolean {
  * secrets stored nowhere else (tickets/backlog/debt-strand-tombstone-reap.md owns any
  * 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.
+ * hold, so a reaped row is recoverable by re-forming. `PendingJoin` is reapable for the same
+ * reason: the inviting party and the user also hold its invitation. `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', 'JoinedStrand'] as const satisfies readonly RevocableTable[];
+export const REAPABLE_TABLES = ['CadrePeer', 'DeviceToken', 'ValidationKey', 'JoinedStrand', 'PendingJoin'] as const satisfies readonly RevocableTable[];
 export type ReapableTable = (typeof REAPABLE_TABLES)[number];
 
 /**
@@ -399,6 +473,53 @@ function joinedStrandRow(row: Record<string, SqlValue>): StrandRow {
   };
 }
 
+/** Every `PendingJoin` column, in the schema's order. */
+const PENDING_JOIN_COLUMNS = 'Id, Invitation, Disclosure, RequestedAt, ExpiresAt, Outcome, OutcomeAt, StrandId, MembershipInvite, FailureCode, FailureReason, StampId';
+
+const PENDING_JOIN_INSERT_SQL = `
+  insert into CadreControl.PendingJoin (${PENDING_JOIN_COLUMNS})
+    with context OwnerKey = ?, Signature = ?
+    values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`;
+
+/** A `PendingJoin` row as read; the schema's `KnownOutcome` check backs the `Outcome` cast. */
+function pendingJoinRow(row: Record<string, SqlValue>): PendingJoinRow {
+  return {
+    Id: row.Id as string,
+    Invitation: row.Invitation as string,
+    Disclosure: row.Disclosure as string,
+    RequestedAt: row.RequestedAt as number,
+    ExpiresAt: row.ExpiresAt as number,
+    Outcome: row.Outcome as PendingJoinRow['Outcome'],
+    OutcomeAt: row.OutcomeAt as number | null,
+    StrandId: row.StrandId as string | null,
+    MembershipInvite: row.MembershipInvite as string | null,
+    FailureCode: row.FailureCode as string | null,
+    FailureReason: row.FailureReason as string | null,
+    StampId: row.StampId as string,
+  };
+}
+
+/**
+ * The row fields `PendingJoin.AuthorizedInsert` signs, in the schema's order: a null column
+ * signs as `''` and an integer as its text (`cast(... as text)` on the SQL side).
+ */
+function pendingJoinAddFields(row: PendingJoinRow): string[] {
+  return [
+    row.Id, row.Invitation, row.Disclosure, String(row.RequestedAt), String(row.ExpiresAt),
+    row.Outcome ?? '', row.OutcomeAt === null ? '' : String(row.OutcomeAt), row.StrandId ?? '',
+    row.MembershipInvite ?? '', row.FailureCode ?? '', row.FailureReason ?? '', row.StampId,
+  ];
+}
+
+/** The values of {@link PENDING_JOIN_INSERT_SQL}'s columns, in {@link PENDING_JOIN_COLUMNS} order. */
+function pendingJoinValues(row: PendingJoinRow): SqlValue[] {
+  return [
+    row.Id, row.Invitation, row.Disclosure, row.RequestedAt, row.ExpiresAt, row.Outcome, row.OutcomeAt,
+    row.StrandId, row.MembershipInvite, row.FailureCode, row.FailureReason, row.StampId,
+  ];
+}
+
 /**
  * Notified after a `CadreControl.CadrePeer` row write has COMMITTED.
  *
@@ -928,6 +1049,31 @@ export class ControlDatabase {
     return rows.length === 0 ? null : joinedStrandRow(rows[0]!);
   }
 
+  /**
+   * Every join this party asked for and has not dismissed (`CadreControl.PendingJoin`),
+   * pending or finished.
+   *
+   * Rows whose `StampId` is retired in `Revocation` are dropped, as {@link queryCadrePeers}
+   * drops them: such a row is either a replaced or dismissed incarnation this node still
+   * holds until the reap sweep removes it, or one re-seated by a replayed approval on a node
+   * that had not yet seen the tombstone. Either way it must not bring a dismissed join back.
+   */
+  async queryPendingJoins(): Promise<PendingJoinRow[]> {
+    this.ensureInitialized();
+    const revoked = await this.queryRevokedStamps('PendingJoin');
+    const rows = await this.readRows(`select ${PENDING_JOIN_COLUMNS} from CadreControl.PendingJoin`, undefined, 'pending-joins');
+    return rows.map(pendingJoinRow).filter(row => !revoked.has(row.StampId));
+  }
+
+  /** Single-row sibling of {@link queryPendingJoins}, with the same retired-stamp filter: the row with this id, or null. */
+  async queryPendingJoin(id: string): Promise<PendingJoinRow | null> {
+    this.ensureInitialized();
+    const revoked = await this.queryRevokedStamps('PendingJoin');
+    const rows = await this.readRows(`select ${PENDING_JOIN_COLUMNS} from CadreControl.PendingJoin where Id = ?`, [id], 'pending-join');
+    const row = rows.length === 0 ? null : pendingJoinRow(rows[0]!);
+    return row === null || revoked.has(row.StampId) ? null : row;
+  }
+
   /**
    * Count rows in a CadreControl table as seen by THIS database instance.
    *
@@ -1531,13 +1677,10 @@ export class ControlDatabase {
    * one exists — the strand's `StrandPartyKey` delete + tombstone, all in ONE
    * transaction. A two-table sibling of {@link deleteGuardedRow} (see that method for the
    * per-clause security rationale: stamp read inside the locked body, `'remove'`-tagged
-   * digests, mandatory same-transaction tombstones); kept separate rather than
-   * generalizing the shared body because no other guarded table has a companion row.
-   *
-   * NOTE: that duplication is a drift risk, not a correctness one — a future tightening of
-   * {@link deleteGuardedRow}'s discipline (an extra precondition, a different digest shape)
-   * will NOT reach this body. Grep for both when you change either; if a second guarded
-   * table ever gains a companion row, generalize instead of copying this a third time.
+   * digests, mandatory same-transaction tombstones). Both sign through
+   * {@link signGuardedRemoval} and run {@link execGuardedRemoval}, so a change to the digest
+   * shape or the statement pair reaches this body; only the stamp reads and the companion-row
+   * branch are its own, because no other guarded table has a companion row.
    *
    * Not wrapped in {@link withWriteLock} — the caller holds the (non-re-entrant) lock.
    */
@@ -1555,45 +1698,23 @@ export class ControlDatabase {
     }
     const partyKeyStamp = await this.queryStampId('StrandPartyKey', strandId, false);
 
-    const strandSignature = signMessage(
-      buildAuthorizationMessage('CadreControl.Strand', 'remove', [strandId, strandStamp]));
-    const strandRevocationSignature = signMessage(
-      buildAuthorizationMessage('CadreControl.Revocation', 'remove', ['Strand', strandId, strandStamp]));
-    const partyKeySignature = partyKeyStamp === null ? null : signMessage(
-      buildAuthorizationMessage('CadreControl.StrandPartyKey', 'remove', [strandId, partyKeyStamp]));
-    const partyKeyRevocationSignature = partyKeyStamp === null ? null : signMessage(
-      buildAuthorizationMessage('CadreControl.Revocation', 'remove', ['StrandPartyKey', strandId, partyKeyStamp]));
+    const strandRemoval = signGuardedRemoval('Strand', strandId, strandStamp, signMessage);
+    const partyKeyRemoval = partyKeyStamp === null
+      ? null
+      : signGuardedRemoval('StrandPartyKey', strandId, partyKeyStamp, signMessage);
 
     await this.inTransaction('delete Strand', async () => {
-      await this.db!.exec(`
-        delete from CadreControl.Strand
-          with context OwnerKey = ?, Signature = ?
-          where Id = ?
-      `, [ownerKey, strandSignature, strandId]);
-      await this.db!.exec(`
-        insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
-          with context OwnerKey = ?, Signature = ?
-          values ('Strand', ?, ?, 0)
-      `, [ownerKey, strandRevocationSignature, strandId, strandStamp]);
-      if (partyKeyStamp !== null) {
-        await this.db!.exec(`
-          delete from CadreControl.StrandPartyKey
-            with context OwnerKey = ?, Signature = ?
-            where Id = ?
-        `, [ownerKey, partyKeySignature, strandId]);
-        await this.db!.exec(`
-          insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
-            with context OwnerKey = ?, Signature = ?
-            values ('StrandPartyKey', ?, ?, 0)
-        `, [ownerKey, partyKeyRevocationSignature, strandId, partyKeyStamp]);
+      await this.execGuardedRemoval(strandRemoval, ownerKey);
+      if (partyKeyRemoval !== null) {
+        await this.execGuardedRemoval(partyKeyRemoval, ownerKey);
       }
     });
 
     log('Strand deleted: %s (stamp retired%s)', strandId,
-      partyKeyStamp === null ? '' : '; party key deleted, stamp retired');
-    this.notifyGuardedDelete({ tableName: 'Strand', rowKey: strandId, stampId: strandStamp });
-    if (partyKeyStamp !== null) {
-      this.notifyGuardedDelete({ tableName: 'StrandPartyKey', rowKey: strandId, stampId: partyKeyStamp });
+      partyKeyRemoval === null ? '' : '; party key deleted, stamp retired');
+    this.notifyGuardedDelete(strandRemoval.ref);
+    if (partyKeyRemoval !== null) {
+      this.notifyGuardedDelete(partyKeyRemoval.ref);
     }
     return true;
   }
@@ -1710,6 +1831,100 @@ export class ControlDatabase {
     return this.lockedWithRetry(() => this.deleteGuardedRow('JoinedStrand', strandId, ownerKey, signMessage), {}, 'joined-strand-delete');
   }
 
+  /**
+   * Record, party-wide, a join this party asked for (`PendingJoin` row), using an owner
+   * signature over every column of the row (see {@link pendingJoinAddFields}). Returns the
+   * row as written, with the fresh `StampId` a later {@link replacePendingJoin} names.
+   *
+   * Fails with a `PendingJoin.Id` uniqueness violation when the party already holds a row for
+   * this invitation; {@link isPendingJoinConflict} identifies that case.
+   */
+  async insertPendingJoin(
+    row: Omit<PendingJoinRow, 'StampId'>,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<PendingJoinRow> {
+    this.ensureInitialized();
+    log('Inserting pending join: %s (outcome: %s)', row.Id, row.Outcome);
+    const { written, params } = this.signPendingJoinInsert(row, ownerKey, signMessage);
+    await this.execWrite(PENDING_JOIN_INSERT_SQL, params, 'pending-join-insert');
+    log('Pending join inserted: %s', row.Id);
+    return written;
+  }
+
+  /**
+   * Replace the live `PendingJoin` row `next.Id` with `next`, under a fresh stamp — the only way
+   * an outcome is written, since the table refuses updates. Returns the row as written.
+   *
+   * One locked transaction deletes the row (owner-signed `'remove'` digest, with its
+   * `Revocation` tombstone) and inserts its successor, so no reader ever sees the id missing in
+   * between. The live row must still be the incarnation the caller read: when its `StampId` is
+   * not `expectedStampId`, or the row is gone, this throws {@link PendingJoinChangedError} and
+   * writes nothing. That check is local; a sibling machine's replacement or removal that lands
+   * between it and the commit fails the transaction instead (its tombstone for the same stamp,
+   * or its successor row, collides on a primary key), and the caller re-reads either way.
+   *
+   * Signatures and the new stamp are minted before the lock, so a retried attempt re-presents
+   * the same signed messages (the contract on {@link withWriteLock}). A retry after an attempt
+   * that committed but reported failure throws {@link PendingJoinChangedError} whose
+   * `liveStampId` is the returned row's own stamp, so a caller that re-reads finds its write.
+   */
+  async replacePendingJoin(
+    expectedStampId: string,
+    next: Omit<PendingJoinRow, 'StampId'>,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<PendingJoinRow> {
+    this.ensureInitialized();
+    const id = next.Id;
+    const removal = signGuardedRemoval('PendingJoin', id, expectedStampId, signMessage);
+    const { written, params } = this.signPendingJoinInsert(next, ownerKey, signMessage);
+
+    return this.lockedWithRetry(async () => {
+      // retry: false — this runs inside the locked write body (see queryStampId's NOTE).
+      const liveStampId = await this.queryStampId('PendingJoin', id, false);
+      if (liveStampId !== expectedStampId) {
+        throw new PendingJoinChangedError(id, expectedStampId, liveStampId);
+      }
+      await this.inTransaction('replace PendingJoin', async () => {
+        await this.execGuardedRemoval(removal, ownerKey);
+        await this.db!.exec(PENDING_JOIN_INSERT_SQL, params);
+      });
+      log('Pending join replaced: %s (outcome: %s; stamp retired)', id, next.Outcome);
+      this.notifyGuardedDelete(removal.ref);
+      return written;
+    }, {}, 'pending-join-replace');
+  }
+
+  /**
+   * Owner-signed removal of one `PendingJoin` row, as {@link deleteJoinedStrand} removes its
+   * row: `'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.
+   */
+  deletePendingJoin(
+    id: string,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): Promise<boolean> {
+    return this.lockedWithRetry(() => this.deleteGuardedRow('PendingJoin', id, ownerKey, signMessage), {}, 'pending-join-delete');
+  }
+
+  /**
+   * Mint a fresh stamp for `row` and the owner signature `PendingJoin.AuthorizedInsert`
+   * verifies, returning the row as it will be written and the parameters of
+   * {@link PENDING_JOIN_INSERT_SQL}.
+   */
+  private signPendingJoinInsert(
+    row: Omit<PendingJoinRow, 'StampId'>,
+    ownerKey: string,
+    signMessage: (message: Uint8Array) => string
+  ): { written: PendingJoinRow; params: SqlValue[] } {
+    const written: PendingJoinRow = { ...row, StampId: generateStampId(this.config.libp2pNode.peerId.toString()) };
+    const signature = signMessage(buildAuthorizationMessage('CadreControl.PendingJoin', 'add', pendingJoinAddFields(written)));
+    return { written, params: [ownerKey, signature, ...pendingJoinValues(written)] };
+  }
+
   /**
    * Insert a validation key into the control database using an owner signature.
    *
@@ -2001,12 +2216,9 @@ export class ControlDatabase {
    *
    * Deliberately NOT wrapped in {@link withWriteLock}: every public entry point already
    * holds the (non-re-entrant) lock, so taking it again here would self-deadlock.
-   *
-   * `table` and its {@link GUARDED_KEY_COLUMN} column are interpolated into the SQL; both
-   * come from closed literal unions — no caller-supplied string reaches the statement.
    */
   private async deleteGuardedRow(
-    table: Exclude<RevocableTable, 'OwnerKey'>,
+    table: RemovableTable,
     keyValue: string,
     ownerKey: string,
     signMessage: (message: Uint8Array) => string
@@ -2019,36 +2231,44 @@ export class ControlDatabase {
       return false;
     }
 
-    const message = buildAuthorizationMessage(`CadreControl.${table}`, 'remove', [keyValue, stampId]);
-    const signature = signMessage(message);
-    // The tombstone carries its OWN owner signature (`Revocation.Authorized`): retiring a
-    // stamp is permanent and party-wide, so the delete's signature deliberately does not
-    // cover it — the digests are domain-separated and neither replays as the other.
-    const revocationSignature = signMessage(
-      buildAuthorizationMessage('CadreControl.Revocation', 'remove', [table, keyValue, stampId]),
-    );
-
-    await this.inTransaction(`delete ${table}`, async () => {
-      await this.db!.exec(`
-        delete from CadreControl.${table}
-          with context OwnerKey = ?, Signature = ?
-          where ${GUARDED_KEY_COLUMN[table]} = ?
-      `, [ownerKey, signature, keyValue]);
-      // ReissuedAt named explicitly at 0 (the only value FreshTombstone accepts) rather
-      // than leaning on the column default — the seat-at-zero rule is load-bearing for
-      // reissueRevocations' monotonic bump, so state it at the write site.
-      await this.db!.exec(`
-        insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
-          with context OwnerKey = ?, Signature = ?
-          values (?, ?, ?, 0)
-      `, [ownerKey, revocationSignature, table, keyValue, stampId]);
-    });
+    const removal = signGuardedRemoval(table, keyValue, stampId, signMessage);
+    await this.inTransaction(`delete ${table}`, () => this.execGuardedRemoval(removal, ownerKey));
 
     log('%s deleted: %s (stamp retired)', table, keyValue);
-    this.notifyGuardedDelete({ tableName: table, rowKey: keyValue, stampId });
+    this.notifyGuardedDelete(removal.ref);
     return true;
   }
 
+  /**
+   * Delete the row incarnation `removal` names and file its tombstone — the statement pair
+   * every owner removal of a guarded row runs ({@link deleteGuardedRow},
+   * {@link deleteStrandAndPartyKey}, {@link replacePendingJoin}). The caller supplies the
+   * transaction: the schema's `RevocationRecorded` check refuses the delete unless the
+   * tombstone commits with it.
+   *
+   * The delete matches the stamp as well as the key, so it can only ever remove the
+   * incarnation the signature names.
+   *
+   * `tableName` and its {@link GUARDED_KEY_COLUMN} column are interpolated into the SQL; both
+   * come from closed literal unions — no caller-supplied string reaches the statement.
+   */
+  private async execGuardedRemoval(removal: GuardedRemoval, ownerKey: string): Promise<void> {
+    const { tableName, rowKey, stampId } = removal.ref;
+    await this.db!.exec(`
+      delete from CadreControl.${tableName}
+        with context OwnerKey = ?, Signature = ?
+        where ${GUARDED_KEY_COLUMN[tableName]} = ? and StampId = ?
+    `, [ownerKey, removal.signature, rowKey, stampId]);
+    // ReissuedAt named explicitly at 0 (the only value FreshTombstone accepts) rather
+    // than leaning on the column default — the seat-at-zero rule is load-bearing for
+    // reissueRevocations' monotonic bump, so state it at the write site.
+    await this.db!.exec(`
+      insert into CadreControl.Revocation (TableName, RowKey, StampId, ReissuedAt)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, 0)
+    `, [ownerKey, removal.revocationSignature, tableName, rowKey, stampId]);
+  }
+
   /**
    * Fire the guarded-delete listener for one committed tombstone, swallowing (and
    * logging) a listener throw — a committed delete never fails because bookkeeping did.
@@ -2186,7 +2406,8 @@ 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` and `JoinedStrand` have no self notion and are not special-cased.
+   *   `ValidationKey`, `JoinedStrand` and `PendingJoin` 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

package/src/control-formation-recorder.ts

@@ -39,8 +39,8 @@ const NEVER_EXPIRES = new Date(8640000000000000);
  *   ATOMICALLY (one `FormationUsage` row), closing the single-use hole the older
  *   never-record fallback left open.
  *
- * This replaces the in-memory stubs used by the formation tests so the consent path
- * is exercised against the persisted control network.
+ * Every `CadreNode`'s formation responder uses it unless the embedder passes another
+ * recorder to `initializeStrandSolicitation`.
  *
  * Usage accounting follows the schema's `FormationUsage.Authorized` semantics:
  * a null `TotalUses` means unlimited uses; otherwise the invite is "used up"
@@ -59,10 +59,9 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
   private readonly approver: FormationApprover;
 
   /**
-   * `approver` defaults to the real HTTP hook client — deliberately ON: this recorder is
-   * constructed by the reference apps and the integration harness, not by `CadreNode`, so an
-   * opt-in approver would leave every real deployment unable to redeem a
-   * `ValidationUrl`-bearing invite. Tests inject a fake.
+   * `approver` defaults to the real HTTP hook client — deliberately ON: `CadreNode` builds this
+   * recorder for every node's responder with no options, so an opt-in approver would leave
+   * every real deployment unable to redeem a `ValidationUrl`-bearing invite. Tests inject a fake.
    */
   constructor(
     private readonly controlDatabase: ControlDatabase,
@@ -72,14 +71,14 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
   }
 
   /** A token is valid when a matching, unexpired `FormationInvite` exists. */
-  async isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }> {
+  async isTokenValid(token: string): Promise<{ valid: boolean; reason?: 'unknown' | 'expired'; invitation?: OpenInvitation }> {
     const invite = await this.controlDatabase.queryFormationInvite(token);
     if (!invite) {
-      return { valid: false };
+      return { valid: false, reason: 'unknown' };
     }
     if (invite.expiresAtMs !== null && invite.expiresAtMs <= Date.now()) {
       log('Token expired: %s', token);
-      return { valid: false };
+      return { valid: false, reason: 'expired' };
     }
     return {
       valid: true,

package/src/control-schema.ts

@@ -424,6 +424,92 @@ declare schema CadreControl {
         )
     ) with context (OwnerKey text, Signature text);
 
+    -- A join THIS party asked for, by redeeming another party's invitation, that it has not
+    -- finished yet, or has finished and not yet dismissed. Party-wide rather than kept on the
+    -- device that asked, so the attempt outlives that device and any owner machine of the party
+    -- can carry it on and record how it ended. Invitation is a bearer credential and
+    -- MembershipInvite a single-use one; both are replicated in plaintext to every machine the
+    -- party owns, under the same accepted risk as JoinedStrand.MemberPrivateKey (docs/strands.md
+    -- → "Closed-Strand Member Key Handling").
+    -- Every write is a whole-row insert or delete: recording an outcome deletes the row (with its
+    -- tombstone) and inserts its successor under a fresh stamp in one transaction
+    -- (ControlDatabase.replacePendingJoin). Which outcome may follow which is CadreNode policy,
+    -- not a rule here, because every writer is an owner.
+    -- Carries a REAP branch, like JoinedStrand, because nothing here is stored only here: the
+    -- inviting party holds the FormationInvite row, the user holds the shared link, and the
+    -- membership invitation is a copy of what the inviter issued.
+    table PendingJoin (
+        Id text primary key,            -- base64url sha256 of the invitation token (cadre-core's
+                                        -- pendingJoinId): one row per invitation, and the Revocation
+                                        -- tombstone that names a removed row never holds the token.
+        Invitation text not null,       -- CadreNode.encodeInvitation: token, sAppId, expiration and
+                                        -- bootstrap addresses. A few kilobytes at most, since
+                                        -- createOpenInvitation caps the addresses an invitation carries.
+        Disclosure text not null,       -- canonicalJson of the disclosure the requester gave; the
+                                        -- formation sets partyId itself on each attempt
+        RequestedAt integer not null,   -- epoch ms
+        ExpiresAt integer not null,     -- epoch ms; no attempt starts at or after it
+        Outcome text null,              -- null while pending | 'joined' | 'failed'
+        OutcomeAt integer null,         -- epoch ms the outcome was recorded
+        StrandId text null,             -- 'joined': the strand the formation returned
+        MembershipInvite text null,     -- 'joined', closed strand only: JSON {inviteKey, invitePrivateKey},
+                                        -- the StrandMembershipInvite the formation delivered
+        FailureCode text null,          -- 'failed': a FormationRejectionCode, 'expired' or 'local'
+        FailureReason text null,        -- 'failed': human-readable text
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay).
+                                        -- \`unique\` holds over LIVE rows only; a removed row's stamp is
+                                        -- retired permanently into Revocation (NotRevoked below).
+        -- The approval that seated a removed row can never re-seat it, so a dismissed or replaced
+        -- row cannot be brought back. Same rationale as OwnerKey.NotRevoked, stated in full there.
+        constraint NotRevoked check on insert (
+            not exists (select 1 from Revocation R where R.TableName = 'PendingJoin' and R.StampId = new.StampId)
+        ),
+        -- A delete must file its correctly named tombstone in the same transaction. Same
+        -- rationale as StrandPartyKey.RevocationRecorded.
+        constraint RevocationRecorded check on delete (
+            exists (select 1 from Revocation R where R.TableName = 'PendingJoin' and R.StampId = old.StampId and R.RowKey = old.Id)
+        ),
+        -- Insert + delete only: neither Authorized rule below covers update, so an in-place
+        -- rewrite would change the outcome unsigned. Mirrors StrandPartyKey.NoUpdate.
+        constraint NoUpdate check on update (false),
+        -- Readers cast Outcome to null | 'joined' | 'failed' (ControlDatabase.queryPendingJoins).
+        constraint KnownOutcome check (new.Outcome is null or new.Outcome = 'joined' or new.Outcome = 'failed'),
+        -- Each outcome carries exactly its own columns, so a reader can trust the shape it reads.
+        constraint OutcomeShape check (
+            (new.Outcome is null
+                and new.OutcomeAt is null and new.StrandId is null and new.MembershipInvite is null
+                and new.FailureCode is null and new.FailureReason is null)
+            or (new.Outcome = 'joined'
+                and new.OutcomeAt is not null and new.StrandId is not null
+                and new.FailureCode is null and new.FailureReason is null)
+            or (new.Outcome = 'failed'
+                and new.OutcomeAt is not null and new.FailureCode is not null
+                and new.StrandId is null and new.MembershipInvite is null)
+        ),
+        constraint AuthorizedInsert check on insert (
+            -- Owners authorize by signing over THIS row, every column ending in StampId; nullable
+            -- columns sign as '' and integers as their text, so a captured approval can only
+            -- reproduce the exact row it approved. Owner-signed only: whether a machine that is
+            -- not an owner may record an outcome is an open decision
+            -- (tickets/blocked/decide-non-owner-machine-completes-a-pending-join.md).
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.PendingJoin', 'add',
+                new.Id, new.Invitation, new.Disclosure, cast(new.RequestedAt as text), cast(new.ExpiresAt as text),
+                coalesce(new.Outcome, ''), coalesce(cast(new.OutcomeAt as text), ''), coalesce(new.StrandId, ''),
+                coalesce(new.MembershipInvite, ''), coalesce(new.FailureCode, ''), coalesce(new.FailureReason, ''),
+                new.StampId), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedDelete check on delete (
+            -- 'remove'-tagged digest over the STORED row (Id, StampId), so the add approval can
+            -- never be replayed as a removal.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.PendingJoin', 'remove', old.Id, old.StampId), context.Signature, A.Key, 'ed25519'))
+
+                -- or REAP: a COMMITTED tombstone already retires this exact row incarnation.
+                -- Why committed.* and why the stamp is bound: stated in full on
+                -- CadrePeer.AuthorizedDelete. Allowed for the reason the table comment gives.
+                or exists (select 1 from committed.Revocation R where R.TableName = 'PendingJoin' and R.RowKey = old.Id and R.StampId = old.StampId)
+        )
+    ) with context (OwnerKey text, Signature text);
+
     -- A peer (node) that is part of the cadre, carrying a self-published,
     -- freshness-stamped, self-signed address record (see PeerAddressRecord in cadre-core).
     -- The row IS the peer-address record: a resolver reads it, re-verifies Sig against
@@ -875,11 +961,11 @@ declare schema CadreControl {
     -- skips the marker, so nothing reaps or re-issues it.
     table Revocation (
         TableName text,             -- 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' |
-                                    -- 'JoinedStrand' | 'DeviceToken', or 'Revocation' for the ledger marker only
-                                    -- (all confined by RowIsGone below)
+                                    -- 'JoinedStrand' | 'PendingJoin' | 'DeviceToken', or 'Revocation' for the
+                                    -- ledger marker only (all confined by RowIsGone below)
         RowKey text not null,       -- primary key of the removed row: OwnerKey.Key / ValidationKey.Key /
                                     -- CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id / StrandPartyKey.Id /
-                                    -- JoinedStrand.Id
+                                    -- JoinedStrand.Id / PendingJoin.Id
                                     -- Every guarded table's RevocationRecorded CHECK requires the
                                     -- accompanying tombstone to carry the removed row's key here, so
                                     -- a REMOVAL cannot file a misnamed tombstone. A tombstone with no
@@ -931,6 +1017,7 @@ declare schema CadreControl {
                 or (new.TableName = 'Strand' and not exists (select 1 from Strand S where S.StampId = new.StampId))
                 or (new.TableName = 'StrandPartyKey' and not exists (select 1 from StrandPartyKey K where K.StampId = new.StampId))
                 or (new.TableName = 'JoinedStrand' and not exists (select 1 from JoinedStrand J where J.StampId = new.StampId))
+                or (new.TableName = 'PendingJoin' and not exists (select 1 from PendingJoin P where P.StampId = new.StampId))
                 or (new.TableName = 'DeviceToken' and not exists (select 1 from DeviceToken D where D.StampId = new.StampId))
                 or (new.TableName = 'Revocation' and new.RowKey = 'ledger' and new.StampId = 'opened')
         ),