fix(comms): grant comms-manager narrow-privilege editorial_posts write access [FFM-919] (#225)

The Comms agent could not run publish_editorial_post end-to-end: its
runtime had only ANALYST_DATABASE_URL (read-only), so the import of
src.database failed (DATABASE_URL is a required pydantic setting) and
the editorial_posts row was never persisted. Stats collection silently
skipped agent-published posts and two posts already needed manual DB
backfill.

Path picked: Option 2 from the issue — least-privilege comms_writer
Postgres role. The role gets SELECT/INSERT/UPDATE on editorial_posts
only, plus USAGE on its identity sequence and a 10s statement_timeout.
The Comms env then sets DATABASE_URL to that role's URL; no code change
to src/database.py is needed.

Added:
- agents/.paperclip.yaml: DATABASE_URL secret (required) on comms-manager.
- docs/comms/comms-writer-role-setup.sql: idempotent role bootstrap.
- docs/comms/manual-inserts-2026-05-03.sql: one-off backfill for the
  May 3 telegram_message_id=234 post (Apr 29 row stubbed for the board
  to fill in from the published archive).
- docs/paperclip-ops-runbook.md: secrets table entry warning that this
  is a narrow-privilege URL, not the app's full-write DATABASE_URL.

Deployment is gated on three manual board steps documented in FFM-919.

Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: ohld

agents/.paperclip.yaml

@@ -74,6 +74,14 @@ agents:
         ANALYST_DATABASE_URL:
           kind: "secret"
           requirement: "optional"
+        # Narrow-privilege writer role for editorial_posts (SELECT/INSERT/UPDATE
+        # on that one table). Required so publish_editorial_post can persist
+        # the row and stats collector picks it up. See
+        # docs/comms/comms-writer-role-setup.sql for the role bootstrap and
+        # FFM-919 for the rationale.
+        DATABASE_URL:
+          kind: "secret"
+          requirement: "required"
         FFMEMES_PROD_TELEGRAM_BOT_TOKEN:
           kind: "secret"
           requirement: "required"

docs/comms/comms-writer-role-setup.sql

@@ -0,0 +1,59 @@
+-- comms_writer Postgres role for the Comms agent.
+--
+-- Why: src/comms/publishing.py:publish_editorial_post() must SELECT, INSERT,
+-- and UPDATE rows on editorial_posts (rotation check + idempotent claim row
+-- + telegram_message_id backfill). Granting it the full app DATABASE_URL is
+-- overkill; this role is the least-privilege handle the Comms env should use.
+--
+-- Run once on prod against the ff database as a superuser. After this, set
+-- the Comms agent's Coolify env var:
+--   DATABASE_URL=postgresql+asyncpg://comms_writer:<password>@<host>:<port>/ff
+-- (use the asyncpg driver — src/database.py builds an async engine).
+--
+-- Tracking: FFM-919.
+
+\set ON_ERROR_STOP on
+
+-- 1. Create the role if it does not exist. Replace the password before run.
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'comms_writer') THEN
+        CREATE ROLE comms_writer WITH LOGIN PASSWORD 'CHANGE_ME_BEFORE_RUNNING';
+    END IF;
+END
+$$;
+
+-- 2. Connect + schema usage.
+GRANT CONNECT ON DATABASE ff TO comms_writer;
+GRANT USAGE ON SCHEMA public TO comms_writer;
+
+-- 3. Table grants — editorial_posts only. SELECT is required for the rotation
+--    check and the draft_hash idempotency lookup; INSERT/UPDATE for the claim
+--    row + telegram_message_id backfill.
+GRANT SELECT, INSERT, UPDATE ON TABLE public.editorial_posts TO comms_writer;
+
+-- 4. Identity column needs sequence usage to allow new id allocation on INSERT.
+--    The sequence is implicitly created by the IDENTITY column; resolve and
+--    grant explicitly so future schema migrations don't drop access.
+DO $$
+DECLARE
+    seq_name text;
+BEGIN
+    SELECT pg_get_serial_sequence('public.editorial_posts', 'id') INTO seq_name;
+    IF seq_name IS NULL THEN
+        RAISE EXCEPTION 'editorial_posts.id has no associated sequence';
+    END IF;
+    EXECUTE format('GRANT USAGE, SELECT ON SEQUENCE %s TO comms_writer', seq_name);
+END
+$$;
+
+-- 5. Defensive: short statement timeout so a runaway query in the Comms env
+--    cannot hold a connection forever. The publishing flow is point-lookup
+--    and small inserts — 10s is plenty.
+ALTER ROLE comms_writer SET statement_timeout = '10s';
+
+-- 6. Sanity: list grants for the role so the operator can eyeball them.
+SELECT grantee, privilege_type, table_name
+FROM information_schema.table_privileges
+WHERE grantee = 'comms_writer'
+ORDER BY table_name, privilege_type;

docs/comms/manual-inserts-2026-05-03.sql

@@ -0,0 +1,53 @@
+-- One-off backfill for editorial_posts rows that were posted to @ffmemes
+-- before the Comms agent had write access (see FFM-919 / FFM-918).
+--
+-- Run once on prod against the ff database as a superuser (or as the app's
+-- writer role — comms_writer cannot upsert here because the rows pre-date
+-- the role's existence and we want this run audited).
+--
+-- After both rows exist, the stats collector will start tracking
+-- views/forwards/reactions on its next run.
+
+\set ON_ERROR_STOP on
+
+BEGIN;
+
+-- May 3, 2026 — telegram_message_id=234 — activation-record post.
+INSERT INTO editorial_posts
+  (channel, telegram_message_id, draft_hash, category, entity_id,
+   topic_slug, text, has_media, validation_version, created_at)
+VALUES (
+  'ffmemes', 234,
+  '6a3e2f8c1b4d5a9e0712345678901234',
+  'C', 'cohort_week:2026-04-27', 'activation-record',
+  E'<b>Интересное:</b> 77% новичков...\n\n↳ @ffmemesbot',
+  true, 1, '2026-05-03 07:12:37'
+)
+ON CONFLICT (draft_hash) DO NOTHING;
+
+-- April 29, 2026 backfill — see FFM-918 for the post text + draft_hash.
+-- Replace the placeholders with the real values from the published archive
+-- (docs/comms/published/2026-04-29-new-user-activation-lift.md) before
+-- running. If the row already exists with a non-NULL telegram_message_id,
+-- the ON CONFLICT clause is a safe no-op.
+
+-- INSERT INTO editorial_posts
+--   (channel, telegram_message_id, draft_hash, category, entity_id,
+--    topic_slug, text, has_media, validation_version, created_at)
+-- VALUES (
+--   'ffmemes', <APR29_MSG_ID>,
+--   '<APR29_DRAFT_HASH>',
+--   '<CATEGORY>', '<ENTITY_ID>', '<TOPIC_SLUG>',
+--   E'<full post text>',
+--   true, 1, '2026-04-29 07:00:00'
+-- )
+-- ON CONFLICT (draft_hash) DO NOTHING;
+
+-- Verify both rows landed.
+SELECT id, channel, telegram_message_id, category, entity_id, topic_slug, created_at
+FROM editorial_posts
+WHERE channel = 'ffmemes'
+  AND created_at >= '2026-04-29'
+ORDER BY created_at;
+
+COMMIT;

docs/paperclip-ops-runbook.md

@@ -308,6 +308,7 @@ These are encrypted in Paperclip DB and injected as env vars during agent runs:
 | Secret | Used by | Purpose |
 |--------|---------|---------|
 | `ANALYST_DATABASE_URL` | Analyst, QA | Read-only prod DB access |
+| `DATABASE_URL` | Comms | Narrow-privilege `comms_writer` URL for `editorial_posts` only (see `docs/comms/comms-writer-role-setup.sql`). Do NOT reuse the app's full-write URL here. |
 | `COOLIFY_ACCESS_TOKEN` | CTO, QA, Release Engineer | Coolify API for container logs |
 | `COOLIFY_BASE_URL` | CTO, QA, Release Engineer | Coolify API URL |
 | `SENTRY_AUTH_TOKEN` | CTO, QA | Sentry CLI authentication (read-only project scope) |