[anth-volk]

Fixes #4008

Summary

• The v2 table user_policies is renamed to user_policy_associations, matching user_household_associations, user_simulation_associations and user_report_associations. Its primary key, unique constraint, three check constraints, two foreign keys and two convention-named indexes take the new name; the foreign keys from legacy_user_policy_mappings and user_report_associations follow the table.
• Deliberate choice: the three composite listing indexes keep their names ix_user_policies_country_user_created_id, ix_user_policies_country_policy and ix_user_policies_country_legacy_policy. The sibling association tables keep short names for the same indexes (ix_user_households_*, ix_user_simulations_*, ix_user_reports_*), so the short names are the existing convention.
• Saved policies, their v1 mappings, the reports that name them and table grants are kept: the table is renamed in place, not recreated.
• The model, the table privilege declarations (privileges.py) and V2_ALEMBIC_HEAD_REVISION use the new name. The Stage 10 saved-policy dual-write copy goes through the model and follows it.
• Migration qualification commands. Both run before every schema upgrade, so they read the saved-policy table under whichever name the database has. The policy qualification counts only while its revision is pending, when the table is still user_policies, so it names that table. The user-association qualification counts on every run, so it counts user_policy_associations when that table exists and user_policies otherwise. Their JSON evidence keeps the key user_policies.
• Unchanged: the route /v2/user-policies, the user_policy_id columns, legacy_user_policy_mappings, and the v1 Cloud SQL table user_policies.

Migration notes

• Route groups covered: none change. The policy user-association routes keep their contracts; only the table behind them is renamed. The generated migration contracts do not change.
• What stays on the Flask/v1 path: everything; v1's Cloud SQL user_policies table is untouched.
• Newly prepared: one Alembic v2 revision, fa7fa1035444 (parent fbb7488ebe8a).
• User-visible API contract changes: none.

The migration correction, and why it is within the migration rules

The revision was generated with uv run alembic -c alembic-v2.ini revision --autogenerate. Autogeneration cannot detect a rename: it created an empty user_policy_associations table and dropped user_policies, which would delete every saved policy, and its copies of the three composite indexes would have collided with the old table's indexes of the same names. The repository's Alembic rules allow a minimal, documented, tested post-generation correction of an objectively incorrect autogenerated operation. The revision has one such correction in each direction:

• op.rename_table replaces the create-and-drop pair.
• Each constraint the generated table named after user_policy_associations is dropped under its old name and created under the generated name with the generated definition, using Alembic operations only (no op.execute, no data operations).
• The generated drops and re-creations of the two convention-named indexes and of the three foreign keys that refer to the table are kept, ordered around the rename. The downgrade is the exact reverse.

The correction is documented in the revision and in docs/engineering/skills/alembic-migrations.md ("API v2 saved-policy table rename"). The v2 Postgres lifecycle test stores a saved policy with a v1 mapping and a report that names it, then checks that the rows, references, delete cascades, a table grant (each privilege separately) and every constraint and index name are right after the upgrade and after the downgrade. Rebuilding the primary key, unique and check constraints takes a brief lock on the table during the upgrade.

Left out: the temporary user_policies view

The plan for this rename includes a view named user_policies over the renamed table, so that the release still serving during a deploy keeps working. It is not in this PR. Alembic does not autogenerate views, and creating one would be a hand-written schema operation, which the migration rules leave to a human decision. test_previous_release_still_finds_user_policies records the gap as a strict expected failure: it stores a saved policy, upgrades to head and reads it under the old name. It starts failing, as a reminder to remove the marker, once a view exists.

Without the view, a Public API release from before this revision fails every statement it makes on saved policies, because it names user_policies:

• During a deploy: from the schema upgrade in the database job until the new release takes traffic (in production, the time deploy-cloud-run-candidate takes; in staging, until the staging deploy).
• After an application rollback to an earlier release: until a release from this revision or later serves traffic again, or until this revision is downgraded. Downgrading it alone renames the table back and keeps every row.
• What fails: the previous release's /v2/user-policies routes, user-report reads that join saved policies, the sign-in merge that moves an unauthenticated user's saved policies, and Stage 10 saved-policy dual-write copies (DB_WRITE_POLICY is cloud_sql today, so these are off).

If a view is added later, the runtime role also needs grants on it. That means a privileges.py entry, and a change to the privilege reconciliation, whose table query reads only ordinary and partitioned tables (relkind IN ('r', 'p')), so it would treat a declared view as missing and grant nothing.

The Stage 12A document (docs/migration/stage-12a-user-login.md) now says this in its rollback and schema compatibility sections, and uses the new table name for current behavior.

Environment variables

None. The change reads and adds no environment variables, and touches no workflow, image or infrastructure.

What this PR waits for

• Let saved reforms and households point at a new v2 policy or household #4005, its base (the bottom of this stack of Public API PRs).
• A person's decision on the temporary user_policies view described above: merge without it and accept the gap during the deploy, or add the view (with its grants) first.
• Alembic v2 chain coordination: if another PR with a v2 revision merges first, this revision is rebased onto the new head (one revision merges at a time).

Testing

Each commit was written test-first:

• 0fda92e3f (qualification commands): test_saved_policies_are_counted_under_their_name_after_the_rename failed first (assert 0 == 3: the renamed table was never counted). Then both qualification unit files passed (16) and the qualification integration test passed against disposable PostgreSQL. The two tests for the pending case pin the old name; they passed before and after.
• b91cebc80 (the rename): on a fresh disposable PostgreSQL 17 database, 11 unit tests failed first (KeyError on user_policy_associations, the missing revision, the privilege manifest, the recorded saved-policy SQL) and 4 lifecycle tests failed (NoSuchTableError public.user_policy_associations, user_policies still present). Then:
  • focused v2 unit tests passed (144) and the v2 lifecycle passed (7 passed, 1 expected failure, twice in a row);
  • alembic -c alembic-v2.ini check reported no new operations;
  • reconcile_v2_privileges.py apply --create-missing-roles and verify passed, then the identity, comparison-run, privilege and saved-policy mirroring integration tests (27 passed);
  • the MySQL v1 lifecycle (4) and the v1 policy and saved-policy dual-write integration tests (12) passed;
  • the make test set without coverage passed (3,398).
• dcf53c748 (review follow-up, tests):
  • With a placeholder later revision added locally, the old revision test read the wrong file and failed; the new one passed.
  • has_table_privilege(role, table, 'SELECT, UPDATE') returned true for a role holding only SELECT, so each privilege is now checked on its own.
  • The old view test also passed on an empty database; the new one fails there.
  • Local, uncommitted checks that the new tests detect what they should: with a view added to the revision, the view test failed as a strict expected failure that passed; with ON DELETE SET NULL removed from the downgrade's report foreign key, the new downgrade cascade check failed.
• 459b03111 (review follow-up, document only): the Stage 12A document.
• On every commit: ruff format --check ., ruff check ., uv run --frozen --extra dev mypy, python scripts/run_quality_guards.py; python scripts/export_migration_contracts.py left the generated files unchanged.

No inline # noqa suppressions are added. A rules fixture (rules/fixtures/api.v2.runtime-privileges-declared/reads_good.py) changes its docstring to the new table name, so this PR requests a review from core-developers.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.95%. Comparing base (8b9272d) to head (459b031).

Files with missing lines	Patch %	Lines
...ata/v2/user_association_migration_qualification.py	85.71%	1 Missing ⚠️

Additional details and impacted files

@@                          Coverage Diff                          @@
##           v2plan/1f-121-repoint-saved-items    #4010      +/-   ##
=====================================================================
- Coverage                              87.95%   87.95%   -0.01%     
=====================================================================
  Files                                    259      259              
  Lines                                  16169    16174       +5     
  Branches                                2636     2636              
=====================================================================
+ Hits                                   14222    14226       +4     
- Misses                                  1275     1276       +1     
  Partials                                 672      672              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.