@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/context/group.js

@@ -1 +1,1319 @@
-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 l,decodeInvitePayload as c,decodeJoinRequest as n,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,h=()=>y??=o(I.stores),b=()=>_??=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 h(),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 h();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 h(),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 h();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 h();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 h(),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 h();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 h(),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 l={circleID:d.circle_id,memberDID:d.member_did,role:d.role,createdAt:w(d.created_at)};await I.emitter.emit("circleMemberAdded",{...l,circleID:l.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 l},createCatalog:async e=>{let t=await b(),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 b();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 h(),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 h(),o=I.identity,d=n(t),l=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:l.invite,welcomeMessage:l.welcomeMessage,ratchetTree:l.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,l.commitMessage)),{invitePayload:u,groupID:e,groupName:c?.name??""}},join:async(e,t)=>{let r=I.identity,i=c(e),a=l(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 h(),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 h(),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 h(),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 b(),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 b();return await t.deleteCatalog(e),{deletedID:e}},deleteCircle:async e=>{let t=await h(),r=await t.getCircle(e);if(await I.groupManager.deleteCircle({stores:I.stores,circleID:e}),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)});let t=i.serialize(I.hlc.now());I.stores.onCommit(()=>I.scheduleBroadcast(r.group_id,{type:"circle:delete",circleID:e,hlc:t}))}return{deletedID:e}},removeCircleMember:async(e,t)=>{let r=await h(),[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 l=await h(),c=Math.floor(Date.now()/1e3),n=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:n,jti:s})),u=i.serialize(I.hlc.now());return await l.addDelegationToken({jti:s,grantor:I.identity.id,audience:t,token:m,resource:a,act:"document/write",exp:n,group_id:o,hlc:u})&&await I.emitter.emit("delegationTokenAdded",{jwt:m,jti:s,grantor:I.identity.id,audience:t,resource:a,exp:n}),I.stores.onCommit(()=>I.scheduleBroadcast(o,{type:"delegation:share",token:m,groupID:o,hlc:u})),m},revokeCapability:async({jti:e})=>{let a=await h(),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 l=await t(I.identity,e),c=r(await I.identity.signToken(l)),n=i.serialize(I.hlc.now()),s=await a.addRevocation({jti:e,revoker_did:I.identity.id,revoked_iat:l.iat,revocation_token:c,verified_at:l.iat,cap_exp:o.exp,group_id:o.group_id,hlc:n});return s&&await I.emitter.emit("delegationTokenRevoked",{jti:e,grantor:o.grantor,audience:o.audience,revokerDID:I.identity.id,revokedAt:l.iat,verifiedAt:l.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:n})),s}}}
+import { createCapability, createRevocationRecord } from '@kokuin/capability';
+import { normalizeDID, stringifyToken } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { getDelegationStore as resolveDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore as resolveGraphStore } from '@kubun/store-graph';
+import { getP2PStore as resolveP2PStore } from '@kubun/store-p2p';
+import { GraphQLError } from 'graphql';
+import { ADMIN_ROLE_ENTRY_TYPE, foldAdminRoster, isLedgerAdminAtHLC, loadVerifiedAdminEntries, reprojectAdminRoster } from '../groups/admin-roster.js';
+import { reprojectCircleDefs, reprojectCircleMembers, reprojectGroupSettings } from '../groups/circle-projection.js';
+import { CIRCLE_DEF_ENTRY_TYPE, CIRCLE_MEMBER_ENTRY_TYPE, encodeCircleMemberSubject, GROUP_SETTINGS_ENTRY_TYPE } from '../groups/circle-reducers.js';
+import { readGroupAnchor } from '../groups/group-anchor.js';
+import { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeInvitePayload } from '../groups/invite-payload.js';
+import { applyInviteGrants, applyInviteRevocations, finalizeJoinedGroup } from '../groups/join-utils.js';
+import { ledgerEntryDigest, signLedgerEntry } from '../groups/ledger-entry.js';
+import { checkPeerAccess, toISO } from './types.js';
+/** Default write-grant lifetime in seconds (30 days). */ const DEFAULT_GRANT_EXPIRES_IN = 2_592_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);
+    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)
+            };
+        },
+        addMember: async (groupID, memberDID, role)=>{
+            const store = await getP2PStore();
+            await store.addGroupMember({
+                group_id: groupID,
+                member_did: memberDID,
+                role,
+                hlc: HLC.serialize(deps.hlc.now())
+            });
+            const row = await store.getGroupMember(groupID, memberDID);
+            if (row == null) throw new Error('Failed to add group member');
+            const memberData = {
+                groupID: row.group_id,
+                memberDID: row.member_did,
+                role: row.role,
+                createdAt: toISO(row.created_at)
+            };
+            await deps.emitter.emit('groupMemberJoined', {
+                ...memberData,
+                groupID: memberData.groupID
+            });
+            return memberData;
+        },
+        setMemberRole: 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.
+            if (!await isLedgerAdminAtHLC({
+                store,
+                groupID,
+                anchor,
+                did: selfDID,
+                atHLC: hlc,
+                logger: deps.logger
+            })) {
+                throw new Error('not authorized: only a group admin can 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 isLedgerAdminAtHLC({
+                store,
+                groupID,
+                anchor,
+                did: memberDID,
+                atHLC: hlc,
+                logger: deps.logger
+            })) {
+                // Demoting a DID that is not currently an admin is a no-op; don't mint a
+                // dead ledger entry + broadcast for it.
+                const existing = await store.getGroupMember(groupID, memberDID);
+                if (existing == null) {
+                    throw new Error('cannot change role: not a group member');
+                }
+                return {
+                    groupID: existing.group_id,
+                    memberDID: existing.member_did,
+                    role: existing.role,
+                    createdAt: toISO(existing.created_at)
+                };
+            }
+            const value = role === 'admin' ? 'admin' : 'revoked';
+            const token = await signLedgerEntry(deps.identity, {
+                type: ADMIN_ROLE_ENTRY_TYPE,
+                subject: memberDID,
+                value,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            // Append the durable entry and reproject the admin overlay atomically, so a
+            // crash can never leave the durable ledger and the projected `role` column
+            // diverged. Reads inside the transaction use the transaction-bound store.
+            // `appendLedgerEntry` normalizes `issuer_did`, so the raw self DID is passed.
+            const memberData = await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: memberDID,
+                    value,
+                    hlc,
+                    issuer_did: selfDID,
+                    signed_token: token
+                });
+                await reprojectAdminRoster({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getGroupMember(groupID, memberDID);
+                if (row == null) throw new Error('Failed to read group member after role change');
+                return {
+                    groupID: row.group_id,
+                    memberDID: row.member_did,
+                    role: row.role,
+                    createdAt: toISO(row.created_at)
+                };
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same entry
+            // against their own anchor) and the local emit to the OUTERMOST commit. Under
+            // `mutateGraph` this handler runs inside the engine's write transaction, so
+            // the inner `withTransaction` above nests inline and does NOT commit on its
+            // own — the outer transaction commits later. Registering via `onCommit` keeps
+            // a rolled-back role change from ever being broadcast or observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('groupMemberRoleChanged', {
+                    ...memberData,
+                    groupID: memberData.groupID
+                });
+            });
+            return memberData;
+        },
+        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)
+                }));
+        },
+        createCircle: async (p)=>{
+            const groupID = p.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 create circle: group has no genesis anchor');
+            }
+            const circleID = deps.runtime.getRandomID();
+            const hlc = HLC.serialize(deps.hlc.now());
+            const value = {
+                name: p.name,
+                description: p.description ?? '',
+                catalogIDs: []
+            };
+            const token = await signLedgerEntry(deps.identity, {
+                type: CIRCLE_DEF_ENTRY_TYPE,
+                subject: circleID,
+                value,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            // Append the signed entry and reproject the circle-definition overlay
+            // atomically so a crash can never leave the durable ledger and the
+            // projected row diverged. `appendLedgerEntry` normalizes `issuer_did`, so
+            // the raw self DID is passed.
+            const circleData = await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: CIRCLE_DEF_ENTRY_TYPE,
+                    subject: circleID,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectCircleDefs({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getCircle(circleID);
+                if (row == null) throw new Error('Failed to read circle after create');
+                return {
+                    id: row.id,
+                    groupID: row.group_id,
+                    name: row.name,
+                    description: row.description,
+                    createdAt: toISO(row.created_at)
+                };
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same entry
+            // against their own anchor) and the local emit to the OUTERMOST commit. Under
+            // `mutateGraph` this handler runs inside the engine's write transaction, so
+            // the inner `withTransaction` above nests inline and does NOT commit on its
+            // own — the outer transaction commits later. Registering via `onCommit` keeps
+            // a rolled-back creation from ever being broadcast or observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('circleCreated', {
+                    ...circleData,
+                    groupID: circleData.groupID
+                });
+            });
+            return circleData;
+        },
+        listCircles: async (groupID)=>{
+            const store = await getP2PStore();
+            const rows = await store.listCirclesByGroup(groupID);
+            return rows.map((row)=>({
+                    id: row.id,
+                    groupID: row.group_id,
+                    name: row.name,
+                    description: row.description,
+                    createdAt: toISO(row.created_at)
+                }));
+        },
+        addCircleMember: 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;
+            // 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,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            // Append the signed entry and reproject the circle-member overlay
+            // atomically so a crash can never leave the durable ledger and the
+            // projected row diverged. `appendLedgerEntry` normalizes `issuer_did`, so
+            // the raw self DID is passed.
+            const circleMemberData = await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: CIRCLE_MEMBER_ENTRY_TYPE,
+                    subject,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectCircleMembers({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getCircleMember(circleID, memberDID);
+                if (row == null) throw new Error('Failed to read circle member after add');
+                return {
+                    circleID: row.circle_id,
+                    memberDID: row.member_did,
+                    role: row.role,
+                    createdAt: toISO(row.created_at)
+                };
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same entry
+            // against their own anchor) and the local emit to the OUTERMOST commit. Under
+            // `mutateGraph` this handler runs inside the engine's write transaction, so
+            // the inner `withTransaction` above nests inline and does NOT commit on its
+            // own — the outer transaction commits later. Registering via `onCommit` keeps
+            // a rolled-back addition from ever being broadcast or observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('circleMemberAdded', {
+                    ...circleMemberData,
+                    circleID: circleMemberData.circleID
+                });
+            });
+            return circleMemberData;
+        },
+        createCatalog: async (p)=>{
+            const graphStore = await getGraphStore();
+            const id = deps.runtime.getRandomID();
+            const hlcStr = HLC.serialize(deps.hlc.now());
+            await graphStore.createCatalog({
+                id,
+                owner_did: ctx.viewerDID,
+                name: p.name,
+                description: p.description ?? '',
+                filter_criteria: JSON.parse(p.filterCriteria),
+                hlc: hlcStr
+            });
+            const row = await graphStore.getCatalog(id);
+            if (row == null) throw new Error('Failed to create catalog');
+            return {
+                id: row.id,
+                ownerDID: row.owner_did,
+                name: row.name,
+                description: row.description,
+                filterCriteria: JSON.stringify(row.filter_criteria),
+                createdAt: toISO(row.created_at)
+            };
+        },
+        listCatalogs: async (ownerDID)=>{
+            const graphStore = await getGraphStore();
+            if (ownerDID != null) {
+                const rows = await graphStore.listCatalogs(ownerDID);
+                return rows.map((row)=>({
+                        id: row.id,
+                        ownerDID: row.owner_did,
+                        name: row.name,
+                        description: row.description,
+                        filterCriteria: JSON.stringify(row.filter_criteria),
+                        createdAt: toISO(row.created_at)
+                    }));
+            }
+            // listCatalogs requires ownerDID -- for unfiltered, list groups then catalogs
+            const store = await getP2PStore();
+            const groups = await store.listGroups();
+            const ownerDIDs = new Set(groups.map((s)=>s.created_by));
+            const allCatalogs = await Promise.all(Array.from(ownerDIDs).map((did)=>graphStore.listCatalogs(did)));
+            return allCatalogs.flat().map((row)=>({
+                    id: row.id,
+                    ownerDID: row.owner_did,
+                    name: row.name,
+                    description: row.description,
+                    filterCriteria: JSON.stringify(row.filter_criteria),
+                    createdAt: toISO(row.created_at)
+                }));
+        },
+        invite: async (groupID, joinRequest, grants, revocations)=>{
+            checkPeerAccess(ctx.viewerDID, deps.identity.id, deps.autoAcceptPeers);
+            const store = await getP2PStore();
+            const ownIdentity = deps.identity;
+            const joinReq = decodeJoinRequest(joinRequest);
+            const result = await deps.groupManager.inviteToGroup({
+                stores: deps.stores,
+                groupID,
+                identity: ownIdentity,
+                recipientDID: joinReq.did,
+                recipientKeyPackage: joinReq.publicPackage,
+                permission: 'member'
+            });
+            // Look up group name for the invite payload
+            const groupRow = await store.getGroup(groupID);
+            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
+                });
+            const encoded = encodeInvitePayload({
+                groupID,
+                groupName: groupRow?.name ?? '',
+                suggestedHubs,
+                invite: result.invite,
+                welcomeMessage: result.welcomeMessage,
+                ratchetTree: result.ratchetTree,
+                ...grants != null && grants.length > 0 ? {
+                    grants
+                } : {},
+                ...revocations != null && revocations.length > 0 ? {
+                    revocations
+                } : {}
+            });
+            await deps.emitter.emit('groupMemberJoined', {
+                groupID,
+                memberDID: joinReq.did,
+                role: 'member',
+                createdAt: new Date().toISOString()
+            });
+            // Fan out the add-commit to existing members so their MLS ratchet +
+            // local roster learn about the new member (RFC 9750 §6.1). The joiner
+            // itself receives the Welcome out-of-band via the invite payload above.
+            deps.stores.onCommit(()=>deps.scheduleSendCommit(groupID, result.commitMessage));
+            return {
+                invitePayload: encoded,
+                groupID,
+                groupName: groupRow?.name ?? ''
+            };
+        },
+        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
+            });
+            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 appended 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;
+            // Read the anchor while the MLS handle is still live — `leaveGroup` tears
+            // it 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 = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+                stores: deps.stores
+            });
+            // Resolve self-admin BEFORE the self-tombstone: once the tombstone writes
+            // `removed_at_hlc == hlc`, membership-at-HLC (which requires
+            // `removed_at_hlc > hlc`) would read false and wrongly report the leaver
+            // as a non-admin, suppressing the revocation.
+            const selfIsAdmin = anchor != null && await isLedgerAdminAtHLC({
+                store,
+                groupID,
+                anchor,
+                did: ownIdentity.id,
+                atHLC: hlc,
+                logger: deps.logger
+            });
+            // Revoke the leaver's own control authority atomically with the tombstone.
+            // Only admins fold authoritatively, so only an admin needs revoking — a
+            // non-admin leave appends nothing and broadcasts no ledger entry.
+            let revokeToken = null;
+            if (selfIsAdmin && anchor != null) {
+                const value = 'revoked';
+                const token = await signLedgerEntry(deps.identity, {
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: ownIdentity.id,
+                    value,
+                    hlc
+                });
+                const entryID = ledgerEntryDigest(token);
+                // `appendLedgerEntry` normalizes `issuer_did`, so the raw self DID is passed.
+                await store.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: ownIdentity.id,
+                    value,
+                    hlc,
+                    issuer_did: ownIdentity.id,
+                    signed_token: token
+                });
+                await reprojectAdminRoster({
+                    store,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                revokeToken = token;
+            }
+            // Both broadcasts go out BEFORE MLS teardown — once `leaveGroup` deletes
+            // the local MLS handle we can no longer encrypt to the group. They are
+            // awaited (not deferred to `onCommit`) so the encrypt happens against the
+            // still-live handle; deferring would fail with the handle gone. A pre-commit
+            // send that a later rollback orphans is benign here: it is an authentic
+            // self-signed revoke converging early, monotonic toward less privilege for
+            // a DID that itself invoked leave — symmetric to the leaveRequest below.
+            // Best-effort: a failed notify must not block the leave itself.
+            try {
+                await deps.broadcastNow(groupID, {
+                    type: 'group:leaveRequest',
+                    groupID,
+                    memberDID: ownIdentity.id,
+                    hlc
+                });
+            } catch (error) {
+                deps.logger.warn('leave-request broadcast failed', {
+                    groupID,
+                    error
+                });
+            }
+            if (revokeToken != null) {
+                try {
+                    await deps.broadcastNow(groupID, {
+                        type: 'ledger:entry',
+                        groupID,
+                        token: revokeToken
+                    });
+                } catch (error) {
+                    deps.logger.warn('self-revoke broadcast failed', {
+                        groupID,
+                        error
+                    });
+                }
+            }
+            await deps.groupManager.leaveGroup({
+                stores: deps.stores,
+                groupID,
+                identity: ownIdentity,
+                hlc
+            });
+            if (groupRow != null) {
+                const leftData = {
+                    id: groupRow.id,
+                    name: groupRow.name,
+                    description: groupRow.description,
+                    createdBy: groupRow.created_by,
+                    createdAt: toISO(groupRow.created_at),
+                    groupID
+                };
+                // Defer past the outermost commit: the `groupLeft` listener reads the P2P
+                // store on the main connection (deadlocks single-conn SQLite / uncommitted on PG).
+                deps.stores.onCommit(()=>{
+                    deps.emitter.emit('groupLeft', leftData).catch((error)=>{
+                        deps.logger.error('groupLeft emit failed', {
+                            groupID,
+                            error
+                        });
+                    });
+                });
+            }
+            return {
+                groupID
+            };
+        },
+        removeMember: async (groupID, memberDID)=>{
+            // One HLC orders BOTH the MLS-roster tombstone and the admin-role
+            // revocation appended below. 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 the ex-admin signs 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 the
+            // roster tombstone so a non-admin attempt rolls back without touching the
+            // MLS roster; the schema-layer `failTransactionFatal` wrap turns the throw
+            // into a full-transaction rollback and forwards the message to the caller.
+            if (!await isLedgerAdminAtHLC({
+                store,
+                groupID,
+                anchor,
+                did: selfDID,
+                atHLC: hlc,
+                logger: deps.logger
+            })) {
+                throw new Error('only a group admin can remove a member');
+            }
+            // Resolve whether the removed DID is an admin BEFORE the tombstone. Once
+            // the roster tombstone writes `removed_at_hlc == hlc`, membership-at-HLC
+            // (which requires `removed_at_hlc > hlc`) would read false and wrongly
+            // report a removed admin as a non-admin, suppressing the revocation.
+            const removedIsAdmin = await isLedgerAdminAtHLC({
+                store,
+                groupID,
+                anchor,
+                did: memberDID,
+                atHLC: hlc,
+                logger: deps.logger
+            });
+            // Refuse to remove the last admin: fold the admin set at this HLC and 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.
+            if (removedIsAdmin) {
+                const entries = await loadVerifiedAdminEntries(store, groupID, deps.logger);
+                const admins = foldAdminRoster(entries, anchor, hlc).admins;
+                const survivors = new Set(admins);
+                survivors.delete(normalizeDID(memberDID));
+                if (survivors.size === 0) {
+                    throw new Error('cannot remove the last admin');
+                }
+            }
+            // MLS-roster delta + projected tombstone, stamped with the shared HLC.
+            const { commitMessage } = await deps.groupManager.removeGroupMember({
+                stores: deps.stores,
+                groupID,
+                memberDID,
+                hlc
+            });
+            // Revoke the ex-admin's control authority atomically with the tombstone.
+            // Only admins fold authoritatively, so only an admin needs revoking — a
+            // non-admin removal appends nothing and broadcasts no ledger entry.
+            let revokeToken = null;
+            if (removedIsAdmin) {
+                const value = 'revoked';
+                const token = await signLedgerEntry(deps.identity, {
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: memberDID,
+                    value,
+                    hlc
+                });
+                const entryID = ledgerEntryDigest(token);
+                // `appendLedgerEntry` normalizes `issuer_did`, so the raw self DID is passed.
+                await store.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: ADMIN_ROLE_ENTRY_TYPE,
+                    subject: memberDID,
+                    value,
+                    hlc,
+                    issuer_did: selfDID,
+                    signed_token: token
+                });
+                await reprojectAdminRoster({
+                    store,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                revokeToken = token;
+            }
+            await deps.emitter.emit('groupMemberLeft', {
+                groupID,
+                memberDID,
+                role: '',
+                createdAt: new Date().toISOString()
+            });
+            // Record-before-send: defer the MLS commit fan-out (so existing members
+            // advance their MLS epoch and tombstone the removed member) and the revoke
+            // broadcast (so co-members fold the same entry against their own anchor) to
+            // the OUTERMOST commit. Registering via `onCommit` keeps a rolled-back
+            // removal from ever being sent or observed.
+            deps.stores.onCommit(()=>{
+                deps.scheduleSendCommit(groupID, commitMessage);
+                if (revokeToken != null) {
+                    deps.scheduleBroadcast(groupID, {
+                        type: 'ledger:entry',
+                        groupID,
+                        token: revokeToken
+                    });
+                }
+            });
+            return {
+                groupID
+            };
+        },
+        update: async (input)=>{
+            const groupID = input.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');
+            }
+            // No-op when the caller set neither field: `UpdateGroupInput` makes both
+            // `name` and `description` optional, so an input carrying only `groupID`
+            // would otherwise mint an empty-value `group.settings` entry + broadcast
+            // that folds to the same projected state. Return the current group row
+            // without appending an entry, broadcasting, or emitting.
+            if (input.name === undefined && input.description === undefined) {
+                const store = await getP2PStore();
+                const row = await store.getGroup(groupID);
+                if (row == null) throw new Error(`Group ${groupID} not found`);
+                return {
+                    id: row.id,
+                    name: row.name,
+                    description: row.description,
+                    createdBy: row.created_by,
+                    createdAt: toISO(row.created_at)
+                };
+            }
+            const hlc = HLC.serialize(deps.hlc.now());
+            // `group.settings` folds per field: carry ONLY the fields the caller set.
+            // An explicit empty string 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;
+            const token = await signLedgerEntry(deps.identity, {
+                type: GROUP_SETTINGS_ENTRY_TYPE,
+                subject: groupID,
+                value,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            // Append the signed entry and reproject the group-settings overlay
+            // atomically so a crash can never leave the durable ledger and the
+            // projected group row diverged. `appendLedgerEntry` normalizes
+            // `issuer_did`, so the raw self DID is passed.
+            const updatedGroupData = await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: GROUP_SETTINGS_ENTRY_TYPE,
+                    subject: groupID,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectGroupSettings({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getGroup(groupID);
+                if (row == null) throw new Error(`Group ${groupID} not found`);
+                return {
+                    id: row.id,
+                    name: row.name,
+                    description: row.description,
+                    createdBy: row.created_by,
+                    createdAt: toISO(row.created_at)
+                };
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same entry
+            // against their own anchor) and the local emit to the OUTERMOST commit. Under
+            // `mutateGraph` this handler runs inside the engine's write transaction, so
+            // the inner `withTransaction` above nests inline and does NOT commit on its
+            // own — the outer transaction commits later. Registering via `onCommit` keeps
+            // a rolled-back update from ever being broadcast or observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('groupDataChanged', {
+                    ...updatedGroupData,
+                    groupID
+                });
+            });
+            return updatedGroupData;
+        },
+        updateCircle: 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;
+            // 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,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            const updatedCircleData = await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: CIRCLE_DEF_ENTRY_TYPE,
+                    subject: input.circleID,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectCircleDefs({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getCircle(input.circleID);
+                if (row == null) throw new Error('Failed to read circle after update');
+                return {
+                    id: row.id,
+                    groupID: row.group_id,
+                    name: row.name,
+                    description: row.description,
+                    createdAt: toISO(row.created_at)
+                };
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same entry
+            // against their own anchor) and the local emit to the OUTERMOST commit. Under
+            // `mutateGraph` this handler runs inside the engine's write transaction, so
+            // the inner `withTransaction` above nests inline and does NOT commit on its
+            // own — the outer transaction commits later. Registering via `onCommit` keeps
+            // a rolled-back update from ever being broadcast or observed locally. Broadcast
+            // first, then emit, to match the order the other producers use.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                if (input.catalogIDs != null) {
+                    void deps.emitter.emit('circleCatalogsChanged', {
+                        ...updatedCircleData,
+                        circleID: input.circleID
+                    });
+                } else {
+                    void deps.emitter.emit('circleDataChanged', {
+                        ...updatedCircleData,
+                        circleID: input.circleID
+                    });
+                }
+            });
+            return updatedCircleData;
+        },
+        updateCatalog: async (p)=>{
+            const graphStore = await getGraphStore();
+            const hlcStr = HLC.serialize(deps.hlc.now());
+            const update = {
+                hlc: hlcStr
+            };
+            if (p.name != null) update.name = p.name;
+            if (p.filterCriteria != null) {
+                update.filter_criteria = JSON.parse(p.filterCriteria);
+            }
+            await graphStore.updateCatalog(p.catalogID, update);
+            const row = await graphStore.getCatalog(p.catalogID);
+            if (row == null) throw new Error(`Catalog ${p.catalogID} not found`);
+            return {
+                id: row.id,
+                ownerDID: row.owner_did,
+                name: row.name,
+                description: row.description,
+                filterCriteria: JSON.stringify(row.filter_criteria),
+                createdAt: toISO(row.created_at)
+            };
+        },
+        deleteCatalog: async (catalogID)=>{
+            const graphStore = await getGraphStore();
+            await graphStore.deleteCatalog(catalogID);
+            return {
+                deletedID: catalogID
+            };
+        },
+        deleteCircle: async (circleID)=>{
+            const store = await getP2PStore();
+            const existing = await store.getCircle(circleID, {
+                includeRemoved: true
+            });
+            // No-op when the circle is absent (never created) or already tombstoned:
+            // minting a dead `removed` entry + broadcast would only churn the ledger
+            // and converge to the same projected state.
+            if (existing == null || existing.removed_at_hlc != null) {
+                return {
+                    deletedID: circleID
+                };
+            }
+            const groupID = existing.group_id;
+            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 both the durable tombstone entry and the broadcast token,
+            // so the locally projected `removed_at_hlc` and the HLC every co-member
+            // folds are identical — store and wire can never diverge.
+            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,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: CIRCLE_DEF_ENTRY_TYPE,
+                    subject: circleID,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectCircleDefs({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getCircle(circleID, {
+                    includeRemoved: true
+                });
+                if (row == null || row.removed_at_hlc == null) {
+                    throw new Error('Failed to tombstone circle after delete');
+                }
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same
+            // tombstone against their own anchor) and the local emit to the OUTERMOST
+            // commit. Under `mutateGraph` this handler runs inside the engine's write
+            // transaction, so the inner `withTransaction` above nests inline and does
+            // NOT commit on its own — the outer transaction commits later. Registering
+            // via `onCommit` keeps a rolled-back deletion from ever being broadcast or
+            // observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('circleDeleted', {
+                    id: existing.id,
+                    groupID: existing.group_id,
+                    name: existing.name,
+                    description: existing.description,
+                    createdAt: toISO(existing.created_at)
+                });
+            });
+            return {
+                deletedID: circleID
+            };
+        },
+        removeCircleMember: async (circleID, memberDID)=>{
+            const store = await getP2PStore();
+            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. Minting a dead `removed`
+            // entry + broadcast for it would only churn the ledger and converge to
+            // the same projected state, so return the requested pair untouched.
+            if (existing == null || existing.removed_at_hlc != null) {
+                return {
+                    circleID,
+                    memberDID
+                };
+            }
+            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;
+            // 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');
+            }
+            // One HLC stamps both the durable tombstone entry and the broadcast token,
+            // so the locally projected `removed_at_hlc` and the HLC every co-member
+            // folds are identical — store and wire can never diverge.
+            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,
+                hlc
+            });
+            const entryID = ledgerEntryDigest(token);
+            // Append the signed tombstone and reproject the circle-member overlay
+            // atomically so a crash can never leave the durable ledger and the
+            // projected row diverged. `appendLedgerEntry` normalizes `issuer_did`, so
+            // the raw self DID is passed.
+            await deps.stores.withTransaction(async (tx)=>{
+                const txStore = await resolveP2PStore(tx);
+                await txStore.appendLedgerEntry({
+                    group_id: groupID,
+                    entry_id: entryID,
+                    type: CIRCLE_MEMBER_ENTRY_TYPE,
+                    subject,
+                    value,
+                    hlc,
+                    issuer_did: deps.identity.id,
+                    signed_token: token
+                });
+                await reprojectCircleMembers({
+                    store: txStore,
+                    groupID,
+                    anchor,
+                    logger: deps.logger
+                });
+                const row = await txStore.getCircleMember(circleID, memberDID);
+                if (row == null || row.removed_at_hlc == null) {
+                    throw new Error('Failed to tombstone circle member after remove');
+                }
+            });
+            // Record-before-send: defer the fan-out (so co-members fold the same
+            // tombstone against their own anchor) and the local emit to the OUTERMOST
+            // commit. Under `mutateGraph` this handler runs inside the engine's write
+            // transaction, so the inner `withTransaction` above nests inline and does
+            // NOT commit on its own — the outer transaction commits later. Registering
+            // via `onCommit` keeps a rolled-back removal from ever being broadcast or
+            // observed locally.
+            deps.stores.onCommit(()=>{
+                deps.scheduleBroadcast(groupID, {
+                    type: 'ledger:entry',
+                    groupID,
+                    token
+                });
+                void deps.emitter.emit('circleMemberRemoved', {
+                    circleID,
+                    memberDID,
+                    role: existing.role,
+                    createdAt: toISO(existing.created_at)
+                });
+            });
+            return {
+                circleID,
+                memberDID
+            };
+        },
+        grantWriteCapability: async ({ to, res, groupID, expiresIn })=>{
+            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()
+            ]);
+            const cap = await delegationStore.getDelegationTokenByJTI(jti);
+            if (cap == null) {
+                // Multi-device-grantor case (the issuing device is not the one running
+                // this resolver) is not yet supported; surface the missing-local-row
+                // condition explicitly so callers can distinguish it from authz.
+                throw new GraphQLError(`No capability found locally for jti ${jti}`, {
+                    extensions: {
+                        code: 'REVOCATION_CAP_UNKNOWN'
+                    }
+                });
+            }
+            if (cap.grantor !== ctx.viewerDID) {
+                throw new GraphQLError(`Only the capability issuer can revoke jti ${jti}`, {
+                    extensions: {
+                        code: 'REVOCATION_UNAUTHORIZED'
+                    }
+                });
+            }
+            // 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'
+                    }
+                });
+            }
+            const record = await createRevocationRecord(deps.identity, jti);
+            const signed = await deps.identity.signToken(record);
+            const token = stringifyToken(signed);
+            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 hot-path `isRevoked` gate fires immediately
+            // without a separate verification round-trip.
+            const changed = await delegationStore.addRevocation({
+                jti,
+                revoker_did: deps.identity.id,
+                revoked_iat: record.iat,
+                revocation_token: token,
+                verified_at: record.iat,
+                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: record.iat,
+                    verifiedAt: record.iat,
+                    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;
+        }
+    };
+}