Reviewed exact relative channel placement

Channel-order audit and changes are independent of ordinary channel reads, metadata changes, creation, scaffolds, forum tags, and permission overwrites. Set capabilities.channelOrderingAudit: true and list each eligible guild in scopes.channelOrderingGuildIds to enable audit_channel_order and discord://guilds/{guildId}/channel-order. The guild allowlist must remain inside the configured read-guild boundary. Enabling changes additionally requires capabilities.channelOrderingChanges: true. Audit adds its exact guild scope to the shared channel-completeness Gateway layout union. When the event feed and native Interactions are disabled, that union uses a layout-only connection with the nonprivileged GUILDS intent. Pinned application and bot identities are mandatory.

The Gateway layout retains only channel ID, documented direct-channel type, nonnegative raw position, nullable parent ID, and the explicit CHANNEL_OBFUSCATED bit. It never retains names, topics, overwrites, raw dispatches, or other channel metadata. Before November 16, 2026, Discord's HTTP guild-channel response can contain the complete inventory while Gateway obfuscation remains opt-in. Beginning November 16, 2026, Discord documents that HTTP omits channels the bot cannot view and Gateway supplies their topology with obfuscated metadata. The audit therefore accepts either a complete legacy HTTP inventory or the exact non-obfuscated Gateway subset, based on coherent evidence rather than the local clock. If Gateway marks a channel obfuscated while HTTP still returns it, the connector discards that HTTP metadata. See Discord's obfuscated-channel contract and channel-obfuscation migration notice.

audit_channel_order takes one exact guild ID and returns canonical sortable groups plus verified application, bot, guild, layout revision, HTTP evidence mode, privacy, and authority evidence. Categories form one guild-level group. Text, announcement, forum, and media channels share a text-like family only within the same parent. Voice and Stage channels share a voice-like family only within the same parent. Each group sorts by ascending raw position and then ascending snowflake ID. Unsupported directory or future channel types remain visible as unsupported topology and block a real move when they are siblings at the target parent. Hidden channel metadata is never returned; an obfuscated entry carries only its exact topology fields.

Authority requires complete guild-level MANAGE_CHANNELS evidence or complete MANAGE_CHANNELS evidence through the visible parent category for every affected child group. Categories and top-level channels require guild-level authority because no parent-category overwrite can establish narrower authority. A cross-parent move additionally requires visible exact target metadata and complete VIEW_CHANNEL plus MANAGE_CHANNELS evidence on that target. An obfuscated target or anchor remains usable by exact ID for a same-parent reorder, and an obfuscated anchor can select a cross-parent destination when its parent authority is otherwise complete; an obfuscated target cannot be moved across parents. Incomplete roles, membership, overwrites, topology, IDs, types, positions, parent relationships, visibility subset, category capacity, or authority fail closed.

The change surface accepts exactly one target channel ID, one distinct anchor channel ID, above or below, a Discord audit-log reason, and a unique one-shot operation key. It expresses immediate relative placement in one sortable family. A same-parent anchor reorders the family; a different-parent anchor selects that exact category or guild root as the destination. The connector validates both parents, destination category capacity, source and destination group authority, target move authority, and exact overwrite preservation. Arbitrary numeric positions, names as targets, bulk caller payloads, arbitrary parent IDs, cross-family movement, permission synchronization, permission changes, flag changes, metadata changes, creation, deletion, retry, rollback, and reconciliation are unavailable.

1. Call plan_channel_order with the exact guild, target channel, anchor channel, placement, audit reason, and one-shot operation key.
2. Review the verified application, bot, guild, target, anchor, operation mode, source and destination parents, family, source and destination capacities, current and desired ranks, complete current and desired affected-group orders, full normalized position payload, affected channels, overwrite behavior, HTTP evidence mode, layout revision, source, destination, and target authority, privacy boundary, risks, warnings, operation-key hash, and keyed digest.
3. If the status is already-current, no confirmation, coordination claim, receipt, activity entry, subscription, or write is needed.
4. Call execute_channel_order with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact ID, parent, relative placement, capacity, rank, affected channel, normalized position, overwrite-preservation and authority fact, reason, risk, warning, operation-key hash, and digest remains intended.
6. Review the newer observed layout revision, complete matching layout, coherent HTTP readback, affected-channel evidence, activity ID, verification, and outcome before any follow-up.

Planning reads the Gateway layout immediately before and after one bounded concurrent HTTP evidence pass containing the guild, connector member, complete role inventory, and guild-channel inventory. Any layout revision or topology change during that pass fails closed. A real plan rejects an absent target or anchor, different sortable families, unsupported siblings at either affected parent, invalid parent topology, exhausted category capacity, missing group or target authority, and incoherent complete or visibility-bounded evidence. Same-parent placement computes one complete desired family order. Cross-parent placement computes the complete source group without the target and destination group with the target immediately above or below the anchor. Every affected group is normalized to sequential positions from zero, so the exact outbound payload is visible during review rather than delegated to Discord's tie handling.

The process-keyed digest binds the normalized request without the raw operation key, its domain-separated hash, verified identities, exact guild and owner, connector membership and permission evidence, complete roles, trusted HTTP metadata, HTTP evidence mode, the complete Gateway layout and revision, every canonical group order, target and anchor, source and destination parents and capacities, exact target overwrites, current and desired affected groups, expected topology, complete normalized position payload, impact, risks, and warnings. A connector restart invalidates the digest. The MCP adapter rebuilds the plan before confirmation, and the service rebuilds it immediately before durable coordination and reservation. Both require the exact same digest.

A real change durably claims the target, anchor, applicable source and destination parent categories, and whole guild channel collection, atomically reserves the one-shot key, and appends a pending content-free activity record. It subscribes to layout updates and verifies the baseline synchronously before marking mutation as started, then sends one non-retried PATCH containing every affected-group channel ID and normalized position plus the encoded audit reason. For a cross-parent move, only the target entry additionally carries the exact destination parent_id and literal lock_permissions: false. Discord returns an empty 204 response, so the connector accepts no body as proof. It waits for a strictly newer complete Gateway layout that matches the expected topology and every desired group, then reads a coherent HTTP inventory that preserves the exact target type, visibility class, and permission overwrites. Subscribing and arming before the write closes the fast-event race.

A known non-retriable Discord client rejection before acceptance can settle as failed. Transport ambiguity, Discord server errors, timeout, continuity loss, malformed or contradictory layout evidence, a newer layout that never reaches the complete reviewed state, an incoherent or overwrite-changing HTTP readback, or any failure after the mutation may have been accepted is uncertain. Direct service instances serialize and quarantine the whole guild channel collection after uncertainty. The production facade's durable collection claim additionally excludes overlapping channel ordering, metadata, creation, forum-tag, and scaffold work across connector processes sharing the activity-state root. The connector never retries, compensates, rolls back, or treats one evidence source as a substitute for the other.

Activity and operation records contain only exact guild, target, anchor, source parent, and destination parent IDs, relative placement, baseline and observed layout revisions, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. They never contain channel names, topics, layout inventories, positions, permission or overwrite evidence, audit reasons, raw operation keys, or raw Discord payloads. Discord's Modify Guild Channel Positions contract defines the remote 204, parent, no-sync, permission, and Channel Update behavior; the connector deliberately sends a stricter complete normalized affected-group payload and requires two-source verification.

Canonical source: docs/reference.md