Reviewed bulk member-role changes

Bulk member-role changes have no immediate-call path and do not inherit single-member authority. Set capabilities.bulkMemberRoleChanges: true, list every eligible guild in scopes.bulkMemberRoleGuildIds, list every eligible role in scopes.bulkMemberRoleIds, keep every ineligible operator, service account, and break-glass identity in scopes.protectedUserIds, and select the member-roles toolset. Both batch allowlists must be nonempty, the batch guild allowlist must stay inside readScope.guildIds when that outer allowlist exists, and the pinned application and bot IDs are required. Enabling a batch guild adds only that exact guild to the private nonprivileged Gateway layout-evidence union; it does not enable the public event feed. Ordinary memberRoleGuildIds and memberRoleIds cannot substitute for either batch allowlist.

Each request selects one add or remove action, one exact guild, one exact role, a Discord audit-log reason, one unique parent operation key, and 2-25 unique exact member IDs. The service canonicalizes the target set by numeric snowflake order and binds its SHA-256 digest. It rejects malformed, duplicate, protected, or special targets before any write and never accepts display names, fuzzy matching, an all-members selector, a role-array replacement, or mixed per-target actions.

1. Call plan_bulk_member_role_change with the complete exact request.
2. Review the verified application and bot identities; exact guild, role, and canonical member set; every member's current and proposed role sets; per-target hierarchy, named guild-permission delta, changed direct-channel decisions, and high-risk gains; the common evidence and target-set digests; completed child checkpoints; exact execution frontier; audit reason; hashed operation keys; warnings; verification boundary; and keyed plan digest.
3. Call execute_bulk_member_role_change with the identical request and digest.
4. Approve the signed MCP confirmation only if every target, role transition, permission impact, checkpoint, warning, reason, hash, frontier, and digest remains intended.
5. If execution returns paused, call the planner again with the original request and parent key, review the fresh remaining frontier and every verified checkpoint, then perform a separately approved execution with the new digest. Never reuse the key for a different request or resume without fresh review.

Planning reuses the complete single-member member-role analyzer under an unforgeable internal batch authority. Every target must independently pass protected-member, special-member, role-management, hierarchy, role-subset, unknown-bit, complete channel-evidence, and bounded permission-impact checks. Reads run only in bounded groups. Every target plan must agree on one keyed common-evidence digest covering the pinned identities, guild, bot roles and permissions, complete role inventory, direct-channel layout, and trusted channel snapshots. Mixed evidence fails the whole plan instead of combining observations from different guild states. The plan exposes only the targets that still need writes as the canonical execution frontier.

The parent request digest binds the exact normalized request, pinned identities, target-set digest, and parent operation-key hash. It is a domain-separated HMAC keyed by the caller-retained parent operation key, so the binding survives a process restart without persisting that raw key. The aggregate plan digest remains process-bound and additionally binds common evidence, every target state and live child plan digest, content-free child and parent receipts, the execution frontier, and the no-retry verification boundary; every restart therefore requires a new plan and approval. A completed child checkpoint is accepted only when its derived one-shot key has a matching terminal receipt with exact guild and role IDs plus verification: match, and a fresh inspection proves the requested role state is still present or absent. A stale, failed, uncertain, mismatched, or drifting checkpoint blocks the batch.

Execution rechecks the aggregate plan before coordination, durably claims the guild member collection, selected role, and every exact member across connector processes sharing the activity-state root, then rechecks the plan inside that claim. It reserves one pending content-free parent receipt before the first mutation. Remaining targets execute sequentially in canonical user-ID order through the existing single-member workflow: each uses a derived one-shot child key, pending content-free activity, one non-retried exact role PUT or DELETE, and exact member readback. The first failed, uncertain, drifting, or otherwise unsettled child stops the frontier. No later target is attempted and no completed target is rolled back.

A failure with a terminal child receipt makes the parent terminal failed or uncertain. A failure before an unsettled child receipt, a verified child checkpoint whose result could not be reported, a post-frontier evidence interruption, or remaining fresh work returns paused with exact remaining IDs. A verified pause releases the facade's durable batch claim so the original request can be freshly reviewed and resumed. Final checkpoint drift makes the parent terminal uncertain, and terminal uncertainty retains coordination for operator review. An abrupt process interruption leaves its pending claim review-required; inspect exact Discord state and the audit log, resolve the claim explicitly, then build a fresh plan before any resume. When no write remains, planning and execution complete without interactive confirmation or mutation. Completion requires fresh validation of every child checkpoint before the parent receipt becomes completed.

The parent receipt contains only the exact guild and completed role IDs, parent request digest, parent operation-key hash, timestamps, fixed status and verification, activity ID, and sanitized error category. Child activity and receipts retain only the existing single-member content-free fields. Member usernames, guild and role names, role sets, permission and hierarchy evidence, channel IDs and names, audit reasons, raw parent or child keys, Discord payloads, and transport causes never enter persistent records or telemetry. Use review_bulk_member_role_change for a locally validated plan-only prompt, and inspect exact members plus the Discord audit log before resolving any terminal uncertainty. See Discord's add guild member role and remove guild member role contracts.

Canonical source: docs/reference.md