[anth-volk]

Fixes #4312

Summary

Records each user's report runs in /v2/reports, reads a report by run and as each user sees it, and takes names only from saved reports. Stacked on #4303 (its user_report_run_associations table and per-user column changes); retargets to master once #4303 merges.

Who asks. POST /v2/reports, POST /v2/reports/{report_id}/runs, GET /v2/reports/{report_id} and GET /v2/reports take an optional user credential: a bearer access token, the PolicyEngine-Unauthenticated-User header, or a server forwarding either (NativeRouteDependencies.optional_user). Without one the request acts as nobody; a credential that is sent but not valid is refused as on the user routes (401; 403 for a forwarded machine-client token). The OpenAPI document marks the credential optional.

Records (new services/v2/report_run_records):

• A create or re-run with a credential checks the requester before the simulation service is asked (a browser credential naming a signed-in user answers 401), then, once the service has answered, records in one transaction a user_report_run_associations row for the run the answer names, created or joined: trigger initial or manual, requested_at when the Public API received the request, ON CONFLICT (user_id, report_run_id) DO NOTHING, so a user asking again for a run keeps their first record. A budget window's request records each year's report run of its window run.
• The record names the user the check found, read FOR SHARE without inserting: a browser merged into an account while the simulation service was asked is answered 503 rather than recorded under a re-created user, and one converted in place is recorded as itself.
• A record that can't be written answers 503 with report_id and run_id.
• The user's saved reports of the report advance last_run_at to the request's time (never backwards). Saving or repointing a saved detailed-save report through /v2/user-reports sets last_run_at from the owner's records, whatever the caller sends; a saved report naming only a v1 report output keeps the caller's value.
• Signing in to an existing account copies the browser's run records to it before the browser's user is deleted (a run the account already has keeps the account's record), and resets the involved saved reports' last_run_at from the account's records. The runtime role's existing SELECT, INSERT and DELETE grants on user_report_run_associations cover it; no UPDATE.

Which run is answered.

• Creates and re-runs read the report back with the run the simulation service's answer names (StartedReportRun for re-runs), which needn't be the newest once sim shares runs; their 502 when it can't be read back names run_id.
• GET /v2/reports/{report_id}?run_id= reads that run (a report run, or a budget window's budget-window run); any other run answers 404.
• Without run_id, a read or list answers the requesting user's newest recorded run, else the newest succeeded run that wasn't forced, else the newest run that wasn't forced (a window's: not recalculated). A forced run is never the default.

Names. A report's label and description are the requesting user's saved report's (the one saved last), null otherwise; reports.label and description are no longer read. POST /v2/reports takes label and description as optional and sends neither to the simulation service.

Forced re-runs are for admin users only: 401 without a credential, 403 below admin, before the simulation service is asked.

The decisions it follows

C1 · 24's answers, recorded in the shared-reports design:

• 2 and 3: a failed run never counts, and a forced re-run is an extra run nobody joins, so the record names whatever run the simulation service answers.
• 6: the per-user columns leave shared rows; names come from saved reports, the trigger from the user's record, and the create's label and description are stored nowhere.
• 7: a user sees the run of their own newest request; a newer run someone else started is offered from GET /v2/reports/{report_id}/runs, never in its place; a repeated request keeps the first requested_at.
• 8: a budget window's request records each year's report run.
• 10: no user_simulation_run_associations; nothing here writes one.
• Who may send force: admin users only.

Deploying, with the simulation service's find-or-create (C1 · 27)

• Order: Share detailed-save reports and runs by key, and record each user's report runs #4303 first (applied in staging and production), then the simulation service's find-or-create by key (PolicyEngine/policyengine-sim-api, C1 · 27), then this. Sim's main still requires label, which this no longer sends, so this must not deploy before C1 · 27.
• What it reads from sim: the create and re-run answers' report_run_id (and a window's budget_window_run_id) as the run the request ended on, joined or created, always 201; the 409 run_in_progress no longer occurs. Built against those shapes with stand-ins for the simulation service, since C1 · 27 isn't merged yet.
• Columns still read, and dropped later: each run's trigger (now nullable in Share detailed-save reports and runs by key, and record each user's report runs #4303) and report_runs' cliff columns. A later task drops them with the per-user columns of reports, after this deploys.

Testing

• Every test this PR adds or changes, run by node ID: 203 pass, the PostgreSQL ones as the runtime role on a disposable PostgreSQL 17 database built at this branch's head, with every role's privileges applied and verified, and alembic -c alembic-v2.ini check clean (no revision here).
• v2-integration-check.yml's report step runs the six new integration modules after the managed roles get their privileges.
• lint-imports, python -m scripts.rules validate, python scripts/run_quality_guards.py, ruff, ruff format and mypy pass. Nothing under policyengine_api/data/v2/ changes.
• Six read-only review rounds; the last two found no bugs. Each round's bugs were fixed test-first (failing test committed first).
• No deployment code changes. The workflow step reads only V2_MIGRATION_DATABASE_URL, V2_ALEMBIC_DISPOSABLE_TEST and DEPLOYMENT_ENVIRONMENT, literal values in the job's own env: for its own PostgreSQL service container.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 91.60494% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.41%. Comparing base (63cce82) to head (77c940a).

Files with missing lines	Patch %	Lines
policyengine_api/fastapi_routes/dependencies.py	53.33%	5 Missing and 2 partials ⚠️
...licyengine_api/fastapi_routes/v2/reports/routes.py	87.50%	4 Missing and 1 partial ⚠️
policyengine_api/libs/simulation_report_reruns.py	0.00%	5 Missing ⚠️
...yengine_api/services/v2/stored_reports/services.py	94.62%	2 Missing and 3 partials ⚠️
...engine_api/services/v2/report_run_records/types.py	90.62%	2 Missing and 1 partial ⚠️
...ored_reports/database_connectors/reads_requests.py	86.36%	0 Missing and 3 partials ⚠️
policyengine_api/libs/simulation_reports.py	0.00%	2 Missing ⚠️
...v2/report_run_records/database_connectors/reads.py	91.66%	0 Missing and 2 partials ⚠️
.../report_run_records/database_connectors/creates.py	90.90%	0 Missing and 1 partial ⚠️
...ine_api/services/v2/report_run_records/services.py	97.22%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                         Coverage Diff                         @@
##           v2plan/c1-25-shared-report-keys    #4313      +/-   ##
===================================================================
- Coverage                            93.45%   93.41%   -0.04%     
===================================================================
  Files                                  369      377       +8     
  Lines                                21478    21823     +345     
  Branches                              3401     3455      +54     
===================================================================
+ Hits                                 20072    20387     +315     
- Misses                                 823      842      +19     
- Partials                               583      594      +11     

Flag	Coverage Δ
integration	57.32% <91.60%> (+0.65%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.