Reviewed exact-channel metadata changes

get_channel and discord://channels/{channelId} read one exact permitted guild channel under the ordinary read boundary. The REST response is immediately reduced to ID, guild ID, type, name, topic, NSFW state, slowmode, default thread slowmode, default auto-archive duration, bitrate, user limit, RTC region, semantic video-quality mode, parent ID, position, overwrite count, applicable fields, and an unknown-field count. Non-applicable fields are returned as null. The projection may contain untrusted channel text or an RTC region ID for transient review, but the connector never caches, journals, persists, or returns the raw payload or complete permission overwrites through this read surface.

Metadata mutation has no immediate-call path. Set capabilities.channelMetadataChanges: true and list every eligible direct guild channel in scopes.channelMetadataIds. This exact mutation allowlist is independent of parent scope and must be a subset of readScope.channelIds when that read allowlist exists. Threads are never eligible. Grant Manage Channels and retain View Channel only on the selected targets, plus Connect on selected voice or Stage channels because Discord otherwise treats channel-management authority there as ineffective. Guild ownership and Administrator are recognized when Discord's complete evidence proves them, but neither is the recommended setup.

The workflow accepts an exact partial intent and preserves every omitted field from fresh state. Name is supported for text, voice, category, announcement, Stage, forum, and media channels. Topic is supported for text and announcement channels up to 1024 characters and forum or media channels up to 4096 characters; explicit null or an empty input clears it. NSFW is supported for text, voice, announcement, Stage, forum, and media channels. Slowmode is supported for text, voice, Stage, forum, and media channels from 0 through 21600 seconds. Default thread slowmode is supported for text, forum, and media channels over the same range. Default auto-archive duration is supported for text, announcement, forum, and media channels at 60, 1440, 4320, or 10080 minutes. Voice and Stage channels additionally support bitrate, user limit, nullable RTC region, and semantic automatic or full video-quality mode. Type-inapplicable, malformed, unknown, empty, or over-broad requests fail before planning.

list_voice_regions and discord://voice/regions expose the complete bounded global inventory. list_guild_voice_regions and discord://guilds/{guildId}/voice-regions expose the inventory Discord reports for one exact permitted guild, including guild-specific and VIP choices. Both projections retain only ID, transient untrusted name, optimal, deprecated, custom, and unknown-field count. Explicit non-null region changes require the selected ID to appear exactly once and not be deprecated in a fresh guild inventory; null restores Discord's automatic selection without fetching unrelated inventory. Voice bitrate planning binds the guild's fresh premium tier and VIP_REGIONS feature to the documented 96, 128, 256, or 384 kbps ceiling, while Stage channels remain capped at 64 kbps. Voice user limits are capped at 99 and Stage user limits at 10000.

Deletion, type conversion, category or parent moves, position changes, permission-overwrite replacement, forum-tag replacement, flags, and thread edits remain outside this workflow. Those operations have different authority, blast radius, reversibility, and concurrency semantics and require separate policy rather than hidden passthrough fields.

plan_channel_metadata_change verifies the application and bot identities, exact guild and owner, bot membership, complete role inventory, complete supported current channel metadata and overwrite evidence, field applicability, local bounds, effective VIEW_CHANNEL and MANAGE_CHANNELS, type-required CONNECT for voice and Stage targets, and any guild-owner or administrator bypass. Voice plans also bind fresh boost and region evidence, expose active-call, bandwidth, occupancy, and automatic-selection warnings, and reject unavailable or deprecated explicit regions. It computes the exact desired state by changing only requested fields, reports no-ops explicitly, and binds the complete projected evidence, current and desired metadata, audit reason, requested fields, local limits, voice-setting evidence, and domain-separated operation-key hash into a process-keyed plan digest. Names, topics, region names, role names, and audit reasons appear only in the transient plan and never in durable records.

execute_channel_metadata_change rebuilds that plan before confirmation, binds signed elicitation to the exact request and digest, requires host write approval, rebuilds the plan again, and skips every write-side gate for an already-current no-op. A real change atomically reserves the one-shot key, writes a pending content-free activity entry, serializes the exact channel inside the process, issues one non-retried PATCH containing only changed fields and an encoded Discord audit reason, validates the exact returned projection, and performs a complete fresh GET. The production facade also acquires durable exact channel and guild channel-collection claims, so connector processes sharing the activity-state root exclude overlapping channel-topology changes. A response or readback mismatch returns completed-with-drift with the observed strict projection. A known pre-response Discord client error is failed; a transport error, server error, malformed response, post-response failure, or readback failure is uncertain and potentially completed. Reserved keys are never retried, rolled back, or compensated, and uncertainty retains the durable claims for operator review.

Direct channel-metadata service instances retain same-channel serialization as defense in depth. Cross-process safety is supplied by the production facade's durable claims described above. The Discord Modify Channel contract defines the remote field and permission behavior; the connector intentionally exposes a smaller reviewed subset.

Canonical source: docs/reference.md