@serfab/cadre-core 0.12.0 → 1.0.0

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

@@ -100,6 +100,29 @@ export declare function signStrandApproval(fields: ReadonlyArray<string | number
  * @returns A fresh base64url stamp (43 chars for 32 bytes).
  */
 export declare function generateStrandStampId(): string;
+/**
+ * A membership writer that runs only in a transaction of its own found another
+ * transaction already open on the strand database, and wrote nothing. Raised only
+ * under `joinOpenTransaction: false` (see {@link StrandWriteOptions}) — the background
+ * callers, which treat it as "the app is mid-transaction; try again later".
+ */
+export declare class StrandTransactionBusyError extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** Options every transactional membership writer accepts. */
+export interface StrandWriteOptions {
+    /**
+     * Default true: when a transaction is already open on the database, run the writer's
+     * statements inside it. The caller composes several writers in one transaction (e.g. a
+     * resign + revoke pair that must land together) and owns its commit and rollback, so
+     * the deferred constraints fire once, at the caller's commit.
+     *
+     * Background callers (the membership reconciler, the unpublish binding cleanup) pass
+     * false: they share the database with the app and must never join a transaction
+     * someone else opened, so the writer throws {@link StrandTransactionBusyError} instead.
+     */
+    joinOpenTransaction?: boolean;
+}
 /** Parameters for {@link bootstrapFounderMembership}. */
 export interface FounderBootstrapParams {
     /** The strand id — written to `Header.Id`. */
@@ -114,7 +137,45 @@ export interface FounderBootstrapParams {
      * Required for a closed strand; ignored for an open strand.
      */
     founderKeyPair?: Ed25519KeyPair;
+    /**
+     * The public key derived from the strand row's SHARED `MemberPrivateKey` (the read
+     * secret every joining party holds). When supplied for a closed strand, a
+     * `Strand.Member` or `Strand.Manager` row holding it refuses the bootstrap with
+     * {@link PreSplitStrandIdentityError} (see {@link assertNotPreSplitStrand}): nothing
+     * seats that key since the per-party identity split, so its presence is exactly the
+     * fingerprint of a strand founded before it. Omitted, no such check runs (a caller that
+     * holds no shared key has nothing to compare against). Ignored for an open strand.
+     */
+    sharedMemberPublicKey?: string;
+}
+/**
+ * A closed strand founded BEFORE the per-party identity split: its founding
+ * `Strand.Member` (and, unless handed on, `Strand.Manager`) is the key derived from the
+ * shared `MemberPrivateKey`, which every joining party holds, so any member can sign as
+ * the founder. There is no repair — rewriting the membership cannot be trusted, since any
+ * joiner could already have admitted or revoked anyone, or could race the rewrite — so
+ * the strand must be recreated. Thrown by {@link assertNotPreSplitStrand} (a founder
+ * bootstrap, or membership-invite issuance); the formation layer maps it to a
+ * non-retryable rejection.
+ */
+export declare class PreSplitStrandIdentityError extends Error {
+    readonly strandId: string;
+    constructor(strandId: string);
 }
+/**
+ * Refuse a closed strand whose membership still holds the key derived from the shared
+ * `MemberPrivateKey` (see {@link FounderBootstrapParams.sharedMemberPublicKey}). `Member`
+ * is the primary probe — every manager is a member (`Manager.MemberExists`), so it also
+ * catches a pre-split founder who handed management to another key and resigned, or a
+ * sealed pre-split strand. `Manager` is probed too, for the partition case the schema
+ * notes on `MemberExists` (a Manager row converged without its Member row). Cannot
+ * misfire: nothing seats the shared-derived key since the split, and rows not yet loaded
+ * read as absent.
+ *
+ * @throws {PreSplitStrandIdentityError} when a `Strand.Member` or `Strand.Manager` row is
+ *   the shared-derived key.
+ */
+export declare function assertNotPreSplitStrand(db: Database, strandId: string, sharedMemberPublicKey: string): Promise<void>;
 /**
  * Founder-only one-time bootstrap of a strand's `Strand.*` membership/RBAC rows.
  *
@@ -136,10 +197,17 @@ export interface FounderBootstrapParams {
  * Manager could never admit anyone, so failing loudly here (which propagates out
  * of `StrandDatabase.initialize()` and triggers the runtime's rollback) is correct.
  *
+ * A closed strand whose membership holds `sharedMemberPublicKey` throws
+ * {@link PreSplitStrandIdentityError} before writing anything: the insert-if-absent
+ * guards would otherwise skip over its pre-split founding rows and leave the shared
+ * key seated.
+ *
  * @param db - The strand's Quereus database (schema already applied).
  * @param params - Strand id/type, the sApp config for the Header, and (closed only)
- *   the derived founder keypair.
+ *   the derived founder keypair and the shared-derived public key to refuse.
  * @throws If `type === 'c'` and no `founderKeyPair` is supplied.
+ * @throws {PreSplitStrandIdentityError} If `type === 'c'` and a `Strand.Member` or
+ *   `Strand.Manager` row is `sharedMemberPublicKey`.
  */
 export declare function bootstrapFounderMembership(db: Database, params: FounderBootstrapParams): Promise<void>;
 /** Parameters for {@link issueInvite}. */
@@ -244,11 +312,41 @@ export interface ConsumeInviteParams {
  * @param db - The closed strand's database.
  * @param params - The invite key/secret, the joining member's public key, and an
  *   optional `nowMs` instant for the expiry comparison (default `Date.now()`).
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If any constraint rejects (bad signature, missing invite, or an expired
  *   invite); the whole transaction rolls back (neither the `Member` nor the
  *   `ConsumedInvite` row survives).
+ * @throws {StrandTransactionBusyError} Under `joinOpenTransaction: false`, when another
+ *   transaction is open; nothing was written.
  */
-export declare function consumeInvite(db: Database, params: ConsumeInviteParams): Promise<void>;
+export declare function consumeInvite(db: Database, params: ConsumeInviteParams, options?: StrandWriteOptions): Promise<void>;
+/**
+ * Burn an invitation against an ALREADY-SEATED member: insert the
+ * `Strand.ConsumedInvite` row alone, naming the existing `Member.Key`, so the bearer
+ * credential can never be spent by anyone else.
+ *
+ * The already-member arm of the bring-up membership reconciler
+ * (`strand-membership-reconciler.ts`): a machine that finds its party's `Member` row
+ * already present (a sibling machine redeemed the invitation's twin first, or a
+ * manager admitted the party directly) may still hold an UNSPENT formation-delivered
+ * invitation — a bearer credential whoever presents can join with. Every
+ * `ConsumedInvite` constraint is satisfiable without a same-transaction `Member`
+ * insert (`MemberExists` reads the live table), so this is one statement whose
+ * deferred checks fire at its own commit. It seats nobody now or later:
+ * `Member.Authorized`'s invite branch requires a same-transaction FRESH consumption,
+ * so the row it leaves is exactly as inert as any other spent invitation's.
+ *
+ * @param db - The closed strand's database (the member already exists).
+ * @param params - The invite key/secret and the EXISTING member's public key, plus the
+ *   optional `nowMs` instant for the expiry gate (default `Date.now()`).
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
+ * @throws If any constraint rejects — already consumed (the `InviteKey` primary key),
+ *   cancelled, expired, or a sealed strand. Callers treat a burn failure as "already
+ *   dead" and log rather than retry.
+ * @throws {StrandTransactionBusyError} Under `joinOpenTransaction: false`, when another
+ *   transaction is open; nothing was tried, so the invitation is exactly as live as before.
+ */
+export declare function burnInvite(db: Database, params: ConsumeInviteParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link cancelInvite}. */
 export interface CancelInviteParams {
     /**
@@ -338,6 +436,15 @@ export interface OutstandingInvite {
  *   matters); empty if none.
  */
 export declare function listOutstandingInvites(db: Database, nowMs?: number): Promise<OutstandingInvite[]>;
+/**
+ * Whether `memberKey` holds a live `Strand.Member` row, as seen by THIS database
+ * instance — the membership probe behind the bring-up reconciler
+ * (`strand-membership-reconciler.ts`). Reads via {@link memberStampId}'s unfiltered
+ * scan + JavaScript compare (the {@link scanMemberPeers} argument for why a PK point
+ * lookup is not reliable on a networked strand). Local visibility only: `false` can
+ * mean "not replicated here yet", never a durable verdict about the strand.
+ */
+export declare function isStrandMember(db: Database, memberKey: string): Promise<boolean>;
 /** Parameters for {@link addMemberByManager}. */
 export interface AddMemberByManagerParams {
     /**
@@ -364,10 +471,11 @@ export interface AddMemberByManagerParams {
  *
  * @param db - The closed strand's database.
  * @param params - The admitting manager keypair and the new member key.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If `Member.Authorized` rejects (e.g. a non-manager key); the insert
  *   rolls back, leaving no `Member` row.
  */
-export declare function addMemberByManager(db: Database, params: AddMemberByManagerParams): Promise<void>;
+export declare function addMemberByManager(db: Database, params: AddMemberByManagerParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link revokeMember}. */
 export interface RevokeMemberParams {
     /**
@@ -417,14 +525,22 @@ export interface RevokeMemberParams {
  * (`Member.MinOneMember`, a local-count floor with the cross-node caveat its
  * schema NOTE states).
  *
+ * Callers running inside a cadre runtime should follow this write with
+ * `CadreNode.refreshRevocationEnforcement(strandId)`. The removed party's
+ * machines are refused at the network layer by the strand's revoked-peer gate
+ * (`strand-revocation-enforcer.ts`), which polls for membership changes because
+ * this bare `Database` handle raises no event the runtime can hook — so without
+ * that call the cut lands up to one poll interval (default 30 s) later.
+ *
  * @param db - The closed strand's database.
  * @param params - The revoking manager keypair and the target member key.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @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>;
+export declare function revokeMember(db: Database, params: RevokeMemberParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link leaveStrand}. */
 export interface LeaveStrandParams {
     /**
@@ -452,12 +568,18 @@ export interface LeaveStrandParams {
  * The same floors as {@link revokeMember} apply: a manager must resign first
  * (`NotAManager`) and the last member cannot leave (`MinOneMember`).
  *
+ * Like {@link revokeMember}, a caller inside a cadre runtime should follow this
+ * with `CadreNode.refreshRevocationEnforcement(strandId)` — here it is what
+ * makes the departing node notice its own departure promptly (the gate emits
+ * `strand:revoked` when it finds this node's own peer id revoked).
+ *
  * @param db - The closed strand's database.
  * @param params - The departing member's own keypair.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @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>;
+export declare function leaveStrand(db: Database, params: LeaveStrandParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link registerMemberPeer}. */
 export interface RegisterMemberPeerParams {
     /**
@@ -503,10 +625,13 @@ export interface RegisterMemberPeerParams {
  *
  * @param db - The closed strand's database (the member already exists).
  * @param params - The member's own keypair and the peer id to bind.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If `MemberPeer.Authorized`/`MemberExists` rejects (wrong signer, or no
  *   matching `Member` row); the insert rolls back, leaving no `MemberPeer` row.
+ * @throws {StrandTransactionBusyError} Under `joinOpenTransaction: false`, when another
+ *   transaction is open; nothing was written.
  */
-export declare function registerMemberPeer(db: Database, params: RegisterMemberPeerParams): Promise<void>;
+export declare function registerMemberPeer(db: Database, params: RegisterMemberPeerParams, options?: StrandWriteOptions): Promise<void>;
 /**
  * Every `PeerId` currently bound to `memberKey`, in storage order.
  *
@@ -589,10 +714,13 @@ export type RemoveMemberPeerParams = RemoveOwnPeerParams | RemoveMemberPeerByMan
  * @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.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If `MemberPeer.Authorized` rejects (neither branch satisfied), or if the row
  *   is still present after the delete (see the point-lookup note below).
+ * @throws {StrandTransactionBusyError} Under `joinOpenTransaction: false`, when another
+ *   transaction is open; nothing was written.
  */
-export declare function removeMemberPeer(db: Database, params: RemoveMemberPeerParams): Promise<void>;
+export declare function removeMemberPeer(db: Database, params: RemoveMemberPeerParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link addManager}. */
 export interface AddManagerParams {
     /**
@@ -636,11 +764,12 @@ export interface AddManagerParams {
  *
  * @param db - The closed strand's database (founder manager already seated).
  * @param params - The authorizing manager's keypair and the new manager key.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @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>;
+export declare function addManager(db: Database, params: AddManagerParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link admitManager} — the same shape as {@link AddManagerParams}. */
 export type AdmitManagerParams = AddManagerParams;
 /**
@@ -670,10 +799,11 @@ export type AdmitManagerParams = AddManagerParams;
  *
  * @param db - The closed strand's database (founder manager already seated).
  * @param params - The authorizing manager's keypair and the key to admit + promote.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @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>;
+export declare function admitManager(db: Database, params: AdmitManagerParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link removeManager}. */
 export interface RemoveManagerParams {
     /**
@@ -758,13 +888,14 @@ export interface RemoveManagerParams {
  *
  * @param db - The closed strand's database.
  * @param params - The authorizing keypair and the target manager key.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If the signer IS the target and it is the sole manager (before writing —
  *   the operation the caller wants is {@link sealStrand}), or if `Manager.Authorized`
  *   rejects (a signer that is neither another existing manager nor the target
  *   itself, or a raw sole-manager `'resign'` whose post-image count is zero); the
  *   whole delete+tombstone transaction rolls back.
  */
-export declare function removeManager(db: Database, params: RemoveManagerParams): Promise<void>;
+export declare function removeManager(db: Database, params: RemoveManagerParams, options?: StrandWriteOptions): Promise<void>;
 /** Parameters for {@link sealStrand}. */
 export interface SealStrandParams {
     /**
@@ -813,6 +944,7 @@ export interface SealStrandParams {
  *
  * @param db - The closed strand's database.
  * @param params - The sole manager's own keypair.
+ * @param options - Whether to join an already-open transaction (see {@link StrandWriteOptions}).
  * @throws If more than one manager exists (the caller wants {@link removeManager}),
  *   or the supplied keypair holds no `Manager` row while one exists, or the strand
  *   holds no `Manager` row and has never retired one (not founded yet — see
@@ -821,7 +953,7 @@ export interface SealStrandParams {
  *   and returns quietly (restart-safe, matching {@link bootstrapFounderMembership}
  *   and {@link removeManager}'s absent-row no-op).
  */
-export declare function sealStrand(db: Database, params: SealStrandParams): Promise<void>;
+export declare function sealStrand(db: Database, params: SealStrandParams, options?: StrandWriteOptions): Promise<void>;
 /**
  * Whether the strand is sealed: a CLOSED strand that holds no `Manager` rows AND
  * has retired at least one `Manager` stamp into `Strand.Revocation`.