@serfab/cadre-core 1.9.0 → 1.11.0

package/dist/control-authorization.d.ts

@@ -33,7 +33,7 @@
  * CHECK the `'reissue'`-tagged digest `ControlDatabase.reissueRevocations`
  * signs — and `countRows` counts it.
  */
-export declare const CONTROL_TABLES: readonly ["OwnerKey", "ValidationKey", "Strand", "StrandPartyKey", "JoinedStrand", "CadrePeer", "DeviceToken", "FormationInvite", "FormationUsage", "Revocation"];
+export declare const CONTROL_TABLES: readonly ["OwnerKey", "ValidationKey", "Strand", "StrandPartyKey", "JoinedStrand", "PendingJoin", "CadrePeer", "DeviceToken", "FormationInvite", "FormationUsage", "Revocation"];
 /**
  * Name of a CadreControl table. Doubles as the table half of a
  * {@link ControlDomain} tag.
@@ -51,7 +51,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' | 'JoinedStrand' | 'DeviceToken'>;
+export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' | 'PendingJoin' | 'DeviceToken'>;
 /**
  * What a signature authorizes, scoped to one table rule — or, for
  * `'Cadre.Enrollment'`, the offline peer vouch that `cadre enroll register`

package/dist/control-authorization.js

@@ -39,6 +39,7 @@ export const CONTROL_TABLES = [
     'Strand',
     'StrandPartyKey',
     'JoinedStrand',
+    'PendingJoin',
     'CadrePeer',
     'DeviceToken',
     'FormationInvite',

package/dist/control-authorization.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-authorization.js","sourceRoot":"","sources":["../src/control-authorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,eAAe;IACf,QAAQ;IACR,gBAAgB;IAChB,cAAc;IACd,WAAW;IACX,aAAa;IACb,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;CACJ,CAAC;AAsDX;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAqB,EACrB,MAAqB,EACrB,SAAmB;IAEnB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"control-authorization.js","sourceRoot":"","sources":["../src/control-authorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,eAAe;IACf,QAAQ;IACR,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;CACJ,CAAC;AAsDX;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAqB,EACrB,MAAqB,EACrB,SAAmB;IAEnB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AACxC,CAAC"}

package/dist/control-cohort.d.ts

@@ -29,7 +29,7 @@ import type { CohortPeerRow } from './strand-cohort.js';
  * 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
+ * sibling's dial alone can take the whole per-peer dial budget (86 s at the
  * default declared link).
  */
 export declare const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;

package/dist/control-cohort.js

@@ -29,7 +29,7 @@ import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
  * 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
+ * sibling's dial alone can take the whole per-peer dial budget (86 s at the
  * default declared link).
  */
 export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;

package/dist/control-database.d.ts

@@ -2,7 +2,7 @@ import { Database } from '@quereus/quereus';
 import type { SqlParameters } from '@quereus/quereus';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow } from './types.js';
+import type { StrandRow, PendingJoinRow, PeerAddressRecord, CadrePeerRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow } from './types.js';
 import type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
@@ -175,6 +175,34 @@ type StrandIdTable = Extract<RevocableTable, 'Strand' | 'JoinedStrand'>;
  * reword reddens there.
  */
 export declare function isStrandIdConflict(error: unknown, table: StrandIdTable): boolean;
+/**
+ * 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 declare function isPendingJoinConflict(error: unknown): boolean;
+/**
+ * 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 declare function pendingJoinId(token: string): 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 declare class PendingJoinChangedError extends Error {
+    readonly id: string;
+    readonly expectedStampId: string;
+    readonly liveStampId: string | null;
+    constructor(id: string, expectedStampId: string, liveStampId: string | null);
+}
 /**
  * The one `CadreControl.Revocation` row that retires nothing, filed once by an owner
  * ({@link ControlDatabase.openRevocationLedger}) so the table is never a never-written
@@ -194,10 +222,12 @@ export declare const REVOCATION_LEDGER_MARKER: {
  * 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 declare const REAPABLE_TABLES: readonly ["CadrePeer", "DeviceToken", "ValidationKey", "JoinedStrand"];
+export declare const REAPABLE_TABLES: readonly ["CadrePeer", "DeviceToken", "ValidationKey", "JoinedStrand", "PendingJoin"];
 export type ReapableTable = (typeof REAPABLE_TABLES)[number];
 /**
  * Notified after a `CadreControl.CadrePeer` row write has COMMITTED.
@@ -445,6 +475,18 @@ export declare class ControlDatabase {
     queryJoinedStrands(): Promise<StrandRow[]>;
     /** Single-row sibling of {@link queryJoinedStrands}: the joined strand with this id, or null. */
     queryJoinedStrand(strandId: string): Promise<StrandRow | null>;
+    /**
+     * 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.
+     */
+    queryPendingJoins(): Promise<PendingJoinRow[]>;
+    /** Single-row sibling of {@link queryPendingJoins}, with the same retired-stamp filter: the row with this id, or null. */
+    queryPendingJoin(id: string): Promise<PendingJoinRow | null>;
     /**
      * Count rows in a CadreControl table as seen by THIS database instance.
      *
@@ -786,13 +828,10 @@ export declare 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.
      */
@@ -847,6 +886,46 @@ export declare class ControlDatabase {
      * then, `true` when a row was actually removed.
      */
     deleteJoinedStrand(strandId: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    insertPendingJoin(row: Omit<PendingJoinRow, 'StampId'>, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<PendingJoinRow>;
+    /**
+     * 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.
+     */
+    replacePendingJoin(expectedStampId: string, next: Omit<PendingJoinRow, 'StampId'>, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<PendingJoinRow>;
+    /**
+     * 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>;
+    /**
+     * 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;
     /**
      * Insert a validation key into the control database using an owner signature.
      *
@@ -1035,11 +1114,22 @@ export declare 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.
+     */
+    private deleteGuardedRow;
+    /**
+     * 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.
      *
-     * `table` and its {@link GUARDED_KEY_COLUMN} column are interpolated into the SQL; both
+     * 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 deleteGuardedRow;
+    private execGuardedRemoval;
     /**
      * Fire the guarded-delete listener for one committed tombstone, swallowing (and
      * logging) a listener throw — a committed delete never fails because bookkeeping did.
@@ -1130,7 +1220,8 @@ export declare 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/dist/control-database.js

@@ -213,18 +213,26 @@ const GUARDED_KEY_COLUMN = {
     Strand: 'Id',
     StrandPartyKey: 'Id',
     JoinedStrand: 'Id',
+    PendingJoin: 'Id',
     DeviceToken: 'PeerId',
 };
+function signGuardedRemoval(tableName, rowKey, stampId, signMessage) {
+    return {
+        ref: { tableName, rowKey, stampId },
+        signature: signMessage(buildAuthorizationMessage(`CadreControl.${tableName}`, 'remove', [rowKey, stampId])),
+        revocationSignature: signMessage(buildAuthorizationMessage('CadreControl.Revocation', 'remove', [tableName, rowKey, stampId])),
+    };
+}
 /**
- * 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) {
+function idConflictPattern(table) {
     return new RegExp(`UNIQUE constraint failed: ${table}\\.Id\\b`, 'i');
 }
 /**
@@ -243,7 +251,42 @@ function strandIdConflictPattern(table) {
  * reword reddens there.
  */
 export function isStrandIdConflict(error, table) {
-    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) {
+    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) {
+    return digest([token], 'sha256', 'base64url');
+}
+/**
+ * {@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(id, expectedStampId, liveStampId) {
+        super(`PendingJoin ${id} changed: expected stamp ${expectedStampId}, found ${liveStampId ?? 'no row'}`);
+        this.id = id;
+        this.expectedStampId = expectedStampId;
+        this.liveStampId = liveStampId;
+        this.name = 'PendingJoinChangedError';
+    }
 }
 /**
  * The one `CadreControl.Revocation` row that retires nothing, filed once by an owner
@@ -258,7 +301,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.
@@ -280,10 +323,12 @@ function errorChainMatches(error, pattern) {
  * 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'];
+export const REAPABLE_TABLES = ['CadrePeer', 'DeviceToken', 'ValidationKey', 'JoinedStrand', 'PendingJoin'];
 /**
  * Runtime membership test for {@link REAPABLE_TABLES}, narrowing a tombstone's
  * `TableName` to the subset {@link ControlDatabase.reapRevokedRow} accepts. A tombstone
@@ -302,6 +347,48 @@ function joinedStrandRow(row) {
         FounderOwnerKey: null,
     };
 }
+/** 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) {
+    return {
+        Id: row.Id,
+        Invitation: row.Invitation,
+        Disclosure: row.Disclosure,
+        RequestedAt: row.RequestedAt,
+        ExpiresAt: row.ExpiresAt,
+        Outcome: row.Outcome,
+        OutcomeAt: row.OutcomeAt,
+        StrandId: row.StrandId,
+        MembershipInvite: row.MembershipInvite,
+        FailureCode: row.FailureCode,
+        FailureReason: row.FailureReason,
+        StampId: row.StampId,
+    };
+}
+/**
+ * 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) {
+    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) {
+    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,
+    ];
+}
 /**
  * ControlDatabase manages the CadreControl schema using Quereus with Optimystic backend.
  * It provides typed query methods for accessing control network data.
@@ -722,6 +809,29 @@ export class ControlDatabase {
         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]);
     }
+    /**
+     * 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() {
+        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) {
+        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.
      *
@@ -1270,13 +1380,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.
      */
@@ -1289,38 +1396,20 @@ export class ControlDatabase {
             return false;
         }
         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 });
+        log('Strand deleted: %s (stamp retired%s)', strandId, partyKeyRemoval === null ? '' : '; party key deleted, stamp retired');
+        this.notifyGuardedDelete(strandRemoval.ref);
+        if (partyKeyRemoval !== null) {
+            this.notifyGuardedDelete(partyKeyRemoval.ref);
         }
         return true;
     }
@@ -1407,6 +1496,78 @@ export class ControlDatabase {
     deleteJoinedStrand(strandId, ownerKey, signMessage) {
         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, ownerKey, signMessage) {
+        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, next, ownerKey, signMessage) {
+        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, ownerKey, signMessage) {
+        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}.
+     */
+    signPendingJoinInsert(row, ownerKey, signMessage) {
+        const written = { ...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.
      *
@@ -1652,9 +1813,6 @@ 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.
      */
     async deleteGuardedRow(table, keyValue, ownerKey, signMessage) {
         this.ensureInitialized();
@@ -1664,31 +1822,41 @@ export class ControlDatabase {
             log('delete %s: no row for %s (already absent)', table, keyValue);
             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.
+     */
+    async execGuardedRemoval(removal, ownerKey) {
+        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.
@@ -1826,7 +1994,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