[anth-volk]

Fixes #899

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

Second of four stacked PRs; it builds on #898. Revision 0002 adds the two definition tables of the simulation schema. After it deploys, both exist in staging and production with no rows; nothing writes them until stage 2.

• simulation.simulations: kind (economy or household), country, policy (null for current law), dynamic, and either a household or a region code (state/ca) with an optional dataset name (null means the region's default dataset in each catalog version). No column refers to a catalog version, so the same simulation can run again on a newer one; each run resolves the region and dataset in its own version (next PR). A check requires the population to match the kind.
• simulation.reports: baseline and reform simulations of the report's own country and kind (composite foreign keys on simulation, country and kind), the year (1900 to 2200) and options (a JSON object). An economy report needs a reform; a household report may have only a baseline.
• Foreign keys into the Public API's tables in the same database: (policy_id, country) to policies (id, country_id), (household_id, country) to households (id, country_id) and dynamic_id to dynamics, all ON DELETE RESTRICT, each with an index. Creating them needs REFERENCES on those tables for the migrator role; a test shows the migration fails and applies nothing without it. The runtime role needs no privilege on them.
• v1 IDs: unique legacy_simulation_id and legacy_report_id (plain columns, since the Public API's v1 database is separate). SimulationStore.create_migrated and ReportStore.create_migrated return the existing row when the same v1 ID is migrated again.
• Definitions never change: the runtime role may read and insert them but not update or delete them. NewSimulation and NewReport check every field before a write (a kind given as text becomes its enum), and the database checks the same fields again for any other writer; a test inserts directly to reach each database check.

Environment variables

This PR reads no new environment variable. The migration job from #898 applies revision 0002 with SIMULATION_MIGRATION_DATABASE_URL as described there.

Waits for

• Give the Simulation Entrypoint its own simulation schema, migration chain and database connection #898, and through it the operator step that creates sim's database roles and grants the migrator REFERENCES on policies, households and dynamics (and the catalog tables used by the next PR) in staging and production. Without the grant, the migration job fails and the deploy stops.
• Migrations in the simulation chain merge one at a time.

Testing

Rebased with #898 onto main at 2a9212f on 2026-10-28, without conflicts in this branch. Every commit was checked again after the rebase: persistence tests on PostgreSQL 17 with database tests required (100 passed at the tip), the contract library's tests, the entrypoint suite (797 passed), the rules guard and quality guards, Ruff, uv lock --check and Pyright. One review round found no bugs; its quality findings (the README's roles table, untested database checks, a kind given as text) are fixed here. A later review of the PR above this one found that revision 0002 gave its check constraints doubled names (ck_simulations_ck_simulations_kind), which alembic check does not compare; the last commit fixes the names and adds a test comparing every constraint name in the migrated database with the table definitions. The checks above were run locally; this push's GitHub Actions runs report their own results.

🤖 Generated with Claude Code