@serfab/cadre-core 0.9.0 → 0.10.0

package/dist/strand-membership-writer.d.ts

@@ -18,18 +18,17 @@ export declare const STRAND_ENGINE = "quereus";
  */
 export declare const STRAND_ENGINE_VERSION = "0.1.0";
 /**
- * The single-digest ed25519 signer the `Strand.*` membership/RBAC constraints
- * verify against.
+ * The single-payload ed25519 signer the `Strand.Invite`/`Strand.ConsumedInvite`
+ * handshake constraints verify against.
  *
- * `schemas/strand.qsql` signs a single SHA-256 digest over a `'|'`-joined payload
- * (e.g. `Member.Authorized` verifies
- * `verify(digest(new.Key), context.ManagerSignature, A.MemberKey, 'ed25519')`).
+ * Those constraints sign a single SHA-256 digest over a `'|'`-joined payload
+ * (e.g. `InviteValid` verifies
+ * `verify(digest(new.Key || '|' || coalesce(new.Expiration, '')), ...)`).
  * So the signer hashes the payload to raw bytes and ed25519-signs *those bytes*:
  * SQL `digest(...)`'s default output is base64url and `verify(...)`'s default
  * `inputEncoding` is base64url, so signer and verifier operate on identical bytes.
- * This differs from the control-layer's multi-field `buildAuthorizationMessage`
- * (a single digest over MANY fields) — the strand layer is a single digest over ONE
- * joined payload field.
+ * The membership/RBAC tables (Member/Manager/MemberPeer/Revocation) instead use
+ * domain/action-tagged VARIADIC digests — see {@link signStrandApproval}.
  *
  * All strand keys are ed25519, so the explicit `'ed25519'` curve arg is mandatory
  * (the crypto plugin otherwise defaults to secp256k1). Mirrors the proven
@@ -43,7 +42,7 @@ export declare function signStrandPayload(payload: string, privateKeyB64: string
 /**
  * The verifier counterpart to {@link signStrandPayload}.
  *
- * Mirrors what every `Strand.*` constraint computes:
+ * Mirrors what the single-payload `Strand.*` constraints compute:
  * `verify(digest(payload), signature, publicKey, 'ed25519')`.
  * SQL `digest`'s default output and `verify`'s default `inputEncoding`/`sigEncoding`/
  * `keyEncoding` are all base64url, so the off-engine check operates on the exact
@@ -57,6 +56,50 @@ export declare function signStrandPayload(payload: string, privateKeyB64: string
  * @returns `true` iff the signature is valid for the payload under that key.
  */
 export declare function verifyStrandPayload(payload: string, signatureB64: string, publicKeyB64: string): boolean;
+/**
+ * Sign a domain/action-tagged `Strand.*` membership/RBAC approval.
+ *
+ * Every `Authorized` branch on `Member`/`Manager`/`MemberPeer`/`Revocation`
+ * verifies a VARIADIC digest — `digest('<domain>', '<action>', <field>, ...,
+ * <StampId>)` — whose leading two elements are fixed literals (the domain tag,
+ * e.g. `'Strand.Member'`, and an action tag, e.g. `'add'`) and whose trailing
+ * element is the row's per-incarnation StampId. The tags keep an approval from
+ * verifying against any rule but the one it was minted for (the idiom of the
+ * control layer's `buildAuthorizationMessage`); the StampId binding makes it
+ * single-use — it authorizes exactly one incarnation of one row, and dies when
+ * that row's stamp is retired into `Strand.Revocation`.
+ *
+ * The caller passes the digest elements exactly as the matching SQL constraint
+ * lists them (each SQL argument = one array element), PRESERVING TYPE: the
+ * crypto plugin's digest framing is type-tagged (INTEGER 1 and TEXT '1' encode
+ * differently, deliberately), so `Manager.Authorized`'s promotion branch —
+ * whose digest includes the INTEGER `new.Generation` — must be signed over the
+ * NUMBER, not its string form. Integer `number` and `bigint` encode
+ * identically in that framing, so JS-side numbers match however the engine
+ * represents the SQL integer.
+ *
+ * Like {@link signStrandPayload}, the raw digest BYTES are ed25519-signed
+ * directly, matching SQL `verify(...)`'s default base64url input decoding.
+ *
+ * @param fields - The digest elements, in constraint order (tags first, StampId last).
+ * @param privateKeyB64 - The signer's base64url ed25519 private seed.
+ * @returns The base64url ed25519 signature over the tagged digest.
+ */
+export declare function signStrandApproval(fields: ReadonlyArray<string | number>, privateKeyB64: string): string;
+/**
+ * Mint a fresh per-row authorization nonce (StampId) for a `Strand.Member`,
+ * `Strand.Manager`, or `Strand.MemberPeer` row.
+ *
+ * 256 bits of CSPRNG output, base64url-encoded — enough entropy that a future
+ * legitimate stamp cannot be guessed and pre-planted into `Strand.Revocation`
+ * (the `RowIsGone` comment in `schemas/strand.qsql` leans on exactly this).
+ * Plain randomness, deliberately NOT the control layer's peer-derived
+ * `generateStampId`: strand rows are not per-peer, so entropy alone carries
+ * the uniqueness.
+ *
+ * @returns A fresh base64url stamp (43 chars for 32 bytes).
+ */
+export declare function generateStrandStampId(): string;
 /** Parameters for {@link bootstrapFounderMembership}. */
 export interface FounderBootstrapParams {
     /** The strand id — written to `Header.Id`. */
@@ -165,8 +208,8 @@ export interface ConsumeInviteParams {
  * Redeem an invite to admit a new `Member`, atomically.
  *
  * `Member.Authorized`'s invite branch needs a `ConsumedInvite` row, while
- * `ConsumedInvite`'s `MemberExists`/`MemberValid` need the `Member` row — a
- * circular dependency. Both are deferred (subquery-bearing) checks that evaluate
+ * `ConsumedInvite`'s `MemberExists` needs the `Member` row — a circular
+ * dependency. Both are deferred (subquery-bearing) checks that evaluate
  * at COMMIT, so inserting `Member` then `ConsumedInvite` inside one explicit
  * transaction lets both rows exist when the deferred checks fire. This mirrors
  * `ControlDatabase.redeemInvitation` (Strand + FormationUsage in one txn).
@@ -174,7 +217,9 @@ export interface ConsumeInviteParams {
  * The `ConsumedInvite` insert carries an `InviteSignature` over
  * `InviteKey || '|' || MemberKey`, proving the consumer holds the invite private
  * key (the on-engine `ValidUsage` gate). The `Member` insert needs no member
- * signature — its admission is the existence of the matching `ConsumedInvite`.
+ * signature — its admission is the existence of the matching `ConsumedInvite` —
+ * but still mints a fresh StampId (NOT NULL on every path; a revoked-then-
+ * re-invited member is a fresh incarnation under a fresh stamp).
  *
  * Single-use: `ConsumedInvite`'s primary key is `InviteKey`, so a second consume
  * of the same invite is rejected by the PK (a distinct layer from the control
@@ -204,11 +249,101 @@ export interface ConsumeInviteParams {
  *   `ConsumedInvite` row survives).
  */
 export declare function consumeInvite(db: Database, params: ConsumeInviteParams): Promise<void>;
+/** Parameters for {@link cancelInvite}. */
+export interface CancelInviteParams {
+    /**
+     * The cancelling manager's strand keypair. Its `publicKeyB64` must be a
+     * PRE-EXISTING `Strand.Manager` row — `CancelledInvite.Authorized` reads
+     * `committed.Manager`, so a manager seated in the SAME transaction cannot cancel.
+     */
+    managerKeyPair: Ed25519KeyPair;
+    /** The `Invite.Key` to kill. */
+    inviteKey: string;
+}
+/**
+ * Cancel an outstanding invitation, permanently: it may never be consumed.
+ *
+ * Files a `Strand.CancelledInvite` tombstone carrying a manager signature over
+ * `digest('Strand.CancelledInvite', 'cancel', InviteKey)`. The digest binds the exact
+ * invite key, so an approval minted for one invitation cannot cancel another.
+ *
+ * One row, one statement — no transaction needed. `CancelledInvite.Authorized` is a
+ * deferred (subquery-bearing) check, so it fires at this statement's own auto-commit.
+ *
+ * Insert-if-absent, matching {@link registerMemberPeer}'s and {@link revokeMember}'s
+ * restart-safe shape: a repeat cancellation logs and returns rather than throwing on the
+ * primary key. (Check-then-write is not atomic; the primary key is the real backstop —
+ * the guard is for the sequential repeat/restart path.)
+ *
+ * Cancellation is what makes removal a re-entry gate: it is the `ConsumedInvite` insert
+ * that `NotCancelled` blocks, and `Member.Authorized`'s invite branch needs a
+ * same-transaction FRESH `ConsumedInvite` row, so a cancelled invitation rolls the whole
+ * join back. Un-cancelling is impossible (`CancelledInvite.Immutable`) — to re-invite a
+ * party, {@link issueInvite} a fresh invitation.
+ *
+ * Enumerate what there is to cancel with {@link listOutstandingInvites}: an invitation
+ * names no invitee, so the strand cannot tell a manager WHICH invitations a departing
+ * member holds. Invitee binding is tracked as `feat-strand-invitee-bound-invites`.
+ *
+ * @param db - The closed strand's database.
+ * @param params - The cancelling manager's keypair and the invite key to kill.
+ * @throws If `CancelledInvite.Authorized` rejects (a non-manager, a manager seated in
+ *   this transaction, or an approval minted for a different invite key) or `OnlyClosed`
+ *   rejects (an open strand); the insert rolls back, leaving no tombstone.
+ */
+export declare function cancelInvite(db: Database, params: CancelInviteParams): Promise<void>;
+/** One redeemable invitation, as reported by {@link listOutstandingInvites}. */
+export interface OutstandingInvite {
+    /** The `Invite.Key` (invite public key, base64url). */
+    inviteKey: string;
+    /**
+     * The expiry as the engine's canonical `datetime` string
+     * (`YYYY-MM-DDTHH:MM:SS[.frac]`, no zone suffix — see {@link canonicalDatetime}), or
+     * `null` for never-expires.
+     *
+     * Deliberately the STORED form, not the epoch-ms {@link IssueInviteParams.expiration}
+     * takes: it is what compares like-for-like against another canonicalised instant, and
+     * what the on-engine `NotExpired` gate sees. It is NOT a JS-parseable ISO instant —
+     * pass it through the engine (or `canonicalDatetime`) rather than `Date.parse`.
+     */
+    expiration: string | null;
+}
+/**
+ * The invitations that are still redeemable: neither consumed, nor cancelled, nor
+ * expired at `nowMs`.
+ *
+ * `Strand.Invite` is insert-only and carries no state column, so "outstanding" is not a
+ * property of the row — it is the `Invite` set minus the `ConsumedInvite` keys, minus
+ * the `CancelledInvite` keys, minus anything whose `Expiration` has passed. All three
+ * exclusions mirror gates a consume would hit anyway (`ConsumedInvite`'s primary key,
+ * `NotCancelled`, `NotExpired`).
+ *
+ * Reads via unfiltered scans and compares in JavaScript — see {@link scanInviteKeys} for
+ * why a full-PK where-equality is not reliable on a networked strand.
+ *
+ * Expiry is compared as `expiration > canonicalDatetime(nowMs)`: the same transform
+ * {@link issueInvite} uses to STORE `Invite.Expiration`, so the string comparison orders
+ * chronologically, and the same strict `>` the on-engine `NotExpired` gate uses (expiry
+ * is exclusive — an invitation is dead at its expiry instant, not after it).
+ *
+ * This is the manager's enumeration side of {@link cancelInvite}, and the "door is open"
+ * pre-flight behind `StrandMemberVerifier.isAuthorizedToJoin`.
+ *
+ * @param db - The closed strand's database.
+ * @param nowMs - The instant (epoch ms) to compare expiries against; defaults to
+ *   `Date.now()`. Tests pin it so the comparison is deterministic, mirroring
+ *   {@link consumeInvite}'s `nowMs` convention.
+ * @returns The redeemable invitations, in NO guaranteed order (the scans promise only a
+ *   superset of the live rows, not a stable sequence — sort by `expiration` if order
+ *   matters); empty if none.
+ */
+export declare function listOutstandingInvites(db: Database, nowMs?: number): Promise<OutstandingInvite[]>;
 /** Parameters for {@link addMemberByManager}. */
 export interface AddMemberByManagerParams {
     /**
      * The admitting manager's strand keypair. Its `publicKeyB64` must be a
-     * `Strand.Manager` row; it signs the new member key directly.
+     * `Strand.Manager` row; it signs the add-tagged digest over the new member key
+     * and its fresh stamp.
      */
     managerKeyPair: Ed25519KeyPair;
     /** The joining member's ed25519 PUBLIC key (base64url) — the new `Member.Key`. */
@@ -218,11 +353,14 @@ export interface AddMemberByManagerParams {
  * Admit a `Member` directly by manager signature — the sibling of the invite
  * path on `Member.Authorized`'s direct-manager branch.
  *
- * The constraint verifies `digest(new.Key)` against a `Manager` row matching
- * `context.ManagerKey`, so the payload is just the member key (no `'|'` join).
- * No `ConsumedInvite` is involved: this is the path a manager uses to seat a
- * member it already trusts (e.g. a manager-side enrollment that admits a
- * party already authorised out-of-band).
+ * The constraint verifies the add-tagged digest
+ * `digest('Strand.Member', 'add', new.Key, new.StampId)` against a pre-existing
+ * (`committed.Manager`) row matching `context.ManagerKey`. The stamp is minted
+ * fresh here and bound inside the signed digest, so the approval seats exactly
+ * this incarnation: once the member is removed (retiring the stamp), the captured
+ * approval can never re-seat it. No `ConsumedInvite` is involved: this is the
+ * path a manager uses to seat a member it already trusts (e.g. a manager-side
+ * enrollment that admits a party already authorised out-of-band).
  *
  * @param db - The closed strand's database.
  * @param params - The admitting manager keypair and the new member key.
@@ -230,6 +368,96 @@ export interface AddMemberByManagerParams {
  *   rolls back, leaving no `Member` row.
  */
 export declare function addMemberByManager(db: Database, params: AddMemberByManagerParams): Promise<void>;
+/** Parameters for {@link revokeMember}. */
+export interface RevokeMemberParams {
+    /**
+     * The revoking manager's strand keypair. Its `publicKeyB64` must be a
+     * PRE-EXISTING `Strand.Manager` row (the manager-removal branch of
+     * `Member.Authorized` reads `committed.Manager` — a manager seated in the same
+     * transaction cannot authorize); it signs the remove-tagged digest over the
+     * target row's key and live stamp, and files the accompanying tombstone.
+     */
+    managerKeyPair: Ed25519KeyPair;
+    /** The `Member.Key` row to delete. */
+    memberKey: string;
+}
+/**
+ * Revoke a `Member` on the signature of an existing manager.
+ *
+ * Reads the target row's live StampId first (a quiet no-op if the row is already
+ * absent — a repeated or restarted revocation should not throw), then runs ONE
+ * transaction pairing the delete with its `Strand.Revocation` tombstone: the
+ * schema's `Member.RevocationRecorded` requires the tombstone in the same
+ * transaction, and the tombstone is what permanently retires the stamp so the
+ * captured admission approval can never re-seat this incarnation.
+ *
+ * The manager-removal branch of `Member.Authorized` verifies the remove-tagged
+ * digest `digest('Strand.Member', 'remove', old.Key, old.StampId)` against a
+ * `committed.Manager` row matching `context.ManagerKey` — distinct from the
+ * add-tagged admission payload, and bound to the live stamp, so neither a
+ * captured admission nor a captured PRIOR removal (whose stamp differs) replays.
+ *
+ * A revoked member cannot re-admit itself off the invite it ALREADY SPENT: that
+ * `ConsumedInvite` row is stale, and the invite branch requires a
+ * same-transaction FRESH consumption. Re-admission normally takes a fresh
+ * manager action ({@link addMemberByManager} or a new invite).
+ *
+ * An UNSPENT invite the revoked party holds is killed EXPLICITLY, by the manager
+ * calling {@link cancelInvite} on it (enumerate the candidates with
+ * {@link listOutstandingInvites}); a cancelled invitation can never be consumed,
+ * and cancellation is permanent. This removal does NOT cascade into cancellation:
+ * an invitation names no invitee, so there is nothing to match the removed member
+ * against — the strand cannot tell which invitations were meant for it, or whether
+ * it holds any. Binding an invitation to its invitee is tracked as
+ * `feat-strand-invitee-bound-invites`.
+ *
+ * A manager must resign its `Manager` row before (or in the same transaction
+ * as) losing membership — `Member.NotAManager` rejects un-membering a key that
+ * still holds a Manager row. And the strand never drops to zero members
+ * (`Member.MinOneMember`, a local-count floor with the same cross-node caveat
+ * as `MinOneManager`).
+ *
+ * @param db - The closed strand's database.
+ * @param params - The revoking manager keypair and the target member key.
+ * @throws If `Member.Authorized` rejects (a non-manager or same-transaction
+ *   signer), `Member.NotAManager` rejects (the target still holds a Manager
+ *   row), or `Member.MinOneMember` rejects (the removal would empty the member
+ *   set); the whole delete+tombstone transaction rolls back.
+ */
+export declare function revokeMember(db: Database, params: RevokeMemberParams): Promise<void>;
+/** Parameters for {@link leaveStrand}. */
+export interface LeaveStrandParams {
+    /**
+     * The departing member's OWN strand keypair. Its `publicKeyB64` is the
+     * `Member.Key` row being deleted; it self-signs the leave-tagged digest —
+     * the self-departure branch verifies the signature against `old.Key` itself,
+     * so only the departing key's holder can produce it — and files the
+     * accompanying tombstone (it is still a committed member until this very
+     * transaction removes it, which is what `Revocation.Authorized` checks). No
+     * manager is involved.
+     */
+    memberKeyPair: Ed25519KeyPair;
+}
+/**
+ * A member leaves the strand by deleting its own `Member` row.
+ *
+ * The self-departure branch of `Member.Authorized` verifies
+ * `digest('Strand.Member', 'leave', old.Key, old.StampId)` against `old.Key`
+ * itself via `context.MemberSignature`. The `'leave'` tag (vs the manager
+ * branch's `'remove'`) is belt-and-braces only — the two branches verify against
+ * different keys; the anti-replay fix is the stamp binding. Like
+ * {@link revokeMember}, the live stamp is read first (absent row → quiet no-op)
+ * and the delete pairs with its `Strand.Revocation` tombstone in one transaction.
+ *
+ * The same floors as {@link revokeMember} apply: a manager must resign first
+ * (`NotAManager`) and the last member cannot leave (`MinOneMember`).
+ *
+ * @param db - The closed strand's database.
+ * @param params - The departing member's own keypair.
+ * @throws If `Member.Authorized`, `Member.NotAManager`, or `Member.MinOneMember`
+ *   rejects; the whole delete+tombstone transaction rolls back.
+ */
+export declare function leaveStrand(db: Database, params: LeaveStrandParams): Promise<void>;
 /** Parameters for {@link registerMemberPeer}. */
 export interface RegisterMemberPeerParams {
     /**
@@ -248,23 +476,30 @@ export interface RegisterMemberPeerParams {
 /**
  * Register a network node (`PeerId`) as acting on behalf of a member.
  *
- * The member self-signs `MemberKey || '|' || PeerId` with its OWN key; the schema's
- * `MemberPeer.Authorized` verifies that signature against `coalesce(new.MemberKey,
- * old.MemberKey)` — i.e. the member key itself — so only the member that owns the
- * key can register peers for it. A deferred `MemberExists` additionally requires the
- * `Member` row to already exist, so a peer for a non-member is rejected at commit.
- *
- * Insert-if-absent on the composite PK `(MemberKey, PeerId)`: a re-register on
- * restart (or a redundant call) is a no-op rather than relying on the platform's
- * PK-uniqueness rejection (not enforced in bootstrap mode — see
- * `optimystic-insert-pk-uniqueness-not-enforced`). A member may register multiple
- * DISTINCT `PeerId`s (multi-device); each is its own row under the same `MemberKey`.
- *
- * Out of scope: peer DELETION. The schema's `MemberExists` reads `new.MemberKey`,
- * which is null on delete, so a `MemberPeer` delete is currently rejected by the
- * schema (noted in the `apply-strand-membership-schema` review). Removing a peer
- * would need a schema tweak (e.g. `coalesce(new.MemberKey, old.MemberKey)` in
- * `MemberExists`), so no `removeMemberPeer` is provided here.
+ * The member self-signs the add-tagged digest
+ * `digest('Strand.MemberPeer', 'add', new.MemberKey, new.PeerId, new.StampId)`
+ * with its OWN key; the schema's `MemberPeer.Authorized` verifies that signature
+ * against `new.MemberKey` — i.e. the member key itself — so only the member that
+ * owns the key can register peers for it. The stamp is minted fresh here and
+ * bound inside the digest, so a captured registration approval neither
+ * re-registers a cleared binding (its stamp is retired) nor authorizes a removal
+ * (wrong tag). A deferred `MemberExists` additionally requires the `Member` row
+ * to already exist, so a peer for a non-member is rejected at commit.
+ *
+ * Insert-if-absent: a re-register on restart (or a redundant call) is a no-op. The
+ * platform DOES reject a duplicate-PK insert, but a restart-safe re-register should
+ * succeed quietly rather than throw, so the writer guards on existence instead of
+ * catching. The guard ({@link memberPeerStampId}) scans the member's peers and compares
+ * both key columns in JavaScript rather than seeking the composite primary key — see
+ * {@link scanMemberPeers} for why a full-PK point lookup is not reliable on a networked
+ * strand. A member may register multiple DISTINCT `PeerId`s (multi-device); each is its
+ * own row (and its own stamp) under the same `MemberKey`.
+ *
+ * Peer DELETION is signature-checked too, not rejected outright: `Authorized` carries
+ * distinct delete branches (self + manager), each over its own action-tagged digest
+ * bound to the row's stamp. Both removal paths live in {@link removeMemberPeer}.
+ * UPDATE is refused outright by `NoUpdate`: a re-binding is a remove plus a fresh
+ * register (under a fresh stamp).
  *
  * @param db - The closed strand's database (the member already exists).
  * @param params - The member's own keypair and the peer id to bind.
@@ -272,48 +507,186 @@ export interface RegisterMemberPeerParams {
  *   matching `Member` row); the insert rolls back, leaving no `MemberPeer` row.
  */
 export declare function registerMemberPeer(db: Database, params: RegisterMemberPeerParams): Promise<void>;
+/**
+ * Every `PeerId` currently bound to `memberKey`, in storage order.
+ *
+ * The enumeration side of {@link removeMemberPeer}: a manager cleaning up after a
+ * revocation knows only the departed member's key, never which devices it registered, so
+ * cleanup is `listMemberPeers` then one `removeMemberPeer` per id. Reads only — the rows
+ * it returns may name a `MemberKey` with no `Member` row (see the `MemberPeer` table NOTE
+ * in the schema), so this is NOT a membership test.
+ *
+ * @param db - The closed strand's database.
+ * @param memberKey - The `MemberPeer.MemberKey` to enumerate.
+ * @returns The bound peer ids, empty if the member has none.
+ */
+export declare function listMemberPeers(db: Database, memberKey: string): Promise<string[]>;
+/** Parameters for the SELF branch of {@link removeMemberPeer}. */
+export interface RemoveOwnPeerParams {
+    /**
+     * The member's OWN strand keypair. Its `publicKeyB64` is the `MemberPeer.MemberKey`
+     * of the row being deleted, and it signs the remove-tagged digest
+     * `digest('Strand.MemberPeer', 'remove', MemberKey, PeerId, StampId)` — the self
+     * branch of `MemberPeer.Authorized` verifies against the row's own member key, so
+     * no OTHER member's row is reachable this way, and the tag + stamp binding keep a
+     * captured registration approval from doubling as a removal (and vice versa).
+     */
+    memberKeyPair: Ed25519KeyPair;
+    /** The `PeerId` of the binding to delete. */
+    peerId: string;
+}
+/** Parameters for the MANAGER branch of {@link removeMemberPeer}. */
+export interface RemoveMemberPeerByManagerParams {
+    /**
+     * The clearing manager's strand keypair. Its `publicKeyB64` must be a PRE-EXISTING
+     * `Strand.Manager` row (the manager branch reads `committed.Manager`, so a manager
+     * seated in the same transaction cannot authorize); it signs the
+     * manager-remove-tagged digest over the exact row and its live stamp, and files
+     * the accompanying tombstone.
+     */
+    managerKeyPair: Ed25519KeyPair;
+    /** The `MemberPeer.MemberKey` whose binding is being cleared. */
+    memberKey: string;
+    /** The `PeerId` of the binding to delete. */
+    peerId: string;
+}
+/**
+ * Either shape accepted by {@link removeMemberPeer}. A discriminated union rather than
+ * one opaque keypair: the two branches sign DIFFERENT action tags (`'remove'` self vs
+ * `'manager-remove'`), so each case carries exactly the fields its payload needs.
+ */
+export type RemoveMemberPeerParams = RemoveOwnPeerParams | RemoveMemberPeerByManagerParams;
+/**
+ * Delete a `MemberPeer` binding — either the member clearing its own, or a manager
+ * clearing another member's.
+ *
+ * Reads the row's live StampId first (absent → quiet no-op, mirroring
+ * {@link registerMemberPeer}'s insert-if-absent, so a repeated or restarted cleanup
+ * is not a silent zero-row "success" the caller cannot distinguish from a real one),
+ * then runs ONE transaction pairing the delete with its `Strand.Revocation`
+ * tombstone — `MemberPeer.RevocationRecorded` requires it, and the retirement is
+ * what keeps the captured registration approval from re-binding the cleared row.
+ *
+ * `MemberPeer` rows do NOT cascade when the member is revoked (`MemberExists` runs on
+ * insert only, and nothing deletes them), so a removed member's peer bindings survive
+ * as orphans — enumerate them with {@link listMemberPeers}, which is how a manager
+ * discovers what to clear. Only that member can sign the self branch, and a member being
+ * removed against its will has no reason to cooperate — hence the manager branch, which
+ * is the cleanup path after a revocation.
+ *
+ * The manager branch is deliberately NOT gated on the member already being gone: a
+ * manager may clear a still-present member's binding too, matching "any manager can
+ * remove any member". It verifies the manager-remove-tagged
+ * `digest('Strand.MemberPeer', 'manager-remove', old.MemberKey, old.PeerId, old.StampId)`
+ * against a `committed.Manager` row; the self branch verifies the remove-tagged
+ * sibling against the row's own member key.
+ *
+ * Cleanup is an explicit follow-up call by the revoking manager, never a cascade inside
+ * {@link revokeMember}: a revocation that also had to clear an unbounded number of peer
+ * rows in the same transaction would couple two concerns and make its failure modes
+ * harder to reason about.
+ *
+ * @param db - The closed strand's database.
+ * @param params - Either the owning member's keypair, or a manager's keypair plus the
+ *   target member key.
+ * @throws If `MemberPeer.Authorized` rejects (neither branch satisfied), or if the row
+ *   is still present after the delete (see the point-lookup note below).
+ */
+export declare function removeMemberPeer(db: Database, params: RemoveMemberPeerParams): Promise<void>;
 /** Parameters for {@link addManager}. */
 export interface AddManagerParams {
     /**
      * An EXISTING manager's strand keypair. Its `publicKeyB64` must already be a
      * `Strand.Manager` row (the existing-manager branch of `Manager.Authorized`
-     * rejects a non-manager once the founder manager exists); it signs the new
-     * manager key and is bound as `context.ManagerKey`.
+     * rejects a non-manager once the founder manager exists); it signs the
+     * add-tagged digest over the new manager key, generation, and fresh stamp,
+     * and is bound as `context.ManagerKey`.
      */
     byManagerKeyPair: Ed25519KeyPair;
     /** The member key to promote — the new `Manager.MemberKey` row. */
     newManagerKey: string;
 }
 /**
- * Promote a member to `Manager` on the signature of an existing manager.
- *
- * The existing-manager branch of `Manager.Authorized` verifies
- * `digest(coalesce(new.MemberKey, old.MemberKey))` — `new.MemberKey` =
- * `newManagerKey` on insert — against a `Manager` row matching
- * `context.ManagerKey`. So the signer signs the new manager key directly (no
- * `'|'` join) and binds itself as `context.ManagerKey`.
- *
- * Once the founder manager exists, the schema's `(select count(1) from Manager)
- * <= 1` bootstrap shortcut no longer applies to a second add (at commit the count
- * includes the new row, so it is ≥ 2), so this genuinely exercises signature
- * verification — a non-manager signer, or a signature over the wrong key, is
- * rejected.
+ * Promote a key that is ALREADY a `Strand.Member` to `Manager` on the signature of
+ * an existing manager — use {@link admitManager} to admit and promote atomically.
+ *
+ * The promotion branch of `Manager.Authorized` requires the authorizer to be a
+ * `Manager` row of STRICTLY SMALLER `Generation` than the new row, verifying
+ * `digest('Strand.Manager', 'add', new.MemberKey, new.Generation, new.StampId)`
+ * against `context.ManagerKey`. So this writer reads the authorizer's generation,
+ * seats the new manager at that value + 1 (the natural successor; the schema
+ * enforces only the strict ordering), mints a fresh stamp, and signs the
+ * add-tagged digest over all three: the generation inside the signed digest keeps
+ * a captured promotion from replaying at a different generation, and the stamp
+ * keeps it from re-seating a second incarnation once this one is removed.
+ * `new.Generation` is an SQL INTEGER digest arg — the digest framing is
+ * type-tagged, so the TS side signs over the NUMBER itself
+ * (see {@link signStrandApproval}).
+ *
+ * The strict ordering — not this writer — is what makes a same-transaction takeover
+ * impossible; the `Manager.Generation` column comment in `schemas/strand.qsql` carries
+ * that argument. All this writer owes it is a generation strictly above the
+ * authorizer's, inside the signed payload.
+ *
+ * When the authorizer has NO `Manager` row (a non-manager signer, or an open
+ * strand with no managers at all), the scan finds nothing and the writer falls
+ * back to generation 1 and issues the insert anyway — deliberately letting the
+ * SCHEMA be the rejector (`Manager.Authorized` / `OnlyClosed`), not a
+ * writer-thrown error, so enforcement is pinned where it actually lives.
  *
  * @param db - The closed strand's database (founder manager already seated).
  * @param params - The authorizing manager's keypair and the new manager key.
- * @throws If `Manager.Authorized` rejects; the insert rolls back.
+ * @throws If `Manager.Authorized` rejects, or if `Manager.MemberExists` rejects because
+ *   `newManagerKey` holds no `Member` row (admit it first, or use
+ *   {@link admitManager}); the insert rolls back.
  */
 export declare function addManager(db: Database, params: AddManagerParams): Promise<void>;
+/** Parameters for {@link admitManager} — the same shape as {@link AddManagerParams}. */
+export type AdmitManagerParams = AddManagerParams;
+/**
+ * Admit a key as a `Member` AND promote it to `Manager`, atomically — the one-step
+ * pair for a key that is not in the strand yet. {@link addManager} alone promotes a
+ * key that is already a member.
+ *
+ * ONE transaction, because `Manager.MemberExists` is a deferred check reading the LIVE
+ * `Member` table: the sibling `Member` insert satisfies it at the shared commit, and a
+ * rejection of either half rolls BOTH rows back — never a `Member` row seated by a
+ * failed promotion, nor a `Manager` row with no member behind it.
+ *
+ * NO new authority: both halves are signed by the SAME manager, over two distinct
+ * action-tagged digests — `digest('Strand.Member', 'add', …)` for the admission and
+ * `digest('Strand.Manager', 'add', …)` for the promotion — each bound to its own row's
+ * fresh stamp. This composes exactly the two approvals that manager could already
+ * issue separately.
+ *
+ * The promoting manager must be a PRE-transaction manager: the direct-admit branch of
+ * `Member.Authorized` reads `committed.Manager`, so `admitManager` cannot be chained —
+ * a manager seated by an `admitManager` earlier in the SAME transaction cannot admit
+ * the next one. (A same-transaction promotion CHAIN rooted at a pre-existing manager
+ * is fine; only the `Member` half needs the committed authorizer.)
+ *
+ * NOT insert-if-absent: a repeat call for a key that is already a member fails on the
+ * `Member` primary key, matching {@link addMemberByManager}'s unguarded shape.
+ *
+ * @param db - The closed strand's database (founder manager already seated).
+ * @param params - The authorizing manager's keypair and the key to admit + promote.
+ * @throws If either half is rejected (`Member.Authorized`, `Manager.Authorized`, a
+ *   duplicate `Member` key, …); the whole transaction rolls back, leaving neither row.
+ */
+export declare function admitManager(db: Database, params: AdmitManagerParams): Promise<void>;
 /** Parameters for {@link removeManager}. */
 export interface RemoveManagerParams {
     /**
-     * The keypair authorizing the removal, bound as `context.ManagerKey` and
-     * signing `digest(targetManagerKey)`. For an ADMIN removal this is a DIFFERENT
-     * existing manager (satisfying the existing-manager branch); for a
+     * The keypair authorizing the removal, bound as `context.ManagerKey`. For an
+     * ADMIN removal this is a DIFFERENT existing manager, signing the
+     * remove-tagged digest (satisfying the existing-manager branch); for a
      * SELF-resignation it is the target's OWN keypair (`publicKeyB64 ===
-     * targetManagerKey`, satisfying the former-manager self branch). The same
-     * context construction satisfies whichever branch applies — see
-     * {@link removeManager}.
+     * targetManagerKey`), signing the resign-tagged digest (satisfying the
+     * former-manager self branch). The writer picks the tag by comparing the keys —
+     * see {@link removeManager}. Either way this keypair also files the
+     * accompanying tombstone, which requires it to be a PRE-transaction MEMBER
+     * (`Revocation.Authorized` reads `committed.Member`) — true for every manager,
+     * since managers are members.
      */
     byManagerKeyPair: Ed25519KeyPair;
     /** The `Manager.MemberKey` row to delete. */
@@ -323,39 +696,60 @@ export interface RemoveManagerParams {
  * Remove a `Manager` row — either an admin removing a different manager or a
  * manager resigning itself.
  *
- * On a DELETE, `coalesce(new.MemberKey, old.MemberKey)` binds `old.MemberKey =
- * targetManagerKey` (there is no `new` row), so the signed payload is the target
- * key for BOTH accepting branches of `Manager.Authorized`, and a single context
- * construction serves both:
- * - **Admin removal**: `byManagerKeyPair` is a different existing manager; the
- *   existing-manager branch verifies the signature against `A.MemberKey =
- *   context.ManagerKey`.
- * - **Self-resignation**: `byManagerKeyPair` IS the target (its `publicKeyB64`
- *   equals `targetManagerKey`); the former-manager self branch verifies
- *   `old.MemberKey = context.ManagerKey` and the self-signature over `old.MemberKey`.
- *
- * The caller selects the case purely by which keypair it passes — no branching here.
- *
- * KNOWN PLATFORM GAP (not fixable here): the optimystic bootstrap-mode transactor
- * evaluates deferred (subquery-bearing) CHECK constraints only on INSERT, not on
- * DELETE. `Manager.Authorized` is deferred, so the platform currently accepts ANY
- * `Manager` delete regardless of signature — `removeManager`'s authorization is
- * effectively unenforced at runtime until that gap is closed (filed as
- * `optimystic-deferred-check-not-enforced-on-delete`). This writer still builds the
- * correct, signed delete so it works unchanged once enforcement lands — exactly as
- * the invite path issues correct inserts despite the open PK-uniqueness gap.
- *
- * KNOWN SCHEMA HAZARD (not guarded here): even with enforcement, `Manager.
- * Authorized`'s `(select count(1) from Manager) <= 1` bootstrap branch is true at
- * commit whenever a delete drops the count to ≤ 1, so removing the strand's LAST (or
- * second-to-last) manager would be accepted regardless of signature — and removing
- * the last one orphans the strand (no one can ever add another). The schema does not
- * prevent this; a "min-one-manager" invariant is deferred to a future schema change
- * rather than grown into this writer.
+ * Reads the target row's live `(Generation, StampId)` first (absent → quiet
+ * no-op, same restart-safe shape as {@link revokeMember}), then runs ONE
+ * transaction pairing the delete with its `Strand.Revocation` tombstone
+ * (`Manager.RevocationRecorded`). The two delete-side branches of
+ * `Manager.Authorized` verify DIFFERENT action-tagged digests, each bound to
+ * `(old.MemberKey, old.StampId)`:
+ * - **Admin removal** (`byManagerKeyPair` is a different existing manager): the
+ *   removal branch verifies `digest('Strand.Manager', 'remove', old.MemberKey,
+ *   old.StampId)` against `A.MemberKey = context.ManagerKey`. Deliberately NO
+ *   generation condition: a later-generation manager may remove an
+ *   earlier-generation one (generation is lineage, not privilege), and deletes
+ *   are safe once inserts are — every accepting branch requires a `Manager` row
+ *   in the post-image, and the promotion branch's generation ordering keeps
+ *   attacker rows out of it. The stamp binding is what makes a captured removal
+ *   single-use: a re-promoted manager carries a fresh stamp the old approval
+ *   does not match — closing the removal half of
+ *   `bug-strand-manager-authority-antireplay` (the insert half was already
+ *   closed by the generation-bearing promotion payload).
+ * - **Self-resignation** (`byManagerKeyPair` IS the target): the former-manager
+ *   self branch verifies `digest('Strand.Manager', 'resign', old.MemberKey,
+ *   old.StampId)` against `old.MemberKey` itself. The distinct `'resign'` tag is
+ *   belt-and-braces (different verifying keys); the anti-replay fix is the stamp.
+ *
+ * The caller selects the case purely by which keypair it passes; the only
+ * branching here is the action tag, chosen by comparing the signer to the target.
+ *
+ * The optimystic bootstrap-mode transactor evaluates deferred (subquery-bearing)
+ * CHECK constraints on DELETE as well as INSERT, so `Manager.Authorized` — deferred —
+ * IS enforced here: a signer that is neither an existing manager nor the target
+ * itself is rejected at commit.
+ *
+ * THE LAST MANAGER CANNOT BE REMOVED. `Manager.MinOneManager` (`check on delete`,
+ * deferred, so it sees the POST-delete count) rejects any delete that would leave the
+ * strand with zero managers — an admin-less closed strand could never admit anyone
+ * again, since `Invite`, `addMemberByManager`, and `addManager` all require a
+ * `Manager` row. The bootstrap branch of `Manager.Authorized` is gated to INSERTs
+ * (`old.MemberKey is null`), so it does not waive the signature check on a delete
+ * that drops the count toward the floor: a second-to-last removal is authorized
+ * exactly like any other.
+ *
+ * HAND-OFF ORDER: a sole manager transferring control must ADD the successor FIRST
+ * and resign SECOND. A same-transaction delete-then-insert swap is rejected — the
+ * bootstrap branch is gated to the founding state (at most one `Member`), and the
+ * successor's insert has no other manager to authorize it once the sole manager's
+ * row is gone.
+ *
+ * Cross-node caveat: `MinOneManager` counts rows visible to THIS transaction, so two
+ * nodes concurrently removing different managers can each see a survivor and still
+ * converge to zero. Noted in the schema; a cross-node floor is not attempted here.
  *
  * @param db - The closed strand's database.
  * @param params - The authorizing keypair and the target manager key.
- * @throws If `Manager.Authorized` rejects (e.g. a non-manager admin removal
- *   while > 2 managers remain); the delete rolls back.
+ * @throws If `Manager.Authorized` rejects (a signer that is neither another existing
+ *   manager nor the target itself) or `Manager.MinOneManager` rejects (the removal
+ *   would leave no managers); the whole delete+tombstone transaction rolls back.
  */
 export declare function removeManager(db: Database, params: RemoveManagerParams): Promise<void>;