docs(genesis-writer): replace the rollout runbook with the sequenced cutover plan

[rickyrombo]

What

Rewrites the genesis migration runbook as a sequenced sixteen-step cutover, and reconciles the reference sections with it and with the code.

The runbook

The previous version ordered the work but left the two hardest transitions underspecified.

Plays were going to be split across chains. They're submitted by whichever node serves the audio — never through the relay — so once nodes start migrating, each one writes its plays to whichever chain it happens to be on while the indexer still reads the old one. The fleet migration takes days, so that's days of plays written where nobody is reading. Step 5 routes all plays through two old-network nodes for the duration; step 13 reverts it.

The indexer switch had no procedure. It's now pinned to a height L chosen in the future, with the flusher filtered below it:

• L in the future so the stop doesn't race the config rollout. Choosing one at or below the current tip means the indexer sails past it, and those blocks get indexed from the old chain and flushed to the new one.
• A filter, not a halt — enqueue is fire-and-forget, so confirmed_block is only roughly ordered by id; stopping at the first row above L would strand one below it.
• "Finished flushing" means pending rows at or below L reach zero and stay zero across a settle window, since a straggler can appear after the queue first reads empty.

That yields an exact boundary: the old indexer covers everything at or below L, the new one everything above H, and the ceiling guarantees nothing above L reached the new chain below H. No pause, and no dependence on the two switches happening at the same instant.

Step 13 also records that reverting the play routing loses a small number of plays on either side of L and duplicates none — plays have no unique key, so there is no dedupe path — and that after is the better default because the window is then bounded by the drain.

Reference reconciliation

Six places contradicted the runbook or the code:

• Validator count. The facts table gave prod as 9 validators. That's the genesis list; the live set is 67 of 72 registered nodes. The runbook's quorum and jailing math is over the live set.
• BlockInterval. Section 7 said to leave it at the default, which the runbook now overrides with 20,000. Adds why the default is wrong here (no snapshot exists until height 100,000), that it's producer-side so it needs no fleet agreement, and that retention is Keep × BlockInterval so it can't be lowered freely.
• State-sync truncation. The table listed blobs but not uploads, audio_previews, or qm_audio_analyses, which are also wiped. Adds them with how each recovers, and notes fix(core): scope the state-sync truncate to the tables the snapshot restores #551 makes the row moot.
• Bootstrap validator power. Section 3 asserted it holds power 100. Its own registration rewrites that to ValidatorVotingPower — 10 on mainnet — because the writer never seeds core_registered_nodes.
• The flusher cursor now points at fix(api): retain flushed new-chain queue rows instead of deleting them AudiusProject/api#1018, which is open and must land before flushing is first enabled.
• Section 11 omitted the chain-aware fallback to core_indexed_blocks. It's only reached on ErrNoRows, so it never runs on a database that has indexed the old chain — which is why the failure is a silent stall rather than an error.

Earlier corrections in this branch

• The height check was inverted. It said to confirm block 5,819; both verification artifacts end at 5,839, so an operator following it against a healthy chain would diagnose the dead-chain failure mode. Now points at the height the writer reports, since every run against fresh data ends somewhere different.
• Seal the artifact before pointing anything at it. A node whose binary doesn't embed this artifact's genesis generates a new one and runs the core migrations down. This destroyed the 2026-08-25 artifact. ALLOW_CONNECTIONS false plus a TEMPLATE copy makes the pristine write unreachable by any connection string.
• The writer's prerequisites were absent — --core-dsn, launchpad secrets, mints file, and a destination empty in both Postgres and its CometBFT directory.
• Parity doesn't come back clean, and three of the five expected divergences are cases where the migration is more correct than the source.

Scope

Documentation only. No code changes. Code prerequisites for steps 11 and 12 are deliberately out of the runbook and will be handled before it's run.