Config design: model channels as rich objects instead of parallel keyed collections

[Aaronontheweb]

Problem

Channel configuration models a channel as a primary key smeared across parallel
collections, not as an object. One Slack channel C123 is expressed three ways:

• an entry in AllowedChannelIds: [ ... ] (the deny-by-default allow-list),
• an optional entry in ChannelAudiences: { "C123": "team" },
• an optional entry in MentionRequiredInThreadByChannel: { "C123": true }.

Each new per-channel knob adds another parallel map keyed by channel ID. The
collections can drift, and there is no single place that holds a channel and its
metadata. ChannelAudiences also overloads its key space with a special "dm"
entry for direct-message audience, which is not a channel at all.

Proposed model

Model a channel as a first-class object and stop keying parallel maps by channel ID.

"Slack": {
  "Channels": [
    { "Id": "C123", "Audience": "team",   "MentionRequiredInThread": true },
    { "Id": "C456", "Audience": "public" }
  ],
  "DirectMessages": { "Audience": "team" },   // replaces the "dm" pseudo-key
  "AllowedUserIds": ["U1"]                      // stays: a user allow-list, orthogonal to channels
}

• The Channels array membership replaces AllowedChannelIds (it becomes the allow-list).
• Audience per entry replaces ChannelAudiences[id].
• MentionRequiredInThread per entry replaces the map.
• The "dm" audience moves to a dedicated DirectMessages.Audience.
• The object becomes the extension point, so the next per-channel setting is a
  property, not a fourth parallel map.

Apply the same shape to all three connectors (Slack, Discord, Mattermost); they
are structurally identical.

Blast radius (about 25 non-test files)

• 3 options types ({Slack,Discord,Mattermost}ChannelOptions)
• 3 ACL policies (read the allow-list + audiences)
• AudienceResult.Resolve (the shared resolver, plus the "dm" case)
• 3 thread-history fetchers
• 3 target / destination resolvers
• Doctor (SlackAclDoctorCheck, DoctorFixService)
• About 6 TUI files (channels editor, wizard steps, config builder, dashboard)
• The JSON schema (3 sections)
• Tests for all of the above

Backwards-compatibility hazard (the hard part)

There is no config-file migration framework today:

• SchemaMigrator is SQLite-only. It runs versioned SQL against the sessions
  database and does nothing for the JSON config.
• SchemaFixResolver (what doctor --fix runs) does only leaf-level fixes:
  integer-to-enum coercion, insert-missing-default, and remove properties
  disallowed by additionalProperties: false. It cannot move data between
  shapes.

A naive schema swap is therefore destructive, not merely non-loading:

1. A live config still has AllowedChannelIds + ChannelAudiences (deployed,
   security-critical data).
2. The new schema no longer lists those keys, so additionalProperties: false
   flags them.
3. doctor --fix runs TryRemoveDisallowedProperties and deletes them,
   silently wiping the channel allow-list and audiences, while the new
   Channels array stays empty.

On a default-deny allow-list, auto-fix would quietly erase the operator's access
config.

Migration strategy (additive + lazy)

• Add Channels (and DirectMessages.Audience). Keep AllowedChannelIds /
  ChannelAudiences in the schema as deprecated but still valid, so
  doctor --fix never deletes them.
• Runtime prefers Channels; when it is absent, it composes the allow-list and
  audiences from the old keys. This is a bounded, documented compatibility read,
  not a silent degradation.
• The TUI writes the new shape and drops the old keys on the next save, so
  configs migrate as operators touch them.
• A later major version ships a one-shot mechanical migrator for stragglers and
  then removes the old keys from the schema.

Required proof (Automation Floor)

• Old-shape to new-shape round-trip tests.
• An ACL-equivalence test proving the allow-list and audience decisions are
  identical before and after migration.

Sequencing

Do this as its own OpenSpec change. The hard part is the backwards-compatible
migration above, not the C# refactor. The MentionRequiredInThread per-channel
setting should fold into this object model rather than ship as a separate map.

Related

• PR feat(channels): add MentionRequiredInThread — gate thread replies on @-mention #1783 (connector-wide MentionRequiredInThread bool, merged to dev; to be removed)
• PR feat(channels): per-channel MentionRequiredInThread with mention-triggered backfill #1798 (per-channel MentionRequiredInThread)
• Issue Channels: add MentionRequiredInThread flag — require @-mention to reply in active threads #1782

[Aaronontheweb]

UX decision: fold the channel detail leaf into the Channels & Permissions list

Design note for the netclaw config side of this work.

Decision

Remove the per-channel detail leaf (the EditAudience screen). Make the
Channels & Permissions list the single editor for a channel. One channel is
one row, and the row carries all of that channel's settings.

Why

The detail leaf edits only the audience, which the list already edits inline
with left/right. On dev the leaf added nothing the list could not do; it was
a richer re-presentation of one field. Its only unique function today is the
per-channel mention toggle. A rich channel object wants one channel on one page,
so the list row is the right home.

Interaction model

• left/right cycles the audience (unchanged).
• Space toggles the mention requirement.
• A description line under the list explains the selected row's current state.

This matches the existing DirectMessages screen idiom ("Space toggles DMs;
left/right changes the DM audience"), so it is a proven pattern, not a new one.
left/right arrows appear only on the audience field; the mention field is
arrow-free so the eye learns "arrows means left/right, arrow-free means Space."

Label

Use Require @mention with an On/Off value. The @ makes it read as a
Slack/Discord mention and avoids the singular/plural awkwardness of "mentions".

Description copy for the selected row:

• On: "the bot stays quiet in the thread until someone @mentions it, then reads
  everything since its last reply."
• Off: "the bot replies to every message in the thread (default)."

Mockup

+-- Slack - Channels & Permissions ------------------------------
|
|  > C01      Audience < Team   >      Require @mention: On
|    C02      Audience < Public >      Require @mention: Off
|    + Add channel
|    Done
|
|  Team - trusted internal channel.
|  Require @mention: the bot stays quiet in the thread until
|  someone @mentions it, then reads everything since its last reply.
|
|  Updated C01 - saved.
+----------------------------------------------------------------
  [up/down] Row  [left/right] Audience  [Space] Require @mention  [a] Add  [Del] Remove  [Esc] Back

Mechanics

• Delete BuildEditAudience, HandleEditAudienceKey, OpenSelectedChannelAudience,
  and the EditAudience value from ChannelsConfigScreen.
• Move the mention toggle into the ChannelPermissions list key handler (Space
  toggles the selected channel's mention requirement and autosaves; reuse the
  existing SetChannelMentionRequired view-model method).
• Enter no longer opens a leaf, so the list handler frees it.

Scope note

This TUI reorganization does not depend on the rich-object config model; it only
rearranges the existing per-channel data. Land it with this change so the detail
page and the object model are designed together, or pull it forward if the leaf
should go sooner.