T-HUB/docs/design/2026-10-09-chat-governance-design.md

# Chat Governance Design — Polls · Approval-Gated Posting · Forum Topics · Multi-Account Policies · Telegram Bot Control
*Design doc: 2026-10-09 · Codebase: `apps/api/src/live-chat/**`, `packages/connector-telegram/src`, `apps/api/src/publishing`, `apps/api/src/media-control`.*

---

## 0. Decision summary (the ten calls this design makes)

| # | Decision |
|---|---|
| D1 | **Polls are OURS, not Telegram's.** Ballots live in `poll_votes`; the Telegram card is an inline-keyboard *mirror* edited in place. Native `sendPoll` is allowed **only** for audience sentiment (≤600 s, anonymous, aggregate-only) and can never gate a post. Rationale: 600 s ceiling, anonymous-by-default, no voter roster API, no reopen (polls report §1). |
| D2 | **Chat-governance bot = grammY 1.46 gateway module** inside the API (`apps/api/src/chat-gov/`), webhook in prod (secret per binding), `@grammyjs/runner` long-poll in dev. Publishing *sends* continue to flow through the existing connector-telegram + Temporal pipeline — the gateway never bulk-posts. |
| D3 | **Forum topics are a binding registry, not a mirror of Telegram state.** Bot API has no list-topics → we persist `message_thread_id` at creation; enabling forum mode stays a human/MTProto runbook step (documented, no userbot in v1). |
| D4 | **Posting rules are data, evaluated at three gates (E1/E2/E3)** with precedence `topic > contentType > account > workspace`, whole-block replacement, compiled snapshot + `policy_version` pinned at save and at every decision. **E3 pre-dispatch re-check is mandatory.** |
| D5 | **Poll-pass NEVER side-channels a platform post.** Pass → `approve`-equivalent transition on a draft (system actor `system:chat-poll-gate`) → existing schedule/publish machinery → E3. Chat-originated posts are auto-materialized as drafts first. |
| D6 | **Chat commands map 1:1 onto existing `DirectorOperation`** (`take|cut|pst-select|lock|override|desired`); authorization reuses workspace RBAC permissions (`director.take`, `director.lock_program`, …) resolved from immutable Telegram numeric `from.id` → `chat_identities` → membership role. Chat is UX; the control plane stays the enforcement point. |
| D7 | **Destructive commands are confirmation-gated**: inline CONFIRM/ABORT, 30 s TTL, requester-only callback, dry-run diff echo, nonce; ephemeral `replace_callback_query_message` (Bot API 10.3) when available. |
| D8 | **Every account/destination evaluates its own policy.** One draft → N destination decision records; partial fan-out (A sent, B blocked) is a first-class outcome. |
| D9 | **Votes from ineligible users are stored, never counted** (GitLab pattern) and surfaced with `INELIGIBLE_ACTOR`; eligibility is re-read at close time. |
| D10 | **Anti-abuse reuses what exists**: `SendGovernors`/`TokenBucket` in front of every outbound mirror/ack, grammY throttler (30/s global, 1/s per chat, 20/min group) with `bypassThrottler` for acks, `update_id` dedupe, per-user per-command-class token bucket, and the existing `live_chat_requests` idempotency pattern for close→publish. |

---

## 1. Feature set

### 1a. Polls in bridged chats — configurable pass criteria

**Subject of a poll.** A poll gates a *thing*: a `draft` (existing DraftPost), a *chat post* (text/media composed via `/post` → materialized as a draft, D5), or nothing (free-standing sentiment/procedural vote). Polls are created from the web UI, the overlay, or `/post`+`/poll` in a bound chat.

**Pass criteria — compiled rule object** (stored on the poll at open; never re-resolved mid-flight):

```jsonc
{
  "version": 1,
  "mode": "quorum",                    // immediate | quorum | admin_only
  "arms": [
    { "kind": "admins",      "x": 2 },                       // x of workspace Admin/Owner set
    { "kind": "participants","x": 3, "of": "observed" }      // of: observed | eligible | none(count-only)
  ],
  "join": "all",                       // all (AND, default) | any (OR)
  "allowVeto": true,                   // one veto fails regardless of quorum
  "minDwellSeconds": 45,               // early close only when quorum ∧ dwell (anti-railroading)
  "timebox": { "duration": "PT2H", "onExpire": "reject" },   // approve | reject | escalateOwner
  "anonymity": "named",                // named | anonymous (never mixed silently)
  "allowSelfApproval": false,          // draft author's yes is stored, not counted
  "resetOnChange": true,               // draft edit ⇒ approvals reset, poll re-arms
  "dryRun": false                      // evaluate + log, never block/fire
}
```

- **admins arm**: eligibility = workspace membership role ∈ {Owner, Admin} (or `chat_identities.role_override` ≥ that) *evaluated at close time* (TOCTOU guard).
- **participants arm**: `of:observed` = distinct chat identities seen in the channel since `opens_at` (roster derived from `live_chat_messages` — we already own that table); `of:eligible` = explicit roster bound to the topic/channel; `of:none` = pure count.
- **mixed** = conjunctive arms (`join:"all"`), the GitHub count+code-owner shape; each arm keeps its own `x`.
- **State machine**: `open → passed | failed | vetoed | quorum_unreachable | cancelled`. `quorum_unreachable` fires eagerly when remaining eligible voters < needed (grey-the-card UI). Closed is terminal; a re-vote is a **new poll with `parent_poll_id`**.
- **Close events**: (1) quorum ∧ minDwell → early close; (2) `closes_at` timebox expiry → `onExpire` action; (3) veto → immediate. Evaluation is event-driven (every ballot re-evaluates); the timebox is the only timer (Temporal `pollTimebox` workflow + lazy re-eval on read).
- **Idempotent close**: state flip and downstream trigger live in one transaction guarded by `poll_outbox` exactly-once claim; double-close cannot double-publish.
- **Native Telegram polls**: `/sentiment <question> ; <opt1> ; <opt2>…` sends `sendPoll` (anonymous, `open_period` ≤600 s), aggregate mirrored into the overlay card, **never linked to a draft**. Capability-gated: `poll.sentiment`.

### 1b. Poll-pass → automatic posting bot

Two wiring modes per destination policy:

1. **Gate mode (default)**: poll arms = the E2 gate on a draft. Pass → approve transition (system actor, §4) → E3 per destination → connector publish (`sendMessage`/`sendPhoto`/`sendMediaGroup`, `message_thread_id` when topic-bound) → `message_id` stored for edit/withdraw. Fail/veto → `reject` with poll reference.
2. **Echo mode (small chats)**: poll subject is a chat post with no scheduled fan-out; pass posts the *same content* back into the originating chat/topic via the announce binding. Internally still materializes a draft + one destination (auditability, D5) — the "direct post" is a fan-out of size 1.

Poll-pass can also **trigger compose**: `/post` with attachments creates the draft in `editing`; on pass with `triggerCompose: true` the UI opens the composer pre-loaded with the approved draft for crosspost (WP15 path: fetch media → asset → draft quoting original → normal policies).

### 1c. Forum topics as subchats

- **`topic_bindings`** registry: `(workspace, connection, chat_id, message_thread_id)` → role `announce | control | audit`, plus assigned accounts and linked virtual channel. A topic binding behaves as a **subchat**: it has its own live-chat channel key (its own seq/fanout topic), its own posting policy (highest precedence), its own member roster.
- **Bot operations**: create (`createForumTopic`, needs `can_manage_topics`), rename (`editForumTopic`), close/reopen (`closeForumTopic`/`reopenForumTopic`), plus `unpinAllForumTopicMessages` on archive. **`deleteForumTopic` is never exposed from chat** (deletes all messages; console-only with confirmation). Enabling forum mode on a supergroup: runbook step for a human admin (Bot API cannot; see research §2). Topic listing/backfill would need MTProto — **deferred**; our registry is authoritative for what we created.
- **Accounts assigned to topics**: `topic_bindings.account_ids[]` — a destination account may be bound to zero+ topics; posts to that account ride `message_thread_id` of the binding. Unbound announce channels post to the channel root.
- Auto-topic-per-series: on first approval pass for a show/series, broadcaster auto-creates a color-coded topic (icon colors from the fixed Telegram palette) and binds it; archive closes it. An **audit topic** is auto-created per workspace and kept append-only (every governance decision mirrored there).

### 1d. Multiple accounts per platform, each with posting rules

- Any number of connections per platform (each Telegram connection = one bot token; Mastodon = one handle; …). Policies anchor to **(platform, accountId)** — the account is the policy anchor, platform is an attribute.
- **Modes**: `immediate` (no gate, still audited) · `quorum` (arms as §1a; `admins`/`participants`/mixed) · `admin_only` (single-admin gate: `quorum:[{kind:admins,x:1}]`, no participant arm, poll optional).
- Cross-cutting knobs per policy: `timebox.onExpire`, `allowSelfApproval:false`, `resetOnChange:true`, `dryRun`, `fallback:block`.
- **Precedence**: `topic > contentType > account > workspace default`, most-specific-wins, **whole-block replacement** (no field merges). Compiled at save-time into a resolved snapshot + `policy_version` hash persisted on the binding; evaluation reads only snapshots. Every rule supports `dryRun` (shadow) for onboarding a new policy.
- Fan-out law (D8): one draft → N destinations → N independent decision records; "fully sent" = all destinations fired.

### 1e. Telegram bot broadcast control

Command grammar (control binding / locked `#control` topic only):

| Command | Maps to | Permission | Confirm? |
|---|---|---|---|
| `/tally` | read director state | `director.view` | no |
| `/pst <sceneId>` | `{type:"pst-select"}` | `director.take` | no |
| `/take [sceneId]` | `{type:"take"}` | `director.take` | no |
| `/cut [sceneId]` | `{type:"cut"}` | `director.take` | **yes** |
| `/lock on` | `{type:"lock",enabled:true}` | `director.lock_program` | no (protective) |
| `/lock off` / `/unlock` | `{type:"lock",enabled:false}` | `director.lock_program` | **yes** |
| `/override <mode|off>` | `{type:"override"}` | `director.override_auto` | **yes** |
| `/start` `/stop` | desired RUNNING/STOPPED | `director.take` | stop: **yes** |
| `/topics new\|close\|list` | topic registry ops | `chatgov.manage` | no |
| `/post <text> [+media reply]` | draft + poll | `drafts.create` | no |
| `/poll` (reply) | open vote on a draft/chat post | `chatgov.vote` | no |
| `/sentiment …` | native sendPoll | `chatgov.sentiment` | no |
| `/register` | claim identity → console approval | — | n/a (approval in console) |
| `/help` | — | — | no |

Channel binding: each control binding carries `linked_channel_id` (the virtual channel commands act on); `/tally` replies with program/preview/lock/override snapshot. Locked channel ⇒ `/take`/`/cut` refused with the interlock reason (state machine enforced server-side in `media-control`, chat only displays).

**Confirmation UX (destructive)**: (1) dry-run diff echo ("program: SRC-A → SRC-B · ch s27-main"); (2) inline `CONFIRM / ABORT` keyboard, `callback_data = cf:<nonce>` (≤64 B); (3) callback accepted **only** from the requesting `from.id`; (4) 30 s TTL → panel self-erases via `replace_callback_query_message` (10.3) or edits to "expired"; (5) `answerCallbackQuery` ack; (6) execution goes through the same idempotent `director()` call the console uses, with the chat nonce as `Idempotency-Key`; (7) result + actor mirrored to the audit topic.


---

## 2. Data model

All tables: `workspace_id uuid NOT NULL`, RLS `ENABLE`+`FORCE` with the standard tenant policy (migration lint enforces), all access via `withTenant`, each added to the guards-bypassed RLS denial suite (WP2 convention).

```sql
-- 001_chatgov.sql (sketch)
CREATE TABLE polls (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id      uuid NOT NULL,
  channel_id        uuid,                    -- live-chat channel (nullable: console-only poll)
  topic_binding_id  uuid,                    -- vote scoped to a subchat when set
  subject_kind      text NOT NULL CHECK (subject_kind IN ('draft','chat_post','none')),
  draft_id          uuid,                    -- FK drafts(id) when subject_kind='draft'
  question          text NOT NULL,           -- 1..300
  parent_poll_id    uuid,                    -- revote lineage
  rule              jsonb NOT NULL,          -- compiled §1a object (snapshot at open)
  policy_version    text NOT NULL,           -- hash of rule at open
  state             text NOT NULL DEFAULT 'open'
                    CHECK (state IN ('open','passed','failed','vetoed','quorum_unreachable','cancelled')),
  opens_at          timestamptz NOT NULL DEFAULT now(),
  closes_at         timestamptz NOT NULL,    -- opens_at + timebox.duration
  closed_at         timestamptz,
  close_reason      text,                    -- quorum_early | timebox | veto | cancelled
  outbox_state      text NOT NULL DEFAULT 'none'   -- none|claimed|done  (exactly-once close)
                    CHECK (outbox_state IN ('none','claimed','done')),
  created_by        uuid NOT NULL,
  created_at        timestamptz NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX polls_open_one_per_draft ON polls (workspace_id, draft_id)
  WHERE state = 'open' AND draft_id IS NOT NULL;      -- one open gate per draft
CREATE INDEX polls_ws_state ON polls (workspace_id, state, closes_at);

CREATE TABLE poll_votes (
  poll_id           uuid NOT NULL REFERENCES polls(id),
  workspace_id      uuid NOT NULL,
  voter_kind        text NOT NULL CHECK (voter_kind IN ('user','chat_identity','system')),
  voter_user_id     uuid,                    -- resolved workspace user, when known
  voter_remote_id   text NOT NULL,           -- provider:from.id (numeric for TG)
  voter_handle      text NOT NULL,
  ballot            text NOT NULL CHECK (ballot IN ('yes','no','veto','abstain')),
  eligible          boolean NOT NULL DEFAULT true,   -- eligibility AT CAST (informational)
  counted           boolean NOT NULL DEFAULT true,   -- ineligible votes stored, not counted
  ineligible_reason text,                    -- INELIGIBLE_ACTOR | SELF_APPROVAL_DENIED
  cast_at           timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (poll_id, voter_remote_id)     -- idempotent upsert; revote = replace ballot
);
CREATE INDEX poll_votes_poll ON poll_votes (poll_id, counted);

CREATE TABLE posting_rules (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id      uuid NOT NULL,
  scope             text NOT NULL CHECK (scope IN ('workspace','account','content_type','topic')),
  account_id        uuid,                    -- connection id; NULL for workspace
  topic_binding_id  uuid,                    -- when scope='topic'
  content_type      text,                    -- 'alert' | 'video' | ... when scope='content_type'
  policy            jsonb NOT NULL,          -- §1a-shaped rule (minus subject)
  policy_version    text NOT NULL,           -- compiled snapshot hash at save
  dry_run           boolean NOT NULL DEFAULT false,
  created_by        uuid NOT NULL,
  created_at        timestamptz NOT NULL DEFAULT now(),
  superseded_by     uuid,
  UNIQUE (workspace_id, scope, account_id, topic_binding_id, content_type)
);
-- Effective policy resolution is done at SAVE time into:
CREATE TABLE posting_policy_snapshots (
  workspace_id      uuid NOT NULL,
  destination_kind  text NOT NULL,           -- 'account' | 'topic'
  account_id        uuid NOT NULL,
  topic_binding_id  uuid,
  effective         jsonb NOT NULL,
  policy_version    text NOT NULL,
  resolved_from     jsonb NOT NULL,          -- audit: which scopes contributed
  updated_at        timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (workspace_id, account_id, topic_binding_id)
);

CREATE TABLE topic_bindings (
  id                    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id          uuid NOT NULL,
  connection_id         uuid NOT NULL,       -- telegram connection (bot)
  chat_id               text NOT NULL,       -- numeric -100… preferred (usernames drift)
  message_thread_id     text,                -- NULL = channel root / whole group
  binding_type          text NOT NULL CHECK (binding_type IN ('announce','control','audit')),
  name                  text NOT NULL,       -- 1..128 (Telegram topic name limit)
  icon_color            integer,             -- one of the 6 fixed TG colors
  state                text NOT NULL DEFAULT 'active' CHECK (state IN ('active','closed','archived')),
  account_ids           uuid[] NOT NULL DEFAULT '{}',  -- accounts that post here
  linked_channel_id     uuid,                -- control: VC this binding commands
  created_at            timestamptz NOT NULL DEFAULT now(),
  UNIQUE (workspace_id, connection_id, chat_id, message_thread_id)
);
CREATE UNIQUE INDEX topic_bindings_one_control
  ON topic_bindings (workspace_id, linked_channel_id)
  WHERE binding_type = 'control' AND linked_channel_id IS NOT NULL;

CREATE TABLE chat_identities (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id      uuid NOT NULL,
  provider          text NOT NULL,
  remote_user_id    text NOT NULL,           -- immutable numeric TG id — NEVER username
  user_id           uuid,                    -- linked workspace user (after /register approval)
  display_name      text,
  status            text NOT NULL DEFAULT 'pending'   -- pending|approved|rejected|banned
                    CHECK (status IN ('pending','approved','rejected','banned')),
  approved_by       uuid,
  first_seen_at     timestamptz NOT NULL DEFAULT now(),
  UNIQUE (workspace_id, provider, remote_user_id)
);

CREATE TABLE chat_command_audit (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id      uuid NOT NULL,
  update_id         bigint NOT NULL,         -- Telegram update id (dedupe)
  binding_id        uuid,                    -- topic binding command arrived on
  provider          text NOT NULL,
  remote_user_id    text NOT NULL,
  user_id           uuid,                    -- resolved identity, if any
  command           text NOT NULL,           -- '/cut'
  args              jsonb NOT NULL DEFAULT '{}',
  permission        text,                    -- RBAC permission required
  decision          text NOT NULL CHECK (decision IN ('accepted','rejected','unauthorized','unknown_command','rate_limited')),
  reason            text,                    -- machine code: INELIGIBLE_ACTOR | LOCKED_CHANNEL | CONFIRM_EXPIRED | ...
  nonce             text,                    -- confirmation nonce when confirm-gated
  idempotency_key   text,                    -- chat nonce used as director key
  result_ref        jsonb,                   -- receipt fingerprint / poll id / draft id
  received_at       timestamptz NOT NULL DEFAULT now(),
  UNIQUE (workspace_id, provider, update_id)
);
CREATE INDEX chat_command_audit_ws_time ON chat_command_audit (workspace_id, received_at DESC);

-- Governance decision records (one per destination per evaluation, §4)
CREATE TABLE gate_decisions (
  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id      uuid NOT NULL,
  draft_id          uuid NOT NULL,
  destination       jsonb NOT NULL,          -- {platform, accountId, topicBindingId?}
  gate              text NOT NULL CHECK (gate IN ('E1','E2','E3')),
  policy_version    text NOT NULL,
  outcome           text NOT NULL CHECK (outcome IN ('fired','blocked','pending')),
  inputs            jsonb NOT NULL,          -- approvals, poll tally, quorum gaps
  reason_codes      text[] NOT NULL DEFAULT '{}',
  actor             text NOT NULL,           -- 'system:gate-e3' | 'user:<id>' | 'chat_poll:<pollId>'
  created_at        timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX gate_decisions_draft ON gate_decisions (workspace_id, draft_id, gate);

-- Poll mirror bookkeeping (card = edited, never re-sent)
CREATE TABLE poll_mirrors (
  poll_id           uuid NOT NULL,
  workspace_id      uuid NOT NULL,
  binding_id        uuid NOT NULL,
  message_remote_id text NOT NULL,           -- for editMessageText
  last_edit_at      timestamptz NOT NULL DEFAULT now(),
  last_render_hash  text NOT NULL,           -- edit-on-change guard
  PRIMARY KEY (poll_id, binding_id)
);
```

**Migration sketch** — single forward migration `001_chatgov.sql`: create the tables above + RLS enable/force + tenant policies + indexes; register retention classes (`poll_votes`, `chat_command_audit`, `gate_decisions` append-hot, monthly-partition candidates per WP2 convention; `polls`/`posting_rules` stay unpartitioned FK parents). Rollback = drop schema objects (no data migration in v1). Decision-record events additionally append to the existing `audit_append` chain (`poll.*`, `policy.*`, `chatcmd.*` actions) so governance lands in the tamper-evident spine.

---

## 3. Bot architecture

**Library: grammY 1.46** (+ `@grammyjs/transformer-throttler`, `@grammyjs/conversations`, `@grammyjs/menu`, `@grammyjs/runner`). TS-first, tracks Bot API 10.3, throttler ships compliant budgets (30/s global · 1/s per chat · 20/min group) and honors 429 `retry_after`; `bypassThrottler` fast-lanes command acks. Telegraf is stale (2024); node-telegram-bot-api is an immature RC — both rejected per research.

**Topology — module, not a new service.** `apps/api/src/chat-gov/`:

```
chat-gov/
  telegram-gateway.ts   grammY Bot per approved token; webhook in prod
                        (POST /webhooks/chatgov/:bindingId, secret_token per
                        connection), runner+long-poll in dev; 1 poller per token
  command-router.ts     grammar → RBAC check → confirm gate → control-plane call
  poll-mirror.ts        poll card render/edit (edit-on-change, 2–5 s throttle)
  poll-service.ts       open/vote/close/evaluate; emits governance WS frames
  policy-service.ts     rule CRUD + compile to posting_policy_snapshots
  gate-evaluator.ts     E1/E2/E3 evaluation + decision records
  chat-gov.module.ts
```

- **Bridge to live-chat WS**: inbound TG messages in bound chats → `NormalizedChatEvent` → existing `LiveChatHubService.ingest` (same dedupe, seq, ring buffer); a topic binding supplies its own `channel_id` so each subchat sequences and fans out independently on the existing `chat:<ws>:<channel>` Redis topic. Outbound, `poll-mirror` and acks go through `SendGovernors`-wrapped transports — a new `ChatTransport` impl for telegram whose `send`/`edit` consume the same token buckets. Governance frames ride the same fanout as `kind:"chat"`: new `kind:"poll"` (snapshot + delta), `kind:"poll_closed"`, `kind:"tally"` — same subscribe/ack/resume contract, server-side debounce (≥250 ms coalesce) so vote storms don't flood the overlay.
- **Capability plumbing**: extend `LiveChatCapability` in `packages/core/src/chat-contract.ts` with `poll: "none" | "vote" | "sentiment"` and `topics: boolean`; `capability-probe.ts` verifies a callback_query round-trip before advertising `vote` (inline keyboards are always sendable; the *callback* is what must work).
- **Command router pipeline** (order fixed): dedupe on `update_id` → resolve binding (chat_id + thread → topic_bindings) → resolve identity (`chat_identities`, numeric id) → RBAC map (identity.user → membership role → permission via existing permission table; role sources are ours, TG admin flags are display hints only) → per-user per-command-class token bucket → parse/validate args → confirm gate for destructive → call control plane (`media-control.director()`, `publishing`, or chat-gov service) with chat nonce as `Idempotency-Key` → `chat_command_audit` row → reply + audit-topic mirror.
- **Permission mapping**: `/tally`→`director.view`; `/pst|/take|/cut|/start|/stop`→`director.take`; `/lock`→`director.lock_program`; `/override`→`director.override_auto`; `/topics`→`chatgov.manage`; `/post`→`drafts.create`; `/poll`→`chatgov.vote`; `/register`→self-service + console approval (`chatgov.manage` approves). Unregistered identity ⇒ everything except `/help`, `/register`, `/tally` is `unauthorized`. Unlinked control binding ⇒ commands rejected with `NO_CHANNEL_BOUND`.
- **Rate limiting, layered**: grammY throttler (outbound API shape) → `SendGovernors` token buckets (our policy: mirror edits ≤1 per 3 s per binding, priority lanes control > notify > bulk) → per-user per-command-class bucket (e.g. `/cut` ≤3/min) → 429 global backoff with jitter. `poll-mirror` edits only when `render_hash` changes.

---

## 4. Quorum evaluation ↔ publishing pipeline

**Draft states today**: `editing → in_review → approved → rejected → scheduled → published`, with `approved_hash`/`approved_revision` pinned at approve time, and `audit_append` per transition. Chat governance plugs into exactly these seams — no parallel pipeline.

**Gates (Argo sync-wave order):**

| Gate | Where | Signal | Fires |
|---|---|---|---|
| E1 | `review → approved` transition | RBAC approvals on the draft | Editor submits / console approve |
| E2 | **Chat poll gate** | `polls.state` outcome | ballot cast (event-driven) or timebox (timer) |
| E3 | Immediately before each platform dispatch | compiled snapshot + approvals + poll state | connector publish call |

**Flow for a quorum-gated destination:**

1. Draft created (console or `/post`) with N destinations → each destination's effective snapshot resolved → `gate_decisions` rows created `pending`.
2. Poll opened (auto on submit when an arm requires chat signal, or manually): rule compiled from the destination's most-gating arm; `polls.rule` snapshot + `policy_version` pinned.
3. **Every ballot** upserts `poll_votes` (idempotent on `(poll_id, voter_remote_id)`) and re-evaluates in the same transaction: eligibility re-read, arms computed, `quorum_unreachable` checked eagerly. Card edits flow through mirror throttle.
4. **Close** (quorum ∧ minDwell | timebox `onExpire` | veto): claim `outbox_state` (exactly-once), set final state, then in the *same transaction*: pass ⇒ `publishingService` transition `in_review → approved` with **system actor** `system:chat-poll-gate:<pollId>`; veto/fail ⇒ `→ rejected` with reason. The poll id doubles as the idempotency key — replayed closes are no-ops. `approved_hash` pinning stays intact: a post-close draft edit re-validates at E3 and is blocked (`RESET_ON_CHANGE` / hash mismatch).
5. **E3 pre-dispatch** (Temporal `scheduledPublish` worker, per destination): re-read snapshot + approvals + poll state + `approved_hash`; evaluate; write the `gate_decisions` outcome (`fired`/`blocked` + reason codes); only then connector publish. Partial fan-out is normal: A fires, B blocked ⇒ B's destination shows in the blocked queue with its reason codes and gap-to-quorum.
6. **Audit trail**: `poll.opened/voted/closed` + `policy.evaluated` + `release.fired/blocked` all append via `audit_append` (tamper-evident chain, actor = system identity with poll ref); every decision record embeds `policy_version`. `admin_only` mode = same path with a 1-arm poll or an E1-only console approval. `immediate` mode = E1 minimal + E3 always.

**Reason codes** (machine-readable, attached to the blocked post object, not just logs): `INSUFFICIENT_QUORUM` (got x, need y, per arm) · `INELIGIBLE_ACTOR` · `SELF_APPROVAL_DENIED` · `TIMEBOX_EXPIRED_AUTO_REJECT` / `..._AUTO_APPROVE` · `RESET_ON_CHANGE` · `PENDING_POLL` · `VETOED` · `OUTSIDE_POLICY` · `POLICY_DRY_RUN` · `OVERRIDDEN_BY_OWNER` · `LOCKED_CHANNEL` · `NO_CHANNEL_BOUND` · `CONFIRM_EXPIRED`.

---

## 5. UI spec

**Poll card (one React component, three mount points: web chat pane, OBS/browser overlay, mobile).**
- Header: question + author avatar + status chip (`collecting votes → quorum met → passed → publishing` phase ribbon).
- Body: horizontal **tally bars** per option, width = share, count + % right-aligned; named mode renders **avatar stacks** (max 5 + `+n`) under each bar; anonymous renders a lock glyph and "votes hidden" — never mixed.
- **Quorum strip**: visually distinct segmented meter per arm — `2/3 admins ●●○ · 1/3 participants ●○○` (dots, not bars: a gate, not an option). Greyed card + "quorum unreachable — 1 eligible voter remaining" when eager-check trips.
- **Countdown chip** on the card edge; `closing soon` (<10% left) gets emphasis. Terminal state: bars freeze, winner highlighted, outcome ribbon `PASS ✓ / FAIL ✗ / VETO ⛔`, auto-collapse to one line in history after 60 s (overlay immediately).
- **Interaction**: web/mobile tap a bar (or 👍/👎/veto buttons); Telegram inline keyboard `[👍 2] [👎 1] [⛔ veto]` — the *card*, not chat messages, is the only surface that changes. Revote overwrites; keyboard row re-renders counts on edit.
- **Overlay mount**: 320–400 px corner card, same component, fed by the same WS frames; server-debounced deltas; resolved state collapses to a single line.

**Vote flow (mobile)**: tap → optimistic bar update (client) → WS confirm (authoritative, replaces optimistic) → haptic + checkmark on your bar. Offline/late frames: card always renders from the last authoritative snapshot (`kind:"poll"` snapshot after `kind:"poll_delta"` catch-up on resume).

**Posting-rules editor** (console, per account and per topic):
- Left: destination tree (platform → accounts → topics). Right: rule card with mode selector (`immediate / quorum / admin_only`), arm builder rows (`kind` + `x` + `of`), `join` toggle, veto switch, min-dwell, timebox duration + `onExpire` select, anonymity, self-approval, reset-on-change, **dry-run toggle with a badge**.
- Save action shows the **resolved preview** ("effective for @newsbot: 2-of-admins AND 3 participants, veto on, 2 h → auto-reject") before commit; the compiled `policy_version` hash is displayed. Every save writes `policy.revised` to the audit chain; edits require `chatgov.manage`.
- **Blocked queue view**: drafts blocked at E2/E3 as first-class cards with gap-to-quorum meter (live), reason-code chips, and actions (nudge voters / open re-vote with `parent_poll_id` / owner override-with-reason).

**Topic management screen**:
- Grid of topic bindings per connection: name, icon color chip, type badge (announce/control/audit), state (active/closed/archived), assigned accounts, linked VC, live policy summary chip.
- Actions: create (calls bot `createForumTopic`, persists thread id), rename, close/reopen, bind/unbind accounts, set control link, edit policy (jumps to rules editor scoped to topic), archive (close + unpin). `delete` is deliberately absent (console-only runbook with typed confirmation; destructive to history).
- Header banner when forum mode is off on the target supergroup: runbook steps (toggle Topics, re-promote bot with `can_manage_topics`) — we cannot detect or fix this from the Bot API; create attempts surface the Telegram error verbatim.

---

## 6. Security

- **Token vault**: bot tokens and any MTProto session are opaque **vault credential handles** (existing envelope-encryption vault, same boundary as stream keys — `credential-handles.ts` pattern). Tokens never appear in DTOs, logs, WS frames, argv, or chat. Gateway reads handles at boot and on rotation; every credential read is audited. Rotation runbook: BotFather `/revoke` → re-vault → gateway reload → old token dead.
- **Identity**: authorization keyed on immutable numeric `from.id` → `chat_identities` (status `approved` only) → membership role → RBAC permission. **Usernames are never trusted.** Unregistered senders get `/register`, which creates a `pending` identity an admin approves in console — no self-elevation.
- **Least privilege on-platform**: bot promoted with only `can_post_messages`, `can_edit_messages`, `can_delete_messages`, `can_manage_topics` — never `can_promote_members`.
- **Anti-abuse**: layered rate limiting (§3); `update_id` uniqueness kills replays; webhook `secret_token` per binding rejects forged updates; per-user per-command-class buckets; flood governors already refuse (not queue) over-budget sends so a poll storm can't wedge the API; poll mirror edit-on-change + render-hash guard; one-open-poll-per-draft unique index stops poll spam gating the same draft; `chat_command_audit` makes every attempt (including rejects) inspectable.
- **NEVER runs from chat without confirmation** (and some never from chat at all):
  - *Confirm-gated*: `/cut`, `/unlock`, `/override on`, `/stop` — CONFIRM/ABORT + dry-run diff + 30 s TTL + requester-only callback + nonce idempotency.
  - *Console-only, never from chat*: credential/token management, role grants and identity approvals, topic **delete**, policy `dry_run`→enforce flips, retention, workspace settings, and any multi-destination bulk publish that would exceed the broadcast lane (bulk always goes through the Temporal pipeline, never a chat command).
  - *Structurally impossible from chat*: reading vault contents, cross-workspace data (RLS + no chat surface for it), editing another user's draft.
- **Privacy**: anonymous polls store no voter linkage (ballot rows only for named mode); scrub() applies to all audited diffs (existing pattern); control chatter is confined to the locked `#control` topic, and the audit topic is append-only (bot has no delete there operationally).
- **Account posture (from scrape-feasibility)**: the multi-account feature targets *our own legitimate accounts* (bots/handles we own). No browser-automation posting, no scraped-account fan-out; any future MTProto admin sidecar (forum-mode enable, topic backfill) stays admin-ops-only, never bulk-posting — that is the documented boundary.

---

## 7. Phased build plan

| Phase | Slice | Deps | Acceptance criteria |
|---|---|---|---|
| **P0 — spine** | Migrations (§2 tables + RLS + indexes + retention classes), `policy-service` rule CRUD + compile-to-snapshot, `gate_decisions` writer, RBAC permissions (`chatgov.*`), audit events | WP2 vault/RBAC, WP3 drafts | Migrations idempotent + lint-clean; RLS denial suite covers every new table (workspace B sees zero A rows); policy compile is pure + snapshot hash deterministic; `policy.revised` lands in audit chain |
| **P1 — E1/E3 gates** | Wire snapshot evaluation into `review→approved` (E1) and the Temporal dispatch worker (E3); blocked queue rows + reason codes; `immediate`/`admin_only` modes live | P0 | `immediate` posts with no gate; `admin_only` blocks until one admin approve; E3 re-check blocks an approval revoked post-approve; partial fan-out observable (A fired, B blocked with codes); no behavior change for existing drafts |
| **P2 — polls core (web)** | `poll-service` + open/vote/close/evaluate; WS `kind:"poll"` frames; web chat poll card + vote flow; mixed arms, veto, timebox, min-dwell, anonymity; E2 pass→approve integration with exactly-once outbox | P0, P1 | 2-of-admins poll passes → draft `approved` once under 5 concurrent closing triggers; veto fails immediately; timebox auto-reject fires once; ineligible/self votes stored-not-counted with codes; `quorum_unreachable` eager; draft edit after close blocks E3 (`RESET_ON_CHANGE`) |
| **P3 — Telegram gateway** | grammY module, webhook + secret per binding, identity registry + `/register` approval, command router with RBAC + per-class buckets, `chat_command_audit`, non-destructive commands (`/tally`, `/pst`, `/take`, `/lock on`, `/topics`) | P0 | Replay of same `update_id` is a no-op; unregistered identity gets `unauthorized` + `/register`; wrong-permission command rejected with code + audited; `/take`/`/pst` produce real DirectorReceipts via existing `director()`; `/lock on` on locked channel consistent with console |
| **P4 — confirm UX + destructive** | CONFIRM/ABORT conversations, nonce idempotency, dry-run diff echo, ephemeral replace (10.3), audit-topic mirror; `/cut`, `/unlock`, `/override`, `/stop` | P3 | `/cut` without confirm never reaches the control plane; confirm panel expires at 30 s; second user's callback on my panel rejected; same nonce can't fire twice; every destructive action mirrored to audit topic with actor + before/after |
| **P5 — poll mirror + topics** | Inline-keyboard poll cards (`callback_data ≤64B`), edit-on-change throttled through governors, `poll_mirrors`; `topic_bindings` CRUD, bot create/close/rename topics, per-topic policy precedence, subchat channel keys in live-chat, accounts↔topics assignment | P2, P3 | Vote via Telegram button updates web card ≤3 s and vice versa (same WS spine); card edits throttled ≥2 s and only on change (governor test); topic create returns persisted `message_thread_id`; topic policy overrides account policy (precedence test); forum-mode-off surfaces runbook banner |
| **P6 — rules editor + topic screen + blocked queue** | Console UI (§5): destination tree, arm builder, resolved preview, dry-run badge; topic management grid; blocked queue with gap-to-quorum + override-with-reason; mobile vote polish | P1, P2, P5 | Editor save shows exact effective preview matching compiled snapshot hash; dry-run badge blocks nothing but logs `POLICY_DRY_RUN`; blocked post card shows live gap + reason chips; override requires free-text reason and is audited |
| **P7 — echo/auto-topic + hardening** | Echo mode (pass→post into same chat/topic as 1-destination fan-out), auto-topic-per-series, `triggerCompose` crosspost hook (WP15), sentiment `sendPoll`, load test (vote storms), secret-scan pass, retention wiring, docs | P5, P6 | Echo post lands in originating topic after pass with `message_id` stored; auto-topic created once per series and closed on archive; 1k votes/min sustained with flat WS queue + no unthrottled mirror edits; secret-scan clean on all gateway paths; docs updated |

**Dependency order**: P0 → P1 → P2 → {P3 → P4} ∥ P5(P2+P3) → P6 → P7. P3 can start immediately after P0 in parallel with P2 (independent seams: inbound commands vs. poll state machine).

**Out of scope v1 (explicit)**: MTProto userbot sidecar (forum-mode enable, topic backfill — runbook doc only), weighted votes, OPA/Rego expression policies, Discord/Discourse poll connectors (schema is provider-neutral; adapters later), paid broadcast (`allow_paid_broadcast`).

---

## 8. Open items (flagged, decided by default)
1. **`of:eligible` rosters** need a membership UI per topic — v1 ships `admins` + `of:observed` + count-only; explicit rosters land with P6 if asked for.
2. **Overlay auth for anonymous viewers** voting in browser: v1 restricts overlay poll cards to *display*; voting happens in Telegram/web-app logged-in surface (avoids a new anon-auth surface).
3. **Multiple bots per workspace**: supported (per-account tokens = blast-radius isolation + independent rate budgets); one poll may still span destinations on different bots — cards mirror per binding.