chore: doc

Author: didinele

docs/prod-branch.md

@@ -1,7 +1,9 @@
 # The `prod` branch — public AMA deployment
 
-**Status:** temporary. Exists only for the window between the M4 AMA cutover and the moment one
-remaining client finishes the AMA they are currently running on the canary bot.
+**Status:** temporary, with a target end date. Exists only for the window between the M4 AMA cutover
+and **2026-08-13**, when the one remaining client finishes the AMA they are running on the canary
+bot. On that date this deployment folds _into_ the canary one (see [Convergence](#convergence)) —
+that direction is decided, not open.
 
 ## Why there are two deployments
 
@@ -90,14 +92,75 @@ out of `canary.automoderator.app`.
 
 ## Convergence
 
-When the client finishes their AMA:
+**Direction: this deployment folds into the canary one on 2026-08-13.** The canary deployment
+(`chatsift-v3`, `/home/deploys/repos/canary`, branch `main`) survives and takes over the public AMA
+token; `chatsift-prod` is deleted.
 
-1. Migrate their now-historical AMA rows from the canary database to this one. Historical rows are
-   far safer to move than in-flight ones — that timing is the entire point of this arrangement.
-2. Shut down the canary deployment's `ama-bot` and retire `canary.automoderator.app` /
-   `api-canary.automoderator.app`, or keep them as a genuine canary.
-3. Decide whether ModMail and the monitoring stack move into this deployment, or this deployment's
-   AMA folds back into the canary one. Whichever database you keep sets the migration direction.
-   That decision does not have to be made now.
+That direction is chosen because it moves the least, and moves the safest things:
 
-Once converged, delete this branch rather than merging it.
+- **The client's rows never move at all.** They are already in the surviving database. The
+  alternative direction would mean migrating them a second time.
+- The surviving deployment keeps the awkward, stateful pieces in place — the #216 partner ModMail
+  instances and their per-partner tokens, Prometheus history, Grafana dashboards, Dozzle's bcrypt
+  users volume. Re-homing those is strictly more work than moving a few days of AMA rows.
+- Only public-AMA data created between the cutover and 2026-08-13 has to move, and AMA sessions are
+  short-lived events, so that is a small set. This deployment runs no `modmail-bot`, so every ModMail
+  table in its database is empty — nothing to reconcile there.
+
+### The one real cost: identity-column collisions
+
+Every AMA table keys on `INTEGER GENERATED BY DEFAULT AS IDENTITY`, so both databases have rows
+numbered from 1 and the merge needs an id remap across the whole FK graph:
+
+```
+ama_sessions (id)
+├── ama_prompt_data      .ama_id      → sessions.id   (UNIQUE; own identity id)
+├── ama_question_tags    .ama_id      → sessions.id   (own identity id; UNIQUE (id, ama_id))
+└── ama_questions        .ama_id      → sessions.id   (own identity id; UNIQUE (id, ama_id))
+    ├── ama_question_askers          .question_id → questions.id   (own identity id)
+    └── ama_question_tag_assignments (question_id, ama_id) → ama_questions (id, ama_id)
+                                     (tag_id,      ama_id) → ama_question_tags (id, ama_id)
+```
+
+`GENERATED BY DEFAULT` rather than `ALWAYS` is what makes this tractable: explicit ids can be
+inserted without disabling anything. Pick a per-table offset above the surviving database's current
+`max(id)`, shift every prod id and every referencing FK by that same offset, insert parent-first in
+the order above, then `ALTER TABLE … ALTER COLUMN id RESTART WITH …` on each sequence.
+
+`scripts/import-legacy-ama.mjs` is the precedent to follow: it emits a single `BEGIN`/`COMMIT` around
+a plpgsql `DO` block to stdout for review rather than connecting to a database, and is applied with
+`psql -v ON_ERROR_STOP=1`. Do the same here.
+
+Unique constraints to be aware of while merging:
+
+- `ama_sessions.share_token` and `ama_prompt_data.prompt_message_id` — random tokens and Discord
+  snowflakes respectively, so collisions are not a practical concern.
+- `dashboard_grants (guild_id, user_id)` — the one genuine risk if any guild ended up with both bots.
+  Insert with `ON CONFLICT DO NOTHING`.
+
+### Steps
+
+1. Confirm the client's AMA is `ended`, then stop **both** `ama-bot` containers so nothing writes
+   mid-merge.
+2. Dump this deployment's AMA tables plus `dashboard_grants`, remap ids as above, apply to the canary
+   database inside one transaction.
+3. In the canary checkout, set `AMA_BOT_TOKEN` to the **public** `@AMA#5595` token and merge this
+   branch's `.env.public` changes into `main` — `API_URL_PROD`, `FRONTEND_URL_PROD`, and `CORS`, but
+   **keep `API_PORT=7004`**, since the surviving deployment is already on that port.
+4. In `chatsift/caddy`, repoint `api.automoderator.app` from `:7005` to `:7004` and delete the
+   `api-canary.automoderator.app` block.
+5. `./compose up -d` in the canary checkout; `./compose down -v` in the prod one; delete
+   `/home/deploys/repos/prod`.
+6. Delete this branch. Its `docker-compose.yml` trim is throwaway, but note that step 3 means the
+   `.env.public` half of it **does** belong on `main` — don't discard the branch before that lands.
+
+### After the fold
+
+- **The client's historical AMA messages become uneditable.** They were authored by the canary
+  application, and the surviving API holds only the public token, so `updateQuestion`, `mergeShared`,
+  and `updateAMA`'s prompt edit will get a 403 on those specific old rows. The session is over, so
+  this is cosmetic — but it is permanent, and worth saying out loud rather than discovering later.
+- **The client needs `@AMA#5595` invited** to their guild for any future AMA; the canary application
+  will no longer be running anywhere.
+- Their dashboard session survives the move to `automoderator.app` without a re-login, because the
+  cookie is scoped to the bare `ROOT_DOMAIN` and both deployments share an `ENCRYPTION_KEY`.