[bokelley]

This is the docs part of #1831, option 3 in the issue. It doesn't change any code.

The problem. With store=, the first new pod upgrades the ledger when it starts (migration 0002, plus 0006 when status notifications are on). A default rolling update keeps the earlier release's pods running against the upgraded ledger. I reproduced this with the published wheels (adcp==9.3.1 + adcp-reporting-storage[pg]==0.1.0b4 → adcp==10.0.0b8 + 0.2.0b1) on PostgreSQL. Those pods:

• still read;
• fail put_configuration, because ON CONFLICT names the four-column key and the primary key is now five columns (42P10);
• fail commit_obligation as LedgerConflictError … integrity rule. 0002 rebuilt the period key with offering_id, so the old ON CONFLICT has no matching index (42P10, wrapped). Every generation in a worker turn reports it;
• with notifications, fail status checkpoint writes as well (the key 0006 widened);
• after a restart, can't start Reliable Reporting, and the error's hint points at migrate_legacy_reporting. That's the 8 → 9 caller-ownership migration; it doesn't apply here and would quarantine state.

The new release reads everything the old one wrote, so nothing is corrupted.

The change:

• docs/reporting-ledger-migration.md gets a new "Deploying the upgrade" section with:
  • who is affected;
  • those symptoms, with the exact errors;
  • "ignore that hint";
  • no rollback short of restoring a backup;
  • two safe shapes: a Recreate rollout, or two phases (redeploy the earlier release with reporting off, then roll forward);
  • when to run python -m adcp migrate / ReportingStatusService.migrate().
• MIGRATION_v9_to_v10.md and the storage README get short warnings that link to it. The README link points at blob/next, since the section isn't on main.

Refs #1831. The issue stays open for the code options: a clearer refusal in 0.1.0b5, and/or an expand/contract upgrade.

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR, no findings.

This PR adds a "Deploying the upgrade" section to the reporting-ledger migration guide plus linked warnings in MIGRATION_v9_to_v10.md and the storage README. No code, wire, schema, or public-API surface is touched (3 files: all Markdown, +61/-2).

Checks applied:

• No critical/high findings (row 1 N/A).
• gated_paths: false (row 2 N/A).
• high_risk: false; no deleted/modified high-risk paths (rows 3, 5 N/A).
• No medium findings in data-loss/schema/infra (row 4 N/A).
• No prior decision (row 6 N/A).
• No no-auto-approve team match (row 7 N/A).
• Zero medium findings (row 8 N/A).
• Falls through to row 9 → approve.

Reviewer verified every load-bearing doc claim against source (error strings, migration ownership 0001–0003, status-checkpoint widening at 0006, anchor match, deployment sequence stops old workers first). Accurate and well-sourced.