Reviewed atomic channel cloning

Channel cloning has separate audit and change gates. Set capabilities.channelCloneAudit: true, list every eligible guild in scopes.channelCloneGuildIds, and list every eligible exact source in scopes.channelCloneSourceIds to enable planning. Enable capabilities.channelCloning: true only when reviewed mutation is needed. Both allowlists must remain inside ordinary read scope, and audit adds its exact guilds to the shared content-free channel-layout Gateway union. Pinned application and bot identities are mandatory.

The workflow clones one exact direct source into the same guild and same parent through one atomic Create Guild Channel request. It supports text, voice, category, announcement, Stage, forum, and media channels. It preserves exact type-applicable topics, age restrictions, slowmode, thread defaults, voice settings, supported flags, permission overwrites, forum and media tags, default reaction, tag sort order, and forum layout. The create endpoint limits every topic to 1024 characters even though forum and media channel objects can hold 4096, so a longer source fails closed instead of being truncated. An optional replacement name is the only requested semantic change. Unknown fields, unknown permission bits, unsupported flags, inapplicable non-neutral values, managed or application-owned channels, parented categories, threads, directory channels, and a media age restriction that the create endpoint cannot carry all fail closed.

Source position is deliberately omitted, so Discord chooses the new channel's default placement and may normalize raw positions. Verification instead proves that every pre-existing channel retains its type, parent, obfuscation state, and relative order inside every same-parent sortable family. Forum and media tag IDs cannot be preserved by channel creation; the connector strips those source-local IDs from the create request and returns an exact source-to-created tag ID mapping after readback. Messages, threads, pins, webhooks, followers, invites, live voice state, and every other child resource are excluded.

Planning combines one continuity-stable complete Gateway layout with a complete or exact visibility-bounded HTTP channel inventory. It requires one visible exact source, a complete role inventory and connector membership, source VIEW_CHANNEL, guild-level MANAGE_CHANNELS, complete overwrite targets, sufficient complete guild and parent capacity, the NEWS guild feature for announcement sources, voice bitrate within the observed guild boost tier, and every copied overwrite permission within the connector's effective guild permissions. Discord requires ADMINISTRATOR to create MANAGE_ROLES overwrites, so those sources remain unavailable under the recommended non-administrator deployment.

1. Call plan_channel_clone with the exact guild and source channel IDs, optional replacement name, Discord audit-log reason, and unique one-shot operation key.
2. Review the exact identities, source and parent, complete atomic payload, default placement, regenerated-tag warning, capacity, topology revision, HTTP evidence mode, authority, privacy boundary, risks, operation-key hash, and keyed digest.
3. Call execute_channel_clone with identical inputs plus the digest.
4. Approve the signed MCP confirmation only if every exact ID, payload field, omission, reason, risk, warning, operation-key hash, and digest remains intended.
5. Review the created channel ID, newer layout revision, exact tag ID mapping, activity ID, verification, and outcome before any follow-up.

The process-keyed digest binds the normalized intent without the raw operation key, verified identities, exact guild and source, complete source settings and overwrites, parent, guild feature and boost evidence, connector membership, complete roles, guild and source permissions, complete layout, HTTP evidence mode, capacity, audit reason, exact outbound payload, and domain-separated operation-key hash. The MCP adapter rebuilds the plan before confirmation, and the service rebuilds it before coordination and reservation. A connector restart invalidates the digest.

A real clone durably coordinates the exact source and whole guild channel collection, reserves the one-shot key, and appends pending content-free activity. It subscribes and synchronously arms a Gateway watch before one non-retried create request, validates the returned channel, requires a newer complete layout containing exactly one added matching channel, performs an exact channel GET plus complete guild-channel readback, proves source semantics and every existing relative order unchanged, and verifies any regenerated tag mapping. The pre-armed watch handles a Gateway event that arrives before the HTTP response.

A known non-rate-limited Discord 4xx refusal before an accepted response settles as failed. Transport ambiguity, rate limiting, server errors, timeout, continuity loss, malformed response, absent or contradictory evidence, source drift, existing-channel reorder, readback mismatch, or any other failure after the mutation starts is uncertain. Direct service instances quarantine that guild after uncertainty or terminal operation-record failure; durable collection claims retain the same cross-process exclusion when the production services share one activity-state root. The connector never retries, guesses, repositions, deletes, rolls back, or repairs the result automatically.

Activity and operation records contain only exact guild, source, and optional created channel IDs, channel type, baseline and observed revisions, plan and operation-key digests, timestamps, fixed outcomes, verification, activity ID, and sanitized error category. They never contain channel names, topics, tags, emoji, overwrite bits, layout inventories, audit reasons, raw operation keys, or raw Discord payloads. Discord's Create Guild Channel contract defines the remote type-specific fields and permission behavior.

Canonical source: docs/reference.md