@serfab/cadre-core 0.13.0 → 1.1.0

package/dist/strand-membership-writer.js

@@ -115,49 +115,118 @@ export function generateStrandStampId() {
     const bytes = randomBytes(256, 'bytes');
     return uint8ArrayToString(bytes, 'base64url');
 }
+// ── Write batches (every membership write is one indivisible transaction) ──────
 /**
- * Run `fn` inside one explicit strand transaction: begin, fn, commit — with the
- * standard rollback-on-failure shape.
- *
- * Used wherever two `Strand.*` writes must land atomically: the invite-consume
- * pair (Member + ConsumedInvite) and every delete-plus-tombstone pair (the
- * `RevocationRecorded` constraints require the `Revocation` row in the SAME
- * transaction as the delete it retires).
- *
- * JOINS a caller-owned transaction instead of opening its own: Quereus's
- * `Database.beginTransaction()` hard-throws "Transaction already active" on any
- * nesting, and a caller composing several writers in one transaction (e.g. a
- * resign + revoke pair that must land atomically) is exactly the case where the
- * deferred constraints should fire once, at the CALLER's commit. In joined mode
- * commit/rollback belong to the caller, so failures simply propagate.
+ * 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".
  */
-async function inStrandTransaction(db, fn) {
-    if (!db.getAutocommit()) {
-        await fn();
-        return;
+export class StrandTransactionBusyError extends Error {
+    constructor(options) {
+        super('Another transaction is open on the strand database. This membership write runs only in a '
+            + 'transaction of its own, so nothing was written; retry once that transaction closes.', options);
+        this.name = 'StrandTransactionBusyError';
+    }
+}
+/**
+ * Join statement fragments into one batch. Named parameters bind across the whole batch,
+ * so each fragment builder uses its own parameter names; a name bound twice would
+ * silently hand one fragment the other's value, so it throws instead.
+ */
+function combineStatements(...fragments) {
+    const params = {};
+    for (const fragment of fragments) {
+        for (const [name, value] of Object.entries(fragment.params)) {
+            if (name in params) {
+                throw new Error(`Strand write batch binds the parameter :${name} in two statements`);
+            }
+            params[name] = value;
+        }
     }
-    await db.beginTransaction();
+    return { sql: fragments.map((fragment) => fragment.sql).join('\n'), params };
+}
+/** Quereus's refusal of a `begin` issued while a transaction is already open. */
+const NESTED_BEGIN_REFUSAL = /^Cannot begin transaction: already in a transaction$/;
+function isNestedBeginRefusal(error) {
+    return error instanceof Error && NESTED_BEGIN_REFUSAL.test(error.message);
+}
+/**
+ * Run `statements` as one indivisible transaction on the shared strand database.
+ *
+ * The whole transaction is ONE `db.exec` batch — `begin transaction; <statements> commit;`
+ * — because Quereus holds its exec mutex for a whole batch but releases it between
+ * separate calls, and any caller's statement that runs while an explicit transaction is
+ * open lands inside it. A `beginTransaction()` / `exec` / `commit()` sequence therefore
+ * swept the app's concurrent writes into a background writer's transaction, and lost them
+ * when that transaction failed.
+ *
+ * Whether a transaction is already open is decided by the batch's own `begin`, under the
+ * mutex, not by `getAutocommit()` beforehand: that reads false whenever another caller's
+ * autocommit statement is merely in flight, which would make a background writer refuse
+ * spuriously and a composing caller run its statements as separate autocommits.
+ *
+ * - The `begin` succeeds: the batch commits or fails as a unit. A failure at `commit`
+ *   (deferred constraints, a refused optimystic commit) leaves nothing open. A failure at
+ *   an earlier statement leaves the batch's transaction open, so it is rolled back here.
+ * - The `begin` is refused because a transaction is already open: nothing has run. With
+ *   `joinOpenTransaction: false` that is a {@link StrandTransactionBusyError} (with the
+ *   refusal as `cause`), and the open transaction — someone else's — is left alone.
+ *   Otherwise the statements run inside it, and its owner commits or rolls back.
+ *
+ * NOTE: interim until Quereus ships a batch that rolls back before releasing its mutex —
+ * requested as `../quereus/tickets/plan/exec-batch-as-one-transaction.md`; switch to that
+ * API when a Quereus release carries it, which also retires the message match in
+ * {@link isNestedBeginRefusal}. Until then two residual windows remain. (1) A statement
+ * that fails before `commit` (a primary-key collision such as a sibling machine seating the
+ * same `Member` first, an immediate CHECK, a storage read error) releases the mutex with the
+ * batch's transaction still open: an app `exec` already queued behind the batch runs inside
+ * it, and the rollback below discards that app write although its `exec` resolved. The
+ * common failures (an `Invite` not replicated yet, expired, cancelled, sealed, and
+ * optimystic commit refusals) all fail at `commit` and leave nothing open. (2) The rollback
+ * decision reads `getAutocommit()` after the batch has released the mutex, so after a
+ * `commit`-time failure a queued app statement in flight reads as "still open" too; the
+ * rollback then runs after that statement's own commit and finds nothing to undo — unless
+ * an app `beginTransaction()` also slipped in between, which it would end.
+ */
+async function execStrandTransaction(db, statements, options) {
     try {
-        await fn();
-        await db.commit();
+        await db.exec(`begin transaction;\n${statements.sql}\ncommit;`, statements.params);
+        return;
     }
     catch (error) {
-        // A failed commit() already tears down the transaction, so rollback() would
-        // throw "No transaction active" and mask the real cause — swallow only that.
-        try {
-            await db.rollback();
+        if (!isNestedBeginRefusal(error)) {
+            await rollbackBatchLeftOpen(db, error);
+            throw error;
         }
-        catch (rollbackError) {
-            log('Rollback after strand transaction failure was a no-op: %s', rollbackError);
+        if (options?.joinOpenTransaction === false) {
+            throw new StrandTransactionBusyError({ cause: error });
         }
-        throw error;
     }
+    await db.exec(statements.sql, statements.params);
 }
 /**
- * File the `Strand.Revocation` tombstone that retires a deleted row's StampId.
+ * Roll back the batch's own transaction when a statement before `commit` failed and left
+ * it open; a `commit`-time failure has already closed it. See the NOTE on
+ * {@link execStrandTransaction} for what this cannot tell apart.
+ */
+async function rollbackBatchLeftOpen(db, cause) {
+    if (db.getAutocommit()) {
+        return;
+    }
+    try {
+        await db.rollback();
+        log('Rolled back a strand write batch left open by a failed statement: %s', cause);
+    }
+    catch (rollbackError) {
+        log('Rolling back a failed strand write batch failed (%s): %o', cause, rollbackError);
+    }
+}
+/**
+ * The `Strand.Revocation` tombstone insert that retires a deleted row's StampId.
  *
- * Runs inside the SAME transaction as the delete it accompanies — the guarded
- * tables' `RevocationRecorded` (deferred) requires the tombstone at commit, and
+ * Always batched with the delete it accompanies — the guarded tables'
+ * `RevocationRecorded` (deferred) requires the tombstone at commit, and
  * `Revocation.RowIsGone` (also deferred) requires the row to already be gone, so
  * the pair only ever lands together.
  *
@@ -168,16 +237,42 @@ async function inStrandTransaction(db, fn) {
  * removes it. Unlike the sibling tables' nullable contexts, `Revocation`'s
  * context is non-null — both fields are always supplied.
  *
- * @param db - The strand database, INSIDE an open transaction.
  * @param tableName - Which guarded table the stamp belonged to.
  * @param stampId - The retired stamp.
  * @param retiree - The committed member filing the tombstone (the delete's own signer).
  */
-async function insertRevocation(db, tableName, stampId, retiree) {
-    const signature = signStrandApproval(['Strand.Revocation', 'retire', tableName, stampId], retiree.privateKeyB64);
-    await db.exec(`insert into Strand.Revocation (TableName, StampId)
-       with context MemberKey = ?, Signature = ?
-       values (?, ?)`, [retiree.publicKeyB64, signature, tableName, stampId]);
+function revocationStatement(tableName, stampId, retiree) {
+    return {
+        sql: `insert into Strand.Revocation (TableName, StampId)
+       with context MemberKey = :revocationSignerKey, Signature = :revocationSignature
+       values (:revocationTable, :revocationStampId);`,
+        params: {
+            revocationSignerKey: retiree.publicKeyB64,
+            revocationSignature: signStrandApproval(['Strand.Revocation', 'retire', tableName, stampId], retiree.privateKeyB64),
+            revocationTable: tableName,
+            revocationStampId: stampId,
+        },
+    };
+}
+/**
+ * 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 class PreSplitStrandIdentityError extends Error {
+    constructor(strandId) {
+        super(`Closed strand ${strandId} was founded before per-party strand identity: its founding ` +
+            'member key is derived from the shared MemberPrivateKey that every joining party holds, ' +
+            'so any member can act as its founder. It cannot be repaired — recreate the strand ' +
+            '(unpublish it and found a new one).');
+        this.strandId = strandId;
+        this.name = 'PreSplitStrandIdentityError';
+    }
 }
 /**
  * Count rows in a `Strand.*` table as seen by this database instance.
@@ -204,6 +299,13 @@ async function strandTableCount(db, table) {
  * scale; if membership churn ever makes that table large — the growth the
  * `Revocation` schema comment already flags, tracked by `debt-strand-tombstone-reap`
  * — this wants a stored "founding closed" marker rather than a scan per call.
+ *
+ * NOTE: on a strand that has never revoked anyone, `Strand.Revocation` has never been
+ * written, so this node does not hold its block, and the storage layer consults the
+ * block's cohort on every read of a block it does not hold — this scan and every
+ * `NotRevoked` insert check pay that per call. Not measured, and cheap while strand
+ * membership writes are rare; if they become frequent, file a singleton marker row in
+ * the strand schema the way the control schema does (`ControlDatabase.openRevocationLedger`).
  */
 async function strandHasManagerRevocation(db) {
     for await (const row of db.eval('select TableName from Strand.Revocation')) {
@@ -305,6 +407,25 @@ async function insertFounderManagerIfAbsent(db, memberKey, strandId) {
        values (?, 0, ?)`, [memberKey, generateStrandStampId()]);
     log('Inserted founding Manager for strand %s', strandId);
 }
+/**
+ * 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 async function assertNotPreSplitStrand(db, strandId, sharedMemberPublicKey) {
+    if (await memberStampId(db, sharedMemberPublicKey) !== undefined
+        || await managerRow(db, sharedMemberPublicKey) !== undefined) {
+        throw new PreSplitStrandIdentityError(strandId);
+    }
+}
 /**
  * Founder-only one-time bootstrap of a strand's `Strand.*` membership/RBAC rows.
  *
@@ -326,20 +447,30 @@ async function insertFounderManagerIfAbsent(db, memberKey, strandId) {
  * 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 async function bootstrapFounderMembership(db, params) {
-    const { strandId, type, founderKeyPair } = params;
+    const { strandId, type, founderKeyPair, sharedMemberPublicKey } = params;
     log('Founder bootstrap for strand %s (type %s)', strandId, type);
     // Validate BEFORE writing anything: a closed strand with no founder key must
     // fail without leaving a closed `Header` that has no founding Member/Manager
     // (such a strand could never admit anyone).
     if (type === 'c' && !founderKeyPair) {
-        throw new Error(`Cannot bootstrap closed strand ${strandId}: no founder key pair derived from MemberPrivateKey. ` +
-            'A closed strand needs a founding Member + Manager or it can never admit members.');
+        throw new Error(`Cannot bootstrap closed strand ${strandId}: no founder key pair derived from this party's ` +
+            'StrandPartyKey. A closed strand needs a founding Member + Manager or it can never admit members.');
+    }
+    if (type === 'c' && sharedMemberPublicKey !== undefined) {
+        await assertNotPreSplitStrand(db, strandId, sharedMemberPublicKey);
     }
     // Header is written for every strand; Member/Manager are closed-only.
     await insertHeaderIfAbsent(db, params);
@@ -428,32 +559,81 @@ export async function issueInvite(db, params) {
  * @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 async function consumeInvite(db, params) {
-    const { inviteKey, invitePrivateKey, memberKey, nowMs } = params;
-    const usagePayload = `${inviteKey}|${memberKey}`;
-    const inviteSignature = signStrandPayload(usagePayload, invitePrivateKey);
-    // Canonicalise "now" the same way issueInvite canonicalises Expiration, so the
-    // schema's `I.Expiration > context.Now` compares like-for-like canonical strings.
-    // Plain runtime Date.now() — the tess Workflow restriction is on scripts, not libs.
-    const nowCanonical = await canonicalDatetime(db, nowMs ?? Date.now());
-    await inStrandTransaction(db, async () => {
-        // 1. Member — admitted by the deferred invite branch (the matching
-        //    ConsumedInvite below), so no manager signature is supplied.
-        await db.exec(`insert into Strand.Member (Key, StampId)
-         with context ManagerKey = null, ManagerSignature = null, MemberSignature = null
-         values (?, ?)`, [memberKey, generateStrandStampId()]);
-        // 2. ConsumedInvite — proves possession of the invite private key and that the
-        //    invite has not expired (NotExpired gate against the canonical Now).
-        await db.exec(`insert into Strand.ConsumedInvite (InviteKey, MemberKey)
-         with context InviteSignature = ?, Now = ?
-         values (?, ?)`, [inviteSignature, nowCanonical, inviteKey, memberKey]);
-    });
+export async function consumeInvite(db, params, options) {
+    const { inviteKey, memberKey } = params;
+    // Member first — admitted by the deferred invite branch (the matching ConsumedInvite
+    // after it), so no manager signature is supplied.
+    const member = {
+        sql: `insert into Strand.Member (Key, StampId)
+       with context ManagerKey = null, ManagerSignature = null, MemberSignature = null
+       values (:memberKey, :memberStampId);`,
+        params: { memberKey, memberStampId: generateStrandStampId() },
+    };
+    await execStrandTransaction(db, combineStatements(member, await consumedInviteStatement(db, params)), options);
     log('Consumed invite %s -> member %s', inviteKey, memberKey);
 }
+/**
+ * The `Strand.ConsumedInvite` marker row insert — the possession-plus-freshness proof
+ * shared by {@link consumeInvite} (batched after its `Member` insert) and
+ * {@link burnInvite} (alone, against an already-seated member).
+ *
+ * The invite signature covers `InviteKey || '|' || MemberKey` (the `ValidUsage` gate),
+ * and "now" is canonicalised the same way {@link issueInvite} canonicalises
+ * `Expiration`, so the schema's `I.Expiration > context.Now` compares like-for-like
+ * canonical strings. Plain runtime Date.now() — the tess Workflow restriction is on
+ * scripts, not libs.
+ */
+async function consumedInviteStatement(db, params) {
+    const { inviteKey, invitePrivateKey, memberKey, nowMs } = params;
+    return {
+        sql: `insert into Strand.ConsumedInvite (InviteKey, MemberKey)
+       with context InviteSignature = :consumedSignature, Now = :consumedNow
+       values (:consumedInviteKey, :consumedMemberKey);`,
+        params: {
+            consumedSignature: signStrandPayload(`${inviteKey}|${memberKey}`, invitePrivateKey),
+            consumedNow: await canonicalDatetime(db, nowMs ?? Date.now()),
+            consumedInviteKey: inviteKey,
+            consumedMemberKey: memberKey,
+        },
+    };
+}
+/**
+ * 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 async function burnInvite(db, params, options) {
+    await execStrandTransaction(db, await consumedInviteStatement(db, params), options);
+    log('Burned invite %s against existing member %s', params.inviteKey, params.memberKey);
+}
 /**
  * Every value of `InviteKey` in one of the two invite-marker tables, as a `Set`.
  *
@@ -593,6 +773,17 @@ async function memberStampId(db, memberKey) {
     }
     return undefined;
 }
+/**
+ * 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 async function isStrandMember(db, memberKey) {
+    return await memberStampId(db, memberKey) != null;
+}
 /**
  * Admit a `Member` directly by manager signature — the sibling of the invite
  * path on `Member.Authorized`'s direct-manager branch.
@@ -608,18 +799,31 @@ async function memberStampId(db, memberKey) {
  *
  * @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 async function addMemberByManager(db, params) {
+export async function addMemberByManager(db, params, options) {
     const { managerKeyPair, memberKey } = params;
-    const stampId = generateStrandStampId();
-    const signature = signStrandApproval(['Strand.Member', 'add', memberKey, stampId], managerKeyPair.privateKeyB64);
-    await db.exec(`insert into Strand.Member (Key, StampId)
-       with context ManagerKey = ?, ManagerSignature = ?, MemberSignature = null
-       values (?, ?)`, [managerKeyPair.publicKeyB64, signature, memberKey, stampId]);
+    await execStrandTransaction(db, memberAddByManagerStatement(params), options);
     log('Admitted member %s by manager %s', memberKey, managerKeyPair.publicKeyB64);
 }
+/** The manager-signed `Strand.Member` insert behind {@link addMemberByManager}, under a fresh stamp. */
+function memberAddByManagerStatement(params) {
+    const { managerKeyPair, memberKey } = params;
+    const stampId = generateStrandStampId();
+    return {
+        sql: `insert into Strand.Member (Key, StampId)
+       with context ManagerKey = :memberAdmitterKey, ManagerSignature = :memberAdmitterSignature, MemberSignature = null
+       values (:memberKey, :memberStampId);`,
+        params: {
+            memberAdmitterKey: managerKeyPair.publicKeyB64,
+            memberAdmitterSignature: signStrandApproval(['Strand.Member', 'add', memberKey, stampId], managerKeyPair.privateKeyB64),
+            memberKey,
+            memberStampId: stampId,
+        },
+    };
+}
 /**
  * Revoke a `Member` on the signature of an existing manager.
  *
@@ -665,25 +869,30 @@ export async function addMemberByManager(db, params) {
  *
  * @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 async function revokeMember(db, params) {
+export async function revokeMember(db, params, options) {
     const { managerKeyPair, memberKey } = params;
     const stampId = await memberStampId(db, memberKey);
     if (stampId == null) {
         log('Member %s already absent; skipping revoke', memberKey);
         return;
     }
-    const signature = signStrandApproval(['Strand.Member', 'remove', memberKey, stampId], managerKeyPair.privateKeyB64);
-    await inStrandTransaction(db, async () => {
-        await db.exec(`delete from Strand.Member
-         with context ManagerKey = ?, ManagerSignature = ?, MemberSignature = null
-         where Key = ?`, [managerKeyPair.publicKeyB64, signature, memberKey]);
-        await insertRevocation(db, 'Member', stampId, managerKeyPair);
-    });
+    const removal = {
+        sql: `delete from Strand.Member
+       with context ManagerKey = :memberRemoverKey, ManagerSignature = :memberRemoverSignature, MemberSignature = null
+       where Key = :memberKey;`,
+        params: {
+            memberRemoverKey: managerKeyPair.publicKeyB64,
+            memberRemoverSignature: signStrandApproval(['Strand.Member', 'remove', memberKey, stampId], managerKeyPair.privateKeyB64),
+            memberKey,
+        },
+    };
+    await execStrandTransaction(db, combineStatements(removal, revocationStatement('Member', stampId, managerKeyPair)), options);
     log('Revoked member %s by manager %s', memberKey, managerKeyPair.publicKeyB64);
 }
 /**
@@ -707,10 +916,11 @@ export async function revokeMember(db, params) {
  *
  * @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 async function leaveStrand(db, params) {
+export async function leaveStrand(db, params, options) {
     const { memberKeyPair } = params;
     const memberKey = memberKeyPair.publicKeyB64;
     const stampId = await memberStampId(db, memberKey);
@@ -718,13 +928,16 @@ export async function leaveStrand(db, params) {
         log('Member %s already absent; skipping leave', memberKey);
         return;
     }
-    const signature = signStrandApproval(['Strand.Member', 'leave', memberKey, stampId], memberKeyPair.privateKeyB64);
-    await inStrandTransaction(db, async () => {
-        await db.exec(`delete from Strand.Member
-         with context ManagerKey = null, ManagerSignature = null, MemberSignature = ?
-         where Key = ?`, [signature, memberKey]);
-        await insertRevocation(db, 'Member', stampId, memberKeyPair);
-    });
+    const departure = {
+        sql: `delete from Strand.Member
+       with context ManagerKey = null, ManagerSignature = null, MemberSignature = :memberSignature
+       where Key = :memberKey;`,
+        params: {
+            memberSignature: signStrandApproval(['Strand.Member', 'leave', memberKey, stampId], memberKeyPair.privateKeyB64),
+            memberKey,
+        },
+    };
+    await execStrandTransaction(db, combineStatements(departure, revocationStatement('Member', stampId, memberKeyPair)), options);
     log('Member %s left the strand', memberKey);
 }
 /**
@@ -757,10 +970,13 @@ export async function leaveStrand(db, params) {
  *
  * @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 async function registerMemberPeer(db, params) {
+export async function registerMemberPeer(db, params, options) {
     const { memberKeyPair, peerId } = params;
     const memberKey = memberKeyPair.publicKeyB64;
     if (await memberPeerStampId(db, memberKey, peerId) != null) {
@@ -768,10 +984,17 @@ export async function registerMemberPeer(db, params) {
         return;
     }
     const stampId = generateStrandStampId();
-    const signature = signStrandApproval(['Strand.MemberPeer', 'add', memberKey, peerId, stampId], memberKeyPair.privateKeyB64);
-    await db.exec(`insert into Strand.MemberPeer (MemberKey, PeerId, StampId)
-       with context Signature = ?, ManagerKey = null, ManagerSignature = null
-       values (?, ?, ?)`, [signature, memberKey, peerId, stampId]);
+    await execStrandTransaction(db, {
+        sql: `insert into Strand.MemberPeer (MemberKey, PeerId, StampId)
+       with context Signature = :peerSignature, ManagerKey = null, ManagerSignature = null
+       values (:peerMemberKey, :peerId, :peerStampId);`,
+        params: {
+            peerSignature: signStrandApproval(['Strand.MemberPeer', 'add', memberKey, peerId, stampId], memberKeyPair.privateKeyB64),
+            peerMemberKey: memberKey,
+            peerId,
+            peerStampId: stampId,
+        },
+    }, options);
     log('Registered MemberPeer (%s, %s)', memberKey, peerId);
 }
 /**
@@ -878,10 +1101,13 @@ async function memberPeerStampId(db, memberKey, peerId) {
  * @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 async function removeMemberPeer(db, params) {
+export async function removeMemberPeer(db, params, options) {
     const memberKey = 'memberKeyPair' in params ? params.memberKeyPair.publicKeyB64 : params.memberKey;
     const { peerId } = params;
     const stampId = await memberPeerStampId(db, memberKey, peerId);
@@ -889,14 +1115,10 @@ export async function removeMemberPeer(db, params) {
         log('MemberPeer (%s, %s) already absent; skipping', memberKey, peerId);
         return;
     }
-    await inStrandTransaction(db, async () => {
-        if ('memberKeyPair' in params) {
-            await deleteOwnMemberPeer(db, params, stampId);
-        }
-        else {
-            await deleteMemberPeerByManager(db, params, stampId);
-        }
-    });
+    const removal = 'memberKeyPair' in params
+        ? ownMemberPeerRemovalStatements(params, stampId)
+        : memberPeerRemovalByManagerStatements(params, stampId);
+    await execStrandTransaction(db, removal, options);
     // NOTE: the delete's `where` puts an equality on BOTH composite-PK columns, which the
     // optimystic vtab module serves via a single-key seek that can MISS on a networked
     // strand (see scanMemberPeers' doc). A missed seek deletes zero rows and still
@@ -911,14 +1133,20 @@ export async function removeMemberPeer(db, params) {
     log('Removed MemberPeer (%s, %s)', memberKey, peerId);
 }
 /** The self branch: the owning member signs the remove-tagged digest + tombstone. */
-async function deleteOwnMemberPeer(db, params, stampId) {
+function ownMemberPeerRemovalStatements(params, stampId) {
     const { memberKeyPair, peerId } = params;
     const memberKey = memberKeyPair.publicKeyB64;
-    const signature = signStrandApproval(['Strand.MemberPeer', 'remove', memberKey, peerId, stampId], memberKeyPair.privateKeyB64);
-    await db.exec(`delete from Strand.MemberPeer
-       with context Signature = ?, ManagerKey = null, ManagerSignature = null
-       where MemberKey = ? and PeerId = ?`, [signature, memberKey, peerId]);
-    await insertRevocation(db, 'MemberPeer', stampId, memberKeyPair);
+    const removal = {
+        sql: `delete from Strand.MemberPeer
+       with context Signature = :peerSignature, ManagerKey = null, ManagerSignature = null
+       where MemberKey = :peerMemberKey and PeerId = :peerId;`,
+        params: {
+            peerSignature: signStrandApproval(['Strand.MemberPeer', 'remove', memberKey, peerId, stampId], memberKeyPair.privateKeyB64),
+            peerMemberKey: memberKey,
+            peerId,
+        },
+    };
+    return combineStatements(removal, revocationStatement('MemberPeer', stampId, memberKeyPair));
 }
 /**
  * The manager branch: a manager signs the manager-remove-tagged digest + tombstone.
@@ -931,13 +1159,20 @@ async function deleteOwnMemberPeer(db, params, stampId) {
  * members' nodes resume answering and dialing that peer. Only clear a binding
  * that should never have existed, or a peer that is truly gone.
  */
-async function deleteMemberPeerByManager(db, params, stampId) {
+function memberPeerRemovalByManagerStatements(params, stampId) {
     const { managerKeyPair, memberKey, peerId } = params;
-    const signature = signStrandApproval(['Strand.MemberPeer', 'manager-remove', memberKey, peerId, stampId], managerKeyPair.privateKeyB64);
-    await db.exec(`delete from Strand.MemberPeer
-       with context Signature = null, ManagerKey = ?, ManagerSignature = ?
-       where MemberKey = ? and PeerId = ?`, [managerKeyPair.publicKeyB64, signature, memberKey, peerId]);
-    await insertRevocation(db, 'MemberPeer', stampId, managerKeyPair);
+    const removal = {
+        sql: `delete from Strand.MemberPeer
+       with context Signature = null, ManagerKey = :peerManagerKey, ManagerSignature = :peerManagerSignature
+       where MemberKey = :peerMemberKey and PeerId = :peerId;`,
+        params: {
+            peerManagerKey: managerKeyPair.publicKeyB64,
+            peerManagerSignature: signStrandApproval(['Strand.MemberPeer', 'manager-remove', memberKey, peerId, stampId], managerKeyPair.privateKeyB64),
+            peerMemberKey: memberKey,
+            peerId,
+        },
+    };
+    return combineStatements(removal, revocationStatement('MemberPeer', stampId, managerKeyPair));
 }
 // ── Manager rotation (add / remove RBAC admins) ───────────────────────────────
 /**
@@ -988,11 +1223,22 @@ async function managerRow(db, memberKey) {
  *
  * @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 async function addManager(db, params) {
+export async function addManager(db, params, options) {
+    const { byManagerKeyPair, newManagerKey } = params;
+    const promotion = await managerAddStatement(db, params);
+    await execStrandTransaction(db, promotion, options);
+    log('Added manager %s (generation %d) by %s', newManagerKey, promotion.params.managerGeneration, byManagerKeyPair.publicKeyB64);
+}
+/**
+ * The `Strand.Manager` insert behind {@link addManager}: reads the authorizer's generation,
+ * seats the new manager one above it under a fresh stamp, and signs all three.
+ */
+async function managerAddStatement(db, params) {
     const { byManagerKeyPair, newManagerKey } = params;
     const authorizer = await managerRow(db, byManagerKeyPair.publicKeyB64);
     // NOTE: +1 saturates at Number.MAX_SAFE_INTEGER, where the successor compares equal
@@ -1002,11 +1248,18 @@ export async function addManager(db, params) {
     // from outside this function, clamp or reject here rather than emitting a dead row.
     const generation = authorizer == null ? 1 : authorizer.generation + 1;
     const stampId = generateStrandStampId();
-    const signature = signStrandApproval(['Strand.Manager', 'add', newManagerKey, generation, stampId], byManagerKeyPair.privateKeyB64);
-    await db.exec(`insert into Strand.Manager (MemberKey, Generation, StampId)
-       with context ManagerKey = ?, Signature = ?
-       values (?, ?, ?)`, [byManagerKeyPair.publicKeyB64, signature, newManagerKey, generation, stampId]);
-    log('Added manager %s (generation %d) by %s', newManagerKey, generation, byManagerKeyPair.publicKeyB64);
+    return {
+        sql: `insert into Strand.Manager (MemberKey, Generation, StampId)
+       with context ManagerKey = :managerAuthorizerKey, Signature = :managerSignature
+       values (:managerMemberKey, :managerGeneration, :managerStampId);`,
+        params: {
+            managerAuthorizerKey: byManagerKeyPair.publicKeyB64,
+            managerSignature: signStrandApproval(['Strand.Manager', 'add', newManagerKey, generation, stampId], byManagerKeyPair.privateKeyB64),
+            managerMemberKey: newManagerKey,
+            managerGeneration: generation,
+            managerStampId: stampId,
+        },
+    };
 }
 /**
  * Admit a key as a `Member` AND promote it to `Manager`, atomically — the one-step
@@ -1035,15 +1288,15 @@ export async function addManager(db, params) {
  *
  * @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 async function admitManager(db, params) {
+export async function admitManager(db, params, options) {
     const { byManagerKeyPair, newManagerKey } = params;
-    await inStrandTransaction(db, async () => {
-        await addMemberByManager(db, { managerKeyPair: byManagerKeyPair, memberKey: newManagerKey });
-        await addManager(db, { byManagerKeyPair, newManagerKey });
-    });
+    const admission = memberAddByManagerStatement({ managerKeyPair: byManagerKeyPair, memberKey: newManagerKey });
+    const promotion = await managerAddStatement(db, params);
+    await execStrandTransaction(db, combineStatements(admission, promotion), options);
     log('Admitted + promoted manager %s by %s', newManagerKey, byManagerKeyPair.publicKeyB64);
 }
 /**
@@ -1112,13 +1365,14 @@ export async function admitManager(db, params) {
  *
  * @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 async function removeManager(db, params) {
+export async function removeManager(db, params, options) {
     const { byManagerKeyPair, targetManagerKey } = params;
     const target = await managerRow(db, targetManagerKey);
     if (target == null) {
@@ -1131,14 +1385,26 @@ export async function removeManager(db, params) {
             + 'Manager table. To permanently freeze admission instead, call sealStrand.');
     }
     const signature = signStrandApproval(['Strand.Manager', tag, targetManagerKey, target.stampId], byManagerKeyPair.privateKeyB64);
-    await inStrandTransaction(db, async () => {
-        await db.exec(`delete from Strand.Manager
-         with context ManagerKey = ?, Signature = ?
-         where MemberKey = ?`, [byManagerKeyPair.publicKeyB64, signature, targetManagerKey]);
-        await insertRevocation(db, 'Manager', target.stampId, byManagerKeyPair);
-    });
+    await execStrandTransaction(db, managerRemovalStatements(byManagerKeyPair, signature, targetManagerKey, target.stampId), options);
     log('Removed manager %s by %s', targetManagerKey, byManagerKeyPair.publicKeyB64);
 }
+/**
+ * The `Strand.Manager` delete plus its tombstone, shared by {@link removeManager} and
+ * {@link sealStrand}, which differ only in the action tag `signature` was minted under.
+ */
+function managerRemovalStatements(signer, signature, targetManagerKey, targetStampId) {
+    const removal = {
+        sql: `delete from Strand.Manager
+       with context ManagerKey = :managerRemoverKey, Signature = :managerRemoverSignature
+       where MemberKey = :managerMemberKey;`,
+        params: {
+            managerRemoverKey: signer.publicKeyB64,
+            managerRemoverSignature: signature,
+            managerMemberKey: targetManagerKey,
+        },
+    };
+    return combineStatements(removal, revocationStatement('Manager', targetStampId, signer));
+}
 /**
  * Seal the strand: the SOLE manager deliberately steps down, permanently freezing
  * membership.
@@ -1177,6 +1443,7 @@ export async function removeManager(db, params) {
  *
  * @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
@@ -1185,7 +1452,7 @@ export async function removeManager(db, params) {
  *   and returns quietly (restart-safe, matching {@link bootstrapFounderMembership}
  *   and {@link removeManager}'s absent-row no-op).
  */
-export async function sealStrand(db, params) {
+export async function sealStrand(db, params, options) {
     const { managerKeyPair } = params;
     const managerCount = await strandTableCount(db, 'Manager');
     if (managerCount === 0) {
@@ -1209,12 +1476,7 @@ export async function sealStrand(db, params) {
         throw new Error('Cannot seal: the supplied keypair does not hold the sole Manager row.');
     }
     const signature = signStrandApproval(['Strand.Manager', 'seal', managerKeyPair.publicKeyB64, self.stampId], managerKeyPair.privateKeyB64);
-    await inStrandTransaction(db, async () => {
-        await db.exec(`delete from Strand.Manager
-         with context ManagerKey = ?, Signature = ?
-         where MemberKey = ?`, [managerKeyPair.publicKeyB64, signature, managerKeyPair.publicKeyB64]);
-        await insertRevocation(db, 'Manager', self.stampId, managerKeyPair);
-    });
+    await execStrandTransaction(db, managerRemovalStatements(managerKeyPair, signature, managerKeyPair.publicKeyB64, self.stampId), options);
     log('Sealed strand: sole manager %s stepped down', managerKeyPair.publicKeyB64);
 }
 /**