@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/context/group.js

@@ -1 +1,1646 @@
-import{createCapability as e,createRevocationRecord as t}from"@enkaku/capability";import{stringifyToken as r}from"@enkaku/token";import{HLC as i}from"@kubun/hlc";import{getGraphStore as a}from"@kubun/store-graph";import{getP2PStore as o}from"@kubun/store-p2p";import{GraphQLError as d}from"graphql";import{decodeFullJoinRequest as n,decodeInvitePayload as c,decodeJoinRequest as l,encodeInvitePayload as s}from"../groups/invite-payload.js";import{applyInviteGrants as m,applyInviteRevocations as u,finalizeJoinedGroup as p}from"../groups/join-utils.js";import{checkPeerAccess as g,toISO as w}from"./types.js";export function createGroupContext(D,I){let y=null,_=null,b=()=>y??=o(I.stores),h=()=>_??=a(I.stores);return{create:async e=>{let t=await I.groupManager.createGroup({stores:I.stores,identity:I.identity,name:e.name,description:e.description,createdBy:D.viewerDID,hubs:e.hubs?.map(e=>({url:e.url,serverDID:e.serverDID??void 0}))}),r=await b(),i=await r.getGroup(t.groupID);if(null==i)throw Error("Failed to create group");let a={id:i.id,name:i.name,description:i.description,createdBy:i.created_by,createdAt:w(i.created_at)};return await I.emitter.emit("groupJoined",a),a},list:async()=>{let e=await b();return(await e.listGroups()).map(e=>({id:e.id,name:e.name,description:e.description,createdBy:e.created_by,createdAt:w(e.created_at)}))},get:async e=>{let t=await b(),r=await t.getGroup(e);return null==r?null:{id:r.id,name:r.name,description:r.description,createdBy:r.created_by,createdAt:w(r.created_at)}},addMember:async(e,t,r)=>{let a=await b();await a.addGroupMember({group_id:e,member_did:t,role:r,hlc:i.serialize(I.hlc.now())});let o=await a.getGroupMember(e,t);if(null==o)throw Error("Failed to add group member");let d={groupID:o.group_id,memberDID:o.member_did,role:o.role,createdAt:w(o.created_at)};return await I.emitter.emit("groupMemberJoined",{...d,groupID:d.groupID}),d},listMembers:async e=>{let t=await b();return(await t.listGroupMembers(e)).map(e=>({groupID:e.group_id,memberDID:e.member_did,role:e.role,createdAt:w(e.created_at)}))},createCircle:async e=>{let t=await I.groupManager.createCircle({stores:I.stores,groupID:e.groupID,name:e.name,description:e.description}),r=await b(),i=await r.getCircle(t.circleID);if(null==i)throw Error("Failed to create circle");let a={id:i.id,groupID:i.group_id,name:i.name,description:i.description,createdAt:w(i.created_at)};return await I.emitter.emit("circleCreated",{...a,groupID:a.groupID}),I.stores.onCommit(()=>I.scheduleBroadcast(i.group_id,{type:"circle:create",circle:{id:i.id,groupID:i.group_id,name:i.name,description:i.description,catalogIDs:i.catalog_ids,hlc:i.hlc}})),a},listCircles:async e=>{let t=await b();return(await t.listCirclesByGroup(e)).map(e=>({id:e.id,groupID:e.group_id,name:e.name,description:e.description,createdAt:w(e.created_at)}))},addCircleMember:async(e,t,r)=>{let a=await b(),o=i.serialize(I.hlc.now());await a.addCircleMember({circle_id:e,member_did:t,role:r,hlc:o});let d=(await a.listCircleMembers(e)).find(e=>e.member_did===t);if(null==d)throw Error("Failed to add circle member");let n={circleID:d.circle_id,memberDID:d.member_did,role:d.role,createdAt:w(d.created_at)};await I.emitter.emit("circleMemberAdded",{...n,circleID:n.circleID});let c=await a.getCircle(e);if(null!=c)if("admin"===d.role||"member"===d.role){let e=d.role;I.stores.onCommit(()=>I.scheduleBroadcast(c.group_id,{type:"member:add",member:{circleID:d.circle_id,memberDID:d.member_did,role:e,hlc:d.hlc}}))}else I.logger.warn("addCircleMember: skipping broadcast for unrecognized role",{circleID:e,memberDID:t,role:d.role});return n},createCatalog:async e=>{let t=await h(),r=I.runtime.getRandomID(),a=i.serialize(I.hlc.now());await t.createCatalog({id:r,owner_did:D.viewerDID,name:e.name,description:e.description??"",filter_criteria:JSON.parse(e.filterCriteria),hlc:a});let o=await t.getCatalog(r);if(null==o)throw Error("Failed to create catalog");return{id:o.id,ownerDID:o.owner_did,name:o.name,description:o.description,filterCriteria:JSON.stringify(o.filter_criteria),createdAt:w(o.created_at)}},listCatalogs:async e=>{let t=await h();if(null!=e)return(await t.listCatalogs(e)).map(e=>({id:e.id,ownerDID:e.owner_did,name:e.name,description:e.description,filterCriteria:JSON.stringify(e.filter_criteria),createdAt:w(e.created_at)}));let r=await b(),i=new Set((await r.listGroups()).map(e=>e.created_by));return(await Promise.all(Array.from(i).map(e=>t.listCatalogs(e)))).flat().map(e=>({id:e.id,ownerDID:e.owner_did,name:e.name,description:e.description,filterCriteria:JSON.stringify(e.filter_criteria),createdAt:w(e.created_at)}))},invite:async(e,t,r,i)=>{g(D.viewerDID,I.identity.id,I.autoAcceptPeers);let a=await b(),o=I.identity,d=l(t),n=await I.groupManager.inviteToGroup({stores:I.stores,groupID:e,identity:o,recipientDID:d.did,recipientKeyPackage:d.publicPackage,permission:"member"}),c=await a.getGroup(e),m=(await a.listHubsByGroupID(e)).map(e=>null==e.server_did?{url:e.url}:{url:e.url,serverDID:e.server_did}),u=s({groupID:e,groupName:c?.name??"",suggestedHubs:m,invite:n.invite,welcomeMessage:n.welcomeMessage,ratchetTree:n.ratchetTree,...null!=r&&r.length>0?{grants:r}:{},...null!=i&&i.length>0?{revocations:i}:{}});return await I.emitter.emit("groupMemberJoined",{groupID:e,memberDID:d.did,role:"member",createdAt:new Date().toISOString()}),I.stores.onCommit(()=>I.scheduleSendCommit(e,n.commitMessage)),{invitePayload:u,groupID:e,groupName:c?.name??""}},join:async(e,t)=>{let r=I.identity,i=c(e),a=n(t),o={publicPackage:a.publicPackage,privatePackage:a.privatePackage,ownerDID:a.did};return await I.groupManager.joinGroup({stores:I.stores,identity:r,groupID:i.groupID,groupName:i.groupName,hubs:i.suggestedHubs,invite:i.invite,keyPackageBundle:o,welcomeMessage:i.welcomeMessage,ratchetTree:i.ratchetTree}),await m({stores:I.stores,selfDID:r.id,groupID:i.groupID,grants:i.grants,hlc:I.hlc,emitter:I.emitter,logger:I.logger}),await u({stores:I.stores,selfDID:r.id,groupID:i.groupID,revocations:i.revocations,hlc:I.hlc,emitter:I.emitter,logger:I.logger}),await p({stores:I.stores,emitter:I.emitter,invite:i})},leave:async e=>{let t=await b(),r=await t.getGroup(e),a=I.identity;try{await I.broadcastNow(e,{type:"group:leaveRequest",groupID:e,memberDID:a.id,hlc:i.serialize(I.hlc.now())})}catch(t){I.logger.warn("leave-request broadcast failed",{groupID:e,error:t})}return await I.groupManager.leaveGroup({stores:I.stores,groupID:e,identity:a}),null!=r&&await I.emitter.emit("groupLeft",{id:r.id,name:r.name,description:r.description,createdBy:r.created_by,createdAt:w(r.created_at),groupID:e}),{groupID:e}},removeMember:async(e,t)=>{let{commitMessage:r}=await I.groupManager.removeGroupMember({stores:I.stores,groupID:e,memberDID:t});return await I.emitter.emit("groupMemberLeft",{groupID:e,memberDID:t,role:"",createdAt:new Date().toISOString()}),I.stores.onCommit(()=>I.scheduleSendCommit(e,r)),{groupID:e}},update:async e=>{await I.groupManager.updateGroup({stores:I.stores,groupID:e.groupID,update:{name:e.name,description:e.description}});let t=await b(),r=await t.getGroup(e.groupID);if(null==r)throw Error(`Group ${e.groupID} not found`);let i={id:r.id,name:r.name,description:r.description,createdBy:r.created_by,createdAt:w(r.created_at)};return await I.emitter.emit("groupDataChanged",{...i,groupID:e.groupID}),I.stores.onCommit(()=>I.scheduleBroadcast(r.id,{type:"group:update",groupID:r.id,update:{name:e.name,description:e.description,hlc:r.hlc}})),i},updateCircle:async e=>{await I.groupManager.updateCircle({stores:I.stores,circleID:e.circleID,update:{name:e.name,description:e.description,catalogIDs:e.catalogIDs}});let t=await b(),r=await t.getCircle(e.circleID);if(null==r)throw Error(`Circle ${e.circleID} not found`);let i={id:r.id,groupID:r.group_id,name:r.name,description:r.description,createdAt:w(r.created_at)};return null!=e.catalogIDs?await I.emitter.emit("circleCatalogsChanged",{...i,circleID:e.circleID}):await I.emitter.emit("circleDataChanged",{...i,circleID:e.circleID}),I.stores.onCommit(()=>I.scheduleBroadcast(r.group_id,{type:"circle:update",circleID:r.id,update:{name:e.name,description:e.description,catalogIDs:e.catalogIDs,hlc:r.hlc}})),i},updateCatalog:async e=>{let t=await h(),r={hlc:i.serialize(I.hlc.now())};null!=e.name&&(r.name=e.name),null!=e.filterCriteria&&(r.filter_criteria=JSON.parse(e.filterCriteria)),await t.updateCatalog(e.catalogID,r);let a=await t.getCatalog(e.catalogID);if(null==a)throw Error(`Catalog ${e.catalogID} not found`);return{id:a.id,ownerDID:a.owner_did,name:a.name,description:a.description,filterCriteria:JSON.stringify(a.filter_criteria),createdAt:w(a.created_at)}},deleteCatalog:async e=>{let t=await h();return await t.deleteCatalog(e),{deletedID:e}},deleteCircle:async e=>{let t=await b(),r=await t.getCircle(e),{broadcast:i}=await I.groupManager.deleteCircle({stores:I.stores,circleID:e});return null!=r&&(await I.emitter.emit("circleDeleted",{id:r.id,groupID:r.group_id,name:r.name,description:r.description,createdAt:w(r.created_at)}),I.stores.onCommit(()=>I.scheduleBroadcast(r.group_id,i))),{deletedID:e}},removeCircleMember:async(e,t)=>{let r=await b(),[a,o]=await Promise.all([r.getCircle(e),r.getCircleMember(e,t)]);if(await I.groupManager.removeCircleMember({stores:I.stores,circleID:e,memberDID:t}),await I.emitter.emit("circleMemberRemoved",{circleID:e,memberDID:t,role:o?.role??"",createdAt:null!=o?w(o.created_at):new Date().toISOString()}),null!=a){let r=i.serialize(I.hlc.now());I.stores.onCommit(()=>I.scheduleBroadcast(a.group_id,{type:"member:remove",circleID:e,memberDID:t,hlc:r}))}return{circleID:e,memberDID:t}},grantWriteCapability:async({to:t,res:a,groupID:o,expiresIn:d})=>{let n=await b(),c=Math.floor(Date.now()/1e3),l=c+(d??2592e3),s=I.runtime.getRandomID(),m=r(await e(I.identity,{sub:I.identity.id,aud:t,act:"document/write",res:a,iat:c,exp:l,jti:s})),u=i.serialize(I.hlc.now());return await n.addDelegationToken({jti:s,grantor:I.identity.id,audience:t,token:m,resource:a,act:"document/write",exp:l,group_id:o,hlc:u})&&await I.emitter.emit("delegationTokenAdded",{jwt:m,jti:s,grantor:I.identity.id,audience:t,resource:a,exp:l}),I.stores.onCommit(()=>I.scheduleBroadcast(o,{type:"delegation:share",token:m,groupID:o,hlc:u})),m},revokeCapability:async({jti:e})=>{let a=await b(),o=await a.getDelegationTokenByJti(e);if(null==o)throw new d(`No capability found locally for jti ${e}`,{extensions:{code:"REVOCATION_CAP_UNKNOWN"}});if(o.grantor!==D.viewerDID)throw new d(`Only the capability issuer can revoke jti ${e}`,{extensions:{code:"REVOCATION_UNAUTHORIZED"}});let n=await t(I.identity,e),c=r(await I.identity.signToken(n)),l=i.serialize(I.hlc.now()),s=await a.addRevocation({jti:e,revoker_did:I.identity.id,revoked_iat:n.iat,revocation_token:c,verified_at:n.iat,cap_exp:o.exp,group_id:o.group_id,hlc:l});return s&&await I.emitter.emit("delegationTokenRevoked",{jti:e,grantor:o.grantor,audience:o.audience,revokerDID:I.identity.id,revokedAt:n.iat,verifiedAt:n.iat,capExp:o.exp,groupID:o.group_id}),I.stores.onCommit(()=>I.scheduleBroadcast(o.group_id,{type:"delegation:revoke",token:c,groupID:o.group_id,hlc:l})),s}}}
+import { createCapability, createRevocationRecord } from '@kokuin/capability';
+import { normalizeDID, stringifyToken } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { MAX_CAP_TTL_SECONDS, getDelegationStore as resolveDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore as resolveGraphStore } from '@kubun/store-graph';
+import { getP2PStore as resolveP2PStore } from '@kubun/store-p2p';
+import { adminCount, readGroupAnchor } from '@kumiai/mls';
+import { GraphQLError } from 'graphql';
+import { ADMIN_ROLE_ENTRY_TYPE } from '../groups/admin-roster.js';
+import { signCatalogSet } from '../groups/catalog-token.js';
+import { CIRCLE_DEF_ENTRY_TYPE, CIRCLE_MEMBER_ENTRY_TYPE, encodeCircleMemberSubject, GROUP_SETTINGS_ENTRY_TYPE } from '../groups/circle-reducers.js';
+import { awaitControlRequestSettled, settleControlRequest, toControlRequestData } from '../groups/control-request.js';
+import { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeInvitePayload } from '../groups/invite-payload.js';
+import { resolveJoinRequestDID } from '../groups/join-request-identity.js';
+import { applyInviteControlState, applyInviteGrants, applyInviteRevocations, collectInviteSeeds, finalizeJoinedGroup } from '../groups/join-utils.js';
+import { signLedgerEntry } from '../groups/ledger.js';
+import { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, requireGroupAdmin } from './require-admin.js';
+import { checkPeerAccess, toCircleData, toISO } from './types.js';
+/** Project a stored catalog row into the GraphQL `PeerCatalog` shape. */ function toCatalogData(row) {
+    return {
+        id: row.id,
+        ownerDID: row.owner_did,
+        name: row.name,
+        description: row.description,
+        filterCriteria: JSON.stringify(row.filter_criteria),
+        active: row.active === 1,
+        sourceGroupID: row.source_group_id,
+        sourceCircleID: row.source_circle_id,
+        createdAt: toISO(row.created_at)
+    };
+}
+/**
+ * Default write-grant lifetime in seconds (30 days).
+ *
+ * Sits exactly at `MAX_CAP_TTL_SECONDS`. Raising it above that ceiling mints
+ * silently — the mint guard below tests the `expiresIn` argument, not the
+ * effective lifetime, so a raised default never reaches it. Every receiver then
+ * drops the grant, which is a harder failure to trace than a throw.
+ */ const DEFAULT_GRANT_EXPIRES_IN = 2_592_000;
+/**
+ * How long an invite waits for its Add commit to land before refusing.
+ *
+ * Sized for the commit lane, not for a local write: the Add goes to the group's
+ * commit log and can be rebased by a concurrent commit before it is accepted, so
+ * the bound has to cover several attempts plus their round-trips. It is a
+ * refusal deadline, not a latency target — an invite that waits this long has
+ * hit a real fault, and the caller can retry.
+ */ const INVITE_COMMIT_TIMEOUT = 30_000;
+export function createGroupContext(ctx, deps) {
+    let p2pStorePromise = null;
+    let delegationStorePromise = null;
+    let graphStorePromise = null;
+    const getP2PStore = ()=>p2pStorePromise ??= resolveP2PStore(deps.stores);
+    const getDelegationStore = ()=>delegationStorePromise ??= resolveDelegationStore(deps.stores);
+    const getGraphStore = ()=>graphStorePromise ??= resolveGraphStore(deps.stores);
+    /**
+   * Mint the identity of a new circle.
+   *
+   * The ONE place a circle id comes from, so the source can be changed without
+   * hunting call sites: the id is handed to the caller before the commit
+   * carrying the definition lands, and every later step names the circle by it.
+   */ const mintCircleID = ()=>deps.runtime.getRandomID();
+    /**
+   * Mint an already-settled `no_op` request: the state the caller asked for is
+   * the state that already holds, so there is no entry to sign, no commit to
+   * drive and nothing to broadcast. The caller still gets a real, resolvable
+   * request — a terminal status IS the outcome, and "nothing to do" is an
+   * outcome an app must be able to read back.
+   *
+   * The enqueue and the settle share one transaction so a crash can never leave
+   * a request that reports `pending` for work that will never run.
+   */ const settleNoOpRequest = async (groupID)=>{
+        const requestID = deps.runtime.getRandomID();
+        const request = await deps.stores.withTransaction(async (tx)=>{
+            const txStore = await resolveP2PStore(tx);
+            const at = new Date().toISOString();
+            await txStore.enqueueControlRequest({
+                id: requestID,
+                groupID,
+                kind: 'ledger',
+                enqueuedAt: at
+            });
+            await txStore.settleControlRequest({
+                id: requestID,
+                outcome: 'no_op',
+                settledAt: at
+            });
+            const row = await txStore.getControlRequest(requestID);
+            if (row == null) {
+                throw new Error('Failed to read the control request after settling it');
+            }
+            return toControlRequestData(row);
+        });
+        // Announce only once the row is durable: a settle emitted from inside the
+        // transaction would tell subscribers about a row a rollback erases.
+        deps.stores.onCommit(()=>{
+            deps.emitter.emit('controlRequestSettled', request).catch((error)=>{
+                deps.logger.error('controlRequestSettled emit failed', {
+                    groupID,
+                    error
+                });
+            });
+        });
+        return request;
+    };
+    /**
+   * Report a commit lane's refusal, from inside the lane.
+   *
+   * Takes no store provider, on purpose. Every caller runs inside a
+   * `stores.onCommit` callback, and those fire AFTER the mutation's transaction
+   * has committed — under `mutateGraph` `deps.stores` IS that transaction, so a
+   * settle written through it waits on a transaction that is already over and
+   * never lands. Silently: `settleControlRequest` swallows everything, so the
+   * row stays `pending`, `controlRequestSettled` never fires, and every waiter
+   * times out instead of learning the outcome. `deps.deviceStores` exists for
+   * exactly this, and a helper that closes over it is what stops the next
+   * deferred settle reaching for the wrong provider.
+   */ const settleRejectedFromLane = (requestID, error)=>{
+        void settleControlRequest({
+            stores: deps.deviceStores,
+            requestID,
+            outcome: 'rejected',
+            error: error instanceof Error ? error.message : String(error),
+            emitter: deps.emitter,
+            logger: deps.logger
+        });
+    };
+    /**
+   * Queue the request that will report a signed entry's outcome, then drive the
+   * MLS commit that enacts it.
+   *
+   * Nothing is projected, broadcast or emitted here, and there is nowhere to write
+   * the entry: an entry enters the group's ledger by being ENACTED. This device
+   * then folds its own committed entry through the same `ingestVerifiedLedgerEntry`
+   * a receiver runs, from the same signed token.
+   */ const enqueueLedgerEntryRequest = async (params)=>{
+        const { groupID, token } = params;
+        const requestID = deps.runtime.getRandomID();
+        const enqueuedAt = new Date().toISOString();
+        await deps.stores.withTransaction(async (tx)=>{
+            const txStore = await resolveP2PStore(tx);
+            await txStore.enqueueControlRequest({
+                id: requestID,
+                groupID,
+                kind: 'ledger',
+                enqueuedAt
+            });
+        });
+        // The commit is the ONLY delivery: the token rides the commit's own frame as
+        // a sealed body, so every co-member resolves it, folds it and emits from
+        // that frame. A separate `ledger:entry` broadcast would race the commit and
+        // hand co-members an entry the group has not yet accepted, so none is sent.
+        //
+        // It is driven AFTER the request row is durable, and decoupled from this
+        // resolver's write transaction — the local MLS handle advances only when the
+        // hub accepts — so it is deferred to the outermost commit. Deferring is what
+        // guarantees the request exists to be settled by the time the lane can
+        // settle it.
+        const build = deps.groupManager.buildEnactLedgerCommit({
+            groupID,
+            tokens: [
+                token
+            ],
+            requestID
+        });
+        deps.stores.onCommit(()=>{
+            void deps.commitToGroup(groupID, build).catch((error)=>{
+                deps.logger.error('enact-ledger commit lane failed', {
+                    groupID,
+                    error
+                });
+                // A lane throw is the group refusing the entry or the deadline
+                // expiring — the request is over and the app must be told. The local
+                // admin gate is NOT this: it throws before anything is enqueued, so a
+                // refused caller has no row to settle.
+                settleRejectedFromLane(requestID, error);
+            });
+        });
+        // Built from the values just written rather than read back: this handler
+        // runs inside `mutateGraph`'s write transaction, so the enqueued row is not
+        // yet visible on any other connection.
+        return {
+            id: requestID,
+            groupID,
+            kind: 'ledger',
+            status: 'pending',
+            error: null,
+            enqueuedAt,
+            settledAt: null
+        };
+    };
+    return {
+        create: async (input)=>{
+            const result = await deps.groupManager.createGroup({
+                stores: deps.stores,
+                identity: deps.identity,
+                name: input.name,
+                description: input.description,
+                createdBy: ctx.viewerDID,
+                hubs: input.hubs?.map((h)=>({
+                        url: h.url,
+                        serverDID: h.serverDID ?? undefined
+                    }))
+            });
+            const store = await getP2PStore();
+            const row = await store.getGroup(result.groupID);
+            if (row == null) throw new Error('Failed to create group');
+            const groupData = {
+                id: row.id,
+                name: row.name,
+                description: row.description,
+                createdBy: row.created_by,
+                createdAt: toISO(row.created_at)
+            };
+            // Defer past the outermost commit: the `groupJoined` listener reads the P2P
+            // store on the main connection — inline deadlocks single-conn SQLite / reads
+            // uncommitted on Postgres, and a rollback then emits nothing.
+            deps.stores.onCommit(()=>{
+                deps.emitter.emit('groupJoined', groupData).catch((error)=>{
+                    deps.logger.error('groupJoined emit failed', {
+                        groupID: groupData.id,
+                        error
+                    });
+                });
+            });
+            return groupData;
+        },
+        list: async ()=>{
+            const store = await getP2PStore();
+            const rows = await store.listGroups();
+            return rows.map((row)=>({
+                    id: row.id,
+                    name: row.name,
+                    description: row.description,
+                    createdBy: row.created_by,
+                    createdAt: toISO(row.created_at)
+                }));
+        },
+        get: async (id)=>{
+            const store = await getP2PStore();
+            const row = await store.getGroup(id);
+            if (row == null) return null;
+            return {
+                id: row.id,
+                name: row.name,
+                description: row.description,
+                createdBy: row.created_by,
+                createdAt: toISO(row.created_at)
+            };
+        },
+        requireAdmin: async (groupID, action)=>{
+            const store = await getP2PStore();
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action
+            });
+        },
+        requireCircleAdmin: async (circleID, action)=>{
+            const store = await getP2PStore();
+            // Tombstoned circles count: deleting an already-deleted circle is a no-op
+            // the gate still has to run ahead of, and skipping them here would send
+            // that path back through a context-method gate whose extensions the
+            // rollback wrapper strips.
+            const circle = await store.getCircle(circleID, {
+                includeRemoved: true
+            });
+            if (circle == null) {
+                // A gate that returns for an unknown id passes every caller it cannot
+                // place in a group. Safe today only because each op re-reads the circle
+                // and refuses, so the gate would be the only thing between a stranger and
+                // an operation if one ever stopped.
+                throw new Error(`Failed to ${action}: circle not found`);
+            }
+            await requireGroupAdmin({
+                store,
+                groupID: circle.group_id,
+                did: deps.identity.id,
+                action
+            });
+        },
+        isAdmin: async (groupID, did)=>{
+            const store = await getP2PStore();
+            // The same call `requireGroupAdmin` makes, deliberately: one membership
+            // row is the single answer to "may this DID act as an admin", so what a
+            // read surface reports and what the gate enforces cannot drift apart.
+            return await store.isGroupAdmin(groupID, did);
+        },
+        requestSetMemberRole: async ({ groupID, memberDID, role })=>{
+            const store = await getP2PStore();
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot set member role: group has no genesis anchor');
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            const selfDID = deps.identity.id;
+            // Defense-in-depth + fail-loud UX. The fold on every peer is the ultimate
+            // authority — a non-admin's entry is dropped at fold time — but checking
+            // here lets the caller fail loudly instead of silently emitting a no-op.
+            // The GraphQL resolver runs this same gate before its rollback wrapper so
+            // the refusal keeps its code; repeating it here covers direct callers.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: selfDID,
+                action: 'set member roles'
+            });
+            if (role === 'admin') {
+                // Admin implies membership: a grant must target an existing member.
+                if (!await store.isGroupMemberAtHLC(groupID, memberDID, hlc)) {
+                    throw new Error('cannot grant admin to a non-member');
+                }
+            } else {
+                if (!await store.isGroupAdmin(groupID, memberDID)) {
+                    // Demoting a DID that is not currently an admin is a no-op; don't mint
+                    // a dead ledger entry + broadcast for it. The caller still gets a real,
+                    // resolvable request — one that is already settled, because the state
+                    // it asked for is the state that already holds. No lane runs, so
+                    // nothing here may touch the commit path.
+                    const existing = await store.getGroupMember(groupID, memberDID);
+                    if (existing == null) {
+                        throw new Error('cannot change role: not a group member');
+                    }
+                    return await settleNoOpRequest(groupID);
+                }
+                // Refuse the last admin's demotion where the caller can see it, the same
+                // guard `leave` and `requestRemoveMember` apply to their own paths. The
+                // group would refuse it anyway — the fold drops an entry that empties the
+                // admin set — but that refusal arrives asynchronously, on the lane, as a
+                // `rejected` settle the caller has to wait for, and a group with no admin
+                // can never grant, revoke or remove again, so this is fail-closed.
+                //
+                // The survivor set comes from the same projected rows the authority check
+                // above reads, exactly as `requestRemoveMember` counts its own: a grant
+                // reaches the ledger when it is signed but the projection only when its
+                // commit is enacted, so counting ledger admins would let the only admin
+                // who can still act be demoted in favour of one who cannot yet.
+                const members = await store.listGroupMembers(groupID);
+                const survivors = members.filter((member)=>member.role === 'admin' && normalizeDID(member.member_did) !== normalizeDID(memberDID));
+                if (survivors.length === 0) {
+                    throw new GraphQLError('cannot demote: this is the only admin — promote another member first', {
+                        extensions: {
+                            code: GROUP_CONTROL_DENIED,
+                            reason: LAST_GROUP_ADMIN,
+                            groupID
+                        }
+                    });
+                }
+            }
+            const value = role === 'admin' ? 'admin' : 'member';
+            const token = await signLedgerEntry(deps.identity, {
+                type: ADMIN_ROLE_ENTRY_TYPE,
+                subject: memberDID,
+                value,
+                groupID,
+                ord: hlc
+            });
+            // The `role` column and `groupMemberRoleChanged` are both written by the
+            // roster mirror when the commit lands, so what comes back is the PENDING
+            // request, not a member row.
+            const requestID = deps.runtime.getRandomID();
+            const enqueuedAt = new Date().toISOString();
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.enqueueControlRequest({
+                    id: requestID,
+                    groupID,
+                    kind: 'ledger',
+                    enqueuedAt
+                });
+            });
+            // The commit is the ONLY delivery of the role change: without it a newly
+            // promoted admin is an admin nowhere and every commit they author is refused.
+            // Driven AFTER the request row is durable and deferred to the outermost
+            // commit, because the local MLS handle advances only when the hub accepts. A
+            // missing commit hub is logged on the lane's promise, not fatal.
+            const build = deps.groupManager.buildEnactLedgerCommit({
+                groupID,
+                tokens: [
+                    token
+                ],
+                requestID
+            });
+            deps.stores.onCommit(()=>{
+                void deps.commitToGroup(groupID, build).catch((error)=>{
+                    deps.logger.error('enact-ledger commit lane failed', {
+                        groupID,
+                        error
+                    });
+                    // A lane throw is the group refusing the entry or the deadline
+                    // expiring — the request is over and the app must be told. The local
+                    // admin gate is NOT this: it throws above, before anything is
+                    // enqueued, so a refused caller has no row to settle.
+                    settleRejectedFromLane(requestID, error);
+                });
+            });
+            // Built from the values just written rather than read back: this handler
+            // runs inside `mutateGraph`'s write transaction, so the enqueued row is
+            // not yet visible on any other connection.
+            return {
+                id: requestID,
+                groupID,
+                kind: 'ledger',
+                status: 'pending',
+                error: null,
+                enqueuedAt,
+                settledAt: null
+            };
+        },
+        listMembers: async (groupID)=>{
+            const store = await getP2PStore();
+            const rows = await store.listGroupMembers(groupID);
+            return rows.map((row)=>({
+                    groupID: row.group_id,
+                    memberDID: row.member_did,
+                    role: row.role,
+                    createdAt: toISO(row.created_at)
+                }));
+        },
+        requestCreateCircle: async (input)=>{
+            const groupID = input.groupID;
+            const store = await getP2PStore();
+            // Defense-in-depth + fail-loud UX. The fold on every peer is the ultimate
+            // authority — a non-admin's entry is dropped at fold time — but checking
+            // here lets the caller fail loudly instead of receiving a request that
+            // settles `committed` for a circle no peer ever projects.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'create a circle'
+            });
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot create circle: group has no genesis anchor');
+            }
+            // The caller is handed the id back before the commit lands, because every
+            // step that follows a create — membership, catalogs, the invite seeds —
+            // names the circle by id. An internal caller may supply a DERIVED id so
+            // its own retry converges on this circle; see `CreateCircleInput`.
+            const circleID = input.circleID ?? mintCircleID();
+            const hlc = HLC.serialize(deps.hlc.now());
+            const value = {
+                name: input.name,
+                description: input.description ?? '',
+                catalogIDs: []
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_DEF_ENTRY_TYPE,
+                subject: circleID,
+                value,
+                groupID,
+                ord: hlc
+            });
+            // No no-op branch: the subject is freshly minted, so there is no prior
+            // state for the requested one to already equal.
+            const request = await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+            return {
+                request,
+                circleID
+            };
+        },
+        listCircles: async (groupID)=>{
+            const store = await getP2PStore();
+            const rows = await store.listCirclesByGroup(groupID);
+            return rows.map(toCircleData);
+        },
+        requestAddCircleMember: async ({ circleID, memberDID, role })=>{
+            const store = await getP2PStore();
+            const circleRow = await store.getCircle(circleID);
+            if (circleRow == null) throw new Error('Failed to add circle member: circle not found');
+            const groupID = circleRow.group_id;
+            // Defense-in-depth + fail-loud UX, as in the other circle producers: an
+            // ungated non-admin's entry would ride a commit the group accepts, so the
+            // request would settle `committed` while every peer's fold drops it.
+            //
+            // It runs BEFORE the no-op check: answering a non-admin `no_op` would both
+            // grant them an outcome they have no authority to ask for and leak whether
+            // the membership they named already held.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'add a circle member'
+            });
+            // No-op when the DID is already an active member at exactly this role: the
+            // entry would fold to the state that already holds. A tombstoned row is NOT
+            // a no-op — re-adding it is a revival, and only a fresh entry performs one.
+            const existingMember = await store.getCircleMember(circleID, memberDID);
+            if (existingMember != null && existingMember.removed_at_hlc == null && existingMember.role === role) {
+                return await settleNoOpRequest(groupID);
+            }
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot add circle member: group has no genesis anchor');
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            const subject = encodeCircleMemberSubject(circleID, memberDID);
+            const value = {
+                role
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_MEMBER_ENTRY_TYPE,
+                subject,
+                value,
+                groupID,
+                ord: hlc
+            });
+            return await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+        },
+        createCatalog: async (p)=>{
+            const graphStore = await getGraphStore();
+            const id = p.catalogID ?? deps.runtime.getRandomID();
+            const hlcStr = HLC.serialize(deps.hlc.now());
+            const filterCriteria = JSON.parse(p.filterCriteria);
+            // Sign a self-contained `catalog:set` token at creation so the catalog can
+            // be forwarded (invite seed / broadcast) with creator-bound provenance a
+            // receiver re-verifies. The signed record carries every authoritative field.
+            const signedToken = await signCatalogSet(deps.identity, {
+                id,
+                ownerDID: ctx.viewerDID,
+                name: p.name,
+                description: p.description ?? '',
+                filterCriteria,
+                hlc: hlcStr
+            });
+            await graphStore.createCatalog({
+                id,
+                owner_did: ctx.viewerDID,
+                name: p.name,
+                description: p.description ?? '',
+                filter_criteria: filterCriteria,
+                hlc: hlcStr,
+                signed_token: signedToken
+            });
+            const row = await graphStore.getCatalog(id);
+            if (row == null) throw new Error('Failed to create catalog');
+            return toCatalogData(row);
+        },
+        listStoredCatalogs: async (filter)=>{
+            const graphStore = await getGraphStore();
+            const rows = await graphStore.listStoredCatalogs(filter);
+            return rows.map(toCatalogData);
+        },
+        listControlRequests: async (groupID)=>{
+            const store = await getP2PStore();
+            const rows = await store.getControlRequests(groupID);
+            return rows.map(toControlRequestData);
+        },
+        getControlRequest: async (id)=>{
+            const store = await getP2PStore();
+            const row = await store.getControlRequest(id);
+            return row == null ? null : toControlRequestData(row);
+        },
+        ackControlRequest: async (id)=>{
+            const store = await getP2PStore();
+            await store.ackControlRequest(id);
+        },
+        awaitSettle: async (id, timeoutMs)=>await awaitControlRequestSettled({
+                stores: deps.stores,
+                emitter: deps.emitter,
+                requestID: id,
+                timeoutMs
+            }),
+        activateCatalogSync: async (catalogID)=>{
+            const graphStore = await getGraphStore();
+            if (await graphStore.getCatalog(catalogID) == null) {
+                throw new Error(`Catalog ${catalogID} not found`);
+            }
+            await graphStore.setCatalogActive(catalogID, true);
+            const row = await graphStore.getCatalog(catalogID);
+            if (row == null) throw new Error(`Catalog ${catalogID} not found`);
+            return toCatalogData(row);
+        },
+        deactivateCatalogSync: async (catalogID)=>{
+            const graphStore = await getGraphStore();
+            if (await graphStore.getCatalog(catalogID) == null) {
+                throw new Error(`Catalog ${catalogID} not found`);
+            }
+            await graphStore.setCatalogActive(catalogID, false);
+            const row = await graphStore.getCatalog(catalogID);
+            if (row == null) throw new Error(`Catalog ${catalogID} not found`);
+            return toCatalogData(row);
+        },
+        requestInvite: async (input)=>{
+            const { groupID, joinRequest, grants, revocations } = input;
+            checkPeerAccess(ctx.viewerDID, deps.identity.id, deps.autoAcceptPeers);
+            const store = await getP2PStore();
+            // Inviting adds a member to the MLS group — an admin action. kumiai already
+            // gates the committer at BUILD time (`createInvite` throws "the inviter must
+            // be an admin in the group roster"), so without this gate a non-admin's
+            // invite still fails — but only after enqueuing a request and reaching the
+            // lane, which then settles `rejected` on the build throw. This gate makes it
+            // fail fast and clean (`NOT_GROUP_ADMIN` before any row is written), and it
+            // is the local half of the defense-in-depth the receive side completes: the
+            // one path kumiai's build gate cannot catch is an inviter admin at build who
+            // is demoted before co-members fold the commit, which the receive policy
+            // refuses (`CommitRejectedError`, group-mls.ts).
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'invite a member to the group'
+            });
+            const ownIdentity = deps.identity;
+            const joinReq = decodeJoinRequest(joinRequest);
+            // The recipient comes from the KeyPackage's own credential, never from the
+            // request's `did` field. The two halves go to different subsystems — the
+            // KeyPackage becomes an MLS leaf, this DID becomes a membership row and a
+            // role entry — so a forged pairing names one identity in the ratchet and
+            // another in the projections, and nothing downstream reconciles them: a
+            // co-member folds the row from the roster diff while the inviter writes
+            // the one it was handed. Resolving here makes every caller safe rather
+            // than each having to remember.
+            const recipientDID = resolveJoinRequestDID(joinRequest);
+            const groupRow = await store.getGroup(groupID);
+            if (groupRow == null) throw new Error('Failed to invite member: group not found');
+            const groupName = groupRow.name;
+            const boundHubs = await store.listHubsByGroupID(groupID);
+            const suggestedHubs = boundHubs.map((hub)=>hub.server_did == null ? {
+                    url: hub.url
+                } : {
+                    url: hub.url,
+                    serverDID: hub.server_did
+                });
+            // Seed the joiner with the group's control state so it is current the
+            // instant it joins — the ledger (circles/members/admin roster), the
+            // inviter's own model access-defaults, and the group's catalogs — without
+            // waiting for a broadcast or a catch-up round-trip.
+            //
+            // Collected ONCE, here, rather than per attempt inside the encoder: they
+            // are the caller's snapshot of the group's control state, and nothing in
+            // them turns on which attempt the group accepts. Re-collecting per rebase
+            // would only make the payload vary between attempts for no gain.
+            const seeds = await collectInviteSeeds({
+                stores: deps.stores,
+                identity: ownIdentity,
+                ownerDID: ctx.viewerDID,
+                groupID,
+                logger: deps.logger
+            });
+            const requestID = deps.runtime.getRandomID();
+            const enqueuedAt = new Date().toISOString();
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.enqueueControlRequest({
+                    id: requestID,
+                    groupID,
+                    kind: 'invite',
+                    enqueuedAt
+                });
+            });
+            const build = deps.groupManager.buildInviteCommit({
+                groupID,
+                identity: ownIdentity,
+                recipientDID,
+                recipientKeyPackage: joinReq.publicPackage,
+                permission: 'member',
+                requestID,
+                encodeInvitePayload: async (material)=>encodeInvitePayload({
+                        groupID,
+                        groupName,
+                        suggestedHubs,
+                        invite: material.invite,
+                        welcomeMessage: material.welcomeMessage,
+                        ratchetTree: material.ratchetTree,
+                        ...grants != null && grants.length > 0 ? {
+                            grants
+                        } : {},
+                        ...revocations != null && revocations.length > 0 ? {
+                            revocations
+                        } : {},
+                        ...seeds.accessDefaults.length > 0 ? {
+                            accessDefaults: seeds.accessDefaults
+                        } : {},
+                        ...seeds.catalogs.length > 0 ? {
+                            catalogs: seeds.catalogs
+                        } : {}
+                    })
+            });
+            deps.stores.onCommit(()=>{
+                void deps.commitToGroup(groupID, build).catch((error)=>{
+                    deps.logger.error('invite commit lane failed', {
+                        groupID,
+                        error
+                    });
+                    settleRejectedFromLane(requestID, error);
+                });
+            });
+            let settled;
+            try {
+                settled = await awaitControlRequestSettled({
+                    stores: deps.stores,
+                    emitter: deps.emitter,
+                    requestID,
+                    timeoutMs: deps.inviteCommitTimeoutMs ?? INVITE_COMMIT_TIMEOUT
+                });
+            } catch (waitError) {
+                // The wait elapsed without a settle. A PARKED Add commit (the inviter's
+                // hub is offline) leaves the request `pending` and the commit still in
+                // flight — it may yet land and add the member — so this is NOT a failure
+                // to report. Read the authoritative row: only a still-`pending` request
+                // returns the truthful pending shape below; anything else fell through
+                // the wait's own settle/timeout race and is handled by the status branch.
+                const parkedRow = await store.getControlRequest(requestID);
+                if (parkedRow == null) {
+                    throw waitError;
+                }
+                settled = toControlRequestData(parkedRow);
+            }
+            if (settled.status === 'pending') {
+                // Truthful pending result — NOT a throw: the caller learns the invite has
+                // not landed yet rather than being told it failed. `request` carries that
+                // status back. No payload rides a pending result: the commit that would
+                // produce it has not been accepted, so there is nothing to hand over yet.
+                return {
+                    request: settled,
+                    invitePayload: null,
+                    groupID,
+                    groupName
+                };
+            }
+            if (settled.status !== 'committed') {
+                // A definitively-failed invite (`rejected`/`lost`/`no_op`) SHOULD report
+                // failure — a settled-negative is a real error, not a pending outcome.
+                throw new Error(`group/invite: the add commit did not land (${settled.status}${settled.error == null ? '' : ` — ${settled.error}`})`);
+            }
+            // Read the payload from the settled row rather than from the callback that
+            // fired alongside it: this is the one route both the live path and a
+            // replayed adopt write to, so a caller answered after a restart is
+            // answered identically.
+            const invitePayload = await store.getControlRequestResult(requestID);
+            if (invitePayload == null) {
+                throw new Error('group/invite: the add commit landed without an invite payload');
+            }
+            return {
+                request: settled,
+                invitePayload,
+                groupID,
+                groupName
+            };
+        },
+        join: async (invitePayloadStr, joinRequestPayloadStr)=>{
+            const ownIdentity = deps.identity;
+            const invite = decodeInvitePayload(invitePayloadStr);
+            // Decode the full join request to get the key package bundle (including private keys)
+            const fullJoinReq = decodeFullJoinRequest(joinRequestPayloadStr);
+            const keyPackageBundle = {
+                publicPackage: fullJoinReq.publicPackage,
+                privatePackage: fullJoinReq.privatePackage,
+                ownerDID: fullJoinReq.did
+            };
+            await deps.groupManager.joinGroup({
+                stores: deps.stores,
+                identity: ownIdentity,
+                groupID: invite.groupID,
+                groupName: invite.groupName,
+                hubs: invite.suggestedHubs,
+                invite: invite.invite,
+                keyPackageBundle,
+                welcomeMessage: invite.welcomeMessage,
+                ratchetTree: invite.ratchetTree
+            });
+            await applyInviteGrants({
+                stores: deps.stores,
+                selfDID: ownIdentity.id,
+                groupID: invite.groupID,
+                grants: invite.grants,
+                hlc: deps.hlc,
+                emitter: deps.emitter,
+                logger: deps.logger
+            });
+            await applyInviteRevocations({
+                stores: deps.stores,
+                selfDID: ownIdentity.id,
+                groupID: invite.groupID,
+                revocations: invite.revocations,
+                hlc: deps.hlc,
+                emitter: deps.emitter,
+                logger: deps.logger
+            });
+            // Fold the invite-carried control state (ledger, access-defaults,
+            // catalogs) now the MLS handle exists, so the genesis anchor is readable
+            // and the joiner projects circles/members at join. Reads the anchor
+            // through the engine transaction's stores so the registry shares its
+            // connection (a separate connection deadlocks single-connection SQLite).
+            await applyInviteControlState({
+                stores: deps.stores,
+                groupID: invite.groupID,
+                accessDefaults: invite.accessDefaults,
+                catalogs: invite.catalogs,
+                hlc: deps.hlc,
+                getGroupAnchor: (gid)=>deps.registry.readHandle(gid, (handle)=>readGroupAnchor(handle), {
+                        stores: deps.stores
+                    }),
+                getGroupLedger: (gid)=>deps.registry.readHandle(gid, (handle)=>handle.ledger, {
+                        stores: deps.stores
+                    }),
+                logger: deps.logger
+            });
+            return await finalizeJoinedGroup({
+                stores: deps.stores,
+                emitter: deps.emitter,
+                invite,
+                logger: deps.logger
+            });
+        },
+        leave: async (groupID)=>{
+            // One HLC orders BOTH the MLS self-removal tombstone and the admin-role
+            // self-revocation enacted below. Sharing a single stamp is what lets a
+            // receiver's deterministic fold keep this leaver's control entries signed
+            // at or before departure and drop everything they sign strictly later.
+            const hlc = HLC.serialize(deps.hlc.now());
+            const store = await getP2PStore();
+            const groupRow = await store.getGroup(groupID);
+            const ownIdentity = deps.identity;
+            // Anchor and roster in one lock: both come from the live handle, which
+            // `leaveGroup` tears down. Under `mutateGraph` this handler already runs
+            // inside the engine transaction, so the registry's restore/persist must
+            // share its connection (a separate connection blocks on the outer write
+            // lock under SQLite).
+            const { anchor, roster } = await deps.registry.readHandle(groupID, async (handle)=>({
+                    anchor: readGroupAnchor(handle),
+                    roster: handle.roster
+                }), {
+                stores: deps.stores
+            });
+            // Authority is read from the HANDLE's roster, not the membership row's
+            // `role`, because the demotion below has to be one the group will enact:
+            // `commitLedgerEntries` judges the roster its own ledger folds to and
+            // refuses an entry that would empty the admin set. Reading the mirrored
+            // column instead lets this producer mint an entry the commit then refuses,
+            // and a lane failure is logged rather than returned — so the caller would
+            // watch a leave succeed and nothing happen.
+            const selfIsAdmin = anchor != null && roster.roles.get(normalizeDID(ownIdentity.id)) === 'admin';
+            // Revoke the leaver's own control authority as it goes. Only admins fold
+            // authoritatively, so only an admin needs revoking — a non-admin leave
+            // enacts no ledger entry and drives no commit.
+            let revokeToken = null;
+            // A group the leaver is alone in has nobody to revoke to and no state to
+            // converge: leaving it is deleting it. Nothing is enacted, so a solo owner
+            // is never trapped in their own group by the guard below.
+            // From the ROSTER, like the authority above it and for the same reason: a
+            // projection that lags reports a group this device is alone in, which skips
+            // the last-admin guard entirely and lets the only admin walk out of a group
+            // that still has members.
+            const hasCoMembers = [
+                ...roster.roles.keys()
+            ].some((did)=>normalizeDID(did) !== normalizeDID(ownIdentity.id));
+            if (selfIsAdmin && anchor != null && hasCoMembers) {
+                // Refuse the last admin's departure where the caller can see it. The
+                // group would refuse it anyway — one admin means this demotion empties
+                // the admin set — but that refusal arrives on the lane, asynchronously,
+                // as a log line. The app's move is to promote a successor first.
+                if (adminCount(roster) <= 1) {
+                    throw new GraphQLError('cannot leave: you are the only admin — promote another member first', {
+                        extensions: {
+                            code: GROUP_CONTROL_DENIED,
+                            reason: LAST_GROUP_ADMIN,
+                            groupID
+                        }
+                    });
+                }
+                revokeToken = await signLedgerEntry(deps.identity, {
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: ownIdentity.id,
+                    value: 'member',
+                    groupID,
+                    ord: hlc
+                });
+            }
+            const leftData = groupRow != null ? {
+                id: groupRow.id,
+                name: groupRow.name,
+                description: groupRow.description,
+                createdBy: groupRow.created_by,
+                createdAt: toISO(groupRow.created_at),
+                groupID
+            } : null;
+            // Announce the departure, then tear the MLS state down. The order is
+            // load-bearing: the announcement is encrypted to the group, and teardown
+            // deletes the key it encrypts under. Advisory and best-effort — a failed
+            // notify must not block the leave itself.
+            const announceAndTearDown = async ()=>{
+                try {
+                    await deps.broadcastNow(groupID, {
+                        type: 'group:leaveRequest',
+                        groupID,
+                        memberDID: ownIdentity.id,
+                        hlc
+                    });
+                } catch (error) {
+                    deps.logger.warn('leave-request broadcast failed', {
+                        groupID,
+                        error
+                    });
+                }
+                // `deviceStores`, never `stores`: this runs after the commit lane has
+                // resolved, so under `mutateGraph` the request's transaction is long
+                // over and a write through it would never land — silently, since
+                // nothing throws and the lane's `catch` sees no error. The departed
+                // admin would keep its MLS state, and so the group's key.
+                await deps.groupManager.leaveGroup({
+                    stores: deps.deviceStores,
+                    groupID,
+                    identity: ownIdentity,
+                    hlc
+                });
+            };
+            // The same order with the local rows already written: announce first, then
+            // drop the key that the announcement was encrypted under.
+            const announceThenDropKey = async ()=>{
+                try {
+                    await deps.broadcastNow(groupID, {
+                        type: 'group:leaveRequest',
+                        groupID,
+                        memberDID: ownIdentity.id,
+                        hlc
+                    });
+                } catch (error) {
+                    deps.logger.warn('leave-request broadcast failed', {
+                        groupID,
+                        error
+                    });
+                }
+                await deps.groupManager.tearDownGroupMLS(deps.deviceStores, groupID);
+            };
+            const emitGroupLeft = ()=>{
+                if (leftData == null) return;
+                deps.emitter.emit('groupLeft', leftData).catch((error)=>{
+                    deps.logger.error('groupLeft emit failed', {
+                        groupID,
+                        error
+                    });
+                });
+            };
+            if (revokeToken == null) {
+                // Nothing to enact, so nothing to confirm — but still nothing that may
+                // be AWAITED here. The announcement publishes on the group's lane, which
+                // encrypts under the live handle, and this handler runs inside the
+                // engine's write transaction: the lane's own reads take a second
+                // connection and block on the outer write lock, so awaiting it hangs the
+                // mutation for good on a hub-bound group. Deferred to the outermost
+                // commit for exactly the reason the self-revoke path below is.
+                //
+                // The LOCAL record of the departure is written here rather than out
+                // there, because it must be true the moment this returns: a screen that
+                // navigates away on success would otherwise still be told this device
+                // belongs to the group it just left.
+                await deps.groupManager.markGroupLeft({
+                    stores: deps.stores,
+                    groupID,
+                    identity: ownIdentity,
+                    hlc
+                });
+                deps.stores.onCommit(()=>{
+                    // A tick past the commit hook, not just past the transaction: KubunDB
+                    // fires a non-transactional `onCommit` SYNCHRONOUSLY, so a store write
+                    // made from inside it still lands while the outer write is finalizing
+                    // and blocks on the connection it is holding.
+                    setTimeout(()=>{
+                        void announceThenDropKey().then(emitGroupLeft).catch((error)=>{
+                            deps.logger.error('leave teardown failed', {
+                                groupID,
+                                error
+                            });
+                        });
+                    }, 0);
+                });
+                return {
+                    groupID
+                };
+            }
+            // The commit is the ONLY delivery of the self-demotion, and the leave waits
+            // on it. A revocation that reached co-members by an ephemeral broadcast
+            // alone was held by whoever happened to be listening and by no one else,
+            // and it never entered the group's authenticated ledger at all — so a peer
+            // that rebuilt from that ledger folded the departed admin back to admin.
+            //
+            // Local state therefore moves only once the group has taken the demotion:
+            // teardown runs on the lane's success, and the entry lands in this device's
+            // own store through the same fold every co-member runs. A lane that never
+            // lands leaves the leaver in the group, still an admin — the state the
+            // group agrees on — rather than a member of nothing who is an admin
+            // everywhere.
+            const requestID = deps.runtime.getRandomID();
+            const enqueuedAt = new Date().toISOString();
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.enqueueControlRequest({
+                    id: requestID,
+                    groupID,
+                    kind: 'ledger',
+                    enqueuedAt
+                });
+            });
+            const build = deps.groupManager.buildEnactLedgerCommit({
+                groupID,
+                tokens: [
+                    revokeToken
+                ],
+                requestID
+            });
+            // Deferred to the outermost commit for the reason every other lane is:
+            // awaiting it inside this write transaction deadlocks the single
+            // connection the lane's own reads need.
+            deps.stores.onCommit(()=>{
+                void deps.commitToGroup(groupID, build).then(async ()=>{
+                    await announceAndTearDown();
+                    // Already past the outermost commit here, so the emit needs no
+                    // further deferral: the listener's reads run on their own connection.
+                    emitGroupLeft();
+                }).catch((error)=>{
+                    deps.logger.error('leave self-revoke commit lane failed', {
+                        groupID,
+                        error
+                    });
+                    settleRejectedFromLane(requestID, error);
+                });
+            });
+            return {
+                groupID
+            };
+        },
+        requestRemoveMember: async (input)=>{
+            const { groupID, memberDID } = input;
+            // One HLC orders BOTH the MLS-roster tombstone the accepted commit writes
+            // and the admin-role revocation signed below to ride it. Sharing a single
+            // stamp is what makes the revocation drop exactly the ex-admin's control
+            // entries signed after the removal: the deterministic fold keeps entries
+            // at or before this HLC and drops everything signed strictly later.
+            const hlc = HLC.serialize(deps.hlc.now());
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot remove member: group has no genesis anchor');
+            }
+            const store = await getP2PStore();
+            const selfDID = deps.identity.id;
+            // Only a current admin may remove a member. This gate runs before anything
+            // is signed or enqueued, so a non-admin attempt leaves no request behind;
+            // the schema-layer `failTransactionFatal` wrap turns the throw into a
+            // full-transaction rollback and forwards the message to the caller. The
+            // resolver runs the same gate ahead of that wrap so the refusal keeps its
+            // code; repeating it here covers direct callers.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: selfDID,
+                action: 'remove a member'
+            });
+            // Resolve whether the removed DID is an admin from the roster as it stands
+            // NOW: this is the only point at which they are still a member, and the
+            // answer decides whether the commit must carry a demotion at all.
+            const removedIsAdmin = await store.isGroupAdmin(groupID, memberDID);
+            // Refuse to remove the last admin: check what survives once the removed DID
+            // is dropped. A group with no admins can never grant, revoke, or remove
+            // again, so this is fail-closed.
+            //
+            // The survivor set is read from the same projected rows the authority check
+            // reads, never from the ledger. A grant reaches the ledger the moment it is
+            // signed but reaches the projection only when its commit is enacted, so the
+            // ledger holds admins who cannot yet act. Counting those as survivors would
+            // permit removing the only admin who can — and if the pending grant's commit
+            // never lands, the group is left with no effective admin at all.
+            if (removedIsAdmin) {
+                const members = await store.listGroupMembers(groupID);
+                const removedDID = normalizeDID(memberDID);
+                const survivors = members.filter((member)=>member.role === 'admin' && normalizeDID(member.member_did) !== removedDID);
+                if (survivors.length === 0) {
+                    // The same refusal `leave` and `requestSetMemberRole` raise, carrying
+                    // the same pair: one rule, three paths, and an app matching on the
+                    // code has to reach it from all three.
+                    throw new GraphQLError('cannot remove the last admin — promote another member first', {
+                        extensions: {
+                            code: GROUP_CONTROL_DENIED,
+                            reason: LAST_GROUP_ADMIN,
+                            groupID
+                        }
+                    });
+                }
+            }
+            // Revoke the ex-admin's control authority on the commit that evicts them.
+            // Only admins fold authoritatively, so only an admin needs revoking — a
+            // non-admin removal carries no ledger entry at all.
+            //
+            // Minted BEFORE the removal so it can ride that very commit: a receiver
+            // refuses a Remove whose target is still an admin in the roster the commit's
+            // entries fold to, so an admin can only be evicted by a commit that also
+            // demotes them.
+            //
+            // The token is NOT appended here. On the lane the accepted commit's
+            // `onAccepted` is its writer, and only that path knows the group took this
+            // attempt: a row written here would survive a lane that never lands,
+            // demoting the target in THIS device's admin-roster fold while every
+            // co-member still folds them as an admin.
+            let revokeToken = null;
+            if (removedIsAdmin) {
+                revokeToken = await signLedgerEntry(deps.identity, {
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: memberDID,
+                    value: 'member',
+                    groupID,
+                    ord: hlc
+                });
+            }
+            // The request is enqueued before the lane is armed so a crash can never
+            // leave a commit driving toward a request that does not exist.
+            const requestID = deps.runtime.getRandomID();
+            const enqueuedAt = new Date().toISOString();
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.enqueueControlRequest({
+                    id: requestID,
+                    groupID,
+                    kind: 'remove',
+                    enqueuedAt
+                });
+            });
+            // The commit is the ONLY delivery of the demotion: the token rides the
+            // commit's own frame as a sealed body, so every co-member resolves it,
+            // folds it and emits from that frame. A separate `ledger:entry` broadcast
+            // would race the commit and hand co-members a demotion the group has not
+            // yet accepted, so none is sent.
+            //
+            // The tombstone and the announcement move with it: they happen in the
+            // lane's `onAccepted`, so nothing here observes a removal the group never
+            // took. Driving is deferred to the outermost commit — awaiting the lane
+            // from inside this write transaction would deadlock the single connection
+            // the lane's own reads need.
+            const build = deps.groupManager.buildRemoveCommit({
+                groupID,
+                memberDID,
+                hlc,
+                requestID,
+                ...revokeToken != null ? {
+                    ledgerEntries: [
+                        revokeToken
+                    ]
+                } : {}
+            });
+            deps.stores.onCommit(()=>{
+                void deps.commitToGroup(groupID, build).catch((error)=>{
+                    deps.logger.error('remove-member commit lane failed', {
+                        groupID,
+                        error
+                    });
+                    // A lane throw is the group refusing the removal or the deadline
+                    // expiring — the request is over and the app must be told. The local
+                    // admin gate is NOT this: it throws above, before anything is
+                    // enqueued, so a refused caller has no row to settle.
+                    settleRejectedFromLane(requestID, error);
+                });
+            });
+            // Built from the values just written rather than read back: this handler
+            // runs inside `mutateGraph`'s write transaction, so the enqueued row is
+            // not yet visible on any other connection.
+            return {
+                id: requestID,
+                groupID,
+                kind: 'remove',
+                status: 'pending',
+                error: null,
+                enqueuedAt,
+                settledAt: null
+            };
+        },
+        requestUpdate: async (input)=>{
+            const groupID = input.groupID;
+            const store = await getP2PStore();
+            // Defense-in-depth + fail-loud UX. The fold on every peer is the ultimate
+            // authority — a non-admin's entry is dropped at fold time — but checking
+            // here lets the caller fail loudly instead of receiving a request that
+            // settles `committed` for a change the fold silently discarded.
+            //
+            // It runs BEFORE the no-op check: answering a non-admin `no_op` would
+            // both grant them an outcome they have no authority to ask for and leak
+            // whether the state they named already held.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'update a group'
+            });
+            // `group.settings` folds per field: carry ONLY the fields the caller set.
+            // An explicit empty string (or empty list) clears the field; an omitted
+            // field is left out of the value entirely so the prior value survives.
+            const value = {};
+            if (input.name !== undefined) value.name = input.name;
+            if (input.description !== undefined) value.description = input.description;
+            if (input.openCircleIDs !== undefined) value.openCircleIDs = input.openCircleIDs;
+            // The commit-hub designation carries only its hub identity (URL + optional
+            // server DID), never a local hub-row id: it is the shared identity every
+            // device folds and matches against its own bound hubs. An absent server DID
+            // is left off entirely rather than carried as null.
+            if (input.commitHub !== undefined) {
+                value.commitHub = input.commitHub.serverDID != null ? {
+                    url: input.commitHub.url,
+                    serverDID: input.commitHub.serverDID
+                } : {
+                    url: input.commitHub.url
+                };
+            }
+            // No-op when the caller set no field: every `UpdateGroupInput` field but
+            // `groupID` is optional, so an input carrying only `groupID` asks for
+            // nothing. Minting an empty-value `group.settings` entry would drive a
+            // commit that folds to the state that already holds.
+            if (Object.keys(value).length === 0) {
+                return await settleNoOpRequest(groupID);
+            }
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot update group: group has no genesis anchor');
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            const token = await signLedgerEntry(deps.identity, {
+                type: GROUP_SETTINGS_ENTRY_TYPE,
+                subject: groupID,
+                value,
+                groupID,
+                ord: hlc
+            });
+            return await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+        },
+        requestUpdateCircle: async (input)=>{
+            const store = await getP2PStore();
+            const existing = await store.getCircle(input.circleID);
+            if (existing == null) throw new Error(`Circle ${input.circleID} not found`);
+            const groupID = existing.group_id;
+            // Defense-in-depth + fail-loud UX, and it runs BEFORE the no-op check so a
+            // caller with no authority is refused rather than told `no_op`, which would
+            // leak whether the definition they named already held.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'update a circle'
+            });
+            // No-op when the caller set no field: every `UpdateCircleInput` field but
+            // `circleID` is optional, so an input carrying only `circleID` asks for
+            // nothing, and the merge below would re-mint the definition that already
+            // holds. Naming a field whose value is unchanged is NOT this case — it
+            // still mints an entry, and the fold that lands it decides from the value
+            // diff whether anything moved.
+            if (input.name === undefined && input.description === undefined && input.catalogIDs === undefined) {
+                return await settleNoOpRequest(groupID);
+            }
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot update circle: group has no genesis anchor');
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            // `circle.def` is whole-value LWW: the winning entry replaces the projected
+            // definition outright. Merge the partial patch over the existing definition
+            // so a name-only update preserves the prior description and catalogIDs.
+            const value = {
+                name: input.name ?? existing.name,
+                description: input.description ?? existing.description,
+                catalogIDs: input.catalogIDs ?? existing.catalog_ids
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_DEF_ENTRY_TYPE,
+                subject: input.circleID,
+                value,
+                groupID,
+                ord: hlc
+            });
+            // Which event this becomes is NOT decided here. The fold that lands the
+            // entry compares the projected catalog list before and after and emits
+            // `circleCatalogsChanged` only when it actually moved. That is the only
+            // predicate every peer can evaluate — a remote peer never sees this input —
+            // so naming `catalogIDs` with the list the circle already carries emits
+            // `circleDataChanged`, not `circleCatalogsChanged`.
+            return await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+        },
+        updateCatalog: async (p)=>{
+            const graphStore = await getGraphStore();
+            // A catalog is owned by its creator (its `owner_did`, bound and signed at
+            // creation). A device holds foreign-owned catalogs from invite seeds and
+            // discovery, so key alone is not authority to change one — verify ownership
+            // before touching the row.
+            const owned = await graphStore.getCatalog(p.catalogID);
+            if (owned == null) throw new Error(`Catalog ${p.catalogID} not found`);
+            if (owned.owner_did !== ctx.viewerDID) {
+                throw new Error(`Catalog ${p.catalogID} is not owned by this device`);
+            }
+            const hlcStr = HLC.serialize(deps.hlc.now());
+            const name = p.name ?? owned.name;
+            const filterCriteria = p.filterCriteria != null ? JSON.parse(p.filterCriteria) : owned.filter_criteria;
+            // Re-sign the whole record, exactly as creation does. The stored token is
+            // forwarded VERBATIM in an invite seed and matched field-by-field against
+            // the plaintext row it travels with, so a token left describing the record
+            // before this edit does not merely go stale — it makes the catalog
+            // unshareable, silently, on the receiving side. `hlc` alone moving is
+            // enough to break that match, so every update re-signs, not only one that
+            // changes the criteria.
+            const signedToken = await signCatalogSet(deps.identity, {
+                id: p.catalogID,
+                ownerDID: ctx.viewerDID,
+                name,
+                description: owned.description,
+                filterCriteria,
+                hlc: hlcStr
+            });
+            await graphStore.updateCatalog(p.catalogID, {
+                name,
+                description: owned.description,
+                filter_criteria: filterCriteria,
+                hlc: hlcStr,
+                signed_token: signedToken
+            });
+            const row = await graphStore.getCatalog(p.catalogID);
+            if (row == null) throw new Error(`Catalog ${p.catalogID} not found`);
+            return toCatalogData(row);
+        },
+        deleteCatalog: async (catalogID)=>{
+            const graphStore = await getGraphStore();
+            // Owner-scoped, as `updateCatalog`: a device holding a foreign-owned catalog
+            // is not authorized to delete it — verify ownership before the row goes.
+            const owned = await graphStore.getCatalog(catalogID);
+            if (owned == null) throw new Error(`Catalog ${catalogID} not found`);
+            if (owned.owner_did !== ctx.viewerDID) {
+                throw new Error(`Catalog ${catalogID} is not owned by this device`);
+            }
+            await graphStore.deleteCatalog(catalogID);
+            return {
+                deletedID: catalogID
+            };
+        },
+        requestDeleteCircle: async ({ circleID })=>{
+            const store = await getP2PStore();
+            const existing = await store.getCircle(circleID, {
+                includeRemoved: true
+            });
+            if (existing == null) throw new Error(`Circle ${circleID} not found`);
+            const groupID = existing.group_id;
+            // Defense-in-depth + fail-loud UX. The fold on every peer is the ultimate
+            // authority — a non-admin's entry is dropped at fold time — but checking
+            // here lets the caller fail loudly instead of receiving a request that
+            // settles `committed` for a change the fold silently discarded.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'delete a circle'
+            });
+            // No-op when the circle is already tombstoned: minting a dead `removed`
+            // entry would only churn the ledger and converge to the same projected
+            // state. The gate runs first, so a non-admin is refused either way.
+            if (existing.removed_at_hlc != null) {
+                return await settleNoOpRequest(groupID);
+            }
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot delete circle: group has no genesis anchor');
+            }
+            // One HLC stamps the durable tombstone entry, the broadcast token and the
+            // commit body, so the HLC every co-member folds and the one this device
+            // folds back off its own commit are identical.
+            const hlc = HLC.serialize(deps.hlc.now());
+            const value = {
+                removed: true
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_DEF_ENTRY_TYPE,
+                subject: circleID,
+                value,
+                groupID,
+                ord: hlc
+            });
+            return await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+        },
+        requestRemoveCircleMember: async ({ circleID, memberDID })=>{
+            const store = await getP2PStore();
+            const circleRow = await store.getCircle(circleID);
+            if (circleRow == null) throw new Error('Failed to remove circle member: circle not found');
+            const groupID = circleRow.group_id;
+            // Defense-in-depth + fail-loud UX, as in `requestDeleteCircle`: without it
+            // a non-admin's entry rides a commit the hub accepts, so the request would
+            // settle `committed` while every peer's fold drops the entry.
+            await requireGroupAdmin({
+                store,
+                groupID,
+                did: deps.identity.id,
+                action: 'remove a circle member'
+            });
+            const existing = await store.getCircleMember(circleID, memberDID);
+            // No-op when the target is not an active member: a never-added DID
+            // (absent row) or an already-tombstoned one.
+            if (existing == null || existing.removed_at_hlc != null) {
+                return await settleNoOpRequest(groupID);
+            }
+            // Read the anchor through the engine transaction's stores: under
+            // `mutateGraph` this handler already runs inside that transaction, so the
+            // registry's restore/persist must share its connection — a separate
+            // connection blocks forever on the outer write lock (single-connection SQLite).
+            const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            if (anchor == null) {
+                throw new Error('cannot remove circle member: group has no genesis anchor');
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            const subject = encodeCircleMemberSubject(circleID, memberDID);
+            const value = {
+                removed: true
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_MEMBER_ENTRY_TYPE,
+                subject,
+                value,
+                groupID,
+                ord: hlc
+            });
+            return await enqueueLedgerEntryRequest({
+                groupID,
+                token
+            });
+        },
+        grantWriteCapability: async ({ to, res, groupID, expiresIn })=>{
+            // Refused rather than clamped: silently shortening a capability the caller
+            // asked for produces a grant that stops working on a date it was never
+            // told about.
+            if (expiresIn != null && expiresIn > MAX_CAP_TTL_SECONDS) {
+                throw new GraphQLError(`expiresIn ${expiresIn} exceeds the maximum capability lifetime of ${MAX_CAP_TTL_SECONDS} seconds`, {
+                    extensions: {
+                        code: 'GRANT_TTL_TOO_LONG'
+                    }
+                });
+            }
+            const [store, delegationStore] = await Promise.all([
+                getP2PStore(),
+                getDelegationStore()
+            ]);
+            const iat = Math.floor(Date.now() / 1000);
+            const exp = iat + (expiresIn ?? DEFAULT_GRANT_EXPIRES_IN);
+            const jti = deps.runtime.getRandomID();
+            const cap = await createCapability(deps.identity, {
+                sub: deps.identity.id,
+                aud: to,
+                act: 'document/write',
+                res,
+                iat,
+                exp,
+                jti
+            });
+            const token = stringifyToken(cap);
+            const hlc = HLC.serialize(deps.hlc.now());
+            const changed = await delegationStore.addDelegationToken({
+                jti,
+                grantor: deps.identity.id,
+                audience: to,
+                token,
+                resource: res,
+                act: 'document/write',
+                exp,
+                hlc
+            });
+            // Record the group this grant belongs to on the p2p edge, keyed by `jti`,
+            // so the p2p layer can resolve the cap's group for revoke-broadcast
+            // targeting and listing enrichment.
+            await store.addGroupDelegation({
+                group_id: groupID,
+                jti
+            });
+            // Surface the just-issued held row to local subscribers of
+            // `ownDelegationTokenAdded`. Case B clients (delegate devices belonging
+            // to the same identity as the grantor) listen on this emitter and
+            // receive the event for tokens addressed to them; the grantor's own
+            // subscriptions also see the issued row.
+            //
+            // The freshly-minted token always carries a new random `jti` and a new
+            // hlc, so `changed` is true in practice — the gate matches the
+            // broadcast-path producer for consistency.
+            if (changed) {
+                await deps.emitter.emit('delegationTokenAdded', {
+                    jwt: token,
+                    jti,
+                    grantor: deps.identity.id,
+                    audience: to,
+                    resource: res,
+                    exp
+                });
+            }
+            // Distribute the grant to group co-members over the same control channel
+            // circle/member ops use. The recipient stores it iff its audience matches,
+            // so its engine can auto-attach the token on later writes. Same hlc as the
+            // grantor-side issued row keeps LWW consistent across devices.
+            deps.stores.onCommit(()=>deps.scheduleBroadcast(groupID, {
+                    type: 'delegation:share',
+                    token,
+                    groupID,
+                    hlc
+                }));
+            return token;
+        },
+        revokeCapability: async ({ jti })=>{
+            const [store, delegationStore] = await Promise.all([
+                getP2PStore(),
+                getDelegationStore()
+            ]);
+            // Scoped to the viewer: a co-member can mint a capability reusing a `jti`
+            // it saw broadcast, so an unscoped read can hand back someone else's row
+            // and deny the issuer its own revocation.
+            const cap = await delegationStore.getDelegationTokenByGrantorJTI({
+                jti,
+                grantor: ctx.viewerDID
+            });
+            if (cap == null) {
+                // Both branches deny, but callers act on them differently: rows under
+                // this `jti` from other grantors mean the viewer is not the issuer,
+                // while none at all means the capability is unknown here — the
+                // multi-device-grantor case (the issuing device is not the one running
+                // this resolver) is not yet supported.
+                const others = await delegationStore.listDelegationTokensByJTI(jti);
+                if (others.length > 0) {
+                    throw new GraphQLError(`Only the capability issuer can revoke jti ${jti}`, {
+                        extensions: {
+                            code: 'REVOCATION_UNAUTHORIZED'
+                        }
+                    });
+                }
+                throw new GraphQLError(`No capability found locally for jti ${jti}`, {
+                    extensions: {
+                        code: 'REVOCATION_CAP_UNKNOWN'
+                    }
+                });
+            }
+            // Resolve the group the cap was granted in from the p2p edge; it targets
+            // the revoke broadcast and enriches the emitted event. A missing edge
+            // means the group is unknown locally — the broadcast then cannot be
+            // scoped, so treat it like the missing-cap case.
+            const groupID = await store.getGroupIDByJTI(jti);
+            if (groupID == null) {
+                throw new GraphQLError(`No group known locally for capability jti ${jti}`, {
+                    extensions: {
+                        code: 'REVOCATION_CAP_UNKNOWN'
+                    }
+                });
+            }
+            // `createRevocationRecord` signs the claims itself, so the record is
+            // already the signed token the store persists and the broadcast carries.
+            const record = await createRevocationRecord(deps.identity, jti);
+            const revokedAt = record.payload.iat;
+            const token = stringifyToken(record);
+            const hlc = HLC.serialize(deps.hlc.now());
+            // Self-issued revocations are verified by construction (the revoker is
+            // the cap's issuer, checked above); seed `verified_at` with the
+            // record's iat so the revocation gate fires immediately without a
+            // separate verification round-trip.
+            const changed = await delegationStore.addRevocation({
+                jti,
+                revoker_did: deps.identity.id,
+                revoked_iat: revokedAt,
+                revocation_token: token,
+                verified_at: revokedAt,
+                cap_exp: cap.exp,
+                hlc
+            });
+            // Surface the verified revocation to local subscribers of
+            // `ownDelegationTokenRevoked`. A self-mint is verified-by-construction
+            // (authority check above), so the emit gate is simply `changed` — the
+            // same idempotence semantic that suppresses duplicate broadcast-path
+            // events on LWW no-ops.
+            if (changed) {
+                await deps.emitter.emit('delegationTokenRevoked', {
+                    jti,
+                    grantor: cap.grantor,
+                    audience: cap.audience,
+                    revokerDID: deps.identity.id,
+                    revokedAt: revokedAt,
+                    verifiedAt: revokedAt,
+                    capExp: cap.exp,
+                    groupID
+                });
+            }
+            // Distribute the revocation to group co-members over the same control
+            // channel that carries delegation:share. Same hlc as the local row keeps
+            // LWW consistent across devices.
+            deps.stores.onCommit(()=>deps.scheduleBroadcast(groupID, {
+                    type: 'delegation:revoke',
+                    token,
+                    groupID,
+                    hlc
+                }));
+            return changed;
+        }
+    };
+}