@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/manager.js

@@ -1,45 +1,219 @@
 import { normalizeDID } from '@kokuin/token';
 import { HLC } from '@kubun/hlc';
 import { getP2PStore } from '@kubun/store-p2p';
-import { commitInvite, createGroup, createInvite, processWelcome, removeMember } from '@kumiai/mls';
+import { commitInvite, commitLedgerEntries, controlCapabilities, createGroup, createInvite, foldEnvelope, processWelcome, readGroupAnchor, removeMember } from '@kumiai/mls';
 import { toB64 } from '@sozai/codec';
+import { toISO } from '../context/types.js';
 import { bindHubToGroup, upsertHub } from '../hub/manager.js';
-import { reprojectAdminRoster } from './admin-roster.js';
 import { reprojectGroupSettings } from './circle-projection.js';
 import { GROUP_SETTINGS_ENTRY_TYPE } from './circle-reducers.js';
-import { buildCurrentGroupAnchorExtension, groupAnchorCapabilities, readGroupAnchor } from './group-anchor.js';
-import { ledgerEntryDigest, signLedgerEntry } from './ledger-entry.js';
+import { serializeCommitJournalBlob } from './commit-adoption.js';
+import { settleControlRequest } from './control-request.js';
+import { buildKubunGroupAnchorExtension } from './group-anchor.js';
+import { ledgerEntryDigest, signLedgerEntry, verifyLedgerEntry } from './ledger.js';
+import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
+import { entriesSurfacedByOwnCommit, foldCommittedLedgerEntries } from './ledger-commit-fold.js';
+import { serializeMLSGroupState } from './mls-state.js';
+import { mirrorRosterRoles, roleFromRoster } from './roster-projection.js';
+/**
+ * Refuse to author a Remove the group will refuse. A receiver rejects a Remove
+ * whose target is still admin in the roster the commit's OWN entries fold to, so
+ * the demotion must ride the same commit. The MLS library's pre-flight does not
+ * cover this — it checks each entry's authority, not the removal's legality.
+ *
+ * Without the check the write path fails OPEN: the author tombstones the member
+ * locally and reports success while every receiver drops the commit.
+ *
+ * Test the FOLDED roster, not the one the handle holds now — the demotion riding
+ * this commit is what makes the removal legal. A fold that rejects outright is
+ * left alone: the commit attempt fails a few lines later with the library's own
+ * precise reason.
+ */ async function assertRemovalDemotes(handle, memberDID, tokens) {
+    const inputs = [];
+    for (const token of tokens){
+        const verified = await verifyLedgerEntry(token);
+        if (verified == null) {
+            continue;
+        }
+        inputs.push({
+            verified,
+            entryID: ledgerEntryDigest(token)
+        });
+    }
+    const folded = foldEnvelope(handle.roster, inputs, handle.groupID);
+    if (!folded.ok) {
+        return;
+    }
+    if (folded.roster.roles.get(normalizeDID(memberDID)) === 'admin') {
+        throw new Error(`Cannot remove ${memberDID}: still an admin in the roster this commit folds to. A demotion entry must ride the same commit.`);
+    }
+}
 export class GroupManager {
     #deviceID;
-    #getRandomID;
+    #runtime;
     #hlc;
     #registry;
+    #stores;
+    #emitter;
+    #logger;
     constructor(params){
         this.#deviceID = params.identity.id;
-        this.#getRandomID = params.getRandomID;
+        this.#runtime = params.runtime;
         this.#hlc = params.hlc;
         this.#registry = params.registry;
+        this.#stores = params.stores;
+        this.#emitter = params.emitter;
+        this.#logger = params.logger;
+    }
+    /**
+   * Mirror the roster and fold the entries a commit this device authored enacted,
+   * through the same projections a received commit's fold writes.
+   *
+   * Runs even for a commit that surfaced NO entries: a role change is folded by
+   * the MLS library into the roster rather than surfaced as an entry.
+   *
+   * Lock order is lane → registry, so this opens its own transaction after the
+   * handle swap released the mutex — no transaction may span a lane operation.
+   * Never throws: the hub has already accepted the commit.
+   */ async #foldOwnCommittedEntries(groupID, handle, tokens) {
+        const stores = this.#stores;
+        if (stores == null) {
+            return;
+        }
+        const entries = entriesSurfacedByOwnCommit(handle, tokens);
+        try {
+            const { affected, roleChanged } = await stores.withTransaction(async (tx)=>{
+                const p2pStore = await getP2PStore(tx);
+                // The author reads roles from the same authenticated source its
+                // co-members read them from on receive: the post-commit handle's roster,
+                // folded from the genesis anchor and the entries the commit chain
+                // enacted. All reads and writes go through the transactional store so
+                // they share the transaction's single connection.
+                //
+                // This is the ONLY place the author's own device learns a role its own
+                // commit changed — the role it reports is the post-commit one, since the
+                // mirror is what makes the change true locally.
+                const members = await p2pStore.listGroupMembers(groupID);
+                const roleChanged = await mirrorRosterRoles({
+                    store: p2pStore,
+                    groupID,
+                    roster: handle.roster,
+                    memberDIDs: members.map((member)=>member.member_did),
+                    members
+                });
+                if (entries.length === 0) {
+                    return {
+                        affected: [],
+                        roleChanged
+                    };
+                }
+                return {
+                    affected: await foldCommittedLedgerEntries({
+                        handle,
+                        entries,
+                        p2pStore,
+                        groupID,
+                        hlc: this.#hlc,
+                        ...this.#logger != null ? {
+                            logger: this.#logger
+                        } : {}
+                    }),
+                    roleChanged
+                };
+            });
+            // Past commit: the rows the events announce are durable.
+            const emitter = this.#emitter;
+            if (emitter != null) {
+                for (const ledger of affected){
+                    await emitLedgerAffectedEvents(emitter, {
+                        applied: true,
+                        affected: {
+                            kind: 'ledger',
+                            ledger
+                        }
+                    });
+                }
+                for (const member of roleChanged){
+                    await emitter.emit('groupMemberRoleChanged', member);
+                }
+            }
+        } catch (error) {
+            this.#logger?.warn('folding own committed ledger entries failed', {
+                groupID,
+                error
+            });
+        }
     }
     async createGroup(params) {
-        const groupID = this.#getRandomID();
+        const groupID = this.#runtime.getRandomID();
         // The creator DID is baked into the MLS GroupContext as the immutable
         // genesis anchor, alongside a fresh 32-byte recovery seed. Both survive
         // every epoch and are authenticated by the GroupInfo signature, so every
         // member derives the same recovery rendezvous. Every member leaf advertises
         // the anchor extension capability so the group can be invited to.
-        const recoverySecret = toB64(crypto.getRandomValues(new Uint8Array(32)));
+        // Randomness comes from the host runtime, never a global: this seed is baked
+        // into the GroupContext for the life of the group and is what every member's
+        // recovery rendezvous derives from, so it is the one value that most needs
+        // the platform's own CSPRNG rather than whatever `crypto` a bundler resolved.
+        const recoverySecret = toB64(this.#runtime.getRandomValues(new Uint8Array(32)));
         const { group } = await createGroup(params.identity, groupID, {
             extensions: [
-                buildCurrentGroupAnchorExtension(normalizeDID(params.identity.id), recoverySecret)
+                buildKubunGroupAnchorExtension(normalizeDID(params.identity.id), recoverySecret)
             ],
-            capabilities: groupAnchorCapabilities()
+            capabilities: controlCapabilities()
         });
         // Atomic register + bind: each `hubs` entry is upserted via `upsertHub`
-        // and bound to the group inside one transaction. A
-        // HubServerDIDConflictError on any entry rolls back the group row, the
-        // MLS state, the membership row, and any earlier hub bindings that were
-        // already added in this transaction.
+        // and bound to the group inside one transaction, so a failure on any entry
+        // rolls back the group row, the MLS state, the membership row, and any
+        // earlier hub bindings that were already added in this transaction.
+        // The group's name and description are a ledger entry like any other, so
+        // they are ENACTED by a commit rather than written straight to the store.
+        // A seeded, un-enacted entry is not an option: `isLedgerComplete` folds a
+        // head from the ids the handle holds and compares it to the authenticated
+        // head, which only moves when a commit enacts entries — so an entry the
+        // head does not cover makes the peer read itself as stranded for life.
+        //
+        // The creator commits to itself: there are no co-members yet, so the commit
+        // message goes nowhere and there is nothing to fan out. What it buys is the
+        // head moving to cover the entry, which is what makes the handle's ledger
+        // complete from the first epoch and what lets a joiner gather these settings
+        // over the authenticated ledger rather than a side channel.
         const hubs = params.hubs ?? [];
+        const settingsHLC = HLC.serialize(this.#hlc.now());
+        // `description` is OMITTED when absent, never `''`: the settings reducer
+        // treats `''` as a real value that CLEARS the field.
+        const settingsValue = {
+            name: params.name,
+            ...params.description != null ? {
+                description: params.description
+            } : {}
+        };
+        // The creator is admin by construction, so the group's commit-hub designation
+        // is authored right here, in the genesis settings the founding commit enacts:
+        // the first hub bound below is the one `insertGroupHub` auto-designates
+        // locally, and carrying it as folded group state is what lets every other
+        // device fold the SAME designation rather than each fall back to its own
+        // first-bound hub. A hubless group folds no designation and keeps using its
+        // loopback lane.
+        const firstHub = hubs[0];
+        if (firstHub != null) {
+            settingsValue.commitHub = firstHub.serverDID != null ? {
+                url: firstHub.url,
+                serverDID: firstHub.serverDID
+            } : {
+                url: firstHub.url
+            };
+        }
+        const settingsToken = await signLedgerEntry(params.identity, {
+            type: GROUP_SETTINGS_ENTRY_TYPE,
+            groupID,
+            subject: groupID,
+            value: settingsValue,
+            ord: settingsHLC
+        });
+        const { newGroup: seededGroup } = await commitLedgerEntries(group, [
+            settingsToken
+        ]);
         await params.stores.withTransaction(async (tx)=>{
             const store = await getP2PStore(tx);
             await store.createGroup({
@@ -51,67 +225,49 @@ export class GroupManager {
             });
             await this.#registry.seed({
                 groupID,
-                handle: group,
+                handle: seededGroup,
                 stores: tx
             });
             // The membership row must exist before projection (setGroupMemberRole is
-            // update-only); the role value here is irrelevant — projecting the genesis
-            // anchor below overwrites it. The ledger fold is the only writer of role.
+            // update-only); the role value here is irrelevant — the roster mirror
+            // below overwrites it.
             await store.addGroupMember({
                 group_id: groupID,
                 member_did: params.identity.id,
                 role: 'member',
                 hlc: HLC.serialize(this.#hlc.now())
             });
-            // Derive the creator's admin role from the genesis anchor: folding the
-            // (empty) ledger to its seed {creator} projects the creator to 'admin'.
             const anchor = readGroupAnchor(group);
-            if (anchor != null) {
-                await reprojectAdminRoster({
-                    store,
-                    groupID,
-                    anchor
-                });
-            }
-            // Seed the group name/description into the ledger: the direct
-            // `store.createGroup` row write does not propagate, so the ledger is the
-            // only channel that carries settings to joiners and survives a reproject.
-            // No broadcast at creation (no co-members yet) — the entry rides catch-up
-            // when peers join. Reprojecting from the seed yields the same name/desc the
-            // group row already holds and sets the settings watermark.
-            const settingsHLC = HLC.serialize(this.#hlc.now());
-            const settingsValue = {
-                name: params.name,
-                description: params.description ?? ''
-            };
-            const settingsToken = await signLedgerEntry(params.identity, {
-                type: GROUP_SETTINGS_ENTRY_TYPE,
-                subject: groupID,
-                value: settingsValue,
-                hlc: settingsHLC
-            });
-            await store.appendLedgerEntry({
-                group_id: groupID,
-                entry_id: ledgerEntryDigest(settingsToken),
-                type: GROUP_SETTINGS_ENTRY_TYPE,
-                subject: groupID,
-                value: settingsValue,
-                hlc: settingsHLC,
-                issuer_did: params.identity.id,
-                signed_token: settingsToken
+            // The handle's roster is authoritative from the first epoch: it folds the
+            // same genesis anchor, so the creator reads as admin here without the
+            // group holding a single ledger entry. Mirroring it is what makes every
+            // later epoch's role a continuation of the authenticated chain rather than
+            // of a separately delivered token.
+            await mirrorRosterRoles({
+                store,
+                groupID,
+                roster: group.roster,
+                memberDIDs: [
+                    params.identity.id
+                ]
             });
             if (anchor != null) {
+                // The seeded handle's own log — it holds exactly the settings entry the
+                // creation commit enacted, which is the whole ledger a group has at
+                // creation.
                 await reprojectGroupSettings({
                     store,
                     groupID,
-                    anchor
+                    anchor,
+                    ledger: seededGroup.ledger
                 });
             }
             for (const hub of hubs){
                 const upserted = await upsertHub({
                     stores: tx,
                     url: hub.url,
-                    serverDID: hub.serverDID ?? null
+                    serverDID: hub.serverDID ?? null,
+                    runtime: this.#runtime
                 });
                 await bindHubToGroup({
                     stores: tx,
@@ -124,18 +280,48 @@ export class GroupManager {
             groupID
         };
     }
-    async inviteToGroup(params) {
+    /**
+   * Add a member by committing directly against the local handle. TEST-ONLY.
+   *
+   * Production invites ride the commit lane: the Add is published to the commit
+   * hub's log under the head CAS, and the local epoch advances only once the hub
+   * accepts. This does neither — it advances and persists the epoch outright —
+   * so calling it on a hub-backed group forks that group, and the fork presents
+   * as a hang rather than an error. `git log -S "groupManager.inviteToGroup"`
+   * shows the last production caller removed by `2e901689`, when the invite
+   * moved onto the lane; `addGroupMember` was deleted rather than renamed for
+   * the same reason. Kept for the ~40 suites that drive a hubless group
+   * directly, and unreachable from outside this package: {@link GroupManager} is
+   * not exported from the plugin's entry point.
+   */ async inviteToGroup(params) {
+        // The roster of the handle the add-commit produced. The invitee's role rides
+        // that commit, so this is the same roster every receiver folds as it applies
+        // the Add — the authenticated epoch chain's order, not a permission the
+        // caller of this method chose to hand us.
+        let postCommitRoster;
         const opResult = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
+            // The entries this invite ADDS to the group's ledger — its own role entry
+            // for the invitee, and nothing else. The invite carries the whole history
+            // (a joiner has nothing to fold it onto), but only what is new rides the
+            // commit, and only what is new has to reach the existing members.
+            const held = new Set(handle.ledgerTokens);
             const { invite } = await createInvite({
                 group: handle,
                 identity: params.identity,
                 recipientDID: params.recipientDID,
                 permission: params.permission
             });
-            const { commitMessage, welcomeMessage, newGroup } = await commitInvite(handle, params.recipientKeyPackage);
+            const addedTokens = invite.ledgerEntries.filter((token)=>!held.has(token));
+            // The invite's ledger entries ride this commit: their content ids go in
+            // the commit's control envelope and the commit advances the ledger head
+            // by exactly those ids, so every receiver folds the invitee's role entry
+            // into its roster as it applies the Add.
+            const { commitMessage, welcomeMessage, newGroup } = await commitInvite(handle, params.recipientKeyPackage, invite);
+            postCommitRoster = newGroup.roster;
             return {
                 result: {
                     invite,
+                    addedTokens,
                     commitMessage,
                     welcomeMessage,
                     ratchetTree: newGroup.state.ratchetTree
@@ -146,34 +332,86 @@ export class GroupManager {
             stores: params.stores
         });
         const store = await getP2PStore(params.stores);
+        // The role comes from the post-commit roster, never from the `permission`
+        // argument: the column must carry only what the commit chain enacted, so
+        // that a caller cannot mint a role the group's other members will not fold.
+        // The roster is always set here — the lane operation assigns it before
+        // returning — and `member` is the roster's own answer for an unlisted DID.
         await store.addGroupMember({
             group_id: params.groupID,
             member_did: params.recipientDID,
-            role: params.permission === 'admin' ? 'admin' : 'member',
+            role: postCommitRoster == null ? 'member' : roleFromRoster(postCommitRoster, params.recipientDID),
             hlc: HLC.serialize(this.#hlc.now())
         });
         return opResult;
     }
     async joinGroup(params) {
-        // Process the welcome message using the invitee's key package bundle
-        const { group } = await processWelcome({
+        // A Welcome is delivered at-least-once — a sender that crashed between
+        // journalling its commit and delivering re-delivers rather than strand an
+        // invitee never told it was added — so this path must absorb the repeat.
+        //
+        // Decided on the EPOCH, not the local group row's status. The status answers
+        // "do I believe I am in this group", and a device is entitled to be wrong:
+        // one asleep across its own removal still reads `joined`, so its genuine
+        // re-admission was discarded as a redelivered Welcome — returning the same
+        // `undefined` a success returns, and leaving it with a handle whose roster
+        // still called it an admin.
+        //
+        // The hazard the dedupe exists for is adopting a handle FROZEN AT ITS
+        // JOINING EPOCH, which is exactly "not ahead of what I hold". So adopt only
+        // a strictly later handle: a repeat is equal-or-lower, a re-admission is
+        // later, no MLS state is a first join.
+        //
+        // Keyed on the id the Welcome DECRYPTS to; the invite's id is an
+        // unauthenticated hint. Cannot be hoisted above the join — that id is
+        // encrypted to the joiner's key — hence `processWelcome` plus this check
+        // rather than `processWelcomeOnce`, which dedupes on group id alone.
+        const p2pStore = await getP2PStore(params.stores);
+        const processed = await processWelcome({
             identity: params.identity,
             invite: params.invite,
             welcome: params.welcomeMessage,
             keyPackageBundle: params.keyPackageBundle,
             ratchetTree: params.ratchetTree
         });
+        const { group } = processed;
+        // Every write below keys on `params.groupID`, the hint. Disagreement would
+        // evaluate the dedupe against one group and seed the handle, roster and hub
+        // bindings onto another, so refuse rather than reconcile.
+        if (group.groupID !== params.groupID) {
+            throw new Error(`joinGroup: the invite names group ${params.groupID} but its Welcome decrypts to ${group.groupID}`);
+        }
+        const held = await p2pStore.getMLSState(group.groupID, this.#deviceID);
+        if (held != null && Number(group.epoch) <= held.epoch) {
+            // A repeat: the first delivery already seeded the handle, the Group row,
+            // the roster and the hub bindings.
+            this.#logger?.debug('welcome for an epoch already held: absorbed as a repeat', {
+                groupID: group.groupID,
+                welcomeEpoch: Number(group.epoch),
+                heldEpoch: held.epoch
+            });
+            return undefined;
+        }
+        // Held state that this Welcome is ahead of: the cached handle can decrypt
+        // nothing at the group's current epoch and must be displaced rather than
+        // defended.
+        const rejoining = held != null;
         // Atomic register + bind: hub entries imported from the invite are
-        // upserted and bound to the group inside one transaction. A
-        // HubServerDIDConflictError on any entry rolls back MLS state, the
-        // (provisional) group row, the membership row, and any earlier hub
-        // bindings.
+        // upserted and bound to the group inside one transaction, so a failure on
+        // any entry rolls back MLS state, the (provisional) group row, the
+        // membership row, and any earlier hub bindings.
         const hubs = params.hubs ?? [];
         await params.stores.withTransaction(async (tx)=>{
+            // `replace` only over MLS state this Welcome is ahead of, established from
+            // the persisted epoch rather than the invite: an unauthenticated payload
+            // must not displace a live member's handle.
             await this.#registry.seed({
                 groupID: params.groupID,
                 handle: group,
-                stores: tx
+                stores: tx,
+                ...rejoining ? {
+                    replace: true
+                } : {}
             });
             // Provision the local Group row if it does not already exist. Required
             // so downstream group-aware components (e.g. HubRelayManager) can read
@@ -188,24 +426,33 @@ export class GroupManager {
                     created_by: params.identity.id,
                     hlc: HLC.serialize(this.#hlc.now())
                 });
+            } else {
+                // A row already here means this device has been in this group before and
+                // left it: joining again is this row rejoining, not a second row for the
+                // same group. The point lookup above is deliberately unfiltered so this
+                // branch can be reached at all.
+                await store.setGroupStatus(params.groupID, 'joined');
             }
             // Seed the full MLS roster (the store roster is the projection of the
             // ratchet tree) so the admin gate can confirm membership of the
-            // creator/existing admins on this peer. Roles default to 'member';
-            // admin authority is derived from the ledger fold and the role column is
-            // corrected when ledger entries arrive.
+            // creator/existing admins on this peer. Roles come from the handle's own
+            // roster, which the Welcome's ledger populates: a joiner therefore learns
+            // who is an admin from the same authenticated fold every other member
+            // holds, at the epoch it joined, without waiting for a token to arrive.
             const localHLC = HLC.serialize(this.#hlc.now());
+            const roster = group.roster;
             await store.addGroupMembers(group.listMembers().map((member)=>({
                     group_id: params.groupID,
                     member_did: member.id,
-                    role: 'member',
+                    role: roleFromRoster(roster, member.id),
                     hlc: localHLC
                 })));
             for (const hub of hubs){
                 const upserted = await upsertHub({
                     stores: tx,
                     url: hub.url,
-                    serverDID: hub.serverDID ?? null
+                    serverDID: hub.serverDID ?? null,
+                    runtime: this.#runtime
                 });
                 await bindHubToGroup({
                     stores: tx,
@@ -216,53 +463,323 @@ export class GroupManager {
         });
         return undefined;
     }
-    async removeMember(params) {
-        const { commitMessage } = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
-            const { commitMessage, newGroup } = await removeMember(handle, params.leafIndex);
-            return {
-                result: {
-                    commitMessage
-                },
-                updated: newGroup
-            };
-        }, {
-            stores: params.stores
+    /**
+   * The admin write path for the control ledger: build a commit carrying no
+   * membership change, only the entries it enacts and the head move covering them.
+   * A role entry that never rides a commit is invisible to every other peer's
+   * roster and to the ledger head.
+   *
+   * BUILD IS SPLIT FROM DRIVE, and every `build*Commit` here shares the contract:
+   * the returned closure is re-run per lane attempt, reads the group's CURRENT
+   * handle and derives a fresh commit against it without advancing the live one,
+   * so a rebase after a lost compare-and-set frames at the up-to-date epoch.
+   * Nothing is adopted, written or handed out before `onAccepted` — adopting
+   * earlier seals the bodies under an epoch no receiver holds — so a losing
+   * attempt is discarded whole.
+   */ buildEnactLedgerCommit(params) {
+        // Reads/writes go through the registry's own connection, not a request
+        // transaction: the lane runs decoupled from the resolver that started it —
+        // possibly after that transaction has committed and across rebases — so it
+        // must observe durable state, not an in-flight write set.
+        return ()=>this.#registry.readHandle(params.groupID, async (handle)=>{
+                const { commitMessage, newGroup } = await commitLedgerEntries(handle, params.tokens);
+                return {
+                    commit: commitMessage,
+                    bodies: params.tokens,
+                    kind: 'ledger',
+                    journal: serializeCommitJournalBlob({
+                        serializedHandle: serializeMLSGroupState(newGroup),
+                        ...params.requestID != null ? {
+                            requestID: params.requestID
+                        } : {}
+                    }),
+                    onAccepted: async ()=>{
+                        await this.#registry.replaceHandle(params.groupID, newGroup);
+                        // The handle is adopted, so this device's own committed entries fold
+                        // through the SAME ingest a co-member's receive side runs on them.
+                        await this.#foldOwnCommittedEntries(params.groupID, newGroup, params.tokens);
+                        await this.#settleCommittedRequest(params.requestID);
+                    }
+                };
+            });
+    }
+    /**
+   * Settle the control request a landed commit enacted, if it had one, with the
+   * artifact it produced when there is one.
+   *
+   * Runs from `onAccepted` and nowhere else: the drive also returns for an
+   * attempt that never landed, and only this closure knows THIS attempt is the
+   * one the group accepted. It runs after the handle swap, so it holds no
+   * registry mutex.
+   */ async #settleCommittedRequest(requestID, result) {
+        const stores = this.#stores;
+        if (requestID == null || stores == null) {
+            return;
+        }
+        await settleControlRequest({
+            stores,
+            requestID,
+            outcome: 'committed',
+            ...result != null ? {
+                result
+            } : {},
+            ...this.#emitter != null ? {
+                emitter: this.#emitter
+            } : {},
+            ...this.#logger != null ? {
+                logger: this.#logger
+            } : {}
         });
-        const store = await getP2PStore(params.stores);
-        await store.removeGroupMember(params.groupID, params.memberDID, HLC.serialize(this.#hlc.now()));
-        return {
-            commitMessage
-        };
     }
-    async removeGroupMember(params) {
-        const { commitMessage } = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
-            const leafIndex = handle.findMemberLeafIndex(params.memberDID);
-            if (leafIndex == null) {
-                throw new Error(`Member ${params.memberDID} not found in MLS group`);
-            }
-            const { commitMessage, newGroup } = await removeMember(handle, leafIndex);
-            return {
-                result: {
-                    commitMessage
-                },
-                updated: newGroup
-            };
-        }, {
-            stores: params.stores
+    /**
+   * The admin membership-add path for the commit lane: build an Add commit
+   * carrying the invitee's key package plus the role entry the invite mints, and
+   * the head move covering it. Same build-vs-drive contract as
+   * {@link buildEnactLedgerCommit}.
+   *
+   * `kind` is `'invite'` because a host cannot re-issue this commit after a crash:
+   * the intent lives in the Add proposal and the KeyPackage, neither of which
+   * survives the process.
+   */ buildInviteCommit(params) {
+        // Reads/writes go through the registry's own connection, not a request
+        // transaction: the lane runs decoupled from the resolver that started it —
+        // possibly after that transaction has committed and across rebases — so it
+        // must observe durable state, not an in-flight write set.
+        return ()=>this.#registry.readHandle(params.groupID, async (handle)=>{
+                // The entries this invite ADDS to the group's ledger — the invitee's own
+                // role entry, and nothing else. The invite carries the whole history (a
+                // joiner has nothing to fold it onto), but only what is new rides the
+                // commit, and only what is new has to reach the existing members.
+                const held = new Set(handle.ledgerTokens);
+                const { invite } = await createInvite({
+                    group: handle,
+                    identity: params.identity,
+                    recipientDID: params.recipientDID,
+                    permission: params.permission
+                });
+                const addedTokens = invite.ledgerEntries.filter((token)=>!held.has(token));
+                const { commitMessage, welcomeMessage, newGroup } = await commitInvite(handle, params.recipientKeyPackage, invite);
+                // Encoded per attempt, before the publish, so the bytes the journal
+                // carries are this attempt's own. The Welcome is inside them, which is
+                // why the blob no longer carries one separately.
+                const invitePayload = await params.encodeInvitePayload({
+                    invite,
+                    welcomeMessage,
+                    ratchetTree: newGroup.state.ratchetTree
+                });
+                return {
+                    commit: commitMessage,
+                    bodies: addedTokens,
+                    kind: 'invite',
+                    journal: serializeCommitJournalBlob({
+                        serializedHandle: serializeMLSGroupState(newGroup),
+                        // The journal is the only durable copy of this payload: a host that
+                        // crashed between the hub accepting this commit and the caller being
+                        // answered has no way to reconstruct it, and the invitee was added
+                        // to the group either way.
+                        invitePayload,
+                        ...params.requestID != null ? {
+                            requestID: params.requestID
+                        } : {}
+                    }),
+                    onAccepted: async ()=>{
+                        await this.#registry.replaceHandle(params.groupID, newGroup);
+                        // The handle is adopted, so this device's own committed entries fold
+                        // through the SAME ingest a co-member's receive side runs on them.
+                        await this.#foldOwnCommittedEntries(params.groupID, newGroup, addedTokens);
+                        // The invitee's role entry is not one of kubun's own types, so the
+                        // fold above skipped it and this is its only writer. The entry's body
+                        // reaches co-members on the commit's own frame; this row is the
+                        // sender's copy, and the fallback a restored handle resolves from.
+                        await this.#recordInvitedMember(params.groupID, newGroup, params.recipientDID);
+                        if (params.onInvited != null) {
+                            await params.onInvited({
+                                invitePayload,
+                                addedTokens
+                            });
+                        }
+                        // The payload settles WITH the request, in one update: the same
+                        // artifact, written to the same row, that a replayed adopt of this
+                        // commit's journal blob would write. Both paths therefore answer the
+                        // caller by the same route.
+                        await this.#settleCommittedRequest(params.requestID, invitePayload);
+                    }
+                };
+            });
+    }
+    /**
+   * Write the membership row for a member an accepted Add commit brought in, and
+   * announce the join.
+   *
+   * The roster comes from the handle this call is given — the ACCEPTED attempt's —
+   * never from a variable a losing attempt may have written. The role comes from
+   * that roster and never from a `permission` argument, so the column can only
+   * carry what the commit chain enacted.
+   *
+   * The author never folds its own commit, so the announcement must come from
+   * here. Every OTHER device announces the same join from its fold, so the two can
+   * never both fire on one device.
+   */ async #recordInvitedMember(groupID, handle, recipientDID) {
+        const stores = this.#stores;
+        if (stores == null) {
+            return;
+        }
+        const store = await getP2PStore(stores);
+        const role = roleFromRoster(handle.roster, recipientDID);
+        await store.addGroupMember({
+            group_id: groupID,
+            member_did: recipientDID,
+            role,
+            hlc: HLC.serialize(this.#hlc.now())
+        });
+        const emitter = this.#emitter;
+        if (emitter == null) {
+            return;
+        }
+        // Read the row back rather than announce what was just written: the store
+        // owns `created_at`, and a row that already existed keeps its own.
+        const row = await store.getGroupMember(groupID, recipientDID);
+        if (row != null) {
+            await emitter.emit('groupMemberJoined', {
+                groupID,
+                memberDID: row.member_did,
+                role: row.role,
+                createdAt: toISO(row.created_at)
+            });
+        }
+    }
+    /**
+   * The admin membership-removal path for the commit lane: build a Remove commit
+   * evicting a member, carrying any demotion entry the removal must enact and the
+   * head move covering it. Same build-vs-drive contract as
+   * {@link buildEnactLedgerCommit}; the leaf index is resolved per attempt so a
+   * rebase cannot evict the leaf a superseded roster held.
+   *
+   * An admin's demotion must ride this very commit — that is what `ledgerEntries`
+   * is for, enforced by {@link assertRemovalDemotes} so a caller that forgets it
+   * fails here rather than shipping a commit the group silently drops.
+   *
+   * `kind` is `'remove'` because a host cannot re-issue this commit after a crash:
+   * the intent lives in the MLS Remove proposal, which does not survive the
+   * process.
+   */ buildRemoveCommit(params) {
+        const tokens = params.ledgerEntries ?? [];
+        return ()=>this.#registry.readHandle(params.groupID, async (handle)=>{
+                const leafIndex = handle.findMemberLeafIndex(params.memberDID);
+                if (leafIndex == null) {
+                    throw new Error(`Member ${params.memberDID} not found in MLS group`);
+                }
+                await assertRemovalDemotes(handle, params.memberDID, tokens);
+                const { commitMessage, newGroup } = await removeMember(handle, leafIndex, tokens);
+                return {
+                    commit: commitMessage,
+                    bodies: tokens,
+                    kind: 'remove',
+                    journal: serializeCommitJournalBlob({
+                        serializedHandle: serializeMLSGroupState(newGroup),
+                        ...params.requestID != null ? {
+                            requestID: params.requestID
+                        } : {}
+                    }),
+                    onAccepted: async ()=>{
+                        // Read the departing row FIRST: the roster mirror inside the fold
+                        // rewrites the role from the post-commit roster, which no longer
+                        // names this member, and the tombstone then puts the row out of
+                        // reach. The announcement has to report the role they held while
+                        // they were still a member.
+                        const departing = await this.#readGroupMember(params.groupID, params.memberDID);
+                        await this.#registry.replaceHandle(params.groupID, newGroup);
+                        await this.#foldOwnCommittedEntries(params.groupID, newGroup, tokens);
+                        await this.#recordRemovedMember(params.groupID, params.memberDID, params.hlc, departing);
+                        await this.#settleCommittedRequest(params.requestID);
+                    }
+                };
+            });
+    }
+    /**
+   * Tombstone the member an accepted Remove commit evicted, and announce it.
+   *
+   * `departing` is passed in because both the roster mirror and the tombstone have
+   * erased the role the announcement must report.
+   *
+   * The tombstone carries the caller's HLC, shared with the demotion entry riding
+   * this same commit, so a fold drops exactly the ex-admin's entries signed at or
+   * after the eviction.
+   *
+   * The author never folds its own commit, so the announcement must come from
+   * here; every OTHER device announces the same removal from its fold.
+   */ async #recordRemovedMember(groupID, memberDID, hlc, departing) {
+        const stores = this.#stores;
+        if (stores == null) {
+            return;
+        }
+        const store = await getP2PStore(stores);
+        await store.removeGroupMember(groupID, memberDID, hlc);
+        // The committer never folds its own commit, so the discovery rows every
+        // other device drops in its fold have to be dropped here too.
+        await store.deletePeerAnnouncements({
+            groupID,
+            peerDIDs: [
+                memberDID
+            ]
+        });
+        const emitter = this.#emitter;
+        if (emitter == null || departing == null) {
+            return;
+        }
+        await emitter.emit('groupMemberLeft', {
+            groupID,
+            memberDID: departing.member_did,
+            role: departing.role,
+            createdAt: toISO(departing.created_at)
         });
+    }
+    /** The membership row as it stands, or `undefined` when nothing is wired. */ async #readGroupMember(groupID, memberDID) {
+        const stores = this.#stores;
+        if (stores == null) {
+            return undefined;
+        }
+        const store = await getP2PStore(stores);
+        return await store.getGroupMember(groupID, memberDID);
+    }
+    /**
+   * Record locally that this device has left, without touching MLS.
+   *
+   * Split from the teardown because the two want opposite timing. What the
+   * device says about ITSELF has to be true the moment `leaveGroup` returns — a
+   * screen that navigates away must not still be told it belongs to the group —
+   * while the departure announcement must reach co-members BEFORE the key it is
+   * encrypted under is deleted, and publishing cannot be awaited inside the
+   * caller's write transaction.
+   *
+   * The group row is kept and marked instead of deleted: its circles, circle
+   * members, peer announcements and hub bindings hang off it, and a device
+   * invited back would otherwise have to rebuild state it still holds.
+   */ async markGroupLeft(params) {
         const store = await getP2PStore(params.stores);
-        await store.removeGroupMember(params.groupID, params.memberDID, params.hlc);
-        return {
-            commitMessage
-        };
+        await store.removeGroupMember(params.groupID, params.identity.id, params.hlc);
+        await store.setGroupStatus(params.groupID, 'left');
+    }
+    /**
+   * Drop this device's MLS state for a group, and nothing else.
+   *
+   * The other half of {@link GroupManager.markGroupLeft}: it must run AFTER the
+   * departure announcement, because that announcement is encrypted under the key
+   * this deletes. Separate from the row writes so the caller can commit those
+   * with its own transaction and leave only this for afterwards — repeating the
+   * writes out here would have them block on a connection the caller still holds.
+   */ async tearDownGroupMLS(stores, groupID) {
+        const store = await getP2PStore(stores);
+        await store.deleteMLSState(groupID, this.#deviceID);
+        stores.onCommit(()=>this.#registry.invalidate(groupID));
     }
     async leaveGroup(params) {
         // MLS does not allow a member to commit their own removal.
         // leaveGroup performs local cleanup: deletes MLS state and group membership.
-        // The actual MLS group removal happens when another member calls removeGroupMember.
+        // The actual MLS group removal happens when an admin drives a Remove commit.
         const store = await getP2PStore(params.stores);
         await store.deleteMLSState(params.groupID, this.#deviceID);
-        await store.removeGroupMember(params.groupID, params.identity.id, params.hlc);
+        await this.markGroupLeft(params);
         // Defer cache eviction to onCommit so a future caller wrapping these
         // deletes in withTransaction does not invalidate the cache when the row
         // delete rolls back. KubunDB's non-tx onCommit fires synchronously, so