ref(conversations)!: Make events the canonical transcript

.agents/skills/junior-qa/SKILL.md

@@ -123,18 +123,19 @@ pnpm --filter @sentry/junior exec vitest run tests/integration/mcp-oauth-callbac
 For SQL conversation storage changes, verify the resumed turn rebuilds context
 from SQL, not `thread-state` mirrors: conversation context must hydrate from
 `junior_conversation_messages` (`hydrateConversationMessages`) and pi history
-from `junior_agent_steps` (`loadProjection`). In those tests, transcripts
-seeded only into `thread-state` must also be persisted to SQL
-(`persistConversationMessages`) before the callback runs, and the resumed
-agent-run input `conversationContext` must contain the SQL-seeded messages.
+from `junior_conversation_events` through the Pi adapter (`loadProjection`). In
+those tests, transcripts seeded only into `thread-state` must also be persisted
+to SQL (`persistConversationMessages`) before the callback runs, and the
+resumed agent-run input `conversationContext` must contain the SQL-seeded
+messages.
 
 ## Failure Handling
 
 If local chat fails because credentials are missing or expired, refresh the
 environment when appropriate with `pnpm dev:env`, then rerun the same command.
 If local chat fails with a `junior_conversation_messages` or
-`junior_agent_steps` query error, the local Postgres schema predates the SQL
-conversation storage cutover; run `pnpm cli -- upgrade`, then rerun.
+`junior_conversation_events` query error, the local Postgres schema predates the
+SQL conversation storage cutover; run `pnpm cli -- upgrade`, then rerun.
 If Redis errors appear during ordinary local QA, check whether
 `JUNIOR_STATE_ADAPTER=redis` was set; local chat normally defaults to memory
 state.

packages/docs/src/content/docs/cli/upgrade.md

@@ -29,27 +29,32 @@ The command takes no extra arguments.
 
 - Move legacy `junior:conversation-work:*` Redis state into the newer conversation record and index state used by the durable worker and dashboard feed.
 - Backfill retained conversation records into the shared Junior SQL database. The upgrade requires `DATABASE_URL`.
-- Repair legacy token and estimated-cost rollups from durable SQL agent steps in bounded batches. Conversations that are active during the repair are left unchanged and can be repaired by rerunning the command after they become idle.
+- Apply the SQL schema cutover and rewrite legacy Pi-message rows into canonical conversation events.
+- Repair legacy token and estimated-cost rollups from durable SQL conversation events in bounded batches. Conversations that are active during the repair are left unchanged and can be repaired by rerunning the command after they become idle.
 
-The migrations are idempotent: rerunning them skips records that were already moved, removes stale legacy index entries that no longer have a record, and upserts SQL conversation rows. The SQL conversation backfill copies a bounded legacy slice of Redis conversation metadata; after cutover, durable conversation metadata is written to SQL while Redis remains the transcript and execution/cache store.
+The migrations are idempotent: rerunning them skips records that were already moved, removes stale legacy index entries that no longer have a record, and upserts SQL conversation rows. The conversation-history import paginates through every conversation in the retained activity index; orphaned or expired Redis keys outside that index are not treated as retained history. After cutover, SQL owns durable conversation metadata and event history.
 
-## Vercel deploys
+## Hard-cutover upgrade sequence
 
-Run `junior upgrade` from the Vercel build command when the deployment has access to the same `REDIS_URL`, `JUNIOR_STATE_KEY_PREFIX`, and `DATABASE_URL` used by production.
+The canonical conversation-event cutover is not rolling-compatible. Do not run it inside a Vercel build while the previous deployment can still accept work. Use this operator sequence:
 
-Use a build command like:
+1. Block new ingress and enqueueing while leaving the previous release's workers and continuation consumers running.
+2. Let existing work drain, then verify that no turns remain running or awaiting resume.
+3. Stop every old worker, queue consumer, and heartbeat. Keep the old deployment stopped for the rest of the procedure.
+4. Run the upgrade from an operator environment with the production `REDIS_URL`, `JUNIOR_STATE_KEY_PREFIX`, and `DATABASE_URL`.
+5. Confirm the history import and visible-message seal complete with no missing rows.
+6. Run `junior check`, deploy the new release, and only then reopen ingress and start the new workers.
 
-```bash
-pnpm exec junior upgrade && pnpm build
-```
-
-For monorepos, keep the same prefix and replace the build command with the app-specific build:
+Run the upgrade as a separate operator command:
 
 ```bash
-pnpm exec junior upgrade && pnpm --filter <app> build
+pnpm exec junior upgrade
+pnpm exec junior check
 ```
 
-This keeps schema creation and SQL backfills out of request handlers. Runtime code trusts that the deployment ran `junior upgrade`; if schema is missing, the deployment is misconfigured and should fail clearly.
+The visible-message seal fails closed if resumable work remains. After the drain succeeds, the upgrade invalidates stale resume state before it resequences conversation history while preserving reporting summaries.
+
+If the command exits nonzero, leave the deployment stopped, correct the reported state, and rerun it. Do not restart workers after only part of the sequence completes.
 
 ## Example output
 
@@ -81,8 +86,9 @@ Treat that as a deploy blocker for the affected environment. Check `REDIS_URL`,
 After running the command:
 
 1. Confirm the final log line includes `Junior upgrade complete`.
-2. Confirm the migration summary has the expected `scanned` and `migrated` counts.
-3. Run `pnpm exec junior check` before building or deploying the app.
+2. Confirm `backfill-conversation-events-sql` scanned the complete retained activity index and did not stop at one page.
+3. Confirm `backfill-conversation-visible-message-events` reports `missing=0`; this is the canonical-history seal.
+4. Run `pnpm exec junior check` before building or deploying the app.
 
 A nonzero `missing` count for `repair-conversation-usage` means retained SQL assistant messages did not contain usable, schema-safe usage values. Junior leaves those totals unchanged.