@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/schema.js

@@ -1,5 +1,7 @@
 import { TransactionFatalError } from '@kubun/engine';
+import { PluginNodeID } from '@kubun/id';
 import { getKubunLogger } from '@kubun/logger';
+import { GraphQLError } from 'graphql';
 import { createFilteredGenerator } from './groups/events.js';
 function requireP2P(ctx) {
     if (ctx.p2p == null) {
@@ -7,6 +9,33 @@ function requireP2P(ctx) {
     }
     return ctx.p2p;
 }
+/**
+ * The read-default writers `setCircleSync` runs its share diff through.
+ *
+ * Owner-signed via the engine's access-default executors, so
+ * `engine:access-default:set` / `:removed` fire and the broadcast + push seeding
+ * stay consistent — the same path `setModelAccessDefaults` takes. Shared by every
+ * caller that applies a circle's sync state, so two entry points cannot write the
+ * same rule two ways.
+ */ function accessDefaultExecutors(context) {
+    return {
+        setReadDefault: async (p)=>{
+            await context.executeSetModelAccessDefaults({
+                modelID: p.modelID,
+                permissionType: 'read',
+                accessLevel: p.accessLevel,
+                allowedDIDs: p.allowedDIDs,
+                allowedCircles: p.allowedCircles,
+                allowedGroups: p.allowedGroups
+            });
+        },
+        removeReadDefault: async (modelID)=>{
+            await context.executeRemoveModelAccessDefaults(modelID, [
+                'read'
+            ]);
+        }
+    };
+}
 /**
  * Re-raise any failure from a membership/circle operation as the engine's
  * transaction-rollback marker so `mutateGraph` rolls back the whole transaction.
@@ -17,24 +46,50 @@ function requireP2P(ctx) {
  * is forwarded unchanged so an expected validation error (e.g. access-denied)
  * still reaches the client as before; the cause carries the full original error.
  *
- * Only multi-write ops whose partial commit would fail OPEN (toward more
- * privilege — leaving a removed/demoted DID authoritative) are wrapped:
- * `inviteToGroup`, `removeGroupMember`, `leaveGroup`, `setMemberRole`,
- * `removeCircleMember`. Ops that fail toward less privilege / benign metadata
- * (circle create/update, capability writes) self-heal on the next idempotent
- * reprojection and are intentionally left unwrapped — a new remove/demote op
- * should add a wrap here.
+ * Wrap ONLY multi-write ops whose partial commit would fail OPEN — toward more
+ * privilege, leaving a removed or demoted DID authoritative — plus every
+ * request-shaped mutation, which enqueues a request row nothing heals. Ops touching
+ * benign metadata are left unwrapped.
  *
- * Caveat: a thrown `GraphQLError`'s `extensions` (e.g. a `code`) are not carried
- * onto the re-raised top-level error (they remain on `.cause`); none of the
- * wrapped resolvers currently throw coded GraphQLErrors, so no client-visible
- * code is lost today.
+ * A thrown `GraphQLError`'s `extensions` ARE carried across the re-raise, so a
+ * refusal that can only be decided by reading the state it refuses — the last
+ * admin leaving, demoting themselves, or being removed — keeps the code an app
+ * matches on. An authorization gate still belongs BEFORE the `try`: it reads
+ * only, so there is nothing to roll back and nothing to un-write. Use
+ * {@link gatedTransaction} rather than calling this directly.
  */ function failTransactionFatal(operation, error) {
     const message = error instanceof Error ? error.message : `${operation} failed`;
+    // A typed refusal keeps its code across the re-raise: graphql-js copies
+    // `originalError.extensions` onto the GraphQLError it wraps this throw in.
+    // Only a check that must READ the state it refuses needs this — a pure
+    // authorization gate still belongs before the `try`, where nothing has been
+    // written yet (see {@link gatedTransaction}).
+    const extensions = error instanceof GraphQLError && Object.keys(error.extensions ?? {}).length > 0 ? error.extensions : undefined;
     throw new TransactionFatalError(message, {
-        cause: error
+        cause: error,
+        ...extensions == null ? {} : {
+            extensions
+        }
     });
 }
+/**
+ * Run an authorization gate and then a rollback-wrapped body, in the only order
+ * that preserves a typed refusal.
+ *
+ * `gate` runs OUTSIDE the `try` because it only reads: there is nothing to roll
+ * back, and a refusal that never opened a transaction should not pretend to have
+ * one. Taking it as its own argument is what stops a mutation gating inside the
+ * wrapper. (A code raised inside `run` reaches the client too — see
+ * {@link failTransactionFatal} — so this is about where the refusal belongs,
+ * not about whether it survives.)
+ */ async function gatedTransaction(operation, gate, run) {
+    await gate();
+    try {
+        return await run();
+    } catch (error) {
+        failTransactionFatal(operation, error);
+    }
+}
 // Internal lowercase-kebab health values -> SDL enum names.
 const HEALTH_STATE_TO_SDL = {
     healthy: 'HEALTHY',
@@ -46,6 +101,48 @@ const HEALTH_STATE_TO_SDL = {
 const HEALTH_CONDITION_TO_SDL = {
     'epoch-stale': 'EPOCH_STALE'
 };
+// Internal lowercase control-request values -> SDL enum names.
+const CONTROL_REQUEST_STATUS_TO_SDL = {
+    pending: 'PENDING',
+    committed: 'COMMITTED',
+    rejected: 'REJECTED',
+    lost: 'LOST',
+    no_op: 'NO_OP'
+};
+const CONTROL_REQUEST_KIND_TO_SDL = {
+    ledger: 'LEDGER',
+    invite: 'INVITE',
+    remove: 'REMOVE'
+};
+/** Project a control request into its SDL shape, mapping both enums to uppercase. */ function toControlRequestSDL(request) {
+    return {
+        ...request,
+        kind: CONTROL_REQUEST_KIND_TO_SDL[request.kind],
+        status: CONTROL_REQUEST_STATUS_TO_SDL[request.status]
+    };
+}
+/**
+ * Deliver one request's terminal status, whenever it happens, then complete.
+ *
+ * `stream` must already be listening when this is called — the read below can
+ * only see a settle that has landed, and the stream can only see one that has
+ * not, so between them every outcome is covered exactly once. A settle is
+ * final, so the first delivery ends the stream.
+ */ async function* watchOneControlRequest(stream, read) {
+    try {
+        const existing = await read();
+        if (existing != null && existing.status !== 'pending') {
+            yield existing;
+            return;
+        }
+        for await (const settled of stream){
+            yield settled;
+            return;
+        }
+    } finally{
+        await stream.return();
+    }
+}
 async function* emptyAsyncGenerator() {
 // no-op: closes immediately so subscribers without a viewer get no events
 }
@@ -60,8 +157,8 @@ type PeerGroup {
 
 type PeerGroupMember {
   groupID: ID!
-  memberDID: DID!
-  role: String!
+  account: AccountNode!
+  role: GroupMemberRole!
   createdAt: DateTimeISO!
 }
 
@@ -70,9 +167,20 @@ type PeerCircle {
   groupID: ID!
   name: String!
   description: String
+  """Admin-authored: every group member reaches an open circle implicitly."""
+  open: Boolean!
   createdAt: DateTimeISO!
 }
 
+type PeerDevice {
+  peerDID: DID!
+  """Self-declared display hint, never an identity."""
+  label: String!
+  availability: String!
+  """The announcer's own stamp; the row is last-writer-wins keyed by it."""
+  hlc: String!
+}
+
 type PeerCircleMember {
   circleID: ID!
   memberDID: DID!
@@ -86,6 +194,9 @@ type PeerCatalog {
   name: String!
   description: String
   filterCriteria: String!
+  active: Boolean!
+  sourceGroupID: ID
+  sourceCircleID: ID
   createdAt: DateTimeISO!
 }
 
@@ -113,8 +224,21 @@ type CreateGroupPayload {
   group: PeerGroup!
 }
 
-type InviteToGroupPayload {
-  invitePayload: String!
+input RequestInviteToGroupInput {
+  groupID: ID!
+  joinRequest: String!
+  grants: [String!]
+  revocations: [String!]
+}
+
+"""
+Waits for its own commit, unlike the other request-shaped mutations. invitePayload
+is present only when status is COMMITTED; PENDING carries none, REJECTED and LOST
+raise. Ack the request once the payload has been passed on.
+"""
+type RequestInviteToGroupPayload {
+  request: ControlRequest!
+  invitePayload: String
   groupID: ID!
   groupName: String!
 }
@@ -135,8 +259,14 @@ type LeaveGroupPayload {
   groupID: ID!
 }
 
-type RemoveGroupMemberPayload {
+input RequestRemoveGroupMemberInput {
   groupID: ID!
+  memberDID: DID!
+}
+
+"""The request, not the removal: the tombstone lands with the commit. Watch it."""
+type RequestRemoveGroupMemberPayload {
+  request: ControlRequest!
 }
 
 enum GroupMemberRole {
@@ -144,14 +274,15 @@ enum GroupMemberRole {
   member
 }
 
-input SetMemberRoleInput {
+input RequestSetMemberRoleInput {
   groupID: ID!
   memberDID: DID!
   role: GroupMemberRole!
 }
 
-type SetMemberRolePayload {
-  member: PeerGroupMember!
+"""The request, not the role: it moves with the commit. Watch it."""
+type RequestSetMemberRolePayload {
+  request: ControlRequest!
 }
 
 input UpdateCatalogInput {
@@ -160,14 +291,49 @@ input UpdateCatalogInput {
   filterCriteria: String
 }
 
-input UpdateGroupInput {
+input RequestUpdateGroupInput {
   groupID: ID!
   name: String
   description: String
+  openCircleIDs: [String!]
+  commitHub: SuggestedHubInput
 }
 
-type UpdateGroupPayload {
-  group: PeerGroup!
+"""
+The request, not the settings: they move with the commit. Watch it. No field
+beyond groupID settles NO_OP.
+"""
+type RequestUpdateGroupPayload {
+  request: ControlRequest!
+}
+
+input RequestCreateCircleInput {
+  groupID: ID!
+  name: String!
+  description: String
+}
+
+"""
+The request plus the new circle's id, minted up front so a caller can name the
+circle before the commit enacts it. Not queryable until then; watch the request.
+"""
+type RequestCreateCirclePayload {
+  request: ControlRequest!
+  circleID: ID!
+}
+
+input RequestAddCircleMemberInput {
+  circleID: ID!
+  memberDID: DID!
+  role: String!
+}
+
+"""
+The request, not the membership: the row appears with the commit. Watch it. A DID
+already in the circle at this role settles NO_OP.
+"""
+type RequestAddCircleMemberPayload {
+  request: ControlRequest!
 }
 
 input UpdateCircleInput {
@@ -177,30 +343,47 @@ input UpdateCircleInput {
   catalogIDs: [String!]
 }
 
-type UpdateCirclePayload {
-  circle: PeerCircle!
+"""
+The request, not the definition: it moves with the commit. Watch it. No field
+beyond circleID settles NO_OP.
+"""
+type RequestUpdateCirclePayload {
+  request: ControlRequest!
 }
 
 type DeleteCatalogPayload {
   deletedID: ID!
 }
 
-type DeleteCirclePayload {
-  deletedID: ID!
+input RequestDeleteCircleInput {
+  circleID: ID!
 }
 
-type RemoveCircleMemberPayload {
+"""
+The request, not the deletion: the tombstone lands with the commit. Watch it. An
+already-gone circle settles NO_OP.
+"""
+type RequestDeleteCirclePayload {
+  request: ControlRequest!
+}
+
+input RequestRemoveCircleMemberInput {
   circleID: ID!
   memberDID: DID!
 }
 
+"""
+The request, not the removal: the tombstone lands with the commit. Watch it. A DID
+that is not an active member settles NO_OP.
+"""
+type RequestRemoveCircleMemberPayload {
+  request: ControlRequest!
+}
+
 type SyncPeer {
   id: String!
   peerDID: DID!
   endpoint: URL!
-  mode: String!
-  priority: String!
-  trustLevel: String!
   createdAt: Int!
   updatedAt: Int!
 }
@@ -221,6 +404,20 @@ type RemoveSyncPeerPayload {
   success: Boolean!
 }
 
+type SyncPeerPayload {
+  messagesReceived: Int!
+  messagesSent: Int!
+  divergentBuckets: Int!
+}
+
+type SyncEvent {
+  type: String!
+  peerID: ID!
+  documentID: ID
+  timestamp: Float!
+  error: String
+}
+
 input CreateHubInput {
   url: URL!
   label: String
@@ -254,10 +451,8 @@ input DelegationTokenCovers {
 }
 
 """
-A verified revocation of a delegation token addressed to the viewer.
-Only surfaces while the underlying held capability still exists locally;
-revocations whose cap was deleted or never arrived are excluded by the
-audience-derivation join.
+A verified revocation of a delegation token addressed to the viewer. Surfaces only
+while the held capability still exists locally.
 """
 type RevokedDelegationToken {
   jti: ID!
@@ -266,22 +461,114 @@ type RevokedDelegationToken {
   revokerDID: DID!
   "Issuer's revocation-record timestamp (iat), Unix epoch seconds."
   revokedAt: Int!
-  """
-  Wall-clock time the revocation became binding, Unix epoch seconds. For
-  self-issued revocations this equals revokedAt (verified at mint time);
-  for received revocations it is the receiver's clock at the moment the
-  cap-vs-revoker cross-check succeeded.
-  """
+  "When the revocation became binding here, Unix epoch seconds."
   verifiedAt: Int!
   capExp: Int
   groupID: ID!
 }
 
+type RemoteGroupInfo {
+  id: ID!
+  name: String!
+}
+
+type PeerInfo {
+  did: ID!
+  endpoint: String!
+  groups: [RemoteGroupInfo!]!
+}
+
+type ConnectPeerPayload {
+  peer: PeerInfo!
+}
+
+"""
+Models to share into a circle. Omitted on sharePeerGroup leaves that leg untouched.
+On setCircleSync it is the desired END STATE — an empty list stops sharing.
+"""
+input ShareInput {
+  models: [ID!]!
+}
+
+input ShareReceiveInput {
+  activate: Boolean!
+}
+
+enum CircleModelAccess {
+  MODEL_GRANTED
+  MODEL_PRE_EXISTING
+  DOCUMENT_ONLY
+}
+
+type ModelShareResult {
+  modelID: ID!
+  access: CircleModelAccess!
+}
+
+type SharePeerGroupPayload {
+  group: PeerGroup!
+  modelAccess: [ModelShareResult!]!
+  catalogID: ID
+}
+
+type AdmitJoinRequestPayload {
+  group: PeerGroup!
+  modelAccess: [ModelShareResult!]!
+  catalogID: ID
+  """Derived from the join request's KeyPackage credential, not its did field."""
+  peerDID: ID!
+  """
+  The invite to hand to the joiner. Carries the access designated above, so the
+  joiner lands in the share circle at join.
+  """
+  invitePayload: String!
+}
+
+"""
+A circle this device can reach, with its own sync state for it. pulling is true only
+when the circle has catalogs and every one is active locally; sharing holds the
+models this device lets the circle read.
+"""
+type CircleSyncState {
+  id: ID!
+  groupID: ID!
+  name: String!
+  description: String!
+  catalogIDs: [ID!]!
+  """Admin-authored: every group member reaches an open circle implicitly."""
+  open: Boolean!
+  pulling: Boolean!
+  sharing: [ID!]!
+}
+
+type JoinPeerGroupPayload {
+  group: PeerGroup!
+  knownCatalogIDs: [ID!]!
+  alreadyJoined: Boolean!
+  """
+  The group's OPEN circles, for an opt-in picker. A closed circle this device holds
+  a grant for is excluded; circleSync returns every reachable circle.
+  """
+  openCircles: [CircleSyncState!]!
+}
+
 extend type Query {
   groups: [PeerGroup!]!
   group(id: ID!): PeerGroup
   groupMembers(groupID: ID!): [PeerGroupMember!]!
   circles(groupID: ID!): [PeerCircle!]!
+  """
+  Every device this one has heard announce in the group, its own row included. A
+  projection, never liveness: no row is deleted on silence, so a sleeping device is
+  still listed and a screen marks it stale rather than losing it.
+  """
+  peerDevices(groupID: ID!): [PeerDevice!]!
+  """
+  Every circle in the group this device can currently reach, with its pull/share
+  state. Re-read to pick up a circle the admin opened or closed since the join.
+  """
+  circleSync(groupID: ID!): [CircleSyncState!]!
+  catalogs(active: Boolean): [PeerCatalog!]!
   hubs: [PeerHub!]!
   hub(id: ID!): PeerHub
   syncPeers: [SyncPeer!]!
@@ -289,6 +576,11 @@ extend type Query {
   ownDelegationTokens(grantor: ID, covers: DelegationTokenCovers): [DelegationToken!]!
   ownRevokedDelegationTokens(grantor: ID): [RevokedDelegationToken!]!
   groupHealth(groupID: ID!): GroupHealthStatus!
+  """
+  This device's own un-acked control requests, oldest first, optionally scoped to
+  one group. The store is per-device.
+  """
+  controlRequests(groupID: ID): [ControlRequest!]!
 }
 
 enum GroupHealthCondition {
@@ -320,28 +612,93 @@ type RejoinGroupPayload {
   state: GroupHealthState!
 }
 
+enum ControlRequestStatus {
+  PENDING
+  COMMITTED
+  REJECTED
+  LOST
+  """
+  The state already held, so no commit was driven. Terminal, and deliberately not
+  COMMITTED: nothing was committed.
+  """
+  NO_OP
+}
+
+enum ControlRequestKind {
+  LEDGER
+  INVITE
+  REMOVE
+}
+
+"""
+One entry of this device's control-request queue: a control-plane mutation whose
+commit lands later. A settled request keeps its row until ackControlRequest drops it.
+"""
+type ControlRequest implements Node {
+  id: ID!
+  groupID: ID!
+  kind: ControlRequestKind!
+  status: ControlRequestStatus!
+  error: String
+  enqueuedAt: DateTimeISO!
+  settledAt: DateTimeISO
+}
+
 extend type Mutation {
+  connectPeer(url: String!): ConnectPeerPayload!
+  sharePeerGroup(peerDID: ID!, groupID: ID, name: String, send: ShareInput, receive: ShareReceiveInput): SharePeerGroupPayload!
+  """
+  Admit a join request's author from local state alone: designate access as
+  sharePeerGroup does, then mint the invite carrying it. No peer connection is
+  opened — the caller hands the payload to the joiner however it can. The admitted
+  DID comes from the request's KeyPackage credential; a disagreeing did field, or a
+  DID already on the roster, is refused.
+  """
+  admitJoinRequest(groupID: ID!, joinRequest: String!, send: ShareInput, receive: ShareReceiveInput): AdmitJoinRequestPayload!
+  joinPeerGroup(peerDID: ID!, groupID: ID!): JoinPeerGroupPayload!
+  """
+  Apply one circle's desired sync end state. A null argument leaves that dimension
+  untouched; share with an empty model list stops sharing into the circle.
+  """
+  setCircleSync(circleID: ID!, pull: Boolean, share: ShareInput): CircleSyncState!
+  """
+  Sync with one named device now. groupID selects the ROUTE, not the scope — the
+  session carries the device's whole active-catalog scope, so one call can move
+  documents belonging to a different group.
+  """
+  syncPeer(groupID: ID!, peerDID: ID!): SyncPeerPayload!
   createGroup(input: CreateGroupInput!): CreateGroupPayload!
-  addGroupMember(groupID: ID!, memberDID: DID!, role: String!): PeerGroupMember!
-  createCircle(groupID: ID!, name: String!, description: String): PeerCircle!
-  addCircleMember(circleID: ID!, memberDID: DID!, role: String!): PeerCircleMember!
+  requestCreateCircle(input: RequestCreateCircleInput!): RequestCreateCirclePayload!
+  requestAddCircleMember(input: RequestAddCircleMemberInput!): RequestAddCircleMemberPayload!
   createCatalog(name: String!, description: String, filterCriteria: String!): PeerCatalog!
-  inviteToGroup(groupID: ID!, joinRequest: String!, grants: [String!], revocations: [String!]): InviteToGroupPayload!
+  requestInviteToGroup(input: RequestInviteToGroupInput!): RequestInviteToGroupPayload!
   joinGroup(invitePayload: String!, joinRequestPayload: String!): JoinGroupPayload!
   prepareJoinRequest: PrepareJoinRequestPayload!
-  completeJoin(invitePayload: String!): CompleteJoinPayload!
+  """
+  Join the group an invite names, declaring in the same call what this device shares
+  back and whether it pulls. send / receive mirror admitJoinRequest. Left off, the
+  join is plumbing only: a member that grants nothing and pulls nothing. Applied to
+  every circle this device now belongs to, which is exactly what the invite seeded.
+  """
+  completeJoin(
+    invitePayload: String!
+    send: ShareInput
+    receive: ShareReceiveInput
+  ): CompleteJoinPayload!
   leaveGroup(groupID: ID!): LeaveGroupPayload!
-  removeGroupMember(groupID: ID!, memberDID: DID!): RemoveGroupMemberPayload!
-  setMemberRole(input: SetMemberRoleInput!): SetMemberRolePayload!
+  requestRemoveGroupMember(input: RequestRemoveGroupMemberInput!): RequestRemoveGroupMemberPayload!
+  requestSetMemberRole(input: RequestSetMemberRoleInput!): RequestSetMemberRolePayload!
   updateCatalog(input: UpdateCatalogInput!): PeerCatalog!
-  updateGroup(input: UpdateGroupInput!): UpdateGroupPayload!
-  updateCircle(input: UpdateCircleInput!): UpdateCirclePayload!
+  activateCatalogSync(catalogID: ID!): PeerCatalog!
+  deactivateCatalogSync(catalogID: ID!): PeerCatalog!
+  requestUpdateGroup(input: RequestUpdateGroupInput!): RequestUpdateGroupPayload!
+  requestUpdateCircle(input: UpdateCircleInput!): RequestUpdateCirclePayload!
   deleteCatalog(catalogID: ID!): DeleteCatalogPayload!
-  deleteCircle(circleID: ID!): DeleteCirclePayload!
-  removeCircleMember(circleID: ID!, memberDID: DID!): RemoveCircleMemberPayload!
+  requestDeleteCircle(input: RequestDeleteCircleInput!): RequestDeleteCirclePayload!
+  requestRemoveCircleMember(input: RequestRemoveCircleMemberInput!): RequestRemoveCircleMemberPayload!
   grantWriteCapability(to: DID!, res: String!, groupID: ID!, expiresIn: Int): String!
   revokeCapability(jti: ID!): Boolean!
-  addSyncPeer(peerDID: DID!, endpoint: URL!, mode: String, priority: String, trustLevel: String): Boolean!
+  addSyncPeer(peerDID: DID!, endpoint: URL!): Boolean!
   removeSyncPeer(peerDID: DID!): RemoveSyncPeerPayload!
   createHub(input: CreateHubInput!): PeerHub!
   updateHub(input: UpdateHubInput!): PeerHub!
@@ -349,10 +706,26 @@ extend type Mutation {
   bindHubToGroup(hubID: ID!, groupID: ID!): Boolean!
   unbindHubFromGroup(hubID: ID!, groupID: ID!): Boolean!
   rejoinGroup(groupID: ID!): RejoinGroupPayload!
+  """
+  Drop a settled request from the queue — the app saying it has observed the
+  outcome. Acking a pending or unknown request is a no-op. node(id:) on an acked
+  request throws.
+  """
+  ackControlRequest(id: ID!): Boolean!
 }
 
 extend type PeerGroup {
   hubs: [PeerHub!]!
+  """
+  Whether the viewer may perform this group's admin-only operations right now. Read
+  from the membership row the admin gate consults, so the two never disagree.
+  """
+  viewerIsAdmin: Boolean!
+  """
+  Every current admin, from the same membership rows. Moves when the MLS commit
+  carrying a role change is enacted.
+  """
+  admins: [AccountNode!]!
 }
 
 extend type PeerHub {
@@ -365,6 +738,8 @@ extend type Subscription {
   groupDataChanged(groupID: ID!): PeerGroup!
   groupMemberJoined(groupID: ID!): PeerGroupMember!
   groupMemberLeft(groupID: ID!): PeerGroupMember!
+  """A member's role as it stands after the enacted commit that changed it."""
+  groupMemberRoleChanged(groupID: ID!): PeerGroupMember!
   circleCreated(groupID: ID!): PeerCircle!
   circleDeleted(groupID: ID!): PeerCircle!
   circleDataChanged(circleID: ID!): PeerCircle!
@@ -374,11 +749,48 @@ extend type Subscription {
   ownDelegationTokenAdded: DelegationToken!
   ownDelegationTokenRevoked: RevokedDelegationToken!
   groupHealthChanged(groupID: ID): GroupHealthEvent!
+  syncEvents(peerDID: ID): SyncEvent!
+  """
+  A control request reached a terminal status, under the same global id the
+  enqueuing mutation returned. requestID watches one request, replaying a status
+  that settled before the subscription opened, then completes; groupID watches every
+  request in the group and stays open. An unknown requestID waits rather than
+  failing — indistinguishable from an uncommitted enqueue — so bring your own timeout.
+  """
+  controlRequestSettled(groupID: ID, requestID: ID): ControlRequest!
 }
 `;
-export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-schema')) {
+export function createP2PSchemaExtension(emitter, syncManager, logger = getKubunLogger('p2p-schema')) {
     return {
         sdl,
+        // These mutations perform network I/O (peer discovery, the MLS dance,
+        // merkle sync) and/or apply received mutations in their own per-step
+        // transactions. Running them inside `mutateGraph`'s write transaction would
+        // hold the DB connection across a network round-trip and deadlock a nested
+        // apply on single-connection SQLite. They still run owner-signed through
+        // `mutateGraph`'s authorization path — only the outer transaction is
+        // dropped, and their local writes autocommit per step (each step is
+        // idempotent, so a partial run is retry-safe).
+        nonTransactionalMutationFields: [
+            'connectPeer',
+            'syncPeer',
+            'sharePeerGroup',
+            // Runs the same designation as `sharePeerGroup` — every step awaits a
+            // control-request settle — and then awaits its own Add commit.
+            'admitJoinRequest',
+            // The mirror of `admitJoinRequest`, and network I/O for the same reason:
+            // it calls `setCircleSync` per circle, which pushes `group/push-control`
+            // over a live peer connection. Latent while the offline CLI join holds no
+            // connection — that arm iterates an empty list — and a deadlock the first
+            // time a joiner completes with one held.
+            'completeJoin',
+            'joinPeerGroup',
+            'setCircleSync',
+            // Waits for its Add commit to land. The lane reads the group's handle on
+            // the registry's own connection, so holding a write transaction across
+            // that wait deadlocks single-connection SQLite.
+            'requestInviteToGroup'
+        ],
         resolvers: {
             queryFields: {
                 groups: async (_source, _args, context)=>{
@@ -393,6 +805,18 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                 circles: async (_source, args, context)=>{
                     return await requireP2P(context).group.listCircles(args.groupID);
                 },
+                peerDevices: async (_source, args, context)=>{
+                    return await requireP2P(context).sync.listPeerDevices(args.groupID);
+                },
+                circleSync: async (_source, args, context)=>{
+                    return await requireP2P(context).peer.listCircleSyncStates(args.groupID);
+                },
+                catalogs: async (_source, args, context)=>{
+                    const active = args.active;
+                    return await requireP2P(context).group.listStoredCatalogs(active != null ? {
+                        active
+                    } : undefined);
+                },
                 hubs: async (_source, _args, context)=>{
                     return await requireP2P(context).hub.list();
                 },
@@ -410,8 +834,8 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                     };
                 },
                 // INERT: always reports `healthy` — nothing signals the monitor. Live
-                // scaffolding for epoch-stale recovery; see
-                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                // scaffolding for epoch-stale recovery, kept so the surface exists once
+                // something drives it.
                 groupHealth: (_source, args, context)=>{
                     const groupID = args.groupID;
                     const { state, lastTransitionAt } = requireP2P(context).hub.getGroupHealth(groupID);
@@ -421,6 +845,10 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         lastTransitionAt: lastTransitionAt == null ? null : new Date(lastTransitionAt).toISOString()
                     };
                 },
+                controlRequests: async (_source, args, context)=>{
+                    const requests = await requireP2P(context).group.listControlRequests(args.groupID);
+                    return requests.map(toControlRequestSDL);
+                },
                 ownDelegationTokens: async (_source, args, context)=>{
                     const viewerDID = context.getViewer();
                     if (viewerDID == null || context.p2p == null) {
@@ -447,6 +875,83 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                 }
             },
             mutationFields: {
+                connectPeer: async (_source, args, context)=>{
+                    const peer = await requireP2P(context).peer.connect(args.url);
+                    return {
+                        peer
+                    };
+                },
+                sharePeerGroup: async (_source, args, context)=>{
+                    const send = args.send;
+                    const receive = args.receive;
+                    return await requireP2P(context).peer.sharePeerGroup({
+                        peerDID: args.peerDID,
+                        groupID: args.groupID ?? null,
+                        name: args.name ?? null,
+                        // No `send` = no access legs (plumbing only); the leg exists only from
+                        // this explicit user selection. `receive.activate` opts the sharer into
+                        // pulling the share scope (default off).
+                        sendModels: send?.models ?? null,
+                        receiveActivate: receive?.activate ?? false,
+                        // Model-default rows go through the engine's owner-signed executor so
+                        // `engine:access-default:set` fires and broadcast/invite seeding stay
+                        // consistent — the same path the `setModelAccessDefaults` mutation uses.
+                        setReadDefaultForCircle: async (modelID, circleID)=>{
+                            await context.executeSetModelAccessDefaults({
+                                modelID,
+                                permissionType: 'read',
+                                accessLevel: 'restricted',
+                                allowedDIDs: null,
+                                allowedCircles: [
+                                    circleID
+                                ],
+                                allowedGroups: null
+                            });
+                        }
+                    });
+                },
+                admitJoinRequest: async (_source, args, context)=>{
+                    const send = args.send;
+                    const receive = args.receive;
+                    return await requireP2P(context).peer.admitJoinRequest({
+                        groupID: args.groupID,
+                        joinRequest: args.joinRequest,
+                        sendModels: send?.models ?? null,
+                        receiveActivate: receive?.activate ?? false,
+                        // Same owner-signed executor `sharePeerGroup` binds, so the rows this
+                        // designation writes are indistinguishable from a connected share's.
+                        setReadDefaultForCircle: async (modelID, circleID)=>{
+                            await context.executeSetModelAccessDefaults({
+                                modelID,
+                                permissionType: 'read',
+                                accessLevel: 'restricted',
+                                allowedDIDs: null,
+                                allowedCircles: [
+                                    circleID
+                                ],
+                                allowedGroups: null
+                            });
+                        }
+                    });
+                },
+                joinPeerGroup: async (_source, args, context)=>{
+                    return await requireP2P(context).peer.joinPeerGroup({
+                        peerDID: args.peerDID,
+                        groupID: args.groupID
+                    });
+                },
+                setCircleSync: async (_source, args, context)=>{
+                    const share = args.share;
+                    return await requireP2P(context).peer.setCircleSync({
+                        circleID: args.circleID,
+                        pull: args.pull ?? null,
+                        share: share ?? null,
+                        ...accessDefaultExecutors(context)
+                    });
+                },
+                syncPeer: async (_source, args, context)=>{
+                    return await requireP2P(context).sync.syncPeer(args.groupID, args.peerDID);
+                },
                 createGroup: async (_source, args, context)=>{
                     const input = args.input;
                     const group = await requireP2P(context).group.create(input);
@@ -454,18 +959,36 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         group
                     };
                 },
-                addGroupMember: async (_source, args, context)=>{
-                    return await requireP2P(context).group.addMember(args.groupID, args.memberDID, args.role);
-                },
-                createCircle: async (_source, args, context)=>{
-                    return await requireP2P(context).group.createCircle({
-                        groupID: args.groupID,
-                        name: args.name,
-                        description: args.description
+                requestCreateCircle: async (_source, args, context)=>{
+                    const input = args.input;
+                    // The context method gates again for callers that reach it directly.
+                    //
+                    // Returns `pending`, not awaited: the commit lane runs on the outermost
+                    // commit, after this transaction closes.
+                    return await gatedTransaction('requestCreateCircle', ()=>requireP2P(context).group.requireAdmin(input.groupID, 'create a circle'), async ()=>{
+                        // Only the three public fields are forwarded: `circleID` is an
+                        // internal affordance for a caller that derives it, and letting a
+                        // client name it would merge two admins' circles under one subject.
+                        const { request, circleID } = await requireP2P(context).group.requestCreateCircle({
+                            groupID: input.groupID,
+                            name: input.name,
+                            description: input.description
+                        });
+                        return {
+                            request: toControlRequestSDL(request),
+                            circleID
+                        };
                     });
                 },
-                addCircleMember: async (_source, args, context)=>{
-                    return await requireP2P(context).group.addCircleMember(args.circleID, args.memberDID, args.role);
+                requestAddCircleMember: async (_source, args, context)=>{
+                    const input = args.input;
+                    // The group is reached through the circle, so the gate resolves it first.
+                    return await gatedTransaction('requestAddCircleMember', ()=>requireP2P(context).group.requireCircleAdmin(input.circleID, 'add a circle member'), async ()=>{
+                        const request = await requireP2P(context).group.requestAddCircleMember(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
                 createCatalog: async (_source, args, context)=>{
                     return await requireP2P(context).group.createCatalog({
@@ -474,15 +997,17 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         filterCriteria: args.filterCriteria
                     });
                 },
-                inviteToGroup: async (_source, args, context)=>{
-                    // invite advances the MLS ratchet and writes the local roster: any
-                    // throw must roll back the whole transaction so the eagerly-swapped
-                    // MLS epoch can never outlive a failed roster write.
-                    try {
-                        return await requireP2P(context).group.invite(args.groupID, args.joinRequest, args.grants, args.revocations);
-                    } catch (error) {
-                        failTransactionFatal('inviteToGroup', error);
-                    }
+                requestInviteToGroup: async (_source, args, context)=>{
+                    const input = args.input;
+                    // No rollback wrapper: this field is non-transactional, so there is no
+                    // outer write transaction to undo. It cannot be transactional — it
+                    // waits for the commit lane, and the lane's own reads need the
+                    // connection a write transaction would be holding.
+                    const result = await requireP2P(context).group.requestInvite(input);
+                    return {
+                        ...result,
+                        request: toControlRequestSDL(result.request)
+                    };
                 },
                 joinGroup: async (_source, args, context)=>{
                     return await requireP2P(context).group.join(args.invitePayload, args.joinRequestPayload);
@@ -491,7 +1016,36 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                     return await requireP2P(context).join.prepareRequest();
                 },
                 completeJoin: async (_source, args, context)=>{
-                    return await requireP2P(context).join.complete(args.invitePayload);
+                    const p2p = requireP2P(context);
+                    const result = await p2p.join.complete(args.invitePayload);
+                    const send = args.send;
+                    const receive = args.receive;
+                    const groupID = result.group?.id;
+                    if (groupID == null || send == null && receive == null) {
+                        return result;
+                    }
+                    // Every circle this device now reaches in the joined group. It joined a
+                    // moment ago, so those are the circles the invite seeded and no others
+                    // — deriving the scope from the invite payload would say the same thing
+                    // through a second reading of it.
+                    // Only circles carrying a catalog. A circle without one is not a scope:
+                    // `pull` has nothing to activate and a read default naming it is granted
+                    // to a set no catalog will ever ask for — the pair reads as configured
+                    // and moves nothing, which is the failure this argument exists to close.
+                    const circles = (await p2p.peer.listCircleSyncStates(groupID)).filter((circle)=>circle.catalogIDs.length > 0);
+                    if (circles.length === 0) {
+                        throw new Error('completeJoin: the invite designated no circle to share into — the admitting device admitted without `send`, so this pair can move nothing');
+                    }
+                    const executors = accessDefaultExecutors(context);
+                    for (const circle of circles){
+                        await p2p.peer.setCircleSync({
+                            circleID: circle.id,
+                            pull: receive?.activate ?? null,
+                            share: send ?? null,
+                            ...executors
+                        });
+                    }
+                    return result;
                 },
                 leaveGroup: async (_source, args, context)=>{
                     // leave tears down the MLS handle and emits a leave event: any throw
@@ -502,64 +1056,100 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         failTransactionFatal('leaveGroup', error);
                     }
                 },
-                removeGroupMember: async (_source, args, context)=>{
-                    // removeMember advances the MLS ratchet and tombstones the removed
-                    // member: any throw must roll back so a removed member can never be
-                    // left untombstoned (and still writable) after a partial commit.
-                    try {
-                        return await requireP2P(context).group.removeMember(args.groupID, args.memberDID);
-                    } catch (error) {
-                        failTransactionFatal('removeGroupMember', error);
-                    }
+                requestRemoveGroupMember: async (_source, args, context)=>{
+                    const input = args.input;
+                    // This transaction owns only the request row — the MLS advance, the roster
+                    // tombstone and the demotion belong to the accepted commit — so a throw
+                    // must roll it back: a queued request no lane settles is `pending` forever.
+                    // Returns `pending`, not awaited: the commit lane runs on the outermost
+                    // commit, after this transaction closes.
+                    return await gatedTransaction('requestRemoveGroupMember', ()=>requireP2P(context).group.requireAdmin(input.groupID, 'remove a member'), async ()=>{
+                        const request = await requireP2P(context).group.requestRemoveMember(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
-                setMemberRole: async (_source, args, context)=>{
+                requestSetMemberRole: async (_source, args, context)=>{
                     const input = args.input;
-                    // setMemberRole appends a ledger entry and reprojects the admin
-                    // overlay: any throw must roll back so the durable ledger and the
-                    // projected role column can never diverge across a partial commit.
-                    try {
-                        const member = await requireP2P(context).group.setMemberRole(input);
+                    // The entry and the request that reports it are written in ONE transaction,
+                    // so neither can outlive the other's rollback.
+                    // Returns `pending`, not awaited: the commit lane runs on the outermost
+                    // commit, after this transaction closes.
+                    //
+                    return await gatedTransaction('requestSetMemberRole', ()=>requireP2P(context).group.requireAdmin(input.groupID, 'set member roles'), async ()=>{
+                        const request = await requireP2P(context).group.requestSetMemberRole(input);
                         return {
-                            member
+                            request: toControlRequestSDL(request)
                         };
-                    } catch (error) {
-                        failTransactionFatal('setMemberRole', error);
-                    }
+                    });
                 },
                 updateCatalog: async (_source, args, context)=>{
                     const input = args.input;
                     return await requireP2P(context).group.updateCatalog(input);
                 },
-                updateGroup: async (_source, args, context)=>{
+                activateCatalogSync: async (_source, args, context)=>{
+                    return await requireP2P(context).group.activateCatalogSync(args.catalogID);
+                },
+                deactivateCatalogSync: async (_source, args, context)=>{
+                    return await requireP2P(context).group.deactivateCatalogSync(args.catalogID);
+                },
+                requestUpdateGroup: async (_source, args, context)=>{
                     const input = args.input;
-                    const group = await requireP2P(context).group.update(input);
-                    return {
-                        group
-                    };
+                    // The context method gates again, ahead of its own no-op check, so a
+                    // caller with no authority is refused rather than told NO_OP.
+                    //
+                    // Nothing is appended to the ledger here — the fold off the enacted commit
+                    // is the only writer — so a throw must roll back the request row.
+                    // Returns `pending`, not awaited: the commit lane runs on the outermost
+                    // commit, after this transaction closes.
+                    //
+                    return await gatedTransaction('requestUpdateGroup', ()=>requireP2P(context).group.requireAdmin(input.groupID, 'update a group'), async ()=>{
+                        const request = await requireP2P(context).group.requestUpdate(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
-                updateCircle: async (_source, args, context)=>{
+                requestUpdateCircle: async (_source, args, context)=>{
                     const input = args.input;
-                    const circle = await requireP2P(context).group.updateCircle(input);
-                    return {
-                        circle
-                    };
+                    // The gate runs ahead of the context method's own no-op check, so a
+                    // caller with no authority is refused rather than told NO_OP.
+                    return await gatedTransaction('requestUpdateCircle', ()=>requireP2P(context).group.requireCircleAdmin(input.circleID, 'update a circle'), async ()=>{
+                        const request = await requireP2P(context).group.requestUpdateCircle(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
                 deleteCatalog: async (_source, args, context)=>{
                     return await requireP2P(context).group.deleteCatalog(args.catalogID);
                 },
-                deleteCircle: async (_source, args, context)=>{
-                    return await requireP2P(context).group.deleteCircle(args.circleID);
+                requestDeleteCircle: async (_source, args, context)=>{
+                    const input = args.input;
+                    // The context method gates again for callers that reach it directly.
+                    //
+                    // Returns `pending`, not awaited: the commit lane runs on the outermost
+                    // commit, after this transaction closes.
+                    //
+                    return await gatedTransaction('requestDeleteCircle', ()=>requireP2P(context).group.requireCircleAdmin(input.circleID, 'delete a circle'), async ()=>{
+                        const request = await requireP2P(context).group.requestDeleteCircle(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
-                removeCircleMember: async (_source, args, context)=>{
-                    // removeCircleMember appends a tombstone ledger entry and reprojects
-                    // the circle-member overlay: any throw must roll back so the durable
-                    // ledger and the projected row can never diverge across a partial
-                    // commit.
-                    try {
-                        return await requireP2P(context).group.removeCircleMember(args.circleID, args.memberDID);
-                    } catch (error) {
-                        failTransactionFatal('removeCircleMember', error);
-                    }
+                requestRemoveCircleMember: async (_source, args, context)=>{
+                    const input = args.input;
+                    // The context method gates again for direct callers; the entry plus
+                    // the request that reports its outcome are written in one transaction,
+                    // so any throw rolls back both.
+                    return await gatedTransaction('requestRemoveCircleMember', ()=>requireP2P(context).group.requireCircleAdmin(input.circleID, 'remove a circle member'), async ()=>{
+                        const request = await requireP2P(context).group.requestRemoveCircleMember(input);
+                        return {
+                            request: toControlRequestSDL(request)
+                        };
+                    });
                 },
                 grantWriteCapability: async (_source, args, context)=>{
                     return await requireP2P(context).group.grantWriteCapability({
@@ -577,13 +1167,7 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                 addSyncPeer: async (_source, args, context)=>{
                     await requireP2P(context).sync.addPeer({
                         peerDID: args.peerDID,
-                        endpoint: args.endpoint,
-                        mode: args.mode ?? 'on-demand',
-                        allowedUsers: {
-                            all: true
-                        },
-                        priority: args.priority ?? '0',
-                        trustLevel: args.trustLevel ?? 'trusted'
+                        endpoint: args.endpoint
                     });
                     return true;
                 },
@@ -616,11 +1200,20 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         groupID: args.groupID
                     });
                 },
-                // INERT: `getGroupHealth` always returns `healthy` (nothing signals the
-                // monitor), so the kickoff branch below is currently unreachable and
-                // `hub.rejoinGroup` terminates in the deferred `recovery-failed` stub.
-                // Reserved for epoch-stale recovery; see
-                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                // Takes the GLOBAL id and decodes it, unlike `Connector`'s local-key
+                // convention: a client only ever holds `ControlRequest.id`, and that is
+                // the global one. The `id` type-field and this decode are the only
+                // translators between the two.
+                ackControlRequest: async (_source, args, context)=>{
+                    const localID = PluginNodeID.fromString(args.id).localID;
+                    await requireP2P(context).group.ackControlRequest(localID);
+                    return true;
+                },
+                // `hub.rejoinGroup` genuinely recovers through the rendezvous now, but
+                // this kickoff branch stays unreachable: `getGroupHealth` always returns
+                // `healthy` because nothing signals the monitor yet, so `state` never
+                // leaves `healthy`. Wiring the auto-detection that would fire this is
+                // separate; see docs/agents/plans/backlog/recovery-rendezvous-transport.md.
                 rejoinGroup: (_source, args, context)=>{
                     const groupID = args.groupID;
                     const hub = requireP2P(context).hub;
@@ -649,13 +1242,54 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                     hubs: async (source, _args, context)=>{
                         const group = source;
                         return await requireP2P(context).hub.listByGroup(group.id);
+                    },
+                    // Reads the viewer's membership row through the same store call the
+                    // admin gate makes, so the answer this field gives and the answer a
+                    // refused mutation gives can never come apart. An unauthenticated
+                    // request has no membership row to be an admin on, so it reads false
+                    // rather than failing.
+                    viewerIsAdmin: async (source, _args, context)=>{
+                        const viewerDID = context.getViewer();
+                        if (viewerDID == null) {
+                            return false;
+                        }
+                        const group = source;
+                        return await requireP2P(context).group.isAdmin(group.id, viewerDID);
+                    },
+                    // Same membership rows, same liveness boundary as `viewerIsAdmin`: a
+                    // removed member is not listed, and a DID carrying a role without a
+                    // membership row cannot appear at all.
+                    admins: async (source, _args, context)=>{
+                        const group = source;
+                        const members = await requireP2P(context).group.listMembers(group.id);
+                        return members.filter((m)=>m.role === 'admin').map((m)=>m.memberDID);
                     }
                 },
+                PeerGroupMember: {
+                    // A DID string is all `AccountNode` needs: the shared node fetcher
+                    // returns a `did:` id unchanged and types it as an account.
+                    account: (source)=>source.memberDID
+                },
                 PeerHub: {
                     groups: async (source, _args, context)=>{
                         const hub = source;
                         return await requireP2P(context).hub.listGroups(hub.id);
                     }
+                },
+                ControlRequest: {
+                    id: (source)=>{
+                        const request = source;
+                        return PluginNodeID.create('p2p', 'ControlRequest', request.id).toString();
+                    }
+                }
+            },
+            nodeResolvers: {
+                ControlRequest: {
+                    resolve: async (localID, context)=>{
+                        const ctx = context;
+                        const request = await requireP2P(ctx).group.getControlRequest(localID);
+                        return request == null ? null : toControlRequestSDL(request);
+                    }
                 }
             },
             subscriptionFields: {
@@ -679,6 +1313,10 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                     resolve: (member)=>member,
                     subscribe: (_src, args)=>createFilteredGenerator(emitter, 'groupMemberLeft', (d)=>d.groupID === args.groupID)
                 },
+                groupMemberRoleChanged: {
+                    resolve: (member)=>member,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'groupMemberRoleChanged', (d)=>d.groupID === args.groupID)
+                },
                 circleCreated: {
                     resolve: (circle)=>circle,
                     subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleCreated', (d)=>d.groupID === args.groupID)
@@ -725,9 +1363,45 @@ export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-s
                         return createFilteredGenerator(emitter, 'delegationTokenRevoked', (data)=>data.audience === viewerDID);
                     }
                 },
+                syncEvents: {
+                    resolve: (event)=>{
+                        const syncEvent = event;
+                        return {
+                            type: syncEvent.type,
+                            peerID: syncEvent.peerID,
+                            documentID: syncEvent.documentID ?? null,
+                            timestamp: syncEvent.timestamp,
+                            error: syncEvent.error ?? null
+                        };
+                    },
+                    subscribe: (_src, args)=>{
+                        const peerDID = args.peerDID;
+                        return syncManager.subscribeEvents(peerDID == null ? undefined : (event)=>event.peerID === peerDID);
+                    }
+                },
+                controlRequestSettled: {
+                    resolve: (data)=>toControlRequestSDL(data),
+                    subscribe: (_src, args, context)=>{
+                        const globalRequestID = args.requestID;
+                        if (globalRequestID != null) {
+                            // The client holds the global id the enqueuing payload returned;
+                            // the row and the emitted event carry the local one.
+                            const requestID = PluginNodeID.fromString(globalRequestID).localID;
+                            // The stream is opened HERE, synchronously, before the generator
+                            // body below ever reads the row: a settle landing between the two
+                            // is queued by the listener, so there is no window where an
+                            // outcome is neither in the row nor in the stream. A settle that
+                            // already happened is only in the row, which is why the read has
+                            // to happen at all.
+                            const stream = createFilteredGenerator(emitter, 'controlRequestSettled', (d)=>d.id === requestID);
+                            return watchOneControlRequest(stream, ()=>requireP2P(context).group.getControlRequest(requestID));
+                        }
+                        const groupID = args.groupID;
+                        return createFilteredGenerator(emitter, 'controlRequestSettled', groupID == null ? undefined : (d)=>d.groupID === groupID);
+                    }
+                },
                 // INERT: this subscription can never fire — `groupHealthChanged` has no
-                // live producer. Reserved for epoch-stale recovery; see
-                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                // live producer. Reserved for epoch-stale recovery.
                 groupHealthChanged: {
                     resolve: (data)=>{
                         const event = data;